Skip to content

feat(gameplay): a first-person mode - #96

Open
ToxicToucan wants to merge 12 commits into
Sacrappy:mainfrom
ToxicToucan:pr/first-person
Open

ToxicToucan wants to merge 12 commits into
Sacrappy:mainfrom
ToxicToucan:pr/first-person

Conversation

@ToxicToucan

@ToxicToucan ToxicToucan commented Nov 19, 2026 •

Copy link
Copy Markdown

#95 (the free-camera fix this builds on) is merged, so this PR now holds only the first-person changes. It's ready for review; the known limits are listed at the end.

What it does

This adds a Gameplay row, First person, which is off by default. It plays from Link's eyes:

  • The right stick, the camera keys and the mouse look around.
  • Link walks the way you look.
  • His face, eyes, eyebrows, eyelashes, teeth and hair are hidden.

While the Free camera is on, it takes over.

How it's built

  • View: first person is a mode of the free view. hos_oot_free_view is called every frame by fix(gameplay): the free camera never moved the view (patch_view finds 0 sites) #95's lift-time hook.
    • The eye sits at Link's eye height: 1.15 m as a child, 1.55 m as an adult. It sits 0.35 m out along the look, starting from his facing.
    • nn_hid.c gives the right stick to the view instead of the game's camera. The game reads the left stick against this view, so walking follows the look.
  • Head hiding: this takes the same path as the game's own AI node OneshotModelSetMaterialVisible (its execute is at main+0x29637f0).
    • For each of Link's models, vtable +208 gives a material index by name, and vtable +456 shows or hides it. Both are called as guest functions.
    • It re-applies every 0.5 s while on, because loads and age or tunic changes make new models. Turning it off shows everything again.
  • In the air: the eye eases out to 0.7 m while Link's height changes faster than 2.5 m/s, so his jump pose and flying hair stay behind it.
  • Mouse: in first person the mouse always takes the native one-to-one path. That's 0.1° per count at the menu's sensitivity, inverted as set. The player camera's hook leaves the motion to the view.
  • Near plane: nx2/oot_near.py adds a lift-time hook after the camera's near load (main+0x4c52d4, ldr s0,[x19,#0x134], its three words checked).
    • hos_oot_near lowers it from 10 cm to 5 cm on the gameplay camera, only in first person and outside events.
    • The camera's own field is never written.

Testing

  • One windowed run, Market save, on Windows with an RTX 4090.
    • The log shows 22 head materials hidden (both model slots), first person: view at …, and near plane 0.100 -> 0.050 m.
    • Screenshots show an eye-level Market with no Link in view. Looking down shows no hair, hat or head.
    • Game speed was 1.000. The run's 2 flashes happen at the area change and match the stock build's.
  • Tests:
    • 55 of the 56 upstream tests that read the changed files pass. test_udmabuf_limit_unreadable also fails on the base, because of O_CLOEXEC with a Windows compiler.
    • test_input_background now takes the HL_OPT_* ids from vk_opt_ids.h.
    • py_compile passes on the nx2 files.

Update: the head bone

Two commits are new:

  • f936d1bc: in first person, Link's Head bone (bone 103 of 309) is scaled to 0 on every player update. Head, hair and hat then vanish through skinning, and the eye moves to 0.10 m.
    • Looking ahead, nothing of the head or hat shows.
    • Looking down after a sword swing, Link's arm, hand and Deku Shield are in view, with his shadow.
  • 18dd5aaf: the view waits until the head is hidden, so leaving the Free camera no longer flashes the cap for a frame.

The Free camera also checked out in two runs: it takes the view and hands it back.

Update: Navi

  • 2798374c, Navi stays out of the eye: in first person her body and wings are hidden. She's a second actor of Link's class beside him. She's found from Link's own pointers, with checks before any call, and only her winged models are touched. After a scene load she's looked for again. She's shown again when first person is off, and her small light glow stays.
  • Checked in game: a test build (not part of this PR) toggled the hide every 5 s in third person. The screenshots alternate between Navi drawn and only her glow left. Link is unchanged, and the frame rate is the same as without it.

Known limits

  • There's no crosshair of its own; aiming items switch to the game's own aim camera.

CI fix (2155880c): host/mouse_native.c no longer includes gpu/vk/vk_api.h. It names the option ids by number, as it already does for others, and tests/test_mouse_native.py checks that those numbers match the renderer's headers.

🤖 Generated with Claude Code

codex and others added 10 commits November 19, 2026 00:36
…era takes the view

nx2/oot_patches.py's patch_view finds the loop head of f_804e48c0 0 times ("the free camera was found 0 times" in every
build log, stock 9f725aa included), so hos_oot_free_view never ran and the free camera never moved the view.
nx2/oot_view.py puts the same call after the instruction at that loop head instead (main+0x4c5068, its three words
checked): the view's matrix at view+8 is complete there and x20 is the view. patch_view counts a function that already
has the call as found and adds no second one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A Gameplay row, First person (off by default; HL_OPT_FIRST_PERSON, 91 in vk_opt_ids.h). While it is on, the free view
(hos_oot_free_view, host/hos_main.c) builds the gameplay view from Link's eyes instead of the free camera's eye: 0.35 m
out from his head along the look, turned by the right stick from his facing; host/nn_hid.c gives the right stick to the
view and not to the game's camera. Link walks as ever, the stick read against this view. The free camera, while on, takes
its place.

