Dungeon Object Rendering & Editor Roadmap

This is the canonical reference for ALTTP dungeon object rendering research and the editor/preview implementation. It lifts the active plan out of the .claude/plans directory so everyone can find and update it in one place.

Context

Runtime entrypoints live in ALTTP bank_00 (see assets/asm/usdasm/bank_00.asm): reset/NMI/IRQ plus the module dispatcher (RunModule) that jumps to gameplay modules (Underworld load/run, Overworld load/run, Interface, etc.). When wiring emulator-based previews or state snapshots, remember the main loop increments $1A, clears OAM, calls RunModule, and the NMI handles joypad + PPU/HDMA updates.
Dungeon object rendering depends on object handler tables in later banks (Phase 1 below), plus WRAM state (tilemap buffers, offsets, drawing flags) and VRAM/CHR layout matching what the handlers expect.

Phases

Phase 1: ALTTP Disassembly Deep Dive

Dump and document object handler tables (Type1/2/3), categorize handlers, map shared subroutines.
Trace WRAM usage: tilemap buffers, offsets, drawing flags, object pointers, room/floor state; build init tables.
Verify ROM address mapping; answer LoROM/HiROM offsets per handler bank.
Deliverables: docs/internal/alttp-object-handlers.md, docs/internal/alttp-wram-state.md, WRAM dump examples.
✅ Handler tables extracted from ROM; summary published in docs/internal/alttp-object-handlers.md (Type1/2/3 addresses and common handlers). Next: fill per-handler WRAM usage.

Phase 2: Emulator Preview Fixes

Fix handler execution (e.g., $3479 timeout) with cycle traces and required WRAM state.
Complete WRAM initialization for drawing context, offsets, flags.
Verify VRAM/CHR and palette setup.
Validate key objects (0x00 floor, 0x01 walls, 0x60 vertical wall) against ZScream.
State injection roadmap (for later emulator manipulation): capture a minimal WRAM/VRAM snapshot that boots directly into a target dungeon room with desired inventory/state. Needed fields: room ID/submodule, Link coords, camera offsets, inventory bitfields (sword/shield/armor/keys/map/compass), dungeon progress flags (boss, pendant/crystal), BG tilemap buffers, palette state. This ties WRAM tracing to the eventual “load me into this dungeon with these items” feature.
Testing plan (headless + MCP):
1. Build/launch headless with gRPC: SDL_VIDEODRIVER=dummy ./scripts/dev_start_yaze.sh (script now auto-finds build_ai/bin/Debug/yaze.app/...).
2. Run yaze-mcp server: /Users/scawful/Code/yaze-mcp/venv/bin/python /Users/scawful/Code/yaze-mcp/server.py (Codex MCP configured with yaze-debugger entry).
3. Dump WRAM via MCP: read_memory address="7E0000" size=0x8000 before/after room entry or object draw; diff snapshots.
4. Annotate diffs in alttp-wram-state.md (purpose/default/required-for-preview vs state injection); script minimal WRAM initializer once stable.

Phase 3: Emulator Preview UI/UX

Object browser with names/search/categories/thumbnails.
Controls: size slider, layer selector, palette override, room graphics selector.
Preview features: auto-render, zoom, grid, PNG export; status with cycle counts and error hints.

Phase 4: Restore Manual Draw Routines

Keep manual routines as fallback (ObjectRenderMode: Manual/Emulator/Hybrid).
Revert/retain original patterns for extensible walls/floors.
Toggle in dungeon_canvas_viewer (or equivalent) to switch modes.

Phase 5: Object Editor – Selection & Manipulation

Selection system (single/multi, marquee, Ctrl/Shift toggles).
Movement via drag + grid snap; keyboard nudge.
Context menu (cut/copy/paste/duplicate/delete, send to back/front, properties).
Scroll-wheel resize with clamping; undo/redo coverage for add/delete/move/resize/property changes.

Phase 6: Object List Panel

Sidebar list with thumbnails, type name, position/size/layer, selection sync.
Drag to reorder (draw order), right-click menu, double-click to edit, add dropdown.

Phase 7: Integration & Polish

Shortcuts (Ctrl+A/C/X/V/D/Z/Y, Delete, arrows, +/- resize, Escape clear).
Visual feedback: selection borders/handles, drag overlays, status bar (selected count, tool mode, grid snap, zoom).
Performance: thumbnail caching, lazy/offscreen rendering, batched updates, debounced re-renders.

Immediate Next Steps

Continue Phase 1 WRAM tracing for problematic handlers (e.g., $3479).
Finish selection/UX wiring from Phase 5 once the current editor diffs stabilize.
Keep this doc in sync with code changes; avoid editing the .claude/plans copy going forward.

4.5 KiB Raw Blame History Unescape Escape