backend-infra-engineer: Post v0.3.9-hotfix7 snapshot (build cleanup)
This commit is contained in:
scawful
@@ -0,0 +1,224 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user