incanto 0.1.0

package/dist/gameplay.d.ts

@@ -0,0 +1,543 @@
+import { c as JsonValue } from "./schema-CcoWb32N.js";
+import { T as Node, l as PropSchema, n as BehaviorCtor, t as Behavior } from "./behavior-BAQq7HGM.js";
+
+//#region src/gameplay/chase.d.ts
+/**
+* Home in on a target node — the workhorse enemy AI. Each frame moves toward
+* `target.position` at `speed`, stopping once within `stopRange` (melee reach).
+* Dimension-agnostic.
+*
+* - `reachedTarget` fires once when it first enters `stopRange` (re-arms after
+*   it leaves), so wire it to an attack.
+* - `loseRange` (>0) gives up the chase when the target gets that far away,
+*   emitting `lostTarget` once.
+* - `moveParent` (default false) moves the parent node instead of this one.
+*   A node carries ONE behavior, so an enemy whose ROOT must hold `Health`
+*   (e.g. for `Health.freeOnDeath` clone-safe cleanup) puts `Chase` on a CHILD
+*   and sets `moveParent:true` — the AI child drives the whole entity. Distance
+*   is measured from the moved node (the parent).
+*/
+declare class Chase extends Behavior {
+  static readonly props: PropSchema;
+  static readonly signals: readonly string[];
+  target: string;
+  speed: number;
+  stopRange: number;
+  loseRange: number;
+  moveParent: boolean;
+  private inRange;
+  private lost;
+  override onReady(): void;
+  override update(dt: number): void;
+}
+//#endregion
+//#region src/gameplay/collector.d.ts
+/**
+* A tally for the "collect N things" pattern, living on the collector itself
+* (usually the player). Adds its node to `group` at ready so Pickups whose
+* `collectorGroup` matches will count it as a collector.
+*
+* Wire a Pickup's `collected(value, other) → Collector.collect` (the value is
+* the first arg) — `total` accumulates and `totalChanged(total)` fires.
+* (Pickup also notifies a global ScoreKeeper; Collector is the per-actor tally,
+* e.g. for split-screen or "each player's coins".)
+*/
+declare class Collector extends Behavior {
+  static readonly props: PropSchema;
+  static readonly signals: readonly string[];
+  group: string;
+  /** Running sum of collected values. */
+  total: number;
+  override onReady(): void;
+  /** Add `value` to the tally and emit `totalChanged`. */
+  collect(value: number): void;
+}
+//#endregion
+//#region src/gameplay/health.d.ts
+/**
+* Hit points with regeneration and post-hit invulnerability (i-frames) —
+* the universal "this thing can be hurt and can die" behavior.
+*
+* Other behaviors hurt it through `damage(n)` (e.g. `DamageOnContact` finds a
+* target's Health and calls it); games heal/kill via `heal(n)` / `kill()`.
+* Wire its `died` signal to a `ScoreKeeper.loseLife`, a respawn, etc.
+*
+* `freeOnDeath` (default false) `queueFree()`s the Health node itself when it
+* dies. Because it is NODE-LOCAL it clones perfectly — this is THE way to free
+* dying SPAWNED entities. Scene-level `connections` (e.g. `died → queueFree`)
+* are NOT copied onto Spawner/WaveSpawner clones, so a `died` connection only
+* ever wires the template, never the live clones; `freeOnDeath` needs no
+* connection and so works on every clone.
+*
+* Dimension-agnostic: no node geometry, just numbers — testable headlessly.
+*/
+declare class Health extends Behavior {
+  static readonly props: PropSchema;
+  static readonly signals: readonly string[];
+  max: number;
+  regenPerSec: number;
+  invulnerableFor: number;
+  freeOnDeath: boolean;
+  /** Current hit points (set to `max` on ready). */
+  current: number;
+  private invulnTimer;
+  private dead;
+  /** True once `current` has hit 0 — `died` fires at most once per life. */
+  get isDead(): boolean;
+  /** Seconds of i-frames remaining (0 = vulnerable). */
+  get invulnerableRemaining(): number;
+  override onReady(): void;
+  override update(dt: number): void;
+  /** Apply `n` damage. No-op while invulnerable or already dead. Emits `damaged`. */
+  damage(n: number): void;
+  /** Restore `n` hit points (clamped to `max`). No-op when dead. Emits `healed`. */
+  heal(n: number): void;
+  /** Drop to 0 and die immediately (ignores i-frames). */
+  kill(): void;
+  private setCurrent;
+  private die;
+}
+//#endregion
+//#region src/gameplay/damage-on-contact.d.ts
+/**
+* Deals damage to whatever it touches — projectiles, spikes, lava, enemy
+* hitboxes. Must sit on an Area2D/Area3D (listens to `triggerEnter`).
+*
+* On overlap it finds the contacted entity's `Health` behavior (see
+* `findHealth` for the exact search order) and calls `damage(amount)`, then
+* emits `dealtDamage(amount, targetNode)`.
+*
+* - `targetGroup` (default '' = anything) gates who can be hurt: only a target
+*   whose Health-owner node is in that group takes damage. This is how you stop
+*   enemies killing each other — give the player's weapon `targetGroup:'enemy'`
+*   and each enemy's contact hitbox `targetGroup:'player'`.
+* - `oncePerTarget` (default) prevents re-hitting the same node (a stationary
+*   hazard would otherwise drain a resting body every frame).
+* - `destroySelf` frees the hazard after a hit (single-use projectiles).
+*
+* SCORING PATTERN (clone-safe): wire the KILLER's `dealtDamage` →
+* `ScoreKeeper.addScore`. The weapon is usually a non-cloned node (it lives on
+* the player), so a scene connection on it survives — unlike a connection on a
+* spawned enemy, which never clones.
+*/
+declare class DamageOnContact extends Behavior {
+  static readonly props: PropSchema;
+  static readonly signals: readonly string[];
+  amount: number;
+  targetGroup: string;
+  oncePerTarget: boolean;
+  destroySelf: boolean;
+  private readonly hit;
+  override onReady(): void;
+  private tryDamage;
+}
+//#endregion
+//#region src/gameplay/follow-camera.d.ts
+/**
+* Make the node it sits on chase a target's position — THE camera-follow
+* behavior. Put it on a `Camera2D`/`Camera3D` (whose `position` is the view
+* center/eye) and point `target` at the player; every frame the camera lerps
+* toward `target.position + offset`.
+*
+* Dimension-agnostic: works on `[x,y]` (2D) and `[x,y,z]` (3D) positions.
+*
+* - `smoothing` (0..1) is a per-frame retention factor: 0 = instant snap,
+*   0.85–0.95 = smooth drag (frame-rate independent at a 60fps reference).
+* - `deadzone` keeps the camera still until the target drifts that far from the
+*   desired point — no jitter when the player makes tiny moves.
+*/
+declare class FollowCamera extends Behavior {
+  static readonly props: PropSchema;
+  static readonly signals: readonly string[];
+  target: string;
+  offset: number[];
+  smoothing: number;
+  deadzone: number;
+  override onReady(): void;
+  override update(dt: number): void;
+}
+//#endregion
+//#region src/gameplay/interactable.d.ts
+/**
+* A proximity-gated "press to use" — doors, levers, chests, NPCs. Each frame,
+* if an actor in `actorGroup` is within `range` (distance on `position` arrays,
+* 2D or 3D) and the `action` input was just pressed, emits
+* `interacted(actor)` (the nearest in-range actor).
+*
+* Wire `interacted → YourBehavior.someMethod`, or read it from a connection.
+*/
+declare class Interactable extends Behavior {
+  static readonly props: PropSchema;
+  static readonly signals: readonly string[];
+  action: string;
+  range: number;
+  actorGroup: string;
+  override update(): void;
+}
+//#endregion
+//#region src/gameplay/lifetime.d.ts
+/**
+* Self-destruct after a fixed time — bullets, particles, temporary spawns,
+* pickups that vanish. Accumulates `dt`; on elapse emits `expired` then
+* `queueFree()`s its node.
+*
+* With `startOnSignal: true` the countdown is armed manually via `startTimer()`
+* (wire a signal → `startTimer`), so the lifetime begins on an event rather
+* than at spawn.
+*/
+declare class Lifetime extends Behavior {
+  static readonly props: PropSchema;
+  static readonly signals: readonly string[];
+  seconds: number;
+  startOnSignal: boolean;
+  private elapsed;
+  private running;
+  private fired;
+  override onReady(): void;
+  /** Arm (or re-arm) the countdown from zero. */
+  startTimer(): void;
+  override update(dt: number): void;
+}
+//#endregion
+//#region src/gameplay/tween.d.ts
+/** Easing curves shared by the tween behaviors (MoveTo, …). Pure math. */
+type EaseName = "linear" | "easeIn" | "easeOut" | "easeInOut";
+//#endregion
+//#region src/gameplay/move-to.d.ts
+/**
+* Tween the node from where it starts to a fixed `to` position over `duration`
+* seconds, through an easing curve — opening doors, sliding platforms, UI
+* pop-ins, scripted moves. Emits `arrived` once at the end.
+*
+* `startOnSignal: true` arms it manually via `start()` (wire a signal → `start`)
+* so the move plays on an event; otherwise it begins at ready. Dimension-
+* agnostic (`[x,y]` / `[x,y,z]`).
+*/
+declare class MoveTo extends Behavior {
+  static readonly props: PropSchema;
+  static readonly signals: readonly string[];
+  to: number[];
+  duration: number;
+  ease: EaseName;
+  startOnSignal: boolean;
+  private from;
+  private elapsed;
+  private running;
+  private arrivedFired;
+  override onReady(): void;
+  /** Begin (or restart) the move from the node's CURRENT position. */
+  start(): void;
+  override update(dt: number): void;
+}
+//#endregion
+//#region src/gameplay/oscillate.d.ts
+declare const AXES: readonly ["x", "y", "z"];
+type Axis = (typeof AXES)[number];
+declare const MODES: readonly ["position", "rotation", "scale"];
+type Mode = (typeof MODES)[number];
+/**
+* Continuous sine motion around a value — floating platforms, bobbing pickups,
+* spinning/pulsing coins. Drives one `axis` of the node's `position`, `rotation`
+* (`mode: 'rotation'` — a "spin" when on z), or `scale` (a "pulse"):
+*
+*     value = start + amplitude · sin(2π · frequency · t)
+*
+* The baseline (`start`) is captured at ready, so it layers on top of authored
+* transforms. Dimension-agnostic; on a 2D node `rotation` is the scalar spin
+* (use `axis: 'z'`).
+*/
+declare class Oscillate extends Behavior {
+  static readonly props: PropSchema;
+  static readonly signals: readonly string[];
+  axis: Axis;
+  amplitude: number;
+  frequency: number;
+  mode: Mode;
+  private base;
+  private time;
+  override onReady(): void;
+  override update(dt: number): void;
+  /** Whether the target channel is the node's scalar 2D rotation. */
+  private isScalarRotation;
+  private readChannel;
+  private writeChannel;
+}
+//#endregion
+//#region src/gameplay/patrol.d.ts
+/**
+* Walk the node along a fixed list of waypoints at constant speed — guards,
+* platforms, moving hazards. `points` are positions (`[x,y]` / `[x,y,z]`) OR
+* node paths whose `position` is read each frame (so you can author markers in
+* the scene). On arrival emits `reachedPoint(index)`; `pauseAt` holds at each
+* point before moving on.
+*
+* - `loop` (default) — after the last point, head back to the first.
+* - `mode: 'pingpong'` — reverse direction at each end instead of wrapping.
+*/
+declare class Patrol extends Behavior {
+  static readonly props: PropSchema;
+  static readonly signals: readonly string[];
+  points: JsonValue[];
+  speed: number;
+  loop: boolean;
+  mode: string;
+  pauseAt: number;
+  private index;
+  private direction;
+  private pauseTimer;
+  override onReady(): void;
+  override update(dt: number): void;
+  /** Resolve waypoint `i` to a position, reading node paths live. */
+  private pointAt;
+  private advance;
+}
+//#endregion
+//#region src/gameplay/pickup.d.ts
+/**
+* A collectible that vanishes when a collector overlaps it. Must sit on an
+* Area2D/Area3D (it listens to the unified `triggerEnter`).
+*
+* On overlap with a node in `collectorGroup`, emits `collected(value, other)`
+* then `queueFree()`s itself. Wire `collected → ScoreKeeper.addScore` (the
+* value is the first arg) or `collected → Collector.collect`.
+*/
+declare class Pickup extends Behavior {
+  static readonly props: PropSchema;
+  static readonly signals: readonly string[];
+  value: number;
+  kind: string;
+  collectorGroup: string;
+  private collectedAlready;
+  override onReady(): void;
+  private tryCollect;
+}
+//#endregion
+//#region src/gameplay/projectile.d.ts
+/**
+* Constant-velocity motion in a straight line — bullets, arrows, thrown rocks.
+* Pure movement by design: pair it with `DamageOnContact` (deal damage on hit),
+* `Lifetime` (auto-despawn), and an Area collider on the same node. Compose,
+* don't conflate.
+*
+* `direction` is either an explicit vector (`[x,y]` / `[x,y,z]`, normalized) or
+* the string `'forward'`, derived from the node's `rotation` (2D: degrees
+* clockwise, +x at 0). It is a union-typed prop, so its schema default is
+* `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.
+*/
+declare class Projectile extends Behavior {
+  static readonly props: PropSchema;
+  static readonly signals: readonly string[];
+  speed: number;
+  direction: JsonValue;
+  gravity: number;
+  private velocity;
+  override onReady(): void;
+  override update(dt: number): void;
+  /** Resolve `direction` to a unit vector, deriving 'forward' from rotation. */
+  private resolveDirection;
+  private forwardFromRotation;
+}
+//#endregion
+//#region src/gameplay/score-keeper.d.ts
+/**
+* The game's state hub — score, lives, and win/lose detection. Put it on the
+* Root/Game node and wire gameplay signals into its methods (e.g. a Pickup's
+* `collected → addScore`, a Health's `died → loseLife`).
+*
+* - `score` rises via `addScore` / `setScore`; reaching `scoreToWin` (>0)
+*   emits `won` once.
+* - `lives` (>0) shrinks via `loseLife`; reaching 0 emits `lost` once.
+*/
+declare class ScoreKeeper extends Behavior {
+  static readonly props: PropSchema;
+  static readonly signals: readonly string[];
+  score: number;
+  lives: number;
+  scoreToWin: number;
+  private hasWon;
+  private hasLost;
+  override onReady(): void;
+  /** Add `n` to the score (negative subtracts), emit `scoreChanged`, check win. */
+  addScore(n: number): void;
+  /** Set the score to `value`, emit `scoreChanged`, check win. */
+  setScore(value: number): void;
+  /** Lose one life (no-op when lives disabled or already lost). Emits `lifeLost`, then `lost` at 0. */
+  loseLife(): void;
+}
+//#endregion
+//#region src/gameplay/spawner.d.ts
+/**
+* Drip-feed clones of a template into the scene on a timer — enemy generators,
+* pickup fountains, particle emitters. `prefab` is a node PATH to a template
+* (usually a hidden `visible: false` child) that gets cloned each `interval`.
+*
+* - `max` caps LIVE instances (0 = unlimited); the count drops automatically as
+*   spawned children free themselves (e.g. via `Lifetime` or `Health.died`), so
+*   the spawner refills.
+* - `total` caps LIFETIME spawns (0 = infinite); on the last one it emits
+*   `finished` and stops.
+* - `autoStart` (default) begins ticking at ready; otherwise call `start()`.
+*
+* Emits `spawned(node)` per spawn. Methods: `spawn()`, `start()`, `stop()`.
+*/
+declare class Spawner extends Behavior {
+  static readonly props: PropSchema;
+  static readonly signals: readonly string[];
+  prefab: string;
+  interval: number;
+  max: number;
+  at: number[];
+  autoStart: boolean;
+  total: number;
+  private readonly source;
+  private template;
+  private readonly live;
+  private timer;
+  private running;
+  private spawnedCount;
+  private done;
+  /** Live (un-freed) spawned instances. */
+  get liveCount(): number;
+  /** @internal The detached template node (test/debug only). */
+  _templateForTest(): Node;
+  override onReady(): void;
+  /** Begin (or resume) interval spawning. */
+  start(): void;
+  /** Pause interval spawning (spawn() still works). */
+  stop(): void;
+  /** Spawn one immediately (ignores the timer; still respects max/total). */
+  spawn(): Node | null;
+  override update(dt: number): void;
+  /** Drop instances that have been freed (parent cleared on free/queueFree). */
+  private prune;
+}
+//#endregion
+//#region src/gameplay/wander.d.ts
+/**
+* Aimless roaming inside a circle around the spawn point — idle critters,
+* ambient wildlife, restless guards. Picks a random destination within `radius`
+* of where it started, walks there at `speed`, then (every `changeEvery`
+* seconds, or on arrival) picks a new one. Uses `this.rng`, so a seeded engine
+* wanders identically every run (replayable, test-stable).
+*
+* Dimension-agnostic: roams in the plane of however many position components
+* the node has (2D `[x,y]`, 3D `[x,z]` ground plane keeping y).
+*/
+declare class Wander extends Behavior {
+  static readonly props: PropSchema;
+  static readonly signals: readonly string[];
+  speed: number;
+  radius: number;
+  changeEvery: number;
+  private origin;
+  private goal;
+  private timer;
+  override onReady(): void;
+  override update(dt: number): void;
+  private pickGoal;
+}
+//#endregion
+//#region src/gameplay/wave-spawner.d.ts
+/**
+* Sequenced enemy waves — the survivor/tower-defense backbone. Each entry in
+* `waves` is `{ prefab, count, interval, delayBefore }`: after `delayBefore`
+* seconds it spawns `count` clones of `prefab` (a hidden template path) one
+* 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.
+*/
+declare class WaveSpawner extends Behavior {
+  static readonly props: PropSchema;
+  static readonly signals: readonly string[];
+  waves: JsonValue[];
+  autoStart: boolean;
+  private readonly source;
+  private parsed;
+  private readonly live;
+  private waveIndex;
+  private phase;
+  private timer;
+  private spawnedThisWave;
+  private announced;
+  override onReady(): void;
+  /** Start (or restart from) wave 0. */
+  start(): void;
+  override update(dt: number): void;
+  private beginWave;
+  private prune;
+  private parseWave;
+}
+//#endregion
+//#region src/gameplay/zombie-ai.d.ts
+/**
+* The staple "zombie / monster" AI: SHAMBLE around on its own, then LOCK ON and
+* CHARGE a target (the player) once it wanders within `aggroRange` — giving up
+* again past `deAggroRange` (hysteresis, so it doesn't flicker at the boundary).
+* One behavior covers both phases so a single node can be a complete enemy
+* (`Wander` + `Chase` can't co-exist — a node carries ONE behavior).
+*
+* While NOT aggroed it roams: with `goalTarget` set it DRIFTS toward that node
+* (e.g. the objective the horde is marching on) with random lateral jitter, so it
+* reads as wandering yet still advances; without one it roams around its spawn.
+*
+* Emits `movementStateChanged('idle'|'walk'|'run')` on every change so a skin can
+* swap animation clips (shamble while roaming, sprint while charging), plus
+* `enteredAggro` / `exitedAggro` (wire to a growl, a glow, a speed-up).
+*
+* Dimension-agnostic; in 3D it moves only in the ground plane (x,z) and leaves
+* the up axis (y) to physics, so a CharacterBody3D settles on terrain.
+*
+* `moveParent` (default false) moves the parent instead of this node — the
+* AI-on-a-child pattern, so the entity ROOT can hold `Health` (clone-safe
+* `freeOnDeath`) while this child drives movement.
+*/
+declare class ZombieAI extends Behavior {
+  static readonly props: PropSchema;
+  static readonly signals: readonly string[];
+  aggroTarget: string;
+  aggroRange: number;
+  deAggroRange: number;
+  chaseSpeed: number;
+  wanderSpeed: number;
+  wanderRadius: number;
+  wanderChangeEvery: number;
+  goalTarget: string;
+  stopRange: number;
+  moveParent: boolean;
+  private aggro;
+  private started;
+  private home;
+  private goal;
+  private timer;
+  private lastState;
+  /** The node we actually move (the parent under moveParent, else this one). */
+  private mover;
+  private effectiveDeAggro;
+  override onReady(): void;
+  override update(dt: number): void;
+  /** Move `mover` toward `to` in the GROUND PLANE; returns true once within
+  *  stopRange (no overshoot). Leaves the up axis (3D y) to physics. */
+  private approach;
+  /** Distance ignoring the up axis in 3D (so terrain height never blocks aggro). */
+  private groundDistance;
+  private setState;
+  private pickGoal;
+}
+//#endregion
+//#region src/gameplay/index.d.ts
+/** Every built-in gameplay behavior, keyed by its registration name. */
+declare const GAMEPLAY_BEHAVIORS: Readonly<Record<string, BehaviorCtor>>;
+/**
+* Register all built-in gameplay behaviors. Idempotent and hot-reload tolerant
+* (`replace: true`) — calling it twice, or after a user already registered a
+* same-named behavior, is safe; pass `replace: false` to fail on conflicts.
+*/
+declare function registerGameplayBehaviors(opts?: {
+  replace?: boolean;
+}): void;
+//#endregion
+export { Chase, Collector, DamageOnContact, FollowCamera, GAMEPLAY_BEHAVIORS, Health, Interactable, Lifetime, MoveTo, Oscillate, Patrol, Pickup, Projectile, ScoreKeeper, Spawner, Wander, WaveSpawner, ZombieAI, registerGameplayBehaviors };

package/dist/gameplay.js

@@ -0,0 +1,2 @@
+import { _ as Health, a as Wander, c as Projectile, d as Oscillate, f as MoveTo, g as DamageOnContact, h as FollowCamera, i as WaveSpawner, l as Pickup, m as Interactable, n as registerGameplayBehaviors, o as Spawner, p as Lifetime, r as ZombieAI, s as ScoreKeeper, t as GAMEPLAY_BEHAVIORS, u as Patrol, v as Collector, y as Chase } from "./gameplay-Ccruc3Wd.js";
+export { Chase, Collector, DamageOnContact, FollowCamera, GAMEPLAY_BEHAVIORS, Health, Interactable, Lifetime, MoveTo, Oscillate, Patrol, Pickup, Projectile, ScoreKeeper, Spawner, Wander, WaveSpawner, ZombieAI, registerGameplayBehaviors };