WIP: feat(gameplay): a Run speed slider (100% to 200%) #1231

Draft
TrashPanda wants to merge 2 commits from TrashPanda/Longshot:feat/run-speed into main
Contributor

Type: feat · Risk: low · Tested on: Linux, RTX 4070 Ti · Needs: Windows, any GPU

Why

Players who want Link to cross the world faster, for example over Hyrule Field, have only the Debug tab's Movement speed. It shows only with the debug tools on, offers five fixed steps (1x to 3x) and is back to 1x at every start. This adds Gameplay → Run speed, a saved slider any player can use without turning on the debug tools. No issue asks for this exactly (searched "run speed", "movement speed", "sprint"); the nearest is a sprint toggle. See #1005.

What changed

A Gameplay row, Run speed, from 100% to 200% in steps of 5 and 100% (original) by default, makes Link run, walk and swim faster while the player steers him. It uses the speed scaling Movement speed already has, so it inherits that feature's limits: only Link's own character controller, only while the left stick is pushed, and only for speeds up to 15 m/s. Cutscenes, scripted walks and ledge climbs keep their pace, and the physics step still stops him at walls.

  • host: oot_speed_choice() and oot_player_speed() in host/hos_main.c pick the Debug tab's Movement speed when it is above 1x (it sends 100 while the tools are off), else Run speed. Anything outside 100 to 200 counts as 100. The log names which row chose: gameplay: run speed 150% or cheats: movement speed 200%.
  • menu: the row in gpu/vk/vk_menu.cpp is a slider that stops at its ends (is_slider, stops_at_ends) and uses tx_fov's "100% (original)" label. opts.run_speed in gpu/vk/vk_menu.h is saved as run_speed in longshot_options.ini. vk_replay.cpp's option callback answers HOS_OPT_RUN_SPEED.
  • id: HOS_OPT_RUN_SPEED = 96 in gpu/vk/vk_api.h. Every id from 62 to 71, plus 80, 88 and 90, is taken by an open pull request (checked across every PR head), so 96 stays clear of them. Only the existing option callback changes, so there is no MKWVK_API_VERSION bump.
  • texts: the row's name and help in all 13 menu languages (gpu/vk/menu_i18n.h, machine-made like the rest).
  • docs: the README's option table and a paragraph under Field of view; docs/development.md's options-file table.
  • test: tests/test_run_speed.py cuts oot_speed_choice() from the source and runs it: Run speed alone, out-of-range values, Movement speed above 1x first, and Movement speed at 1x or out of range. It also reads the id, the row (range, step, live, no restart), the default, the slider, the saved key, the README line, and that only host/hos_main.c reads the option.

Measurements

Verdict: it works as set. Over a fixed 90-frame stick hold, Link covers 1.47x the distance at 150% and 1.92x at 200%, with no change at 100%. The ratios fall a little short of 1.5 and 2 because each hold starts from a standstill and includes his acceleration.

Hardware: Ubuntu 26.04.1 LTS, kernel 7.0.0-43; RTX 4070 Ti 12 GB, NVIDIA 595.99.02; Ryzen 7 9800X3D, 32 GB
Scene: Hyrule Field (child), reached by the control bridge's teleport; headless, 1920x1080, the game folder's options, Debug tools Off
Method: through scripts/longshot_ctl.py, option set run_speed N, then the left stick held forward for 90 frames and back for 90, measuring Link's horizontal distance from status's pos. 100, 150 and 200% were run interleaved, twice each, 4 holds per setting; the table shows the median (the holds agree within 0.6 m).
Baseline: Run speed at 100% on the same build, interleaved with the other settings in one session; at 100% the scaling returns before touching the speed, so this is main's movement.
How to reproduce: any save in Hyrule Field; Gameplay → Run speed at 100%, 150% and 200%; hold forward for 1.5 s at each.

