feat(editor): in-game map editor for lighting, and a feed that lights the game from its per-map files #1817
No reviewers
Labels
No labels
area/accessibility
area/audio
area/input
area/install
area/menu
area/renderer
area/saves
area/tooling
area/upscaling
beanstalk: approved
beanstalk: failed
beanstalk: needs approval
beanstalk: running
beanstalk: tested
ci: approved
good first issue
gpu/amd
gpu/igpu
gpu/intel
gpu/nvidia
help wanted
kind
bug
kind
chore
kind
docs
kind
feature
kind
performance
kind
question
needs measurements
platform/linux
platform/macos
platform/steam-deck
platform/windows
preview
priority
critical
priority
high
priority
low
regression
risk
high
risk
low
risk
medium
status
blocked
status
confirmed
status
duplicate
status
invalid
status
needs-info
status
wontfix
ci: approved
No milestone
No project
No assignees
2 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
MagicBeanDev/Longshot!1817
Loading…
Reference in a new issue
No description provided.
Delete branch "Drommedhar/Longshot:feat/map-editor"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
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) orHOS_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
HOS_MAP_EDITORandHOS_MAP_LIGHTSunset the game behaves as on main: the hooks in shared code are one cached flag test (the source checks are named under Testing).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):
HOS_MAP_EDITOR=1(andHOS_MAP_LIGHTS=1to have the game lit by saved lights at the next map load).By part (folders):
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.cloads 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.canswers "the triangles of this piece" and "the cursor's ray against this shape". Formats:docs/map-data.md.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.gpu/vk/map_editor.h,map_editor_file.h;docs/map-data.mdsection 8).<scene>.jsonin the maps folder (LONGSHOT_MAPS_DIR, elsemapsbeside 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.host/map_lights*.c|h;docs/development.md, "Feeding the editor's lights to the game"). WithHOS_MAP_LIGHTS=1the 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 tocache/map-lightsof the game folder, never over the game's files. A saved edit shows at the next load of the map.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.pyruns it on an invented memory image.gpu/vk/vk_api.h,host/rx_backend.c).MKWVK_API_VERSION35 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.host/hos_main.c(map-name hook, the time setter, the live and feed init, Shift read),host/display.candhost/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).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'sLONGSHOT_MINGW, which this PR does not change.HOS_MAP_EDITOR=1(2: enter by itself)HOS_MAP_LIGHTS=1LONGSHOT_MAPS_DIR=<folder>mapsbeside the NFC folder<scene>.jsonis read and writtenRX_VK_EDITOR_DEPTH=0RX_VK_EDITOR_SCRIPT,RX_VK_EDITOR_COMMANDS,RX_VK_EDITOR_SURFACE_LOG,HOS_MAP_LIVE_LOGHOS_OPT_MAP_EDITOR(option id 100)All are in
gpu/vk/switches.defanddocs/development.md.Testing
Tested:
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.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.tests/test_map_editor_host.py(the gate inhost/map_editor_mode.h: withHOS_MAP_EDITORunset the renderer is never asked),tests/input_background_test.cviatest_input_background.py(themap-editor-offcase: 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.pyas main;scripts/check_guide_screenshots.py --review-sourcesgives what main gives (no guide image changes:docs/images/guide/source-review-map-editor.md).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 (
PlacementMgrthread, 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.pycovers 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:
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/mapsthere (never run); the editor reads keys through the same Win32 calls as the Insert menu does; the.ps1checks are Windows PowerShell.e0f3ccfa):ml_live_initis 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.Must be tested:
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-lightsonly.Turning it off: leave the switches unset; delete
cache/map-lightsin the game folder to forget the feed's files; reverting the commit is enough.Compatibility:
MKWVK_API_VERSIONis 46 (appended members only); no change to saves,longshot_options.inior the shader and pipeline caches; the maps folder and the game folder'scache/map-lightsare new and used only with the switches set.Checklist
Everyone
main: one commit on top of main (0de25c3e).python -I -B tests/run_all.pypasses (any failure that also fails onmainis named): the same 51 checks fail on main and here, the failing sets are equal by name, named in the first comment below.third_party/untouched (a new folder with aPROVENANCE.mdinstead).When it applies
Assisted-by:/Co-Authored-By:trailers.MKWVK_API_VERSIONbumped (gpu/vk/vk_api.h'sMkwVkHostchanged).tests/that reads changed source updated in this PR, not weakened (test_hos_ab.py,test_screensaverfixture,test_switch_table).🤖 Generated with Claude Code
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)
Possibly related, for context:
The checks that fail on main @
0de25c3eand fail the same way on this PR @e0b344bf(tests/run_all.py, one shell, one compiler; none fails only here):main: 705 passed, 51 failed, 119 skipped; this PR: 724 passed, 51 failed, 119 skipped.
WIP: feat(editor): in-game map editor for lighting, and a feed that lights the game from its per-map filesto feat(editor): in-game map editor for lighting, and a feed that lights the game from its per-map filesfeat(editor): in-game map editor for lighting, and a feed that lights the game from its per-map filesto WIP: feat(editor): in-game map editor for lighting, and a feed that lights the game from its per-map filesWIP: feat(editor): in-game map editor for lighting, and a feed that lights the game from its per-map filesto feat(editor): in-game map editor for lighting, and a feed that lights the game from its per-map filesView 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.