backend-infra-engineer: Post v0.3.9-hotfix7 snapshot (build cleanup)

2025-12-22 00:20:49 +00:00
parent 2934c82b75
commit 5c4cd57ff8
1259 changed files with 239160 additions and 43801 deletions
--- a/docs/internal/agents/archive/gemini-session-2025-11-23/gemini3-overworld-fix-prompt.md
+++ b/docs/internal/agents/archive/gemini-session-2025-11-23/gemini3-overworld-fix-prompt.md
@@ -0,0 +1,165 @@
+# Gemini 3 Pro Prompt: Overworld Regression Fix and Improvements
+
+## Context
+
+You are working on **yaze** (Yet Another Zelda3 Editor), a C++23 ROM editor for The Legend of Zelda: A Link to the Past. A regression has been introduced that breaks loading of custom ROMs like "Oracle of Secrets" ROM hack.
+
+## Primary Bug: ASM Version Check Inconsistency
+
+### Root Cause Analysis
+
+The recent refactoring introduced `OverworldVersionHelper` for centralized ROM version detection, but **not all code paths were updated to use it consistently**. Specifically:
+
+**In `src/zelda3/overworld/overworld.cc:71`:**
+```cpp
+uint8_t asm_version = (*rom_)[OverworldCustomASMHasBeenApplied];
+if (asm_version >= 3) {  // BUG: 0xFF (255) is >= 3!
+  AssignMapSizes(overworld_maps_);
+} else {
+  FetchLargeMaps();  // Vanilla ROMs need this path
+}
+```
+
+**The bug**: `asm_version >= 3` evaluates to `true` for vanilla ROMs where `asm_version == 0xFF` (255), causing vanilla ROMs and custom ROMs without ZScream ASM patches to incorrectly call `AssignMapSizes()` instead of `FetchLargeMaps()`.
+
+**Other places correctly check**:
+```cpp
+if (asm_version >= 3 && asm_version != 0xFF) { ... }  // Correct
+```
+
+### Inconsistent Locations Found
+
+Search results showing mixed patterns:
+- `overworld.cc:71` - **BUG**: `if (asm_version >= 3)` - missing `&& asm_version != 0xFF`
+- `overworld.cc:449` - **BUG**: `if (expanded_flag != 0x04 || asm_version >= 3)` - missing check
+- `overworld.cc:506` - **BUG**: similar pattern
+- `overworld.cc:281` - **CORRECT**: `(asm_version < 3 || asm_version == 0xFF)`
+- `overworld.cc:373` - **CORRECT**: `if (asm_version >= 3 && asm_version != 0xFF)`
+- Other files also have inconsistencies
+
+## Your Task
+
+### Phase 1: Fix the Regression (CRITICAL)
+
+1. **Update all ASM version checks** in overworld code to either:
+   - Use `OverworldVersionHelper::GetVersion()` and semantic checks like `SupportsAreaEnum()`, OR
+   - Consistently use `asm_version >= 3 && asm_version != 0xFF` pattern
+
+2. **Key files to fix**:
+   - `src/zelda3/overworld/overworld.cc`
+   - `src/zelda3/overworld/overworld_map.cc`
+   - `src/zelda3/overworld/overworld_item.cc`
+
+3. **Priority fixes in `overworld.cc`**:
+   - Line 71: Change to `if (asm_version >= 3 && asm_version != 0xFF)`
+   - Line 449: Add `&& asm_version != 0xFF` check
+   - Line 506: Add `&& asm_version != 0xFF` check
+   - Review all other locations from the grep results
+
+### Phase 2: Standardize Version Checking (Recommended)
+
+Replace all raw `asm_version` checks with `OverworldVersionHelper`:
+
+**Instead of:**
+```cpp
+uint8_t asm_version = (*rom_)[OverworldCustomASMHasBeenApplied];
+if (asm_version >= 3 && asm_version != 0xFF) {
+```
+
+**Use:**
+```cpp
+auto version = OverworldVersionHelper::GetVersion(*rom_);
+if (OverworldVersionHelper::SupportsAreaEnum(version)) {
+```
+
+This centralizes the logic and prevents future inconsistencies.
+
+### Phase 3: Add Unit Tests
+
+Create tests in `test/unit/zelda3/overworld_test.cc` to verify:
+1. Vanilla ROM (0xFF) uses `FetchLargeMaps()` path
+2. ZScream v3 ROM (0x03) uses `AssignMapSizes()` path
+3. Custom ROMs with other values behave correctly
+
+## Key Files Reference
+
+```
+src/zelda3/overworld/
+├── overworld.cc              # Main loading logic
+├── overworld.h
+├── overworld_map.cc          # Individual map handling
+├── overworld_map.h
+├── overworld_item.cc         # Item loading
+├── overworld_item.h
+├── overworld_entrance.h      # Entrance/Exit data
+├── overworld_exit.cc
+├── overworld_exit.h
+├── overworld_version_helper.h # Version detection helper
+```
+
+## OverworldVersionHelper API
+
+```cpp
+enum class OverworldVersion {
+  kVanilla = 0,     // 0xFF in ROM - no ZScream ASM
+  kZSCustomV1 = 1,
+  kZSCustomV2 = 2,
+  kZSCustomV3 = 3   // Area enum system
+};
+
+class OverworldVersionHelper {
+  static OverworldVersion GetVersion(const Rom& rom);
+  static bool SupportsAreaEnum(OverworldVersion v);     // v3 only
+  static bool SupportsExpandedSpace(OverworldVersion v); // v1+
+  static bool SupportsCustomBGColors(OverworldVersion v); // v2+
+  // ...
+};
+```
+
+## Commits That Introduced the Regression
+
+1. `1e39df88a3` - "refactor: enhance overworld entity properties and version handling"
+   - Introduced `OverworldVersionHelper`
+   - 15 files changed, +546 -282 lines
+
+2. `5894809aaf` - "refactor: improve overworld map version handling and code organization"
+   - Updated `OverworldMap` to use version helper
+   - 4 files changed, +145 -115 lines
+
+## Build & Test Commands
+
+```bash
+# Configure
+cmake --preset mac-dbg
+
+# Build
+cmake --build build --target yaze -j8
+
+# Run unit tests
+ctest --test-dir build -L stable -R overworld
+
+# Run the app to test loading
+./build/bin/Debug/yaze.app/Contents/MacOS/yaze --rom_file=/path/to/oracle_of_secrets.sfc
+```
+
+## Success Criteria
+
+1. Oracle of Secrets ROM loads correctly in the Overworld Editor
+2. Vanilla ALTTP ROMs continue to work
+3. ZScream v3 patched ROMs continue to work
+4. All existing unit tests pass
+5. No new compiler warnings
+
+## Additional Context
+
+- The editor supports multiple ROM types: Vanilla, ZScream v1/v2/v3 patched ROMs, and custom hacks
+- `OverworldCustomASMHasBeenApplied` address (0x130000) stores the version byte
+- 0xFF = vanilla (no patches), 1-2 = legacy ZScream, 3 = current ZScream
+- "Oracle of Secrets" is a popular ROM hack that may use 0xFF or a custom value
+
+## Code Quality Requirements
+
+- Follow Google C++ Style Guide
+- Use `absl::Status` for error handling
+- Run clang-format before committing
+- Update CLAUDE.md coordination board when done