@waica/engine 0.14.1 → 0.16.0

package/README.md

@@ -6,6 +6,52 @@ Waica's public engine core: entities and components, the game loop, scene and pr
 import { Component, Game, loadScene } from '@waica/engine'
 ```
 
+## Hitbox Collision Layers and Masks
+
+Every `Hitbox` belongs to one named Collision Layer and declares the other layers in which it is interested through a Collision Mask:
+
+```ts
+import { Hitbox } from '@waica/engine'
+
+entity.add(Hitbox, {
+  layer: 'projectile',
+  collidesWith: ['enemy'],
+})
+```
+
+A layer must match `^[a-z][a-z0-9-]*$`. Layer names form an open, project-owned vocabulary; matching is exact and case-sensitive. `"*"` is valid only in a mask and matches every valid layer. An empty mask means no outgoing interest. Invalid layers cannot be targeted, and invalid or non-string mask entries are ignored without runtime coercion or warnings.
+
+A pair reaches exact overlap testing when either side's mask names the other side's layer. After an overlap, only an interested side receives `onCollide`; a one-way projectile mask therefore does not notify its target. Omitted fields retain the compatibility defaults `layer: 'default'` and `collidesWith: ['*']`, so two unconfigured Hitboxes still notify both sides.
+
+Layers and masks are read while the collision-pair snapshot is consumed. A component can change them during `onUpdate` or one callback and affect later pairs in that Simulation Step. Pair order remains the original lexicographic Entity order, component callbacks remain in insertion order, and destroyed entities are still skipped between sides.
+
+### Shipped taxonomy and migration
+
+Waica's shipped prefabs use this directional policy:
+
+| Hitbox owner | `layer` | `collidesWith` |
+| --- | --- | --- |
+| Player | `player` | `['*']` |
+| Slime, blob, or orc / `Hazard` | `enemy` | `['player']` |
+| Coin, potion, or crate / `Collectible` | `collectible` | `['player']` |
+| Overlap `SceneTransition` | `scene-transition` | `['player']` |
+| Platformer projectile | `projectile` | `['enemy']` |
+
+`Collectible`, `Hazard`, overlap `SceneTransition`, and the example projectile trust those masks and no longer recheck the other Entity's role inside `onCollide`. Existing external projects using any of these handlers must explicitly migrate their sibling Hitboxes before relying on the new behavior. The defaults preserve engine-level callback delivery, but a wildcard-backed migrated handler can act on unintended default-layer entities.
+
+1. Assign `player` / `['*']` to player Hitboxes.
+2. Assign the relevant row above to each shipped handler carrier, or choose equivalent project-owned names.
+3. Run MCP `validate_project`; malformed values are errors and duplicate mask entries are warnings.
+4. Keep `trigger: 'interact'` Scene Transitions unchanged—their Hitbox mask is relevant only to overlap mode.
+
+The editor and MCP author explicit categories for newly generated player/enemy identities. NPCs, custom or identity-less characters, generic objects, and existing external project files are not inferred or rewritten. `public/waica.params.json` may override either field with the same exact values, including a `string[]` mask.
+
+## Collision broadphase
+
+The Game uses fresh internal uniform grids to accelerate automatic Hitbox dispatch, Hitbox-backed `area`/`point` queries, and Solid-backed `ray` queries. Hitboxes and Solids stay in separate domains. `nearest`, `DynamicBody` physical-contact solving, Pointer picking, navigation, and unrelated scans remain linear or otherwise unchanged.
+
+The grid changes candidate discovery only: existing exact geometry is still authoritative. Each operation observes candidates alive at its start, preserves Entity or Solid source order and tie behavior, and recomputes after scene swaps, spawns, movement, shape edits, or Tilemap-derived Solid changes. Oversized bodies and query regions fall back conservatively, so they may cost more but cannot lose results. Grid sizing, occupancy limits, indices, and rebuild controls are deliberately package-internal and have no public tuning API.
+
 ## Logical spatial queries
 
 Every `Game` owns one stable `game.query` service. Queries use logical XY coordinates, including in isometric scenes, and return typed live engine objects:
@@ -45,7 +91,7 @@ Calls eagerly snapshot candidates that are alive at call start. Results preserve
 
 Invalid inputs fail closed without throwing: invalid `area` bodies and non-finite point coordinates return `[]`; invalid nearest coordinates or radii return `null`; and ray returns `null` for non-finite values, a zero direction, or a negative distance. Nearest permits positive `Infinity`; ray distance must be finite and may be zero. Zero-area candidate geometry never matches.
 
-Area and point intentionally use the collision system's polygonally approximated circle/ellipse outline. Ray queries intersect circle-shaped Solids as analytic ellipses and return their exact outward unit normal.
+Area and point intentionally use the collision system's polygonally approximated circle/ellipse outline. Ray queries intersect circle-shaped Solids as analytic ellipses and return their exact outward unit normal. Collision Layers and Masks never filter `area` or `point`; use a query filter when category-like eligibility is needed.
 
 ## Component lifecycle
 
@@ -124,3 +170,26 @@ class PathFinder extends Component {
 ```
 
 The return value still passes through the bounded safe projector; it is not serialized with arbitrary `toJSON()`. The package root exports the Runtime Snapshot, projection marker, metadata, control and activation types plus `RUNTIME_BRIDGE_PROTOCOL_VERSION` and `RUNTIME_PROJECTION_LIMITS`.
