docs(oot): say what x9 holds at the Scarecrow recording cut #268

Open
mooki wants to merge 1 commit from mooki/Longshot:fix/scarecrow-x9-comment into main
Member

Type: docs · Risk: low · Tested on: Linux, Core i9-13900K, no GPU used · Needs: none

Why

The review of #78 asked that the comment at the Scarecrow recording site say what x9 holds there, so the next reader does not have to go to the lift to see why three sites can share one remainder.

What changed

This adds the explanation the review asked for as a source comment above one table entry. Nothing that runs changes: the comment sits inside the patch table's text and the table's entries are untouched.

  • lift patches: the comment above the f_832b6840 entry of WHOLE_SITES in nx2/oot_patches.py now says that x9 is the elapsed counter's address at that cut, why, and that it is the field the other two Scarecrow sites reach as x19 + 0x265fc. A comment only: no entry of the table changed.

One difference from the wording suggested in the review ("x19 + 0x265fc here"): in this function the object pointer is still in x0, so the comment says x0 + 0x265fc and then names the x19 form of the other two sites.

Measurements

Verdict: nothing to measure: a comment in a source file. The syntax tree of nx2/oot_patches.py (which leaves comments out) is the same on main 5e072fc8c and on this head, and the whole game-free suite on this head has the same totals as main (542 passed, 3 failed, 16 skipped), with the same three failures, which are main's own.

Branch state: on main 5e072fc8c2adadba5ea610148be1c47800ba0cca; head db58c774c688923310c0dd0192202b0c8242c948; whole game-free suite on this head: 542 passed, 3 failed, 16 skipped (main 5e072fc8c2adadba5ea610148be1c47800ba0cca: 542 passed, 3 failed, 16 skipped). The 3 failing tests fail on main the same way: tests/test_framegen_resources.py, tests/test_module_ids.py, tests/test_pad_layout.py. The commits are unchanged by rebases apart from the results table.

Commits: main 5e072fc8c2 (2026-11-14); this PR fix/scarecrow-x9-comment @ db58c774c6. The two focused tests and the earlier syntax-tree value below ran on main f3fe1763dd (2026-11-13) and this PR's earlier head 8703a58866fdbaf3285a110baa6153c43e1b28a8.
Hardware: Core i9-13900K, 96 GB RAM, Arch Linux 7.2.15. No GPU and no game needed.
Scene: none; a source comment.
Method: the two tests that read this table, run main, this PR, main, this PR; and the file's syntax tree (Python's ast.dump, which leaves comments out) compared between the two commits. The tree comparison was repeated for the current commits, and the whole game-free suite was run on main and on this head.
How to reproduce: on each commit, python -I -B tests/test_scarecrow_timing.py and python -I -B tests/test_frame_whole.py; for the tree, python -c "import ast,hashlib,sys; print(hashlib.sha256(ast.dump(ast.parse(open('nx2/oot_patches.py', encoding='utf-8').read())).encode()).hexdigest()[:16])". The hashes are from Python 3.14, because ast.dump differs between Python versions.

Before: main @ 5e072fc8c After: this PR @ db58c774c6
syntax tree of nx2/oot_patches.py (sha256, first 16 hex digits, Python 3.14) 23278eff46b7038f 23278eff46b7038f
whole game-free suite 542 passed, 3 failed, 16 skipped 542 passed, 3 failed, 16 skipped

Earlier, on the commits before the carries, the two tests that read the table ran twice each and the tree was the same on both sides. That tree differs from the one above only because main's nx2/oot_patches.py changed in between; within each pair the two trees are equal.

Before: main @ f3fe1763 After: this PR @ 8703a588
tests/test_scarecrow_timing.py, 2 runs each pass, pass pass, pass
tests/test_frame_whole.py, 2 runs each pass, pass pass, pass
syntax tree of nx2/oot_patches.py (sha256, first 16 hex digits) 62c1524a3459fb89 62c1524a3459fb89

The output of those runs:

