incanto 0.74.0 → 0.75.0

package/dist/gameplay.d.ts

@@ -1,5 +1,5 @@
-import { b as Engine, d as PropSchema, jt as Node, n as BehaviorCtor, t as Behavior } from "./behavior-J1cmVah0.js";
-import { c as JsonValue, s as JsonObject } from "./rng-Bb-IutXB.js";
+import { b as Engine, d as PropSchema, jt as Node, n as BehaviorCtor, t as Behavior } from "./behavior-B_245qRy.js";
+import { c as JsonValue, s as JsonObject } from "./rng-BsXZg3D6.js";
 
 //#region src/gameplay/chase.d.ts
 /**
@@ -28,10 +28,14 @@ declare class Chase extends Behavior {
   speed: number;
   /** The group member currently chased (`targetGroup`), or null. */
   private picked;
+  /** Read-only: the node being chased this frame, or null (out of sight, none in the group, no `target`). */
+  get chasing(): Node | null;
+  private current;
   private sincePick;
   stopRange: number;
   loseRange: number;
   moveParent: boolean;
+  requireSight: boolean;
   ground: boolean | null;
   facePath: string;
   /** Signed fall speed accumulated while a ground chaser is off the floor. */
@@ -54,11 +58,44 @@ declare class Chase extends Behavior {
   private dropIfAirborne;
   /** The nearest live member of `targetGroup` — re-picked every `retargetEvery` seconds, never the mover itself. */
   private nearestOfGroup;
+  /** `requireSight`: a static-only ray from half a metre over the mover to half a metre over the target reaches it. */
+  private canSee;
   /** See `ground`: an explicit answer, else "is the mover a 3D kinematic capsule". */
   private walksTheGround;
   override update(dt: number): void;
 }
 //#endregion
+//#region src/gameplay/chase-camera.d.ts
+/**
+* A camera BEHIND something that turns — a car, a boat, a tank, a horse.
+*
+* `FollowCamera` keeps a fixed world offset, which is right for a top-down or
+* side view and wrong for a vehicle: the offset has to swing round with the
+* target's heading, and lazily, or every corner snaps the view. Four examples
+* (a delivery van, a harbour boat, an errand car, a race car) wrote this same
+* behaviour by hand — `back`, `up`, a smoothed yaw — before it existed.
+*
+* The heading comes from the target's rotation BASIS, not from `rotation[1]`:
+* a tilted body's Euler XYZ triple reads `[180, 180−yaw, 180]` past 90° of
+* yaw, and a camera that read the middle number swung to the wrong side. Aim
+* the camera with `Camera3D.lookAt` (or `Camera2D.follow`); this only places it.
+*/
+declare class ChaseCamera extends Behavior {
+  static readonly props: PropSchema;
+  static readonly signals: readonly string[];
+  target: string;
+  back: number;
+  up: number;
+  smoothing: number;
+  /** The heading the camera currently trails (radians) — a harness reads it. */
+  heading: number | null;
+  override onReady(): void;
+  override update(dt: number): void;
+  private placed;
+  /** Put the camera on its mark NOW (a scene start, a respawn) instead of flying there. */
+  snap(): void;
+}
+//#endregion
 //#region src/gameplay/collector.d.ts
 /**
 * A tally for the "collect N things" pattern, living on the collector itself
@@ -109,8 +146,23 @@ declare class Currency extends Behavior {
   canAfford(cost: number): boolean;
   /** Pay `cost` if it is there. Returns whether it went through. */
   spend(cost: number): boolean;
-  /** Take payment in. */
+  /**
+  * Take payment in — and say what did NOT fit.
+  *
+  * This clamped at `max` and emitted `earned(gain)` anyway, so a purse with a
+  * ceiling took a coin it could not hold and told the game it had. Measured on
+  * a game whose purse holds four: the fifth pickup vanished off the floor, the
+  * HUD said `4 / 4`, and nothing anywhere had the pickup. The game then wrote
+  * `if (purse.amount >= purse.max)` itself — the comparison `spend`'s
+  * `refused` exists so that nobody repeats.
+  *
+  * `earned` is now what was actually TAKEN, and `refused` carries the
+  * remainder. A purse with no ceiling never refuses, which is every purse
+  * written before this.
+  */
   earn(gain: number): void;
