fraxel 0.1.0-alpha.1

package/dist/nodes/_node.js

@@ -0,0 +1,371 @@
+import { Event, getEventName } from '../events/event.js';
+import {} from './lib/types.js';
+import { InvalidNodeIdError, NodeChildNotFoundError, NodeTypeMismatchError, UnknownNodeTypeError, } from '../errors/node.js';
+import { getNodeName } from './lib/utils.js';
+import { Nodes } from './lib/registry.js';
+import { PrimaryNode } from './lib/enum.js';
+const idRegEx = /([a-zA-Z][a-zA-Z0-9-_]*)/g;
+export class Node {
+    type;
+    #id;
+    #zIndex = 0;
+    _parent;
+    _children = [];
+    /**
+     * The **`deltaIncrease`** property changes the speed of the node and its children.
+     *
+     * @example
+     * ```tsx
+     * // Speed x0.5
+     * <transform deltaIncrease={0.5}>
+     *   <Ball />
+     * </transform>
+     * ```
+     */
+    deltaIncrease = 1;
+    script;
+    // States
+    /**
+     * The **`isStarted`** property of the node indicates whether the node is started.
+     */
+    isStarted = false;
+    /**
+     * The **`isDestroyed`** property of the node indicates whether the node is destroyed.
+     */
+    isDestroyed = false;
+    constructor(type, { id, zIndex, deltaIncrease, script, children }) {
+        this.type = type;
+        if (typeof id === 'string') {
+            const matches = id.match(idRegEx);
+            if (matches == null || matches.length !== 1 || matches[0] !== id) {
+                throw new InvalidNodeIdError('The id ' + id + ' does not matches with `([a-zA-Z][a-zA-Z0-9-_]*)`');
+            }
+        }
+        this.#id = id ?? Symbol(type);
+        if (script) {
+            this.script = script;
+            this.script.init(this);
+        }
+        this.#zIndex = zIndex ?? this.#zIndex;
+        this.deltaIncrease = deltaIncrease ?? this.deltaIncrease;
+        this.addChild(...(children ?? []));
+    }
+    /**
+     * The read-only **`id`** property of a node represents the node's identifier.
+     * It can be used to retrieve this node via `child()`.
+     * IDs can be non-unique and must match `([a-zA-Z][a-zA-Z0-9-_]*)`.
+     *
+     * @example
+     * ```tsx
+     * const container = useChild(['container'], PrimaryNode.Transform)
+     *
+     * return (
+     *   <transform>
+     *     <transform id='container' />
+     *   </transform>
+     * )
+     * ```
+     *
+     * **`id`** can be used as path to find nested nodes.
+     *
+     * @example
+     * ```tsx
+     * const child2 = useChild(['child1', 'child2'], PrimaryNode.Transform)
+     *
+     * return (
+     *   <transform>
+     *     <transform id='child1'>
+     *       <transform id='child2' />
+     *     </transform>
+     *   </transform>
+     * )
+     * ```
+     */
+    get id() {
+        return this.#id;
+    }
+    /**
+     * The read-only **`parent`** property returns the parent of this node.
+     *
+     * @example
+     * ```tsx
+     * const transform = useNode(PrimaryNode.Transform)
+     *
+     * useMount(() => {
+     *   const parent = transform.node.parent
+     *   parent?.destroy()
+     * })
+     *
+     * return (
+     *   <transform ref={transform}>
+     *     <transform id='container' />
+     *   </transform>
+     * )
+     * ```
+     */
+    get parent() {
+        return this._parent;
+    }
+    /**
+     * The read-only **`children`** property returns the child nodes.
+     *
+     * @example
+     * ```tsx
+     * const transform = useNode(PrimaryNode.Transform)
+     *
+     * useMount(() => {
+     *   const children = transform.node.children
+     *   console.log(children) // [Node]
+     * })
+     *
+     * return (
+     *   <transform ref={transform}>
+     *     <transform id='container' />
+     *   </transform>
+     * )
+     * ```
+     */
+    get children() {
+        return this._children;
+    }
+    /**
+     * Gets or sets the **`zIndex`** of the node.
+     */
+    set zIndex(value) {
+        if (value === this.#zIndex)
+            return;
+        this.zIndexChanged.emit(value);
+        this.#zIndex = value;
+    }
+    get zIndex() {
+        return this.#zIndex;
+    }
+    /**
+     * Gets or sets the **`globalZIndex`** of the node.
+     */
+    set globalZIndex(value) {
+        if (this._parent == null)
+            this.zIndex = value;
+        else
+            this.zIndex = value - this._parent.globalZIndex;
+    }
+    get globalZIndex() {
+        if (this._parent == null)
+            return this.zIndex;
+        return this.zIndex + this._parent.globalZIndex;
+    }
+    /**
+     * Gets or sets the **`globalDeltaIncrease`** of the node.
+     */
+    set globalDeltaIncrease(value) {
+        if (this._parent == null)
+            this.deltaIncrease = value;
+        else
+            this.deltaIncrease = value / this._parent.globalDeltaIncrease;
+    }
+    get globalDeltaIncrease() {
+        if (this._parent == null)
+            return this.deltaIncrease;
+        return this.deltaIncrease * this._parent.globalDeltaIncrease;
+    }
+    // Methods
+    /**
+     * Returns the first descendant node that matches the given path and type.
+     *
+     * @param options Options to filter nodes
+     * @returns The matching node, or throws if not found
+     *
+     * @example
+     * ```tsx
+     * const transform = useNode(PrimaryNode.Transform)
+     *
+     * useMount(() => {
+     *   const sprite = transform.node.child({
+     *     path: ['sprite'],
+     *     type: PrimaryNode.Sprite
+     *   })
+     * })
+     *
+     * return (
+     *   <transform ref={transform}>
+     *     <sprite id='sprite' />
+     *   </transform>
+     * )
+     * ```
+     */
+    child(options) {
+        const { type, path } = options;
+        if (!(type in Nodes)) {
+            throw new UnknownNodeTypeError(type);
+        }
+        let node;
+        for (let i = 0; i < path.length; i++) {
+            if (node == null)
+                break;
+            const n = path[i];
+            if (n === '' && i === path.length - 1)
+                break;
+            node = node._children.find((node) => node.id === n);
+        }
+        if (node == null) {
+            throw new NodeChildNotFoundError(path.join('/'));
+        }
+        if (!(node instanceof Nodes[type])) {
+            throw new NodeTypeMismatchError(type, getNodeName(node));
+        }
+        return node;
+    }
+    /**
+     * Add child nodes to this node.
+     * @param children Nodes to add as children
+     */
+    addChild(...children) {
+        for (const child of children) {
+            if (this._children.includes(child)) {
+                const index = this._children.indexOf(child);
+                this._children.splice(index, 1);
+            }
+            this.#attachChild(child);
+            this._children.push(child);
+            if (this.isStarted) {
+                child.start();
+            }
+        }
+        this.#sortChildren();
+    }
+    removeChild(child) {
+        const index = this._children.indexOf(child);
+        if (index === -1)
+            return;
+        child._parent = undefined;
+        child.zIndexChanged.off(this.#reorder);
+        this._children.splice(index, 1);
+    }
+    #attachChild(child) {
+        child._parent = this;
+        child.zIndexChanged.on(this.#reorder);
+    }
+    #reorder = () => {
+        this.#sortChildren();
+    };
+    #sortChildren() {
+        this._children.sort((a, b) => a.globalZIndex - b.globalZIndex);
+    }
+    // Events
+    /**
+     * The **`zIndexChanged`** event fires when the node's `zIndex` value changes.
+     */
+    zIndexChanged = new Event('zIndexChange', (_zIndex) => { });
+    /**
+     * The **`started`** event fires when the node finishes its `start()` lifecycle.
+     */
+    started = new Event('start', () => { });
+    /**
+     * The **`drawed`** event fires each frame when the node is being drawn.
+     */
+    drawed = new Event('draw', (_delta) => { });
+    /**
+     * The **`updated`** event fires each frame during the node's update cycle.
+     */
+    updated = new Event('update', (_delta) => { });
+    /**
+     * The **`destroyed`** event fires when the node is destroyed.
+     */
+    destroyed = new Event('destroy', () => { });
+    // Event functions
+    onZIndexChange(_zIndex) { }
+    onStart() { }
+    onDraw(_delta) { }
+    onUpdate(_delta) { }
+    onDestroy() { }
+    // Lifecycle methods
+    /**
+     * The **`start`** method initializes the node and starts its lifecycle.
+     * It attaches event callbacks and starts all child nodes.
+     * Called automatically when the node is added to the scene.
+     */
+    start() {
+        if (this.isStarted)
+            return;
+        // Attach events
+        const events = Object.keys(this)
+            .filter((key) => this[key] instanceof Event)
+            .map((key) => this[key]);
+        for (const event of events) {
+            const key = getEventName(event.baseName);
+            if (this[key] == null)
+                continue;
+            const cb = this[key];
+            event.on(cb.bind(this));
+        }
+        this.isStarted = true;
+        for (const node of this._children) {
+            node.start();
+        }
+        this.started.emit();
+    }
+    /**
+     * The **`update`** method is called each frame to update the node and its children.
+     * @param delta The time elapsed since the last frame in seconds.
+     */
+    update(delta) {
+        this.updated.emit(delta);
+        for (const node of this._children) {
+            node.update(delta * node.deltaIncrease);
+        }
+    }
+    /**
+     * The **`draw`** method is called each frame to render the node and its children.
+     * It applies position translation for proper rendering hierarchy.
+     * @param delta The time elapsed since the last frame in seconds.
+     */
+    draw(delta) {
+        for (const node of this._children) {
+            node.draw(delta * node.deltaIncrease);
+        }
+        this.drawed.emit(delta);
+    }
+    /**
+     * The **`destroy`** method destroys this node and all its children.
+     */
+    destroy() {
+        if (this.isDestroyed)
+            return;
+        const q = this._parent != null ? this._parent._children : [];
+        const index = q.indexOf(this);
+        if (index < 0)
+            return;
+        q.splice(index, 1);
+        this.isDestroyed = true;
+        this.destroyed.emit();
+        this.cleanEvents();
+        for (const node of [...this._children]) {
+            node.destroy();
+        }
+    }
+    /**
+     * The **`cleanEvents`** method removes all event listeners from this node.
+     * It is called automatically when the node is destroyed.
+     *
+     * @example
+     * ```tsx
+     * const transform = useNode(PrimaryNode.Transform)
+     *
+     * useMount(() => {
+     *   transform.node.started.on(() => {
+     *     console.log('Node started')
+     *   })
+     *
+     *   transform.node.cleanEvents()
+     *   // No listeners will fire
+     * })
+     * ```
+     */
+    cleanEvents() {
+        this.started.clean();
+        this.drawed.clean();
+        this.updated.clean();
+        this.destroyed.clean();
+    }
+}
+//# sourceMappingURL=_node.js.map

