# Dungeon Rendering System Analysis

This document analyzes the dungeon object and background rendering pipeline, identifying potential issues with palette indexing, graphics buffer access, and memory safety.

## Graphics Pipeline Overview

```
ROM Data (3BPP compressed)
    ↓
DecompressV2() → SnesTo8bppSheet()
    ↓
graphics_buffer_ (8BPP linear, values 0-7)
    ↓
Room::CopyRoomGraphicsToBuffer()
    ↓
current_gfx16_ (room-specific graphics buffer)
    ↓
ObjectDrawer::DrawTileToBitmap() / BackgroundBuffer::DrawTile()
    ↓
Bitmap pixel data (indexed 8BPP)
    ↓
SetPalette() → SDL Surface → Texture
```

## Palette Structure

### ROM Storage (kDungeonMainPalettes = 0xDD734)
- 20 dungeon palette sets
- 90 colors per set (180 bytes)
- Colors packed without transparent entries

### SNES Hardware Layout
The SNES expects 16-color rows with transparent at indices 0, 16, 32...

### Current yaze Implementation
- 90 colors loaded as linear array (indices 0-89)
- 6 groups of 15 colors each
- Palette stride: `* 15`

## Palette Offset Analysis

### Current Implementation
```cpp
// object_drawer.cc:916
uint8_t palette_offset = (tile_info.palette_ & 0x07) * 15;

// background_buffer.cc:64
uint8_t palette_offset = palette_idx * 15;
```

### The Math
For 3BPP graphics (pixel values 0-7):
- Pixel 0 = transparent (skipped)
- Pixels 1-7 → `(pixel - 1) + palette_offset`

With `* 15` stride:
| Palette | Pixel 1 | Pixel 7 | Colors Used |
|---------|---------|---------|-------------|
| 0       | 0       | 6       | 0-6         |
| 1       | 15      | 21      | 15-21       |
| 2       | 30      | 36      | 30-36       |
| 3       | 45      | 51      | 45-51       |
| 4       | 60      | 66      | 60-66       |
| 5       | 75      | 81      | 75-81       |

**Unused colors**: 7-14, 22-29, 37-44, 52-59, 67-74, 82-89 (8 colors per group)

### Verdict
The `* 15` stride is **correct** for the 90-color packed format. The "wasted" colors are an artifact of:
- ROM storing 15 colors per group (4BPP capacity)
- Graphics using only 8 values (3BPP)

## Current Status & Findings (2025-11-26)

### 1. 8BPP Conversion Mismatch (Fixed)
- **Issue:** `LoadAllGraphicsData` converted 3BPP to **8BPP linear** (1 byte/pixel), but `Room::CopyRoomGraphicsToBuffer` was treating it as 3BPP planar and trying to convert it to 4BPP packed. This caused double conversion and data corruption.
- **Fix:** Updated `CopyRoomGraphicsToBuffer` to copy 8BPP data directly (4096 bytes per sheet). Updated draw routines to read 1 byte per pixel.

### 2. Palette Stride (Fixed)
- **Issue:** Previous code used `* 16` stride, which skipped colors in the packed 90-color palette.
- **Fix:** Updated to `* 15` stride and `pixel - 1` indexing.

### 3. Buffer vs. Arena (Investigation)
- **Issue:** We attempted to switch to `gfx::Arena::Get().gfx_sheets()` for safer access, but this resulted in an empty frame (likely due to initialization order or empty Arena).
- **Status:** Reverted to `rom()->graphics_buffer()` but added strict 8BPP offset calculations (4096 bytes/sheet).
- **Artifacts:** We observed "number-like" tiles (5, 7, 8) instead of dungeon walls. This suggests we might be reading from a font sheet or an incorrect offset in the buffer.
- **Next Step:** Debug logging added to `CopyRoomGraphicsToBuffer` to print block IDs and raw bytes. This will confirm if we are reading valid graphics data or garbage.

### 4. LoadAnimatedGraphics sizeof vs size() (Fixed 2025-11-26)
- **Issue:** `room.cc:821,836` used `sizeof(current_gfx16_)` instead of `.size()` for bounds checking.
- **Context:** For `std::array<uint8_t, N>`, sizeof equals N (works), but this pattern is confusing and fragile.
- **Fix:** Updated to use `current_gfx16_.size()` for clarity and maintainability.

### 5. LoadRoomGraphics Entrance Blockset Condition (Not a Bug - 2025-11-26)
- **File:** `src/zelda3/dungeon/room.cc:352`
- **Observation:** Condition `if (i == 6)` applies entrance graphics only to block 6
- **Status:** This is intentional behavior. The misleading "3-6" comment was removed.
- **Note:** Changing to `i >= 3 && i <= 6` caused tiling artifacts - reverted.