+
+## game.time: simulated timers and tweens
+
+Every `Game` owns a `time: GameTime` service — `after`, `every`, a single-number `tween`, and a `now` reader — advanced only by Simulation Steps (ADR 0014), never by the wall clock:
+
+```ts
+const stun = game.time.after(0.3, () => fsm.goto('idle'), { owner: entity })
+game.time.every(1, () => game.stats.set('clock', game.time.now), { scope: 'session' })
+game.time.tween({
+  from: 0, to: 1, seconds: 0.5, easing: 'quadOut',
+  onUpdate: (v) => { overlay.opacity = v },
+  onComplete: () => game.loadSceneByName('b'),
+  owner: entity,
+})
+stun.remaining // seconds left, counting down
+game.time.now  // seconds of Game Time since the Game started
+```
+
+- **`after(seconds, callback, options?)`** runs `callback` once, `seconds` of Game Time later (0 or a negative duration: the start of the next step). **`every(seconds, callback, options?)`** runs it every `max(seconds, 1/60)`, first one interval after creation, with no drift. **`tween(options)`** carries `from` to `to` over `seconds`, calling `onUpdate(value)` synchronously on creation and again on every later step, finishing with exactly `to` then `onComplete()`. Easing is `'linear'` (default), `'quadIn'`/`'quadOut'`/`'quadInOut'`, `'cubicIn'`/`'cubicOut'`/`'cubicInOut'`, `'sineInOut'`, or a custom `(t) => number`.
+- All three return a `TimerHandle`: `cancel()`, `active`, `elapsed`, `remaining` (seconds of Game Time). `cancel()` — and owner/scene cancellation — leaves a tween's last applied value in place and never calls `onComplete`.
+- **Step placement.** At the start of every Simulation Step, before the Component Update Schedule, `game.time` advances `now`, runs every due timer (due time, then creation order), then advances every tween that existed before that step (creation order). Work a callback creates is never run or advanced in that same step.
+- **Scope.** A timer or tween is scene-scoped by default: `unloadScene()` and every scene load — including a Game's first — cancel it, running no callback. `{ scope: 'session' }` survives a scene change. `{ owner: entity }` cancels it immediately when that entity is destroyed, whatever its scope; an owner already dead at scheduling time yields an inactive handle. `game.dispose()` cancels everything in both scopes. This is the opposite default from `game.onUpdate`/`game.events` (ADR 0011), which survive a scene change by construction, and the same one `game.audio.play()` uses (ADR 0012) — see ADR 0017 for why timers follow audio's rule rather than the host-subscription one: a timer's callback almost always closes over the scene that scheduled it.
+- **No Promises.** Nothing here returns one, and nothing is async — a `.then` continuation is not step-exact (it runs after the whole synchronous frame), which is exactly what `game.time` exists to avoid. Compose delays with `after`, not `await`.