Before, Run speed 100%: this PR @ b402d18e After, Run speed 150%: this PR @ b402d18e After, Run speed 200%: this PR @ b402d18e
Link's distance per 90-frame hold (median of 4) 6.29 m 9.28 m (1.47x) 12.11 m (1.92x)
run_speed=100: 6.34 m forward, 6.29 m back
run_speed=150: 9.28 m forward, 9.28 m back
run_speed=200: 11.73 m forward, 12.14 m back
run_speed=100: 6.29 m forward, 6.28 m back
run_speed=150: 9.26 m forward, 9.27 m back
run_speed=200: 12.07 m forward, 12.26 m back
[hos BaseProcExecutor0] gameplay: run speed 150%
[hos BaseProcExecutor0] gameplay: run speed 200%
[hos BaseProcExecutor0] gameplay: run speed 100%

No frame-rate effect is expected: the change is a multiply on one float, made only when Link's controller sets its speed.

Flags and settings

One new menu row and ini key; the default leaves Link's speed unchanged.

Flag What it is Before this PR After this PR Effect Helps / doesn't help / untested Recommendation
Gameplay → Run speed; run_speed Link's speed while steered, percent of his own (none) 100 (original) 100 to 200% faster running, walking and swimming Helps: crossing large areas. Doesn't change cutscenes, scripted walks or ledge climbs. Untested: Windows, every movement state (horseback with Epona, Iron Boots, climbing) Ship at 100%; a player's choice

Testing

Tested:

  • Linux (Ubuntu 26.04.1), RTX 4070 Ti, NVIDIA 595.99.02. I built this branch with make_game.py and ran it headless through the control bridge. Hyrule Field, the stick held at 100, 150 and 200%: numbers above, the log naming each change, no device loss or Vulkan error. The run is recorded in docs/tested/2026-11-16-run-speed-trashpanda-field1.md. The build was made on main 615b2498, just before this rebase onto 623a0ca3; the feature's code is the same.
  • The menu row rendered game-free with scripts/screenshots' fixture, extended locally to the Gameplay tab and not committed (picture in the first comment).
  • python -I -B tests/run_all.py on Linux: the new tests/test_run_speed.py and the checks it touches (test_option_ids, test_movement_speed, test_menu_i18n, test_readme_menu_rows, test_camera_speed, test_oot_fov, test_menu_keys, test_tested_configurations) pass. After the rebase onto 623a0ca3: 649 passed, 24 failed, 21 skipped. 23 of the 24 fail the same on main 623a0ca3 on this PC (test_walk_key, test_damage_debug_menu, test_upscaler_rows, test_linux_preflight, test_make_game_cache and others). The 24th, test_crash_record, failed only inside the full parallel run and passes alone, 3 runs of 3.

Not tested:

  • Windows, AMD and Intel GPUs. The change is host C and menu code with nothing GPU-specific, but it has not run there.
  • Playing with the row by hand: Epona, Iron Boots, swimming, ledges, dungeons and boss rooms at 200%. Movement speed has the same scaling up to 3x, and the 15 m/s cap keeps the ledge-climb fling it once had away.

Must be tested:

  • Windows, any GPU: open Gameplay → Run speed, set 150%, run across Hyrule Field, expecting Link visibly faster, the menu showing 150% after a restart, and gameplay: run speed 150% in longshot_log.txt (Test Farm: @Beanstalk windows, set Gameplay Run speed to 150% and run in Hyrule Field).

Risks

What could break: Link's movement while Run speed is above 100%: a room or puzzle timed around his running speed, or a narrow ledge he now overshoots. At 100%, the default, nothing changes: the scaling returns before touching the speed.

Turning it off: Run speed at 100% (original), or revert the commit.

