@waica/engine 0.4.1 → 0.5.0

package/dist/authoring-defaults.d.ts

@@ -0,0 +1,11 @@
+import type { ComponentClass } from './component.js';
+/**
+ * The public authoring surface of a component class: own enumerable fields
+ * plus setter-backed accessors (walking the whole prototype chain, so a
+ * getter/setter pair inherited from a base class counts), read through the
+ * getter so the value is the public one. Excludes `_`-prefixed keys, the
+ * base Component wiring (`entity`, `game`), anything the class (or an
+ * ancestor) declares `transient`, and values that are `undefined` or not
+ * JSON-serializable (`Map`, `Set`, functions, class instances).
+ */
+export declare function authoringDefaults(Class: ComponentClass, onError?: (error: unknown) => void): Record<string, unknown>;

package/dist/authoring-defaults.js

@@ -0,0 +1,51 @@
+const EXCLUDED_KEYS = new Set(['entity', 'game']);
+function isSerializable(value) {
+    if (value === null)
+        return true;
+    const kind = typeof value;
+    if (kind === 'string' || kind === 'number' || kind === 'boolean')
+        return true;
+    if (kind !== 'object')
+        return false;
+    if (Array.isArray(value))
+        return true;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * The public authoring surface of a component class: own enumerable fields
+ * plus setter-backed accessors (walking the whole prototype chain, so a
+ * getter/setter pair inherited from a base class counts), read through the
+ * getter so the value is the public one. Excludes `_`-prefixed keys, the
+ * base Component wiring (`entity`, `game`), anything the class (or an
+ * ancestor) declares `transient`, and values that are `undefined` or not
+ * JSON-serializable (`Map`, `Set`, functions, class instances).
+ */
+export function authoringDefaults(Class, onError) {
+    let instance;
+    try {
+        instance = new Class();
+    }
+    catch (error) {
+        onError?.(error);
+        return {};
+    }
+    const transient = new Set(Class.transient ?? []);
+    const keys = new Set(Object.keys(instance));
+    for (let proto = Object.getPrototypeOf(instance); proto && proto !== Object.prototype; proto = Object.getPrototypeOf(proto)) {
+        for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(proto))) {
+            if (descriptor.set)
+                keys.add(key);
+        }
+    }
+    const result = {};
+    for (const key of keys) {
+        if (EXCLUDED_KEYS.has(key) || key.startsWith('_') || transient.has(key))
+            continue;
+        const value = instance[key];
+        if (value === undefined || !isSerializable(value))
+            continue;
+        result[key] = value;
+    }
+    return result;
+}

package/dist/component.d.ts

