Add opt-in Ocarina of Time developer debug tools #785

Merged

ArmstrongThomas merged 5 commits from codex/oot-debug-tools into main

2026-11-09 02:44:07 +00:00

ArmstrongThomas commented

2026-11-08 21:06:49 +00:00

(Migrated from github.com)

What this adds

An opt-in Ocarina of Time developer debug panel for reproducing gameplay and rendering issues. It can move Link or the camera to inspect a scene, return Link to a marked position, travel to another map, switch Link's age, edit his inventory, and set up time-of-day or damage test cases.

Player movement gives Link camera-relative no-clip flight with gradual acceleration, braking, and turning. Enable No-clip flight in the panel to allow double-tap Jump to take off or land. Switching the setting off disables the shortcut and ends flight. Hold Jump to climb, or use L or Page Down to descend.
Free camera routes movement and look input to the view while Link stays in place.
Scene setup adds a same-scene position mark and return, a world-clock control, and quantity adjustments for supported consumables.
Heart protection preserves health while retaining hit reactions and knockback.
Teleport travels to another map through the game's own map change: it requests the same Dm_SY_BancChangeGo event an entrance uses, with the destination map, spawn anchor and arrival event, picking the child or adult map from Link's current age. Destinations: 19 overworld areas (Kokiri Forest through Desert Colossus, including Lake Hylia) and 12 dungeons; Hyrule Castle is Ganon's Castle grounds as an adult and Gerudo Fortress is adult only. Enter on the Teleport row opens a list page grouped into Overworld and Dungeons. Requests are refused while an event plays or a map loads.
Switch age flips the game's Sequence_IsChildhood flag, as the Temple of Time does, and reloads the current map in the other age through the same map change (the Market when the current map is not in the teleport list). The flag is restored if the map change cannot be requested. The Temple of Time event's equipment swap is not reproduced.
Inventory opens a list of about 85 pouch contents in five sections (Equipment, Items, Masks, Upgrades, Quest) with live counts read from the game twice a second. Enter unlocks a missing item or relocks a held one, and Left/Right change amounts. Edits go through the game's own OneShotAddOrRemovePouchContent; counts come from QueryGetPouchContentNumByActorName. Masks share one slot as in the game, so choosing a mask first returns the one held. The item list lives in gpu/vk/oot_cheat_items.h, shared by the menu and the game side.
List navigation: the list pages show 20 rows; holding an arrow or the D-pad repeats with acceleration, Page Up/Down jump a screen, Home/End go to the ends, and Q/E or the bumpers jump between sections.

The panel is hidden by default. On Windows, add HOS_OOT_CHEATS=1 to hookshot_env.txt, then open Insert → Gameplay → Cheats. The translated hooks are gated to the supported OOT build (e0f3ccfa). Flight, free camera, and the position mark reset at exit.

Validation

The local Windows build linked successfully.
On a copied Sacred Grove save, verified Jump-to-climb, descent, opposite headings, forward movement after rotating the camera, and landing after disabling flight.
Verified free-camera movement with Link stationary, return to a marked position, and a consumable edit that survived saving and restarting. The game clock read back the selected hours.
The double-tap shortcut was confirmed in gameplay by the local tester.
The tester tried a handful of the 31 teleport destinations. Each reached the intended area, though some arrival spots could be improved. The full destination list still needs coverage.
The tester confirmed that Switch age and the inventory editor worked. An edited item count may take until the next refresh to appear.
Heart protection was checked in gameplay. Linux runtime coverage is outside this implementation.

## What this adds An opt-in Ocarina of Time developer debug panel for reproducing gameplay and rendering issues. It can move Link or the camera to inspect a scene, return Link to a marked position, travel to another map, switch Link's age, edit his inventory, and set up time-of-day or damage test cases. - **Player movement** gives Link camera-relative no-clip flight with gradual acceleration, braking, and turning. Enable No-clip flight in the panel to allow double-tap Jump to take off or land. Switching the setting off disables the shortcut and ends flight. Hold Jump to climb, or use L or Page Down to descend. - **Free camera** routes movement and look input to the view while Link stays in place. - **Scene setup** adds a same-scene position mark and return, a world-clock control, and quantity adjustments for supported consumables. - **Heart protection** preserves health while retaining hit reactions and knockback. - **Teleport** travels to another map through the game's own map change: it requests the same `Dm_SY_BancChangeGo` event an entrance uses, with the destination map, spawn anchor and arrival event, picking the child or adult map from Link's current age. Destinations: 19 overworld areas (Kokiri Forest through Desert Colossus, including Lake Hylia) and 12 dungeons; Hyrule Castle is Ganon's Castle grounds as an adult and Gerudo Fortress is adult only. Enter on the Teleport row opens a list page grouped into Overworld and Dungeons. Requests are refused while an event plays or a map loads. - **Switch age** flips the game's `Sequence_IsChildhood` flag, as the Temple of Time does, and reloads the current map in the other age through the same map change (the Market when the current map is not in the teleport list). The flag is restored if the map change cannot be requested. The Temple of Time event's equipment swap is not reproduced. - **Inventory** opens a list of about 85 pouch contents in five sections (Equipment, Items, Masks, Upgrades, Quest) with live counts read from the game twice a second. Enter unlocks a missing item or relocks a held one, and Left/Right change amounts. Edits go through the game's own `OneShotAddOrRemovePouchContent`; counts come from `QueryGetPouchContentNumByActorName`. Masks share one slot as in the game, so choosing a mask first returns the one held. The item list lives in `gpu/vk/oot_cheat_items.h`, shared by the menu and the game side. - **List navigation**: the list pages show 20 rows; holding an arrow or the D-pad repeats with acceleration, Page Up/Down jump a screen, Home/End go to the ends, and Q/E or the bumpers jump between sections. The panel is hidden by default. On Windows, add `HOS_OOT_CHEATS=1` to `hookshot_env.txt`, then open **Insert → Gameplay → Cheats**. The translated hooks are gated to the supported OOT build (`e0f3ccfa`). Flight, free camera, and the position mark reset at exit. ## Validation - The local Windows build linked successfully. - On a copied Sacred Grove save, verified Jump-to-climb, descent, opposite headings, forward movement after rotating the camera, and landing after disabling flight. - Verified free-camera movement with Link stationary, return to a marked position, and a consumable edit that survived saving and restarting. The game clock read back the selected hours. - The double-tap shortcut was confirmed in gameplay by the local tester. - The tester tried a handful of the 31 teleport destinations. Each reached the intended area, though some arrival spots could be improved. The full destination list still needs coverage. - The tester confirmed that Switch age and the inventory editor worked. An edited item count may take until the next refresh to appear. - Heart protection was checked in gameplay. Linux runtime coverage is outside this implementation.

❤️ 1

hckrman101 (Migrated from github.com) approved these changes

2026-11-09 02:26:25 +00:00

shayderrr commented

2026-11-09 02:44:03 +00:00

(Migrated from github.com)