@waica/engine 0.3.0

package/dist/solid-axis.js

@@ -0,0 +1,77 @@
+import { collisionBounds, collisionOverlap } from './collision-shape.js';
+import { Solid } from './components/solid.js';
+const CONTACT_TOLERANCE = 1e-7;
+function bodyFor(solid) {
+    return {
+        x: solid.entity.position.x + solid.offsetX,
+        y: solid.entity.position.y + solid.offsetY,
+        width: solid.width,
+        height: solid.height,
+        shape: solid.shape,
+        points: solid.points,
+    };
+}
+/**
+ * Resolves one axis against scene Solids. Large displacements are split into
+ * body-sized steps so a thin wall cannot sit entirely between two samples.
+ * Returns whether a new contact blocked the move.
+ */
+export function resolveSolidAxis({ entity, axis, previous, body, onContact, }) {
+    const position = entity.position;
+    const target = position[axis];
+    const solids = entity.game.entities
+        .filter((other) => other !== entity)
+        .map((other) => other.get(Solid))
+        .filter((solid) => solid !== undefined);
+    position[axis] = previous;
+    // Preserve the established spawn-inside-wall bail: pre-existing overlaps
+    // are ignored for this move rather than becoming arbitrary push-out rules.
+    const ignored = new Set(solids.filter((solid) => collisionOverlap(body(), bodyFor(solid))));
+    const bounds = collisionBounds(body());
+    const extent = axis === 'x' ? bounds.right - bounds.left : bounds.top - bounds.bottom;
+    const maxStep = Math.max(extent / 2, 0.05);
+    const displacement = target - previous;
+    const steps = Math.max(1, Math.ceil(Math.abs(displacement) / maxStep));
+    let free = previous;
+    for (let step = 1; step <= steps; step++) {
+        const candidate = previous + displacement * (step / steps);
+        position[axis] = candidate;
+        const blockers = solids.filter((solid) => !ignored.has(solid) && collisionOverlap(body(), bodyFor(solid)));
+        if (blockers.length === 0) {
+            free = candidate;
+            continue;
+        }
+        // More than one Solid can occupy a sample. Resolve against each from the
+        // same known-free point and keep the nearest contact along this move.
+        let contact = candidate;
+        let contactDistance = Infinity;
+        let contacts = [];
+        for (const solid of blockers) {
+            let open = free;
+            let blocked = candidate;
+            for (let iteration = 0; iteration < 14; iteration++) {
+                const middle = (open + blocked) / 2;
+                position[axis] = middle;
+                if (collisionOverlap(body(), bodyFor(solid)))
+                    blocked = middle;
+                else
+                    open = middle;
+            }
+            const distance = Math.abs(open - free);
+            if (distance < contactDistance - CONTACT_TOLERANCE) {
+                contact = open;
+                contactDistance = distance;
+                contacts = [solid];
+            }
+            else if (Math.abs(distance - contactDistance) <= CONTACT_TOLERANCE) {
+                contacts.push(solid);
+            }
+        }
+        position[axis] = contact;
+        for (const solid of contacts)
+            onContact?.(solid);
+        return true;
+    }
+    position[axis] = target;
+    return false;
+}

package/dist/state/hooks.d.ts