package/dist/nodes/_node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_node.js","sourceRoot":"","sources":["../../src/nodes/_node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,EAAsB,MAAM,gBAAgB,CAAA;AACnD,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAC5C,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAEzC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAoE3C,MAAM,OAAO,GAAG,2BAA2B,CAAA;AAE3C,MAAM,OAAgB,IAAI;IACxB,IAAI,CAAG;IACP,GAAG,CAAiB;IACpB,OAAO,GAAW,CAAC,CAAA;IACnB,OAAO,CAAO;IACd,SAAS,GAAW,EAAE,CAAA;IACtB;;;;;;;;;;OAUG;IACH,aAAa,GAAW,CAAC,CAAA;IACzB,MAAM,CAAiB;IACvB,SAAS;IACT;;OAEG;IACH,SAAS,GAAY,KAAK,CAAA;IAC1B;;OAEG;IACH,WAAW,GAAY,KAAK,CAAA;IAE5B,YAAY,IAAO,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAkB;QAClF,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAEhB,IAAI,OAAO,EAAE,KAAK,QAAQ,EAAE,CAAC;YAC3B,MAAM,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;YACjC,IAAI,OAAO,IAAI,IAAI,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC;gBACjE,MAAM,IAAI,kBAAkB,CAC1B,SAAS,GAAG,EAAE,GAAG,mDAAmD,CACrE,CAAA;YACH,CAAC;QACH,CAAC;QAED,IAAI,CAAC,GAAG,GAAG,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,CAAA;QAE7B,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;YACpB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAwB,CAAC,CAAA;QAC5C,CAAC;QAED,IAAI,CAAC,OAAO,GAAG,MAAM,IAAI,IAAI,CAAC,OAAO,CAAA;QACrC,IAAI,CAAC,aAAa,GAAG,aAAa,IAAI,IAAI,CAAC,aAAa,CAAA;QAExD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,CAAA;IACpC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,IAAI,EAAE;QACJ,OAAO,IAAI,CAAC,GAAG,CAAA;IACjB,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,OAAO,CAAA;IACrB,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,SAAS,CAAA;IACvB,CAAC;IAED;;OAEG;IACH,IAAI,MAAM,CAAC,KAAa;QACtB,IAAI,KAAK,KAAK,IAAI,CAAC,OAAO;YAAE,OAAM;QAClC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAC9B,IAAI,CAAC,OAAO,GAAG,KAAK,CAAA;IACtB,CAAC;IACD,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,OAAO,CAAA;IACrB,CAAC;IACD;;OAEG;IACH,IAAI,YAAY,CAAC,KAAK;QACpB,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI;YAAE,IAAI,CAAC,MAAM,GAAG,KAAK,CAAA;;YACxC,IAAI,CAAC,MAAM,GAAG,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY,CAAA;IACtD,CAAC;IACD,IAAI,YAAY;QACd,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI;YAAE,OAAO,IAAI,CAAC,MAAM,CAAA;QAC5C,OAAO,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY,CAAA;IAChD,CAAC;IACD;;OAEG;IACH,IAAI,mBAAmB,CAAC,KAAK;QAC3B,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI;YAAE,IAAI,CAAC,aAAa,GAAG,KAAK,CAAA;;YAC/C,IAAI,CAAC,aAAa,GAAG,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,mBAAmB,CAAA;IACpE,CAAC;IACD,IAAI,mBAAmB;QACrB,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI;YAAE,OAAO,IAAI,CAAC,aAAa,CAAA;QACnD,OAAO,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,OAAO,CAAC,mBAAmB,CAAA;IAC9D,CAAC;IAED,UAAU;IACV;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,KAAK,CAAwB,OAA+C;QAC1E,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,OAAO,CAAA;QAE9B,IAAI,CAAC,CAAC,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,oBAAoB,CAAC,IAAI,CAAC,CAAA;QACtC,CAAC;QAED,IAAI,IAAsB,CAAA;QAE1B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACrC,IAAI,IAAI,IAAI,IAAI;gBAAE,MAAK;YACvB,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAA;YACjB,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,CAAC,MAAM,GAAG,CAAC;gBAAE,MAAK;YAC5C,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC,CAAA;QACrD,CAAC;QAED,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;YACjB,MAAM,IAAI,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;QAClD,CAAC;QAED,IAAI,CAAC,CAAC,IAAI,YAAY,KAAK,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;YACnC,MAAM,IAAI,qBAAqB,CAAC,IAAI,EAAE,WAAW,CAAC,IAAkC,CAAC,CAAC,CAAA;QACxF,CAAC;QAED,OAAO,IAAwB,CAAA;IACjC,CAAC;IAED;;;OAGG;IACH,QAAQ,CAAC,GAAG,QAAgB;QAC1B,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;YAC7B,IAAI,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;gBACnC,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;gBAC3C,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAA;YACjC,CAAC;YACD,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAA;YACxB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;YAC1B,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;gBACnB,KAAK,CAAC,KAAK,EAAE,CAAA;YACf,CAAC;QACH,CAAC;QACD,IAAI,CAAC,aAAa,EAAE,CAAA;IACtB,CAAC;IACD,WAAW,CAAC,KAAW;QACrB,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;QAC3C,IAAI,KAAK,KAAK,CAAC,CAAC;YAAE,OAAM;QACxB,KAAK,CAAC,OAAO,GAAG,SAAS,CAAA;QACzB,KAAK,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QACtC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAA;IACjC,CAAC;IAED,YAAY,CAAC,KAAW;QACtB,KAAK,CAAC,OAAO,GAAG,IAAI,CAAA;QACpB,KAAK,CAAC,aAAa,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IACvC,CAAC;IACD,QAAQ,GAAG,GAAG,EAAE;QACd,IAAI,CAAC,aAAa,EAAE,CAAA;IACtB,CAAC,CAAA;IACD,aAAa;QACX,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,YAAY,CAAC,CAAA;IAChE,CAAC;IAED,SAAS;IACT;;OAEG;IACH,aAAa,GAAG,IAAI,KAAK,CAAC,cAAc,EAAE,CAAC,OAAe,EAAE,EAAE,GAAE,CAAC,CAAC,CAAA;IAElE;;OAEG;IACH,OAAO,GAAG,IAAI,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;IAEtC;;OAEG;IACH,MAAM,GAAG,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC,MAAc,EAAE,EAAE,GAAE,CAAC,CAAC,CAAA;IAElD;;OAEG;IACH,OAAO,GAAG,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC,MAAc,EAAE,EAAE,GAAE,CAAC,CAAC,CAAA;IAErD;;OAEG;IACH,SAAS,GAAG,IAAI,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;IAE1C,kBAAkB;IAClB,cAAc,CAAE,OAAe,IAAG,CAAC;IACnC,OAAO,KAAK,CAAC;IACb,MAAM,CAAE,MAAc,IAAG,CAAC;IAC1B,QAAQ,CAAE,MAAc,IAAG,CAAC;IAC5B,SAAS,KAAK,CAAC;IAEf,oBAAoB;IACpB;;;;OAIG;IACH,KAAK;QACH,IAAI,IAAI,CAAC,SAAS;YAAE,OAAM;QAE1B,gBAAgB;QAChB,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC;aAC7B,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,GAAiB,CAAC,YAAY,KAAK,CAAC;aACzD,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,GAAiB,CAAC,CAAyB,CAAA;QAEhE,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,MAAM,GAAG,GAAG,YAAY,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAA;YACxC,IAAI,IAAI,CAAC,GAAiB,CAAC,IAAI,IAAI;gBAAE,SAAQ;YAC7C,MAAM,EAAE,GAAG,IAAI,CAAC,GAAiB,CAAe,CAAA;YAChD,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;QACzB,CAAC;QAED,IAAI,CAAC,SAAS,GAAG,IAAI,CAAA;QAErB,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YAClC,IAAI,CAAC,KAAK,EAAE,CAAA;QACd,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAA;IACrB,CAAC;IACD;;;OAGG;IACH,MAAM,CAAC,KAAa;QAClB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACxB,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YAClC,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,CAAA;QACzC,CAAC;IACH,CAAC;IACD;;;;OAIG;IACH,IAAI,CAAC,KAAa;QAChB,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YAClC,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,CAAA;QACvC,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACzB,CAAC;IAED;;OAEG;IACH,OAAO;QACL,IAAI,IAAI,CAAC,WAAW;YAAE,OAAM;QAE5B,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAA;QAE5D,MAAM,KAAK,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;QAC7B,IAAI,KAAK,GAAG,CAAC;YAAE,OAAM;QACrB,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAA;QAElB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAA;QACvB,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAA;QAErB,IAAI,CAAC,WAAW,EAAE,CAAA;QAElB,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YACvC,IAAI,CAAC,OAAO,EAAE,CAAA;QAChB,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,WAAW;QACT,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;QACpB,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAA;QACnB,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;QACpB,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAA;IACxB,CAAC;CACF"}

