feat(editor): in-game map editor for lighting, and a feed that lights the game from its per-map files #1817

Open
Drommedhar wants to merge 1 commit from Drommedhar/Longshot:feat/map-editor into main
First-time contributor

Type: feat · Risk: low · Tested on: Windows 11, AMD Radeon RX 9070 XT, at 2560x1440 (by hand) · Needs: Linux (a build and a short look), NVIDIA and Intel (a short look)

TL;DR

This adds an in-game map editor for lighting, and a feed that makes the game light itself with what the editor saves. In the editor you pick a surface in the picture, add a light or mark a surface as a light source, move it, see it in the game at once, and save it per map. Both parts are off unless you set HOS_MAP_EDITOR=1 (the editor) or HOS_MAP_LIGHTS=1 (the feed). Checked with 42 new game-free test files, by hand in the game on Windows (before the last sync with main), and after the sync by the whole suite, a full build and one scripted smoke run.

Breakdown

  • Who it helps: people who want to author or fix a map's lighting without editing the game's files by hand, and the ray tracing work that needs per-surface light data.
  • What was wrong: nothing about the game's lighting could be seen, picked or changed from inside the game; the data lives in files only a reader of the formats can follow.
  • What changes: with the switches set, F8 opens an editor with a free camera, a hover and click that pick the surface under the cursor by its triangles, light and surface editing, and a per-map file; the feed serves the game its own lighting files with those lights in them.
  • What does not change: with HOS_MAP_EDITOR and HOS_MAP_LIGHTS unset the game behaves as on main: the hooks in shared code are one cached flag test (the source checks are named under Testing).
  • How it was checked: the whole suite against main (numbers under Testing), 42 new game-free test files, and by hand in the game on Windows at 2560x1440 before the sync with main (hover, click, add a light, move it, cast light, save, reload); after the sync, a full build and one scripted smoke run.
  • What is still open: never built or run on Linux; the live lights rest on addresses of one game build; a list of unproven cases is under Testing.
  • Risk: low while off; with the editor on, a wrong write into the game's light objects would corrupt its memory, so the live module checks the build and the whole pointer chain before every write and switches itself off on any doubt.

Why

Lighting in this game is data: placed lights, lights rigged to objects, baked lists, an ambient per map, emission on materials. There was no way to see where a light sits, to try another one, or to say "this surface glows" and see the result, short of editing the files and restarting. The editor makes that a loop of seconds, and the per-map file it writes is the data a later ray tracing step can read (surfaces that emit light, with the values for them). This PR is the editor, the file, and the feed that carries a saved file into the game's own lighting; it does not change how the renderer lights anything.

The model and mesh file formats were learned with the public https://github.com/moose-modder/hookshot-mod-studio (GPL-3.0) as a reference for understanding; no code was copied, and our own description of the formats is in docs/map-data.md.

What changed

An editor in the renderer, readers for the game's map data in the host, a per-map file format, a feed that serves the game its lighting files with the editor's lights in them, and live writing of light values into the game. Everything is behind two environment switches. Read it in this order:

To try it (Windows; the editor is checked there):

  1. Start the game with HOS_MAP_EDITOR=1 (and HOS_MAP_LIGHTS=1 to have the game lit by saved lights at the next map load).
  2. In a map press F8: the free camera flies (WASD, Q down, E up, Shift faster, hold the right mouse button to look).
  3. Hover a surface: it is outlined with its object and material; click it to select it (the Edit tab shows its card).
  4. Add a light at the clicked point, move it with the handle, set its colour and brightness: it is lit in the game at once. Cast light marks the surface as a light source (data for ray tracing).
  5. Save (the footer, or it saves by itself a moment after a change), leave and enter the map again: the lights are back. F7 hides the panel.