@@ -0,0 +1,90 @@
+import type { Entity } from '../entity.js';
+import type { Game } from '../game.js';
+import type { StateJson, StateMachine } from './state-machine.js';
+/** What state code receives: the entity, the game, and the machine itself. */
+export interface StateContext {
+    entity: Entity;
+    game: Game;
+    fsm: StateMachine;
+}
+/** Code for one state. Every hook is optional — a state can be pure data. */
+export interface StateHooks {
+    onEnter?(ctx: StateContext): void;
+    onUpdate?(ctx: StateContext, dt: number): void;
+    onCollide?(ctx: StateContext, other: Entity): void;
+    onExit?(ctx: StateContext): void;
+}
+/**
+ * A named bundle of state code. Two entries are special: '*' is the
+ * always-hook — it runs every frame no matter which state is active
+ * (per-frame bookkeeping like motor timers lives there) — and 'default'
+ * is the fallback — a state that doesn't define a phase inherits it, so
+ * a custom state keeps the stock body update unless it overrides it.
+ */
+export type StateLogic = Record<string, StateHooks>;
+/**
+ * Registers state code under a logic-set name. A role's name is also its
+ * logic-set name, so this is how a role's code is extended: registering
+ * again with the same name merges per state.
+ */
+export declare function defineStates(name: string, states: StateLogic): void;
+/** A role's starter state graph — what new characters of the role begin with. */
+export interface RoleGraph {
+    initial: string;
+    states: Record<string, StateJson>;
+}
+/**
+ * A character role: the whole behavior package behind one answer to
+ * "what is this character?". The editor uses the description to let the
+ * role explain itself, and the driver + graph to install the package.
+ */
+export interface RoleDefinition {
+    /** One plain-language line: what this role is and does. */
+    description: string;
+    /**
+     * Component the role's states move (they early-return without it).
+     * Several roles may share one driver — the contract is N roles : 1 driver.
+     */
+    driver?: string;
+    /** Starter graph installed when a character adopts this role. */
+    graph?: RoleGraph;
+    /** The role's state code, registered as the role's logic set. */
+    states?: StateLogic;
+    /**
+     * Signals the role's code emits (name → plain-language description).
+     * The editor lists them wherever a transition asks for a signal, so
+     * users pick from a vocabulary instead of typing names blind.
+     */
+    signals?: Record<string, string>;
+}
+/** All state-registry data an archetype installs before project extensions. */
+export interface ArchetypeBundle {
+    roles: Readonly<Record<string, RoleDefinition>>;
+    /** Extra named logic sets that are not themselves roles. */
+    logicSets?: Readonly<Record<string, StateLogic>>;
+}
+/** Clears role definitions and every named logic set. */
+export declare function resetRegistries(): void;
+/**
+ * Replaces the active registry contents with one archetype's complete bundle.
+ * Project defineRole/defineStates calls may extend this clean baseline after it
+ * is installed.
+ */
+export declare function installArchetype(bundle: ArchetypeBundle): void;
+/**
+ * Registers a character role. Prefabs adopt it via the StateMachine's
+ * `role` prop; the role's name doubles as its logic-set name, so
+ * defineStates(name, {...}) extends its code. Registering an existing
+ * role again merges its definition (and its states).
+ */
+export declare function defineRole(name: string, def: RoleDefinition): void;
+/** The registered role, if any — driver, graph and description included. */
+export declare function roleDefinition(name: string): RoleDefinition | undefined;
+/** Every registered role name — for the editor's Role pickers. */
+export declare function registeredRoles(): string[];
+/** The registered code for a set, if any. */
+export declare function logicSet(name: string): StateLogic | undefined;
+/** Every registered set name — for error messages and editor pickers. */
+export declare function registeredLogicSets(): string[];
+/** Closest registered set to a (likely typo'd) name, for the not-found error. */
+export declare function closestLogicSet(name: string): string | undefined;

package/dist/state/hooks.js

@@ -0,0 +1,81 @@
+const sets = new Map();
+/**
+ * Registers state code under a logic-set name. A role's name is also its
+ * logic-set name, so this is how a role's code is extended: registering
+ * again with the same name merges per state.
+ */
+export function defineStates(name, states) {
+    sets.set(name, { ...sets.get(name), ...states });
+}
+const roles = new Map();
+/** Clears role definitions and every named logic set. */
+export function resetRegistries() {
+    roles.clear();
+    sets.clear();
+}
+/**
+ * Replaces the active registry contents with one archetype's complete bundle.
+ * Project defineRole/defineStates calls may extend this clean baseline after it
+ * is installed.
+ */
+export function installArchetype(bundle) {
+    resetRegistries();
+    for (const [name, def] of Object.entries(bundle.roles))
+        defineRole(name, def);
+    for (const [name, states] of Object.entries(bundle.logicSets ?? {})) {
+        defineStates(name, states);
+    }
+}
+/**
+ * Registers a character role. Prefabs adopt it via the StateMachine's
+ * `role` prop; the role's name doubles as its logic-set name, so
+ * defineStates(name, {...}) extends its code. Registering an existing
+ * role again merges its definition (and its states).
+ */
+export function defineRole(name, def) {
+    roles.set(name, { ...roles.get(name), ...def });
+    if (def.states)
+        defineStates(name, def.states);
+}
+/** The registered role, if any — driver, graph and description included. */
+export function roleDefinition(name) {
+    return roles.get(name);
+}
+/** Every registered role name — for the editor's Role pickers. */
+export function registeredRoles() {
+    return [...roles.keys()];
+}
+/** The registered code for a set, if any. */
+export function logicSet(name) {
+    return sets.get(name);
+}
+/** Every registered set name — for error messages and editor pickers. */
+export function registeredLogicSets() {
+    return [...sets.keys()];
+}
+/** Closest registered set to a (likely typo'd) name, for the not-found error. */
+export function closestLogicSet(name) {
+    let best;
+    let bestDistance = Infinity;
+    for (const candidate of sets.keys()) {
+        const distance = editDistance(name, candidate);
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = candidate;
+        }
+    }
+    return bestDistance <= Math.max(2, Math.floor(name.length / 3)) ? best : undefined;
+}
+function editDistance(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let diagonal = row[0];
+        row[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const previous = row[j];
+            row[j] = Math.min(previous + 1, row[j - 1] + 1, diagonal + (a[i - 1] === b[j - 1] ? 0 : 1));
+            diagonal = previous;
+        }
+    }
+    return row[b.length];
+}