The player's update keeps his place, facing and eye height (1.15 m as a child, 1.55 m as an adult) and hides his head
the way the game's own AI node OneshotModelSetMaterialVisible does (its execute at main+0x29637f0): through his models'
vtable +208 (a material's index by name) and +456 (show or hide it), called as guest functions. The face, eyes, eyebrows,
eyelashes, teeth, front hair and the hair model go; the hat is part of the tunic's material and stays. They are hidden
again every half second while it is on (a load or a change of age or tunic makes new models) and shown again when off.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
His jump pose leans the head forward and his hair flies up, past the first-person eye's 0.35 m: while his height changes
faster than 2.5 m/s the eye eases out to 0.7 m (80 ms), and back after he lands (400 ms). Read from his height over time,
so it needs no game state.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
With the Mouse camera on Native, the player camera's hook (host/mouse_native.c) leaves the mouse's motion to the
first-person view while it is on, still counting as run so the right stick is not given it too, and the view takes it
one to one (hos_mouse_first_person: 0.1 degrees a count at the menu's sensitivity, Invert mouse vertical as ever). With
the mouse as the right stick, and with the camera keys, the view already turned: they are the right stick.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
While first person is on, the mouse goes the native way whatever the Mouse camera row says (host/nn_hid.c and
host/mouse_native.c native_on), so the view turns by the mouse's counts, not by a stick made of them; the right stick
and the camera keys still turn it as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
nx2/oot_near.py hooks the camera update after it loads its near distance (main+0x4c52d4, ldr s0, [x19, #0x134]; its three
words checked), and host/hos_main.c hos_oot_near lowers that load to 5 cm at most (the game's is 10 cm) on the gameplay
camera while first person is on and no event plays, so what is just in front of the eye is not cut off. The camera's own
field is never written.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…idden again

Turned on, or back from the free camera, the first-person view took over at once while the head was hidden only at the
player's next update: one frame showed the cap from inside (a one-frame flash at the free camera's end, dev-fp2 present
6648). The view now waits for that update (fp_head_ready), showing the game's own view meanwhile.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…y and what he holds come into view

While first person is on, every player update sets the Head bone's local scale to 0 on each of his models, through the
model's own calls: vtable +0x48 names a bone by index (the skeleton's resource dictionary), +0x60 (model, &scale, index;
main+0x3596360) sets its local scale, as the animation does. The hat is part of the tunic's mesh (Head_Band__Mt_Cloth,
90 skin bones) and every shape hangs from bone 0, so only the skinning can take it with the head: the head, hair and
hat go together. The eye then sits 0.10 m out instead of 0.35 m (HL_FP_EYE_OUT), so looking down shows his arms, his
hands and what they hold. HL_FP_HEAD_BONE=0 leaves the bone alone (the materials are hidden as before).

Checked in one run (Market, first person on, with the flash and speed checks): the Head bone found (103 of 309) and
scaled every update; looking ahead nothing of the head or hat in view; looking down his arm, hand and Deku Shield in view.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…without the renderer's headers

host/mouse_native.c included gpu/vk/vk_api.h and vk_opt_ids.h for two option ids. The
mouse test compiles the file alone in a temp folder, where those headers are not, so it
failed on Linux ("../gpu/vk/vk_api.h: No such file or directory"). The file now names the
two ids by number, as it already does the Mouse camera (6) and Invert mouse vertical (8),
and the test checks them against the renderer's headers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ToxicToucan ToxicToucan changed the title feat(gameplay): a first-person mode (draft, stacked on #95) feat(gameplay): a first-person mode Nov 20, 2026
@ToxicToucan
ToxicToucan marked this pull request as ready for review November 20, 2026 04:35
ToxicToucan and others added 2 commits November 20, 2026 09:10
v0.4.3 gives 91 to the Frame generation multiplier and 92/93 to V-Sync mode and the VRR
cap, so the First person row's id moves from 91 to 120 (vk_opt_ids.h; mouse_native.c's
literal and its test follow). Options are saved by row name, so options files are
unaffected. vk_replay.cpp keeps both sides' option answers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
She hovers by Link's head, so in first person her glowing body and wings filled the view.
Here she is a second actor of Link's own class beside him, whose models carry Mt_Wings
(Link's own models have none). She is found from Link's own pointers (his actor and
components, one step further), each candidate checked before anything is called on it:
in the heap, a vtable in main, a model component of Link's class, within 5 m of Link,
then a look-up-only query for Mt_Wings. While first person is on, her materials
(Mt_Body, Mt_Body_AlphaMask, Mt_Wings) are hidden on that actor's winged models only;
shown again when it is off. A lost actor (a scene load) is looked for again. Her small
light glow stays.

The head's material code becomes one function for any list of names
(fp_set_materials_on, with an optional "only models with this material" filter).

Checked in game (Windows, Market save): with the hide toggled every 5 s in third person,
screenshots alternate between Navi drawn and only her glow left; Link is unchanged; no
frame-rate change against the same run without it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants