# Top-down character (character.top_down)

## What it is for

The player seen from above: an isometric follow camera, movement relative to the world on `move_x` / `move_y`, aim from the pointer
(or the nearest enemy in front, or the heading) and a motor other kits use to lock, push or turn the body (attacks, dashes,
staggers). It owns the entity tagged `player` and provides `character.control`. For the choice between character kits and the
shared hooks, see the [character guide](guide:character).

## Turn it on

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "character.top_down" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "character.top_down",
                              config: { "moveSpeed": 7, "cameraProjection": "orthographic", "aim": "pointer" } }
```

It requires `input.actions`, `world.ground`, `physics.character`, `physics.port` and `game.engine`, and conflicts with
`character.third_person`. Optional: `input.scheme` (click to move) and `ai.navigation` (routes around walls and through doors).

## First example

<!-- test: kits/game_engine/host/tests/physics_async_lot1.rs::the_top_down_character_stands_and_holds_its_state_on_its_loop -->
With a floor and two walls at x = +-5.5, holding `KeyD` then `KeyA` moves the character sideways; the walls stop it before
5.5 m, the floor holds it, and it never falls through.

## Settings and defaults

| Setting | Default | Meaning |
|---|---|---|
| `moveSpeed` / `acceleration` | 7 / 60 | walk speed (m/s) and how fast the body reaches it (m/s²) |
| `turnSpeed` | 18 | turn rate of the body toward the move or aim direction, rad/s |
| `aim` | `auto` | `auto`: the pointer when the host publishes `aim.point`, else the nearest enemy in front, else the heading; or `pointer`, `move` |
| `aimAssistRange` / `aimAssistCone` | 7 / 100 | assist range (m) and cone (degrees) |
| `cameraYaw` / `cameraPitch` | 45 / 55 | degrees around the vertical axis, and below the horizon |
| `cameraDistance` | 22 | metres from the target |
| `cameraProjection` | `perspective` | or `orthographic` (then `cameraViewHeight` is the visible world height; 0 derives it) |
| `cameraFov` / `cameraSmoothing` | 0 / 0.125 | lens (0: the renderer's); follow softness in seconds (0 follows rigidly) |
| `cameraTargetOffset` | `[0, 0, 0]` | moves the framed point, in world axes |
| `clickArrive` / `clickReach` | 0.3 / 1.6 | click to move: stop distance, and reach before attacking or using the clicked entity |
| `clickPath` / `clickBlocked` / `clickRepath` | `navigation` / `straight` / 0.5 | route with `ai.navigation` (or `straight`), what to do when the point is unreachable (`straight` or `stop`), replan distance |
| `actionLayers` | `{}` | animation layers by action family; empty keeps the defaults |

## Services, events, variables

- `character.control` (service): `player()`, `position()`, `teleport`, `attach`, `detach`.
- `character.motor` (service): `aimYaw`, `aimTarget`, `face`, `lock`, `push`, `setSpeedFactor`, `moveDir`.
- `camera.top_down` (service): target, yaw, pitch, distance, shake.
- Events: `player.action`, `player.moved` (10 Hz), `player.pushed` (dash, lunge, knockback); it listens to `room.entered`.
- Variables: `player.speed`, `camera.mode`, `camera.projection`, `camera.viewHeight`, `camera.fov`, `camera.smoothing`, `aim.yaw`.

## Hooks and modding

Hooks `character.action` (mutable `movement`, `moveScale`), `character.push` (mutable `distance`, 0 means no push) and
`character.respawn` (mutable `x`, `y`, `z`; reasons `scene`, `instance`, `spawn`), all cancellable, with the payloads of the
[character guide](guide:character). Every setting above is moddable.

## Limits

No free look and no first-person view. Hooks run on the web and in the native player; Godot, Unity and Unreal receive the kit as
files and push and place the player without them. An unbound player model is a capsule: bind a rigged hero asset.

## Versions

Kit 1.10.0 (animation layers and `character.action`); the camera lens, offset and smoothing keys arrived in 1.7.0 to 1.9.0; click
routes with `ai.navigation` in 1.6.0.