### 7. Layout Not Being Loaded (Fixed 2025-11-26) - MAJOR BREAKTHROUGH
- **File:** `src/zelda3/dungeon/room.cc` - `LoadLayoutTilesToBuffer()`
- **Issue:** `layout_.LoadLayout(layout)` was never called, so `layout_.GetObjects()` always returned empty
- **Impact:** Only floor tiles were drawn, no layout tiles appeared
- **Fix:** Added `layout_.set_rom(rom_)` and `layout_.LoadLayout(layout)` call before accessing layout objects
- **Result:** **WALLS NOW RENDER CORRECTLY!** Left/right walls display properly.
- **Remaining:** Some objects still don't look right - needs further investigation

## Breakthrough Status (2025-11-26)

### What's Working Now
- ✅ Floor tiles render correctly
- ✅ Layout tiles load from ROM
- ✅ Left/right walls display correctly
- ✅ Basic room structure visible

### What Still Needs Work
- ⚠️ Some objects don't render correctly
- ⚠️ Need to verify object tile IDs and graphics lookup
- ⚠️ May be palette or graphics sheet issues for specific object types
- ⚠️ Floor rendering (screenshot shows grid, need to confirm if floor tiles are actually rendering or if the grid is obscuring them)

### Next Investigation Steps
1. **Verify Floor Rendering:** Check if the floor tiles are actually rendering underneath the grid or if they are missing.
2. **Check Object Types:** Identify which specific objects are rendering incorrectly (e.g., chests, pots, enemies).
3. **Verify Tile IDs:** Check `RoomObject::DecodeObjectFromBytes()` and `GetTile()` to ensure correct tile IDs are being calculated.
4. **Debug Logging:** Use the added logging to verify that the correct graphics sheets are being loaded for the objects.

## Detailed Context for Next Session

### Architecture Overview
The dungeon rendering has TWO separate tile systems:

1. **Layout Tiles** (`RoomLayout` class) - Pre-defined room templates (8 layouts total)
   - Loaded from ROM via `kRoomLayoutPointers[]` in `dungeon_rom_addresses.h`
   - Rendered by `LoadLayoutTilesToBuffer()` → `bg1_buffer_.SetTileAt()` / `bg2_buffer_.SetTileAt()`
   - **NOW WORKING** after the LoadLayout fix

2. **Object Tiles** (`RoomObject` class) - Placed objects (walls, doors, decorations, etc.)
   - Loaded from ROM via `LoadObjects()` → `ParseObjectsFromLocation()`
   - Rendered by `RenderObjectsToBackground()` → `ObjectDrawer::DrawObject()`
   - **PARTIALLY WORKING** - walls visible but some objects look wrong

### Key Files for Object Rendering
| File | Purpose |
|------|---------|
| `room.cc:LoadObjects()` | Parses object data from ROM |
| `room.cc:RenderObjectsToBackground()` | Iterates objects, calls ObjectDrawer |
| `object_drawer.cc` | Main object rendering logic |
| `object_drawer.cc:DrawTileToBitmap()` | Draws individual 8x8 tiles |
| `room_object.cc:DecodeObjectFromBytes()` | Decodes 3-byte object format |
| `room_object.cc:GetTile()` | Returns TileInfo for object tiles |

### Object Encoding Format (3 bytes)
```
Byte 1: YYYYY XXX  (Y = tile Y position bits 4-0, X = tile X position bits 2-0)
Byte 2: S XXX YYYY (S = size bit, X = tile X position bits 5-3, Y = tile Y position bits 8-5)
Byte 3: OOOOOOOO  (Object ID)
```

### Potential Object Rendering Issues to Investigate

1. **Tile ID Calculation**
   - Objects use `GetTile(index)` to get TileInfo for each sub-tile
   - The tile ID might be calculated incorrectly for some object types
   - Check `RoomObject::EnsureTilesLoaded()` and tile lookup tables

2. **Graphics Sheet Selection**
   - Objects should use tiles from `current_gfx16_` (room-specific buffer)
   - Different object types may need tiles from different sheet ranges:
     - Blocks 0-7: Main dungeon graphics
     - Blocks 8-11: Static sprites (pots, fairies, etc.)
     - Blocks 12-15: Enemy sprites

3. **Palette Assignment**
   - Objects have a `palette_` field in TileInfo
   - Dungeon palette has 6 groups × 15 colors = 90 colors
   - Palette offset = `(palette_ & 0x07) * 15`
   - Some objects might have wrong palette index