[main @ f3fe1763] tests/test_scarecrow_timing.py: exit 0 | PASS: short-song recording and playback share a fractional clock
[main @ f3fe1763] tests/test_frame_whole.py: exit 0 | OK
[PR @ 8703a588] tests/test_scarecrow_timing.py: exit 0 | PASS: short-song recording and playback share a fractional clock
[PR @ 8703a588] tests/test_frame_whole.py: exit 0 | OK
[main @ f3fe1763] tests/test_scarecrow_timing.py: exit 0 | PASS: short-song recording and playback share a fractional clock
[main @ f3fe1763] tests/test_frame_whole.py: exit 0 | OK
[PR @ 8703a588] tests/test_scarecrow_timing.py: exit 0 | PASS: short-song recording and playback share a fractional clock
[PR @ 8703a588] tests/test_frame_whole.py: exit 0 | OK

Screenshots

Nothing on screen.

Flags and settings

None.

Testing

Tested: on this exact head, the whole game-free suite (python -I -B tests/run_all.py) gave 542 passed, 3 failed, 16 skipped, the same totals as main 5e072fc8c; the three failures are main's own: tests/test_framegen_resources.py, tests/test_module_ids.py and tests/test_pad_layout.py. The suite includes tests/test_scarecrow_timing.py and tests/test_frame_whole.py, and neither is among its failures. The syntax-tree comparison above is for the current pair. The two tests' own runs above, on Arch Linux, are from the earlier commits. The carry onto main 5e072fc8c left the commit unchanged (a comparison of the two ranges shows it identical). Before writing the comment I read the lifted f_832b6840 of a Linux build of main to check what it claims: x8 is set to x0 + 0x26000 at the function's entry; the cut at 0x832b6af8 is entered two ways, by falling through and from 0x832b6e00, and each sets x9 to x8 + 1532 immediately before; the one branch that reuses x8 for something else returns without reaching the cut; and the store at 0x832b6dac, right after the cut, writes the new count through x9.

Not tested: nothing in the game and no build: the patch table is the same on both commits (the tree hash above), so the lift's edits are the same. The full game-free suite on main a55fc6cf2 was not run; this head's diff merges into it without a conflict.

Must be tested: None.

Risks

What could break: no behaviour changes. One cost to weigh: nx2/oot_patches.py is one of the lift's inputs, so I expect a build to lift again once after this merges, as after any change to that file. If that is not worth it for a comment, this can wait and ride along with the next change to the file.

Turning it off: reverting the commit is enough.

Compatibility: Nothing changes for players or saves: no entry of the patch table changed. A build lifts again once after this merges, as said above.

Reviewer notes

The four comment lines above the f_832b6840 entry are the whole change.

Issues

See #78

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).
  • Measurements has a verdict, or one line saying why there is nothing to measure.
  • Testing names what was tested, what wasn't, and what must still be tested, where and how.
  • Rebased on current main: on 5e072fc8c (2026-11-14) at the last carry, without a conflict; main has moved since (a55fc6cf2 was checked), and this head's diff merges into it without a conflict (not rebased).
  • python -I -B tests/run_all.py passes (any failure that also fails on main is named). On this head: 542 passed, 3 failed, 16 skipped, and the 3 failures also fail on main 5e072fc8c, named under Measurements.
  • 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.

New on this forge; not opened on GitHub.

Assisted-by: GPT-6 Astra
Co-Authored-By: GPT-6 Astra [email protected]