package/dist/nodes/animation-player.d.ts

@@ -0,0 +1,208 @@
+import { Event } from '../events/event.js';
+import { PrimaryNode } from './lib/enum.js';
+import { Node, type NodeOptions } from './_node.js';
+import type { Reactive } from '../reactivity/types.js';
+/**
+ * Options for the `AnimationPlayer` node.
+ */
+export interface AnimationPlayerOptions extends NodeOptions<PrimaryNode.AnimationPlayer> {
+    /**
+     * A function that returns a record of animation definitions.
+     * The function is called when the node starts (deferred), not at construction time.
+     *
+     * @example
+     * ```tsx
+     * <animation-player
+     *   animations={() => ({
+     *     idle: { keyframes: idleFrames, fps: 8 },
+     *     walk: { keyframes: walkFrames, fps: 8, loop: true },
+     *   })}
+     * />
+     * ```
+     */
+    animations?: Reactive<Record<string, Animation>>;
+    /**
+     * The animation to play initially. Accepts a static name or a reactive `Reactive`
+     * that automatically switches animations when the signal value changes.
+     *
+     * @example
+     * ```tsx
+     * // Static
+     * <animation-player animations={...} currentAnim="idle" />
+     *
+     * // Reactive
+     * const animName = useComputed(() => isWalking() ? 'walk' : 'idle')
+     * <animation-player animations={...} currentAnim={animName} />
+     * ```
+     */
+    currentAnim?: Reactive<string>;
+    /**
+     * When `true`, the node is automatically destroyed when the current animation ends.
+     * Useful for one-shot effect animations.
+     *
+     * @default false
+     *
+     * @example
+     * ```tsx
+     * <animation-player
+     *   animations={() => ({ explode: { keyframes: frames, fps: 12 } })}
+     *   currentAnim="explode"
+     *   destroyOnEnd
+     * />
+     * ```
+     */
+    destroyOnEnd?: boolean;
+}
+export declare class AnimationPlayer extends Node<PrimaryNode.AnimationPlayer> {
+    #private;
+    /** The read-only **`currentAnim`** property returns the current animation name */
+    get currentAnim(): string | null;
+    /** The read-only **`index`** property returns the current index */
+    get index(): number;
+    /**
+     * Creates a new `AnimationPlayer` node.
+     *
+     * If `animations` is provided, it is invoked when the node starts.
+     * If `currentAnim` is a `SignalGetter`, the player reactively tracks
+     * the signal and switches animations automatically.
+     *
+     * @param options AnimationPlayer configuration options
+     */
+    constructor(options: AnimationPlayerOptions);
+    /**
+     * Detects whether `currentAnim` **change**
+     */
+    animationChanged: Event<[_newAnim: string, _oldAnim: string | null], "animationChange">;
+    /**
+     * Detects whether `stop` is **called**
+     */
+    animationStopped: Event<[_anim: string], "animationStop">;
+    /**
+     * Detects whether this `index` **change**
+     */
+    animationIndexChanged: Event<[_index: number], "animationIndexChange">;
+    /**
+     * Detects whether the current animation **end**
+     */
+    animationEnded: Event<[_anim: string], "animationEnd">;
+    /**
+     * The **`add`** method adds an animation with a key.
+     * @param animName Animation identifier
+     * @param animation Animation object
+     * @returns This instance for chaining
+     *
+     * @example
+     * ```tsx
+     * const sprite = useNode(PrimaryNode.Sprite)
+     * const anim = useNode(PrimaryNode.AnimationPlayer)
+     *
+     * useMount(() => {
+     *   anim.node
+     *     .add('idle', {
+     *       fps: 4,
+     *       keyframes: keyframesFromSheet(sprite.node, IDLE_TEXTURE, 4),
+     *       loop: true,
+     *     })
+     *     .add('walk', {
+     *       fps: 4,
+     *       keyframes: keyframesFromSheet(sprite.node, WALK_TEXTURE, 4),
+     *       loop: true,
+     *     })
+     *     .play('idle')
+     * })
+     *
+     * return (
+     *   <sprite ref={sprite} textureId={IDLE_TEXTURE} sourceSize={new Vector2(16, 16)}>
+     *     <animation-player ref={anim} />
+     *   </sprite>
+     * )
+     * ```
+     */
+    add(animName: string, animation: Animation): this;
+    /**
+     * The **`define`** method adds multiple animations at once.
+     * @param animations Record of animation names to animation objects
+     * @returns This instance for chaining
+     *
+     * @example
+     * ```tsx
+     * const sprite = useNode(PrimaryNode.Sprite)
+     * const anim = useNode(PrimaryNode.AnimationPlayer)
+     *
+     * useMount(() => {
+     *   anim.node
+     *     .define({
+     *       idle: {
+     *         fps: 4,
+     *         keyframes: keyframesFromSheet(sprite.node, IDLE_TEXTURE, 4),
+     *         loop: true,
+     *       },
+     *       walk: {
+     *         fps: 4,
+     *         keyframes: keyframesFromSheet(sprite.node, WALK_TEXTURE, 4),
+     *         loop: true,
+     *       },
+     *     })
+     *     .play('idle')
+     * })
+     *
+     * return (
+     *   <sprite ref={sprite} textureId={IDLE_TEXTURE} sourceSize={new Vector2(16, 16)}>
+     *     <animation-player ref={anim} />
+     *   </sprite>
+     * )
+     * ```
+     */
+    define(animations: Record<string, Animation>): this;
+    /**
+     * The **`play`** method plays an animation by name.
+     * @param animName Animation identifier
+     * @param index Index to start from (default `0`)
+     *
+     * @example
+     * ```tsx
+     * const anim = useNode(PrimaryNode.AnimationPlayer)
+     *
+     * useMount(() => {
+     *   anim.node.play('idle')
+     * })
+     *
+     * return <animation-player ref={anim} />
+     * ```
+     */
+    play(animName: string, index?: number): void;
+    /**
+     * The **`setNext`** method sets the animation to play after the current one ends.
+     * @param animName Animation to play next, or `null` to stop
+     *
+     * @example
+     * ```tsx
+     * const anim = useNode(PrimaryNode.AnimationPlayer)
+     *
+     * useEvent(anim, 'animationEnded', () => {
+     *   anim.node.setNext('idle')
+     * })
+     * ```
+     */
+    setNext(animName: string | null): void;
+    /**
+     * The **`stop`** method stops the current animation.
+     */
+    stop(): void;
+    update(delta: number): void;
+    cleanEvents(): void;
+}
+export interface Animation {
+    /** Frames per second */
+    fps: number;
+    /** Frames in the `Animation` */
+    keyframes: AnimationKeyframe[];
+    /** Whether the `Animation` should start over when it reaches the end. */
+    loop?: boolean | undefined;
+}
+/**
+ * A keyframe function that receives the local time (0–1) within the frame
+ * and applies the frame's visual state to the sprite.
+ */
+export type AnimationKeyframe = (time: number) => void;
+//# sourceMappingURL=animation-player.d.ts.map

