fraxel 0.1.0-alpha.1

package/dist/nodes/animation-player.js

@@ -0,0 +1,249 @@
+import { KeyframeNotFoundError } from '../errors/animation.js';
+import { Event } from '../events/event.js';
+import { PrimaryNode } from './lib/enum.js';
+import { Node } from './_node.js';
+import { Nodes } from './lib/registry.js';
+import { subReactive } from '../reactivity/reactive.js';
+export class AnimationPlayer extends Node {
+    #animations = new Map();
+    #currentAnim = null;
+    #nextAnim = null;
+    #index = 0;
+    #destroyOnEnd = false;
+    /** The read-only **`currentAnim`** property returns the current animation name */
+    get currentAnim() {
+        return this.#currentAnim;
+    }
+    /** The read-only **`index`** property returns the current index */
+    get index() {
+        return Math.floor(this.#index);
+    }
+    /**
+     * 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) {
+        super(PrimaryNode.AnimationPlayer, options);
+        this.#destroyOnEnd = options.destroyOnEnd ?? false;
+        this.started.on(() => {
+            if (options.animations) {
+                this.define(subReactive(options.animations, (animations) => {
+                    this.#animations.clear();
+                    this.define(animations);
+                }));
+            }
+            if (options.currentAnim != null) {
+                this.play(subReactive(options.currentAnim, (anim) => this.play(anim), (fn) => this.destroyed.on(fn)));
+            }
+        });
+    }
+    // Events
+    /**
+     * Detects whether `currentAnim` **change**
+     */
+    animationChanged = new Event('animationChange', (_newAnim, _oldAnim) => { });
+    /**
+     * Detects whether `stop` is **called**
+     */
+    animationStopped = new Event('animationStop', (_anim) => { });
+    /**
+     * Detects whether this `index` **change**
+     */
+    animationIndexChanged = new Event('animationIndexChange', (_index) => { });
+    /**
+     * Detects whether the current animation **end**
+     */
+    animationEnded = new Event('animationEnd', (_anim) => { });
+    // utils
+    /**
+     * 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, animation) {
+        this.#animations.set(animName, animation);
+        return 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) {
+        for (const animName in animations) {
+            if (!Object.hasOwn(animations, animName))
+                continue;
+            const animation = animations[animName];
+            if (animation == null)
+                continue;
+            this.add(animName, animation);
+        }
+        return 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, index) {
+        if (this.#currentAnim === animName && (index == null || Math.floor(this.#index) === index))
+            return;
+        if (this.#currentAnim != null)
+            this.stop();
+        const oldAnim = this.#currentAnim;
+        this.#index = index ?? 0;
+        this.#currentAnim = animName;
+        this.animationChanged.emit(animName, oldAnim);
+        this.animationIndexChanged.emit(index ?? 0);
+    }
+    /**
+     * 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) {
+        this.#nextAnim = animName;
+    }
+    /**
+     * The **`stop`** method stops the current animation.
+     */
+    stop() {
+        if (this.#currentAnim == null)
+            return;
+        this.animationStopped.emit(this.#currentAnim);
+        this.#index = 0;
+        this.#currentAnim = null;
+    }
+    #updateAnim(delta) {
+        if (this.#currentAnim == null)
+            return;
+        const anim = this.#animations.get(this.#currentAnim);
+        if (anim == null)
+            return;
+        if (this.#index >= anim.keyframes.length) {
+            if (!anim.loop) {
+                const animName = this.#currentAnim;
+                this.stop();
+                this.animationEnded.emit(animName);
+                if (this.#destroyOnEnd) {
+                    this.destroy();
+                    return;
+                }
+                if (this.#nextAnim == null)
+                    return;
+            }
+            if (this.#nextAnim != null) {
+                if (this.#currentAnim != null) {
+                    this.stop();
+                }
+                this.play(this.#nextAnim);
+                this.#nextAnim = null;
+            }
+            this.#index = 0;
+            this.animationIndexChanged.emit(0);
+        }
+        const i = Math.floor(this.#index);
+        const kf = anim.keyframes[i];
+        if (kf == null)
+            throw new KeyframeNotFoundError(i);
+        kf(this.#index % 1);
+        this.#index += delta * anim.fps;
+        if (this.#index < anim.keyframes.length && i !== Math.floor(this.#index)) {
+            this.animationIndexChanged.emit(Math.floor(this.#index));
+        }
+    }
+    update(delta) {
+        this.#updateAnim(delta);
+        super.update(delta);
+    }
+    cleanEvents() {
+        this.animationChanged.clean();
+        this.animationEnded.clean();
+        this.animationIndexChanged.clean();
+        this.animationStopped.clean();
+        super.cleanEvents();
+    }
+}
+Nodes['animation-player'] = AnimationPlayer;
+//# sourceMappingURL=animation-player.js.map

package/dist/nodes/animation-player.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation-player.js","sourceRoot":"","sources":["../../src/nodes/animation-player.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,128 @@
+import { Event } from '../events/event.js';
+import { PrimaryNode } from './lib/enum.js';
+import { Node, type NodeOptions } from './_node.js';
+/**
+ * Options for the `AudioPlayer` node.
+ */
+export interface AudioPlayerOptions extends NodeOptions<PrimaryNode.AudioPlayer> {
+    /**
+     * The **`soundId`** property defines which sound to play.
+     * Obtain a sound ID via `loadSound()`.
+     *
+     * @example
+     * ```tsx
+     * <audio-player soundId={shootSound} />
+     * ```
+     */
+    soundId: symbol;
+    /**
+     * The **`loop`** property determines whether the sound loops.
+     * @default false
+     */
+    loop?: boolean;
+    /**
+     * The **`volume`** property sets the playback volume (0 to 1).
+     * @default 1
+     */
+    volume?: number;
+    /**
+     * The **`playbackRate`** property sets the playback speed.
+     * @default 1
+     */
+    playbackRate?: number;
+    /**
+     * The **`persistUntilEnd`** property keeps the node alive until playback finishes.
+     * When `true`, calling `destroy()` while audio is playing will defer destruction
+     * until the sound ends. Useful for components that play a sound and are destroyed
+     * immediately after.
+     *
+     * @default false
+     *
+     * @example
+     * ```tsx
+     * // Pea plays splat sound and destroys itself.
+     * // AudioPlayer survives until the sound finishes.
+     * <audio-player ref={audio} soundId={SPLAT} persistUntilEnd />
+     * ```
+     */
+    persistUntilEnd?: boolean;
+}
+/**
+ * The **`AudioPlayer`** node plays audio buffers. It manages `AudioBufferSourceNode`
+ * and `GainNode` for volume control. The `AudioContext` is created lazily on first use.
+ *
+ * @example
+ * ```tsx
+ * import { useNode, useEvent } from 'dinix/hooks'
+ * import { PrimaryNode } from 'dinix/nodes/enum'
+ *
+ * function Gun() {
+ *   const audio = useNode(PrimaryNode.AudioPlayer)
+ *   const clickable = useNode(PrimaryNode.Clickable)
+ *
+ *   useEvent(clickable, 'click', () => {
+ *     audio.node.play()
+ *   })
+ *
+ *   return (
+ *     <sprite ref={clickable} textureId={GUN}>
+ *       <audio-player ref={audio} soundId={shootSound} volume={0.8} />
+ *     </sprite>
+ *   )
+ * }
+ * ```
+ *
+ * For one-shot sounds on components that destroy themselves, use `persistUntilEnd`:
+ *
+ * @example
+ * ```tsx
+ * function Pea({ position }: { position: VectorLike }) {
+ *   const audio = useNode(PrimaryNode.AudioPlayer)
+ *   const collider = useNode(PrimaryNode.Collider)
+ *
+ *   useEvent(collider, 'colliderEntered', () => {
+ *     audio.node.play()
+ *     pea.node.destroy() // audio survives until sound finishes
+ *   })
+ *
+ *   return (
+ *     <transform ref={pea} position={position}>
+ *       <sprite textureId={PEA}>
+ *         <collider ref={collider} ... />
+ *       </sprite>
+ *       <audio-player ref={audio} soundId={SPLAT} persistUntilEnd />
+ *     </transform>
+ *   )
+ * }
+ * ```
+ */
+export declare class AudioPlayer extends Node<PrimaryNode.AudioPlayer> {
+    #private;
+    constructor(options: AudioPlayerOptions);
+    /** The `ended` event fires when playback reaches the end (non-looping only). */
+    ended: Event<[], "ended">;
+    /** The `error` event fires if playback fails. */
+    error: Event<[_err: Error], "error">;
+    /**
+     * Starts or resumes playback.
+     * @param offset Time in seconds to start from (default: 0 or pause position)
+     */
+    play(offset?: number): void;
+    /** Pauses playback without resetting position. */
+    pause(): void;
+    /** Stops playback and resets position to 0. */
+    stop(): void;
+    /** Whether the sound is currently playing. */
+    get isPlaying(): boolean;
+    /** Sets the volume (0 to 1). */
+    set volume(value: number);
+    /** Gets the current volume. */
+    get volume(): number;
+    /** Sets the playback rate. */
+    set playbackRate(value: number);
+    /** Gets the current playback rate. */
+    get playbackRate(): number;
+    /** @internal Cleans up audio resources on destroy. */
+    destroy(): void;
+}
+//# sourceMappingURL=audio-player.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"audio-player.d.ts","sourceRoot":"","sources":["../../src/nodes/audio-player.ts"],"names":[],"mappings":"AAAA,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;AAKnD;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,WAAW,CAAC,WAAW,CAAC,WAAW,CAAC;IAC9E;;;;;;;;OAQG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;IACd;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;;;;;;;;;;OAcG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,qBAAa,WAAY,SAAQ,IAAI,CAAC,WAAW,CAAC,WAAW,CAAC;;gBAYhD,OAAO,EAAE,kBAAkB;IASvC,gFAAgF;IAChF,KAAK,qBAA+B;IAEpC,iDAAiD;IACjD,KAAK,gCAA0C;IAE/C;;;OAGG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAsC3B,kDAAkD;IAClD,KAAK,IAAI,IAAI;IAOb,+CAA+C;IAC/C,IAAI,IAAI,IAAI;IAaZ,8CAA8C;IAC9C,IAAI,SAAS,YAEZ;IAED,gCAAgC;IAChC,IAAI,MAAM,CAAC,KAAK,EAAE,MAAM,EAKvB;IAED,+BAA+B;IAC/B,IAAI,MAAM,IARQ,MAAM,CAUvB;IAED,8BAA8B;IAC9B,IAAI,YAAY,CAAC,KAAK,EAAE,MAAM,EAK7B;IAED,sCAAsC;IACtC,IAAI,YAAY,IARQ,MAAM,CAU7B;IAED,sDAAsD;IACtD,OAAO,IAAI,IAAI;CAQhB"}

package/dist/nodes/audio-player.js

@@ -0,0 +1,173 @@
+import { Event } from '../events/event.js';
+import { PrimaryNode } from './lib/enum.js';
+import { Node } from './_node.js';
+import { Nodes } from './lib/registry.js';
+import { getAudioContext } from '../audio/audio-context.js';
+import { getSound } from '../assets/load-sound.js';
+/**
+ * The **`AudioPlayer`** node plays audio buffers. It manages `AudioBufferSourceNode`
+ * and `GainNode` for volume control. The `AudioContext` is created lazily on first use.
+ *
+ * @example
+ * ```tsx
+ * import { useNode, useEvent } from 'dinix/hooks'
+ * import { PrimaryNode } from 'dinix/nodes/enum'
+ *
+ * function Gun() {
+ *   const audio = useNode(PrimaryNode.AudioPlayer)
+ *   const clickable = useNode(PrimaryNode.Clickable)
+ *
+ *   useEvent(clickable, 'click', () => {
+ *     audio.node.play()
+ *   })
+ *
+ *   return (
+ *     <sprite ref={clickable} textureId={GUN}>
+ *       <audio-player ref={audio} soundId={shootSound} volume={0.8} />
+ *     </sprite>
+ *   )
+ * }
+ * ```
+ *
+ * For one-shot sounds on components that destroy themselves, use `persistUntilEnd`:
+ *
+ * @example
+ * ```tsx
+ * function Pea({ position }: { position: VectorLike }) {
+ *   const audio = useNode(PrimaryNode.AudioPlayer)
+ *   const collider = useNode(PrimaryNode.Collider)
+ *
+ *   useEvent(collider, 'colliderEntered', () => {
+ *     audio.node.play()
+ *     pea.node.destroy() // audio survives until sound finishes
+ *   })
+ *
+ *   return (
+ *     <transform ref={pea} position={position}>
+ *       <sprite textureId={PEA}>
+ *         <collider ref={collider} ... />
+ *       </sprite>
+ *       <audio-player ref={audio} soundId={SPLAT} persistUntilEnd />
+ *     </transform>
+ *   )
+ * }
+ * ```
+ */
+export class AudioPlayer extends Node {
+    #soundId;
+    #source = null;
+    #gainNode = null;
+    #loop;
+    #volume;
+    #playbackRate;
+    #persistUntilEnd;
+    #startTime = 0;
+    #pauseOffset = 0;
+    #isPlaying = false;
+    constructor(options) {
+        super(PrimaryNode.AudioPlayer, options);
+        this.#soundId = options.soundId;
+        this.#loop = options.loop ?? false;
+        this.#volume = options.volume ?? 1;
+        this.#playbackRate = options.playbackRate ?? 1;
+        this.#persistUntilEnd = options.persistUntilEnd ?? false;
+    }
+    /** The `ended` event fires when playback reaches the end (non-looping only). */
+    ended = new Event('ended', () => { });
+    /** The `error` event fires if playback fails. */
+    error = new Event('error', (_err) => { });
+    /**
+     * Starts or resumes playback.
+     * @param offset Time in seconds to start from (default: 0 or pause position)
+     */
+    play(offset) {
+        try {
+            const ctx = getAudioContext();
+            const buffer = getSound(this.#soundId);
+            this.stop();
+            this.#source = ctx.createBufferSource();
+            this.#gainNode = ctx.createGain();
+            this.#source.buffer = buffer;
+            this.#source.loop = this.#loop;
+            this.#source.playbackRate.value = this.#playbackRate;
+            this.#gainNode.gain.value = this.#volume;
+            this.#source.connect(this.#gainNode);
+            this.#gainNode.connect(ctx.destination);
+            this.#pauseOffset = offset ?? this.#pauseOffset;
+            this.#source.start(0, this.#pauseOffset);
+            this.#startTime = ctx.currentTime - this.#pauseOffset;
+            this.#isPlaying = true;
+            this.#source.onended = () => {
+                if (!this.#isPlaying)
+                    return;
+                this.#isPlaying = false;
+                this.#pauseOffset = 0;
+                this.ended.emit();
+                if (this.#persistUntilEnd && this.isDestroyed) {
+                    super.destroy();
+                }
+            };
+        }
+        catch (err) {
+            this.error.emit(err instanceof Error ? err : new Error(String(err)));
+        }
+    }
+    /** Pauses playback without resetting position. */
+    pause() {
+        if (!this.#isPlaying || this.#source == null)
+            return;
+        const ctx = getAudioContext();
+        this.#pauseOffset = (ctx.currentTime - this.#startTime) * this.#playbackRate;
+        this.stop();
+    }
+    /** Stops playback and resets position to 0. */
+    stop() {
+        if (this.#source != null) {
+            this.#source.onended = null;
+            this.#source.disconnect();
+            this.#source = null;
+        }
+        if (this.#gainNode != null) {
+            this.#gainNode.disconnect();
+            this.#gainNode = null;
+        }
+        this.#isPlaying = false;
+    }
+    /** Whether the sound is currently playing. */
+    get isPlaying() {
+        return this.#isPlaying;
+    }
+    /** Sets the volume (0 to 1). */
+    set volume(value) {
+        this.#volume = value;
+        if (this.#gainNode != null) {
+            this.#gainNode.gain.value = value;
+        }
+    }
+    /** Gets the current volume. */
+    get volume() {
+        return this.#volume;
+    }
+    /** Sets the playback rate. */
+    set playbackRate(value) {
+        this.#playbackRate = value;
+        if (this.#source != null) {
+            this.#source.playbackRate.value = value;
+        }
+    }
+    /** Gets the current playback rate. */
+    get playbackRate() {
+        return this.#playbackRate;
+    }
+    /** @internal Cleans up audio resources on destroy. */
+    destroy() {
+        if (this.#persistUntilEnd && this.#isPlaying) {
+            this.isDestroyed = true;
+            return;
+        }
+        this.stop();
+        super.destroy();
+    }
+}
+Nodes['audio-player'] = AudioPlayer;
+//# sourceMappingURL=audio-player.js.map

package/dist/nodes/audio-player.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-player.js","sourceRoot":"","sources":["../../src/nodes/audio-player.ts"],"names":[],"mappings":"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"}

package/dist/nodes/group.d.ts

@@ -0,0 +1,55 @@
+import { Node, type NodeOptions } from './_node.js';
+import { PrimaryNode } from './lib/enum.js';
+/**
+ * Options for the `Group` node.
+ */
+export interface GroupOptions extends NodeOptions<PrimaryNode.Group> {
+}
+/**
+ * The **`Group`** node is a lightweight container for organizing child nodes
+ * without spatial positioning. Unlike `Transform`, it does not manage position,
+ * rotation, or scale — it purely serves as a logical grouping mechanism.
+ *
+ * Use `Group` when you need to:
+ * - Batch-destroy a set of nodes by destroying the parent
+ * - Organize nodes in the hierarchy without affecting their position
+ * - Apply `deltaIncrease` to a subset of nodes
+ * - Attach a script to a group of nodes
+ *
+ * For nodes that need spatial positioning, use `Transform` instead.
+ *
+ * @example
+ * ```tsx
+ * import { useNode } from 'dinix/hooks'
+ * import { PrimaryNode } from 'dinix/nodes/enum'
+ *
+ * function EnemySpawner() {
+ *   const enemies = useNode(PrimaryNode.Group)
+ *
+ *   useMount(() => {
+ *     // All enemies are children of the group
+ *     // Destroying the group destroys all enemies
+ *   })
+ *
+ *   return (
+ *     <group ref={enemies}>
+ *       <Enemy position={[0, 0]} />
+ *       <Enemy position={[50, 0]} />
+ *     </group>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Slowing down a subset of nodes
+ * <group deltaIncrease={0.5}>
+ *   <SlowEnemy />
+ *   <SlowProjectile />
+ * </group>
+ * ```
+ */
+export declare class Group extends Node<PrimaryNode.Group> {
+    constructor(options: GroupOptions);
+}
+//# sourceMappingURL=group.d.ts.map

package/dist/nodes/group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group.d.ts","sourceRoot":"","sources":["../../src/nodes/group.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAA;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAG3C;;GAEG;AACH,MAAM,WAAW,YAAa,SAAQ,WAAW,CAAC,WAAW,CAAC,KAAK,CAAC;CAAG;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qBAAa,KAAM,SAAQ,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC;gBACpC,OAAO,EAAE,YAAY;CAGlC"}

package/dist/nodes/group.js

@@ -0,0 +1,54 @@
+import { Node } from './_node.js';
+import { PrimaryNode } from './lib/enum.js';
+import { Nodes } from './lib/registry.js';
+/**
+ * The **`Group`** node is a lightweight container for organizing child nodes
+ * without spatial positioning. Unlike `Transform`, it does not manage position,
+ * rotation, or scale — it purely serves as a logical grouping mechanism.
+ *
+ * Use `Group` when you need to:
+ * - Batch-destroy a set of nodes by destroying the parent
+ * - Organize nodes in the hierarchy without affecting their position
+ * - Apply `deltaIncrease` to a subset of nodes
+ * - Attach a script to a group of nodes
+ *
+ * For nodes that need spatial positioning, use `Transform` instead.
+ *
+ * @example
+ * ```tsx
+ * import { useNode } from 'dinix/hooks'
+ * import { PrimaryNode } from 'dinix/nodes/enum'
+ *
+ * function EnemySpawner() {
+ *   const enemies = useNode(PrimaryNode.Group)
+ *
+ *   useMount(() => {
+ *     // All enemies are children of the group
+ *     // Destroying the group destroys all enemies
+ *   })
+ *
+ *   return (
+ *     <group ref={enemies}>
+ *       <Enemy position={[0, 0]} />
+ *       <Enemy position={[50, 0]} />
+ *     </group>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Slowing down a subset of nodes
+ * <group deltaIncrease={0.5}>
+ *   <SlowEnemy />
+ *   <SlowProjectile />
+ * </group>
+ * ```
+ */
+export class Group extends Node {
+    constructor(options) {
+        super(PrimaryNode.Group, options);
+    }
+}
+Nodes.group = Group;
+//# sourceMappingURL=group.js.map