+  /** How much more this purse can hold (Infinity with no ceiling). */
+  get room(): number;
   /** What has already been complained about, so a loop says it once. */
   private complained;
   /**
@@ -154,6 +206,29 @@ declare class Health extends Behavior {
   invulnerableFor: number;
   freeOnDeath: boolean;
   freeParent: boolean;
+  knockback: number;
+  knockbackSeconds: number;
+  knockUp: number;
+  staggerSeconds: number;
+  applyKnockback: boolean;
+  /** Unit direction of the last hit that had a source, source → this body (ground plane). */
+  hitDirection: number[];
+  private staggerLeft;
+  private kickLeft;
+  private kick;
+  private kickFresh;
+  /** True while a hit's stagger holds this body's movers and controllers. */
+  get staggered(): boolean;
+  /** True while a hit's shove is still moving this body. */
+  get knocked(): boolean;
+  /** The shove's current velocity (decaying), empty when not knocked — a controller that drives the body reads it. */
+  get kickVelocity(): number[];
+  /** The vertical part of the shove, ONCE (a lift is an impulse, not a per-frame write); 0 after. */
+  takeLift(): number;
+  /** A body driven by a character controller gets its shove from the controller, not from here. */
+  private drivenByController;
+  /** The body a hit moves: this node if it is spatial, else the nearest spatial ancestor (a Health on a child `Hp` node moves its parent). */
+  private bodyNode;
   /** Current hit points (set to `max` on ready). */
   current: number;
   private invulnTimer;
