yaze/docs/internal/agents/archive/large-ref-docs/overworld-system-reference.md

Gemini Pro 3 Overworld Architecture Reference

Compact reference for YAZE Overworld/Dungeon systems. Use this to quickly locate code and understand patterns.

---

1. Overworld Editor Architecture (~8,900 lines across 7 modules)

Main Editor

File	Lines	Purpose
src/app/editor/overworld/overworld_editor.cc	3,204	Main coordinator, canvas, menus
src/app/editor/overworld/overworld_editor.h	350	Class definition

Sub-Modules

File	Lines	Purpose
map_properties.cc	1,759	MapPropertiesSystem - property panels
tile16_editor.cc	2,584	Tile16Editor - tile editing popup
entity.cc	491	OverworldEntity - entity containers
entity_operations.cc	239	Entity CRUD helpers
overworld_entity_renderer.cc	151	Entity drawing
scratch_space.cc	444	Tile16 storage utilities

Data Models

File	Purpose
src/zelda3/overworld/overworld.cc	Main overworld class, loading logic
src/zelda3/overworld/overworld_map.cc	Individual map data
src/zelda3/overworld/overworld_item.cc	Item entities
src/zelda3/overworld/overworld_version_helper.h	Version detection API

---

2. Completed Work (Gemini's Previous Session)

ASM Version Check Standardization

• Replaced raw asm_version >= 3 with OverworldVersionHelper::SupportsAreaEnum()
• Fixed critical bug: vanilla ROMs (0xFF) incorrectly treated as v3+
• Applied consistently across: overworld.cc, overworld_item.cc, overworld_map.cc

Tile16Editor Texture Queueing

• Fixed tile16_editor.cc lines 37-38, 44-45, 56-57
• Pattern: QueueTextureCommand() instead of RenderBitmap() during init

Test Infrastructure

• Created test/unit/zelda3/overworld_regression_test.cc
• Tests OverworldVersionHelper logic (passing)

---

3. Remaining Work Checklist

P0 - Must Complete

Texture Queueing TODOs in overworld_editor.cc

6 locations still use inline rendering instead of deferred queueing:

Line	Current Code	Fix Pattern
1392	// TODO: Queue texture	Use QueueTextureCommand()
1397	// TODO: Queue texture	Use QueueTextureCommand()
1740	// TODO: Queue texture	Use QueueTextureCommand()
1809	// TODO: Queue texture	Use QueueTextureCommand()
1819	// TODO: Queue texture	Use QueueTextureCommand()
1962	// TODO: Queue texture	Use QueueTextureCommand()

Pattern to follow (from tile16_editor.cc):

// BEFORE (blocking)
Renderer::Get().RenderBitmap(&some_bitmap_);

// AFTER (non-blocking)
gfx::Arena::Get().QueueTextureCommand(gfx::TextureCommand{
    .operation = gfx::TextureOperation::kCreate,
    .bitmap = &some_bitmap_,
    .priority = gfx::TexturePriority::kHigh
});

Entity Deletion Pattern (entity.cc:319) - WORKING CORRECTLY

• Note: The TODO comment is misleading. The deleted flag pattern IS CORRECT for ROM editors
• Entities live at fixed ROM offsets, so marking deleted = true is the proper approach
• Renderer correctly skips deleted entities (see overworld_entity_renderer.cc)
• entity_operations.cc reuses deleted slots when creating new entities
• No fix needed - just a cleanup of the misleading TODO comment

P1 - Should Complete

Tile16Editor Undo/Redo - ALREADY COMPLETE

• Location: tile16_editor.cc:1681-1760
• SaveUndoState() called before all edit operations
• Undo() and Redo() fully implemented with absl::Status returns
• Ctrl+Z/Ctrl+Y handling at lines 224-231
• Stack management with kMaxUndoStates_ limit
• No additional work needed

Overworld Regression Test Completion

• Location: test/unit/zelda3/overworld_regression_test.cc
• Current: Only tests version helper
• Need: Add more comprehensive mock ROM data

P2 - Stretch Goals

Dungeon Downwards Draw Routines

• Location: src/zelda3/dungeon/object_drawer.cc lines 160-185
• Missing implementations marked with stubs
• Need: Implement based on game ROM patterns

E2E Cinematic Tests

• Design doc: docs/internal/testing/dungeon-gui-test-design.md
• Framework: ImGuiTestEngine integration ready
• Need: Screenshot capture, visual verification

---

4. Key Patterns

Bitmap/Surface Synchronization

// CORRECT: Use set_data() for bulk replacement
bitmap.set_data(new_data);  // Syncs both data_ and surface_->pixels

// WRONG: Direct assignment breaks sync
bitmap.mutable_data() = new_data;  // NEVER DO THIS

Graphics Refresh Order

// 1. Update model
map.SetProperty(new_value);

// 2. Reload from ROM
map.LoadAreaGraphics();

// 3. Force render
Renderer::Get().RenderBitmap(&map_bitmap_);  // Immediate
// OR
gfx::Arena::Get().QueueTextureCommand(...);  // Deferred (preferred)

Version Helper Usage

#include "zelda3/overworld/overworld_version_helper.h"

auto version = OverworldVersionHelper::GetVersion(*rom_);

// Feature gates
if (OverworldVersionHelper::SupportsAreaEnum(version)) {
  // v3+ only features
}
if (OverworldVersionHelper::SupportsExpandedSpace(version)) {
  // v1+ features
}

Entity Rendering Colors (0.85f alpha)

ImVec4 entrance_color(1.0f, 0.85f, 0.0f, 0.85f);  // Bright yellow-gold
ImVec4 exit_color(0.0f, 1.0f, 1.0f, 0.85f);       // Cyan
ImVec4 item_color(1.0f, 0.0f, 0.0f, 0.85f);       // Bright red
ImVec4 sprite_color(1.0f, 0.0f, 1.0f, 0.85f);     // Bright magenta

---

5. File Quick Reference

Overworld Editor Entry Points

• Initialize() → overworld_editor.cc:64
• Load() → overworld_editor.cc:150
• Update() → overworld_editor.cc:203
• DrawFullscreenCanvas() → overworld_editor.cc:472
• ProcessDeferredTextures() → overworld_editor.cc:899

Tile16Editor Entry Points

• Initialize() → tile16_editor.cc:30
• Update() → tile16_editor.cc:100
• DrawTile16Editor() → tile16_editor.cc:200

Entity System Entry Points

• OverworldEntity::Draw() → entity.cc:50
• DeleteSelectedEntity() → entity.cc:319
• Entity containers: entrances_, exits_, items_, sprites_

Dungeon System Entry Points

• ObjectDrawer::DrawObject() → object_drawer.cc:50
• Draw routines: lines 100-300
• Downwards stubs: lines 160-185

---

6. Test Commands

# Run overworld regression test specifically
ctest --test-dir build_gemini -R "OverworldRegression" -V

# Run all zelda3 unit tests
ctest --test-dir build_gemini -R "zelda3" -L unit

# Run GUI E2E tests
ctest --test-dir build_gemini -L gui -V

---

7. Validation Criteria

For Texture Queueing Fix

• No // TODO comments remain at specified lines
• QueueTextureCommand() used consistently
• UI doesn't freeze when loading maps
• ctest -L stable passes

For Entity Deletion Fix

• Items actually removed from vector
• No memory leaks (items properly destroyed)
• Undo can restore deleted items (if implementing undo)

For Dungeon Draw Routines

• Downwards objects render correctly
• Layer ordering maintained (BG1 → BG2 → BG3)
• Palette applied correctly after render