package/dist/nodes/animation-player.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation-player.d.ts","sourceRoot":"","sources":["../../src/nodes/animation-player.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAA;AAEnD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAGtD;;GAEG;AACH,MAAM,WAAW,sBAAuB,SAAQ,WAAW,CAAC,WAAW,CAAC,eAAe,CAAC;IACtF;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAA;IAChD;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;IAC9B;;;;;;;;;;;;;;OAcG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AAED,qBAAa,eAAgB,SAAQ,IAAI,CAAC,WAAW,CAAC,eAAe,CAAC;;IAOpE,kFAAkF;IAClF,IAAI,WAAW,kBAEd;IACD,mEAAmE;IACnE,IAAI,KAAK,WAER;IAED;;;;;;;;OAQG;gBACS,OAAO,EAAE,sBAAsB;IA2B3C;;OAEG;IACH,gBAAgB,wEAAkF;IAClG;;OAEG;IACH,gBAAgB,0CAAoD;IACpE;;OAEG;IACH,qBAAqB,kDAA4D;IACjF;;OAEG;IACH,cAAc,yCAAmD;IAGjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS;IAI1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC;IAW5C;;;;;;;;;;;;;;;OAeG;IACH,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;IAUrC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAI/B;;OAEG;IACH,IAAI;IAuDJ,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAK3B,WAAW,IAAI,IAAI;CAOpB;AAID,MAAM,WAAW,SAAS;IACxB,wBAAwB;IACxB,GAAG,EAAE,MAAM,CAAA;IACX,gCAAgC;IAChC,SAAS,EAAE,iBAAiB,EAAE,CAAA;IAC9B,yEAAyE;IACzE,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAC3B;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA"}