Compatibility: A new run_speed line in longshot_options.ini; older builds ignore it. Saves, shader and pipeline caches and the vk ABI (MKWVK_API_VERSION) are unchanged.

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

  • Numbers from the same PC, scene and settings, at least 2 interleaved runs each, the median reported.
  • Switches documented (docs/development.md; the README for a menu row) and shipped at their recommended value.
  • Screenshots of the same spot, captioned like the Measurements columns, for a change that shows on screen.
  • A file in docs/tested/ for each new measured run (format in docs/tested-configurations.md).
  • Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. (Linux built; Windows left to CI's build, nothing platform-specific added)
  • Docs updated.
**Type:** feat · **Risk:** low · **Tested on:** Linux, RTX 4070 Ti · **Needs:** Windows, any GPU ## Why Players who want Link to cross the world faster, for example over Hyrule Field, have only the Debug tab's Movement speed. It shows only with the debug tools on, offers five fixed steps (1x to 3x) and is back to 1x at every start. This adds **Gameplay → Run speed**, a saved slider any player can use without turning on the debug tools. No issue asks for this exactly (searched "run speed", "movement speed", "sprint"); the nearest is a sprint toggle. See #1005. ## What changed A Gameplay row, Run speed, from 100% to 200% in steps of 5 and 100% (original) by default, makes Link run, walk and swim faster while the player steers him. It uses the speed scaling Movement speed already has, so it inherits that feature's limits: only Link's own character controller, only while the left stick is pushed, and only for speeds up to 15 m/s. Cutscenes, scripted walks and ledge climbs keep their pace, and the physics step still stops him at walls. - host: `oot_speed_choice()` and `oot_player_speed()` in `host/hos_main.c` pick the Debug tab's Movement speed when it is above 1x (it sends 100 while the tools are off), else Run speed. Anything outside 100 to 200 counts as 100. The log names which row chose: `gameplay: run speed 150%` or `cheats: movement speed 200%`. - menu: the row in `gpu/vk/vk_menu.cpp` is a slider that stops at its ends (`is_slider`, `stops_at_ends`) and uses `tx_fov`'s "100% (original)" label. `opts.run_speed` in `gpu/vk/vk_menu.h` is saved as `run_speed` in `longshot_options.ini`. `vk_replay.cpp`'s option callback answers `HOS_OPT_RUN_SPEED`. - id: `HOS_OPT_RUN_SPEED = 96` in `gpu/vk/vk_api.h`. Every id from 62 to 71, plus 80, 88 and 90, is taken by an open pull request (checked across every PR head), so 96 stays clear of them. Only the existing option callback changes, so there is no `MKWVK_API_VERSION` bump. - texts: the row's name and help in all 13 menu languages (`gpu/vk/menu_i18n.h`, machine-made like the rest). - docs: the README's option table and a paragraph under Field of view; `docs/development.md`'s options-file table. - test: `tests/test_run_speed.py` cuts `oot_speed_choice()` from the source and runs it: Run speed alone, out-of-range values, Movement speed above 1x first, and Movement speed at 1x or out of range. It also reads the id, the row (range, step, live, no restart), the default, the slider, the saved key, the README line, and that only `host/hos_main.c` reads the option. ## Measurements **Verdict:** it works as set. Over a fixed 90-frame stick hold, Link covers 1.47x the distance at 150% and 1.92x at 200%, with no change at 100%. The ratios fall a little short of 1.5 and 2 because each hold starts from a standstill and includes his acceleration. Hardware: Ubuntu 26.04.1 LTS, kernel 7.0.0-43; RTX 4070 Ti 12 GB, NVIDIA 595.99.02; Ryzen 7 9800X3D, 32 GB Scene: Hyrule Field (child), reached by the control bridge's teleport; headless, 1920x1080, the game folder's options, Debug tools Off Method: through `scripts/longshot_ctl.py`, `option set run_speed N`, then the left stick held forward for 90 frames and back for 90, measuring Link's horizontal distance from `status`'s `pos`. 100, 150 and 200% were run interleaved, twice each, 4 holds per setting; the table shows the median (the holds agree within 0.6 m). Baseline: Run speed at 100% on the same build, interleaved with the other settings in one session; at 100% the scaling returns before touching the speed, so this is main's movement. How to reproduce: any save in Hyrule Field; Gameplay → Run speed at 100%, 150% and 200%; hold forward for 1.5 s at each. | | Before, Run speed 100%: this PR @ b402d18e | After, Run speed 150%: this PR @ b402d18e | After, Run speed 200%: this PR @ b402d18e | |---|---|---|---| | Link's distance per 90-frame hold (median of 4) | 6.29 m | 9.28 m (1.47x) | 12.11 m (1.92x) | ``` run_speed=100: 6.34 m forward, 6.29 m back run_speed=150: 9.28 m forward, 9.28 m back run_speed=200: 11.73 m forward, 12.14 m back run_speed=100: 6.29 m forward, 6.28 m back run_speed=150: 9.26 m forward, 9.27 m back run_speed=200: 12.07 m forward, 12.26 m back [hos BaseProcExecutor0] gameplay: run speed 150% [hos BaseProcExecutor0] gameplay: run speed 200% [hos BaseProcExecutor0] gameplay: run speed 100% ``` No frame-rate effect is expected: the change is a multiply on one float, made only when Link's controller sets its speed. ### Flags and settings One new menu row and ini key; the default leaves Link's speed unchanged. | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | Gameplay → Run speed; `run_speed` | Link's speed while steered, percent of his own | (none) | 100 (original) | 100 to 200% faster running, walking and swimming | Helps: crossing large areas. Doesn't change cutscenes, scripted walks or ledge climbs. Untested: Windows, every movement state (horseback with Epona, Iron Boots, climbing) | Ship at 100%; a player's choice | ## Testing **Tested:** - Linux (Ubuntu 26.04.1), RTX 4070 Ti, NVIDIA 595.99.02. I built this branch with `make_game.py` and ran it headless through the control bridge. Hyrule Field, the stick held at 100, 150 and 200%: numbers above, the log naming each change, no device loss or Vulkan error. The run is recorded in `docs/tested/2026-11-16-run-speed-trashpanda-field1.md`. The build was made on main 615b2498, just before this rebase onto 623a0ca3; the feature's code is the same. - The menu row rendered game-free with `scripts/screenshots`' fixture, extended locally to the Gameplay tab and not committed (picture in the first comment). - `python -I -B tests/run_all.py` on Linux: the new `tests/test_run_speed.py` and the checks it touches (`test_option_ids`, `test_movement_speed`, `test_menu_i18n`, `test_readme_menu_rows`, `test_camera_speed`, `test_oot_fov`, `test_menu_keys`, `test_tested_configurations`) pass. After the rebase onto 623a0ca3: 649 passed, 24 failed, 21 skipped. 23 of the 24 fail the same on main 623a0ca3 on this PC (`test_walk_key`, `test_damage_debug_menu`, `test_upscaler_rows`, `test_linux_preflight`, `test_make_game_cache` and others). The 24th, `test_crash_record`, failed only inside the full parallel run and passes alone, 3 runs of 3. **Not tested:** - Windows, AMD and Intel GPUs. The change is host C and menu code with nothing GPU-specific, but it has not run there. - Playing with the row by hand: Epona, Iron Boots, swimming, ledges, dungeons and boss rooms at 200%. Movement speed has the same scaling up to 3x, and the 15 m/s cap keeps the ledge-climb fling it once had away. **Must be tested:** - Windows, any GPU: open Gameplay → Run speed, set 150%, run across Hyrule Field, expecting Link visibly faster, the menu showing 150% after a restart, and `gameplay: run speed 150%` in `longshot_log.txt` (Test Farm: @Beanstalk windows, set Gameplay Run speed to 150% and run in Hyrule Field). ## Risks **What could break:** Link's movement while Run speed is above 100%: a room or puzzle timed around his running speed, or a narrow ledge he now overshoots. At 100%, the default, nothing changes: the scaling returns before touching the speed. **Turning it off:** Run speed at 100% (original), or revert the commit. **Compatibility:** A new `run_speed` line in `longshot_options.ini`; older builds ignore it. Saves, shader and pipeline caches and the vk ABI (`MKWVK_API_VERSION`) are unchanged. ## 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] Numbers from the same PC, scene and settings, at least 2 interleaved runs each, the median reported. - [x] Switches documented (docs/development.md; the README for a menu row) and shipped at their recommended value. - [x] Screenshots of the same spot, captioned like the Measurements columns, for a change that shows on screen. - [x] A file in `docs/tested/` for each new measured run (format in `docs/tested-configurations.md`). - [ ] Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. (Linux built; Windows left to CI's build, nothing platform-specific added) - [x] Docs updated.
Players who want Link to cross the world faster had only the Debug tab's
Movement speed: shown only with the debug tools on, in five fixed steps,
and back to 1x at each start. Gameplay's Run speed is a saved slider any
player can use.

- Gameplay -> Run speed, 100% to 200% in steps of 5, 100% (original) the
  default, saved as run_speed; it applies at once.
- host/hos_main.c: oot_player_speed takes the Debug tab's Movement speed
  when it is above 1x, else Run speed (HOS_OPT_RUN_SPEED, 96: 62 to 90
  are taken by open pull requests). The scaling is the one Movement speed
  already has: Link's controller only, only while he is steered, only up
  to 15 m/s, so cutscenes and ledge climbs keep their pace. The log says
  which row chose ("gameplay: run speed N%").
- The row's texts in the 13 menu languages; README and the options file
  table.
- tests/test_run_speed.py: the choice between the two rows, cut from the
  source and run, and the row, default, slider, saved key and README line.

The option callback answers the new id; MkwVkHost and MkwVkRenderer are
unchanged, so no MKWVK_API_VERSION bump.
docs(tested): Run speed measured in Hyrule Field (RTX 4070 Ti, Linux)
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) 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 6s
6733b16208
Author
Contributor

