WIP: feat(lift): hook sites, named places in the game's code the host steps in, compiled into the translated game; Text speed and size the first #1821

Draft
dyst wants to merge 9 commits from dyst/Longshot:feat/hook-sites into main
Member

Type: feat · Risk: low · Tested on: Windows 11, RTX 3080, Ryzen 9 3900X · Needs: a run on Linux

TL;DR

The first piece of the Modding API's core: hook sites. A site is a named place in the game's code, found by the instruction words around it, where the host can step in; the lift compiles each one into the translated game as a check of one byte, so a site nothing uses costs a load and a predicted branch, and its function keeps its fast local registers. Text speed and Text size, which were a text patch on the translated C, are the first users: their patch is deleted, and the game behaves as before. The translation changes in exactly one function.

Breakdown

  • Who it helps: everyone changing the engine's game-code features, and mods later: a feature hooks a named site instead of editing the translated C by its text.
  • What was wrong: the engine's features were about forty text patches on the lifted C (nx2/oot_patches.py), found by exact text that any change to the translator can break, with no list of what they touch.
  • What changes: sites as data, the resolver, what a site compiles to, the host's handler table; Text speed and Text size moved onto the site textStep, their text patch deleted.
  • What does not change: what the player sees; every other function of the translation.
  • How it was checked: new game-free tests with teeth; the whole translation compared byte for byte at each step; tests/run_all.py against main; a run in the game.
  • What is still open: a run on Linux.
  • Risk: low: one function of the translation changes, and the game ran.

Why

The Modding API Spec (wiki, Modding-API-Spec, section 8.1) and its plan (Modding-API-Plan, milestone M2, pieces 1 and 2) start the core with the hook compiler: named sites, compiled into the lifted code and always present, which the engine's own features use first and mods later. Text speed is the plan's first conversion (small and serial). Relates to #1097 (the text patches have no list of their addresses). The plan's gate 1 (the translation unchanged with a site table present and empty) is #1798's tool.

Stacked on #1587 (and #1560 under it), whose head hook point the entry sites use.

What changed

A site table, a resolver and a compiler of sites into the lifted code, the host's side of it, and the first feature moved onto a site.

  • nx2/hooks.py (new): the site table of a game build (nx2/sites/<build id>.toml; the next PR makes it a file a site); a site's signature must match exactly once in its module, at the address given, or the lift stops naming every bad site. An "after" site runs once its instruction falls through (not at a branch that never does); an "entry" site is the first thing its function does, and its handler may finish the function. What a site compiles to: if (hos_sites[n]) hos_site_call(c, n). Inside that branch the function's local registers that changed since the last sync are written back before the call and read again after it, so a site keeps its function's locals and a dormant one touches only its byte. The lift counts every site it writes and stops on one written into no function. a64_sites.c names the lift's sites and holds their bytes. python -I nx2/hooks.py <exefs> resolves the sites without lifting.
  • nx2/emit.py: C spliced after an instruction that is not an op (a conditional branch, a call) where it falls through; the sites' own table, Lifter.site_after, with the instruction's sync marks (tagged lines). nx2/chunks.py sends the site tables to the emit's worker processes. nx2/lift.py, nx2/make_game.py (.toml in the lift's sources), nx2/build.py (a64_sites.c).
  • host/hook_sites.c, host/hook_sites.h (new): handlers attached by a site's name, called in order until one says the function is done; a site's byte set while it has a handler.
  • host/oot_text_step.c (new): Text speed and Text size's handler on textStep, after the letter count's check in f_80b1e140 (a text pane's LetterAnimControl step). nx2/oot_patches.py: the Text speed text patch deleted.
  • From a cold review (6eeedb76): the site's call of the host is declared A64_NOESC, as every call lifted code makes (without it the call captures the context in the whole function, its dormant path too: a64-kit's a64.h); an after site runs every handler, an entry site stops at the first that did the function's work (a64_site_entry); BLRAA and BLRAB are calls, not branches away; a signature is found by an exact anchor word, not a regex at every byte; a lift with more sites than the host's table holds stops; host/hook_sites.h says what a handler may rely on.
  • Tests: tests/test_hook_sites.py (new), tests/test_text_speed.py rewritten, tests/test_text_size.py.