package/dist/state/state-machine.d.ts

@@ -0,0 +1,83 @@
+import { Component } from '../component.js';
+import type { Entity } from '../entity.js';
+import { type StateHooks } from './hooks.js';
+/** One outgoing edge: when `on` fires, the machine moves to `to`. */
+export interface StateTransitionJson {
+    /** Trigger: 'input:<action>' | 'timer:<seconds>' | 'signal:<name>'. */
+    on: string;
+    to: string;
+}
+/**
+ * One state, as prefab data. Its code (if any) is looked up by state name
+ * in the machine's logic set. The '*' state key holds from-any-state
+ * transitions instead of a real state.
+ */
+export interface StateJson {
+    /** Clip to play on enter; defaults to the state's own name. */
+    clip?: string;
+    transitions?: StateTransitionJson[];
+}
+/** What a trigger string is checked against. */
+export interface TriggerEnv {
+    /** An unconsumed press of the action this frame (see Input.consume). */
+    justPressed(action: string): boolean;
+    /** Seconds spent in the current state. */
+    elapsed: number;
+    signals: ReadonlySet<string>;
+}
+/** Whether one trigger fires. Unknown or malformed triggers never fire. */
+export declare function evaluateTrigger(on: string, env: TriggerEnv): boolean;
+/** The first firing transition: the state's own edges, then '*''s. */
+export declare function nextTransition(states: Record<string, StateJson>, current: string, env: TriggerEnv): StateTransitionJson | undefined;
+/**
+ * The hooks that actually run for one phase of a state: the state's own
+ * (logic set + instance), or — when none of them define the phase — the
+ * set's 'default' entry. A custom state keeps the role's stock body
+ * update unless it brings its own.
+ */
+export declare function phaseHooks(hooks: StateHooks[], fallback: StateHooks | undefined, phase: keyof StateHooks): StateHooks[];
+/**
+ * Finite state machine: the single owner of a character's per-frame
+ * logic — only the active state's code moves the body, so behaviors
+ * never fight over velocity. States and transitions are prefab data;
+ * state code lives in the role's logic set (defineRole / defineStates)
+ * picked by `role`. Entering a state plays the sibling AnimatedSprite
+ * clip of the same name (or the state's `clip` override); a missing
+ * clip warns and keeps the previous one.
+ */
+export declare class StateMachine extends Component {
+    static componentName: string;
+    static displayName: string;
+    static params: {
+        role: {
+            label: string;
+        };
+    };
+    /** The character's role — names the logic set providing its state code. */
+    role: string;
+    /** Starting state; defaults to the first declared state. */
+    initial: string;
+    states: Record<string, StateJson>;
+    /** Active state name. */
+    current: string;
+    /** Seconds spent in the active state. */
+    elapsed: number;
+    private readonly instanceHooks;
+    private readonly signals;
+    private readonly warnedClips;
+    onReady(): void;
+    /** Adds instance-level hooks on top of the logic set — the escape hatch. */
+    on(state: string, hooks: StateHooks): void;
+    /** Queues a signal for 'signal:<name>' transitions, consumed this frame or the next. */
+    signal(name: string): void;
+    /** Jumps straight to a state, ignoring transitions. */
+    goto(state: string): void;
+    onUpdate(dt: number): void;
+    onCollide(other: Entity): void;
+    private env;
+    private hooksFor;
+    private run;
+    private runCollision;
+    private enter;
+    private playClip;
+}