4. **Object Type Handlers**
   - `ObjectDrawer` has different draw methods for different object sizes
   - `DrawSingle()`, `Draw2x2()`, `DrawVertical()`, `DrawHorizontal()`, etc.
   - Some handlers might have bugs in tile placement

### Debug Logging Currently Active
- `[CopyRoomGraphicsToBuffer]` - Logs block/sheet IDs and first bytes
- `[RenderRoomGraphics]` - Logs dirty flags and floor graphics
- `[LoadLayoutTilesToBuffer]` - Logs layout object count
- `[ObjectDrawer]` - Logs first 5 tile draws with position/palette info

### Files Modified in This Session
1. `src/zelda3/dungeon/room.cc:LoadLayoutTilesToBuffer()` - Added layout loading call
2. `src/zelda3/dungeon/room.cc:LoadRoomGraphics()` - Fixed comment, kept i==6 condition
3. `src/app/app.cmake` - Added z3ed WASM exports
4. `src/app/editor/ui/ui_coordinator.cc` - Fixed menu bar right panel positioning
5. `src/app/rom.cc` - Added debug logging for graphics loading

### Quick Test Commands
```bash
# Build
cmake --build build --target yaze -j4

# Run with dungeon editor
./build/bin/Debug/yaze.app/Contents/MacOS/yaze --rom_file=zelda3.sfc --editor=Dungeon
```

### 6. 2BPP Placeholder Sheets (Verified 2025-11-26)
- **Sheets 113-114:** These are 2BPP font/title sheets loaded separately via Load2BppGraphics()
- **In graphics_buffer:** They contain 0xFF placeholder data (4096 bytes each)
- **Impact:** If blockset IDs accidentally point to 113-114, tiles render as solid color
- **Status:** This is expected behavior, not a bug

## Debugging the "Number-Like" Artifacts

The observed "5, 7, 8" number patterns could indicate:

1. **Font Sheet Access:** Blockset IDs pointing to font sheets (but sheets 113-114 have 0xFF, not font data)
2. **Debug Rendering:** Tile IDs or coordinates rendered as text (check for printf to canvas)
3. **Corrupted Offset:** Wrong src_index calculation causing read from arbitrary memory
4. **Uninitialized blocks_:** If LoadRoomGraphics() not called before CopyRoomGraphicsToBuffer()

### Debug Logging Added (room.cc)
```cpp
printf("[CopyRoomGraphicsToBuffer] Block %d (Sheet %d): Offset %d\n", block, sheet_id, src_sheet_offset);
printf("  Bytes: %02X %02X %02X %02X %02X %02X %02X %02X\n", ...);
```

### Next Steps
1. Run the application and check console output for:
   - Sheet IDs for each block (should be 0-112 or 115-126 for valid dungeon graphics)
   - First bytes of each sheet (should NOT be 0xFF for valid graphics)
2. If sheet IDs are valid but graphics are wrong, check:
   - LoadGfxGroups() output for blockset 0 (verify main_blockset_ids)
   - GetGraphicsAddress() returning correct ROM offsets

## Graphics Buffer Layout

### Per-Sheet (4096 bytes each)
- Width: 128 pixels (16 tiles × 8 pixels)
- Height: 32 pixels (4 tiles × 8 pixels)
- Format: 8BPP linear (1 byte per pixel)
- Values: 0-7 for 3BPP graphics

### Room Graphics Buffer (current_gfx16_)
- Size: 64KB (0x10000 bytes)
- Layout: 16 blocks × 4096 bytes
- Contains: Room-specific graphics from blocks_[0..15]

### Index Calculation
```cpp
int tile_col = tile_id % 16;
int tile_row = tile_id / 16;
int tile_base_x = tile_col * 8;
int tile_base_y = tile_row * 1024;  // 8 rows * 128 bytes stride
int src_index = (py * 128) + px + tile_base_x + tile_base_y;
```

## Files Involved

| File | Function | Purpose |
|------|----------|---------|
| `rom.cc` | `LoadAllGraphicsData()` | Decompresses and converts 3BPP→8BPP |
| `room.cc` | `CopyRoomGraphicsToBuffer()` | Copies sheet data to room buffer |
| `room.cc` | `LoadAnimatedGraphics()` | Loads animated tile data |
| `room.cc` | `RenderRoomGraphics()` | Renders room with palette |
| `object_drawer.cc` | `DrawTileToBitmap()` | Draws object tiles |
| `background_buffer.cc` | `DrawTile()` | Draws background tiles |
| `snes_palette.cc` | `LoadDungeonMainPalettes()` | Loads 90-color palettes |
| `snes_tile.cc` | `SnesTo8bppSheet()` | Converts 3BPP→8BPP |