package/dist/collision-category.d.ts

@@ -0,0 +1,4 @@
+/** Package-internal runtime syntax check for one Collision Layer. */
+export declare function validCollisionLayer(value: unknown): value is string;
+/** Package-internal exact directional interest check. */
+export declare function collisionMaskTargets(mask: unknown, targetLayer: unknown): boolean;

package/dist/collision-category.js

@@ -0,0 +1,11 @@
+const COLLISION_LAYER_PATTERN = /^[a-z][a-z0-9-]*$/;
+/** Package-internal runtime syntax check for one Collision Layer. */
+export function validCollisionLayer(value) {
+    return typeof value === 'string' && COLLISION_LAYER_PATTERN.test(value);
+}
+/** Package-internal exact directional interest check. */
+export function collisionMaskTargets(mask, targetLayer) {
+    if (!validCollisionLayer(targetLayer) || !Array.isArray(mask))
+        return false;
+    return mask.some((entry) => typeof entry === 'string' && (entry === '*' || entry === targetLayer));
+}

package/dist/collision-dispatch.d.ts

@@ -0,0 +1,8 @@
+import type { Game } from './game.js';
+/** Package-internal deterministic work receipt used by focused tests. */
+export interface CollisionDispatchStats {
+    readonly candidatePairs: number;
+    readonly narrowphaseCalls: number;
+}
+/** Game's package-internal trigger dispatch implementation. */
+export declare function dispatchCollisions(game: Game): CollisionDispatchStats;

package/dist/collision-dispatch.js

@@ -0,0 +1,36 @@
+import { collisionBody } from './collision-body.js';
+import { collisionMaskTargets } from './collision-category.js';
+import { collisionOverlap } from './collision-shape.js';
+import { Hitbox } from './components/hitbox.js';
+import { createHitboxBroadphase } from './spatial-broadphase.js';
+/** Game's package-internal trigger dispatch implementation. */
+export function dispatchCollisions(game) {
+    const pairs = createHitboxBroadphase(game).pairs();
+    let narrowphaseCalls = 0;
+    for (const [first, second] of pairs) {
+        const a = first.entity;
+        const b = second.entity;
+        if (!a.alive || !b.alive)
+            continue;
+        if (a.get(Hitbox) !== first.hitbox || b.get(Hitbox) !== second.hitbox)
+            continue;
+        const notifyA = collisionMaskTargets(first.hitbox.collidesWith, second.hitbox.layer);
+        const notifyB = collisionMaskTargets(second.hitbox.collidesWith, first.hitbox.layer);
+        if (!notifyA && !notifyB)
+            continue;
+        narrowphaseCalls += 1;
+        if (!collisionOverlap(collisionBody(first.hitbox), collisionBody(second.hitbox)))
+            continue;
+        if (notifyA) {
+            for (const component of [...a.components])
+                component.onCollide?.(b);
+        }
+        if (!a.alive || !b.alive)
+            continue;
+        if (notifyB) {
+            for (const component of [...b.components])
+                component.onCollide?.(a);
+        }
+    }
+    return { candidatePairs: pairs.length, narrowphaseCalls };
+}

package/dist/component.d.ts

