incanto 0.69.0 → 0.71.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-rm8vVzu_.js";
-import { c as JsonValue, s as JsonObject } from "./schema-B6ugCV1Q.js";
+import { b as Engine, d as PropSchema, jt as Node, n as BehaviorCtor, t as Behavior } from "./behavior-Dcz0fr1S.js";
+import { c as JsonValue, s as JsonObject } from "./rng-Bb-IutXB.js";
 
 //#region src/gameplay/chase.d.ts
 /**
@@ -58,6 +58,8 @@ declare class Collector extends Behavior {
   /** How many have been picked up so far. */
   override serialize(): JsonValue;
   override deserialize(data: JsonValue): void;
+  /** The counter on screen. `collect(0)` used to be the only way to repaint it. */
+  override announce(): void;
 }
 //#endregion
 //#region src/gameplay/currency.d.ts
@@ -85,10 +87,21 @@ declare class Currency extends Behavior {
   spend(cost: number): boolean;
   /** Take payment in. */
   earn(gain: number): void;
+  /** What has already been complained about, so a loop says it once. */
+  private complained;
+  /**
+  * A zero is ordinary; a NEGATIVE is a caller that flipped a sign.
+  *
+  * Reported rather than thrown: this is called from game code inside a frame,
+  * and a throw here quarantines the node holding the player's money.
+  */
+  private refuseNonsense;
   /** Set it outright (a shop that grants, a cheat, a restore). */
   setAmount(next: number): void;
   override serialize(): JsonValue;
   override deserialize(data: JsonValue): void;
+  /** The wallet on screen — `setAmount`'s own doc comment already named a restore. */
+  override announce(): void;
 }
 //#endregion
 //#region src/gameplay/health.d.ts
