WIP: feat(gameplay): an Auto-jump row: running or rolling off an edge jumps, as on the N64 #1327

Draft
kingo wants to merge 1 commit from kingo/Longshot:feat/auto-jump into main
First-time contributor

Type: feat · Risk: low · Tested on: Windows 11, RTX 5060 Ti 8 GB · Needs: Linux, any pad

Why

On the N64, Link jumps on his own when he runs or rolls off an edge: rocks in Zora's Domain, platforms, ledges. The remake drops him instead and leaves the jump to a button (Swap Jump Controls is its only option), so the edge-to-edge platforming players know by muscle memory needs a press each time. Searched the tracker (auto-jump, autojump, "auto jump", "jump off", ledge, cliff, pchtxt): nothing builds it in. A community Auto Jump .pchtxt mod exists (https://gamebanana.com/mods/739034) and is used as an example in the Mods work (#134, #1036); a menu row works without a mod, with the game's own jump and ledge grab, and walks still drop.

What changed

A new row in Gameplay, Auto-jump: Off (the default, the game as now) or On.

Gameplay's Auto-jump row

With On, where Link's AI selectors pick their fall on losing the ground, they pick their jump instead (the selectors' names are the game's own, from its node name strings; nothing decompiled is used):

Where (lifted function) Selector Picks instead of Fall When
f_808170d0 at L_808175a0 SelectorPlayerSchedulerWalk its Jump output (+50 over Fall +51) he runs: forward speed above 5.0
f_80814b20 SelectorPlayerSchedulerRolling Jump (0x3f over Fall 0x43) a roll
f_80814b20 at L_80814c18 the same, while the roll can't be cancelled (its action's flag bit 11) the ground check runs there too, then Jump a roll; otherwise he rolled on in the air and jumped late
f_8081d450 Rolling's cancel check the shared helper's next action, Jump (0x0d over Fall 0x21) a roll
  • The speed is Link's forward speed from his controller (*(controller+40)+472, the controller found as oot_player_controller finds it). Measured in game: a walk 4.45 to 4.56, a run 5.30 to 5.31, so 5.0 sits between. No controller found: the game's fall.
  • host/oot_autojump.c decides (hos_oot_autojump), nx2/oot_patches.py patch_autojump puts the four calls in; each site keeps the game's own pick when the row is off.
  • menu: the row in gpu/vk/vk_menu.cpp (opts.auto_jump, after Skip opening), read by the host as HOS_OPT_AUTO_JUMP (73; 62 to 72, 80, 88 and 90 are taken). README's option table has its line.

Measurements

Verdict: nothing to measure: a gameplay option, off by default; with it on, one function call where Link loses the ground.

Flags and settings

One new menu row.

Flag What it is Before this PR After this PR Effect Helps / doesn't help / untested Recommendation
Auto-jump (auto_jump= in longshot_options.ini) Gameplay row: jump on running or rolling off an edge (none: he falls) Off (0) On (1): running or rolling off an edge jumps; walking off drops Helps players used to the N64's platforming; Off unchanged Off by default, the player's choice

Testing

Tested: Windows 11 Pro 26200, RTX 5060 Ti 8 GB, a pad through SDL, the Sacred Forest Meadow (a test build of this change with log lines at each site). With On: running off edges jumped (10 edges logged, the runs at speed 5.30 to 5.31); walking off dropped (4.50 to 4.56); rolling off jumped (7 rolls); ledge grabs and ladders worked as before. Off: he falls, as now.

Video: the row turned on, then edges walked, run and rolled off

tests/test_oot_autojump.py (new; fails on main: no row): the row, its id and default, the four sites patched once each and left alone when their anchor moved, the game's fall kept when off, and host/oot_autojump.c compiled with a stub option. Run with the checks it touches (test_option_ids, test_readme_menu_rows, test_oot_damage, test_opening_skip): all pass. The full suite is not run yet (the game was open); it will be before this leaves WIP.