@@ -7,6 +7,8 @@ export interface ParamSpec {
     min?: number;
     max?: number;
     step?: number;
+    /** Specialized editor control for values that are otherwise plain JSON. */
+    kind?: 'string-list';
     /** Allowed values for a string param; rendered as a dropdown. Takes precedence over ref. */
     options?: string[];
     /** Project value this string param names; rendered and validated as a typed reference. */
@@ -65,7 +67,7 @@ export declare abstract class Component {
     onUpdate?(dt: number): void;
     /** Runs after the scene changes between identity and projected rendering. */
     onProjectionChange?(projection: 'isometric' | null): void;
-    /** Runs when this entity's Hitbox overlaps another one's. */
+    /** Runs on overlap when this entity's Hitbox mask names the other's layer. */
     onCollide?(other: Entity): void;
     /** Runs when this entity's DynamicBody physically contacts a Solid. */
     onContact?(contact: SolidContact): void;

package/dist/components/hitbox.d.ts

@@ -1,13 +1,21 @@
 import { Component } from '../component.js';
 import { type CollisionPoint, type CollisionShape } from '../collision-shape.js';
 /**
- * Trigger collider: the Game detects overlaps between Hitboxes and calls
- * onCollide(other) on both entities' components. For static physical
+ * Trigger collider. A pair is tested when either Hitbox's Collision Mask
+ * names the other's Collision Layer; only each interested owner receives
+ * `onCollide`. Spatial Queries ignore categories. For static physical
  * collision see Solid.
  */
 export declare class Hitbox extends Component {
     static componentName: string;
     static params: {
+        layer: {
+            label: string;
+        };
+        collidesWith: {
+            label: string;
+            kind: 'string-list';
+        };
         offsetX: {
             label: string;
         };
@@ -15,6 +23,10 @@ export declare class Hitbox extends Component {
             label: string;
         };
     };
+    /** One exact, case-sensitive `^[a-z][a-z0-9-]*$` membership name. */
+    layer: string;
+    /** Outgoing layer interest; `'*'` means every valid layer and `[]` means none. */
+    collidesWith: string[];
     shape: CollisionShape;
     width: number;
     height: number;

package/dist/components/hitbox.js

@@ -1,16 +1,23 @@
 import { Component } from '../component.js';
 import { resolveCollisionPoints, } from '../collision-shape.js';
 /**
- * Trigger collider: the Game detects overlaps between Hitboxes and calls
- * onCollide(other) on both entities' components. For static physical
+ * Trigger collider. A pair is tested when either Hitbox's Collision Mask
+ * names the other's Collision Layer; only each interested owner receives
+ * `onCollide`. Spatial Queries ignore categories. For static physical
  * collision see Solid.
  */
 export class Hitbox extends Component {
     static componentName = 'Hitbox';
     static params = {
+        layer: { label: 'Collision Layer' },
+        collidesWith: { label: 'Collision Mask', kind: 'string-list' },
         offsetX: { label: 'x offset' },
         offsetY: { label: 'y offset' },
     };
+    /** One exact, case-sensitive `^[a-z][a-z0-9-]*$` membership name. */
+    layer = 'default';
+    /** Outgoing layer interest; `'*'` means every valid layer and `[]` means none. */
+    collidesWith = ['*'];
     shape = 'rectangle';
     width = 1;
     height = 1;

package/dist/entity.js

@@ -55,6 +55,10 @@ export class Entity {
         if (this.destroyed)
             return;
         this.destroyed = true;
+        // Immediately, before any onDestroy hook runs, whatever the scope
+        // (ADR 0017, CA-5) — `alive` is already false by the time any of this
+        // entity's own timers/tweens could observe it.
+        this.game.time.cancelOwnedBy(this);
         for (const c of [...this.components])
             c.onDestroy?.();
         this.components.length = 0;

package/dist/game-time.d.ts

@@ -0,0 +1,189 @@
+/** The closed set of named Penner curves a Tween can ease through. */
+export type EasingName = 'linear' | 'quadIn' | 'quadOut' | 'quadInOut' | 'cubicIn' | 'cubicOut' | 'cubicInOut' | 'sineInOut';
+/** What `after`/`every`/`tween` hand back: see CA-6. */
+export interface TimerHandle {
+    /** Idempotent and silent, even on an already-inactive handle. */
+    cancel(): void;
+    readonly active: boolean;
+    /** Seconds of Game Time, per-kind semantics in CA-6. Frozen once inactive. */
+    readonly elapsed: number;
+    /** Seconds of Game Time until the next due time; 0 once inactive. */
+    readonly remaining: number;
+}
+export interface TimerOptions {
+    /**
+     * Structural, not `instanceof Entity` (spec inference 19) — an object with
+     * a boolean `alive` qualifies, whatever else it is, so behaviors-test stub
+     * entities do too. An owner already dead at scheduling time yields an
+     * inactive handle that never runs, silently (CA-5) — a real Entity's
+     * `destroy()` cancels a live one the same way, whatever its scope.
+     * `alive` is read exactly once, right here at scheduling time; nothing
+     * polls it afterwards. Automatic cancellation of a live handle is driven
+     * entirely by `Entity.destroy()` calling `cancelOwnedBy()`, so an owner
+     * that is not a real `Entity` (never calls `destroy()`) only ever gets
+     * this one dead-at-scheduling check — its handle keeps firing even if
+     * something later flips its `alive` to false by hand.
+     */
+    owner?: {
+        readonly alive: boolean;
+    };
+    /**
+     * `'session'` survives a scene change; anything else — including leaving
+     * it unset — means scene-scoped (ADR 0017), the opposite default from
+     * `game.onUpdate`/`game.events` (ADR 0011). Narrowed to the two literal
+     * values (mirroring `AudioPlayOptions.scope` in `audio/types.ts`) so a
+     * typo is a compile error instead of a silent downgrade to scene scope.
+     */
+    scope?: 'scene' | 'session';
+}
+export interface TweenOptions {
+    from: number;
+    to: number;
+    /** <= 0 (a negative clamped to 0) or below one step: `from` on creation, `to` + onComplete next step. */
+    seconds: number;
+    /** A known name (default `'linear'`) or a custom `(t) => number`. */
+    easing?: EasingName | ((t: number) => number);
+    onUpdate: (value: number) => void;
+    onComplete?: () => void;
+    /**
+     * Structural, not `instanceof Entity` (spec inference 19) — an object with
+     * a boolean `alive` qualifies. `alive` is read once, at scheduling time,
+     * to reject an owner already dead; automatic cancellation afterwards is
+     * driven entirely by `Entity.destroy()` calling `cancelOwnedBy()`, never
+     * by polling `alive` again, so a non-`Entity` owner only ever gets that
+     * one dead-at-scheduling check.
+     */
+    owner?: {
+        readonly alive: boolean;
+    };
+    /** Same as `TimerOptions.scope`: `'session'` survives a scene change, anything else means scene. */
+    scope?: 'scene' | 'session';
+}
+/**
+ * Module-private key for the per-step advance pass. Not exported, so
+ * `time[ADVANCE]()` cannot be spelled outside this file — `advanceGameTime`
+ * (below, exported) is the only reachable entry point from project code.
+ */
+declare const ADVANCE: unique symbol;
+/**
+ * The `game.time` service (CA-1..CA-9, CA-14): `after`, `every` and `tween`
+ * scheduled against Game Time (`now`), advanced only by Simulation Steps —
+ * never the wall clock, never synchronously, never while paused or not
+ * simulating. Constructible standalone, like `Stats`: a `Game` owns one via
+ * `game.time`, and a behaviors-test stub game can carry its own, advanced by
+ * the same engine-internal hook `Game` uses (`advanceGameTime`, exported
+ * below — not part of this class's documented API).
+ */
+export declare class GameTime {
+    private stepCount;
+    private nextId;
+    private timers;
+    private tweens;
+    /**
+     * Set whenever a timer/tween goes inactive since the matching array was
+     * last pruned, whether by firing/completing the per-step advance pass or
+     * by a plain `handle.cancel()` from outside it; consumed (and cleared) by
+     * the next `reclaim()` that actually reassigns that array (CA-3 perf: no
+     * reassignment when nothing died). Invariant: a flag is false only when
+     * its array holds no inactive entries — every path that clears a flag
+     * prunes that array first, and every path that deactivates an entry sets
+     * the matching flag. `reclaim()` relies on this to skip a prune safely.
+     */
+    private timersDirty;
+    private tweensDirty;
+    /** 0 on a new GameTime; `N * SIMULATION_STEP` exactly after N steps — computed, never summed (CA-9). */
+    get now(): number;
+    /** Active timers plus active tweens across both scopes (CA-10). */
+    get pending(): number;
+    /** Smallest positive integer n s.t. n more steps fires/completes something; null when nothing is pending (CA-10). */
+    get nextInSteps(): number | null;
+    /** Shared traversal for `pending`: how many entries in `entries` are active. */
+    private countActive;
+    /** Shared traversal for `nextInSteps`: folds `stepsUntilDue` over every active entry, starting from `min`. */
+    private minStepsUntilDue;
+    /**
+     * Runs `callback` once, `seconds` of Game Time from now (0 or a negative
+     * duration: the start of the next step). Never synchronous (CA-1).
+     */
+    after(seconds: number, callback: () => void, options?: TimerOptions): TimerHandle;
+    /**
+     * Runs `callback` every `max(seconds, SIMULATION_STEP)` of Game Time,
+     * first one interval after creation, with no drift: each due time is
+     * `start + n * interval`, computed directly rather than by repeated
+     * addition (CA-2).
+     */
+    every(seconds: number, callback: () => void, options?: TimerOptions): TimerHandle;
+    /**
+     * Carries a single number from `from` to `to` over `seconds` of Game
+     * Time, reporting it through `onUpdate` on every step including creation
+     * (synchronous, before this returns — CA-7). Owner already dead, or any
+     * invalid input, skips even that first call.
+     */
+    tween(options: TweenOptions): TimerHandle;
+    /**
+     * Internal: the start-of-step pass (CA-3) — advances `now`, then runs
+     * every due timer (due time, then creation order), then advances every
+     * tween that existed before this pass (creation order). Reachable only as
+     * `time[ADVANCE]()`, and `ADVANCE` is not exported, so `advanceGameTime()`
+     * (below, exported) is genuinely the only way in from project code. With
+     * nothing scheduled (the common case once a scene settles) this does no
+     * allocation beyond the step count itself; with timers but no tweens, the
+     * tween snapshot and `advanceTweens()` are skipped too.
+     */
+    [ADVANCE](): void;
+    /**
+     * Engine-internal by convention, like `Game.removeEntity`: a public
+     * method, not access-controlled, that `Game.unloadScene()` and every
+     * scene load are expected to call, including the first (CA-4).
+     */
+    cancelSceneScoped(): void;
+    /**
+     * Engine-internal by convention, like `Game.removeEntity`: a public
+     * method, not access-controlled, that `Entity.destroy()` (CA-5) is
+     * expected to be the only caller of. Nothing re-reads `owner.alive` on
+     * later steps; a non-`Entity` owner whose `alive` flips without ever
+     * going through a real `destroy()` call never reaches here, so its
+     * timers/tweens keep running (see `TimerOptions.owner`).
+     */
+    cancelOwnedBy(owner: {
+        readonly alive: boolean;
+    }): void;
+    /**
+     * Engine-internal by convention, like `Game.removeEntity`: a public
+     * method, not access-controlled, that `Game.dispose()` is expected to
+     * call (CA-4).
+     */
+    cancelAll(): void;
+    /**
+     * Prunes each array only when its dirty flag is set, then clears that
+     * flag — safe because of the invariant documented on `timersDirty`
+     * /`tweensDirty`: a false flag means the array already holds no inactive
+     * entries, so skipping the filter changes no observable behavior. Called
+     * both at the tail of the per-step advance pass and by
+     * `cancelSceneScoped`/`cancelOwnedBy`/`cancelAll`, which are also
+     * reachable with `simulate === false` (e.g. the editor's edit mode
+     * calling `loadScene` on every edit), when no step ever runs to reclaim
+     * otherwise.
+     */
+    private reclaim;
+    private runDueTimers;
+    private advanceTweens;
+    private deactivate;
+    /** Smallest n >= 1 such that `n` more steps reaches `dueTime`, guarding against float noise near a step boundary. */
+    private stepsUntilDue;
+    private invalid;
+    private handleFor;
+}
+/**
+ * Engine-internal: advances `time` by exactly one Simulation Step (CA-3).
+ * `Game.simulateStep()` calls this as its very first statement, so nothing
+ * advances with `simulate === false`, on a zero-step frame, or while the
+ * Runtime Bridge is paused and not stepping. A standalone `GameTime` — a
+ * behaviors-test stub game, or this package's own game-time.test.ts (CA-14)
+ * — must call this the same way. This is the only way in: the pass itself
+ * lives behind the module-private `ADVANCE` symbol key, unreachable from
+ * outside this file, so project code has no `advanceStep()`-shaped method
+ * to call directly and desynchronize Game Time with.
+ */
+export declare function advanceGameTime(time: GameTime): void;
+export {};