@@ -116,6 +129,7 @@ declare class Health extends Behavior {
   regenPerSec: number;
   invulnerableFor: number;
   freeOnDeath: boolean;
+  freeParent: boolean;
   /** Current hit points (set to `max` on ready). */
   current: number;
   private invulnTimer;
@@ -194,6 +208,14 @@ declare class Health extends Behavior {
   /** Current HP and whether death already fired — `max` comes back from JSON. */
   override serialize(): JsonValue;
   override deserialize(data: JsonValue): void;
+  /**
+  * Repaint the bar. Not `died` — a save is being read, nobody just died.
+  *
+  * This one needed the hook most: `setCurrent` is private AND early-returns
+  * when the value is unchanged, so no call a game could make would repaint a
+  * restored bar. It read 100 at 38 HP until the next hit teleported it to 37.
+  */
+  override announce(): void;
 }
 //#endregion
 //#region src/gameplay/damage-on-contact.d.ts
@@ -297,6 +319,7 @@ declare class FollowCamera extends Behavior {
   offset: number[];
   smoothing: number;
   deadzone: number;
+  private shakeRng;
   override onReady(): void;
   private shakeMag;
   private shakeT;
@@ -321,6 +344,8 @@ declare class Interactable extends Behavior {
   action: string;
   range: number;
   actorGroup: string;
+  /** Actions already reported missing, so a per-frame read says it once. */
+  private readonly reportedActions;
   override update(): void;
 }
 //#endregion
@@ -466,7 +491,31 @@ declare class Patrol extends Behavior {
   * this one is invisible to it.
   */
   private reportDeadWaypoint;
-  /** Resolve waypoint `i` to a position, reading node paths live. */
+  /**
+  * Resolve waypoint `i` to a position in the MOVER's frame, reading node paths
+  * live.
+  *
+  * A node-path waypoint used to return the marker's raw `position`, which is
+  * parent-relative — and it was then fed to `moveToward(mover.position, …)`,
+  * i.e. read in the MOVER's frame. So a walker and its markers under different
+  * parents walked a shifted copy of the path, silently, with the marker nodes
+  * sitting right there in the scene. Measured on a tower-defence lane
+  * organised the ordinary way (markers under `/root/Path`, spawns under a
+  * container at [-50, 90]): every creep stacked motionless 90 px below and
+  * 72 px short of the keep, `incanto-check` `1/1 scene(s) valid`, zero errors,
+  * zero warnings, and the wave could be neither won nor lost.
+  *
+  * `Chase` has converted through world space since the identical bug was found
+  * there ("comparing two nodes' raw `position` only worked while they happened
+  * to share a parent"), and a `FollowCamera` aimed at a node uses its world
+  * position too. Patrol was the outlier.
+  *
+  * A LITERAL array stays local, because that is the only frame an author can
+  * mean when they type numbers into a behaviour's props.
+  *
+  * `reportDeadWaypoint` could not see this: it fires when a path resolves to
+  * NOTHING, and a path that resolves into the wrong frame resolves fine.
+  */
   private pointAt;
   private advance;
 }
@@ -508,14 +557,58 @@ declare class Pickup extends Behavior {
 * `null` (the engine's "any JSON" escape hatch) and `null` means `'forward'`.
 * `gravity` adds a constant downward (+y, the 2D y-down convention) pull, for
 * lobbed/arcing shots.
+*
+* **Every prop here is live.** `speed` and `direction` re-bake the heading when
+* written, and the heading is resolved on the FIRST STEP rather than at
+* `onReady` — because `onReady` is before the one place a game aims a spawned
+* bullet. `SpawnSource.spawn` ends with `parent.addChild(clone)` and `Spawner`
+* emits `spawned(node)` after that, so a handler that sets a rotation or a
+* direction was always too late. Measured at speed 100 over 60 frames:
+*
+* ```
+* A rotation 0  direction [0,1]     -> pos [  0, 100]   authored: obeyed
+* B rotation 90 direction "forward" -> pos [  0, 100]   authored: obeyed
+* C rotation 90 set after addChild  -> pos [100,   0]   IGNORED
+* D direction [0,1] set after add   -> pos [100,   0]   IGNORED — and it read
+*                                                       back [0,1] while
+*                                                       travelling +x
+* ```
+*
+* What is deliberately NOT live is `rotation` after that first step: a
+* projectile that spins for looks would have its spin become its trajectory.
+* Call `aim()` to re-derive from the current rotation on purpose.
 */
 declare class Projectile extends Behavior {
   static readonly props: PropSchema;
   static readonly signals: readonly string[];
-  speed: number;
-  direction: JsonValue;
+  private _speed;
+  private _direction;
   gravity: number;
+  /** The straight-line part, `direction × speed`. Empty until the first step. */
   private velocity;
+  /**
+  * The +y accumulated by `gravity`, kept APART from `velocity`.
+  *
+  * Re-aiming replaces the straight-line part; the fall is a fact about the
+  * world, not about the shot, so an arrow re-aimed halfway down keeps falling
+  * rather than snapping back to level.
+  */
+  private fall;
+  /** Units per second along `direction`. Writable at any time. */
+  get speed(): number;
+  set speed(value: number);
+  /** A vector (`[x,y(,z)]`) or `'forward'`. Writable at any time. */
+  get direction(): JsonValue;
+  set direction(value: JsonValue);
+  private get armed();
+  /**
+  * Re-derive the heading from `direction` (or, for `'forward'`, from the
+  * node's CURRENT rotation) and bake it into the velocity.
+  *
+  * 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;
   override onReady(): void;
   override update(dt: number): void;
   /** Resolve `direction` to a unit vector, deriving 'forward' from rotation. */
@@ -642,6 +735,14 @@ declare class ScoreKeeper extends Behavior {
   /** The run's progress. `scoreToWin` is balance and comes back from JSON. */
   override serialize(): JsonValue;
   override deserialize(data: JsonValue): void;
+  /**
+  * The score line and the lives counter. NOT `won`/`lost`.
+  *
+  * Re-firing those on load is how a Continue lands straight on the game-over
+  * screen it was loaded to escape — the flags come back through `hasWon` /
+  * `hasLost` and the game reads them, rather than being told again.
+  */
+  override announce(): void;
 }
 //#endregion
 //#region src/gameplay/spawner.d.ts
@@ -679,6 +780,7 @@ declare class Spawner extends Behavior {
   get liveCount(): number;
   /** @internal The detached template node (test/debug only). */
   _templateForTest(): Node;
+  override onEnterTree(): void;
   override onReady(): void;
   /** Begin (or resume) interval spawning. */
   start(): void;
@@ -724,8 +826,9 @@ declare class Wander extends Behavior {
 * every `interval` seconds, then waits until they're ALL cleared (freed) before
 * starting the next wave.
 *
-* Signals: `waveStarted(i)` when a wave begins spawning, `waveCleared(i)` when
-* its last instance frees, `allCleared` after the final wave clears.
+* Signals: `spawned(node)` per clone, `waveStarted(i)` when a wave begins
+* spawning, `waveCleared(i)` when its last instance frees, `allCleared` after
+* the final wave clears.
 */
 declare class WaveSpawner extends Behavior {
   static readonly props: PropSchema;
@@ -740,9 +843,27 @@ declare class WaveSpawner extends Behavior {
   private timer;
   private spawnedThisWave;
   private announced;
+  override onEnterTree(): void;
   override onReady(): void;
   /** Start (or restart from) wave 0. */
   start(): void;
+  /**
+  * Which wave you were on — and nothing else.
+  *
+  * `behaviorsWithoutSave` is documented as "the list to read before shipping",
+  * and nobody had read it against this repo's own examples. Five of them put a
+  * `WaveSpawner` at the centre of the game (`fps-3d`, `tps-3d`, `tps-3d-neon`,
+  * `tps-3d-ruins`, `dogfight-3d`), and every one of them saved a run on wave 3
+  * and continued it on wave 1 — silently, because a save reloads the scene
+  * from source and a fresh `onReady` honestly starts at the beginning.
+  *
+  * The wave RESTARTS rather than resuming mid-spawn, which is the same
+  * checkpoint rule the rest of the save system follows: spawned entities are
+  * never restored, so resuming "four enemies into wave 3" would mean resuming
+  * a wave whose enemies do not exist. `waveStarted` fires again for the HUD.
+  */
+  override serialize(): JsonValue;
+  override deserialize(data: JsonValue): void;
   override update(dt: number): void;
   private beginWave;
   private prune;
@@ -834,6 +955,18 @@ declare class DayNight extends Behavior {
   private baseAmbient;
   private baseExposure;
   private captured;
+  /** Said once: there was no sky to move when this first looked. */
+  private reportedNoSky;
+  /**
+  * What time it is. A save that forgets it returns you at dawn.
+  *
+  * `startHour` is the scene's opening, not the run's clock: a fresh `onReady`
+  * cannot know that this player has been out all night. `paused` goes with it
+  * because a game that stops the clock for a cutscene must not resume ticking
+  * on load.
+  */
+  override serialize(): JsonValue;
+  override deserialize(data: JsonValue): void;
   override onReady(): void;
   override update(dt: number): void;
   private applyHour;
@@ -904,6 +1037,25 @@ type GameFlowState = "playing" | "paused" | "gameover" | "won";
 /**
 * Swap to another scene behind a black fade (title→game→next level).
 * Headless (no DOM) the swap is immediate. Restores timeScale to 1.
+*
+* ONE AT A TIME. A door is usually a trigger, and a player who walks along a
+* wall of them fires several inside one fade. Measured on three doorways passed
+* in about a second:
+*
+* ```
+* setScene calls: 3 | order: ["crypt","garden","forge"]
+* final scene   : forge
+* ```
+*
+* Three complete scenes loaded and the player landed in the third — a level
+* they never walked to, from a door they never reached. Further calls while a
+* travel is in flight are IGNORED rather than queued: you already went through
+* a door, and the second one is the same input arriving twice.
+*
+* The outgoing scene also stops while the screen is black. It kept simulating
+* through the fade, so a player who triggered the door mid-fall died in the
+* level they were leaving — and the checkpoint that death wrote was for the
+* level they had left.
 */
 declare function goToScene(engine: Engine, sceneJson: JsonObject, opts?: {
   fadeSeconds?: number;
@@ -961,8 +1113,24 @@ declare class GameFlow extends Behavior {
   state: GameFlowState;
   private frozeScale;
   override onReady(): void;
-  /** The panel follows the state; nothing else may own its visibility. */
+  /**
+  * The panel follows the state; nothing else may own its visibility.
+  *
+  * …and while it is up, the layer it lives on takes ARROW KEYS AND THE PAD.
+  * `HudLayer.focusNavigation` is off by default and rightly so — a game whose
+  * HUD happens to contain a button must not lose its arrow keys the moment one
+  * exists — and `incanto-hud.md` says "turn it on for the screens that ARE
+  * menus and off again when play resumes". A pause panel IS that screen, and
+  * this is the one place in the engine that knows when it opens and closes, so
+  * every game with a pause menu was writing the same two lines or shipping a
+  * menu no controller could reach.
+  *
+  * The layer's own value is remembered and put back: a game that turned
+  * navigation on for its own reasons keeps it after a pause.
+  */
   private syncPausePanel;
+  /** The layer's own `focusNavigation`, while this flow is borrowing it. */
+  private navigationWas;
   gameOver(text?: string, color?: string): void;
   win(text?: string, color?: string): void;
   pause(): void;
@@ -971,7 +1139,7 @@ declare class GameFlow extends Behavior {
   /** Fade to another scene (next level, back to title). */
   goToScene(sceneJson: JsonObject, opts?: {
     fadeSeconds?: number;
-  }): void;
+  } | undefined): void;
   private transition;
   private freeze;
   private thaw;
@@ -1025,6 +1193,19 @@ declare class CameraShake extends Behavior {
   private t;
   private prev;
   /**
+  * Decoration draws from its OWN stream — see `effectRng`.
+  *
+  * A shake drew from `engine.rng`, the stream game logic reads and
+  * `captureState` saves, once per axis per RENDERED frame. So the player's
+  * frame rate decided the game's random numbers, and toggling the
+  * `reduceMotion` accessibility switch changed the rolls: a replay recorded at
+  * 60 fps does not reproduce on a laptop that dropped to 30, and two players
+  * with the same seed diverge because one of them was hit. The particle
+  * siblings were moved off `engine.rng` for exactly this; both camera shakes
+  * were left behind.
+  */
+  private shakeRng;
+  /**
   * Start a shake — unless the player asked for no motion.
   *
   * `settings.reduceMotion` is an accessibility switch, and camera movement the
@@ -1085,6 +1266,69 @@ declare class PathFollow extends Behavior {
   override update(dt: number): void;
 }
 //#endregion
+//#region src/gameplay/prefab-shelf.d.ts
+/**
+* A shelf of templates the GAME clones itself — towers, bolts, damage numbers.
+*
+* `Spawner` detaches its one prefab at enter, so a spawned enemy's whole
+* subtree is live and nobody has to think about it. A game that clones on its
+* own terms — a tower the player places, a bolt that tower fires — has no
+* spawner, so its templates sat in the tree as LIVE nodes: their behaviours
+* ticked, their turrets shot, and `visible: false` hid a node without switching
+* it off. The documented answer was to author every template `"enabled": false`
+* and wake the clone with `clone.behavior?.enable()`.
+*
+* That wakes ONE node, and the same docs teach that a node carries one
+* behaviour — so a prefab's parts live on children, and every one of those
+* stays asleep, silently and for good, because `enabled` is a pause switch that
+* never complains. Measured on a shipped tower defense: the bolt's
+* `Projectile` was woken and its sibling `Lifetime` was not, so every bolt that
+* MISSED flew forever — five still in the tree at 69 seconds, in a game that
+* passed its harness, its audit and every rung of the ladder.
+*
+* ```json
+* { "name": "Prefabs", "type": "Node2D", "script": { "name": "PrefabShelf" },
+*   "children": [ { "name": "Tower", "type": "Node2D", "children": [] } ] }
+* ```
+* ```ts
+* const shelf = this.node.getNode('/Game/Prefabs').behavior as PrefabShelf;
+* const tower = shelf.make('Tower');       // detached, like `duplicateNode`
+* tower.position = at;                     // set it up BEFORE it readies
+* this.node.getNode('/Game/Towers').addChild(tower);
+* ```
+*
+* The children never ENTER the tree, so nothing has to be asleep, nothing has
+* to be hidden, and `make()` hands back a clone that is awake all the way down.
+*/
+declare class PrefabShelf extends Behavior {
+  static readonly props: PropSchema;
+  static readonly signals: readonly string[];
+  prefabs: string;
+  /** Templates, in the order they were authored. */
+  private readonly held;
+  override onEnterTree(): void;
+  /** A shelf attached at runtime never saw `onEnterTree`; idempotent. */
+  override onReady(): void;
+  private claim;
+  /** What this shelf holds, in authored order. */
+  names(): string[];
+  /**
+  * A live clone of one template, DETACHED — `addChild` it yourself.
+  *
+  * Detached for the same reason `duplicateNode` is, and it is not a
+  * formality: `onReady` fires on attach, and a behaviour that reads its node
+  * there (`FloatAway` banks its starting position) would bank the wrong one.
+  * Set the clone up, then attach it.
+  *
+  * The clone is VISIBLE even if the template was authored hidden (a scene
+  * migrating off the old `visible: false` shelf keeps working), and every
+  * behaviour in it is however it was authored: awake unless the template
+  * itself asks to sleep, which is now only ever a state machine's own doing.
+  */
+  make(name: string): Node;
+  private childNames;
+}
+//#endregion
 //#region src/gameplay/spatial.d.ts
 /**
 * A node's position with every spatial ancestor's added in.
@@ -1131,4 +1375,4 @@ declare function registerGameplayBehaviors(opts?: {
   replace?: boolean;
 }): void;
 //#endregion
-export { CameraShake, Chase, Collector, Cooldown, Currency, DamageOnContact, DayNight, type DayPhase, FaceTarget, FloatAway, FollowCamera, GAMEPLAY_BEHAVIORS, GameFlow, type GameFlowState, Health, Interactable, Lifetime, MoveTo, Oscillate, PathFollow, Patrol, Pickup, Projectile, SavePoint, ScoreKeeper, Spawner, Wander, WaveSpawner, ZombieAI, goToScene, hitStop, localFromWorld, phaseOf, registerGameplayBehaviors, restartScene, screenFlash, worldPosition };
+export { CameraShake, Chase, 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, Wander, WaveSpawner, ZombieAI, goToScene, hitStop, localFromWorld, phaseOf, registerGameplayBehaviors, restartScene, screenFlash, worldPosition };

package/dist/gameplay.js

@@ -1,2 +1,2 @@
-import { A as DamageOnContact, C as restartScene, D as FaceTarget, E as FloatAway, F as localFromWorld, I as worldPosition, M as Currency, N as Collector, O as DayNight, P as Chase, S as goToScene, T as FollowCamera, _ as Cooldown, a as Wander, b as Interactable, c as SavePoint, d as Patrol, f as PathFollow, g as CameraShake, h as Lifetime, i as WaveSpawner, j as Health, k as phaseOf, l as Projectile, m as MoveTo, n as registerGameplayBehaviors, o as Spawner, p as Oscillate, r as ZombieAI, s as ScoreKeeper, t as GAMEPLAY_BEHAVIORS, u as Pickup, v as hitStop, x as GameFlow, y as screenFlash } from "./gameplay-D1KixWK8.js";
-export { CameraShake, Chase, Collector, Cooldown, Currency, DamageOnContact, DayNight, FaceTarget, FloatAway, FollowCamera, GAMEPLAY_BEHAVIORS, GameFlow, Health, Interactable, Lifetime, MoveTo, Oscillate, PathFollow, Patrol, Pickup, Projectile, SavePoint, ScoreKeeper, Spawner, Wander, WaveSpawner, ZombieAI, goToScene, hitStop, localFromWorld, phaseOf, registerGameplayBehaviors, restartScene, screenFlash, worldPosition };
+import { A as DayNight, C as goToScene, E as FollowCamera, F as Collector, I as Chase, M as DamageOnContact, N as Health, O as FloatAway, P as Currency, Q as worldPosition, S as GameFlow, Z as localFromWorld, _ as CameraShake, a as Wander, b as screenFlash, c as SavePoint, d as Pickup, f as Patrol, g as Lifetime, h as MoveTo, i as WaveSpawner, j as phaseOf, k as FaceTarget, l as Projectile, m as Oscillate, n as registerGameplayBehaviors, o as Spawner, p as PathFollow, r as ZombieAI, s as ScoreKeeper, t as GAMEPLAY_BEHAVIORS, u as PrefabShelf, v as Cooldown, w as restartScene, x as Interactable, y as hitStop } from "./gameplay-CNULJvwh.js";
+export { CameraShake, Chase, Collector, Cooldown, Currency, DamageOnContact, DayNight, FaceTarget, FloatAway, FollowCamera, GAMEPLAY_BEHAVIORS, GameFlow, Health, Interactable, Lifetime, MoveTo, Oscillate, PathFollow, Patrol, Pickup, PrefabShelf, Projectile, SavePoint, ScoreKeeper, Spawner, Wander, WaveSpawner, ZombieAI, goToScene, hitStop, localFromWorld, phaseOf, registerGameplayBehaviors, restartScene, screenFlash, worldPosition };

package/dist/{heightmap-CRK0M4jT.js → heightmap-BYgD5Edk.js}

@@ -1,4 +1,4 @@
-import { t as createNoise2D } from "./noise-CGUMx44x.js";
+import { t as createNoise2D } from "./noise-D3nPpmFg.js";
 //#region src/3d/terrain/heightmap.ts
 /**
 * Pure heightfield + splat-weight math for `Terrain3D` — NO three imports, so