feat(menu): turn the people and animals placed in an area off, per area (Debug tab page, !actors, HOS_OOT_ACTORS_OFF) #1426
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
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
MagicBeanDev/Longshot!1426
Loading…
Reference in a new issue
No description provided.
Delete branch "mooki/Longshot:feat/actor-toggles"
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: medium · Tested on: Linux (Arch, kernel 7.2.15), RTX 4090 (NVIDIA 615.78.08) · Needs: Windows, any GPU (the Debug tab's page and a
!actorsline in a real run)Why
Some places are hard to look at, to test or to film because of what stands in them: the birds and the crowd of Castle Town's market hide what a tester is checking, the people of the market ask for text and hold Link, a bug hunt in one corner of a town keeps meeting the same person. The Debug tab can already move Link, change the time and give items, but nothing can take an actor out of an area. This adds that, per area, and leaves the dangerous cases out so a tester cannot trap themselves: the page offers people, animals, enemies, breakable things and effect spots, never doors, gates, chests, switches, events, warps, shops, bosses or geometry, and an actor that the area's own layout ties to an event, a door or a group of people stays even when its kind is off.
What changed
A map's actors are placed from two layout files, and the game registers each entry with its actor registry as the layout loads; an entry the registry cannot make gets the answer 0 and the layout reader goes on without it. The host now gives that answer for an entry the rules leave out, so the actor is never created: no update, no drawing, no physics, nothing in the save, nothing sent in a co-op room. It applies when the area loads next (Teleport, Switch age, walking out and in), and the page's Reload area button does that in one press.
Three doors, one table of rules (a rule is an area and a kind or family; a family is the first two words of a kind's name:
Npc_Town_*stands for every kind that starts with those two words, and a pattern may have*and?anywhere):!actors off|on AREA PATTERN [force],!actors clear [AREA],!actors list [AREA],!actors reload(AREA is a map name as the log'smap:line shows it, PATTERN a kind or a family); its answers go to the log;HOS_OOT_ACTORS_OFF=AREA:PATTERN[!],..., read when the first layout is read (and fromlongshot_env.txt).What stays when its kind is off (the layout is read once more as its first entry is registered,
host/oot_actor_ties.h):force.forceor not. The Static layout lists groups (AiGroups: a logic module and the actors it works with). Leaving out a street vendor in the Castle Town market stopped the area's load for good (black screen, the game running one frame in many seconds); it is the first reference of a group whose other references are its customers, while leaving out any of its customers did not. So the first reference of a group that has another person or animal among its references is never left out.forceor not. Three guards in the market each sit in a group with two event actors and an area; with one of them left out the game's logic froze about a minute into play, when Link walked past that area (the screen stands still, a game frame takes seconds). A guard whose group has no event did not, nor did an animal of a larger group, the people in no group, or two people of a group of shop people.Both group rules are read from those cases, in one area, one run each; they keep more than the cases need (the leaders are 154 actors in 46 areas, the event groups tie the people in every area that has guards or a scripted crowd), and they are a guess about every other area: the plain limit is that a person whose absence stalls some other script is not known to the tool until a run shows it.
Files to read first:
nx2/oot_patches.pypatch_actor_layout: hooks the layout reader (f_80c1ba50) at its head and its one call of the registry's add (f_83b072b0); both or neither; the registry's other callers (creation by name: events, shots, spawners) are left alone.host/oot_actors.c: the guest side: the layout's file is read once as its first entry is registered, every entry is checked against it (hash and kind together) before anything is left out, and a layout it cannot read whole is counted and left alone; per-area counts, a summary line a second after a load, the page's list and switch, the live command, the environment switch. Layout reads on the BancModule thread, the page and the live command on others: one lock.host/oot_actor_filter.h(the rules, the kinds that are never offered, the counts, the commands),host/oot_byml.h(a read-only, bounds-checked BYML reader),host/oot_actor_ties.h(what the layout ties): pure, no game memory; the tests compile them alone.host/hos_main.chos_oot_reload_area(the Teleport list's map change to the map the game is in, asked as the control bridge asks),host/nn_hid.c(!actors),host/rx_backend.candgpu/vk/vk_api.h(the three callbacks and the row struct),gpu/vk/vk_menu.cpp(the page).docs/development.md("Turning actors off in an area") and the README's Debug tab text.What it does not do, and the page says so:
longshot_options.ini: a player must not find the market empty after a restart.HOS_OOT_ACTORS_OFFis the way to keep one.Measurements
Nothing to measure as a speed change: with no rule nothing is left out, and the only cost is one hash lookup per placed entry and one read of the layout's file per load (the run's log shows it in its load line); the game runs that tested it are under Testing.
Flags and settings
One switch and one menu page; no stored option.
HOS_OOT_ACTORS_OFFAREA:PATTERN[!],...docs/development.md, and a row of the switch tablegpu/vk/switches.def: #1309's rule for a new switch)Testing
Tested: Linux 7.2.15 (Arch), i9-13900K, RTX 4090 (NVIDIA 615.78.08), GCC 16.2.1 and Clang 23.1.3, 2026-11-17; rebased onto
main @ 67efc4d3e, this PR @e3d67d232(five commits; the first bullet is that rebase's reruns, game-free, with no window and no GPU, other work on the PC at load 20 to 60). The other bullets are the earlier results, each with its head overmain @ 544229a26: the game runs and the whole suite are of3a9eeb4f5, and the last commit,7a61b791d, changes tests, comments and docs only, with the 14 focused checks and the Windows fixture check re-run on it. They were not rerun.main @ 67efc4d3e(2026-11-17: #1309, #1383, #1378, #1379), old head7a61b791d, new heade3d67d232. The same changed lines as7a61b791dexcept in one commit (the Actors page,518e007ea, now the 2nd):git range-diffpairs all 5 commits, 1=and 4!; the commit with changed lines differs in 19 old and 22 new patch lines, the other three!differ in context lines only (added and deleted lines equal). (1) The API number, 30 to 32:MKWVK_API_VERSION, the(version 32, longshot)comments,HOS_OPT_CHEAT_ACTORS's, the menu's fourhost->version >= 32guards and its comment,tests/test_actors_page.py's guard text. (2) The host table: main'sperf_tracking(#1383, version 30) now sits beforeactors_list,actors_setandactors_reloadingpu/vk/vk_api.h, inhost/rx_backend.c's prototypes and initializer, and intests/test_audio_output_devices.py's expected slots and its offset checks (they followperf_trackinginstead ofmonitor_select). (3) One new row ingpu/vk/switches.def,HOS_OOT_ACTORS_OFF(diag, string): #1309's rule says a newRX_,HOS_orLONGSHOT_name read from the environment needs one, andhost/oot_actors.creads this one. Conflicts: three files in the Actors-page commit (vk_api.h,rx_backend.c,test_audio_output_devices.py) and one file each in two later commits (the renumbered lines oftests/test_actors_page.pyand ofgpu/vk/vk_api.h), all resolved by keeping both sides, main'sperf_trackingfirst, with the number 32; the pinned-number check stays as loose as it was (>= 30, where it was>= 29). (4) The doc row:docs/development.md's sentence on the API versions now names version 32, the Debug tab's Actors page (actors_list,actors_set,actors_reload). That commit's message saysMKWVK_API_VERSION 32where it said 30. No check deleted.main @ 67efc4d3ewith this PR's changed or new test files copied in: 2 pass, 6 fail (test_actor_filter, test_actor_layout_hook, test_actor_ties, test_actors_page, test_audio_output_devices, test_damage_debug_menu fail on main's source, as they must); test_input_background, test_switch_table pass on main too (test_input_background: the PR's change to its fixture is a stand-in for a host function that only the PR'snn_hid.ccalls, so it compiles on main too;test_switch_tablereads main's own source, where no name is new). With the new switch's row deleted in a scratch copy of the head,test_switch_tablefails, naming it:HOS_OOT_ACTORS_OFF is read (host/oot_actors.c:58) and has no row in gpu/vk/switches.def. The whole suite,tests/run_all.py --jobs 6 --strictin the idle gate with a fresh HOME, each commit in its own clean checkout, one after the other:main @ 67efc4d3e665 passed, 40 failed, 17 skipped in 188 s; this heade3d67d232670 passed, 39 failed, 17 skipped in 202 s. Failing onmainand passing on this head: test_damage_debug_menu.run_all.py --changed 67efc4d3e(the checks that read the 22 changed files; its header counts 255) lists 238 checks by name: all ran in this whole-suite run, and each passed or is one ofmain's own failures.test_damage_debug_menufails onmain @ 67efc4d3e(its fixture lacks stand-ins for the Frame pacing and Threaded rendering rows) and passes here, because this PR's version of it adds them. A Linux build of this head,make_game.pybehind the full-build lock and the build gate, no shader preparation, the game's lifted code reused from an earlier build whose lift key equals this head's (checked): exit 0,v3.0.0-rc.7-9-ge3d67d232, 419 of 519 objects new, 0 failed, 0:01:16. Built, not run. The lift hook'snx2/oot_patches.pyis unchanged andnx2/is the same as on the old base, so the lift key is the old build's.main @ 67efc4d3e): PASS, 8 translation units, 0 failures, 0 unjudged (test_actor_filter,test_actor_layout_hook,test_actor_ties,test_audio_output_devices,test_damage_debug_menu,test_input_background). Windows execution not run.3a9eeb4f5overmain @ 544229a26. What this rebase changed in lines the game runs: the API number and the host table's slot order (actors_*after main'sperf_tracking), whichtest_audio_output_devicespins by offset and the build above compiled; the layout hook, the host code and the page are the same lines.tests/test_actor_filter.py(the rules, the never-offered kinds, force, the commands, the env text, the counts),tests/test_actor_ties.py(the BYML reader on made-up layouts shaped like the real ones: truncated, looped, oversized, a key missing; what a link ties; the groups' leaders and event groups),tests/test_actor_layout_hook.py(the lift patch on text shaped as the lift writes it, and the glue compiled over a made-up guest memory: a left-out entry gets 0 and0xffffffff, a mismatched hash leaves nothing out),tests/test_actors_page.py(the page's states). Each failed before its code (the headers did not exist; the two group rules failed in the tie and filter tests before they were written) and passes with it, under gcc and clang with ASan and UBSan.tests/input_background_test.cgot a stand-in for the new host function it links, found by the whole suite.Actorslist, and is read as none); the lift patch applies to the real liftedcode_009.cat exactly the three places.python -I -B tests/run_all.py --jobs 6 --strict, in a fresh home, on this PR @3a9eeb4f5(the 14 checks that read the changed files again on7a61b791d: all pass) and (the failing ones only, by name) ongit archiveof main @544229a26. This PR: 669 passed, 39 failed, 17 skipped (285 s, 708 checks). The 39 that fail are main's own: run by name ongit archiveof main @544229a26the same 39 fail (0 passed, 39 failed), and none is in this PR's files: test_bug_report_defaults, test_cpu_report, test_crt_options, test_display_startup_failure, test_dlss_feature_size, test_failed_compile_keeps_objects, test_framegen_preset, test_fsr_uniform_ownership, test_guest_imported, test_hud_layout_row, test_import_reach, test_invalidate_vcore, test_linux_preflight, test_linux_pressure, test_linux_update, test_mirror_budget, test_missing_nup, test_mods_size_table, test_nonuniform_image_arrays, test_parallel_init_order, test_pending_guest_import, test_pipeline_play_cache, test_present_thread, test_profiling_mode, test_readback_timeout_source, test_replay_write_order, test_rumble_menu, test_run_all_changed, test_slow_frames, test_staging_burst, test_switch_table, test_target_image_pool, test_tested_configurations, test_upscaler_round_trip, test_upscaler_rows, test_vcore_escape, test_vk_occlusion_queries, test_vk_swapchain_compat, test_walk_key.make_game.pybuild of this PR's sources exited 0 (the last one compiled in 30 s; the lift ofcode_009.cchanged in the first, so that object and the host files that changed were new, the rest came from the object cache),@@done; the generatedcode_009.chas the two hooks atf_80c1ba50's head and at its registry call (0x80c1beac). Shaders were prepared in 25 s from a warm cache of the same translator sources.7a61b791d: PASS (8 translation units, 0 failures;test_input_backgroundamong them). A cross-build on Linux with llvm-mingw of an earlier head: the renderer DLL linked and 63 of 63 host sources compiled for Windows,host/oot_actors.camong them, with 0 warnings under the project's flags (-Wno-everything, so that is not a warning-clean claim); the game executable was not linked (no Windows lift here). Nothing ran on Windows.actors: AREA: 18 families, 1468 placed, 1306 never offered, 51 tied, N left out (load L)read N = 2 at the boot (only the env rule on the two rats), 18 after!actors offfor the free-roaming bird and the people family, and!actors reload(Static 13, Dynamic 5), 3 after the page turned the people family On and its Reload area (the bird and the two rats stay off), 0 after!actors clearand!actors reload, each equal to the offline prediction made from the player's layout files with the same code. Link ran the legs to the spot in the market's street after each of the four loads, a 10 s wait, and a walk of four places after the first two (the first place after the others): the walk passed the place that froze the earlier runs, and a frame-counter check and a 20 s wait after each found no stall; every load was clean (control at once), 0 kernel errors, no crash, nono controllerline. Pictures of the same spots, from the build of3a9eeb4f5, looked at (local files, the game's own; named here, not attached):3a9eeb4f5, only the env rule on the two rats (no person off)3a9eeb4f5, the bird and the people family offNot tested:
force(it skips the entries a layout ties by a link): tested game-free only.Must be tested:
actors: ... left outinlongshot_log.txt, fewer people in the street than before and no frozen frame.Risks
What could break: With no rule nothing is left out: every placed entry still goes to the game's own registry call, and the host adds one hash lookup per entry and one read of the layout's file per load. A layout it cannot read, or an entry that does not match the file, leaves everything in. With a rule on, an area whose script expects a missing person may wait for them (in the Castle Town market the game's logic froze for guards, and the load stopped for a street vendor); the page never offers shop, door, event or boss kinds, keeps what the layout links to an event or a door, and keeps the leaders and the event groups' people, but another area may have another case and a player who turns a family off there could meet a stalled game: the tool is a Debug tab tool, off by default, with a page that says Changes apply when the area loads again. The runtime-made actors (events, shots, spawners) are not touched. Co-op: local only, no message.
Where the code names the game's kinds: one place,
host/oot_actor_filter.h: the prefixes it offers (Npc_,Animal_,EnvironmentalAnimal_,Enemy_,Obj_Pot,Obj_BrokenBox,Obj_Plant_,EftLoc_) and a list of 18 words that make a kind never offered (the player, door, gate, shutter, barrier, lock, chest, switch, event, cutscene, warp, entrance, anchor, area, shop, boss, and the name of the owl character). Every other kind the page and the commands show is read from the player's own layout files at run time; the tests and the docs use made-up names that follow the same shapes.Turning it off: do not set
HOS_OOT_ACTORS_OFFand leave the page's families On (the default); or revert the commit.Compatibility:
MKWVK_API_VERSIONgoes from 30 to 32:MkwVkHostgainsactors_list,actors_setandactors_reload(after main'sperf_tracking, version 30) and a row struct, and the host option ids gainHOS_OPT_CHEAT_ACTORS(37); the renderer and the host build together, and a host older than 32 shows the page as "Not available in this build". The number renumbers again at merge if another pull request lands first: main is at 30 (#1383), open PR 1358 takes 31 (overlay_text), PR 68 takes 33 and PR 1411 takes 34, so it becomes the next free number above whichever lands first. No save, nolongshot_options.inikey (rules are not stored), no shader or pipeline cache change (vk_api.hand the menu are not in the translator's stamp). The lifted code of one function changes (nx2/oot_patches.py), so a build lifts again as for any patch.Issues
None: I needed it for my own testing (bug hunts and pictures in busy places). A search of the tracker for actors, NPCs, crowd and removing actors finds no issue or pull request for this. Related: #996 and #1153 report frame rate drops in the Castle Town market; turning the crowd off with this page is one way to narrow those down (not tried here).
Checklist
Everyone
type(scope): description) of the status line's type.main(67efc4d3e, 2026-11-17; the first Testing bullet).python -I -B tests/run_all.pypasses (any failure that also fails onmainis named): the 40 failures onmain @ 67efc4d3e(39 on this PR's head: one fewer,test_damage_debug_menu, which this PR's test fixes) are main's own, the same names, and are named in Testing.third_party/untouched (a new folder with aPROVENANCE.mdinstead).When it applies
Assisted-by:/Co-Authored-By:trailers.HOS_OOT_ACTORS_OFFalso has its row ingpu/vk/switches.def(#1309's rule).MKWVK_API_VERSIONbumped, 30 to 32 (gpu/vk/vk_api.h'sMkwVkHostchanged); it renumbers again at merge if another pull request lands first (Compatibility).tests/that reads changed source updated in this PR, not weakened (test_audio_output_devices,test_damage_debug_menu,test_input_background).New on this forge; not opened on GitHub.
WIP: feat(menu): turn the people and animals placed in an area off, per area (Debug tab page, !actors, HOS_OOT_ACTORS_OFF)to feat(menu): turn the people and animals placed in an area off, per area (Debug tab page, !actors, HOS_OOT_ACTORS_OFF)7a61b791d3e3d67d2320Rebased
7a61b791donto main67efc4d3e; new heade3d67d232.Patch: the same changed lines as
7a61b791dexcept in one commit (the Actors page,518e007ea, now the 2nd):git range-diffpairs all 5 commits, 1=and 4!; the commit with changed lines differs in 19 old and 22 new patch lines, the other three!differ in context lines only (added and deleted lines equal). (1) The API number, 30 to 32:MKWVK_API_VERSION, the(version 32, longshot)comments,HOS_OPT_CHEAT_ACTORS's, the menu's fourhost->version >= 32guards and its comment,tests/test_actors_page.py's guard text. (2) The host table: main'sperf_tracking(#1383, version 30) now sits beforeactors_list,actors_setandactors_reloadingpu/vk/vk_api.h, inhost/rx_backend.c's prototypes and initializer, and intests/test_audio_output_devices.py's expected slots and its offset checks (they followperf_trackinginstead ofmonitor_select). (3) One new row ingpu/vk/switches.def,HOS_OOT_ACTORS_OFF(diag, string): #1309's rule says a newRX_,HOS_orLONGSHOT_name read from the environment needs one, andhost/oot_actors.creads this one. Conflicts: three files in the Actors-page commit (vk_api.h,rx_backend.c,test_audio_output_devices.py) and one file each in two later commits (the renumbered lines oftests/test_actors_page.pyand ofgpu/vk/vk_api.h), all resolved by keeping both sides, main'sperf_trackingfirst, with the number 32; the pinned-number check stays as loose as it was (>= 30, where it was>= 29). (4) The doc row:docs/development.md's sentence on the API versions now names version 32, the Debug tab's Actors page (actors_list,actors_set,actors_reload). That commit's message saysMKWVK_API_VERSION 32where it said 30. No check deleted.Carried: the earlier results are of
3a9eeb4f5and7a61b791dovermain @ 544229a26(the last commit,7a61b791d, changes tests, comments and docs only): the red-first game-free tests, the layout reader on the 160 real layouts, the whole suite (669 passed, 39 failed, 17 skipped), the first Linux build, and the game runs in the Castle Town market (eight runs; the last one, at3a9eeb4f5, passed). Not rerun; the description names each head.Rerun: the PR's own tests and the ones that read what it changed (test_actor_filter, test_actor_ties, test_actor_layout_hook, test_actors_page, test_damage_debug_menu, test_input_background, test_audio_output_devices, test_switch_table) on the new head: 8 of 8 pass. The same set run over
main @ 67efc4d3ewith this PR's changed or new test files copied in: 2 pass, 6 fail (test_actor_filter, test_actor_layout_hook, test_actor_ties, test_actors_page, test_audio_output_devices, test_damage_debug_menu fail on main's source, as they must); test_input_background, test_switch_table pass on main too (test_input_background: the PR's change to its fixture is a stand-in for a host function that only the PR'snn_hid.ccalls, so it compiles on main too;test_switch_tablereads main's own source, where no name is new). With the new switch's row deleted in a scratch copy of the head,test_switch_tablefails, naming it:HOS_OOT_ACTORS_OFF is read (host/oot_actors.c:58) and has no row in gpu/vk/switches.def. The whole suite,tests/run_all.py --jobs 6 --strictin the idle gate with a fresh HOME, each commit in its own clean checkout, one after the other:main @ 67efc4d3e665 passed, 40 failed, 17 skipped in 188 s; this heade3d67d232670 passed, 39 failed, 17 skipped in 202 s. Failing onmainand passing on this head: test_damage_debug_menu.run_all.py --changed 67efc4d3e(the checks that read the 22 changed files; its header counts 255) lists 238 checks by name: all ran in this whole-suite run, and each passed or is one ofmain's own failures.test_damage_debug_menufails onmain @ 67efc4d3e(its fixture lacks stand-ins for the Frame pacing and Threaded rendering rows) and passes here, because this PR's version of it adds them. A Linux build of this head,make_game.pybehind the full-build lock and the build gate, no shader preparation, the game's lifted code reused from an earlier build whose lift key equals this head's (checked): exit 0,v3.0.0-rc.7-9-ge3d67d232, 419 of 519 objects new, 0 failed, 0:01:16. Built, not run. The lift hook'snx2/oot_patches.pyis unchanged andnx2/is the same as on the old base, so the lift key is the old build's.Windows: syntax check of the changed C/C++ fixtures (llvm-mingw 20261104, idle gate, base
main @ 67efc4d3e): PASS, 8 translation units, 0 failures, 0 unjudged (test_actor_filter,test_actor_layout_hook,test_actor_ties,test_audio_output_devices,test_damage_debug_menu,test_input_background). Windows execution not run.Game: not rerun. The earlier runs are of
3a9eeb4f5overmain @ 544229a26. What this rebase changed in lines the game runs: the API number and the host table's slot order (actors_*after main'sperf_tracking), whichtest_audio_output_devicespins by offset and the build above compiled; the layout hook, the host code and the page are the same lines.One docs commit on top of the rebase: the guide check (Guide images and local UI source review) failed after the rebase because source files the Graphics guide image is reviewed against changed, some in this PR and two (
vk_internal.h,vk_reflex.h) already in main's #1309. I rendered the Graphics view from main and from this head and compared them: the only difference is the version text, so the image is kept and its reviewed hashes and dependency list are brought up to date, with a note in the guide's source review file.scripts/check_guide_screenshots.py --review-sourcesnow exits 0 on this head. No code changed.View command line instructions
Checkout
From your project repository, check out a new branch and test the changes.