Tested in game: Linux (Ubuntu 26.04.1, kernel 7.0.0-43), RTX 4070 Ti, NVIDIA 595.99.02, headless through the control bridge: Hyrule Field (child), Run speed set to 100/150/200% twice each, the left stick held 90 frames forward and back. Median distance per hold 6.29 m / 9.28 m (1.47x) / 12.11 m (1.92x); the log named each change (gameplay: run speed N%); no device loss or Vulkan error. Built on main 615b2498 just before rebasing onto 623a0ca3 (same feature code).

Tested in game: Linux (Ubuntu 26.04.1, kernel 7.0.0-43), RTX 4070 Ti, NVIDIA 595.99.02, headless through the control bridge: Hyrule Field (child), Run speed set to 100/150/200% twice each, the left stick held 90 frames forward and back. Median distance per hold 6.29 m / 9.28 m (1.47x) / 12.11 m (1.92x); the log named each change (gameplay: run speed N%); no device loss or Vulkan error. Built on main 615b2498 just before rebasing onto 623a0ca3 (same feature code).
Author
Contributor

Gameplay → Run speed, this PR @ b402d18e, set to 150% (rendered game-free from the menu's own code with scripts/screenshots' fixture, extended locally to the Gameplay tab; not committed):

Gameplay tab, Run speed at 150%

Gameplay → Run speed, this PR @ b402d18e, set to 150% (rendered game-free from the menu's own code with `scripts/screenshots`' fixture, extended locally to the Gameplay tab; not committed): ![Gameplay tab, Run speed at 150%](https://git.magicbean.dev/attachments/9b1a6c6e-a798-4db5-958f-e8867715d5e0)
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: an in-game run on Linux, RTX 4070 Ti, through the control bridge, with a matching author comment.
  • Nothing gets worse that I know of: ticked: Measurements shows the 100% baseline unchanged, and the risks named are gameplay effects, not speed or memory.
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: an in-game run on Linux, RTX 4070 Ti, through the control bridge, with a matching author comment. - *Nothing gets worse that I know of*: ticked: Measurements shows the 100% baseline unchanged, and the risks named are gameplay effects, not speed or memory.
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) 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 6s
This pull request has changes conflicting with the target branch.
  • gpu/vk/menu_i18n.h
  • gpu/vk/vk_api.h
Some workflows are waiting to be reviewed.
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/run-speed:TrashPanda-feat/run-speed'
git switch 'TrashPanda-feat/run-speed'
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!1231
No description provided.