package/dist/state/state-machine.js

@@ -0,0 +1,173 @@
+import { Component } from '../component.js';
+import { AnimatedSprite } from '../components/animated-sprite.js';
+import { closestLogicSet, logicSet, registeredLogicSets, } from './hooks.js';
+/** Whether one trigger fires. Unknown or malformed triggers never fire. */
+export function evaluateTrigger(on, env) {
+    const sep = on.indexOf(':');
+    if (sep <= 0)
+        return false;
+    const kind = on.slice(0, sep);
+    const arg = on.slice(sep + 1);
+    if (kind === 'input')
+        return env.justPressed(arg);
+    if (kind === 'timer')
+        return env.elapsed >= Number(arg);
+    if (kind === 'signal')
+        return env.signals.has(arg);
+    return false;
+}
+/** The first firing transition: the state's own edges, then '*''s. */
+export function nextTransition(states, current, env) {
+    const edges = [...(states[current]?.transitions ?? []), ...(states['*']?.transitions ?? [])];
+    return edges.find((t) => evaluateTrigger(t.on, env));
+}
+/**
+ * The hooks that actually run for one phase of a state: the state's own
+ * (logic set + instance), or — when none of them define the phase — the
+ * set's 'default' entry. A custom state keeps the role's stock body
+ * update unless it brings its own.
+ */
+export function phaseHooks(hooks, fallback, phase) {
+    if (hooks.some((h) => h[phase]))
+        return hooks;
+    return fallback?.[phase] ? [fallback] : hooks;
+}
+/**
+ * Finite state machine: the single owner of a character's per-frame
+ * logic — only the active state's code moves the body, so behaviors
+ * never fight over velocity. States and transitions are prefab data;
+ * state code lives in the role's logic set (defineRole / defineStates)
+ * picked by `role`. Entering a state plays the sibling AnimatedSprite
+ * clip of the same name (or the state's `clip` override); a missing
+ * clip warns and keeps the previous one.
+ */
+export class StateMachine extends Component {
+    static componentName = 'StateMachine';
+    static displayName = 'State Machine';
+    static params = {
+        role: { label: 'Role' },
+    };
+    /** The character's role — names the logic set providing its state code. */
+    role = '';
+    /** Starting state; defaults to the first declared state. */
+    initial = '';
+    states = {};
+    /** Active state name. */
+    current = '';
+    /** Seconds spent in the active state. */
+    elapsed = 0;
+    instanceHooks = new Map();
+    signals = new Set();
+    warnedClips = new Set();
+    onReady() {
+        if (this.role && !logicSet(this.role)) {
+            const sets = registeredLogicSets();
+            const hint = closestLogicSet(this.role);
+            console.error(`[waica] "${this.entity.name}": role "${this.role}" has no registered state code. ` +
+                `Known: ${sets.length ? sets.join(', ') : '(none)'}.` +
+                (hint ? ` Did you mean "${hint}"?` : ''));
+        }
+        const start = this.initial || Object.keys(this.states).find((name) => name !== '*');
+        if (start)
+            this.enter(start);
+    }
+    /** Adds instance-level hooks on top of the logic set — the escape hatch. */
+    on(state, hooks) {
+        const list = this.instanceHooks.get(state) ?? [];
+        list.push(hooks);
+        this.instanceHooks.set(state, list);
+    }
+    /** Queues a signal for 'signal:<name>' transitions, consumed this frame or the next. */
+    signal(name) {
+        this.signals.add(name);
+    }
+    /** Jumps straight to a state, ignoring transitions. */
+    goto(state) {
+        if (state !== this.current)
+            this.enter(state);
+    }
+    onUpdate(dt) {
+        if (!this.current)
+            return;
+        this.run('*', 'onUpdate', dt);
+        this.run(this.current, 'onUpdate', dt);
+        this.elapsed += dt;
+        // Chained transitions settle within the frame (e.g. land → idle → run),
+        // capped so a degenerate cyclic graph can't hang the loop.
+        for (let hops = 0; hops < 8; hops++) {
+            const edge = nextTransition(this.states, this.current, this.env());
+            if (!edge)
+                break;
+            // A transition fired by a key press spends it: one press, one
+            // transition — it can't fire again from the state just entered.
+            if (edge.on.startsWith('input:'))
+                this.game.input.consume(edge.on.slice('input:'.length));
+            this.enter(edge.to);
+        }
+        this.signals.clear();
+    }
+    onCollide(other) {
+        // The state that was active when the contact happened owns it: a
+        // transition fired inside the always-hook must not hand the collision
+        // to the state it just entered.
+        const state = this.current;
+        if (!state)
+            return;
+        this.runCollision('*', other);
+        // Either side can be destroyed by a hook. Game.dispatchCollisions guards
+        // the same way between the two sides of one contact.
+        if (!this.entity.alive || !other.alive)
+            return;
+        this.runCollision(state, other);
+    }
+    env() {
+        return {
+            justPressed: (action) => this.game.input.justPressed(action) && !this.game.input.consumed(action),
+            elapsed: this.elapsed,
+            signals: this.signals,
+        };
+    }
+    hooksFor(state) {
+        const fromSet = this.role ? logicSet(this.role)?.[state] : undefined;
+        return [...(fromSet ? [fromSet] : []), ...(this.instanceHooks.get(state) ?? [])];
+    }
+    run(state, phase, dt = 0) {
+        const ctx = { entity: this.entity, game: this.game, fsm: this };
+        const fallback = state !== '*' && this.role ? logicSet(this.role)?.['default'] : undefined;
+        for (const hooks of phaseHooks(this.hooksFor(state), fallback, phase)) {
+            if (phase === 'onUpdate')
+                hooks.onUpdate?.(ctx, dt);
+            else
+                hooks[phase]?.(ctx);
+        }
+    }
+    runCollision(state, other) {
+        const ctx = { entity: this.entity, game: this.game, fsm: this };
+        const fallback = state !== '*' && this.role ? logicSet(this.role)?.['default'] : undefined;
+        for (const hooks of phaseHooks(this.hooksFor(state), fallback, 'onCollide')) {
+            hooks.onCollide?.(ctx, other);
+        }
+    }
+    enter(state) {
+        if (this.current)
+            this.run(this.current, 'onExit');
+        this.current = state;
+        this.elapsed = 0;
+        this.playClip(state);
+        this.run(state, 'onEnter');
+    }
+    playClip(state) {
+        const sprite = this.entity.get(AnimatedSprite);
+        if (!sprite)
+            return;
+        const clip = this.states[state]?.clip ?? state;
+        if (sprite.clips[clip]) {
+            sprite.play(clip);
+        }
+        else if (!this.warnedClips.has(state)) {
+            this.warnedClips.add(state);
+            console.warn(`[waica] "${this.entity.name}": no clip "${clip}" for state "${state}" — ` +
+                `keeping "${sprite.current ?? 'none'}"`);
+        }
+    }
+}

