@waica/cli 0.3.0

package/dist/mcp/node_modules/@waica/engine/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/mcp/node_modules/@waica/engine/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/mcp/node_modules/@waica/engine/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/mcp/node_modules/@waica/engine/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;
+}

package/dist/mcp/node_modules/@waica/engine/dist/ui.js

@@ -0,0 +1,175 @@
+/**
+ * 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 class GameUi {
+    stats;
+    host;
+    sources = new Map();
+    pieces = new Map();
+    overlay;
+    active = true;
+    constructor(stats, 
+    /** Resolved lazily: the canvas may not be in the DOM at construction. */
+    host) {
+        this.stats = stats;
+        this.host = host;
+    }
+    /** Registers a piece's HTML source. Re-defining an unmounted name wins. */
+    define(name, html) {
+        this.sources.set(name, html);
+    }
+    defineAll(pieces) {
+        for (const [name, html] of Object.entries(pieces))
+            this.define(name, html);
+    }
+    /** Piece names available to show (defined via the registry or define()). */
+    names() {
+        return [...this.sources.keys()];
+    }
+    show(name) {
+        const piece = this.mount(name);
+        if (piece)
+            piece.visible = true;
+        this.sync();
+    }
+    hide(name) {
+        const piece = this.pieces.get(name);
+        if (piece)
+            piece.visible = false;
+        this.sync();
+    }
+    toggle(name) {
+        if (this.isVisible(name))
+            this.hide(name);
+        else
+            this.show(name);
+    }
+    isVisible(name) {
+        return this.pieces.get(name)?.visible ?? false;
+    }
+    /**
+     * 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) {
+        return this.mount(name)?.root ?? null;
+    }
+    /** Called by the game loop: the overlay only draws while simulating. */
+    setActive(active) {
+        if (this.active === active)
+            return;
+        this.active = active;
+        this.sync();
+    }
+    /** Unmounts every piece and removes the overlay (Game.dispose). */
+    dispose() {
+        for (const piece of this.pieces.values()) {
+            for (const off of piece.unsubs)
+                off();
+        }
+        this.pieces.clear();
+        this.overlay?.remove();
+        this.overlay = undefined;
+    }
+    mount(name) {
+        const existing = this.pieces.get(name);
+        if (existing)
+            return existing;
+        const html = this.sources.get(name);
+        if (html == null) {
+            console.warn(`[waica] unknown ui piece: "${name}"`);
+            return null;
+        }
+        // Same geometry as the overlay, so the piece's own CSS positions
+        // against the full canvas. pointer-events stays off unless the piece's
+        // CSS opts in (e.g. a button with pointer-events:auto).
+        const shell = document.createElement('div');
+        shell.style.cssText = 'position:absolute;inset:0;pointer-events:none';
+        const shadow = shell.attachShadow({ mode: 'open' });
+        const root = document.createElement('div');
+        root.style.display = 'contents';
+        root.innerHTML = html;
+        shadow.append(root);
+        const piece = { shell, root, visible: false, unsubs: bindStats(root, this.stats) };
+        this.mountOverlay().append(shell);
+        this.pieces.set(name, piece);
+        return piece;
+    }
+    mountOverlay() {
+        if (this.overlay)
+            return this.overlay;
+        const overlay = document.createElement('div');
+        overlay.style.cssText = 'position:absolute;inset:0;z-index:9000;pointer-events:none';
+        const host = this.host();
+        if (getComputedStyle(host).position === 'static')
+            host.style.position = 'relative';
+        host.append(overlay);
+        this.overlay = overlay;
+        this.sync();
+        return overlay;
+    }
+    sync() {
+        if (this.overlay)
+            this.overlay.style.display = this.active ? '' : 'none';
+        for (const piece of this.pieces.values()) {
+            piece.shell.style.display = piece.visible ? '' : 'none';
+        }
+    }
+}
+const BINDING = /\{\{\s*([\w-]+)\s*\}\}/g;
+function renderStat(value) {
+    if (value === undefined)
+        return '';
+    if (typeof value === 'boolean')
+        return value ? '✓' : '✕';
+    return String(value);
+}
+/**
+ * Replaces {{stat}} placeholders in the fragment's text with reactive text
+ * nodes kept in sync with the stats. Text-only by design: the binding
+ * language has no expressions — presentation, never logic.
+ */
+function bindStats(root, stats) {
+    const unsubs = [];
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+    const targets = [];
+    for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+        // Braces inside <style>/<script> are CSS/code, not bindings.
+        if (node.parentElement?.closest('style, script'))
+            continue;
+        if ((node.nodeValue ?? '').includes('{{'))
+            targets.push(node);
+    }
+    for (const text of targets) {
+        const source = text.nodeValue ?? '';
+        const parts = [];
+        let last = 0;
+        for (const match of source.matchAll(BINDING)) {
+            const stat = match[1];
+            if (stat === undefined)
+                continue;
+            if (match.index > last)
+                parts.push(document.createTextNode(source.slice(last, match.index)));
+            const bound = document.createTextNode(renderStat(stats.get(stat)));
+            unsubs.push(stats.onChange(stat, (value) => (bound.nodeValue = renderStat(value))));
+            parts.push(bound);
+            last = match.index + match[0].length;
+        }
+        if (parts.length === 0)
+            continue;
+        if (last < source.length)
+            parts.push(document.createTextNode(source.slice(last)));
+        text.replaceWith(...parts);
+    }
+    return unsubs;
+}

package/dist/mcp/node_modules/@waica/engine/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@waica/engine",
+  "version": "0.3.0",
+  "description": "Waica game engine core — archetype-driven, web-first, 2D & 3D",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chichex/waica",
+    "directory": "packages/engine"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@types/three": "^0.185.1",
+    "three": "^0.185.1"
+  }
+}