Measurements

Verdict: not measured in frames: the translation changes in one function, f_80b1e140, which now keeps its local registers (it kept them in the context before, for the text patch), and a dormant site costs a byte load and a predicted branch. A timed run of dormant sites in hot functions is planned with the next pieces.

Baseline: #1587's head, which this PR is stacked on: main differs from it by #1560 and #1587, which have their own comparisons with main (byte for byte the same).
Hardware: Windows 11 Pro N (build 22631), RTX 3080, Ryzen 9 3900X, 64 GB
Scene: none: the translation, game-free (the in-game run is in Testing)
Method: scripts/lift_parity.py lift (#1798) of each commit, rc.8's ExeFS, the Builder's Python and llvm-mingw, then compare
How to reproduce: python -I scripts/lift_parity.py lift --checkout <a checkout> for #1587's head and for this branch, then python -I scripts/lift_parity.py compare <one> <the other>

Before: #1587 @ ab68fc1a After: this PR @ 6eeedb76
files the lift wrote 91 (1.73 GB) 89 the same, a64_sites.c new, the chunk cost estimates
functions that differ 1 of 2,994 in its file: f_80b1e140 (the patch's two lines replaced by the site; its locals kept), at every step: the conversion, the locals, the review's fixes
with a site table present and no site in it (414ca471) the same as before: every file

After the rebase onto main 0de25c3e (which brought #134's ExeFS patches, #1740's text patch and #1774's menu modules), lifted again:

Before: main @ 0de25c3e After: #1587 @ 725cc27a
files the lift wrote 91 (1.73 GB) 91, the same
Before: #1587 @ 725cc27a After: #1822 @ 957a28b8 (this PR with the feature modules on top)
files the lift wrote 91 (1.73 GB) 89 the same, a64_sites.c new, the chunk cost estimates
functions that differ 1 of 2,994 in its file: f_80b1e140

This PR's own head was not lifted again after the rebase: its translation lies between those two (the site's byte by number here, by name in #1822).

Flags and settings

None.

Testing

Tested:

  • tests/test_hook_sites.py (new): the table's format and 16 kinds of mistake; the resolver over made-up code; install; a made-up function emitted through the lift's own emitter with an entry and an after site (the locals kept, a dormant site touching only its byte, the write-back and the reads after the handler, a patch and a site on one instruction, a stand-in run gatherer); that function compiled and run, dormant and with a handler; the host's handler table compiled and run. Seven deliberate breaks of the site's code, each caught.

  • tests/test_text_speed.py, tests/test_text_size.py, tests/test_spawn_emit.py, tests/test_lift_emit.py, tests/test_menu_hooks.py, tests/test_entry_below_locals.py pass.

  • The whole translation compared byte for byte (#1798) at each commit: #1587's head against a table present and empty, the same; the conversion of Text speed, its one function named; the site keeping its function's locals, the same one function; the review's fixes, the same one function and a64_sites.c.

  • python -I -B tests/run_all.py (the Builder's llvm-mingw first on PATH, LONGSHOT_MINGW set), on main 0de25c3e: 706 passed / 45 failed at 4cdd901d. The one failing here only, tests/test_a64_helper_build_flags.py (#756's: its stand-in lift folder lacked a64_sites.c), is fixed in the commit that adds the file and passes; the other 44 fail on main 0de25c3e too, rerun there.

  • A cold review of the branch by a second agent (code read, nothing run); its findings fixed in 6eeedb76, each with a test, and every test mutation it listed as uncaught now caught.

  • In the game (Windows 11, RTX 3080, Ryzen 9 3900X), by the person I work for: a pack of the next PR's branch at 95fbe486 (this branch at ada6d3fc with the feature modules on top; their translations byte for byte the same) over main 47430e81's base, with #1729's header fix applied for the build only; the repository's kokiri-start save, Kokiri Forest's signs and dialogue. Text speed: Normal types the letters out, the fastest setting shows each page at once. Text size: larger, as before, including #1779's first showing at the default size, which main has too.

  • Rebased onto main 0de25c3e: the conflicts were the menu rows' reader (#1774's menu_text()) and an import of tests/test_text_size.py; the checks of the files it touches pass; the comparisons and run_all above are on it.

Not tested: Linux. In the game, this branch's last commit (6eeedb76, the review's fixes: the site's call declared A64_NOESC, an after site running every handler): its translation differs from ada6d3fc's in f_80b1e140 alone (the declaration) and in a64_sites.c (the sites' kinds), and its host code is covered by tests/test_hook_sites.py's compiled runs.

Must be tested:

  • Linux, any PC with the game: a lift of this branch compared with #1587's (#1798's tool), expecting one function to differ, f_80b1e140; and Text speed in a dialogue, expecting the letters faster (by hand, or the Test Farm on a Linux machine).

Risks

What could break: Text speed and Text size, whose code moved (the in-game run covers both); a site whose signature stops matching after a game update stops the lift with the site named, by design.

Turning it off: revert; a site with no handler costs a byte load.

Compatibility: nx2/sites/ is part of the lift's sources, so the translation is made again once.

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).
  • 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.
  • Testing names what was tested, what wasn't, and what must still be tested, where and how.
  • Rebased on current main.
  • python -I -B tests/run_all.py passes (any failure that also fails on main is named).
  • 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.
  • A check under tests/ that reads changed source updated in this PR, not weakened.
  • Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. (Windows built and run; Linux not built here: Must be tested)
  • Docs updated.

🤖 Generated with Claude Code

**Type:** feat · **Risk:** low · **Tested on:** Windows 11, RTX 3080, Ryzen 9 3900X · **Needs:** a run on Linux ## TL;DR The first piece of the Modding API's core: hook sites. A site is a named place in the game's code, found by the instruction words around it, where the host can step in; the lift compiles each one into the translated game as a check of one byte, so a site nothing uses costs a load and a predicted branch, and its function keeps its fast local registers. Text speed and Text size, which were a text patch on the translated C, are the first users: their patch is deleted, and the game behaves as before. The translation changes in exactly one function. ## Breakdown - **Who it helps:** everyone changing the engine's game-code features, and mods later: a feature hooks a named site instead of editing the translated C by its text. - **What was wrong:** the engine's features were about forty text patches on the lifted C (`nx2/oot_patches.py`), found by exact text that any change to the translator can break, with no list of what they touch. - **What changes:** sites as data, the resolver, what a site compiles to, the host's handler table; Text speed and Text size moved onto the site `textStep`, their text patch deleted. - **What does not change:** what the player sees; every other function of the translation. - **How it was checked:** new game-free tests with teeth; the whole translation compared byte for byte at each step; `tests/run_all.py` against main; a run in the game. - **What is still open:** a run on Linux. - **Risk:** low: one function of the translation changes, and the game ran. ## Why The Modding API Spec (wiki, Modding-API-Spec, section 8.1) and its plan (Modding-API-Plan, milestone M2, pieces 1 and 2) start the core with the hook compiler: named sites, compiled into the lifted code and always present, which the engine's own features use first and mods later. Text speed is the plan's first conversion (small and serial). Relates to #1097 (the text patches have no list of their addresses). The plan's gate 1 (the translation unchanged with a site table present and empty) is #1798's tool. Stacked on #1587 (and #1560 under it), whose head hook point the entry sites use. ## What changed A site table, a resolver and a compiler of sites into the lifted code, the host's side of it, and the first feature moved onto a site. - `nx2/hooks.py` (new): the site table of a game build (`nx2/sites/<build id>.toml`; the next PR makes it a file a site); a site's signature must match exactly once in its module, at the address given, or the lift stops naming every bad site. An "after" site runs once its instruction falls through (not at a branch that never does); an "entry" site is the first thing its function does, and its handler may finish the function. What a site compiles to: `if (hos_sites[n]) hos_site_call(c, n)`. Inside that branch the function's local registers that changed since the last sync are written back before the call and read again after it, so a site keeps its function's locals and a dormant one touches only its byte. The lift counts every site it writes and stops on one written into no function. `a64_sites.c` names the lift's sites and holds their bytes. `python -I nx2/hooks.py <exefs>` resolves the sites without lifting. - `nx2/emit.py`: C spliced after an instruction that is not an op (a conditional branch, a call) where it falls through; the sites' own table, `Lifter.site_after`, with the instruction's sync marks (tagged lines). `nx2/chunks.py` sends the site tables to the emit's worker processes. `nx2/lift.py`, `nx2/make_game.py` (`.toml` in the lift's sources), `nx2/build.py` (`a64_sites.c`). - `host/hook_sites.c`, `host/hook_sites.h` (new): handlers attached by a site's name, called in order until one says the function is done; a site's byte set while it has a handler. - `host/oot_text_step.c` (new): Text speed and Text size's handler on `textStep`, after the letter count's check in `f_80b1e140` (a text pane's LetterAnimControl step). `nx2/oot_patches.py`: the Text speed text patch deleted. - From a cold review (6eeedb76): the site's call of the host is declared `A64_NOESC`, as every call lifted code makes (without it the call captures the context in the whole function, its dormant path too: a64-kit's `a64.h`); an after site runs every handler, an entry site stops at the first that did the function's work (`a64_site_entry`); `BLRAA` and `BLRAB` are calls, not branches away; a signature is found by an exact anchor word, not a regex at every byte; a lift with more sites than the host's table holds stops; `host/hook_sites.h` says what a handler may rely on. - Tests: `tests/test_hook_sites.py` (new), `tests/test_text_speed.py` rewritten, `tests/test_text_size.py`. ## Measurements **Verdict:** not measured in frames: the translation changes in one function, `f_80b1e140`, which now keeps its local registers (it kept them in the context before, for the text patch), and a dormant site costs a byte load and a predicted branch. A timed run of dormant sites in hot functions is planned with the next pieces. Baseline: #1587's head, which this PR is stacked on: main differs from it by #1560 and #1587, which have their own comparisons with main (byte for byte the same). Hardware: Windows 11 Pro N (build 22631), RTX 3080, Ryzen 9 3900X, 64 GB Scene: none: the translation, game-free (the in-game run is in Testing) Method: `scripts/lift_parity.py lift` (#1798) of each commit, rc.8's ExeFS, the Builder's Python and llvm-mingw, then `compare` How to reproduce: `python -I scripts/lift_parity.py lift --checkout <a checkout>` for #1587's head and for this branch, then `python -I scripts/lift_parity.py compare <one> <the other>` | | Before: #1587 @ ab68fc1a | After: this PR @ 6eeedb76 | |---|---|---| | files the lift wrote | 91 (1.73 GB) | 89 the same, `a64_sites.c` new, the chunk cost estimates | | functions that differ | | 1 of 2,994 in its file: `f_80b1e140` (the patch's two lines replaced by the site; its locals kept), at every step: the conversion, the locals, the review's fixes | | with a site table present and no site in it (414ca471) | | the same as before: every file | After the rebase onto main 0de25c3e (which brought #134's ExeFS patches, #1740's text patch and #1774's menu modules), lifted again: | | Before: main @ 0de25c3e | After: #1587 @ 725cc27a | |---|---|---| | files the lift wrote | 91 (1.73 GB) | 91, the same | | | Before: #1587 @ 725cc27a | After: #1822 @ 957a28b8 (this PR with the feature modules on top) | |---|---|---| | files the lift wrote | 91 (1.73 GB) | 89 the same, `a64_sites.c` new, the chunk cost estimates | | functions that differ | | 1 of 2,994 in its file: `f_80b1e140` | This PR's own head was not lifted again after the rebase: its translation lies between those two (the site's byte by number here, by name in #1822). ### Flags and settings None. ## Testing **Tested:** - `tests/test_hook_sites.py` (new): the table's format and 16 kinds of mistake; the resolver over made-up code; install; a made-up function emitted through the lift's own emitter with an entry and an after site (the locals kept, a dormant site touching only its byte, the write-back and the reads after the handler, a patch and a site on one instruction, a stand-in run gatherer); that function compiled and run, dormant and with a handler; the host's handler table compiled and run. Seven deliberate breaks of the site's code, each caught. - `tests/test_text_speed.py`, `tests/test_text_size.py`, `tests/test_spawn_emit.py`, `tests/test_lift_emit.py`, `tests/test_menu_hooks.py`, `tests/test_entry_below_locals.py` pass. - The whole translation compared byte for byte (#1798) at each commit: #1587's head against a table present and empty, the same; the conversion of Text speed, its one function named; the site keeping its function's locals, the same one function; the review's fixes, the same one function and `a64_sites.c`. - `python -I -B tests/run_all.py` (the Builder's llvm-mingw first on `PATH`, `LONGSHOT_MINGW` set), on main 0de25c3e: 706 passed / 45 failed at 4cdd901d. The one failing here only, `tests/test_a64_helper_build_flags.py` (#756's: its stand-in lift folder lacked `a64_sites.c`), is fixed in the commit that adds the file and passes; the other 44 fail on main 0de25c3e too, rerun there. - A cold review of the branch by a second agent (code read, nothing run); its findings fixed in 6eeedb76, each with a test, and every test mutation it listed as uncaught now caught. - In the game (Windows 11, RTX 3080, Ryzen 9 3900X), by the person I work for: a pack of the next PR's branch at 95fbe486 (this branch at ada6d3fc with the feature modules on top; their translations byte for byte the same) over main 47430e81's base, with #1729's header fix applied for the build only; the repository's `kokiri-start` save, Kokiri Forest's signs and dialogue. Text speed: Normal types the letters out, the fastest setting shows each page at once. Text size: larger, as before, including #1779's first showing at the default size, which main has too. - Rebased onto main 0de25c3e: the conflicts were the menu rows' reader (#1774's `menu_text()`) and an import of `tests/test_text_size.py`; the checks of the files it touches pass; the comparisons and `run_all` above are on it. **Not tested:** Linux. In the game, this branch's last commit (6eeedb76, the review's fixes: the site's call declared `A64_NOESC`, an after site running every handler): its translation differs from ada6d3fc's in `f_80b1e140` alone (the declaration) and in `a64_sites.c` (the sites' kinds), and its host code is covered by `tests/test_hook_sites.py`'s compiled runs. **Must be tested:** - Linux, any PC with the game: a lift of this branch compared with #1587's (#1798's tool), expecting one function to differ, `f_80b1e140`; and Text speed in a dialogue, expecting the letters faster (by hand, or the Test Farm on a Linux machine). ## Risks **What could break:** Text speed and Text size, whose code moved (the in-game run covers both); a site whose signature stops matching after a game update stops the lift with the site named, by design. **Turning it off:** revert; a site with no handler costs a byte load. **Compatibility:** `nx2/sites/` is part of the lift's sources, so the translation is made again once. ## 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). - [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. - [x] Nothing gets worse that I know of: any cost (speed, latency, memory, a setup that worked before) is measured and in Risks. - [x] Testing names what was tested, what wasn't, and what must still be tested, where and how. - [x] Rebased on current `main`. - [x] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named). - [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] A check under `tests/` that reads changed source updated in this PR, not weakened. - [ ] Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. (Windows built and run; Linux not built here: Must be tested) - [x] Docs updated. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Longshot adds to a64-kit's Lifter.emit_function in four places: fastfp's runs of float
instructions, lift_fixes' entry label and goto, entry_hooks' call and poll's interrupt
polls. Each replaced or wrapped the method when nx2/lift.py imported it (fastfp with a
151-line copy), so what the lift wrote depended on the order of those imports.

nx2/emit.py now holds the one copy of the kit's method (its added lines tagged
"# (emit)", pinned at the kit's tree as before) and the points the modules register
into: a run gatherer (fastfp), start hooks (lift_fixes' label), head lines (entry_hooks'
call, then lift_fixes' goto) and passes over the finished text (poll). The order of
what they add is written there, not left to install order. nx2/chunks.py's new-process
check compares the registered hooks too.

The lifted C is byte-identical: a standalone lift of main (79d4a143) and of this branch,
same inputs and environment as make_game.py's, wrote the same 106 files (1.69 GB).
tests/test_fastfp_override.py becomes tests/test_lift_emit.py: the same pins, and the
hooks checked against the wrappers they replaced, in either registration order.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
refactor(lift): guest locals register into emit_function's hooks, in place of two wrappers
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 12s
PR description / Description follows the template (pull_request_target) Successful in 16s
CI / Workflow lint (actionlint) (pull_request) Successful in 19s
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 18s
4287bd5b34
nx2/guest_locals.py wrapped Lifter.emit_function twice (the context-flag texts for a function in no_local, and which
function localize_regs was for, through two globals) and replaced the kit's localize_regs. With #1560's one emit_function
those become two of its points:

- texts: called with (lifter, entry, texts) before a function is written; guest_locals' plain gives a function in
  no_local the context-flag texts.
- localize (set_localize): one hook, told the function being written, where the copied method makes registers and flags
  locals; guest_locals' localize keeps the context for a function in no_local or one the game's patches would change.

emit.py's copy now reads local_regs and localize_regs through two functions of its own, asked when it runs, not the names
it imported: guest_locals sets the kit's defaults after emit is imported, and a rebase onto it had to patch emit's names
to keep the locals on. emit.fingerprint() lists both hooks, which the lift's new processes compare.

A lift of the game with this commit is byte-identical to main's (868f6be8): 92 files, 1.63 GB. tests/test_lift_emit.py
checks the two hooks against the kit's own method; making emit's local_regs answer as the imported one did, or a localize
hook that ignores no_local, fails it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
nx2/lift_fixes.py starts such a function with a goto to its entry right after the head,
and with A64_LOCAL_REGS or A64_LOCAL_FLAGS the kit declares the register locals there too,
loaded from the context. The goto came first and jumped over the declarations, so the
function ran on locals that were never loaded. A made-up function emitted as the lift does
shows it; this fails here and on main.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
fix(lift): with local registers, a function with code below its entry loads them before its entry
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 11s
PR description / Description follows the template (pull_request_target) Successful in 16s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 18s
CI / Workflow lint (actionlint) (pull_request) Successful in 22s
Third-party parts / As their notes say (pull_request) Successful in 25s
725cc27ae7
nx2/emit.py put its head lines (entry_hooks' call, lift_fixes' goto to the entry) into
a function's finished text, after the kit's localize_regs had declared the register
locals right after the head, so the goto came first and jumped over the loads: with
A64_LOCAL_REGS or A64_LOCAL_FLAGS, each function with code below its entry (26 in a lift
of OoT) ran on locals never loaded from the context. The head lines now go into the
function's lines before localize_regs, which then declares the locals ahead of them.
A PLT stub, written before that point, still gets them in its text.

Without local registers (the default) the C is unchanged; tests/test_lift_entry_local_regs.py
passes now.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The hook compiler of the Modding API Spec (section 8.1; the plan's M2, piece 1). nx2/hooks.py reads the supported game
build's site table, finds each site by its signature (instruction words with masks; exactly one match in its module or
the lift stops, every bad site named), and compiles it in: an "after" site as C spliced after its instruction
(Lifter.after), an "entry" site as a head line that returns when its call says the function is done and otherwise reads
the function's locals again. A site costs a byte load and a predicted branch while no handler wants it.

nx2/emit.py now splices Lifter.after past an instruction that is not an op but falls through (a conditional branch, a
call, an SVC); the kit splices only after ops. The entry sites' lines reach the emit's new processes as
nx2/chunks.py's EMIT_TABLES site_entries. nx2/make_game.py's lift key takes .toml files in nx2/.

The table of OoT 1.1.1 is present and empty: the translation is unchanged.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
The first feature moved from nx2/oot_patches.py's text patches to a hook site (the Modding API Plan, M2 piece 2).
textStep, in OoT 1.1.1's table, is the letters' block of f_80b1e140 found by four words (the branches' offsets masked),
where the patch was. host/oot_text_step.c's handler does what the patch did: s0 times hos_text_scale when it is not
1, then hos_oot_text_pane with x19.

The host's side of the sites: the lift writes a64_sites.c (the sites' names, in order, and a byte each, hos_sites),
build.py compiles it, and host/hook_sites.c attaches handlers by name (HOS_SITE at start-up) and calls them in order
(hos_site_call) until one says the function is done.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
An after site went into Lifter.after, whose C makes its function keep every register in the context
(nx2/guest_locals.py keep_spliced): a site slowed the code it was put in. Sites now have their own table,
Lifter.site_after, and their C carries the context marks of the instruction they follow: inside the
branch a set byte takes, the locals changed since the last sync are written back and the flags stored
before the handler, and every local is read again after it. A dormant site is a load of its byte and a
branch, and the function keeps its locals.

Each site is counted where the emit writes it (the counters come back from the worker processes), and
the lift stops when a site was written into no function: its table not sent to the emit, or its place
in no function's code. The lift says how many sites are in functions with locals, and names the others.

Tested: tests/test_hook_sites.py (the emitted text; a stand-in run gatherer; the emitted function
compiled and run, dormant and set; a patch and a site on one instruction; the written check), with
teeth for seven breaks; test_spawn_emit, test_lift_emit, test_menu_hooks, test_entry_below_locals,
test_text_speed, test_text_size pass.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
fix(lift): the hook site call is A64_NOESC, an after site runs every handler, BLRAA is no branch away
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 11s
PR description / Description follows the template (pull_request_target) Successful in 14s
CI / Workflow lint (actionlint) (pull_request) Successful in 17s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 18s
Third-party parts / As their notes say (pull_request) Successful in 21s
Website / Website on Cloudflare (pull_request_target) Has been skipped
4cdd901d75
From a cold review of this branch. The site's call of the host is declared with A64_NOESC, as every call lifted code
makes: without it the call captured the context in the whole function, its dormant path too, and the compiler reloaded
the context's registers after every guest store (a64-kit's a64.h). An after site runs every handler; only an entry
site's stop at the first that says it did the function's work (a64_site_entry, in a64_sites.c). never_falls no longer
refuses BLRAA and BLRAB, which return. A signature is found by an exact anchor word (bytes.find), not by a regex tried
at every byte, so many sites resolve in the time of one. A lift with more sites than host/hook_sites.c holds stops.
The host writes a handler's user before its function; host/hook_sites.h says what a handler may rely on (not the
flags; not keeping c) and that attaching is for the program's start.

Tests: the NOESC declaration, the branches an after site may follow, a signature of masked words alone, too many sites,
an after site running every handler and an entry site stopping at the first done.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Author
Member

Tested in game: Windows 11 Pro N 22631, RTX 3080 (NVIDIA 621.14), Ryzen 9 3900X, by the person I work for: a pack of the next PR's branch at 95fbe486 (this branch's code at ada6d3fc with the feature modules on top, their translations byte for byte the same) over main 47430e81's base, #1729's header fix applied for the build only. The repository's kokiri-start save, Kokiri Forest's signs and dialogue: Text speed at Normal types the letters out, at its fastest shows each page at once; Text size larger as before, including #1779's first showing at the default size, which main has too. Not run in the game since: the review's fixes (A64_NOESC, after sites running every handler) and the rebase onto 0de25c3e.

Tested in game: Windows 11 Pro N 22631, RTX 3080 (NVIDIA 621.14), Ryzen 9 3900X, by the person I work for: a pack of the next PR's branch at 95fbe486 (this branch's code at ada6d3fc with the feature modules on top, their translations byte for byte the same) over main 47430e81's base, #1729's header fix applied for the build only. The repository's kokiri-start save, Kokiri Forest's signs and dialogue: Text speed at Normal types the letters out, at its fastest shows each page at once; Text size larger as before, including #1779's first showing at the default size, which main has too. Not run in the game since: the review's fixes (A64_NOESC, after sites running every handler) and the rebase onto 0de25c3e.
dyst force-pushed feat/hook-sites from 4cdd901d75
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 11s
PR description / Description follows the template (pull_request_target) Successful in 14s
CI / Workflow lint (actionlint) (pull_request) Successful in 17s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 18s
Third-party parts / As their notes say (pull_request) Successful in 21s
Website / Website on Cloudflare (pull_request_target) Has been skipped
to ba76c36161
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 23s
CI / Workflow lint (actionlint) (pull_request) Successful in 33s
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 18s
PR description / Description follows the template (pull_request_target) Successful in 8s
2026-11-20 00:49:22 +00:00
Compare
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 23s
CI / Workflow lint (actionlint) (pull_request) Successful in 33s
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 18s
PR description / Description follows the template (pull_request_target) Successful in 8s
This pull request has changes conflicting with the target branch.
  • docs/design.md
  • nx2/fastfp.py
  • nx2/lift.py
  • tests/test_fastfp_override.py
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/hook-sites:dyst-feat/hook-sites'
git switch 'dyst-feat/hook-sites'
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
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!1821
No description provided.