|
yaze 0.3.2
Link to the Past ROM Editor
|
|
| |
|
yaze 0.3.2
Link to the Past ROM Editor
|
|
|
| |
Status: partly implemented (Atlas P1, 2026-09-28). Working now: the
[atlas]project keys, the annotation loader (yaze.atlas/1 files and the two Oracle of Secrets files) andz3ed atlas-render --view dungeon --json. Not yet: the overworld view, PNG output and the editor windows; those parts of this page describe the plan. The design is in docs/internal/plans/atlas-2026-09-27.md.
The Atlas draws two overview pictures of your hack:
yaze reads most of this from the ROM. Annotations add what the ROM cannot tell: names, colors, planned rooms and links that only exist in your ASM.
Today (P1) the dungeon model is available as JSON from the command line:
The JSON (schema yaze.atlas.dungeon/1) lists every room with its area, status, name, doors, links in and out, chest and key badges and plans, plus door edges, areas and a per-area key table. Every fact says where it came from: rom, registry, annotation:<file>, symbol:<label> or default. stdout gets a short JSON summary (ROM SHA-1, annotation files, counts, warnings). The command never writes the ROM.
Planned: --view overworld, --out <png>, and two editor windows with hover, filters, click-to-open and PNG export.
A project with no annotations still works. yaze uses built-in vanilla defaults: dungeon names and colors keyed by the entrance dungeon ID (Eastern Palace, Desert Palace, ...), Light/Dark/Special World sections, large areas from the ROM, and the vanilla rules for tiles, items and warp pads.
Add an [atlas] section to your .yaze file:
| Key | Meaning |
|---|---|
annotations | One or more annotation files, comma separated, relative to the .yaze file. Later files override earlier ones. |
defaults | vanilla (default) keeps the built-in names and colors under your own; none starts empty. |
symbols | Optional .sym file for links read from ROM symbols. Lookup order: --symbols, the .sym next to the ROM, this key, then [files] symbols_filename. |
export_folder | Where the editor's Export buttons write (planned). |
yaze keeps the section when it saves the project, together with any keys, sections and comments it does not know. A project with --project must load something project-specific: a dungeon registry (Docs/Dev/Planning/dungeons.json) or [atlas] annotations. Otherwise, and when a listed file is missing, atlas-render stops with an error instead of guessing.
A minimal file:
IDs can be "0x0F", "0F" or a number. Room and map lists accept ranges such as "0x90-0x96". Colors are #RRGGBB. Keys that start with _ are comments. The JSON Schema is assets/atlas/atlas-annotations-1.schema.json.
| Field | Use it for |
|---|---|
dungeons[] | Code, name and color for each dungeon. Key by dungeon_id (the entrance dungeon ID byte) or by owner (a dungeon ID from your project registry). |
areas[] | Groups of rooms the ROM cannot assign to a dungeon, for example a hub reached by a scripted warp. Each has key, code, name, color, rooms. |
rooms.<id>.name | A room name shown in the cell and tooltip. |
rooms.<id>.status | "reserved" marks an empty room you want to keep. |
plans[] | Rooms you plan to use. Drawn as a dashed outline in the plan color. |
| Field | Use it for |
|---|---|
links[] | Links made by your ASM or scripts. Example: {"view": "dungeon", "kind": "pit", "from": "0x81", "to": "0x05", "source": "pit ring checked in the emulator"}. Leave out to for a label-only pill. |
symbol_links[] | Room lists your ASM keeps at a label. Example: {"symbol": "MyHack_WarpTable", "count": 3, "width": 1, "kind": "dream", "label": "DREAM {n} IN"}. |
A link that lands in another dungeon or area gets a red ring.
| Field | Use it for |
|---|---|
overworld.sections[] | Section titles and where each world block sits in the picture. |
overworld.regions[] | Region name, world (LW, DW, SW), color and maps. |
overworld.maps.<id>.name | Map names. |
overworld.gates."<map>:<Gate>" | A note, a role override (ROUTE, POCKET, DECOR) or "suppress": true for a gate badge. |
overworld.edges[] | Force an edge between two maps to open, swim, blocked or special. |
overworld.closed_border_maps | Maps whose borders are closed (special camera). |
overworld.isolated_maps | Maps the walkability check must not cross. |
Gates and edges are detected from tile types by default. Use annotations to correct the result, not to repeat it.
The Atlas also reads the two files used by the Oracle of Secrets map scripts, room_annotations.json and overworld_annotations.json, without changes:
The field-by-field mapping is in section 6.5 of the design doc. The loader also accepts these optional keys in those files, for what the old scripts hard-coded: title, dungeon_colors ({"D1": "#E27676"}), areas[].code, areas[].color, plans[].color, symbol_links and legend_notes in the room file; sections, legend_notes and title in the overworld file.
The old scripts read the dream warps from the .sym themselves. For the Atlas, add them to the room file:
With that entry, atlas-render on a playtest ROM with its .sym matches the old room_matrix.json room for room.
schema or invalid JSON stops atlas-render with a non-zero exit and names the file and the JSON pointer, for example room_annotations.json: /plans/0/rooms/1: "0x1G" is not a room ID .....sym.
1.10.0