225 lines
7.0 KiB
Markdown
225 lines
7.0 KiB
Markdown
# 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):
|
|
```cpp
|
|
// 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
|
|
```cpp
|
|
// 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
|
|
```cpp
|
|
// 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
|
|
```cpp
|
|
#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)
|
|
```cpp
|
|
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
|
|
|
|
```bash
|
|
# 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
|