WIP: feat(menu): turn the people and animals placed in an area off, per area (Debug tab page, !actors, HOS_OOT_ACTORS_OFF) #1426

Draft
mooki wants to merge 6 commits from mooki/Longshot:feat/actor-toggles into main
Member

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 !actors line 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):

  • the Debug tab's page Actors in this area: the families of the area Link is in, how many are placed, how many are tied and stay, On/Off for each, Reload area; the page works while Debug tools is on (its switches wait otherwise, and the log says so);
  • the live input line !actors off|on AREA PATTERN [force], !actors clear [AREA], !actors list [AREA], !actors reload (AREA is a map name as the log's map: line shows it, PATTERN a kind or a family); its answers go to the log;
  • the environment switch HOS_OOT_ACTORS_OFF=AREA:PATTERN[!],..., read when the first layout is read (and from longshot_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):

  • Linked to an event or a door: an actor an event actor links to, or that is linked to or from a door, stays unless the rule says force.
  • The leader of a group of people stays, force or 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.
  • The people of a group that names an event actor stay, force or 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.py patch_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.c hos_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.c and gpu/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:

  • It does not touch actors the game creates while playing (events, shots, the field's enemy spawners): a stalled event is the way this could trap a player.
  • It applies at the next load, not at once.
  • It is local: a co-op room sends nothing about it, and another player still sees what their own game placed.
  • The game's lists of actors created and deleted together keep naming a left-out actor: what the game does with it was not read from its code, only tried (an animal in such a list of 41 actors in the Castle Town market was left out and froze nothing, one run).
  • The rules are kept for the session and are not written to longshot_options.ini: a player must not find the market empty after a restart. HOS_OOT_ACTORS_OFF is 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.

Flag What it is Before this PR After this PR Effect Helps / doesn't help / untested Recommendation
HOS_OOT_ACTORS_OFF rules from the start of the run, AREA:PATTERN[!],... not there unset: no rule turns the matching kinds off in the area at its next load helps a scripted run or a test start with the same empty corner each time; the log names every kind left out unset for players (documented in docs/development.md, and a row of the switch table gpu/vk/switches.def: #1309's rule for a new switch)
Debug tab, Actors in this area (page) the same rules, from the menu not there shown with the other debug tools the families of the area Link is in, On/Off, Reload area drawn and used in the run (pictures below); not tried with a controller on with Debug tools, as the other tools

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 over main @ 544229a26: the game runs and the whole suite are of 3a9eeb4f5, 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.

  • The rebase onto main @ 67efc4d3e (2026-11-17: #1309, #1383, #1378, #1379), old head 7a61b791d, new head e3d67d232. The same changed lines as 7a61b791d except in one commit (the Actors page, 518e007ea, now the 2nd): git range-diff pairs 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 four host->version >= 32 guards and its comment, tests/test_actors_page.py's guard text. (2) The host table: main's perf_tracking (#1383, version 30) now sits before actors_list, actors_set and actors_reload in gpu/vk/vk_api.h, in host/rx_backend.c's prototypes and initializer, and in tests/test_audio_output_devices.py's expected slots and its offset checks (they follow perf_tracking instead of monitor_select). (3) One new row in gpu/vk/switches.def, HOS_OOT_ACTORS_OFF (diag, string): #1309's rule says a new RX_, HOS_ or LONGSHOT_ name read from the environment needs one, and host/oot_actors.c reads 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 of tests/test_actors_page.py and of gpu/vk/vk_api.h), all resolved by keeping both sides, main's perf_tracking first, 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 says MKWVK_API_VERSION 32 where it said 30. No check deleted.
    • Reruns: 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 @ 67efc4d3e with 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's nn_hid.c calls, so it compiles on main too; test_switch_table reads 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_table fails, 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 --strict in the idle gate with a fresh HOME, each commit in its own clean checkout, one after the other: main @ 67efc4d3e 665 passed, 40 failed, 17 skipped in 188 s; this head e3d67d232 670 passed, 39 failed, 17 skipped in 202 s. Failing on main and 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 of main's own failures. test_damage_debug_menu fails on main @ 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.py behind 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's nx2/oot_patches.py is unchanged and nx2/ 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 3a9eeb4f5 over main @ 544229a26. What this rebase changed in lines the game runs: the API number and the host table's slot order (actors_* after main's perf_tracking), which test_audio_output_devices pins by offset and the build above compiled; the layout hook, the host code and the page are the same lines.
  • The new game-free tests, red first. 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 and 0xffffffff, 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.c got a stand-in for the new host function it links, found by the whole suite.
  • The layout reader on real data (local files, not in git). The C reader gave the same actors, links, ties (event, door, leader, event group) and map name as an independent Python reader on 159 of the 160 layouts of the game (the 160th has no Actors list, and is read as none); the lift patch applies to the real lifted code_009.c at exactly the three places.
  • The whole suite, 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 on 7a61b791d: all pass) and (the failing ones only, by name) on git archive of 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 on git archive of main @ 544229a26 the 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.
  • Linux build. A full make_game.py build of this PR's sources exited 0 (the last one compiled in 30 s; the lift of code_009.c changed in the first, so that object and the host files that changed were new, the rest came from the object cache), @@done; the generated code_009.c has the two hooks at f_80c1ba50's head and at its registry call (0x80c1beac). Shaders were prepared in 25 s from a warm cache of the same translator sources.
  • Windows, compiled, not run. The Windows-target syntax check of the changed fixtures on 7a61b791d: PASS (8 translation units, 0 failures; test_input_background among 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.c among 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.
  • In the game, the Castle Town market (from a save in the street, child, day). Eight runs on the lane (several games each, windowless); the first seven found what the tool must keep: with the market's people family off, the game stalled in the load (bisected to the street vendor) and, after that was kept, froze about a minute into play (bisected, by env sets and then one set at a time, to three guards in event groups). The last run (the head, one game) passed: the load line 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 off for 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 clear and !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, no no controller line. Pictures of the same spots, from the build of 3a9eeb4f5, looked at (local files, the game's own; named here, not attached):
Spot Before: this PR @ 3a9eeb4f5, only the env rule on the two rats (no person off) After: this PR @ 3a9eeb4f5, the bird and the people family off
the walk's last place (3.7, 5.9) a man and a red-haired girl talking, a girl in yellow, more people behind (picture 1) none of them; the stall women and a dog (tied) stay (picture 2)
the bird's own place (-1.7, 15.0) rules cleared: a white bird at the right (picture 4) no bird (picture 3)
the Debug tab's page the Actors in this area row and its help (picture 5) the people family's row: 46 placed, 31 tied to an event, a door or a group (stay), 15 left out at the last load, its switch turned back On (picture 6)

1 and 2: the same spot in the market before and after the people family was turned off and the area reloaded; the people who stay are tied to an event or a group
3 and 4: the bird's own spot with its family off, then after the rules were cleared and the area reloaded (the white bird at the right)
5 and 6: the Debug tab with the page's help, and the page itself with the area's families (names as the game's own files have them, read at run time)

Not tested:

  • Windows: no run (above). A controller on the page; other GPUs and the Steam Deck.
  • Any area but the Castle Town market, adult Link, a dungeon, and an area with an AutoPlacement spawner or a catching game's animals (they are tied to an event: the page keeps them, by the tie, not by a run).
  • What a missing person does to a script this tool cannot see in other areas: two stalls were found in the Castle Town market by running it, and the same could be true of an area nobody ran (shop people, guards at other gates, scripted crowds).
  • force (it skips the entries a layout ties by a link): tested game-free only.

Must be tested:

  • Windows, any GPU, by hand or the Test Farm (Windows, the Debug tab's Actors in this area in Castle Town): Debug tools On, the Debug tab's Actors in this area, the people family Off, Reload area, then walk the market for a minute, expecting the page to list the market's families, the load line actors: ... left out in longshot_log.txt, fewer people in the street than before and no frozen frame.
  • Any GPU, by hand, a second area with groups of people (Kakariko Village or the Lon Lon Ranch): turn one family off, Reload area, walk around for a minute, expecting no stuck load, no frozen frame and no person standing in a half state; if one appears, name the kind in the issue (the two group rules above are the place to add it).

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_OFF and leave the page's families On (the default); or revert the commit.

Compatibility: MKWVK_API_VERSION goes from 30 to 32: MkwVkHost gains actors_list, actors_set and actors_reload (after main's perf_tracking, version 30) and a row struct, and the host option ids gain HOS_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, no longshot_options.ini key (rules are not stored), no shader or pipeline cache change (vk_api.h and 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

  • One topic.
  • The title is a Conventional Commit (type(scope): description) of the status line's type.
  • Why gives the reason plainly and links the issues that fit (the tracker searched, said under Issues).
  • Tested on my own PC where it runs (in the game, for a change the game runs), as Testing's Tested says; what
    can't be run by hand is in Testing's Not testable by hand, with why.
  • Measurements has a verdict, or one line saying why there is nothing to measure.
  • Nothing gets worse that I know of: any cost (speed, latency, memory, a setup that worked before) is measured and
    in Risks. Not ticked yet: Risks says a rule can stall the game in other areas, and only Castle Town was checked.
  • Testing names what was tested, what wasn't, and what must still be tested, where and how.
  • Rebased on current main (67efc4d3e, 2026-11-17; the first Testing bullet).
  • python -I -B tests/run_all.py passes (any failure that also fails on main is named): the 40 failures on main @ 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.
  • 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; the README for a menu row) and shipped at their recommended value (unset: no rule). HOS_OOT_ACTORS_OFF also has its row in gpu/vk/switches.def (#1309's rule).
  • Screenshots of the same spot, captioned like the Measurements columns, for a change that shows on screen (the table and pictures under Testing).
  • MKWVK_API_VERSION bumped, 30 to 32 (gpu/vk/vk_api.h's MkwVkHost changed); it renumbers again at merge if another pull request lands first (Compatibility).
  • A game-free test added for the feature, failing before the code and passing here.
  • A check under tests/ that reads changed source updated in this PR, not weakened (test_audio_output_devices, test_damage_debug_menu, test_input_background).
  • Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths (the Windows build compiled, not run).
  • Docs updated.

New on this forge; not opened on GitHub.

**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 `!actors` line 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): - the Debug tab's page **Actors in this area**: the families of the area Link is in, how many are placed, how many are tied and stay, On/Off for each, Reload area; the page works while Debug tools is on (its switches wait otherwise, and the log says so); - the live input line `!actors off|on AREA PATTERN [force]`, `!actors clear [AREA]`, `!actors list [AREA]`, `!actors reload` (AREA is a map name as the log's `map:` line shows it, PATTERN a kind or a family); its answers go to the log; - the environment switch `HOS_OOT_ACTORS_OFF=AREA:PATTERN[!],...`, read when the first layout is read (and from `longshot_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`): - **Linked to an event or a door**: an actor an event actor links to, or that is linked to or from a door, stays unless the rule says `force`. - **The leader of a group of people stays, `force` or 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. - **The people of a group that names an event actor stay, `force` or 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.py` `patch_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.c` `hos_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.c` and `gpu/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: - It does not touch actors the game creates while playing (events, shots, the field's enemy spawners): a stalled event is the way this could trap a player. - It applies at the next load, not at once. - It is local: a co-op room sends nothing about it, and another player still sees what their own game placed. - The game's lists of actors created and deleted together keep naming a left-out actor: what the game does with it was not read from its code, only tried (an animal in such a list of 41 actors in the Castle Town market was left out and froze nothing, one run). - The rules are kept for the session and are not written to `longshot_options.ini`: a player must not find the market empty after a restart. `HOS_OOT_ACTORS_OFF` is 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. | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | `HOS_OOT_ACTORS_OFF` | rules from the start of the run, `AREA:PATTERN[!],...` | not there | unset: no rule | turns the matching kinds off in the area at its next load | helps a scripted run or a test start with the same empty corner each time; the log names every kind left out | unset for players (documented in `docs/development.md`, and a row of the switch table `gpu/vk/switches.def`: #1309's rule for a new switch) | | Debug tab, **Actors in this area** (page) | the same rules, from the menu | not there | shown with the other debug tools | the families of the area Link is in, On/Off, Reload area | drawn and used in the run (pictures below); not tried with a controller | on with Debug tools, as the other tools | ## 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 over `main @ 544229a26`: the game runs and the whole suite are of `3a9eeb4f5`, 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. - **The rebase onto `main @ 67efc4d3e` (2026-11-17: #1309, #1383, #1378, #1379), old head `7a61b791d`, new head `e3d67d232`.** The same changed lines as `7a61b791d` except in one commit (the Actors page, `518e007ea`, now the 2nd): `git range-diff` pairs 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 four `host->version >= 32` guards and its comment, `tests/test_actors_page.py`'s guard text. (2) The host table: main's `perf_tracking` (#1383, version 30) now sits before `actors_list`, `actors_set` and `actors_reload` in `gpu/vk/vk_api.h`, in `host/rx_backend.c`'s prototypes and initializer, and in `tests/test_audio_output_devices.py`'s expected slots and its offset checks (they follow `perf_tracking` instead of `monitor_select`). (3) One new row in `gpu/vk/switches.def`, `HOS_OOT_ACTORS_OFF` (diag, string): #1309's rule says a new `RX_`, `HOS_` or `LONGSHOT_` name read from the environment needs one, and `host/oot_actors.c` reads 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 of `tests/test_actors_page.py` and of `gpu/vk/vk_api.h`), all resolved by keeping both sides, main's `perf_tracking` first, 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 says `MKWVK_API_VERSION 32` where it said 30. No check deleted. - Reruns: 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 @ 67efc4d3e` with 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's `nn_hid.c` calls, so it compiles on main too; `test_switch_table` reads 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_table` fails, 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 --strict` in the idle gate with a fresh HOME, each commit in its own clean checkout, one after the other: `main @ 67efc4d3e` 665 passed, 40 failed, 17 skipped in 188 s; this head `e3d67d232` 670 passed, 39 failed, 17 skipped in 202 s. Failing on `main` and 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 of `main`'s own failures. `test_damage_debug_menu` fails on `main @ 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.py` behind 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's `nx2/oot_patches.py` is unchanged and `nx2/` 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 `3a9eeb4f5` over `main @ 544229a26`. What this rebase changed in lines the game runs: the API number and the host table's slot order (`actors_*` after main's `perf_tracking`), which `test_audio_output_devices` pins by offset and the build above compiled; the layout hook, the host code and the page are the same lines. - **The new game-free tests, red first.** `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 and `0xffffffff`, 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.c` got a stand-in for the new host function it links, found by the whole suite. - **The layout reader on real data (local files, not in git).** The C reader gave the same actors, links, ties (event, door, leader, event group) and map name as an independent Python reader on 159 of the 160 layouts of the game (the 160th has no `Actors` list, and is read as none); the lift patch applies to the real lifted `code_009.c` at exactly the three places. - **The whole suite**, `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 on 7a61b791d: all pass) and (the failing ones only, by name) on `git archive` of 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 on `git archive` of main @ 544229a26 the 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. - **Linux build.** A full `make_game.py` build of this PR's sources exited 0 (the last one compiled in 30 s; the lift of `code_009.c` changed in the first, so that object and the host files that changed were new, the rest came from the object cache), `@@done`; the generated `code_009.c` has the two hooks at `f_80c1ba50`'s head and at its registry call (`0x80c1beac`). Shaders were prepared in 25 s from a warm cache of the same translator sources. - **Windows, compiled, not run.** The Windows-target syntax check of the changed fixtures on 7a61b791d: PASS (8 translation units, 0 failures; `test_input_background` among 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.c` among 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. - **In the game, the Castle Town market (from a save in the street, child, day).** Eight runs on the lane (several games each, windowless); the first seven found what the tool must keep: with the market's people family off, the game stalled in the load (bisected to the street vendor) and, after that was kept, froze about a minute into play (bisected, by env sets and then one set at a time, to three guards in event groups). The last run (the head, one game) passed: the load line `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 off` for 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 clear` and `!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, no `no controller` line. Pictures of the same spots, from the build of 3a9eeb4f5, looked at (local files, the game's own; named here, not attached): | Spot | Before: this PR @ 3a9eeb4f5, only the env rule on the two rats (no person off) | After: this PR @ 3a9eeb4f5, the bird and the people family off | |---|---|---| | the walk's last place (3.7, 5.9) | a man and a red-haired girl talking, a girl in yellow, more people behind (picture 1) | none of them; the stall women and a dog (tied) stay (picture 2) | | the bird's own place (-1.7, 15.0) | rules cleared: a white bird at the right (picture 4) | no bird (picture 3) | | the Debug tab's page | the Actors in this area row and its help (picture 5) | the people family's row: 46 placed, 31 tied to an event, a door or a group (stay), 15 left out at the last load, its switch turned back On (picture 6) | ![1 and 2: the same spot in the market before and after the people family was turned off and the area reloaded; the people who stay are tied to an event or a group](https://git.magicbean.dev/attachments/c7948f60-be9a-4461-853a-86ef6562538d) ![3 and 4: the bird's own spot with its family off, then after the rules were cleared and the area reloaded (the white bird at the right)](https://git.magicbean.dev/attachments/bb1c8971-4596-45f1-9af6-bb2545f465f0) ![5 and 6: the Debug tab with the page's help, and the page itself with the area's families (names as the game's own files have them, read at run time)](https://git.magicbean.dev/attachments/9370bf5f-5e49-4d3e-b8a7-6a2a25c88b69) **Not tested:** - Windows: no run (above). A controller on the page; other GPUs and the Steam Deck. - Any area but the Castle Town market, adult Link, a dungeon, and an area with an AutoPlacement spawner or a catching game's animals (they are tied to an event: the page keeps them, by the tie, not by a run). - What a missing person does to a script this tool cannot see in other areas: two stalls were found in the Castle Town market by running it, and the same could be true of an area nobody ran (shop people, guards at other gates, scripted crowds). - `force` (it skips the entries a layout ties by a link): tested game-free only. **Must be tested:** - Windows, any GPU, by hand or the Test Farm (Windows, the Debug tab's Actors in this area in Castle Town): Debug tools On, the Debug tab's **Actors in this area**, the people family Off, Reload area, then walk the market for a minute, expecting the page to list the market's families, the load line `actors: ... left out` in `longshot_log.txt`, fewer people in the street than before and no frozen frame. - Any GPU, by hand, a second area with groups of people (Kakariko Village or the Lon Lon Ranch): turn one family off, Reload area, walk around for a minute, expecting no stuck load, no frozen frame and no person standing in a half state; if one appears, name the kind in the issue (the two group rules above are the place to add it). ## 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_OFF` and leave the page's families On (the default); or revert the commit. **Compatibility:** `MKWVK_API_VERSION` goes from 30 to 32: `MkwVkHost` gains `actors_list`, `actors_set` and `actors_reload` (after main's `perf_tracking`, version 30) and a row struct, and the host option ids gain `HOS_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, no `longshot_options.ini` key (rules are not stored), no shader or pipeline cache change (`vk_api.h` and 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 - [x] One topic. - [x] The title is a Conventional Commit (`type(scope): description`) of the status line's type. - [x] Why gives the reason plainly and links the issues that fit (the tracker searched, said under Issues). - [x] Tested on my own PC where it runs (in the game, for a change the game runs), as Testing's Tested says; what can't be run by hand is in Testing's Not testable by hand, with why. - [x] Measurements has a verdict, or one line saying why there is nothing to measure. - [ ] Nothing gets worse that I know of: any cost (speed, latency, memory, a setup that worked before) is measured and in Risks. Not ticked yet: Risks says a rule can stall the game in other areas, and only Castle Town was checked. - [x] Testing names what was tested, what wasn't, and what must still be tested, where and how. - [x] Rebased on current `main` (67efc4d3e, 2026-11-17; the first Testing bullet). - [x] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named): the 40 failures on `main @ 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. - [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; the README for a menu row) and shipped at their recommended value (unset: no rule). `HOS_OOT_ACTORS_OFF` also has its row in `gpu/vk/switches.def` (#1309's rule). - [x] Screenshots of the same spot, captioned like the Measurements columns, for a change that shows on screen (the table and pictures under Testing). - [x] `MKWVK_API_VERSION` bumped, 30 to 32 (`gpu/vk/vk_api.h`'s `MkwVkHost` changed); it renumbers again at merge if another pull request lands first (Compatibility). - [x] A game-free test added for the feature, failing before the code and passing here. - [x] A check under `tests/` that reads changed source updated in this PR, not weakened (`test_audio_output_devices`, `test_damage_debug_menu`, `test_input_background`). - [x] Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths (the Windows build compiled, not run). - [x] Docs updated. New on this forge; not opened on GitHub.
The pure part of turning actors off per area, with its game-free tests (the tests were written first and failed
without the headers):

- host/oot_actor_filter.h: the rules (an area, a pattern, on or off; the last matching rule decides; a menu rule
  waits for the Debug tools, an explicit one does not), the kinds the tool never offers (anything that is not a
  person, an animal, an enemy, a breakable or an effect, and any that names a door, a lock, a chest, an event, an
  anchor, an area, a shop, a boss or the player), the family of a kind, the per-area counts and the Actors page's
  rows, the live command's parse and the environment switch's.
- host/oot_byml.h: a read-only, bounds-checked view of a BYML file as it lies in memory.
- host/oot_actor_ties.h: reads a layout's entries and links and marks the ones an event links to, or that are
  linked to or from a door, which the filter keeps unless forced.
- tests/test_actor_filter.py, tests/test_actor_ties.py: the rules, refusals, counts, commands and environment
  parse; the reader on layouts built from invented actors, every cut of the file and every changed byte of it.

Assisted-by: Claude Sonnet 5.5
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
The game places a map's actors from its two layout files and registers each entry with its actor registry as the
layout loads. An entry the registry cannot make gets the answer 0 and the id 0xffffffff, and the layout reader
already 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.

- nx2/oot_patches.py: patch_actor_layout hooks the layout reader (f_80c1ba50) at its head and its one registry call
  (f_83b072b0); both or neither, the registry's other callers (creation by name) are left.
- host/oot_actors.c: the layout's file is read once for its links as the first entry is registered, and every
  entry is checked against it (hash and kind together) before anything is left out; a layout it cannot read whole
  is counted and left alone. Counts per area, a summary line a second after a load, the page's list and switch,
  the live command and the environment switch.
- host/nn_hid.c: the live input file's `!actors off|on|clear|list|reload`; HOS_OOT_ACTORS_OFF=<area>:<pattern>[!],...
- host/hos_main.c: `hos_oot_reload_area`, the Teleport list's map change to the map the game is in, asked as the
  control bridge asks.
- gpu/vk/vk_api.h: MKWVK_API_VERSION 30, MkwVkActorRow, actors_list / actors_set / actors_reload and
  HOS_OPT_CHEAT_ACTORS; host/rx_backend.c fills them.
- gpu/vk/vk_menu.cpp: the Debug tab's "Actors in this area" page (families, counts, Off and On, Reload area).
- tests/test_actor_layout_hook.py (the patch on text shaped as the lift writes it, and the glue compiled over a made-up
  guest memory), tests/test_actors_page.py, tests/test_audio_output_devices.py (the new slots),
  tests/test_damage_debug_menu.py (the Debug tab's order; it also compiles again), tests/input_background_test.c (a stand-in
  for the live command's handler: the fixture compiles nn_hid.c's live input).
- docs/development.md and README.md.

Assisted-by: Claude Sonnet 5.5
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
A run in Castle Town with the Hylia people and the cucco left out never finished loading (a black screen, the game's main thread
running one frame in many seconds). Bisected by game runs: the cucco, the people in no group and the soldiers, Malon and Talon were
each fine, and so were six of the seven group-only people; one kind alone, Npc_Hylia_035_Child, stopped the load. It is the first
reference of an AiGroup (Market_Child_Prefab_c602, an ActorLogicNpcStreetVendor module whose other references are its customers and
areas), and the one person the others in that module depend on.

The layout reader now also reads the Static layout's AiGroups: the first reference of a group that has another person or animal
among its references is marked OAF_TIE_LEADER. A leader stays whatever the rule says, force included (a forced rule still skips the
entries tied to an event or a door). It keeps more than the one case proves (154 leaders in 46 areas, six entries in Castle Town:
the people 035 and 059, the two street vendors, Hylia_002 and Soldier_007, a dog and the gold skulltula); the log and the page count them as tied.

- host/oot_actor_filter.h: OAF_TIE_LEADER; oaf_wants_skip never forces a leader out.
- host/oot_actor_ties.h: the AiGroups pass; an AiGroups, References or group that is not what the reader expects refuses the layout whole.
- tests/test_actor_ties.py (a layout with seven groups: leader, no other person, alone, a prop first, an unknown first reference, an
  animal first, no References; AiGroups not an array; every cut and changed byte of that file), tests/test_actor_filter.py (a leader is
  not forced out), tests/test_actors_page.py (the words: tied to an event, a door or a group).
- gpu/vk/vk_menu.cpp, gpu/vk/vk_api.h, README.md, docs/development.md: the words and the group's leader.

Assisted-by: Claude Sonnet 5.5
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Castle Town's guards (Npc_Hylia_Soldier_005, _006, _008) each sit in an AiGroup with two EventRequestActors and an area. Leaving one out
froze the game's logic about a minute into play, when Link walked past that area and its event asked for the guard (one game frame took
seconds, the screen stood still). A guard whose group has no event, the cucco, the people in no group, Malon, Talon and the customers of
the street vendors did not freeze anything (bisected in the game, one run each).

host/oot_actor_ties.h reads the References of each AiGroup twice: when any reference is an event actor, every person and animal the tool
offers among them gets OAF_TIE_ASKED. host/oot_actor_filter.h never forces out an entry with OAF_TIE_LEADER or OAF_TIE_ASKED
(OAF_TIE_NEVER_FORCED). Tests first: tests/test_actor_ties.py (a group with an area first, a person, an event, a person; the guard
group) and tests/test_actor_filter.py (asked stays when forced) failed before the code.

Assisted-by: Claude Sonnet 5.5
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
chore(tests): no names read from the game's files in the tests, comments and docs
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 10s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 17s
CI / Workflow lint (actionlint) (pull_request) Successful in 19s
Website / Website on Cloudflare (pull_request_target) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 10s
Third-party parts / As their notes say (pull_request) Successful in 27s
7a61b791d3
The tests, the code comments, docs/development.md, README.md and gpu/vk/vk_api.h named the game's own areas and actors (the layout
fixtures, the never-offered list, the examples, the vendor and the guards of the Castle Town market). They now use made-up names that
follow the same shapes (Town_Child, Npc_Town_002_Child, Animal_Test_Meadow, Obj_Test_Door_09, ...), and the vendor and guard cases are
described in words. The prefixes and the words the code needs stay in host/oot_actor_filter.h, in one place, with a comment that the kinds
the page shows are read from the player's own files at run time.

test_actor_filter checks every word of the never-offered list against a made-up kind that carries it, and the list's length, instead of
naming the owl. No product logic changes. Mutations still fail the tests (no leader tie, no event-group tie, forced asked or leader, a
dropped word or prefix).

Assisted-by: Claude Sonnet 5.5
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
mooki changed title from 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) 2026-11-17 14:49:02 +00:00
mooki force-pushed feat/actor-toggles from 7a61b791d3
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 10s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 17s
CI / Workflow lint (actionlint) (pull_request) Successful in 19s
Website / Website on Cloudflare (pull_request_target) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 10s
Third-party parts / As their notes say (pull_request) Successful in 27s
to e3d67d2320
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 10s
PR description / Description follows the template (pull_request_target) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Successful in 14s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 15s
Third-party parts / As their notes say (pull_request) Successful in 19s
2026-11-17 16:51:44 +00:00
Compare
Author
Member

Rebased 7a61b791d onto main 67efc4d3e; new head e3d67d232.
Patch: the same changed lines as 7a61b791d except in one commit (the Actors page, 518e007ea, now the 2nd): git range-diff pairs 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 four host->version >= 32 guards and its comment, tests/test_actors_page.py's guard text. (2) The host table: main's perf_tracking (#1383, version 30) now sits before actors_list, actors_set and actors_reload in gpu/vk/vk_api.h, in host/rx_backend.c's prototypes and initializer, and in tests/test_audio_output_devices.py's expected slots and its offset checks (they follow perf_tracking instead of monitor_select). (3) One new row in gpu/vk/switches.def, HOS_OOT_ACTORS_OFF (diag, string): #1309's rule says a new RX_, HOS_ or LONGSHOT_ name read from the environment needs one, and host/oot_actors.c reads 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 of tests/test_actors_page.py and of gpu/vk/vk_api.h), all resolved by keeping both sides, main's perf_tracking first, 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 says MKWVK_API_VERSION 32 where it said 30. No check deleted.
Carried: the earlier results are of 3a9eeb4f5 and 7a61b791d over main @ 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, at 3a9eeb4f5, 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 @ 67efc4d3e with 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's nn_hid.c calls, so it compiles on main too; test_switch_table reads 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_table fails, 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 --strict in the idle gate with a fresh HOME, each commit in its own clean checkout, one after the other: main @ 67efc4d3e 665 passed, 40 failed, 17 skipped in 188 s; this head e3d67d232 670 passed, 39 failed, 17 skipped in 202 s. Failing on main and 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 of main's own failures. test_damage_debug_menu fails on main @ 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.py behind 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's nx2/oot_patches.py is unchanged and nx2/ 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 3a9eeb4f5 over main @ 544229a26. What this rebase changed in lines the game runs: the API number and the host table's slot order (actors_* after main's perf_tracking), which test_audio_output_devices pins by offset and the build above compiled; the layout hook, the host code and the page are the same lines.

Rebased `7a61b791d` onto main `67efc4d3e`; new head `e3d67d232`. Patch: the same changed lines as `7a61b791d` except in one commit (the Actors page, `518e007ea`, now the 2nd): `git range-diff` pairs 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 four `host->version >= 32` guards and its comment, `tests/test_actors_page.py`'s guard text. (2) The host table: main's `perf_tracking` (#1383, version 30) now sits before `actors_list`, `actors_set` and `actors_reload` in `gpu/vk/vk_api.h`, in `host/rx_backend.c`'s prototypes and initializer, and in `tests/test_audio_output_devices.py`'s expected slots and its offset checks (they follow `perf_tracking` instead of `monitor_select`). (3) One new row in `gpu/vk/switches.def`, `HOS_OOT_ACTORS_OFF` (diag, string): #1309's rule says a new `RX_`, `HOS_` or `LONGSHOT_` name read from the environment needs one, and `host/oot_actors.c` reads 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 of `tests/test_actors_page.py` and of `gpu/vk/vk_api.h`), all resolved by keeping both sides, main's `perf_tracking` first, 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 says `MKWVK_API_VERSION 32` where it said 30. No check deleted. Carried: the earlier results are of `3a9eeb4f5` and `7a61b791d` over `main @ 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, at `3a9eeb4f5`, 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 @ 67efc4d3e` with 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's `nn_hid.c` calls, so it compiles on main too; `test_switch_table` reads 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_table` fails, 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 --strict` in the idle gate with a fresh HOME, each commit in its own clean checkout, one after the other: `main @ 67efc4d3e` 665 passed, 40 failed, 17 skipped in 188 s; this head `e3d67d232` 670 passed, 39 failed, 17 skipped in 202 s. Failing on `main` and 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 of `main`'s own failures. `test_damage_debug_menu` fails on `main @ 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.py` behind 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's `nx2/oot_patches.py` is unchanged and `nx2/` 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 `3a9eeb4f5` over `main @ 544229a26`. What this rebase changed in lines the game runs: the API number and the host table's slot order (`actors_*` after main's `perf_tracking`), which `test_audio_output_devices` pins by offset and the build above compiled; the layout hook, the host code and the page are the same lines.
docs(guide): the Graphics guide image is retained after the Debug tab's Actors page and main's switch table
All checks were successful
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 7s
CI / Workflow lint (actionlint) (pull_request) Successful in 14s
Guide screenshots / Guide images and local UI source review (pull_request) Successful in 15s
Third-party parts / As their notes say (pull_request) Successful in 22s
PR description / Description follows the template (pull_request_target) Successful in 3s
4221dd0976
scripts/check_guide_screenshots.py --review-sources failed on the head: the recorded inputs vk_api.h, vk_menu.cpp (and, by this PR or by main's #1309, the others it names)
changed. The maintained helper rendered the Graphics view from main 67efc4d3e and from this head: the two renderings differ only in the
version text, so the image is retained and not recaptured. manifest.json: the reviewed hashes of settings-graphics.png advance and the
dependency list gains the headers the helper's compiler pass now finds (device_policy.h and what it includes, and this PR's own new
headers); source-review-fullscreen-monitor.md records the review. The PNG, its capture revision and the fixture are unchanged.

Assisted-by: Claude Sonnet 5.5
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Author
Member

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-sources now exits 0 on this head. No code changed.

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-sources` now exits 0 on this head. No code changed.
Owner

Brought up to the ready-for-review standard (#1454): the checklist's Everyone list has two new boxes, added here from what this PR's description and comments show (please check they match what you know).

  • Tested on my own PC: ticked: Testing's Tested names game runs on Linux with an RTX 4090, though those runs are on an earlier head, not the rebased one.
  • Nothing gets worse that I know of: not ticked: Risks says a rule can stall the game in other areas, and only Castle Town was checked. Measure that cost and state it in Risks, then tick it.
Brought up to the [ready-for-review standard](https://git.magicbean.dev/MagicBeanDev/Longshot/src/branch/main/CONTRIBUTING.md#ready-for-review-out-of-wip) (#1454): the checklist's Everyone list has two new boxes, added here from what this PR's description and comments show (please check they match what you know). - *Tested on my own PC*: ticked: Testing's Tested names game runs on Linux with an RTX 4090, though those runs are on an earlier head, not the rebased one. - *Nothing gets worse that I know of*: not ticked: Risks says a rule can stall the game in other areas, and only Castle Town was checked. Measure that cost and state it in Risks, then tick it.
mooki changed title from feat(menu): turn the people and animals placed in an area off, per area (Debug tab page, !actors, HOS_OOT_ACTORS_OFF) to WIP: feat(menu): turn the people and animals placed in an area off, per area (Debug tab page, !actors, HOS_OOT_ACTORS_OFF) 2026-11-17 20:51:47 +00:00
Author
Member

Thank you for adding the two boxes; they match what I know. Under the ready-for-review list (#1454) I have moved this back to WIP until one cost is measured and named in Risks: a rule's cost in areas other than Castle Town. I will tick the box and mark it ready again when that number is in.

Thank you for adding the two boxes; they match what I know. Under the ready-for-review list (#1454) I have moved this back to WIP until one cost is measured and named in Risks: a rule's cost in areas other than Castle Town. I will tick the box and mark it ready again when that number is in.
All checks were successful
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 7s
CI / Workflow lint (actionlint) (pull_request) Successful in 14s
Guide screenshots / Guide images and local UI source review (pull_request) Successful in 15s
Third-party parts / As their notes say (pull_request) Successful in 22s
PR description / Description follows the template (pull_request_target) Successful in 3s
This pull request has changes conflicting with the target branch.
  • docs/images/guide/manifest.json
  • docs/images/guide/source-review-fullscreen-monitor.md
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/actor-toggles:mooki-feat/actor-toggles'
git switch 'mooki-feat/actor-toggles'
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!1426
No description provided.