@spawnite/engine 0.1.0-beta.15

package/dist/wiki/engine/entities/camera.md

@@ -0,0 +1,326 @@
+---
+title: Camera
+description: The camera, following or chasing the player, from the side, orbiting free or flying.
+useCases:
+    - third person camera
+    - camera follows the player
+    - first person view
+    - over the shoulder camera
+    - zoom the camera
+    - field of view setting
+    - side view camera
+    - camera shake
+    - fly camera
+    - top down camera over the map
+sidebar:
+    order: 3
+---
+
+`<Camera>` mounts the one camera inside a [World](/engine/structure/world/), with Roblox's defaults: third person, an orbit the player drags with the right button or one finger, and a zoom on the wheel or two fingers, within the engine's distance and tilt bounds. The wheel zooms all the way in to first person, and Shift turns a lock that captures the cursor. What it keeps in frame is `follow`, the player unless given.
+
+Its props are in [`CameraProps`](https://wiki.spawnite.com/reference/camera/cameraprops/).
+
+## Presets and knobs
+
+A game picks a preset, and any knob it passes as a prop wins over the preset's. Roblox gives a game the same kind of switches: a camera mode, the zoom distances, whether shift lock is allowed, and a click-to-move mode. Unity and Unreal ship a rig for the game to build on instead.
+
+| Preset                 | Orbit on          | First person | Shift lock | Starts locked | Click-to-walk | Framing           |
+| ---------------------- | ----------------- | ------------ | ---------- | ------------- | ------------- | ----------------- |
+| `CameraPreset.Default` | right button drag | yes          | yes        | no            | no            | the engine's      |
+| `CameraPreset.Shooter` | right button drag | yes          | always on  | yes           | no            | over the shoulder |
+| `CameraPreset.Classic` | left button drag  | no           | no         | no            | yes           | the engine's      |
+
+The shooter preset frames her over her right shoulder, as Marvel Rivals and Fortnite do:
+
+- The aim sits 0.45 m above her eyes, above her head, and 0.55 m to her right. At level aim the eye stands about 0.1 m over the top of the warden's hair and looks past her head, so her head sits below and left of the crosshair.
+- The eye starts 2.75 m back, looking 10 degrees down.
+- The camera sees 102 degrees across a 16:9 screen, Roblox's 70 top to bottom.
+- A pixel of mouse travel turns the camera half a degree, and tilts it 0.77 as far, as Roblox's does.
+
+The default and classic presets keep Roblox's framing, the aim level with her eyes, and see 80 degrees across a 16:9 screen. Roblox's level framing suits its blocky rigs; on an avatar with tall hair it puts the eye below the top of her head at level aim, looking up at her.
+
+A free orbit, `follow={null}`, has no lock, no first person and no Play menu whatever its preset, since it follows no one to lock onto or look out of; a knob passed as a prop still turns one on.
+
+The knobs are the following props:
+
+- `minDistance` and `maxDistance`: the zoom's near and far stops in third person, 0.7 m and 9 m in every preset.
+- `fieldOfView`: the degrees the camera sees across a 16:9 screen, 102 in the shooter preset and 80 in the others. [Field of view](#field-of-view) says how the player's setting takes its place.
+- `minFieldOfView` and `maxFieldOfView`: the narrowest and widest the player's Field of view goes in this game, 60 and 120 in every preset.
+- `fixedFieldOfView`: whether the camera keeps `fieldOfView` whatever the player sets. Off in every preset.
+- `minPolarAngle` and `maxPolarAngle`: the tilt's stops, in radians from straight up, so 90 degrees is level. Every preset lets the player look 80 degrees up and 80 degrees down, as Roblox's camera does: `minPolarAngle` is 10 degrees, and `maxPolarAngle` is 170. A game that wants a tighter limit passes a smaller `maxPolarAngle`, such as `MathUtils.degToRad(90 + 60)` to look at most 60 degrees up, or a larger `minPolarAngle` to look less far down.
+- `firstPersonMinPolarAngle` and `firstPersonMaxPolarAngle`: the same stops in first person, 1 and 179 degrees from straight up in every preset, so the player looks 89 degrees up and down, as Source and Unreal allow. They stop short of 90, because straight up leaves the eye no sideways direction and a turn there spins the view. Out of first person past third person's stops, the eye glides back to them.
+- `bodyNearEye`: what the camera does with her body when the eye comes close to it, as [Close to her](#close-to-her) says. `BodyNearEye.Fade` in every preset, `BodyNearEye.Hide` to hide her, or `BodyNearEye.Off` to leave her drawn.
+- `eyeHeightFraction`: how far up her height the aim sits at the near stop, as a fraction of her measured height, 0.78 in every preset. A fraction frames every avatar alike, whatever its height.
+- `shoulderOffset`: the metres right of her the aim moves while the lock is on, 0.55 in the shooter preset and 0.49, Roblox's 1.75 studs, in the others. A negative value moves it to her left.
+- `pivotRise`: the metres above her eyes the aim rises while the lock is on, 0.45 in the shooter preset and none in the others.
+- `lookSpeed`: the radians a pixel of mouse travel turns the camera while the cursor is captured: half a degree in the shooter preset, and a full turn across 1,600 pixels in the others. A pixel tilts the camera 0.77 as far as it turns it, as Roblox's does. The player's Camera sensitivity multiplies it, and Invert vertical look flips its vertical half. The engine asks for raw mouse input with the lock, so the system's pointer acceleration never bends it.
+- `firstPerson`: whether a wheel notch in at the near stop puts the eye in her head.
+- `lockToggle`: whether Shift turns the lock on and off.
+- `startLocked`: whether the lock is on from the start, so the Play menu shows first.
+- `freeCursorKey`: the key that frees the cursor while held, as [Panels that free the cursor](#panels-that-free-the-cursor) says. No preset sets one.
+- `clickToWalk`: whether a click on the ground walks her there. A press that travels more than 5 pixels or lasts longer than 0.4 s turns the camera instead.
+
+`distance` sets the metres from her the eye starts at, clamped between the stops. The wheel moves it from there, and a changed `distance` moves the eye there. `pitch` sets the degrees the eye starts looking down, negative for up. Without them, the eye starts at the preset's start, 2.75 m back and 10 degrees down for the shooter, or where the last scene's camera stood for the others, within the stops.
+
+A shooter framed closer and wider than the preset, over a shoulder further out:
+
+```tsx
+import { Camera, CameraPreset } from "@spawnite/engine";
+
+export function ShooterCamera() {
+    return (
+        <Camera
+            preset={CameraPreset.Shooter}
+            fieldOfView={100}
+            shoulderOffset={0.8}
+            distance={3}
+        />
+    );
+}
+```
+
+An orbit on the left button's drag, with no click-to-walk, is the classic preset with one knob laid over it:
+
+```tsx
+import { Camera, CameraPreset, CharacterSpawn, World } from "@spawnite/engine";
+
+export function Run() {
+    return (
+        <World map="meadow">
+            <CharacterSpawn />
+            <Camera preset={CameraPreset.Classic} clickToWalk={false} />
+        </World>
+    );
+}
+```
+
+## Field of view
+
+The camera's field of view is the degrees it sees across a 16:9 screen, as PC shooters show theirs: Overwatch and Call of Duty measure their figure across 16:9, and Valorant, Apex and Destiny also give the player a figure across. The engine converts it to three.js's `fov`, which is the degrees top to bottom.
+
+A landscape screen of any other shape keeps the height a 16:9 screen sees, and widens or narrows at the sides. At 90, a 16:9 screen sees 59 degrees top to bottom, and a 21:9 screen sees the same 59 and 105 across, so an ultrawide sees more at the sides and never less above and below. Unity, Godot, Roblox, PlayCanvas, three.js and Call of Duty keep the height the same way.
+
+A screen held upright, taller than wide, keeps that same angle across its short side, so its long side sees the figure: 90 top to bottom on a 9:16 phone, and more on a taller one. The screen's shape is read again each time it changes.
+
+The shooter preset sees 102 degrees across, Roblox's lens of 70 top to bottom at 16:9, so a player who comes from Roblox sees the world as wide as there. Other third-person shooters sit narrower, between 80 and 90: Fortnite shows 80, Gears 5 opens at 80, and Marvel Rivals holds 90. A player who wants theirs sets it in Settings. The default and classic presets see 80 across, about three.js's 50 top to bottom on a 16:9 screen.
+
+The player's Field of view setting, on the Settings panel's Video tab, takes the place of the game's figure, within the game's `minFieldOfView` and `maxFieldOfView`. The setting starts empty, which shows the game's figure. Settings live in the page's local storage, and each game runs at an origin of its own, so each game keeps its own field of view and starts at its own figure. [Where the settings live](/engine/ui/settings/#where-the-settings-live) says more.
+
+`fixedFieldOfView` keeps the game's figure whatever the player sets, for a design that needs one lens, such as a puzzle that hides what stands out of frame. The Settings panel then shows the row greyed out at the game's figure and says the game sets its own. Leave it off where you can: a field of view that suits the player's screen, and how far they sit from it, eases motion sickness, which is why the Game Accessibility Guidelines and the Xbox Accessibility Guidelines ask for the setting.
+
+A rig built on `useCamera` offers the player's setting by passing `fieldOfView`, [below](#the-rig). The chase, track, side and fly cameras keep the lens their `fov` sets, and the Settings panel shows no Field of view row beside them.
+
+## The lock and first person
+
+While the lock is on, the browser captures the cursor on the canvas: the mouse turns the camera with no button held, and a crosshair marks the middle of the screen, where a `Weapon` aims. She faces the way the camera looks, and the movement keys walk her forward, back and sideways without turning her. Her own page draws that turn, and her look up and down, on every frame, at her movement's `turnRate`, so her body and what she holds follow the mouse as smoothly as the camera does, in a room too; [Multiplayer](https://wiki.spawnite.com/platform/multiplayer/#her-own-character-comes-first) says why. The aim sits `shoulderOffset` right of her, 0.49 m by default, Roblox's shift lock offset, so the middle of the screen clears her back. It stays at her eyes, or `pivotRise` above them, at every zoom.
+
+A shot through the crosshair lands where the crosshair points, at any distance, as in Roblox shooters, Fortnite and Unreal's Lyra. `aimShot` follows the crosshair's ray from abreast of her, so nothing between the eye and her back counts, to the first target or fixed collider it meets, or to the weapon's range where it meets neither. The shot then leaves her muzzle for that point. When the point lies less than a metre past the muzzle, or cover stands between her middle and the muzzle, the shot runs along the crosshair's ray itself, from the point abreast of her, where the path there from her middle is clear, and otherwise from her middle. A free cursor aims at the first target or collider under it too, but over open ground it aims level with her middle, so a click on the ground shoots across it rather than into it. A game with a trigger of its own asks `isCursorCaptured(canvas)` which of the two to aim: it answers true under the browser's pointer lock, and in an automated browser under the capture the engine grants without one.
+
+First person is the same, with the eye a centimetre behind her eyes, her body faded out as [Close to her](#close-to-her) says, and 89 degrees of tilt either way. A wheel notch out puts the eye back at the near stop. Either one is `readStrafe(world)`, which the loop sends to the step as its input's `strafe`, and a room steps her the same way.
+
+A phone has no cursor to capture, so on a device with only a touch screen the camera never locks, and a preset that starts locked plays as the unlocked camera. A tablet with a mouse attached locks as a desktop does.
+
+## Panels that free the cursor
+
+A screen a player clicks frees the cursor while it shows, and the camera takes the cursor back when it closes, with no code of the game's own. A [Modal](/engine/ui/modal/) and the [dialog panel](/engine/behaviours/dialog/#the-panel) do it unless told not to, and a [Panel](/engine/ui/panel/#a-panel-that-frees-the-cursor) does it with `freeCursor`. Anything else calls `useFreeCursor(active)`, which frees the cursor while its component is mounted and `active` holds. Roblox frees the mouse while a `Modal` button shows, and Unreal's CommonUI switches to menu input while a menu widget is active; Unity, Godot and PlayCanvas leave it to the game.
+
+While a screen holds the cursor free, the following holds:
+
+- The cursor goes free at once, and no menu opens.
+- The mouse stops turning the camera, and the crosshair hides.
+- The lock stays on, so the movement keys still walk her as they did, and a drag with the orbit's button turns the camera.
+- Two screens open at once keep the cursor free until the last of them closes.
+- The menu's Play closes the menu and leaves the cursor free.
+
+When the last screen closes, the camera takes back the capture the engine let go for it. Chrome and Safari grant a lock with no click once the page let the last one go itself, so the lock comes straight back. Firefox grants it only inside the click or key press that closed the screen, or in fullscreen. Where the browser refuses, the Play menu shows, and one click on Play takes the lock back. A lock the engine never held, or one Escape let go, comes back through Play, as it always does. Chrome shows its own "Press Esc to show your cursor" notice on a lock taken back, unless its last notice ran its course; a page cannot hide it.
+
+`freeCursorKey`, a `KeyboardEvent.code` such as `"AltLeft"`, frees the cursor while the player holds that key, as an MMO's cursor key does, and takes the lock back when she lets it go. It is a hold rather than a toggle, so letting go never leaves her with a free cursor in a fight. Guild Wars 2 offers both, Neverwinter and Black Desert toggle, and Fortnite's Cursor Mode sits on Left Alt; a game that wants a toggle calls `useFreeCursor` from its own key. Windowed Firefox grants no lock on a key let go, so there the menu's Play takes it back. No preset sets the key, and it is unset unless a game passes it.
+
+The browser hit-tests nothing under a pointer lock, so an element hovered as the lock began would stay hovered. While the cursor is captured, the engine marks the page's root with `data-cursor-captured`, and every `hover:` and `group-hover:` class turns off. A game's own stylesheet starts a hover rule with `:where(:root:not([data-cursor-captured]))` to do the same.
+
+In development, the engine warns once per control when a button, a link or a field shows while the camera captures the cursor and nothing frees it, since no click reaches it. A control that a key presses names the key with `aria-keyshortcuts`, `keyShortcuts` on a [Button](/engine/ui/button/), and the warning passes it.
+
+## The Play menu
+
+The engine's menu is the one thing a game cannot cover or block. Game mounts it last, as a modal dialog in the browser's top layer, and raises it again whenever another dialog opens while it is up, so a game's end screen or modal stays under it and takes no input; the world runs on under it. Escape reaches the engine before any handler a game adds, in every game. While the menu is shut, Escape closes a panel registered with `takeEscape(close)` first, as World of Warcraft's Escape closes the open window before it opens the Game Menu: the panel taken last closes first, with the cursor captured or free and in fullscreen or not, and the next Escape opens the menu. With no such panel, Escape opens the menu: with the cursor captured, the browser lets the cursor go and the menu shows; in fullscreen, the browser leaves fullscreen and the menu shows; with the cursor free, the engine opens it. With the menu open, Escape closes it, and with Settings open, Escape goes back to the menu. The [dialog panel](/engine/behaviours/dialog/#the-panel) takes it while a conversation is open. The page letting the cursor go or leaving fullscreen itself, as when a game turns the lock off at a run's end, opens no menu. A held Escape changes nothing, an Escape under the loading screen opens nothing, and in a development build Escape inside the devtools stays with the devtools.
+
+The browser captures a cursor only inside a click or a key press. So whenever the camera wants the cursor and does not hold it, and no screen holds it free, from a shooter's first frame and when a new run turns the lock back on, the menu also shows. One click on Play captures the cursor and goes fullscreen, Settings opens [the player's settings](/engine/ui/settings/), and a toggle turns fullscreen on or off. A touch screen has neither Escape nor a cursor to let go, so there a menu button in the top-left corner opens the menu. In the player app, the game's frame may not go fullscreen, so Play asks the app to fill the screen with its own play screen, the frame and the app's controls together, as [the trust boundary](https://wiki.spawnite.com/platform/trust-boundary/#storage-and-permissions) says; the toggle is the app's, in its pill. A player who turns Fullscreen on Play off in Settings keeps the page as it is on Play. Browser shooters use the same convention: releasing the cursor is the menu. iPhone Safari has no fullscreen for a page, so the toggle does not show there.
+
+In a browser driven by automation, where `navigator.webdriver` is true, the engine asks for no pointer lock and no fullscreen: headless Chromium on Windows keeps a hidden window, and a lock there confines the real cursor to it. The engine counts the lock as granted there as soon as the camera wants it, so the page goes straight into play with no Play menu, in every game and with no code of the game's own. This is what `spawnite play`, the studio MCP's playtest tools and a game's boot smoke see. While the stand-in lock holds, the mouse turns the camera, a click aims through the crosshair and no click walks her, as under a real lock, so a check's mouse moves turn a captured camera as a player's do. Escape still opens the menu and lets the stand-in lock go, and the next Escape, or Play, goes back into play. A player's browser never sets `navigator.webdriver`, so a player always gets the menu.
+
+A game that runs in the platform's frame gets no `fullscreen` in the frame's `allow` list, as [the trust boundary](https://wiki.spawnite.com/platform/trust-boundary/#storage-and-permissions) says: Play asks the app over the channel, and the app fills the screen with the frame and its own controls together, then answers once its screen has settled.
+
+Fullscreen uses up the click, and Chrome grants a lock only inside a click, or with no click once the page let the last lock go itself. Changing the screen can also let a lock go. So Play asks for the lock inside the click, lets it go itself as it lands, fills the screen, and takes the lock back once the screen has settled: outside the app, once the page's fullscreen lands, and in the app, once the app answers and the frame has its new size. The Play menu stays away meanwhile. A browser that refuses the late lock, as Firefox does in the app's frame, shows the Play menu again, and a second click captures the cursor. Emscripten, which Unity's web builds use, and Babylon.js also take the lock once fullscreen has landed.
+
+## The rig
+
+`useCamera({ follow, through, settle, latch })` is what the component hangs on: it registers the mounted controls with what they follow and returns the props drei's controls take. The props include controls that ease a drag over the wall clock rather than the world's, so the view still turns while the world is paused or slowed. The follow itself runs on the world's time, so the chase camera's swing back behind her and the track chase camera hold and slow with the world. A game with controls of its own spreads those the same way, and names its component as `through`, which is what the devtools row is called. While the devtools' free or map camera holds the view, it takes every other camera out of the world, a rig's included, so the loop, the save, the lock, click-to-walk and the devtools read the devtools' camera alone. It puts each back when it goes, with the settings it had and its orbit where the player left it; the rig's controls stay mounted, turned off. The rig needs no code for this. `settle`, true unless given, pulls the eye in front of whatever stands between it and her; the side camera passes false. `latch`, false unless given, reads the stick in the direction the camera faced when the push began rather than the direction it faces now; the chase camera passes true.
+
+`useCamera` also takes the lens, the stops, the aim and the start `distance`, which default to the engine's. `fov` sets the lens in degrees top to bottom, as three.js's camera takes it. `fieldOfView` instead takes the figure across 16:9, its range and whether it is fixed, `{ degrees, min, max, fixed }`, and lays the player's Field of view setting over it, as `<Camera>` does. [`CameraRigOptions`](https://wiki.spawnite.com/reference/camera/camerarigoptions/) lists every option and its default.
+
+The side camera and the fly camera pass their locked stops the same way. `tuning` holds the settings that only one camera reads: the chase camera's `turnRate`, `holdSeconds` and `latchTurn`, the fly camera's `metresPerSecond` and `rotateSpeed`, and the lock's `lookSpeed` and `shoulderOffset`. Two tell [the Settings panel](/engine/ui/settings/#rows-that-hide-themselves) which of the player's rows reach the rig: `playerLook: true` where its look follows Camera sensitivity and Invert vertical look, and `lockToggleOffered: true` where Shift toggles its lock. A rig that sets neither shows neither row.
+
+In the devtools, the camera's row holds a Settings leaf with these values, `settle`, `latch` and the camera's own tuning. An edit there shows on the next frame; a changed option wins over it.
+
+## Following
+
+A following camera aims at the [player's character](/engine/entities/player/) where she is drawn, between the last two steps, at a height that slides from her eyes up close to her middle far away, or stays at her eyes while the lock is on. The eye line is never above the top of her [body](/engine/entities/player/), which is what the push holds out of rocks: an aim inside a ledge over her head would leave no place for the eye clear of it. While the lock is on the aim rises `pivotRise` above the eye line. The eye is swept from the aim toward where the orbit wants it, as a small sphere against the ground, the map's edge walls, the scatter and the fixed props, and stands where the sphere first meets one: it comes in at once and eases back out once the way clears, along the same line, so it never climbs a slope or swings away from her. The aim is swept out from her eye line the same way, so a rise or a shoulder never stands it inside a ledge, a slope or a stone. The orbit's framing, where the player left the drag and the wheel, is what a game saves.
+
+The ground never stops the tilt. Looking up, the eye comes in along its line to keep 0.3 m over the ground under her feet, as Unreal's spring arm and Roblox's camera come in against the ground, so the player can look at the sky at any zoom. Past 60 degrees up, the eye also comes in toward the aim, reaching the near stop at 80 degrees, and the aim rises with the tilt, 0.9 m at 80 degrees, as Lyra's third-person camera lifts its offset with the pitch. Her body drops out of the bottom of the frame, and what she holds up along the look stays below the crosshair rather than filling a corner of the screen. The eye eases back out as the look comes down.
+
+A following camera mounts behind the player, looking the way she faces, as Roblox's camera does when a character spawns. The first held forward key walks her the way she faces, whichever way the last scene left the camera; a player spawned with `facing` 0 walks toward negative z. With no player in the world yet, it mounts behind that rest facing. It turns once, as it mounts, and never recentres after that. The tilt and the distance stay where the last scene left them, within the bounds, unless the preset or a `distance` or `pitch` prop sets a start. A free orbit and the fly camera keep where they mount.
+
+`rememberFraming` keeps where the player left the camera, its turn, tilt and distance, on this device under the game's name, as the quality setting is kept, and puts it back as the camera mounts, over the turn behind her. It is a view setting, so it stays with the device and never goes in the player's save. It is off by default, so each load starts behind her. Unity, Unreal, Godot and Roblox keep no framing between sessions themselves; a game that wants it writes it to the device.
+
+`frameCamera(world, { azimuth, polar, distance })` puts a framing back with no transition, on the spot rather than a second later. A game calls it once, to set the camera's start angle, from an effect that runs once `useQueryFirst(CameraTrait)` from `koota/react` returns the mounted camera: called before Camera has mounted, it finds no orbit and does nothing. A saved framing takes the same shape.
+
+### Close to her
+
+As the eye comes close to her body, whether looking up, backed against a wall or in first person, she fades out, as Roblox's camera fades a character near the lens. The fade is a screen-door dither: each pixel of her is drawn or dropped against a fixed pattern, so she stays in the opaque pass and her shadow on the ground stays whole. She is whole while the eye is more than 0.35 m from her body, the upright capsule of her radius from her feet to the top of her model, and gone once it is within 0.14 m, in proportion between. A partial fade glides at 2.8 of a whole fade a second, and a fade to gone, or out of it, is at once. In first person she is gone.
+
+The dither is compiled into a VRM body's materials as the body loads, so a fade never compiles a shader mid-play. A body that is not a VRM does not dither: it hides once the fade reaches gone. `bodyNearEye` picks the behaviour:
+
+- `BodyNearEye.Fade`, the default, fades her as above.
+- `BodyNearEye.Hide` hides her, shadow and all, once the eye is within 0.14 m.
+- `BodyNearEye.Off` leaves her drawn however close the eye comes. First person still fades her.
+
+## Shake
+
+`shakeCamera(world, { strength, at, radius, cap })` shakes the page's camera for a big moment, such as an explosion, a boss's slam or a special attack:
+
+```ts
+import { shakeCamera } from "@spawnite/engine";
+
+//  A blast at the monster's feet: a whole shake up close, none 20 m away.
+shakeCamera(world, { strength: 0.6, at: position, radius: 20 });
+```
+
+`strength` runs from 0 to a whole shake at 1, and adds to the shake the camera holds, up to a whole one. `at` is where the moment happened, and the shake fades evenly with the distance from the player's character, or from the eye where she has none, to none at `radius` metres, 20 unless given; left out, the moment shakes at its whole strength. The camera turns by the square of the shake it holds, so a small moment barely stirs the view and a big one throws it, and the shake fades on its own: a whole one in two thirds of a second. `cameraShakeSettings` holds how far a whole shake turns the view, how fast it swings and fades, and the default reach.
+
+Call it from a view, where the page draws the moment. Each page shakes its own camera, so each player feels a moment by how near she stands to it; a room has no camera, and a call there does nothing. The room's clock is every player's, so no page may stop it for a hit-stop, and a shake takes its place.
+
+The shake turns the camera for one frame after its rig has placed it, so it never builds up and the rig's framing, which a game saves, stays as the player left it. It turns the view left and right, up and down, and most of all about its middle. What the player aims through the middle of the screen turns with the view, so a shot goes where the crosshair shows.
+
+`cap` keeps many moments at once from throwing the view. With the moment added, the camera's shake reaches no higher than `cap`, and a shake already past it stays as it is; left out, the cap is a whole shake. A game with many moments passes one cap from every call, and a lower one from its player's own shots, so a held trigger never shakes more than one shot does:
+
+```ts
+//  Every moment of the siege stacks to 0.6 of a whole shake at most.
+shakeCamera(world, { strength: 0.45, at: position, cap: 0.6 });
+```
+
+The player's [Screen shake](/engine/ui/settings/) row scales what she sees, from the game's own at 100 to none at 0, and Reduced motion turns it off, as the Xbox accessibility guidelines ask a game to allow. A game that moves its view its own way for a hit, rather than through `shakeCamera`, multiplies that move by `readCameraShakeScale(useSettings.getState())`, so the row reaches it too.
+
+Unity's Cinemachine Impulse and Unreal's `PlayWorldCameraShake` build the same thing: a shake raised at a place in the world, scaled by each local camera's distance from it and never sent over the network. Both add every shake to the others with no cap on the total, where `cap` lets a game hold its total down. Godot, Roblox and PlayCanvas have none, and their games copy the trauma model from Squirrel Eiserloh's "Juicing Your Cameras With Math" (GDC 2016), which this one follows and which clamps the total at a whole shake. Unity and Unreal take a shake asset with its own curve and length; here a moment is one number, since a creator's agent picks a strength far more easily than it authors a curve, and the settings above reach every other knob.
+
+## Shots from any angle
+
+`frameShot(surface, camera, aspect)` builds the camera for a screenshot from a map's data and its ground, with no render, so an agent sees a map from any side without writing a view first. Blender, Unity, Godot and Unreal give a person the same top, front and side views and "frame selected" in the editor; here they are the fields of one call. The camera is a raw `{ eye, target, fov, ortho }`, returned as written, or a framed shot:
+
+- `angle`: `top`, `bottom`, `front`, `back`, `left` or `right`, orthographic; `three-quarter`, 45° round from `front` toward `right` at eye level, orthographic; `iso`, 45° up from the south-east in perspective, the default; or `{ azimuth, elevation }` in degrees, in perspective. `front` stands at +z looking toward −z, as three's default camera does, and azimuth 90 stands at +x. `top` keeps north up the image.
+- `around`: `all`, every prop or the whole ground when the map has none, the default; a prop, region, path or view by name; a point; or a list of points.
+- `zoom`: 2 stands twice as close in perspective, or spans half as much orthographic; 1 by default.
+- `ortho`: overrides the angle's own projection.
+
+The devtools' `frameShot`, which the playtest's shots call, also takes an entity for `around`: by the key its dump files it under; by a selector of what it is, as CSS's attribute selectors pick an element, such as `[monster.kind=colossus]` for the entity whose `monster` trait's `kind` is `colossus` or `[controlled]` for one that holds the `controlled` trait, several groups for all of them; or by its row's one name in the tree, among the rows whose entity is still in the world. It frames what the page draws of the entity, its model as posed at the shot, where it stands then, whether or not the dump names any of its traits. Where the page draws nothing of it, as in a headless world, the shot frames its body or its collider. A name the map has wins, and a selector or a name that picks more than one entity throws, naming each one's key. The store's `findEntities(subject)` answers the keys a subject picks.
+
+A scene with no map, as a track game's, passes the box it draws in place of the ground. A raw camera then shoots as written, `all` frames that box, and a point frames the point; a name throws, because there is no map to hold it.
+
+A perspective shot stands at the distance that fits the subject's bounding sphere at a 50° field of view, as the devtools' focus does. An orthographic shot fits the subject's box as the camera sees it, so a square map from above fills the frame. `frameView`'s region, path and prop framing is `frameShot` with `iso`.
+
+## Side view
+
+`<SideCamera />` frames the player from the side, for a platformer: an orbit that follows her with its direction, tilt and distance locked at its props, and no drag, wheel or touch to move them. The loop aims it at her each frame, as it aims the following camera, but the eye does not settle: it stays at its distance when a trunk stands between it and her, as Unreal's side-scroller turns its spring arm's collision test off, so the frame never lurches in while she walks past the trees. The direction the stick is read in never turns, so left and right on the stick always walk her across the screen: along the world's x at the default azimuth. Forward on the stick walks her into the screen.
+
+Its props are in [`SideCameraProps`](https://wiki.spawnite.com/reference/camera/sidecameraprops/).
+
+It aims hard, with no lag and no dead zone. Unreal's side-scroller template is the same shape: a spring arm with its rotation fixed and its lag off.
+
+```tsx
+import { CharacterSpawn, SideCamera, World } from "@spawnite/engine";
+
+export function Level() {
+    return (
+        <World map="meadow">
+            <CharacterSpawn />
+            <SideCamera />
+        </World>
+    );
+}
+```
+
+## Chasing
+
+`<ChaseCamera />` stays behind the player. It is the following camera with one difference: each frame its direction turns toward the way she faces, at a quarter turn a second, the short way round. The tilt and the distance stay where the drag and the wheel leave them, within the bounds, and the eye settles in front of a trunk as the following camera's does. A drag wins: the camera stops turning while the player drags it and for a second after the drag ends. `fov` sets its lens, 50 degrees unless given. Roblox's `Follow` camera and Unreal's spring arm that inherits the pawn's yaw are the same camera.
+
+A camera that turns toward her on its own needs the stick read differently, or a stick held a little off straight spins the view: she walks a little to the side, the camera turns after her, and the stick, read against the camera, now points further to the side. So while the chase camera is mounted, the stick is read in the direction the camera faced when the push began. That direction holds until the stick lets go or turns more than 30 degrees, and then the camera's direction is read again. A held forward walks her straight along the way the push began while the camera comes round behind her. The following camera and the side camera read the stick against the camera's direction on every frame.
+
+```tsx
+import { CharacterSpawn, ChaseCamera, World } from "@spawnite/engine";
+
+export function Run() {
+    return (
+        <World map="meadow">
+            <CharacterSpawn />
+            <ChaseCamera />
+        </World>
+    );
+}
+```
+
+### Along a track
+
+`<ChaseCamera track={track} />` chases the entity riding a [TrackMover](/engine/behaviours/track-mover/) on that track rather than the player's character, the player's own where several ride it. The eye stands on the track 6.8 m behind the rider and 3.5 m above it, and looks 4 m ahead down the track at 1.5 m above it, both carried across with the rider. Through a bend the eye stays over the track behind, where a camera hung off the rider's facing would swing out past the outside of the corner. Before the start and past the end, the eye carries on along the end's direction. The eye eases after the rider and the aim eases faster, so the rider stays framed while the eye trails; a rider put more than 10 m from the eye, as at a restart, is cut to. Unity's Cinemachine spline dolly and Unreal's `CameraRig_Rail` are the same camera. Roblox and Godot leave it to the game.
+
+This camera has no orbit, so no drag or wheel turns it, and a touch game keeps the drag for its own controls. The stick is read as it is, with no camera direction: a track mover reads only its sideways part.
+
+```tsx
+import {
+    ChaseCamera,
+    Entity,
+    RunContext,
+    Track,
+    TrackMover,
+} from "@spawnite/engine";
+
+const run = new Track([
+    { x: 0, y: 0, z: 0, width: 6 },
+    { x: 8, y: -4, z: -20 },
+    { x: -8, y: -8, z: -45 },
+]);
+
+export function Run() {
+    return (
+        <>
+            <Entity authority={RunContext.Client}>
+                <TrackMover track={run} distance={6} />
+            </Entity>
+            <ChaseCamera track={run} fov={52} />
+        </>
+    );
+}
+```
+
+## Flying
+
+`<FreeCamera />` is a fly camera with no target and no orbit centre, as Unreal's spectator pawn and Godot's editor camera: a spectator's or an editor's view of the world. It takes no props. It mounts where the canvas camera stands, facing where it faced, and from there the movement keys fly it: forward and back along its line of sight, left and right across it, and `E` and `Q` climb and descend along the world's up. A drag with the left button or one finger turns it about itself. While the devtools' terrain editor holds a tool, the left button and one finger paint instead: the right button and two fingers turn it, and the wheel flies it along its line of sight, `freeCameraSettings.wheelMetres` for each pixel of scroll. It flies on the same keys and stick the player walks on, so a scene mounts it instead of a player, not beside one, and a modal that pauses holds it still as it holds the world. It flies on the wall clock, so it keeps its speed over a world the devtools hold or slow. The devtools' Free camera button mounts it over whatever camera the scene mounts, a game's own included, and a second press gives the view back to the scene's camera, which picks up from the next frame.
+
+## Over the map
+
+`<MapCamera />` is a city builder's camera, as Cities: Skylines' and Anno's on the keys and the mouse and Google Maps' under the fingers: an orbit whose pivot sits on the ground, so the map is always the subject and nothing can be lost. It takes no props. It mounts where the canvas camera stands, its target where the camera's line meets the ground, or 20 m ahead where it never does, and from there the movement keys pan along the ground at a share of the eye's height a second, so the map crosses the screen in about the same time at any height; `Q` and `E` turn about the ground point. The wheel, a trackpad's two-finger scroll and a pinch zoom toward the ground under the pointer, the pinch faster since the browser reports it in small steps, and the view tilts toward top-down as it zooms out and back down as it zooms in, 15° a doubling of the distance, picking up from wherever a drag left the tilt. The right button or two fingers turn and tilt, and a left or middle drag or one finger grab the ground, the point pressed staying under the pointer; a left press that never moves is a click, which selects as everywhere in the devtools. The devtools' Map button mounts it over whatever camera the scene mounts, a game's own included, and flies it up over the player's character until the whole map is in view; a second press gives the view back to the scene's camera, which picks up from the next frame. A scene can also mount it itself, as the story does.
+
+## Sample
+
+```tsx
+import { Camera, CameraTarget, CharacterSpawn, World } from "@spawnite/engine";
+
+export function Run() {
+    return (
+        <World map="meadow">
+            <CharacterSpawn />
+            <Camera follow={CameraTarget.ViewTarget} />
+        </World>
+    );
+}
+```
+
+A lobby that shows the world without a player mounts `<Camera follow={null} />` instead: a free orbit, for a menu, that stays where the drag leaves it. The default follows the player, as Roblox's camera follows the character unless a script says otherwise.