package/dist/stats.d.ts

@@ -0,0 +1,27 @@
+/** A stat's value: points/lives are numbers, flags are booleans, labels strings. */
+export type StatValue = number | boolean | string;
+/**
+ * Named game state (points, lives, door-open flags…) declared in the
+ * project's src/stats.json. Every new Game starts from the declared initial
+ * values; behaviours read and change them and can subscribe to changes.
+ */
+export declare class Stats {
+    private readonly initial;
+    private values;
+    private readonly emitter;
+    constructor(initial?: Record<string, StatValue>);
+    /** Current value; undeclared stats read as undefined. */
+    get(name: string): StatValue | undefined;
+    /** Numeric read: non-number and undeclared stats count as 0. */
+    count(name: string): number;
+    /** Sets a stat (declared or not) and notifies subscribers on real changes. */
+    set(name: string, value: StatValue): void;
+    /** Adds delta (default 1) to a numeric stat; undeclared stats start at 0. */
+    add(name: string, delta?: number): number;
+    /** Back to the declared initial values, notifying every stat that changed. */
+    reset(): void;
+    /** Fires when the named stat changes. Returns the unsubscribe. */
+    onChange(name: string, handler: (value: StatValue | undefined) => void): () => void;
+    /** Every stat with its current value (declared and runtime-created). */
+    entries(): Array<[string, StatValue]>;
+}

