# Strategy camera (camera.strategy)

## What it is for

The camera of a top-down game (MOBA, RTS, strategy), with no interface of its own. It follows the player, or is free; it recentres on a respawn or when the player entity is replaced; it can peek at a point of the map (a minimap click, a ping) and come back; it pans with the screen edge and with the keyboard axes `camera.pan_x` and `camera.pan_y` (which free it from the hero) and zooms between `minDistance` and `maxDistance`. It knows nothing of the rules of the game, and the engine draws the view. It requires `camera.top_down`, `world.ground`, `input.actions` and `game.engine`.

## Turn it on

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "camera.strategy" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "camera.strategy", config: { "panSpeed": 40, "maxDistance": 80 } }
```

## First example

<!-- test: kits/game_engine/host/tests/parity.rs::rust_host_matches_the_typescript_traces (fixture camera.strategy.modes) -->
This replay (a recorded trace the host checks on every run) shows the modes: the camera starts following at the origin, follows the player entity as it moves, `lookAt` frees it and clamps to the default bounds of ±100, `recenter` follows again, and `peekAt` looks at a point while staying in follow mode until `endPeek`.

```text
snapshot()           -> { "mode": "follow", "focus": [0, 0], "peeking": false, ... }
player created at (5, 7), one tick      -> focus [5, 7]      player moved to (-12.5, 3) -> focus [-12.5, 3]
lookAt(20, 30)       -> mode "free", focus [20, 30]          lookAt(500, -500) -> focus [100, -100]
recenter()           -> mode "follow", focus on the player   peekAt(10, 10) -> peeking true, focus [10, 10], mode "follow"
```

## Settings and defaults

| Setting | Default | Meaning |
|---|---|---|
| `edgePan` | `true` | Screen-edge panning on (it applies in free mode, or in follow mode with `edgePanInFollow`) |
| `edgeSize` | 18 | Width of the screen edge that pans, in pixels (4 to 60) |
| `edgePanInFollow` | `false` | Lets the screen edge unlock follow; off by default, so entering free mode is explicit |
| `recenterOnRespawn` | `true` | Follow the player again when revived or replaced by a new player entity |
| `panSpeed` | 32 | Pan speed (5 to 120) |
| `minDistance` | 24 | Closest zoom distance (5 to 100) |
| `maxDistance` | 60 | Farthest zoom distance (5 to 150) |
| `zoomSpeed` | 0.12 | Zoom step per wheel unit (0.01 to 1) |

A game or a mod may change all eight settings. The kit has no hook and emits no event: it publishes variables.

Input actions: `camera.recenter` (Space) follows the hero again, `camera.toggleFollow` (Y) switches between follow and free, and the axes `camera.pan_x` and `camera.pan_y` pan the camera and free it from the hero. The axes have no key by default, so an existing game keeps its arrow keys; the click-to-move and strategy control schemes bind them to the arrows, and the player can remap them.

## Services

- `pan(x, y)` sets the pan intent from -1 to 1 on each axis (ignored in follow mode unless `edgePanInFollow`); `lookAt(x, z)` centres on a point and frees the camera; `peekAt(x, z)` looks at a point without leaving follow mode and `endPeek()` comes back.
- `recenter()` follows the player again, `toggleFollow()` switches between follow and free, and `zoom(delta)` zooms (the delta is limited to -3..3, scaled by `zoomSpeed`, and the distance is kept between `minDistance` and `maxDistance`).
- `setViewport(points)` hands the screen corners projected on the ground, for a minimap rectangle, and `snapshot()` answers `{ mode, peeking, focus, distance, edgeSize, edgePan, viewport }`.

Published variables: `camera.focus` (`[x, groundY, z]`, what the view looks at), `camera.control` (`follow` or `free`) and `camera.distance`. The camera stays inside the bounds of `moba.match.map().camera`, else those of `world.ground.bounds()`, else ±100. It listens to `player.died` to remember a death even when the revival comes before the next camera tick.

## When it does not do what you expect

- The camera does not move with the screen edge: it is in follow mode (set `edgePanInFollow`, or free it with `toggleFollow()`), or `edgePan` is off.
- The arrow keys do nothing: the axes `camera.pan_x` and `camera.pan_y` have no key until a control scheme or the game gives them one.

## Limits

- The kit moves the view point and publishes it; it draws no screen, no minimap and no selection, and it ignores the rules of the map. It is for top-down games and targets the web and native players.

## Versions

1.3.0 (2026-10-10): extension contract of `game.engine` 1.2, all settings moddable; 1.2.0: keyboard pan axes; 1.1.0: follow stays locked at screen edges, recentre on respawn; 1.0.0 (2026-10-04): first release.