**Type:** docs · **Risk:** low · **Tested on:** Linux, Core i9-13900K, no GPU used · **Needs:** none ## Why The review of #78 asked that the comment at the Scarecrow recording site say what x9 holds there, so the next reader does not have to go to the lift to see why three sites can share one remainder. ## What changed This adds the explanation the review asked for as a source comment above one table entry. Nothing that runs changes: the comment sits inside the patch table's text and the table's entries are untouched. - lift patches: the comment above the `f_832b6840` entry of `WHOLE_SITES` in `nx2/oot_patches.py` now says that x9 is the elapsed counter's address at that cut, why, and that it is the field the other two Scarecrow sites reach as x19 + 0x265fc. A comment only: no entry of the table changed. One difference from the wording suggested in the review ("x19 + 0x265fc here"): in this function the object pointer is still in x0, so the comment says x0 + 0x265fc and then names the x19 form of the other two sites. ## Measurements **Verdict:** nothing to measure: a comment in a source file. The syntax tree of `nx2/oot_patches.py` (which leaves comments out) is the same on main `5e072fc8c` and on this head, and the whole game-free suite on this head has the same totals as main (542 passed, 3 failed, 16 skipped), with the same three failures, which are main's own. <!-- branch-state --> Branch state: on main `5e072fc8c2adadba5ea610148be1c47800ba0cca`; head `db58c774c688923310c0dd0192202b0c8242c948`; whole game-free suite on this head: `542 passed, 3 failed, 16 skipped` (main `5e072fc8c2adadba5ea610148be1c47800ba0cca`: `542 passed, 3 failed, 16 skipped`). The 3 failing tests fail on main the same way: `tests/test_framegen_resources.py`, `tests/test_module_ids.py`, `tests/test_pad_layout.py`. The commits are unchanged by rebases apart from the results table. <!-- /branch-state --> Commits: main 5e072fc8c2adadba5ea610148be1c47800ba0cca (2026-11-14); this PR fix/scarecrow-x9-comment @ db58c774c688923310c0dd0192202b0c8242c948. The two focused tests and the earlier syntax-tree value below ran on main f3fe1763dda267a134494f1d21e6ad10b1ec4cd8 (2026-11-13) and this PR's earlier head 8703a58866fdbaf3285a110baa6153c43e1b28a8. Hardware: Core i9-13900K, 96 GB RAM, Arch Linux 7.2.15. No GPU and no game needed. Scene: none; a source comment. Method: the two tests that read this table, run main, this PR, main, this PR; and the file's syntax tree (Python's `ast.dump`, which leaves comments out) compared between the two commits. The tree comparison was repeated for the current commits, and the whole game-free suite was run on main and on this head. How to reproduce: on each commit, `python -I -B tests/test_scarecrow_timing.py` and `python -I -B tests/test_frame_whole.py`; for the tree, `python -c "import ast,hashlib,sys; print(hashlib.sha256(ast.dump(ast.parse(open('nx2/oot_patches.py', encoding='utf-8').read())).encode()).hexdigest()[:16])"`. The hashes are from Python 3.14, because `ast.dump` differs between Python versions. | | Before: main @ 5e072fc8c | After: this PR @ db58c774c6 | |---|---|---| | syntax tree of `nx2/oot_patches.py` (sha256, first 16 hex digits, Python 3.14) | 23278eff46b7038f | 23278eff46b7038f | | whole game-free suite | 542 passed, 3 failed, 16 skipped | 542 passed, 3 failed, 16 skipped | Earlier, on the commits before the carries, the two tests that read the table ran twice each and the tree was the same on both sides. That tree differs from the one above only because main's `nx2/oot_patches.py` changed in between; within each pair the two trees are equal. | | Before: main @ f3fe1763 | After: this PR @ 8703a588 | |---|---|---| | `tests/test_scarecrow_timing.py`, 2 runs each | pass, pass | pass, pass | | `tests/test_frame_whole.py`, 2 runs each | pass, pass | pass, pass | | syntax tree of `nx2/oot_patches.py` (sha256, first 16 hex digits) | 62c1524a3459fb89 | 62c1524a3459fb89 | The output of those runs: ``` [main @ f3fe1763] tests/test_scarecrow_timing.py: exit 0 | PASS: short-song recording and playback share a fractional clock [main @ f3fe1763] tests/test_frame_whole.py: exit 0 | OK [PR @ 8703a588] tests/test_scarecrow_timing.py: exit 0 | PASS: short-song recording and playback share a fractional clock [PR @ 8703a588] tests/test_frame_whole.py: exit 0 | OK [main @ f3fe1763] tests/test_scarecrow_timing.py: exit 0 | PASS: short-song recording and playback share a fractional clock [main @ f3fe1763] tests/test_frame_whole.py: exit 0 | OK [PR @ 8703a588] tests/test_scarecrow_timing.py: exit 0 | PASS: short-song recording and playback share a fractional clock [PR @ 8703a588] tests/test_frame_whole.py: exit 0 | OK ``` ### Screenshots Nothing on screen. ### Flags and settings None. ## Testing **Tested:** on this exact head, the whole game-free suite (`python -I -B tests/run_all.py`) gave 542 passed, 3 failed, 16 skipped, the same totals as main `5e072fc8c`; the three failures are main's own: `tests/test_framegen_resources.py`, `tests/test_module_ids.py` and `tests/test_pad_layout.py`. The suite includes `tests/test_scarecrow_timing.py` and `tests/test_frame_whole.py`, and neither is among its failures. The syntax-tree comparison above is for the current pair. The two tests' own runs above, on Arch Linux, are from the earlier commits. The carry onto main `5e072fc8c` left the commit unchanged (a comparison of the two ranges shows it identical). Before writing the comment I read the lifted `f_832b6840` of a Linux build of main to check what it claims: x8 is set to x0 + 0x26000 at the function's entry; the cut at 0x832b6af8 is entered two ways, by falling through and from 0x832b6e00, and each sets x9 to x8 + 1532 immediately before; the one branch that reuses x8 for something else returns without reaching the cut; and the store at 0x832b6dac, right after the cut, writes the new count through x9. **Not tested:** nothing in the game and no build: the patch table is the same on both commits (the tree hash above), so the lift's edits are the same. The full game-free suite on main `a55fc6cf2` was not run; this head's diff merges into it without a conflict. **Must be tested:** None. ## Risks **What could break:** no behaviour changes. One cost to weigh: `nx2/oot_patches.py` is one of the lift's inputs, so I expect a build to lift again once after this merges, as after any change to that file. If that is not worth it for a comment, this can wait and ride along with the next change to the file. **Turning it off:** reverting the commit is enough. **Compatibility:** Nothing changes for players or saves: no entry of the patch table changed. A build lifts again once after this merges, as said above. ## Reviewer notes The four comment lines above the `f_832b6840` entry are the whole change. ## Issues See #78 ## 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] Measurements has a verdict, or one line saying why there is nothing to measure. - [x] Testing names what was tested, what wasn't, and what must still be tested, where and how. - [x] Rebased on current `main`: on `5e072fc8c` (2026-11-14) at the last carry, without a conflict; main has moved since (`a55fc6cf2` was checked), and this head's diff merges into it without a conflict (not rebased). - [x] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named). On this head: 542 passed, 3 failed, 16 skipped, and the 3 failures also fail on main `5e072fc8c`, named under Measurements. - [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. --- New on this forge; not opened on GitHub. Assisted-by: GPT-6 Astra Co-Authored-By: GPT-6 Astra <[email protected]>
Author
Member

Head 7497f0828 on main 514591a30; the whole game-free suite on it: 517 passed, 1 failed, 15 skipped. A comment only, as asked in the review of #78; the description says how the claim in the comment was checked against the lifted function and why it names x0 where the review's suggestion named x19.

Head `7497f0828` on main `514591a30`; the whole game-free suite on it: 517 passed, 1 failed, 15 skipped. A comment only, as asked in the review of #78; the description says how the claim in the comment was checked against the lifted function and why it names x0 where the review's suggestion named x19.
mooki changed title from WIP: docs(oot): say what x9 holds at the Scarecrow recording cut to docs(oot): say what x9 holds at the Scarecrow recording cut 2026-11-13 19:09:44 +00:00
mooki force-pushed fix/scarecrow-x9-comment from 8703a58866
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 6s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
to 7497f08283
Some checks failed
CI / Conventional Commit title (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Blocked by required conditions
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Blocked by required conditions
CI / Workflow lint (actionlint) (pull_request) Blocked by required conditions
Third-party parts / As their notes say (pull_request) Blocked by required conditions
Third-party parts / The same as upstream (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request) Blocked by required conditions
PR description / Description follows the template (pull_request_target) Has been cancelled
Website / Website on Cloudflare (pull_request_target) Has been skipped
2026-11-13 19:09:45 +00:00
Compare
mooki force-pushed fix/scarecrow-x9-comment from 7497f08283
Some checks failed
CI / Conventional Commit title (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Blocked by required conditions
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Blocked by required conditions
CI / Workflow lint (actionlint) (pull_request) Blocked by required conditions
Third-party parts / As their notes say (pull_request) Blocked by required conditions
Third-party parts / The same as upstream (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request) Blocked by required conditions
PR description / Description follows the template (pull_request_target) Has been cancelled
Website / Website on Cloudflare (pull_request_target) Has been skipped
to db58c774c6
All checks were successful
Website / Website on Cloudflare (pull_request_target) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 5s
2026-11-14 13:56:07 +00:00
Compare
Author
Member

Carried onto main 5e072fc8c; new head db58c774c. This carry is mechanical: every commit replays unchanged, with no conflicts. The whole suite on this exact head: 542 passed, 3 failed, 16 skipped; its only failures are main's own tests/test_pad_layout.py, tests/test_module_ids.py and tests/test_framegen_resources.py.

Carried onto main `5e072fc8c`; new head `db58c774c`. This carry is mechanical: every commit replays unchanged, with no conflicts. The whole suite on this exact head: 542 passed, 3 failed, 16 skipped; its only failures are main's own `tests/test_pad_layout.py`, `tests/test_module_ids.py` and `tests/test_framegen_resources.py`.
Author
Member

The description is moved to the current template. The earlier one no longer passed the description check since #571 changed the template: it had no status line, no Risks section, no Must be tested part and no Everyone checklist, and its measurement columns named no commits.

Nothing else changed. The head is still db58c774c6, with no new commit and no push, and the code and the measurements are the same. The measurement table now names main 5e072fc8c and this head. The two focused runs from the earlier commits stay, marked with theirs.

The syntax tree of nx2/oot_patches.py is the same on main 5e072fc8c and on this head (23278eff46b7038f, Python 3.14). The whole game-free suite on this head is the result from my comment of 2026-11-14: 542 passed, 3 failed, 16 skipped, the same as main 5e072fc8c, with the same three failures. I did not rerun the suite on main a55fc6cf2; this head's diff merges into it without a conflict.

The description is moved to the current template. The earlier one no longer passed the description check since https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/571 changed the template: it had no status line, no Risks section, no Must be tested part and no Everyone checklist, and its measurement columns named no commits. Nothing else changed. The head is still db58c774c6, with no new commit and no push, and the code and the measurements are the same. The measurement table now names main 5e072fc8c and this head. The two focused runs from the earlier commits stay, marked with theirs. The syntax tree of `nx2/oot_patches.py` is the same on main 5e072fc8c and on this head (23278eff46b7038f, Python 3.14). The whole game-free suite on this head is the result from my comment of 2026-11-14: 542 passed, 3 failed, 16 skipped, the same as main 5e072fc8c, with the same three failures. I did not rerun the suite on main a55fc6cf2; this head's diff merges into it without a conflict.
All checks were successful
Website / Website on Cloudflare (pull_request_target) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 5s
This pull request doesn't have enough approvals yet. 0 of 1 approvals granted.
Some workflows are waiting to be reviewed.
This branch is out-of-date with the base branch
You are not authorized to merge this pull request.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u 'fix/scarecrow-x9-comment:mooki-fix/scarecrow-x9-comment'
git switch 'mooki-fix/scarecrow-x9-comment'
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!268
No description provided.