package/dist/stats.js

@@ -0,0 +1,54 @@
+import { Emitter } from './events.js';
+/**
+ * Named game state (points, lives, door-open flags…) declared in the
+ * project's src/stats.json. Every new Game starts from the declared initial
+ * values; behaviours read and change them and can subscribe to changes.
+ */
+export class Stats {
+    initial;
+    values;
+    emitter = new Emitter();
+    constructor(initial = {}) {
+        this.initial = { ...initial };
+        this.values = { ...initial };
+    }
+    /** Current value; undeclared stats read as undefined. */
+    get(name) {
+        return this.values[name];
+    }
+    /** Numeric read: non-number and undeclared stats count as 0. */
+    count(name) {
+        const value = this.values[name];
+        return typeof value === 'number' ? value : 0;
+    }
+    /** Sets a stat (declared or not) and notifies subscribers on real changes. */
+    set(name, value) {
+        if (this.values[name] === value)
+            return;
+        this.values[name] = value;
+        this.emitter.emit(name, value);
+    }
+    /** Adds delta (default 1) to a numeric stat; undeclared stats start at 0. */
+    add(name, delta = 1) {
+        const next = this.count(name) + delta;
+        this.set(name, next);
+        return next;
+    }
+    /** Back to the declared initial values, notifying every stat that changed. */
+    reset() {
+        const previous = this.values;
+        this.values = { ...this.initial };
+        for (const name of new Set([...Object.keys(previous), ...Object.keys(this.values)])) {
+            if (previous[name] !== this.values[name])
+                this.emitter.emit(name, this.values[name]);
+        }
+    }
+    /** Fires when the named stat changes. Returns the unsubscribe. */
+    onChange(name, handler) {
+        return this.emitter.on(name, handler);
+    }
+    /** Every stat with its current value (declared and runtime-created). */
+    entries() {
+        return Object.entries(this.values);
+    }
+}

package/dist/ui.d.ts

@@ -0,0 +1,47 @@
+import type { Stats } from './stats.js';
+/**
+ * The HTML UI layer. Each piece is a self-contained HTML fragment
+ * (markup + <style>) that only DRAWS: it declares which stats it shows
+ * with {{stat}} placeholders and positions itself with its own CSS.
+ * Behaviour always comes from outside — code toggles pieces with
+ * show/hide and wires interactivity through element().
+ *
+ * Pieces mount inside a transparent overlay that covers the game canvas
+ * (each in its own shadow root, so styles never leak between pieces or
+ * into the hosting page). The whole overlay hides while the game is not
+ * simulating (pause / editor edit mode).
+ */
+export declare class GameUi {
+    private readonly stats;
+    /** Resolved lazily: the canvas may not be in the DOM at construction. */
+    private readonly host;
+    private readonly sources;
+    private readonly pieces;
+    private overlay?;
+    private active;
+    constructor(stats: Stats, 
+    /** Resolved lazily: the canvas may not be in the DOM at construction. */
+    host: () => HTMLElement);
+    /** Registers a piece's HTML source. Re-defining an unmounted name wins. */
+    define(name: string, html: string): void;
+    defineAll(pieces: Record<string, string>): void;
+    /** Piece names available to show (defined via the registry or define()). */
+    names(): string[];
+    show(name: string): void;
+    hide(name: string): void;
+    toggle(name: string): void;
+    isVisible(name: string): boolean;
+    /**
+     * The piece's DOM root — the escape hatch that keeps pieces logic-free:
+     * behaviour is wired from code (element(...).querySelector + listeners).
+     * Mounts the piece hidden if it wasn't mounted yet.
+     */
+    element(name: string): HTMLElement | null;
+    /** Called by the game loop: the overlay only draws while simulating. */
+    setActive(active: boolean): void;
+    /** Unmounts every piece and removes the overlay (Game.dispose). */
+    dispose(): void;
+    private mount;
+    private mountOverlay;
+    private sync;
+}