@@ -165,7 +240,15 @@ declare class Health extends Behavior {
   override onReady(): void;
   override update(dt: number): void;
   /** Apply `n` damage. No-op while invulnerable or already dead. Emits `damaged`. */
-  damage(n: number): void;
+  /**
+  * The shove, frame by frame, decaying linearly — written EVERY frame like a
+  * dash, because a controller brakes toward its own pace and a one-frame
+  * velocity dies. A dynamic body gets its velocity written (the vertical part
+  * once, as a lift); a kinematic or plain node is displaced through
+  * `moveBody` with `force`, so it still slides along walls.
+  */
+  private applyKick;
+  damage(n: number, from?: readonly number[] | undefined): void;
   /**
   * Be immune for `seconds` from NOW — a dodge roll, a spawn, a cutscene.
   *
@@ -389,6 +472,7 @@ declare class Interactable extends Behavior {
   focusedBy: Node | null;
   /** Actions already reported missing, so a per-frame read says it once. */
   private readonly reportedActions;
+  override onReady(): void;
   override update(): void;
   /** Is THIS the Interactable `actor` means — the nearest (that it faces) of every one in reach? */
   private claims;
@@ -423,6 +507,52 @@ declare class Lifetime extends Behavior {
   override update(dt: number): void;
 }
 //#endregion
+//#region src/gameplay/mount.d.ts
+/**
+* Get on something and drive it; get off beside it.
+*
+* A horse, a car, a boat, a turret seat: the player's controller lets go, the
+* player's body PARKS (collider off, hidden, weightless, riding along so
+* everything that targets the player follows), the player's `skin` moves onto
+* the steed's `saddle`, and the steed's `drive` — a `CharacterController3D` or
+* a `Vehicle3D` — is enabled. `dismount()` puts everything back beside the
+* steed. Two examples (an errand car, a saddled horse) wrote these sixty lines
+* before it existed, and both forgot something the other remembered.
+*
+* Wire it from an `Interactable`: `interacted → Mount.toggle`.
+*/
+declare class Mount extends Behavior {
+  static readonly props: PropSchema;
+  static readonly signals: readonly string[];
+  rider: string;
+  steed: string;
+  drive: string;
+  walk: string;
+  skin: string;
+  saddle: string;
+  skinOnSaddle: number[];
+  skinOnRider: number[];
+  dismountAt: number[];
+  /** True while the rider is on. */
+  mounted: boolean;
+  mounts: number;
+  private parked;
+  override onReady(): void;
+  private riderNode;
+  private steedNode;
+  /** The first child (or the named one) carrying a boolean `enabled` and a `yaw` or a `throttle` — a controller or a vehicle. */
+  private switchOf;
+  private skinNode;
+  private saddleNode;
+  /** Get on. False when already on. */
+  mount(): boolean;
+  /** Get off beside the steed. False when not on. */
+  dismount(): boolean;
+  /** On if off, off if on — the handler an `Interactable`'s `interacted` wires to. */
+  toggle(): void;
+  override update(): void;
+}
+//#endregion
 //#region src/gameplay/tween.d.ts
 /** Easing curves shared by the tween behaviors (MoveTo, …). Pure math. */
 type EaseName = "linear" | "easeIn" | "easeOut" | "easeInOut";
@@ -451,6 +581,12 @@ declare class MoveTo extends Behavior {
   override onReady(): void;
   /** Begin (or restart) the move from the node's CURRENT position. */
   start(): void;
+  /**
+  * Land on `to` NOW and say `arrived` (once). A skipped cutscene must leave
+  * the world as the whole cutscene would have — the door it opens, open.
+  * Wire `skipped → Door.finish`.
+  */
+  finish(): void;
   override update(dt: number): void;
 }
 //#endregion
@@ -565,6 +701,54 @@ declare class Patrol extends Behavior {
   private advance;
 }
 //#endregion
+//#region src/gameplay/phases.d.ts
+/**
+* A boss that changes at two thirds and again at a third.
+*
+* Every other common wiring in this engine became declarative — score to
+* screen, damage to a health bar, waves, win, lose, the save, the restore — and
+* a fight's PHASES stayed the one thing that needed TypeScript. The shipped
+* boss reads `healthChanged(current, max)`, divides, compares against two
+* constants and calls its own `enterPhase`; every boss anyone builds writes
+* those eight lines again.
+*
+* This is the threshold half and only that half. WHAT a phase does is the
+* game's business, and it is reached through connections:
+*
+* ```json
+* { "name": "Mood", "type": "Node", "uid": "n_…",
+*   "script": { "name": "Phases", "props": { "at": [0.66, 0.33] } } }
+* ```
+* ```json
+* { "signal": "phase2", "from": "Boss/Mood", "to": "Adds",  "handler": "start" },
+* { "signal": "phase3", "from": "Boss/Mood", "to": "Roar",  "handler": "play"  },
+* { "signal": "phaseChanged", "from": "Boss/Mood", "to": "Hud", "handler": "onPhase" }
+* ```
+*
+* The numbered signals exist because a connection cannot filter on a NUMBER: a
+* `filter` gates on a node's group or tags, so `phaseChanged(2)` could only ever
+* reach one handler that switches. `phase2`…`phase5` is what makes "phase two
+* starts the adds" a line in the scene file.
+*/
+declare class Phases extends Behavior {
+  static readonly props: PropSchema;
+  static readonly signals: readonly string[];
+  at: number[];
+  health: string;
+  /** Which phase the fight is in: 1 until the first threshold is crossed. */
+  phase: number;
+  private watched;
+  override onReady(): void;
+  /** Wire this to a `healthChanged` yourself when the health is somewhere odd. */
+  read(current: number, max: number): void;
+  /** The phase survives a save, like every other run-state number here. */
+  override serialize(): {
+    phase: number;
+  };
+  override deserialize(data: unknown): void;
+  override announce(): void;
+}
+//#endregion
 //#region src/gameplay/pickup.d.ts
 /**
 * A collectible that vanishes when a collector overlaps it. Must sit on an
@@ -653,7 +837,15 @@ declare class Projectile extends Behavior {
   * This is what a `spawned(node)` handler calls after turning the clone, and
   * the only way a `'forward'` projectile ever re-reads its rotation.
   */
-  aim(direction?: JsonValue | undefined): void;
+  /**
+  * Bake the velocity from `direction` × `speed` — plus `carry`, the SHOOTER's
+  * velocity, so a shell fired from a tank doing 16 m/s flies with it instead
+  * of at the standing tank's speed (a tank could outrun its own shot; a
+  * sideways shell landed behind what the barrel pointed at). Added once, at
+  * launch; a later `speed` or `direction` write re-bakes with the same carry.
+  */
+  aim(direction?: JsonValue | undefined, carry?: readonly number[] | undefined): void;
+  private carry;
   override onReady(): void;
   override update(dt: number): void;
   /** Resolve `direction` to a unit vector, deriving 'forward' from rotation. */
@@ -692,6 +884,9 @@ declare class SavePoint extends Behavior {
   scene: string;
   restoreOnReady: boolean;
   probeOnReady: boolean;
+  keep: string[];
+  /** Poses read out of the slot, waiting for `announce()` to put them back. */
+  private keptPoses;
   /** Seconds this run has been playing — written into the slot as `playtime`. */
   private elapsed;
   private slots;
@@ -747,9 +942,20 @@ declare class SavePoint extends Behavior {
   restore(): void;
   /** Forget this slot — a "delete save" button. */
   clear(): void;
-  /** The run's own clock survives a save/continue cycle. */
+  /** The run's own clock — and the poses the scene asked to keep. */
   override serialize(): JsonValue;
   override deserialize(data: JsonValue): void;
+  /**
+  * Put the kept nodes back where the run left them.
+  *
+  * In `announce()` and not in `deserialize()`, for the reason the hook exists:
+  * a pose written mid-pass can be overwritten by another behavior's restore
+  * (a camera rig, a controller reading its target), and announce runs after
+  * the whole pass has landed.
+  */
+  override announce(): void;
+  /** Read the poses the scene named — reporting the ones it cannot. */
+  private readPoses;
 }
 //#endregion
 //#region src/gameplay/score-keeper.d.ts
@@ -983,6 +1189,88 @@ declare class ZombieAI extends Behavior {
   private pickGoal;
 }
 //#endregion
+//#region src/gameplay/ballistics.d.ts
+/**
+* The two questions a lobbed shot asks: **at what angle**, and **where will it
+* land**.
+*
+* `Projectile.gravity` has flown arcing shells since it shipped, and nothing
+* could aim one: `Turret` pointed straight at its target, so a gun firing a
+* falling shell at anything further than a few metres dropped it short — a
+* measured 66 m short, on an artillery duel built from the package. Every game
+* that wanted a mortar, a grenade, a catapult or a lobbed spell wrote this
+* arithmetic itself, and a preview drawn with slightly different arithmetic
+* lands somewhere the shell does not.
+*/
+/**
+* The unit direction that puts a shot from `from` onto `to`, or `null` when
+* the speed cannot reach it.
+*
+* `arc` picks the root: `'low'` is the flat, fast one (a rifle grenade),
+* `'high'` the mortar's — same landing point, a much taller flight, and the
+* one that clears a wall in between.
+*
+* Dimension-agnostic, like everything else here: a 3D shot spreads over x/z
+* with +y up, a 2D one over x with −y up (the y-down screen convention
+* `Projectile.gravity` already follows).
+*/
+declare function ballisticAim(from: readonly number[], to: readonly number[], speed: number, gravity: number, arc?: "low" | "high"): number[] | null;
+/** The angle that carries a shot FURTHEST — what a gun fires when it cannot reach. */
+declare function maxRangeAim(from: readonly number[], to: readonly number[]): number[] | null;
+interface BallisticPathOptions {
+  /** How long to walk, in seconds (default 12). */
+  seconds?: number;
+  /** The step — leave it at the engine's fixed step so the walk matches the flight. */
+  dt?: number;
+  /** Called with each point; return true to stop (the ground, a wall, the map edge). */
+  stop?: (at: readonly number[]) => boolean;
+}
+/**
+* Walk the flight a `Projectile` with this `speed`, `direction` and `gravity`
+* WOULD fly — the same integration, step for step.
+*
+* That is the point: an aiming line drawn from the closed-form parabola drifts
+* from the shell the engine actually flies (Euler with the fall accumulated
+* first), and the player aims by the line. Same arithmetic, same landing.
+*/
+declare function ballisticPath(from: readonly number[], direction: readonly number[], speed: number, gravity: number, options?: BallisticPathOptions | undefined): number[][];
+//#endregion
+//#region src/gameplay/blast.d.ts
+declare class Blast extends Behavior {
+  static readonly props: PropSchema;
+  static readonly signals: readonly string[];
+  radius: number;
+  damage: number;
+  falloff: "linear" | "none";
+  groups: string;
+  when: string;
+  self: boolean;
+  throughWalls: boolean;
+  private went;
+  /** Has it gone off? A keg explodes once. */
+  get spent(): boolean;
+  private get carrier();
+  override onReady(): void;
+  /** Go off now: everything with a `Health` inside `radius` takes its share. */
+  blast(): number;
+  /** Who is even a candidate: the named groups, or every HEALTH in the tree. */
+  private candidates;
+  /**
+  * `throughWalls: false` — a static-only ray, the same one
+  * `Turret.requireSight` casts, with the two things a BLAST has to know that
+  * a turret does not.
+  *
+  * A bomb lies on the ground, so its ray starts inside the floor's collider
+  * and Rapier reports a hit at zero distance: every victim looked shielded,
+  * by the ground the bomb was standing on. And a crate solid enough to walk
+  * into is a collider between the blast and the crate's own centre, so the
+  * first thing a bomb could never destroy was the box beside it. Neither is a
+  * wall: a hit at the origin is what the blast is sitting on, and a hit that
+  * belongs to the target is the target.
+  */
+  private reaches;
+}
+//#endregion
 //#region src/gameplay/checkpoint.d.ts
 /**
 * A checkpoint: touch it and a `Respawn` puts you back HERE from now on.
@@ -1007,7 +1295,38 @@ declare class Checkpoint extends Behavior {
   dropBelow: number;
   /** True after the first activation. */
   lit: boolean;
+  /**
+  * Where this checkpoint sent the catcher, and WHEN it did.
+  *
+  * The position is not derivable at restore: a checkpoint can be lit while its
+  * own node has since moved (a lift, a boat), and `dropBelow` is applied once
+  * at lighting. The clock is what orders three lit checkpoints back into the
+  * order the run walked them.
+  */
+  private sentTo;
+  private litAt;
   override onReady(): void;
+  /**
+  * What a save has to carry: WHICH checkpoint the run had reached.
+  *
+  * `Checkpoint` had none of this, so a continued run came back with every
+  * checkpoint dark and the `Respawn` pointing at the level's start — the first
+  * fall after a continue undid the whole session. It was not in the skill's
+  * list of built-ins that save either, so nothing said it would not.
+  */
+  override serialize(): JsonValue;
+  override deserialize(data: JsonValue): void;
+  /**
+  * Point the catcher back where the run left it.
+  *
+  * Every lit checkpoint sharing a catcher runs this, and they must not fight:
+  * each one writes only if no lit sibling on the same `Respawn` was walked
+  * LATER, so all of them reach the same answer and the order they announce in
+  * does not matter.
+  */
+  override announce(): void;
+  /** Was another lit checkpoint on this same catcher reached after this one? */
+  private laterSiblingLit;
 }
 //#endregion
 //#region src/gameplay/day-night.d.ts
@@ -1194,8 +1513,112 @@ declare class GameFlow extends Behavior {
   * game will have. `UiPanel` appeared in zero template scenes before this.
   */
   pausePanelPath: string;
+  /**
+  * A screen shown at BOOT, holding the world until something resumes.
+  *
+  * '' (the default) is a game that starts playing, which is every game this
+  * engine shipped until now. Naming a panel here is the whole of a title
+  * screen: the flow pauses in `onReady`, shows this instead of the pause
+  * panel, and a `PLAY` button wires straight to `resume` —
+  *
+  * ```json
+  * { "from": "%Play", "signal": "pressed", "to": ".", "handler": "resume" }
+  * ```
+  *
+  * Every shipped shell wrote that in TypeScript, together with the eighty
+  * lines below it, and `incanto-hud.md` told authors to copy one.
+  */
+  titlePanelPath: string;
+  /**
+  * Where this game keeps its saves — a `SaveSlots` namespace. `''` = no saving.
+  *
+  * `SaveSlots`, `captureState` and `restoreState` have existed since the save
+  * round and no shipped starter used any of them: a scaffolded game could not
+  * be closed and come back. The API was never the problem; the SEQUENCE was —
+  * write a slot, reload the scene from source, wait for the reload, restore by
+  * uid — and every game that wanted a save menu had to get that right before it
+  * had one. `restart()` is already the engine's verb for "reload this scene",
+  * wired from a button with no TypeScript; `save()` and `continueFrom()` are
+  * its two siblings.
+  *
+  * WHEN to save is still yours. The skill's rule stands — there is no autosave
+  * — you wire `save` to whatever signal marks the moment: a checkpoint, a level
+  * end, a button in the pause menu.
+  */
+  saveSlots: string;
+  /** Lazily built, so a game with no `saveSlots` never touches storage. */
+  private slots;
+  private store;
+  /**
+  * Write this scene's behaviour state into a slot. `false` = nothing was
+  * written, and the log says why.
+  */
+  save(slot?: unknown): boolean;
+  /** Is there something in this slot to come back to? */
+  hasSave(slot?: unknown): boolean;
+  /**
+  * Reload this scene and hand every behaviour its state back.
+  *
+  * The order is the whole feature: `restoreState` has to run AFTER the reload
+  * and after `onReady`, because `onReady` is where a behaviour sets its
+  * starting values and restoring first would be overwritten.
+  */
+  continueFrom(slot?: unknown): boolean;
+  /**
+  * Screens pushed OVER the base one — options, credits, controls.
+  *
+  * The genuinely hard part of a shell is BACK. Options opens from the title
+  * AND from the pause menu and has to return to whichever asked, which is a
+  * stack; every game that hand-rolls it eventually gets a screen stuck. Two
+  * connection rows now:
+  *
+  * ```json
+  * { "from": "%TitleOptions", "signal": "pressed", "to": ".",
+  *   "handler": "screen", "args": ["%Options"] },
+  * { "from": "%Back", "signal": "pressed", "to": ".", "handler": "back" }
+  * ```
+  */
+  private readonly screens;
+  /**
+  * Every screen this flow has ever raised — the set it is allowed to HIDE.
+  *
+  * Popping the stack before syncing would drop the closing screen out of the
+  * list of panels to consider, so `back()` showed the title again and left
+  * Options on top of it. A screen that has been opened stays this flow's to
+  * close.
+  */
+  private readonly everShown;
+  /**
+  * Is the BASE screen the title rather than the pause menu?
+  *
+  * Both are "the world is held and a panel is up", and only this tells them
+  * apart — so `back()` from Options knows which one to bring back.
+  */
+  private onTitle;
+  /**
+  * Push a screen over whatever is showing, and hold the world while it is up.
+  *
+  * A connection handler, so a button reaches it with no script:
+  * `{"handler": "screen", "args": ["%Options"]}` — the bound argument is the
+  * panel's node path.
+  *
+  * Opening a screen during PLAY freezes the world (an inventory, a map), and
+  * `back()` gives it back. Opening one while already paused keeps the pause.
+  */
+  screen(path: unknown): void;
+  /**
+  * Close the top screen and show whoever asked for it.
+  *
+  * With nothing left on the stack this returns to the base screen — the title
+  * at boot, the pause menu while paused — and if there is no base screen
+  * either, it resumes: a screen opened during play closes back into the game.
+  */
+  back(): void;
   state: GameFlowState;
   private frozeScale;
+  /** Dropped when this flow's node leaves the tree — see `onReady`. */
+  private unwatchScene;
+  override onExitTree(): void;
   override onReady(): void;
   /**
   * The panel follows the state; nothing else may own its visibility.
@@ -1230,6 +1653,52 @@ declare class GameFlow extends Behavior {
   override update(): void;
 }
 //#endregion
+//#region src/gameplay/group-camera.d.ts
+/**
+* One camera, several players — the couch co-op camera.
+*
+* `FollowCamera` follows ONE target and `ChaseCamera` rides behind ONE
+* character, so a game with two players at the same keyboard had nothing to
+* frame them both: whoever the camera followed could walk the other off screen,
+* and the other player's half of the game went with them.
+*
+* This keeps EVERY target in frame: the camera sits at their centroid plus
+* `offset`, and pulls BACK along that offset until the pair that is furthest
+* apart fits inside `padding` of the view. It is the Overcooked / Castle
+* Crashers / Lovers-in-a-Dangerous-Spacetime camera.
+*
+* ```json
+* { "name": "Camera", "type": "Camera3D", "props": { "current": true, "fov": 50 },
+*   "script": { "name": "GroupCamera",
+*               "props": { "targets": "player", "offset": [0, 12, 14],
+*                          "minZoom": 0.8, "maxZoom": 2.6, "smoothing": 0.12 } } }
+* ```
+*
+* Pair it with `CharacterController3D`'s `camera: "none"` on every player, or
+* the controllers will fight it for the camera every frame.
+*/
+declare class GroupCamera extends Behavior {
+  static readonly props: PropSchema;
+  static readonly signals: readonly string[];
+  targets: string;
+  offset: number[];
+  minZoom: number;
+  maxZoom: number;
+  padding: number;
+  smoothing: number;
+  lookAtGroup: boolean;
+  /** The zoom actually in use — 1 is the authored offset. */
+  zoom: number;
+  /** The point the camera is framing. */
+  centre: number[];
+  override onReady(): void;
+  /** Everyone the camera is trying to keep on screen, right now. */
+  members(): Node[];
+  override update(dt: number): void;
+  /** Snap to the group now — after a teleport, a scene swap, a respawn. */
+  snap(): void;
+}
+//#endregion
 //#region src/gameplay/juice.d.ts
 /**
 * Game-feel primitives ("juice"): the weapon cooldown, camera shake, screen
@@ -1339,6 +1808,9 @@ declare class PathFollow extends Behavior {
   speed: number;
   loop: boolean;
   moveParent: boolean;
+  path: string;
+  autoStart: boolean;
+  private declared;
   facePath: string;
   turnSpeed: number;
   private waypoints;
@@ -1346,6 +1818,9 @@ declare class PathFollow extends Behavior {
   /** True while there is somewhere left to go. */
   get moving(): boolean;
   setPath(waypoints: readonly (readonly number[])[]): void;
+  override onReady(): void;
+  /** Walk the declared `path` from its first waypoint — the cue a connection can give. */
+  start(): void;
   /** Stop in place (keeps the node where it is). */
   stop(): void;
   override update(dt: number): void;
@@ -1402,6 +1877,16 @@ declare class PrefabShelf extends Behavior {
   /** What this shelf holds, in authored order. */
   names(): string[];
   /**
+  * The held template itself — to ASK it something, never to change it.
+  *
+  * `Turret.arc` needs the shell's `speed` and `gravity` to solve a firing
+  * angle, and it needs them BEFORE it makes a clone (the barrel elevates
+  * every frame, not only when the gun fires). Re-declaring those numbers on
+  * the turret would be two surfaces free to disagree; reading the one that
+  * flies is the answer. Mutating what comes back changes every future clone.
+  */
+  template(name: string): Node | null;
+  /**
   * A live clone of one template, DETACHED — `addChild` it yourself.
   *
   * Detached for the same reason `duplicateNode` is, and it is not a
@@ -1418,38 +1903,76 @@ declare class PrefabShelf extends Behavior {
   private childNames;
 }
 //#endregion
-//#region src/gameplay/spatial.d.ts
+//#region src/gameplay/sight.d.ts
 /**
-* A node's position with every spatial ancestor's added in.
-*
-* The tree composes transforms for DRAWING — three does it for free — and every
-* piece of engine logic that reads `node.position` gets the LOCAL number
-* instead. Physics already knew (`worldPosition2D`/`worldPosition3D` in the
-* adapters); the camera did not, and neither did anything that chases a target.
-*
-* A camera parented to the player is the Godot and Phaser idiom, and the
-* authoring skill explicitly permits it — *"EVERY node type can hold children …
-* any node works as a grouping container"*. Measured on exactly that scene:
+* Eyes for a watcher — a guard, a turret, a camera, a beast.
 *
+* ```json
+* { "name": "Guard", "type": "CharacterBody3D", "children": [
+*   { "name": "Skin", "type": "ModelInstance3D", "props": { "model": "$base" } },
+*   { "name": "Eyes", "type": "Node",
+*     "script": { "name": "Sight", "props": { "range": 12, "coneDeg": 70, "fillSeconds": 1 } } },
+*   { "name": "Hunt", "type": "Node", "script": { "name": "Chase", "props": { "enabled": false } } }
+* ] }
 * ```
-* player world position : [1400, 900]
-* renderer view centre  : {"x":0,"y":0}
-* framing               : camera /Level/Player/Cam centred [1400, 900]
-*                         1 in view, 0 outside it
+* ```jsonc
+* { "signal": "spotted", "from": "Guard/Eyes", "to": "Guard/Hunt", "handler": "enable" },
+* { "signal": "lost",    "from": "Guard/Eyes", "to": "Guard/Hunt", "handler": "disable" }
 * ```
 *
-* The renderer drew empty world 1600 px from the player while `framing` — the
-* instrument the skills tell you to trust before handing a game back —
-* certified the player on screen.
-*
-* Arity comes from the node itself: a 2D node has two components, a 3D node
-* three, and an ancestor that is neither contributes nothing.
+* On a child of the watcher's body. Every frame it looks the way the node at
+* `facingPath` faces (the Skin the controller turns, +Z-forward) and sees
+* anything in `targetGroup` inside `coneDeg` and `range` with nothing
+* STATIC between its eye and their chest (`los`). `suspicion` fills over
+* `fillSeconds` while something is seen and drains when nothing is;
+* `spotted(node)` fires when it reaches 1, `lost(node)` when it empties —
+* once each, an edge, so a connection can flip a state. `sees(node)`,
+* `seen()` and `target` (the nearest) answer any frame.
+*
+* Five examples wrote this by hand before it existed, and `Chase` still
+* chases through walls — give an enemy eyes and it stops.
 */
+declare class Sight extends Behavior {
+  static readonly props: PropSchema;
+  static readonly signals: readonly string[];
+  range: number;
+  coneDeg: number;
+  targetGroup: string;
+  facingPath: string;
+  eyeHeight: number;
+  chestHeight: number;
+  fillSeconds: number;
+  los: boolean;
+  /** 0..1 — how sure it is; 1 is `spotted`. */
+  suspicion: number;
+  /** The nearest node it sees right now, or null. */
+  target: Node | null;
+  private seenNow;
+  private alarmed;
+  private lastTarget;
+  /** Is this node in sight right now? */
+  sees(node: Node): boolean;
+  /** Everything in sight right now, nearest first. */
+  seen(): Node[];
+  override update(dt: number): void;
+  private facing;
+  private distanceTo;
+}
+//#endregion
+//#region src/core/pose.d.ts
+/** The node's position in WORLD space — its parents' positions and rotations composed. */
 declare function worldPosition(node: Node): number[];
 /**
-* Turn a world position into the local one `node.position` has to hold for the
-* node to END UP there — the inverse of `worldPosition` for its parent chain.
+* A LOCAL vector turned into world space by the node's own rotation and every
+* ancestor's — a barrel's forward, a muzzle's offset, a hardpoint's direction.
+*
+* `worldPosition` answers where a node IS; this answers which way it points,
+* and two games wrote it by hand (a tank's `forwardOf`, an artillery piece's
+* barrel tip) because nothing else could say it. `worldDirection(node, [0,0,1])`
+* is the +Z-forward convention every 3D skin in this engine follows.
 */
+declare function worldDirection(node: Node, local: readonly number[]): number[];
+/** The local `position` that puts `node` at `world` — the inverse of `worldPosition`. */
 declare function localFromWorld(node: Node, world: readonly number[]): number[];
 //#endregion
 //#region src/gameplay/turret.d.ts
@@ -1468,7 +1991,13 @@ declare function localFromWorld(node: Node, world: readonly number[]): number[];
 *   shot takes one, puts it at the turret plus `muzzle`, points its
 *   `Projectile` at the target and adds it under `into` (the turret's parent
 *   when empty). The clone does the hurting then — give it `DamageOnContact`.
-* - `facePath` turns a barrel toward the target at `turnSpeed`.
+* - `facePath` turns a barrel toward the target at `turnSpeed` — and the
+*   `muzzle` offset rides THAT node, so a shell leaves the tip of the barrel
+*   wherever it happens to be pointing.
+* - **`arc`** lobs: a shell with `Projectile.gravity` aimed straight at
+*   anything far away falls out of the sky long before it arrives, so a
+*   lobbing gun solves its launch angle (`'low'` flat and fast, `'high'` over
+*   whatever stands in between) and ELEVATES the barrel to match.
 *
 * Signals: `acquired(target)` when something comes in range, `fired(target)`
 * per shot, `lost()` when nothing live is in range any more.
@@ -1477,6 +2006,7 @@ declare class Turret extends Behavior {
   static readonly props: PropSchema;
   static readonly signals: readonly string[];
   targetGroup: string;
+  requireSight: boolean;
   range: number;
   damage: number;
   cooldown: number;
@@ -1484,6 +2014,7 @@ declare class Turret extends Behavior {
   prefab: string;
   muzzle: number[];
   into: string;
+  arc: "flat" | "low" | "high";
   facePath: string;
   turnSpeed: number;
   /** What it is shooting at right now, or null. */
@@ -1492,7 +2023,18 @@ declare class Turret extends Behavior {
   shots: number;
   private wait;
   override onReady(): void;
+  /** `requireSight`: a static-only ray from the turret to the target reaches it. */
+  private canSee;
   override update(dt: number): void;
+  /** Where a clone actually leaves from: the turret plus its muzzle, turned by the barrel. */
+  private muzzleAt;
+  /**
+  * The heading of this shot: straight at the target, or the arc that lands on
+  * it. Solved from the MUZZLE, which is where the shell starts.
+  */
+  private aimAt;
+  /** The shell's own numbers, read off the template that will be cloned. */
+  private shellBallistics;
   /** One clone from the shelf, at the muzzle, aimed at the target, into the container. */
   private launch;
 }
@@ -1509,4 +2051,4 @@ declare function registerGameplayBehaviors(opts?: {
   replace?: boolean;
 }): void;
 //#endregion
-export { CameraShake, Chase, Checkpoint, Collector, Cooldown, Currency, DamageOnContact, DayNight, type DayPhase, FaceTarget, FloatAway, FollowCamera, GAMEPLAY_BEHAVIORS, GameFlow, type GameFlowState, Health, Interactable, Lifetime, MoveTo, Oscillate, PathFollow, Patrol, Pickup, PrefabShelf, Projectile, SavePoint, ScoreKeeper, Spawner, Turret, Wander, WaveSpawner, ZombieAI, goToScene, hitStop, localFromWorld, phaseOf, registerGameplayBehaviors, restartScene, screenFlash, worldPosition };
+export { type BallisticPathOptions, Blast, CameraShake, Chase, ChaseCamera, Checkpoint, Collector, Cooldown, Currency, DamageOnContact, DayNight, type DayPhase, FaceTarget, FloatAway, FollowCamera, GAMEPLAY_BEHAVIORS, GameFlow, type GameFlowState, GroupCamera, Health, Interactable, Lifetime, Mount, MoveTo, Oscillate, PathFollow, Patrol, Phases, Pickup, PrefabShelf, Projectile, SavePoint, ScoreKeeper, Sight, Spawner, Turret, Wander, WaveSpawner, ZombieAI, ballisticAim, ballisticPath, goToScene, hitStop, localFromWorld, maxRangeAim, phaseOf, registerGameplayBehaviors, restartScene, screenFlash, worldDirection, worldPosition };