The Dungeon Editor provides a Workbench-first workspace for editing Zelda 3 dungeon rooms. The default flow keeps room navigation, the canvas, selection inspection, and local edit tools in one stable window so common edits do not require chasing separate floating panels.

Overview

Key Features

512x512 canvas per room with pan, zoom, grid, and collision overlays
Layer visualization with BG1/BG2 toggles and colored object outlines
Dungeon Workbench with room browser, canvas, and a three-mode inspector
Window workflow fallback for users who still want standalone panels
Undo/Redo shared across all panels
Overworld integration - double-click entrances to open linked rooms

Related Documentation:

Architecture

The editor uses a three-layer architecture:

Layer	Components	Responsibility
UI	DungeonEditorV2	Panels, canvas, menus, toolbar
Backend	DungeonEditorSystem	State management, undo/redo, persistence
Data	Room Model	Buffers, objects, palettes, blocksets

Rendering Pipeline

Load - Read room header, blockset pointers, and door/entrance metadata
Decode - Convert blockset into bitmaps; parse objects by layer
Draw - Build BG1/BG2 bitmaps with object overlays
Queue - Push bitmaps to texture queue for GPU upload
Present - Display layers with selection widgets and grid

Changes to tiles, palettes, or objects invalidate only the affected room's cache.

Editing Workflow

Opening Rooms

Launch YAZE with a ROM: ./scripts/yaze zelda3.sfc
Select Dungeon.
Use the Dungeon Workbench room browser, recent-room tabs, or connected graph to navigate rooms.
Use split view or recent-room tabs for comparison instead of opening many separate room windows.

Workbench Inspector

The right inspector has three primary modes:

Mode	Purpose
Room	Current room summary, room actions, header fields, apply scope, layer/compositing controls
Selection	Focused object/entity properties, copy/delete/clear actions, and entity-specific tools
Tools	Workbench-local edit tools embedded as primary inspector content

The Tools mode includes Object Selector, Door tools, Sprite tools, Item tools, Palette, Room Graphics, Room Tags, Custom Collision, Water Fill, and Minecart tools. Choose the active tool from one grouped menu; the tool fills the remaining inspector height. Use Room or Selection to return to metadata, or Pop out to move the active tool into its traditional floating window. Standalone tool entries remain available in the Window Browser/sidebar while Workbench mode is active. If a tool is already floating, opening it from the Workbench focuses that window instead of drawing the same tool twice.

The Object Selector renders room-context thumbnails by default when room graphics are available. The compact cards preserve each object's aspect ratio, show its hexadecimal ID in a stable footer, and put the full name and diagnostic detail in the hover tooltip. Search and the two primary filters stay visible; thumbnail, card-size, reset, and custom-object actions live under More. Entries that cannot render a tile layout fall back to a typed symbol.

Available Panels

Panel	Purpose
Dungeon Workbench	Default single-window dungeon editing surface
Room List / Room Matrix	Navigation/review surfaces; also available inside the Workbench flow
Entrances List	Navigate between overworld entrances and rooms
Object Tile Editor	Standalone 8x8 tile composition editor for object asset authoring
Window Browser	Manage standalone windows when using Window workflow

Workbench-local edit tools can run inside the Tools inspector or in standalone windows. Switch to Window workflow from the sidebar when you want the older navigation-first panel layout.

Canvas Controls

Action	Control
Select object	Left-click
Add to selection	Shift + Left-click
Move object	Drag handles
Pan canvas	Hold Space + drag
Zoom	Mouse wheel or trackpad pinch
Context menu	Right-click
Cycle overlapping selections	Alt + click

Enable Object Labels from the toolbar to display layer-colored labels.

To record a rendering problem, right-click the canvas and open the room or selection issue report. The report stays local until you choose Save to Issue Log. Its form scrolls independently on small windows, while save, copy, screenshot, and close actions remain available in the footer. File paths and raw renderer diagnostics are collapsed by default so they do not crowd the normal reporting flow. Screenshot capture keeps the action buttons in place. Long status messages stay on one line; hover over the status to read the full message, including any error details.

Saving

File > Save ROM persists dungeon data in this order: dungeon maps (when Save Dungeon Maps is enabled), then per-room objects, sprites, room headers (14-byte header + message IDs), door pointers (with 0xF0 0xFF marker), then palettes, torches, pits, blocks, chests, pot items, and dirty entrance/spawn-point metadata. No need to save from the Dungeon Editor separately for ROM file writes.
Oversized dirty pot-item edits now fail the save and stay dirty instead of silently preserving stale ROM bytes.
Undo/Redo: Cmd/Ctrl+Z and Cmd/Ctrl+Shift+Z
Changes are tracked across all panels
Keep backups enabled in File > Options > Experiment Flags
To validate output against ZScream golden ROMs on macOS, see ZScreamCLI Validation.

Troubleshooting

Issue	Solution
Objects on wrong layer	Check BG toggles in the Workbench toolbar and the layer field in Selection or Inspector → Tools
Palette not saving	Open Inspector → Tools → Palette and ensure the palette edit is applied before switching rooms
Door alignment issues	Use clickable door-pair badges or Inspector → Tools → Doors to verify linked room IDs
Sluggish performance	Prefer Workbench mode and close unused standalone room windows

Quick Launch Examples

# Open specific room for testing
./scripts/yaze --rom_file=zelda3.sfc --editor=Dungeon --room=0 \
  --open_panels=dungeon.workbench
 
# Open Workbench directly with startup shells hidden
./scripts/yaze --rom_file=zelda3.sfc --editor=Dungeon --room=16 \
  --open_panels=dungeon.workbench \
  --startup_welcome=hide --startup_dashboard=hide
 
# Legacy full window workflow with standalone panels
./scripts/yaze --rom_file=zelda3.sfc --editor=Dungeon \
  --open_panels="dungeon.room_selector,dungeon.room_matrix,dungeon.object_selector,dungeon.palette_editor"

	yaze 0.3.2 Link to the Past ROM Editor