Composition pipelines

Strategy A: NSCR-driven BG screen

Inputs: NCGR tilebank (8×8 tiles) + NCLR palette + NSCR screen map. Output: 256×192 BG image (32×24 cells).

     ┌──────────┐
NCLR │ palette  │──────┐
     └──────────┘      │
     ┌──────────┐      ▼
NCGR │ tilebank │──┐  ┌────────────────────┐
     └──────────┘  └─►│ compose_nscr_screen│──► 256×192 RGBA
     ┌──────────┐  ┌─►│  for each cell:    │
NSCR │ screen   │──┘  │   tile_idx (10b)   │
     │ (32×24)  │     │   palette_bank(4b) │
     └──────────┘     │   hflip / vflip    │
                      └────────────────────┘

# src/translator/_sprite_decode.py::compose_nscr_screen
for cell_y in range(24):
    for cell_x in range(32):
        word = nscr.cells[cell_y * 32 + cell_x]
        tile = word & 0x3FF
        hflip = (word >> 10) & 1
        vflip = (word >> 11) & 1
        bank  = (word >> 12) & 0xF
        tile_pixels = ncgr.tile(tile)              # 8×8 indices
        if hflip: tile_pixels = flip_x(tile_pixels)
        if vflip: tile_pixels = flip_y(tile_pixels)
        for py in range(8):
            for px in range(8):
                idx = tile_pixels[py][px]
                color = nclr.bank(bank)[idx]
                out[cell_y*8 + py][cell_x*8 + px] = color

Used by 1,099 NSCR-bearing containers. Examples: buyitem.lzs shop chrome, title_pack.ofs castle art, every map-screen overlay.

Strategy B: NCER-driven OBJ sprite

Inputs: NCGR tilebank + NCLR palette + NCER cell definition. Output: one or more sprite cells, each composed of multiple OAM "chips."

     ┌──────────┐
NCLR │ palette  │──────────┐
     └──────────┘          │
     ┌──────────┐          ▼
NCGR │ tilebank │──┐ ┌─────────────────────┐
     └──────────┘  └►│ compose_ncer_cell   │──► per-cell PNG
                    │   for each OBJ:     │
     ┌──────────┐   │     (x,y,w,h,tile,  │
NCER │ cells +  │──►│      palette,flip)  │
     │ OAM list │   │     blit into canvas│
     └──────────┘   └─────────────────────┘

Each cell holds obj_count OAM entries; per OBJ the (shape, size) pair selects pixel dimensions via the standard NDS lookup:

Used by 926 NCER-bearing containers.

Strategy C: tad widget table

Inputs: NCER cell (selected by cell_id) + NCLR + the tad/widget-table record (palette, sub, flags, x, y). Output: composed UI screen at the abs_x/abs_y of each record.

The table can sit in two places:

• A tad RESO entry inside the asset container (e.g. buyitem.lzs's tad entry).
• Inside an overlay's .rodata (e.g. ov070's table at 0x0215A538 for the buyitem screen).

Either way the engine walks the table, calls a sprite-constructor for each entry, and the constructor resolves the asset bytes from the content cache. See sprite pipeline for the runtime side.

50 containers ship with a static recipe: 37 with a rnan-only table, 8 with tad, 5 with nib.

Strategy D: code-driven (no static recipe)

123 NCER-bearing containers ship without any static placement table. The composition logic is hard-coded in the controller/body overlay pair. Examples:

• FUN_02174604: place(slot, x=20, y=0, w=216, h=64, type=2)
• FUN_02174760: place(slot, x=13, y=40, w=230, h=112, type=2)
• FUN_021747A8: place(slot, x=13, y=60, w=230, h=94, type=2)
• FUN_02177FE4: two placements at (8,64) and (8,120), w=240 h=28
• FUN_0217B9D8: place(slot, x=13, y=60, w=230, h=94, type=2)
• FUN_02181D24: looks up (x, y) from a 6-entry table at 0x0218CBE6
• FUN_02174B80: triple-nested loop, 144 sprites in a 3×4×12 grid (buyitem catalog)

Runtime shadow-OAM

The engine never writes OAM RAM (0x07000000 / 0x07000400) directly during scene composition. It builds a shadow OAM in main RAM via STR/STRH at sprite-slot addresses computed from *0x021907BC + i*0x40 + field_offset chains. At VBlank, FUN_02185BF8 (ov137) and FUN_0207001C (arm9) DMA the shadow buffer into hardware OAM.

OAM/VRAM transfer wrappers (all four resolve to FUN_02017D9C = DMA0):

Source

• src/translator/_sprite_decode.py — compose_nscr_screen, compose_ncer_cell, OBJ_SIZE_LUT
• notes/phaseA_ghidra/DISCOVERIES.md — verified placement recipes
• notes/phaseA_ghidra/BUYITEM_RECIPE_CRACKED.md — Strategy C worked example