# First-person character (character.first_person)

## What it is for

The player on foot, seen through its eyes: the same kinematic capsule as the third-person character (walk, run, jump, vehicles),
with a free look. The pointer or the right stick turns the head, the body faces where the eyes look and movement follows the look.
It owns the entity tagged `player` and provides `character.control`. For the choice between character kits, the shared services and
the hooks, see the [character guide](guide:character).

## Turn it on

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "character.first_person" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "character.first_person",
                              config: { "eyeHeight": 1.7, "fov": 80 } }
```

It requires `input.actions`, `world.ground`, `physics.character`, `physics.port` and `game.engine`, and conflicts with the other
controlled-character kits. With `input.pointer_lock` installed, the mouse is captured for the look.

## First example

<!-- test: kits/character_first_person/tests/character_first_person.rs::the_pointer_turns_the_head_right_and_down -->
Feed the look with pointer pixels and read where the eyes point (here `lookSensitivity` is 0.01):

```text
camera.look.add(100, 50)    -> yaw() = -1, pitch() = -0.5   (right turns the head right, down looks down)
character.control.lookYaw() -> -1                           (the aim of a shooter)
```

## Settings and defaults

| Setting | Default | Meaning |
|---|---|---|
| `walkSpeed` / `runSpeed` | 4 / 7 | metres per second |
| `jumpImpulse` | 5 | vertical take-off speed |
| `eyeHeight` | 1.62 | height of the eyes above the feet, metres |
| `fov` | 72 | vertical field of view, degrees |
| `lookSensitivity` | 0.0024 | radians turned per pointer pixel |
| `stickLookSpeed` | 2.4 | radians per second at full right stick |
| `pitchLimit` | 85 | how far up and down the head tilts, degrees |
| `actionLayers` | `{}` | animation layers by action family; empty keeps the defaults |

Inputs: `look_x`, `look_y`. There is no double jump in first person.

## Services, events, variables

- `character.control` (service): `player()`, `position()`, `lookYaw()`, `pitch()`, `speed()`, `detach`, `attach`, `teleport`, `hold(owner)`.
- `camera.first_person` (service): `yaw()`, `pitch()`, `eyeHeight()`, `fov()`, `add(dx, dy)`.
- `camera.look` (service): `add(dx, dy)`, `yaw()`, `pitch()`, `setYaw(yaw)`.
- Events: `player.moved` (10 Hz while moving), `player.jumped`, `player.action`, `player.pushed`; it listens to `vehicle.entered` and `vehicle.exited`.
- Variables: `player.speed`, `camera.mode`, `camera.pitch`.

## Hooks and modding

Hooks `character.jump` (mutable `speed`), `character.respawn` (mutable `x`, `y`, `z`) and `character.action` (mutable `movement`,
`moveScale`), all cancellable, with the payloads of the [character guide](guide:character). Moddable settings: `actionLayers`,
`walkSpeed`, `runSpeed`, `jumpImpulse`, `eyeHeight`, `fov`, `pitchLimit`; `lookSensitivity` and `stickLookSpeed` are the comfort of
the person playing and are not moddable.

## Limits

The player model is not drawn through its own eyes; it shows to others, in a mirror or in a vehicle. Same Rust rules on the web and
in the native player; Godot, Unity and Unreal do not run this kit yet.

## Versions

Kit 1.8.0; services `character.control`, `camera.first_person` and `camera.look` 1.0.0 (`setYaw` since camera.look 1.5.0).