Not tested: Linux; adult Link (the run speed may differ: the walk/run gap is from child Link); other selectors that also fall (Charge, lock-on, BackFlip, SideStep, Land): off an edge from those he still falls.

Must be tested:

  • Linux, any pad: Gameplay → Auto-jump → On, run off an edge in the Sacred Forest Meadow, expecting a jump; walk off, expecting a drop (Test Farm: @Beanstalk linux, Auto-jump run and walk off an edge).

Risks

What could break: with On, a run off an edge where a fall was wanted jumps (as on the N64). With Off nothing changes: each site keeps the game's pick.

Turning it off: the row's Off, or revert the commit.

Compatibility: one new line in longshot_options.ini; nothing else changes.

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.
  • Switches documented (docs/development.md; the README for a menu row) and shipped at their recommended value.
  • A check under tests/ that reads changed source updated in this PR, not weakened.
  • Docs updated.

🤖 Generated with Claude Code

**Type:** feat · **Risk:** low · **Tested on:** Windows 11, RTX 5060 Ti 8 GB · **Needs:** Linux, any pad ## Why On the N64, Link jumps on his own when he runs or rolls off an edge: rocks in Zora's Domain, platforms, ledges. The remake drops him instead and leaves the jump to a button (Swap Jump Controls is its only option), so the edge-to-edge platforming players know by muscle memory needs a press each time. Searched the tracker (auto-jump, autojump, "auto jump", "jump off", ledge, cliff, pchtxt): nothing builds it in. A community Auto Jump `.pchtxt` mod exists (https://gamebanana.com/mods/739034) and is used as an example in the Mods work (#134, #1036); a menu row works without a mod, with the game's own jump and ledge grab, and walks still drop. ## What changed A new row in Gameplay, **Auto-jump**: Off (the default, the game as now) or On. ![Gameplay's Auto-jump row](https://git.magicbean.dev/attachments/5a67f002-79d3-42ad-b10d-14122c528cba) With On, where Link's AI selectors pick their fall on losing the ground, they pick their jump instead (the selectors' names are the game's own, from its node name strings; nothing decompiled is used): | Where (lifted function) | Selector | Picks instead of Fall | When | |---|---|---|---| | `f_808170d0` at `L_808175a0` | SelectorPlayerSchedulerWalk | its Jump output (+50 over Fall +51) | he runs: forward speed above 5.0 | | `f_80814b20` | SelectorPlayerSchedulerRolling | Jump (0x3f over Fall 0x43) | a roll | | `f_80814b20` at `L_80814c18` | the same, while the roll can't be cancelled (its action's flag bit 11) | the ground check runs there too, then Jump | a roll; otherwise he rolled on in the air and jumped late | | `f_8081d450` | Rolling's cancel check | the shared helper's next action, Jump (0x0d over Fall 0x21) | a roll | - The speed is Link's forward speed from his controller (`*(controller+40)+472`, the controller found as `oot_player_controller` finds it). Measured in game: a walk 4.45 to 4.56, a run 5.30 to 5.31, so 5.0 sits between. No controller found: the game's fall. - `host/oot_autojump.c` decides (`hos_oot_autojump`), `nx2/oot_patches.py` `patch_autojump` puts the four calls in; each site keeps the game's own pick when the row is off. - menu: the row in `gpu/vk/vk_menu.cpp` (`opts.auto_jump`, after Skip opening), read by the host as `HOS_OPT_AUTO_JUMP` (73; 62 to 72, 80, 88 and 90 are taken). README's option table has its line. ## Measurements **Verdict:** nothing to measure: a gameplay option, off by default; with it on, one function call where Link loses the ground. ### Flags and settings One new menu row. | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | Auto-jump (`auto_jump=` in longshot_options.ini) | Gameplay row: jump on running or rolling off an edge | (none: he falls) | Off (0) | On (1): running or rolling off an edge jumps; walking off drops | Helps players used to the N64's platforming; Off unchanged | Off by default, the player's choice | ## Testing **Tested:** Windows 11 Pro 26200, RTX 5060 Ti 8 GB, a pad through SDL, the Sacred Forest Meadow (a test build of this change with log lines at each site). With On: running off edges jumped (10 edges logged, the runs at speed 5.30 to 5.31); walking off dropped (4.50 to 4.56); rolling off jumped (7 rolls); ledge grabs and ladders worked as before. Off: he falls, as now. [Video: the row turned on, then edges walked, run and rolled off](https://git.magicbean.dev/attachments/07c31c9f-60ce-455d-aed7-9cbea60588d9) `tests/test_oot_autojump.py` (new; fails on main: no row): the row, its id and default, the four sites patched once each and left alone when their anchor moved, the game's fall kept when off, and `host/oot_autojump.c` compiled with a stub option. Run with the checks it touches (`test_option_ids`, `test_readme_menu_rows`, `test_oot_damage`, `test_opening_skip`): all pass. The full suite is not run yet (the game was open); it will be before this leaves WIP. **Not tested:** Linux; adult Link (the run speed may differ: the walk/run gap is from child Link); other selectors that also fall (Charge, lock-on, BackFlip, SideStep, Land): off an edge from those he still falls. **Must be tested:** - Linux, any pad: Gameplay → Auto-jump → On, run off an edge in the Sacred Forest Meadow, expecting a jump; walk off, expecting a drop (Test Farm: @Beanstalk linux, Auto-jump run and walk off an edge). ## Risks **What could break:** with On, a run off an edge where a fall was wanted jumps (as on the N64). With Off nothing changes: each site keeps the game's pick. **Turning it off:** the row's Off, or revert the commit. **Compatibility:** one new line in longshot_options.ini; nothing else changes. ## 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`. - [ ] `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] Switches documented (docs/development.md; the README for a menu row) and shipped at their recommended value. - [x] A check under `tests/` that reads changed source updated in this PR, not weakened. - [x] Docs updated. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
feat(gameplay): an Auto-jump row: running or rolling off an edge jumps, as on the N64
Some checks are pending
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
Guide screenshots / Guide images and local UI source review (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_target) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 8s
d52e9a0615
Gameplay's Auto-jump (off by default, option 73). Where Link's walk and roll selectors pick their fall on losing the
ground, the jump is picked instead: off the walk selector when he runs (forward speed above 5.0; a walk measured 4.45
to 4.5, a run 5.31), off a roll always, also while the roll can't be cancelled. Walking off still drops, and ledge
grabs keep working.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Author
First-time contributor

Tested in game: Windows 11 Pro 26200, RTX 5060 Ti 8 GB (NVIDIA), a pad through SDL, Sacred Forest Meadow as child Link: with Auto-jump On, running off edges jumped (speed 5.30-5.31), walking off dropped (4.50-4.56), rolling off jumped; ledge grabs and ladders worked; Off falls as before.

Tested in game: Windows 11 Pro 26200, RTX 5060 Ti 8 GB (NVIDIA), a pad through SDL, Sacred Forest Meadow as child Link: with Auto-jump On, running off edges jumped (speed 5.30-5.31), walking off dropped (4.50-4.56), rolling off jumped; ledge grabs and ladders worked; Off falls as before.
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: Author's Tested in game comment: an in-game run on Windows 11, RTX 5060 Ti with a pad, Sacred Forest Meadow.
  • Nothing gets worse that I know of: ticked: Measurements gives a verdict with nothing to measure for speed, and Risks states the one behaviour change, with the option off by default.
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: Author's Tested in game comment: an in-game run on Windows 11, RTX 5060 Ti with a pad, Sacred Forest Meadow. - *Nothing gets worse that I know of*: ticked: Measurements gives a verdict with nothing to measure for speed, and Risks states the one behaviour change, with the option off by default.
Some checks are pending
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
Guide screenshots / Guide images and local UI source review (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_target) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 8s
This pull request is marked as a work in progress.
Some workflows are waiting to be reviewed.
This branch is out-of-date with the base branch
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u 'feat/auto-jump:kingo-feat/auto-jump'
git switch 'kingo-feat/auto-jump'
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!1327
No description provided.