yaze/docs/dungeon_developer_guide.md

Dungeon Editor Developer Guide

1. Implementation Plan

Goal: Implement fully functional dungeon room editing based on ZScream's proven approach.

1.1. Current State Analysis

• Working: Room header loading, basic class structures (Room, RoomObject), graphics loading, and UI framework.
• Not Working: Object parsing, drawing, placement, and saving. The core issue is the incomplete implementation of the 3-byte object encoding/decoding scheme and the failure to render object tiles to the background buffer.

1.2. ZScream's Approach

ZScream's implementation relies on several key concepts that need to be ported:

• Object Encoding: Three different 3-byte encoding formats for objects based on their ID range (Type 1, Type 2, Type 3).
• Layer Separation: Objects are organized into three layers (BG1, BG2, BG3) separated by 0xFFFF markers in the ROM.
• Object Loading: A loop parses the object data, decodes each 3-byte entry based on its type, and handles layer and door markers.
• Object Drawing: Each object's constituent tiles are drawn to the correct background buffer (tilesBg1Buffer or tilesBg2Buffer), which is then used to render the final room image.

1.3. Implementation Tasks

1. Core Object System (High Priority):
   • Implement the three different object encoding and decoding schemes.
   • Enhance the room object parser to correctly handle layers and door sections.
   • Implement tile loading for objects from the ROM's subtype tables.
   • Create an object drawing system that renders the loaded tiles to the correct background buffer.
2. Editor UI Integration (Medium Priority):
   • Implement object placement, selection, and drag-and-drop on the canvas.
   • Create UI panels for editing object properties (position, size, layer).
3. Save System (High Priority):
   • Implement the serialization of room objects back into the 3-byte ROM format, respecting layers and markers.
   • Implement the logic to write the serialized data back to the ROM, handling potential room size expansion.

---

2. Graphics Rendering Pipeline

This section provides a comprehensive analysis of how the dungeon editor renders room graphics.

2.1. Architecture Diagram

┌─────────────────────────────────────────────────────────────────┐
│                         ROM Data                                 │
│ ┌────────────────────────┐ ┌──────────────────────────────────┐│
│ │ Room Headers           │ │ Dungeon Palettes                 ││
│ │  - Palette ID          │ │  - dungeon_main[id]              ││
│ │  - Blockset ID         │ │  - sprites_aux1[id]              ││
│ └────────────────────────┘ └──────────────────────────────────┘│
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                  Room Loading (room.cc)                          │
│    ├─ Load 16 blocks (graphics sheets)                          │
│    └─ Copy graphics to a 32KB buffer (`current_gfx16_`)         │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│          Room::RenderRoomGraphics() Pipeline                     │
│                                                                  │
│  Step 1: DrawFloor() on BG1 and BG2 buffers                     │
│    └─ Populates buffers with repeating floor tile pattern.      │
│                                                                  │
│  Step 2: RenderObjectsToBackground()                            │
│    └─ Iterates room objects and draws their tiles into the BG1/BG2 buffers.│
│                                                                  │
│  Step 3: DrawBackground() on BG1 and BG2                        │
│    └─ Converts tile words in buffers to 8bpp indexed pixel data in a Bitmap.│
│                                                                  │
│  Step 4: Apply Palette & Create/Update Texture                  │
│    ├─ Get dungeon_main palette for the room.                    │
│    ├─ Apply palette to the Bitmap.                              │
│    └─ Create or update an SDL_Texture from the paletted Bitmap. │
└─────────────────────────────────────────────────────────────────┘

2.2. Blank Canvas Bug: Root Cause Analysis

A critical "blank canvas" bug was diagnosed and fixed. The root cause was multifaceted:

1. Missing Object Rendering: The RenderObjectsToBackground() step was missing entirely. The background buffers only contained the floor pattern, so walls and objects were never drawn.

   • Fix: Implemented RenderObjectsToBackground() to iterate through all loaded room objects and draw their constituent tiles into the correct background buffer (bg1 or bg2).

2. Missing Palette Application: The indexed-pixel Bitmap was being converted to a texture without its palette. SDL had no information to map the color indices to actual colors, resulting in a blank texture.

   • Fix: Added a call to bitmap.SetPaletteWithTransparent() before the CreateAndRenderBitmap() or UpdateBitmap() call.

3. Incorrect Tile Word Format: The floor drawing logic was writing only the tile ID to the buffer, discarding the necessary palette information within the 16-bit tile word.

   • Fix: Modified the code to use gfx::TileInfoToWord() to ensure the full 16-bit value, including palette index, was written.

4. Incorrect Palette ID: The system was hardcoded to use palette 0 for all rooms, causing most dungeons to render with incorrect, "gargoyle-y" colors.

   • Fix: Modified the code to use the specific palette ID loaded from each room's header.

Key Takeaway: The entire rendering pipeline, from buffer population to palette application, must be executed in the correct order for graphics to appear.