By part (folders):

  • Map data readers, host (host/oot_*.c, host/oot_*.h). Placement lists (oot_banc), the game's lighting data (oot_scene_light, oot_scene_light_baked), model files with their materials, shapes and bones (oot_model), meshes including meshlet shapes and the connected pieces of a surface (oot_model_mesh), the material and object classes (oot_model_class), BYML reading and writing (oot_byml, oot_byml_write), the RomFS and mods file layer (oot_romfs). host/map_editor_data.c loads a map's data on a thread of its own when the map's name changes and gives the renderer an immutable snapshot (map_editor_store.h, map_editor_light_snap.h); host/map_editor_surface.c answers "the triangles of this piece" and "the cursor's ray against this shape". Formats: docs/map-data.md.
  • The editor, renderer (gpu/vk/vk_editor*.cpp|h, gpu/vk/map_editor*.h). The mode, markers and Dear ImGui panel (vk_editor.cpp, vk_editor_lights.cpp): one panel with Edit, Lights, Scene and Advanced tabs, whose layout rules are a table with tests (vk_editor_layout.h: no sentences, a control that cannot apply is not drawn). Picking: the scene's depth at the click's texel (vk_editor_depth*: one texel copied through the recorder, never a raw Vulkan call in the editor) and then the triangles (mesh_owner_of_point, with see-through surfaces such as water, glass and decals tested by the cursor's ray: vk_editor_seethrough.h). The lights: add, move (a handle in the picture), edit, duplicate, delete, disable a shipped light; a default reach of 15 m so a new light is seen. Marks: a surface (a piece, a shape, a sub-object, a material, every object of a kind) marked as a light source expands to per-piece emitters with precedence (vk_editor_emitters.h), with values for ray tracing. Filters (material classes, glowing only), the time-of-day row (frozen by default while the editor is on), fly-to on a click in a list, the right-mouse look, the tag under the cursor.
  • The per-map file (gpu/vk/map_editor.h, map_editor_file.h; docs/map-data.md section 8). <scene>.json in the maps folder (LONGSHOT_MAPS_DIR, else maps beside the NFC folder), format 2: tags, lights, overrides of shipped lights, emissive marks, ambient. Written whole or not at all; a file that does not parse is never overwritten without a button press.
  • The feed (host/map_lights*.c|h; docs/development.md, "Feeding the editor's lights to the game"). With HOS_MAP_LIGHTS=1 the game's file layer serves, in memory, the lighting files the game reads itself (rig lists, palette pack, world parameters, scene settings, the size table at the start; a scene's placement file and its light settings at every open) with the editor's lights, changes and ambient in them, written to cache/map-lights of the game folder, never over the game's files. A saved edit shows at the next load of the map.
  • Live lights (host/map_lights_live.c|h, host/hos_main.c). While the editor is on, the values of a light are queued by the renderer and written into the game's light object on the game's own thread, once a frame. Before every write it checks that the build is the supported one (the module is given the build id and stays off on any other), that the whole pointer chain lies inside the guest's mapped memory, that the table, the light's class and its present values are plausible; any failure writes nothing and switches live editing off until the next map load, with one log line. tests/test_map_lights_live.py runs it on an invented memory image.
  • Renderer interface (gpu/vk/vk_api.h, host/rx_backend.c). MKWVK_API_VERSION 35 to 46: map_acquire/map_release (36), maps_dir (37), the snapshot's lighting and models (38), live_* (39), editor_look (40), editor_camera/editor_link (41), editor_surface/editor_surface_release (42), the snapshot's classes (43), editor_time (44), editor_ray (45), editor_teleport (46); all appended after main's Mods tab members. HOS_OPT_MAP_EDITOR = 100.
  • Hooks in shared code, all gated by the switches: host/hos_main.c (map-name hook, the time setter, the live and feed init, Shift read), host/display.c and host/posix/display_sdl.c (the mouse is free while the editor is on; the look), host/nn_hid.c (no button reaches the game while the editor is on; the camera keys), host/mods.c (the file layer's one test), gpu/vk/vk_menu.cpp, vk_draw.cpp, vk_replay.cpp, vk_main.cpp, vk_internal.h (a few lines each), nx2/build.py (the new host files; one C++ file in the executable).
  • Checks a reviewer can run: scripts/map_editor_check.ps1, map_editor_tags_check.ps1, map_editor_lights_check.ps1, map_lights_check.ps1 (headless runs on the repository save; take the runtime and run folders as parameters; GPU jobs), scripts/model_mesh_check.py, scripts/byml_write_check.py, scripts/map_lights_plan_check.py (against your own game folder, printing counts only), scripts/gpu_idle.ps1 (the lock and idle test the headless checks use).

Measurements

Verdict: nothing to measure: both parts are off by default and cost one cached test while off; with the editor on, the editor's panel and picking are the only cost (a developer tool). No performance claim is made.

Flags and settings

This PR adds the switches below, all off by default (it is a developer tool). The checks' scripts also use existing switches (HOS_HEADLESS, RX_VK_SHOT_W, RX_VK_SHOT_H, RX_VK_VALIDATION) and the Builder's LONGSHOT_MINGW, which this PR does not change.

Flag What it is Before this PR After this PR Effect Helps / doesn't help / untested Recommendation
HOS_MAP_EDITOR=1 (2: enter by itself) the map editor and its data none off reads a map's data on a thread; F8 opens the editor tested on Windows (AMD) off: a developer tool; for a player it would be a menu row later
HOS_MAP_LIGHTS=1 the feed: the game is lit by the saved per-map files none off serves lighting files in memory tested on Windows off until the editor is used
LONGSHOT_MAPS_DIR=<folder> the maps folder none maps beside the NFC folder where <scene>.json is read and written tested default is right
RX_VK_EDITOR_DEPTH=0 turns the editor's depth pick off none on while the editor is on one texel of depth copied per click tested: its first version recorded a raw copy outside the recorder and lost the device; it was rebuilt through the recorder and run under the Khronos validation layer (1.4.363): the run with the pick reported no message that the same run without it lacks on
RX_VK_EDITOR_SCRIPT, RX_VK_EDITOR_COMMANDS, RX_VK_EDITOR_SURFACE_LOG, HOS_MAP_LIVE_LOG scripted actions, a command file, a log of surface fetches, a log of every live write and probe none off for the headless checks diagnostics off: only for testing
HOS_OPT_MAP_EDITOR (option id 100) the renderer's answer to the host: the editor mode none 0 the host frees the mouse and takes the buttons from the game while it is on tested n/a (not a menu row)

All are in gpu/vk/switches.def and docs/development.md.

Testing

Tested:

  • The whole suite, python -I -B tests/run_all.py, in one shell with one compiler on PATH, main and this branch one after the other: main @ 0de25c3e: 705 passed, 51 failed, 119 skipped; this PR @ e0b344bf: 724 passed, 51 failed, 119 skipped. The failing sets are equal by name: the same 51 checks fail on both (they need Tooling beside the checkout, a tool this PC does not have, or are out of date against main's own sources); none fails only here, and the 19 more that pass here are this PR's.
  • 42 new game-free test files (named in the diff under tests/): the readers (test_banc_reader, test_scene_light, test_model_reader, test_model_mesh, test_byml_write), the file format and its host side (test_map_editor_file.cpp, test_map_editor_host, test_map_editor_worker, test_map_editor_light_snap), the editor's pure logic (test_editor_*.cpp: geometry, picking, depth, layout rules, emitters, see-through, filters, time, fly, look, gizmo, card text, light scale, live logic), the feed (test_map_lights_*), the live module on an invented memory image (test_map_lights_live), and the lock the headless checks use (test_gpu_lock). They use invented data only.
  • By hand, before the sync with main: in the game, on Windows 11 with an AMD Radeon RX 9070 XT (AMD driver 26.11.2 (as the game's log names it), Ryzen 9 9950X3D), at 2560x1440, the editor was tried on this branch, the last time on the commit just before the sync with main: hover and click on surfaces including water and glass; add, move, recolour and delete a light and see it lit at once; mark a surface as a light source; disable a shipped light; save, reload the map and find the lights back; the free camera, the look, fly-to; the time row. The scripted checks listed above were also run headless then. The depth pick was run under the Khronos validation layer (1.4.363): the run with the pick reported no message that the same run without it lacks.
  • After the sync with main the tree was not played by hand: it got the whole suite, a full build (pack) and one scripted smoke run: a first scripted run (cold pipeline caches) did not reach play in time; a second, after a game-started map reload, crashed in the game's placement loader (see below); after the fix the same script ran to the end by itself twice (exit 0): enter the editor, click a surface, add a light, mark a surface, Disable a shipped light, save, Reload map (the light is gone from the game's lamp list), Enable, save, Reload map (it is back). With the live write log on, neither run has a live write or read between a "quiet on" and the next "quiet off". Pictures were looked at.
  • Off by default, by the source: tests/test_map_editor_host.py (the gate in host/map_editor_mode.h: with HOS_MAP_EDITOR unset the renderer is never asked), tests/input_background_test.c via test_input_background.py (the map-editor-off case: with the switch unset every button reaches the game), tests/test_map_lights_host.py (switch off: nothing served, nothing read), tests/test_switch_table.py.
  • scripts/check_third_party.py as main; scripts/check_guide_screenshots.py --review-sources gives what main gives (no guide image changes: docs/images/guide/source-review-map-editor.md).
  • The synced tree compiles: every file this PR touches, and the Vulkan back end and host files that include them, were compiled with the build's flags against main's headers; and packs of the whole game were built from this tree (scripts/dev_packs.py pack, 8 jobs: both modules linked); the final one is the tree of this commit.

A crash found by the smoke run, and its fix. One scripted run on the synced tree crashed in the game's placement loader (PlacementMgr thread, a read of guest address 0x10) during a map reload that followed a live write by a frame or two: the editor had Disabled a shipped light, saved and pressed Reload map. The feed was not at fault (the fault came before the away map opened a single file, the same sequence with the feed off survived, and the substitute files the feed builds have the same names and sizes as the pre-sync tree's). The likely cause is a live write into a light object while another thread of the game tears the map down; this is a probable cause, not a proven one, because the crash was not reproduced. The live module now goes quiet (the queue dropped, no write and no read of the game's memory) from the moment a map change is asked for by us, before the game is asked, until the next map is loaded, and from the earliest sign the host has that the game began a change itself (the reserved next map, a map loading, an event playing, read fresh at each update instead of from the 250 ms sample); a write is applied only to an object found through the search table in the same tick. The same sequence then passed twice. tests/test_map_lights_live.py covers it on the invented memory image: a write queued and a reload requested in the same tick writes nothing; quiet lasts until the new generation; a game-started change with the early sign writes nothing after it.

Not tested:

  • A map change that the game itself starts (a door, a cutscene, death, a save loaded) while a live edit is being written was not run, only our own reload and teleport; the early sign makes the module quiet one player update (about 9 to 17 ms at the 60 to 112 fps of the runs) after the game reserves the next map, so a write inside the game's own decision-to-reservation time plus that update can still race.
  • Linux was never built or run. The code is written to the host's POSIX shim and has no Linux-only branch except: the right-mouse look is a no-op with one log line on Linux (host/posix/display_sdl.c: the camera turns with a controller there); the abort net (vk_editor_abort.cpp) is Windows-only (install() does nothing elsewhere); the maps folder is $XDG_DATA_HOME/longshot/maps there (never run); the editor reads keys through the same Win32 calls as the Insert menu does; the .ps1 checks are Windows PowerShell.
  • The live lights rest on addresses of one game build (e0f3ccfa): ml_live_init is given the build id and the module stays off on any other build, with a log line (hos_main.c). The feed and the editor do not depend on it.
  • Headless runs cannot use FSR, so every in-game check was made without it.
  • Unproven: a light on a moving object after a restart; two lights on one rig object; the ambient (it needs a restart); changes to shipped rig lights (the game rewrites them every frame: not editable live); the "far from Link" warning's distance (120 m is a starting number); characters cannot be picked; AMD and Intel (only one AMD PC was used).

Must be tested:

  • Linux (a Linux build, Mesa and NVIDIA): the game builds and starts with the switches unset and set; F8 opens the editor, hover and click pick a surface, a light can be added and is lit, a save is read back after a reload; expecting the right-mouse look to do nothing (a controller turns the camera); by hand or the Test Farm (a Beanstalk comment on this PR).
  • NVIDIA and Intel on Windows: start with HOS_MAP_EDITOR=1, press F8 in a map, click a surface and add a light, expecting the editor's picture to draw and the added light to be lit in the game (by hand or the Test Farm).

Risks

What could break: a map change that the game itself starts while a live edit is being written can still race, within the window described under Testing (the time from the game's decision to reserve the next map until the next player update, at most about one frame plus the game's own unmeasured lead time); a crash of that kind needs the editor on and a light being edited at that moment. The editor is a developer tool and is off by default. With the switches unset, the hooks are one cached test each (the file layer's, the mouse's, the input's, the renderer's per-frame tick). With the editor on: it takes every button from the game and the mouse; the live module writes into the game's memory (checked, and only on the one supported build); a wrong light edit can make a map dark or very bright, in the saved file and the game folder's cache/map-lights only.
Turning it off: leave the switches unset; delete cache/map-lights in the game folder to forget the feed's files; reverting the commit is enough.
Compatibility: MKWVK_API_VERSION is 46 (appended members only); no change to saves, longshot_options.ini or the shader and pipeline caches; the maps folder and the game folder's cache/map-lights are new and used only with the switches set.

Checklist

Everyone

  • One topic.
  • The title is a Conventional Commit of the status line's type.
  • Why gives the reason plainly. (No issue on the tracker covers it.)
  • Tested on my own PC where it runs, as Testing's Tested says; what can't be run is in Not tested.
  • Measurements has a verdict, or one line saying why there is nothing to measure.
  • Nothing gets worse that I know of: the cost while off is one cached test.
  • Testing names what was tested, what wasn't, and what must still be tested.
  • Rebased on current main: one commit on top of main (0de25c3e).
  • python -I -B tests/run_all.py passes (any failure that also fails on main is named): the same 51 checks fail on main and here, the failing sets are equal by name, named in the first comment below.
  • No game files, dumps, build output or generated files.
  • third_party/ untouched (a new folder with a PROVENANCE.md instead).
  • The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled.

When it applies

  • AI assistance recorded with Assisted-by: / Co-Authored-By: trailers.
  • Switches documented (docs/development.md) and shipped at their recommended value (off: a developer tool).
  • MKWVK_API_VERSION bumped (gpu/vk/vk_api.h's MkwVkHost changed).
  • A game-free test added, failing on main and passing here.
  • A check under tests/ that reads changed source updated in this PR, not weakened (test_hos_ab.py, test_screensaver fixture, test_switch_table).
  • Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. Not ticked: Windows only so far, Linux never built (Testing, Not tested); the PR stays WIP until a Linux build and look.
  • Docs updated.

🤖 Generated with Claude Code

**Type:** feat · **Risk:** low · **Tested on:** Windows 11, AMD Radeon RX 9070 XT, at 2560x1440 (by hand) · **Needs:** Linux (a build and a short look), NVIDIA and Intel (a short look) ## TL;DR This adds an in-game map editor for lighting, and a feed that makes the game light itself with what the editor saves. In the editor you pick a surface in the picture, add a light or mark a surface as a light source, move it, see it in the game at once, and save it per map. Both parts are off unless you set `HOS_MAP_EDITOR=1` (the editor) or `HOS_MAP_LIGHTS=1` (the feed). Checked with 42 new game-free test files, by hand in the game on Windows (before the last sync with main), and after the sync by the whole suite, a full build and one scripted smoke run. ## Breakdown - **Who it helps:** people who want to author or fix a map's lighting without editing the game's files by hand, and the ray tracing work that needs per-surface light data. - **What was wrong:** nothing about the game's lighting could be seen, picked or changed from inside the game; the data lives in files only a reader of the formats can follow. - **What changes:** with the switches set, F8 opens an editor with a free camera, a hover and click that pick the surface under the cursor by its triangles, light and surface editing, and a per-map file; the feed serves the game its own lighting files with those lights in them. - **What does not change:** with `HOS_MAP_EDITOR` and `HOS_MAP_LIGHTS` unset the game behaves as on main: the hooks in shared code are one cached flag test (the source checks are named under Testing). - **How it was checked:** the whole suite against main (numbers under Testing), 42 new game-free test files, and by hand in the game on Windows at 2560x1440 before the sync with main (hover, click, add a light, move it, cast light, save, reload); after the sync, a full build and one scripted smoke run. - **What is still open:** never built or run on Linux; the live lights rest on addresses of one game build; a list of unproven cases is under Testing. - **Risk:** low while off; with the editor on, a wrong write into the game's light objects would corrupt its memory, so the live module checks the build and the whole pointer chain before every write and switches itself off on any doubt. ## Why Lighting in this game is data: placed lights, lights rigged to objects, baked lists, an ambient per map, emission on materials. There was no way to see where a light sits, to try another one, or to say "this surface glows" and see the result, short of editing the files and restarting. The editor makes that a loop of seconds, and the per-map file it writes is the data a later ray tracing step can read (surfaces that emit light, with the values for them). This PR is the editor, the file, and the feed that carries a saved file into the game's own lighting; it does not change how the renderer lights anything. The model and mesh file formats were learned with the public https://github.com/moose-modder/hookshot-mod-studio (GPL-3.0) as a reference for understanding; no code was copied, and our own description of the formats is in `docs/map-data.md`. ## What changed An editor in the renderer, readers for the game's map data in the host, a per-map file format, a feed that serves the game its lighting files with the editor's lights in them, and live writing of light values into the game. Everything is behind two environment switches. Read it in this order: **To try it** (Windows; the editor is checked there): 1. Start the game with `HOS_MAP_EDITOR=1` (and `HOS_MAP_LIGHTS=1` to have the game lit by saved lights at the next map load). 2. In a map press **F8**: the free camera flies (WASD, Q down, E up, Shift faster, hold the right mouse button to look). 3. Hover a surface: it is outlined with its object and material; click it to select it (the Edit tab shows its card). 4. **Add a light** at the clicked point, move it with the handle, set its colour and brightness: it is lit in the game at once. **Cast light** marks the surface as a light source (data for ray tracing). 5. Save (the footer, or it saves by itself a moment after a change), leave and enter the map again: the lights are back. **F7** hides the panel. **By part** (folders): - **Map data readers, host (`host/oot_*.c`, `host/oot_*.h`).** Placement lists (`oot_banc`), the game's lighting data (`oot_scene_light`, `oot_scene_light_baked`), model files with their materials, shapes and bones (`oot_model`), meshes including meshlet shapes and the connected pieces of a surface (`oot_model_mesh`), the material and object classes (`oot_model_class`), BYML reading and writing (`oot_byml`, `oot_byml_write`), the RomFS and mods file layer (`oot_romfs`). `host/map_editor_data.c` loads a map's data on a thread of its own when the map's name changes and gives the renderer an immutable snapshot (`map_editor_store.h`, `map_editor_light_snap.h`); `host/map_editor_surface.c` answers "the triangles of this piece" and "the cursor's ray against this shape". Formats: `docs/map-data.md`. - **The editor, renderer (`gpu/vk/vk_editor*.cpp|h`, `gpu/vk/map_editor*.h`).** The mode, markers and Dear ImGui panel (`vk_editor.cpp`, `vk_editor_lights.cpp`): one panel with Edit, Lights, Scene and Advanced tabs, whose layout rules are a table with tests (`vk_editor_layout.h`: no sentences, a control that cannot apply is not drawn). Picking: the scene's depth at the click's texel (`vk_editor_depth*`: one texel copied through the recorder, never a raw Vulkan call in the editor) and then the triangles (`mesh_owner_of_point`, with see-through surfaces such as water, glass and decals tested by the cursor's ray: `vk_editor_seethrough.h`). The lights: add, move (a handle in the picture), edit, duplicate, delete, disable a shipped light; a default reach of 15 m so a new light is seen. Marks: a surface (a piece, a shape, a sub-object, a material, every object of a kind) marked as a light source expands to per-piece emitters with precedence (`vk_editor_emitters.h`), with values for ray tracing. Filters (material classes, glowing only), the time-of-day row (frozen by default while the editor is on), fly-to on a click in a list, the right-mouse look, the tag under the cursor. - **The per-map file (`gpu/vk/map_editor.h`, `map_editor_file.h`; `docs/map-data.md` section 8).** `<scene>.json` in the maps folder (`LONGSHOT_MAPS_DIR`, else `maps` beside the NFC folder), format 2: tags, lights, overrides of shipped lights, emissive marks, ambient. Written whole or not at all; a file that does not parse is never overwritten without a button press. - **The feed (`host/map_lights*.c|h`; `docs/development.md`, "Feeding the editor's lights to the game").** With `HOS_MAP_LIGHTS=1` the game's file layer serves, in memory, the lighting files the game reads itself (rig lists, palette pack, world parameters, scene settings, the size table at the start; a scene's placement file and its light settings at every open) with the editor's lights, changes and ambient in them, written to `cache/map-lights` of the game folder, never over the game's files. A saved edit shows at the next load of the map. - **Live lights (`host/map_lights_live.c|h`, `host/hos_main.c`).** While the editor is on, the values of a light are queued by the renderer and written into the game's light object on the game's own thread, once a frame. Before every write it checks that the build is the supported one (the module is given the build id and stays off on any other), that the whole pointer chain lies inside the guest's mapped memory, that the table, the light's class and its present values are plausible; any failure writes nothing and switches live editing off until the next map load, with one log line. `tests/test_map_lights_live.py` runs it on an invented memory image. - **Renderer interface (`gpu/vk/vk_api.h`, `host/rx_backend.c`).** `MKWVK_API_VERSION` 35 to 46: `map_acquire`/`map_release` (36), `maps_dir` (37), the snapshot's lighting and models (38), `live_*` (39), `editor_look` (40), `editor_camera`/`editor_link` (41), `editor_surface`/`editor_surface_release` (42), the snapshot's classes (43), `editor_time` (44), `editor_ray` (45), `editor_teleport` (46); all appended after main's Mods tab members. `HOS_OPT_MAP_EDITOR` = 100. - **Hooks in shared code, all gated by the switches:** `host/hos_main.c` (map-name hook, the time setter, the live and feed init, Shift read), `host/display.c` and `host/posix/display_sdl.c` (the mouse is free while the editor is on; the look), `host/nn_hid.c` (no button reaches the game while the editor is on; the camera keys), `host/mods.c` (the file layer's one test), `gpu/vk/vk_menu.cpp`, `vk_draw.cpp`, `vk_replay.cpp`, `vk_main.cpp`, `vk_internal.h` (a few lines each), `nx2/build.py` (the new host files; one C++ file in the executable). - **Checks a reviewer can run:** `scripts/map_editor_check.ps1`, `map_editor_tags_check.ps1`, `map_editor_lights_check.ps1`, `map_lights_check.ps1` (headless runs on the repository save; take the runtime and run folders as parameters; GPU jobs), `scripts/model_mesh_check.py`, `scripts/byml_write_check.py`, `scripts/map_lights_plan_check.py` (against your own game folder, printing counts only), `scripts/gpu_idle.ps1` (the lock and idle test the headless checks use). ## Measurements **Verdict:** nothing to measure: both parts are off by default and cost one cached test while off; with the editor on, the editor's panel and picking are the only cost (a developer tool). No performance claim is made. ### Flags and settings This PR adds the switches below, all off by default (it is a developer tool). The checks' scripts also use existing switches (`HOS_HEADLESS`, `RX_VK_SHOT_W`, `RX_VK_SHOT_H`, `RX_VK_VALIDATION`) and the Builder's `LONGSHOT_MINGW`, which this PR does not change. | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | `HOS_MAP_EDITOR=1` (2: enter by itself) | the map editor and its data | none | off | reads a map's data on a thread; F8 opens the editor | tested on Windows (AMD) | off: a developer tool; for a player it would be a menu row later | | `HOS_MAP_LIGHTS=1` | the feed: the game is lit by the saved per-map files | none | off | serves lighting files in memory | tested on Windows | off until the editor is used | | `LONGSHOT_MAPS_DIR=<folder>` | the maps folder | none | `maps` beside the NFC folder | where `<scene>.json` is read and written | tested | default is right | | `RX_VK_EDITOR_DEPTH=0` | turns the editor's depth pick off | none | on while the editor is on | one texel of depth copied per click | tested: its first version recorded a raw copy outside the recorder and lost the device; it was rebuilt through the recorder and run under the Khronos validation layer (1.4.363): the run with the pick reported no message that the same run without it lacks | on | | `RX_VK_EDITOR_SCRIPT`, `RX_VK_EDITOR_COMMANDS`, `RX_VK_EDITOR_SURFACE_LOG`, `HOS_MAP_LIVE_LOG` | scripted actions, a command file, a log of surface fetches, a log of every live write and probe | none | off | for the headless checks | diagnostics | off: only for testing | | `HOS_OPT_MAP_EDITOR` (option id 100) | the renderer's answer to the host: the editor mode | none | 0 | the host frees the mouse and takes the buttons from the game while it is on | tested | n/a (not a menu row) | All are in `gpu/vk/switches.def` and `docs/development.md`. ## Testing **Tested:** - The whole suite, `python -I -B tests/run_all.py`, in one shell with one compiler on PATH, main and this branch one after the other: **main @ 0de25c3e: 705 passed, 51 failed, 119 skipped; this PR @ e0b344bf: 724 passed, 51 failed, 119 skipped.** The failing sets are equal by name: the same 51 checks fail on both (they need Tooling beside the checkout, a tool this PC does not have, or are out of date against main's own sources); none fails only here, and the 19 more that pass here are this PR's. - 42 new game-free test files (named in the diff under `tests/`): the readers (`test_banc_reader`, `test_scene_light`, `test_model_reader`, `test_model_mesh`, `test_byml_write`), the file format and its host side (`test_map_editor_file.cpp`, `test_map_editor_host`, `test_map_editor_worker`, `test_map_editor_light_snap`), the editor's pure logic (`test_editor_*.cpp`: geometry, picking, depth, layout rules, emitters, see-through, filters, time, fly, look, gizmo, card text, light scale, live logic), the feed (`test_map_lights_*`), the live module on an invented memory image (`test_map_lights_live`), and the lock the headless checks use (`test_gpu_lock`). They use invented data only. - **By hand, before the sync with main:** in the game, on Windows 11 with an AMD Radeon RX 9070 XT (AMD driver 26.11.2 (as the game's log names it), Ryzen 9 9950X3D), at 2560x1440, the editor was tried on this branch, the last time on the commit just before the sync with main: hover and click on surfaces including water and glass; add, move, recolour and delete a light and see it lit at once; mark a surface as a light source; disable a shipped light; save, reload the map and find the lights back; the free camera, the look, fly-to; the time row. The scripted checks listed above were also run headless then. The depth pick was run under the Khronos validation layer (1.4.363): the run with the pick reported no message that the same run without it lacks. - **After the sync with main** the tree was not played by hand: it got the whole suite, a full build (pack) and one scripted smoke run: a first scripted run (cold pipeline caches) did not reach play in time; a second, after a game-started map reload, **crashed in the game's placement loader** (see below); after the fix the same script ran to the end by itself twice (exit 0): enter the editor, click a surface, add a light, mark a surface, Disable a shipped light, save, Reload map (the light is gone from the game's lamp list), Enable, save, Reload map (it is back). With the live write log on, neither run has a live write or read between a "quiet on" and the next "quiet off". Pictures were looked at. - Off by default, by the source: `tests/test_map_editor_host.py` (the gate in `host/map_editor_mode.h`: with `HOS_MAP_EDITOR` unset the renderer is never asked), `tests/input_background_test.c` via `test_input_background.py` (the `map-editor-off` case: with the switch unset every button reaches the game), `tests/test_map_lights_host.py` (switch off: nothing served, nothing read), `tests/test_switch_table.py`. - `scripts/check_third_party.py` as main; `scripts/check_guide_screenshots.py --review-sources` gives what main gives (no guide image changes: `docs/images/guide/source-review-map-editor.md`). - The synced tree compiles: every file this PR touches, and the Vulkan back end and host files that include them, were compiled with the build's flags against main's headers; and packs of the whole game were built from this tree (`scripts/dev_packs.py pack`, 8 jobs: both modules linked); the final one is the tree of this commit. **A crash found by the smoke run, and its fix.** One scripted run on the synced tree crashed in the game's placement loader (`PlacementMgr` thread, a read of guest address 0x10) during a map reload that followed a live write by a frame or two: the editor had Disabled a shipped light, saved and pressed Reload map. The feed was not at fault (the fault came before the away map opened a single file, the same sequence with the feed off survived, and the substitute files the feed builds have the same names and sizes as the pre-sync tree's). The likely cause is a live write into a light object while another thread of the game tears the map down; this is a probable cause, not a proven one, because the crash was not reproduced. The live module now goes quiet (the queue dropped, no write and no read of the game's memory) from the moment a map change is asked for by us, before the game is asked, until the next map is loaded, and from the earliest sign the host has that the game began a change itself (the reserved next map, a map loading, an event playing, read fresh at each update instead of from the 250 ms sample); a write is applied only to an object found through the search table in the same tick. The same sequence then passed twice. `tests/test_map_lights_live.py` covers it on the invented memory image: a write queued and a reload requested in the same tick writes nothing; quiet lasts until the new generation; a game-started change with the early sign writes nothing after it. **Not tested:** - **A map change that the game itself starts** (a door, a cutscene, death, a save loaded) while a live edit is being written was not run, only our own reload and teleport; the early sign makes the module quiet one player update (about 9 to 17 ms at the 60 to 112 fps of the runs) after the game reserves the next map, so a write inside the game's own decision-to-reservation time plus that update can still race. - **Linux was never built or run.** The code is written to the host's POSIX shim and has no Linux-only branch except: the right-mouse look is a no-op with one log line on Linux (`host/posix/display_sdl.c`: the camera turns with a controller there); the abort net (`vk_editor_abort.cpp`) is Windows-only (`install()` does nothing elsewhere); the maps folder is `$XDG_DATA_HOME/longshot/maps` there (never run); the editor reads keys through the same Win32 calls as the Insert menu does; the `.ps1` checks are Windows PowerShell. - **The live lights rest on addresses of one game build** (`e0f3ccfa`): `ml_live_init` is given the build id and the module stays off on any other build, with a log line (`hos_main.c`). The feed and the editor do not depend on it. - Headless runs cannot use FSR, so every in-game check was made without it. - Unproven: a light on a moving object after a restart; two lights on one rig object; the ambient (it needs a restart); changes to shipped rig lights (the game rewrites them every frame: not editable live); the "far from Link" warning's distance (120 m is a starting number); characters cannot be picked; AMD and Intel (only one AMD PC was used). **Must be tested:** - Linux (a Linux build, Mesa and NVIDIA): the game builds and starts with the switches unset and set; F8 opens the editor, hover and click pick a surface, a light can be added and is lit, a save is read back after a reload; expecting the right-mouse look to do nothing (a controller turns the camera); by hand or the Test Farm (a Beanstalk comment on this PR). - NVIDIA and Intel on Windows: start with `HOS_MAP_EDITOR=1`, press F8 in a map, click a surface and add a light, expecting the editor's picture to draw and the added light to be lit in the game (by hand or the Test Farm). ## Risks **What could break:** a map change that the game itself starts while a live edit is being written can still race, within the window described under Testing (the time from the game's decision to reserve the next map until the next player update, at most about one frame plus the game's own unmeasured lead time); a crash of that kind needs the editor on and a light being edited at that moment. The editor is a developer tool and is off by default. With the switches unset, the hooks are one cached test each (the file layer's, the mouse's, the input's, the renderer's per-frame tick). With the editor on: it takes every button from the game and the mouse; the live module writes into the game's memory (checked, and only on the one supported build); a wrong light edit can make a map dark or very bright, in the saved file and the game folder's `cache/map-lights` only. **Turning it off:** leave the switches unset; delete `cache/map-lights` in the game folder to forget the feed's files; reverting the commit is enough. **Compatibility:** `MKWVK_API_VERSION` is 46 (appended members only); no change to saves, `longshot_options.ini` or the shader and pipeline caches; the maps folder and the game folder's `cache/map-lights` are new and used only with the switches set. ## Checklist ### Everyone - [x] One topic. - [x] The title is a Conventional Commit of the status line's type. - [x] Why gives the reason plainly. (No issue on the tracker covers it.) - [x] Tested on my own PC where it runs, as Testing's Tested says; what can't be run is in Not tested. - [x] Measurements has a verdict, or one line saying why there is nothing to measure. - [x] Nothing gets worse that I know of: the cost while off is one cached test. - [x] Testing names what was tested, what wasn't, and what must still be tested. - [x] Rebased on current `main`: one commit on top of main (0de25c3e). - [x] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named): the same 51 checks fail on main and here, the failing sets are equal by name, named in the first comment below. - [x] No game files, dumps, build output or generated files. - [x] `third_party/` untouched (a new folder with a `PROVENANCE.md` instead). - [x] The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled. ### When it applies - [x] AI assistance recorded with `Assisted-by:` / `Co-Authored-By:` trailers. - [x] Switches documented (docs/development.md) and shipped at their recommended value (off: a developer tool). - [x] `MKWVK_API_VERSION` bumped (`gpu/vk/vk_api.h`'s `MkwVkHost` changed). - [x] A game-free test added, failing on main and passing here. - [x] A check under `tests/` that reads changed source updated in this PR, not weakened (`test_hos_ab.py`, `test_screensaver` fixture, `test_switch_table`). - [ ] Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. Not ticked: Windows only so far, Linux never built (Testing, Not tested); the PR stays WIP until a Linux build and look. - [x] Docs updated. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
feat(editor): in-game map editor for lighting, and a feed that lights the game from its per-map files
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Blocked by required conditions
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Blocked by required conditions
CI / Conventional Commit title (pull_request) Blocked by required conditions
CI / Workflow lint (actionlint) (pull_request) Blocked by required conditions
Guide screenshots / Guide images and local UI source review (pull_request) Blocked by required conditions
Third-party parts / The same as upstream (pull_request) Blocked by required conditions
Third-party parts / As their notes say (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request_target) Has been skipped
PR description / Description follows the template (pull_request_target) Failing after 4s
e0b344bf26
An in-game editor (F8) to author lighting per map: pick a surface by its
triangles, add and move lights, mark surfaces as light sources, save a
per-map file. A feed serves the game its own lighting files with those lights
in them, and live writes show an edit at once. Both are off unless
HOS_MAP_EDITOR=1 or HOS_MAP_LIGHTS=1 is set; the renderer interface goes to
version 46. The model and mesh formats were learned with the public
moose-modder/hookshot-mod-studio (GPL-3.0) as a reference; no code was copied.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Author
First-time contributor

Tested in game: Windows 11, AMD Radeon RX 9070 XT, AMD proprietary driver 26.11.2, Ryzen 9 9950X3D, 2560x1440, the Market: the editor was played by hand on the branch before the sync with main (hover and click on surfaces including water, add and move a light, cast light, save, reload); after the sync with main the tree was not played by hand: the whole suite, a full build and two scripted smoke runs (click a surface, add a light, mark a surface, Disable a shipped light, save, reload the map, Enable, save, reload) ran to the end with exit 0 after a first run crashed during a map reload and the live module was made quiet around map changes (see Testing)

Tested in game: Windows 11, AMD Radeon RX 9070 XT, AMD proprietary driver 26.11.2, Ryzen 9 9950X3D, 2560x1440, the Market: the editor was played by hand on the branch before the sync with main (hover and click on surfaces including water, add and move a light, cast light, save, reload); after the sync with main the tree was not played by hand: the whole suite, a full build and two scripted smoke runs (click a surface, add a light, mark a surface, Disable a shipped light, save, reload the map, Enable, save, reload) ran to the end with exit 0 after a first run crashed during a map reload and the live module was made quiet around map changes (see Testing)
Member

Possibly related, for context:

  • PR #1151 WIP: feat(vk): ray tracing: lights from glowing materials, guide buffers and alpha in the rays without micromaps (on #727) — Overlapping ray-tracing emitter/light work
Possibly related, for context: - PR #1151 WIP: feat(vk): ray tracing: lights from glowing materials, guide buffers and alpha in the rays without micromaps (on #727) — Overlapping ray-tracing emitter/light work
Author
First-time contributor

The checks that fail on main @ 0de25c3e and fail the same way on this PR @ e0b344bf (tests/run_all.py, one shell, one compiler; none fails only here):

  • Auto-controlled
  • tests/test_auto_handheld.py
  • tests/test_bug_report.py
  • tests/test_bug_report_defaults.py
  • tests/test_build_long_paths.py
  • tests/test_capture_read_once.py
  • tests/test_crash_dialog.py
  • tests/test_crash_groups.py
  • tests/test_crt_options.py
  • tests/test_damage_debug_menu.py
  • tests/test_dev_packs.py
  • tests/test_discover.py
  • tests/test_display_startup_failure.py
  • tests/test_dlss_feature_size.py
  • tests/test_failed_compile_keeps_objects.py
  • tests/test_fastfp_fma.py
  • tests/test_fma_soft.py
  • tests/test_fpx_sticky.py
  • tests/test_game_menu_mouse_buttons.py
  • tests/test_guest_imported.py
  • tests/test_hardware_report.py
  • tests/test_high_fps_fixes.py
  • tests/test_host_guest_writes.py
  • tests/test_hud_layout_row.py
  • tests/test_job_queue.py
  • tests/test_libc_hooks.py
  • tests/test_lift_lookups.py
  • tests/test_linux_preflight.py
  • tests/test_linux_pressure.py
  • tests/test_make_game_cache.py
  • tests/test_missing_nup.py
  • tests/test_mods_list.py
  • tests/test_pads_after_menu.py
  • tests/test_pending_guest_import.py
  • tests/test_pipeline_play_cache.py
  • tests/test_prepare_cache_save.py
  • tests/test_present_thread.py
  • tests/test_profiling_mode.py
  • tests/test_psychov35_fsr3_fg.py
  • tests/test_readback_timeout_source.py
  • tests/test_release.py
  • tests/test_sdiv_overflow.py
  • tests/test_slow_frames.py
  • tests/test_song_note_cue.py
  • tests/test_spawn_emit.py
  • tests/test_tested_configurations.py
  • tests/test_upscaler_rows.py
  • tests/test_vbytes.py
  • tests/test_vcore_escape.py
  • tests/test_vfpx_elem.py
  • tests/test_walk.py
  • tests/test_walk_key.py

main: 705 passed, 51 failed, 119 skipped; this PR: 724 passed, 51 failed, 119 skipped.

The checks that fail on main @ 0de25c3e and fail the same way on this PR @ e0b344bf (tests/run_all.py, one shell, one compiler; none fails only here): - Auto-controlled - tests/test_auto_handheld.py - tests/test_bug_report.py - tests/test_bug_report_defaults.py - tests/test_build_long_paths.py - tests/test_capture_read_once.py - tests/test_crash_dialog.py - tests/test_crash_groups.py - tests/test_crt_options.py - tests/test_damage_debug_menu.py - tests/test_dev_packs.py - tests/test_discover.py - tests/test_display_startup_failure.py - tests/test_dlss_feature_size.py - tests/test_failed_compile_keeps_objects.py - tests/test_fastfp_fma.py - tests/test_fma_soft.py - tests/test_fpx_sticky.py - tests/test_game_menu_mouse_buttons.py - tests/test_guest_imported.py - tests/test_hardware_report.py - tests/test_high_fps_fixes.py - tests/test_host_guest_writes.py - tests/test_hud_layout_row.py - tests/test_job_queue.py - tests/test_libc_hooks.py - tests/test_lift_lookups.py - tests/test_linux_preflight.py - tests/test_linux_pressure.py - tests/test_make_game_cache.py - tests/test_missing_nup.py - tests/test_mods_list.py - tests/test_pads_after_menu.py - tests/test_pending_guest_import.py - tests/test_pipeline_play_cache.py - tests/test_prepare_cache_save.py - tests/test_present_thread.py - tests/test_profiling_mode.py - tests/test_psychov35_fsr3_fg.py - tests/test_readback_timeout_source.py - tests/test_release.py - tests/test_sdiv_overflow.py - tests/test_slow_frames.py - tests/test_song_note_cue.py - tests/test_spawn_emit.py - tests/test_tested_configurations.py - tests/test_upscaler_rows.py - tests/test_vbytes.py - tests/test_vcore_escape.py - tests/test_vfpx_elem.py - tests/test_walk.py - tests/test_walk_key.py main: 705 passed, 51 failed, 119 skipped; this PR: 724 passed, 51 failed, 119 skipped.
Drommedhar changed title from WIP: feat(editor): in-game map editor for lighting, and a feed that lights the game from its per-map files to feat(editor): in-game map editor for lighting, and a feed that lights the game from its per-map files 2026-11-19 23:30:42 +00:00
Drommedhar changed title from feat(editor): in-game map editor for lighting, and a feed that lights the game from its per-map files to WIP: feat(editor): in-game map editor for lighting, and a feed that lights the game from its per-map files 2026-11-19 23:47:47 +00:00
Drommedhar changed title from WIP: feat(editor): in-game map editor for lighting, and a feed that lights the game from its per-map files to feat(editor): in-game map editor for lighting, and a feed that lights the game from its per-map files 2026-11-20 07:30:13 +00:00
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Blocked by required conditions
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Blocked by required conditions
CI / Conventional Commit title (pull_request) Blocked by required conditions
CI / Workflow lint (actionlint) (pull_request) Blocked by required conditions
Guide screenshots / Guide images and local UI source review (pull_request) Blocked by required conditions
Third-party parts / The same as upstream (pull_request) Blocked by required conditions
Third-party parts / As their notes say (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request_target) Has been skipped
PR description / Description follows the template (pull_request_target) Failing after 4s
This pull request has changes conflicting with the target branch.
  • docs/development.md
  • docs/user/images/guide/source-review-map-editor.md
  • gpu/vk/vk_api.h
  • gpu/vk/vk_draw.cpp
  • gpu/vk/vk_menu.cpp
  • gpu/vk/vk_replay.cpp
  • host/nn_hid.c
  • host/rx_backend.c
  • tests/input_background_test.c
  • tests/test_hos_ab.py
  • tests/test_input_background.py
Some workflows are waiting to be reviewed.
View command line instructions

Manual merge helper

Use this merge commit message when completing the merge manually.

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u 'feat/map-editor:Drommedhar-feat/map-editor'
git switch 'Drommedhar-feat/map-editor'
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
MagicBeanDev/Longshot!1817
No description provided.