@@ -7,8 +7,10 @@ export interface ParamSpec {
     min?: number;
     max?: number;
     step?: number;
-    /** Allowed values for a string param; rendered as a dropdown. */
+    /** 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. */
+    ref?: 'prefab' | 'stat' | 'action' | 'clip';
 }
 export interface ComponentClass<T extends Component = Component> {
     new (): T;
@@ -21,6 +23,12 @@ export interface ComponentClass<T extends Component = Component> {
     displayName?: string;
     /** Which properties the inspector exposes, with their ranges. */
     params?: Record<string, ParamSpec>;
+    /**
+     * Instance fields holding runtime state rather than authorable defaults.
+     * Excluded from authoringDefaults(); a subclass that does not redeclare
+     * this inherits its base's list.
+     */
+    transient?: readonly string[];
 }
 /** Cardinal unit normal pointing away from the contacted Solid surface. */
 export interface ContactNormal {
@@ -43,6 +51,7 @@ export declare abstract class Component {
     static componentName: string;
     static displayName?: string;
     static params?: Record<string, ParamSpec>;
+    static transient?: readonly string[];
     entity: Entity;
     game: Game;
     /** Runs once the component is mounted on its entity. */

package/dist/component.js

@@ -6,6 +6,7 @@ export class Component {
     static componentName = 'Component';
     static displayName;
     static params;
+    static transient;
     entity;
     game;
 }

package/dist/components/animated-sprite.d.ts

@@ -26,6 +26,7 @@ export declare class AnimatedSprite extends Component {
             step: number;
         };
     };
+    static transient: string[];
     /** Spritesheet URL. */
     texture: string;
     /** Sheet grid dimensions. */

package/dist/components/animated-sprite.js

@@ -19,6 +19,16 @@ export class AnimatedSprite extends Component {
         offsetY: { label: 'y offset' },
         layer: { label: 'layer', min: -5, max: 5, step: 1 },
     };
+    static transient = [
+        'current',
+        'player',
+        'sheets',
+        'texs',
+        'mesh',
+        'frame',
+        'frameScaleX',
+        'frameScaleY',
+    ];
     /** Spritesheet URL. */
     texture = '';
     /** Sheet grid dimensions. */

package/dist/components/sprite.d.ts

@@ -20,6 +20,7 @@ export declare class Sprite extends Component {
             step: number;
         };
     };
+    static transient: string[];
     private _width;
     private _height;
     get width(): number;

package/dist/components/sprite.js

@@ -12,6 +12,7 @@ export class Sprite extends Component {
         offsetY: { label: 'y offset' },
         layer: { label: 'layer', min: -5, max: 5, step: 1 },
     };
+    static transient = ['mesh'];
     // Size, color and offset are reactive so inspector edits update the live quad.
     // Texture still needs a rebuild. TODO(H1): fully reactive props.
     _width = 1;

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { CAMERA_DEFAULTS, resolveSceneCamera, stepSceneCamera } from './camera.j
 export type { SceneCameraJson, CameraLimitsJson, ResolvedSceneCamera } from './camera.js';
 export { Entity } from './entity.js';
 export { Component } from './component.js';
+export { authoringDefaults } from './authoring-defaults.js';
 export type { ComponentClass, ContactNormal, ParamSpec, SolidContact, } from './component.js';
 export { collectModuleComponents, mergeRegistryComponents } from './component-registry.js';
 export type { ComponentModule } from './component-registry.js';

package/dist/index.js

@@ -2,6 +2,7 @@ export { Game } from './game.js';
 export { CAMERA_DEFAULTS, resolveSceneCamera, stepSceneCamera } from './camera.js';
 export { Entity } from './entity.js';
 export { Component } from './component.js';
+export { authoringDefaults } from './authoring-defaults.js';
 export { collectModuleComponents, mergeRegistryComponents } from './component-registry.js';
 export { Input, DEFAULT_BINDINGS } from './input.js';
 export { Stats } from './stats.js';

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

@@ -13,7 +13,7 @@ export interface StateTransitionJson {
  * transitions instead of a real state.
  */
 export interface StateJson {
-    /** Clip to play on enter; defaults to the state's own name. */
+    /** Clip reference resolved against the sibling AnimatedSprite; defaults to the state's name. */
     clip?: string;
     transitions?: StateTransitionJson[];
 }
@@ -53,6 +53,7 @@ export declare class StateMachine extends Component {
             label: string;
         };
     };
+    static transient: string[];
     /** The character's role — names the logic set providing its state code. */
     role: string;
     /** Starting state; defaults to the first declared state. */

package/dist/state/state-machine.js

@@ -47,6 +47,7 @@ export class StateMachine extends Component {
     static params = {
         role: { label: 'Role' },
     };
+    static transient = ['current', 'elapsed', 'instanceHooks', 'signals', 'warnedClips'];
     /** The character's role — names the logic set providing its state code. */
     role = '';
     /** Starting state; defaults to the first declared state. */
@@ -96,7 +97,12 @@ export class StateMachine extends Component {
         // 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)
+            // A '*' edge is re-merged against whatever state the loop just
+            // entered, so a still-queued signal (signals.clear() only runs after
+            // this loop) keeps firing every remaining hop. Without this guard
+            // that replays onExit/onEnter on the state hops already settled into
+            // — goto() has the same guard for the same reason.
+            if (!edge || edge.to === this.current)
                 break;
             // A transition fired by a key press spends it: one press, one
             // transition — it can't fire again from the state just entered.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waica/engine",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Waica game engine core — archetype-driven, web-first, 2D & 3D",
   "license": "MIT",
   "type": "module",