cubeforge 0.3.15 → 0.3.16

package/dist/index.d.ts

@@ -3,8 +3,8 @@ import * as React from 'react';
 import React__default, { CSSProperties, ReactNode, ReactElement } from 'react';
 import { Plugin, EntityId, ECSWorld, ScriptUpdateFn, NavGrid, WorldSnapshot, EventBus } from '@cubeforge/core';
 export { AssetProgress, Component, ECSWorld, Ease, EntityId, GameTimer, HotReloadablePlugin, MergedRect, NavGrid, Plugin, PreloadManifest, ScriptUpdateFn, TimelineEntry, TransformComponent, TweenHandle, TweenTimeline, Vec2Like, WorldSnapshot, arrive, createTag, createTimeline, createTimer, createTransform, definePlugin, findByTag, flee, hotReloadPlugin, mergeTileColliders, patrol, preloadManifest, seek, tween, wander } from '@cubeforge/core';
-import { Sampling, BlendMode, PostProcessEffect } from '@cubeforge/renderer';
-export { AnimationStateComponent, BlendMode, MagFilterValue, NineSliceComponent, ParallaxLayerComponent, Particle, ParticlePoolComponent, PostProcessEffect, PostProcessStack, RenderLayer, RenderLayerManager, RenderSystem, Sampling, SpriteComponent, SquashStretchComponent, TextComponent, TextureFilter, TextureFilterValue, TrailComponent, chromaticAberrationEffect, createNineSlice, createPostProcessStack, createRenderLayerManager, createSprite, defaultLayers, scanlineEffect, vignetteEffect } from '@cubeforge/renderer';
+import { Sampling, BlendMode, AnimatorStateDefinition, AnimatorParamValue, PostProcessEffect } from '@cubeforge/renderer';
+export { AnimationClipDefinition, AnimationStateComponent, AnimatorComponent, AnimatorCondition, AnimatorParamValue, AnimatorStateDefinition, AnimatorTransition, BlendMode, MagFilterValue, NineSliceComponent, ParallaxLayerComponent, Particle, ParticlePoolComponent, PostProcessEffect, PostProcessStack, RenderLayer, RenderLayerManager, RenderSystem, Sampling, SpriteComponent, SquashStretchComponent, TextComponent, TextureFilter, TextureFilterValue, TrailComponent, chromaticAberrationEffect, createNineSlice, createPostProcessStack, createRenderLayerManager, createSprite, defaultLayers, scanlineEffect, vignetteEffect } from '@cubeforge/renderer';
 import { ColliderShape } from '@cubeforge/physics';
 export { BoxColliderComponent, CapsuleColliderComponent, CircleColliderComponent, ColliderShape, CompoundColliderComponent, RaycastHit, RigidBodyComponent, createCompoundCollider, overlapBox, overlapCircle, raycast, raycastAll, sweepBox } from '@cubeforge/physics';
 import { InputManager, ActionBindings, InputContextName, PlayerInput, InputRecorderControls } from '@cubeforge/input';
@@ -376,6 +376,14 @@ declare function defineAnimations<S extends string>(clips: Record<S, AnimationCl
  */
 declare function AnimatedSprite<S extends string>(props: AnimatedSpriteProps<S>): ReactElement;
 
+interface AnimatorProps {
+    initial: string;
+    states: Record<string, AnimatorStateDefinition>;
+    params?: Record<string, AnimatorParamValue>;
+    playing?: boolean;
+}
+declare function Animator({ initial, states, params, playing }: AnimatorProps): null;
+
 interface SquashStretchProps {
     /** How much to squash/stretch (default 0.2) */
     intensity?: number;
@@ -1122,6 +1130,10 @@ declare function useProfiler(): ProfilerData;
  */
 declare function usePostProcess(effect: PostProcessEffect): void;
 
+declare function playClip(world: ECSWorld, entityId: EntityId, clipName: string): void;
+declare function setAnimationState(world: ECSWorld, entityId: EntityId, stateName: string): void;
+declare function setAnimatorParam(world: ECSWorld, entityId: EntityId, name: string, value: AnimatorParamValue): void;
+
 /**
  * Define a reusable entity prefab with default props.
  *
@@ -1147,4 +1159,4 @@ declare function usePostProcess(effect: PostProcessEffect): void;
  */
 declare function definePrefab<D extends Record<string, unknown>>(name: string, defaults: D, render: (props: D) => ReactElement): React__default.FC<Partial<D>>;
 
-export { AnimatedSprite, type AnimatedSpriteProps, Animation, type AnimationSet, AssetLoader, type BoundInputMap, BoxCollider, Camera2D, type CameraControls, CameraZone, CapsuleCollider, Checkpoint, CircleCollider, CompoundCollider, type CoordinateHelpers, Entity, Game, type GameControls, type GamepadState, type InputContextControls, MovingPlatform, NineSlice, ParallaxLayer, ParticleEmitter, type ParticlePreset, type PauseControls, type PreloadState, type ProfilerData, RigidBody, ScreenFlash, type ScreenFlashHandle, Script, type SnapshotControls, Sprite, type SpriteAtlas, SquashStretch, Text, type TiledLayer, type TiledObject, Tilemap, Trail, Transform, type VirtualInputState, VirtualJoystick, type VirtualJoystickProps, World, createAtlas, defineAnimations, definePrefab, useCamera, useCoordinates, useDestroyEntity, useEntity, useEvent, useEvents, useGame, useGamepad, useInput, useInputContext, useInputMap, useInputRecorder, useLocalMultiplayer, usePause, usePlayerInput, usePostProcess, usePreload, useProfiler, useSnapshot, useVirtualInput };
+export { AnimatedSprite, type AnimatedSpriteProps, Animation, type AnimationSet, Animator, AssetLoader, type BoundInputMap, BoxCollider, Camera2D, type CameraControls, CameraZone, CapsuleCollider, Checkpoint, CircleCollider, CompoundCollider, type CoordinateHelpers, Entity, Game, type GameControls, type GamepadState, type InputContextControls, MovingPlatform, NineSlice, ParallaxLayer, ParticleEmitter, type ParticlePreset, type PauseControls, type PreloadState, type ProfilerData, RigidBody, ScreenFlash, type ScreenFlashHandle, Script, type SnapshotControls, Sprite, type SpriteAtlas, SquashStretch, Text, type TiledLayer, type TiledObject, Tilemap, Trail, Transform, type VirtualInputState, VirtualJoystick, type VirtualJoystickProps, World, createAtlas, defineAnimations, definePrefab, playClip, setAnimationState, setAnimatorParam, useCamera, useCoordinates, useDestroyEntity, useEntity, useEvent, useEvents, useGame, useGamepad, useInput, useInputContext, useInputMap, useInputRecorder, useLocalMultiplayer, usePause, usePlayerInput, usePostProcess, usePreload, useProfiler, useSnapshot, useVirtualInput };

package/dist/index.js

@@ -2126,9 +2126,47 @@ var RenderSystem = class {
       camY = cam.y;
       zoom = cam.zoom;
     }
+    for (const id of world.query("Animator", "AnimationState")) {
+      const animator = world.getComponent(id, "Animator");
+      const anim = world.getComponent(id, "AnimationState");
+      if (!animator.playing) continue;
+      if (!animator.states[animator.currentState]) {
+        animator.currentState = animator.initialState;
+        animator._entered = false;
+      }
+      const stateDef = animator.states[animator.currentState];
+      if (!stateDef) continue;
+      if (!animator._entered) {
+        anim.currentClip = stateDef.clip;
+        animator._entered = true;
+        stateDef.onEnter?.();
+      }
+      if (stateDef.transitions && stateDef.transitions.length > 0) {
+        const sorted = [...stateDef.transitions].sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+        for (const trans of sorted) {
+          if (trans.exitTime != null && anim.frames.length > 0) {
+            const progress = anim.currentIndex / anim.frames.length;
+            if (progress < trans.exitTime) continue;
+          }
+          if (evaluateConditions(trans.when, animator.params)) {
+            stateDef.onExit?.();
+            animator.currentState = trans.to;
+            animator._entered = false;
+            break;
+          }
+        }
+      }
+    }
     for (const id of world.query("AnimationState", "Sprite")) {
       const anim = world.getComponent(id, "AnimationState");
       const sprite = world.getComponent(id, "Sprite");
+      if (anim.clips && anim.currentClip && anim._resolvedClip !== anim.currentClip) {
+        const clip = anim.clips[anim.currentClip];
+        if (clip) {
+          resolveClip(anim, clip);
+          anim._resolvedClip = anim.currentClip;
+        }
+      }
       if (!anim.playing || anim.frames.length === 0) continue;
       anim.timer += dt;
       const frameDuration = 1 / anim.fps;
@@ -2136,8 +2174,24 @@ var RenderSystem = class {
         anim.timer -= frameDuration;
         anim.currentIndex++;
         if (anim.currentIndex >= anim.frames.length) {
-          anim.currentIndex = anim.loop ? 0 : anim.frames.length - 1;
+          if (anim.loop) {
+            anim.currentIndex = 0;
+          } else {
+            anim.currentIndex = anim.frames.length - 1;
+            anim.playing = false;
+            if (anim.onComplete && !anim._completed) {
+              anim._completed = true;
+              anim.onComplete();
+            }
+            if (anim.clips && anim.currentClip) {
+              const currentClipDef = anim.clips[anim.currentClip];
+              if (currentClipDef?.next && anim.clips[currentClipDef.next]) {
+                anim.currentClip = currentClipDef.next;
+              }
+            }
+          }
         }
+        anim.frameEvents?.[anim.currentIndex]?.();
       }
       sprite.frameIndex = anim.frames[anim.currentIndex];
     }
@@ -2552,31 +2606,44 @@ var RenderSystem = class {
     this.lastTimestamp = now;
   }
 };
-
-// ../../packages/renderer/src/canvas2d.ts
-var Canvas2DRenderer = class {
-  constructor(canvas) {
-    this.canvas = canvas;
-    const ctx = canvas.getContext("2d");
-    if (!ctx) throw new Error("Could not get 2D context from canvas");
-    this.ctx = ctx;
-  }
-  ctx;
-  clear(color) {
-    if (color) {
-      this.ctx.fillStyle = color;
-      this.ctx.fillRect(0, 0, this.canvas.width, this.canvas.height);
-    } else {
-      this.ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
+function resolveClip(anim, clip) {
+  anim.frames = clip.frames;
+  anim.fps = clip.fps ?? 12;
+  anim.loop = clip.loop ?? true;
+  anim.onComplete = clip.onComplete;
+  anim.frameEvents = clip.frameEvents;
+  anim.currentIndex = 0;
+  anim.timer = 0;
+  anim._completed = false;
+  anim.playing = true;
+}
+function evaluateConditions(conditions, params) {
+  for (const cond of conditions) {
+    const val = params[cond.param];
+    if (val === void 0) return false;
+    switch (cond.op) {
+      case "==":
+        if (val !== cond.value) return false;
+        break;
+      case "!=":
+        if (val === cond.value) return false;
+        break;
+      case ">":
+        if (val <= cond.value) return false;
+        break;
+      case ">=":
+        if (val < cond.value) return false;
+        break;
+      case "<":
+        if (val >= cond.value) return false;
+        break;
+      case "<=":
+        if (val > cond.value) return false;
+        break;
     }
   }
-  get width() {
-    return this.canvas.width;
-  }
-  get height() {
-    return this.canvas.height;
-  }
-};
+  return true;
+}
 
 // ../../packages/renderer/src/postProcess.ts
 function createPostProcessStack() {
@@ -2644,6 +2711,31 @@ function chromaticAberrationEffect(offset = 2) {
   };
 }
 
+// ../../packages/renderer/src/canvas2d.ts
+var Canvas2DRenderer = class {
+  constructor(canvas) {
+    this.canvas = canvas;
+    const ctx = canvas.getContext("2d");
+    if (!ctx) throw new Error("Could not get 2D context from canvas");
+    this.ctx = ctx;
+  }
+  ctx;
+  clear(color) {
+    if (color) {
+      this.ctx.fillStyle = color;
+      this.ctx.fillRect(0, 0, this.canvas.width, this.canvas.height);
+    } else {
+      this.ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
+    }
+  }
+  get width() {
+    return this.canvas.width;
+  }
+  get height() {
+    return this.canvas.height;
+  }
+};
+
 // ../../packages/physics/src/components/rigidbody.ts
 function createRigidBody(opts) {
   return {
@@ -5335,7 +5427,7 @@ function Animation({ frames, fps = 12, loop = true, playing = true, onComplete,
 }
 
 // src/components/AnimatedSprite.tsx
-import { useMemo } from "react";
+import { useEffect as useEffect18, useContext as useContext16 } from "react";
 import { Fragment as Fragment3, jsx as jsx5, jsxs as jsxs3 } from "react/jsx-runtime";
 function defineAnimations(clips) {
   return clips;
@@ -5366,72 +5458,130 @@ function AnimatedSprite(props) {
     sampling,
     blendMode
   } = props;
-  const animProps = useResolvedAnimation(props);
+  const spriteEl = /* @__PURE__ */ jsx5(
+    Sprite,
+    {
+      width,
+      height,
+      src,
+      color,
+      offsetX,
+      offsetY,
+      zIndex,
+      visible,
+      flipX,
+      flipY,
+      anchorX,
+      anchorY,
+      frameWidth,
+      frameHeight,
+      frameColumns,
+      atlas,
+      frame,
+      tileX,
+      tileY,
+      tileSizeX,
+      tileSizeY,
+      sampling,
+      blendMode
+    }
+  );
+  if (props.animations) {
+    return /* @__PURE__ */ jsxs3(Fragment3, { children: [
+      spriteEl,
+      /* @__PURE__ */ jsx5(
+        MultiClipAnimation,
+        {
+          animations: props.animations,
+          current: props.current
+        }
+      )
+    ] });
+  }
   return /* @__PURE__ */ jsxs3(Fragment3, { children: [
+    spriteEl,
     /* @__PURE__ */ jsx5(
-      Sprite,
+      Animation,
       {
-        width,
-        height,
-        src,
-        color,
-        offsetX,
-        offsetY,
-        zIndex,
-        visible,
-        flipX,
-        flipY,
-        anchorX,
-        anchorY,
-        frameWidth,
-        frameHeight,
-        frameColumns,
-        atlas,
-        frame,
-        tileX,
-        tileY,
-        tileSizeX,
-        tileSizeY,
-        sampling,
-        blendMode
+        frames: props.frames,
+        fps: props.fps,
+        loop: props.loop,
+        playing: props.playing,
+        onComplete: props.onComplete,
+        frameEvents: props.frameEvents
       }
-    ),
-    /* @__PURE__ */ jsx5(Animation, { ...animProps })
+    )
   ] });
 }
-function useResolvedAnimation(props) {
-  const clip = props.animations ? props.animations[props.current] ?? Object.values(props.animations)[0] : null;
-  const frames = useMemo(
-    () => clip ? clip.frames : props.frames,
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [clip ? props.current : props.frames]
-  );
-  if (clip) {
-    return {
-      frames,
-      fps: clip.fps,
-      loop: clip.loop,
+function MultiClipAnimation({ animations, current }) {
+  const engine = useContext16(EngineContext);
+  const entityId = useContext16(EntityContext);
+  useEffect18(() => {
+    const clip = animations[current] ?? Object.values(animations)[0];
+    const state = {
+      type: "AnimationState",
+      clips: animations,
+      currentClip: current,
+      _resolvedClip: current,
+      frames: clip.frames,
+      fps: clip.fps ?? 12,
+      loop: clip.loop ?? true,
       playing: true,
-      onComplete: clip.onComplete,
-      frameEvents: void 0
+      currentIndex: 0,
+      timer: 0,
+      _completed: false,
+      onComplete: clip.onComplete
     };
-  }
-  return {
-    frames,
-    fps: props.fps,
-    loop: props.loop,
-    playing: props.playing,
-    onComplete: props.onComplete,
-    frameEvents: props.frameEvents
-  };
+    engine.ecs.addComponent(entityId, state);
+    return () => engine.ecs.removeComponent(entityId, "AnimationState");
+  }, []);
+  useEffect18(() => {
+    const anim = engine.ecs.getComponent(entityId, "AnimationState");
+    if (!anim) return;
+    anim.clips = animations;
+    anim.currentClip = current;
+  }, [current, animations, engine, entityId]);
+  return null;
+}
+
+// src/components/Animator.tsx
+import { useEffect as useEffect19, useContext as useContext17 } from "react";
+function Animator({ initial, states, params = {}, playing = true }) {
+  const engine = useContext17(EngineContext);
+  const entityId = useContext17(EntityContext);
+  useEffect19(() => {
+    const comp = {
+      type: "Animator",
+      initialState: initial,
+      currentState: initial,
+      states,
+      params: { ...params },
+      playing,
+      _entered: false
+    };
+    engine.ecs.addComponent(entityId, comp);
+    return () => engine.ecs.removeComponent(entityId, "Animator");
+  }, []);
+  useEffect19(() => {
+    const comp = engine.ecs.getComponent(entityId, "Animator");
+    if (!comp) return;
+    Object.assign(comp.params, params);
+    comp.playing = playing;
+  }, [params, playing, engine, entityId]);
+  useEffect19(() => {
+    const comp = engine.ecs.getComponent(entityId, "Animator");
+    if (!comp) return;
+    comp.states = states;
+  }, [states, engine, entityId]);
+  return null;
 }
 
 // src/components/SquashStretch.tsx
-import { useEffect as useEffect18, useContext as useContext16 } from "react";
+import { useEffect as useEffect20, useContext as useContext18 } from "react";
 function SquashStretch({ intensity = 0.2, recovery = 8 }) {
-  const engine = useContext16(EngineContext);
-  const entityId = useContext16(EntityContext);
-  useEffect18(() => {
+  const engine = useContext18(EngineContext);
+  const entityId = useContext18(EntityContext);
+  useEffect20(() => {
     engine.ecs.addComponent(entityId, {
       type: "SquashStretch",
       intensity,
@@ -5445,7 +5595,7 @@ function SquashStretch({ intensity = 0.2, recovery = 8 }) {
 }
 
 // src/components/ParticleEmitter.tsx
-import { useEffect as useEffect19, useContext as useContext17 } from "react";
+import { useEffect as useEffect21, useContext as useContext19 } from "react";
 
 // src/components/particlePresets.ts
 var PARTICLE_PRESETS = {
@@ -5535,9 +5685,9 @@ function ParticleEmitter({
   const resolvedColor = color ?? presetConfig.color ?? "#ffffff";
   const resolvedGravity = gravity ?? presetConfig.gravity ?? 200;
   const resolvedMaxParticles = maxParticles ?? presetConfig.maxParticles ?? 100;
-  const engine = useContext17(EngineContext);
-  const entityId = useContext17(EntityContext);
-  useEffect19(() => {
+  const engine = useContext19(EngineContext);
+  const entityId = useContext19(EntityContext);
+  useEffect21(() => {
     engine.ecs.addComponent(entityId, {
       type: "ParticlePool",
       particles: [],
@@ -5560,7 +5710,7 @@ function ParticleEmitter({
     });
     return () => engine.ecs.removeComponent(entityId, "ParticlePool");
   }, []);
-  useEffect19(() => {
+  useEffect21(() => {
     const pool = engine.ecs.getComponent(entityId, "ParticlePool");
     if (!pool) return;
     pool.active = active;
@@ -5794,7 +5944,7 @@ function Checkpoint({
 }
 
 // src/components/Tilemap.tsx
-import { useEffect as useEffect20, useState as useState5, useContext as useContext18 } from "react";
+import { useEffect as useEffect22, useState as useState5, useContext as useContext20 } from "react";
 import { Fragment as Fragment5, jsx as jsx9 } from "react/jsx-runtime";
 var animatedTiles = /* @__PURE__ */ new Map();
 function getProperty(props, name) {
@@ -5820,9 +5970,9 @@ function Tilemap({
   navGrid,
   mergeColliders = true
 }) {
-  const engine = useContext18(EngineContext);
+  const engine = useContext20(EngineContext);
   const [spawnedNodes, setSpawnedNodes] = useState5([]);
-  useEffect20(() => {
+  useEffect22(() => {
     if (!engine) return;
     const createdEntities = [];
     async function load() {
@@ -6035,7 +6185,7 @@ function Tilemap({
 }
 
 // src/components/ParallaxLayer.tsx
-import { useEffect as useEffect21, useContext as useContext19 } from "react";
+import { useEffect as useEffect23, useContext as useContext21 } from "react";
 import { jsx as jsx10, jsxs as jsxs7 } from "react/jsx-runtime";
 function ParallaxLayerInner({
   src,
@@ -6047,9 +6197,9 @@ function ParallaxLayerInner({
   offsetX,
   offsetY
 }) {
-  const engine = useContext19(EngineContext);
-  const entityId = useContext19(EntityContext);
-  useEffect21(() => {
+  const engine = useContext21(EngineContext);
+  const entityId = useContext21(EntityContext);
+  useEffect23(() => {
     engine.ecs.addComponent(entityId, {
       type: "ParallaxLayer",
       src,
@@ -6065,7 +6215,7 @@ function ParallaxLayerInner({
     });
     return () => engine.ecs.removeComponent(entityId, "ParallaxLayer");
   }, []);
-  useEffect21(() => {
+  useEffect23(() => {
     const layer = engine.ecs.getComponent(entityId, "ParallaxLayer");
     if (!layer) return;
     layer.src = src;
@@ -6147,7 +6297,7 @@ var ScreenFlash = forwardRef((_, ref) => {
 ScreenFlash.displayName = "ScreenFlash";
 
 // src/components/CameraZone.tsx
-import { useEffect as useEffect22, useContext as useContext20, useRef as useRef8 } from "react";
+import { useEffect as useEffect24, useContext as useContext22, useRef as useRef8 } from "react";
 import { Fragment as Fragment6, jsx as jsx12 } from "react/jsx-runtime";
 function CameraZone({
   x,
@@ -6159,10 +6309,10 @@ function CameraZone({
   targetY,
   children
 }) {
-  const engine = useContext20(EngineContext);
+  const engine = useContext22(EngineContext);
   const prevFollowRef = useRef8(void 0);
   const activeRef = useRef8(false);
-  useEffect22(() => {
+  useEffect24(() => {
     const eid = engine.ecs.createEntity();
     engine.ecs.addComponent(eid, createScript(() => {
       const cam = engine.ecs.queryOne("Camera2D");
@@ -6209,11 +6359,11 @@ function CameraZone({
 }
 
 // src/components/Trail.tsx
-import { useEffect as useEffect23, useContext as useContext21 } from "react";
+import { useEffect as useEffect25, useContext as useContext23 } from "react";
 function Trail({ length = 20, color = "#ffffff", width = 3 }) {
-  const engine = useContext21(EngineContext);
-  const entityId = useContext21(EntityContext);
-  useEffect23(() => {
+  const engine = useContext23(EngineContext);
+  const entityId = useContext23(EntityContext);
+  useEffect25(() => {
     engine.ecs.addComponent(entityId, createTrail({ length, color, width }));
     return () => engine.ecs.removeComponent(entityId, "Trail");
   }, []);
@@ -6221,7 +6371,7 @@ function Trail({ length = 20, color = "#ffffff", width = 3 }) {
 }
 
 // src/components/NineSlice.tsx
-import { useEffect as useEffect24, useContext as useContext22 } from "react";
+import { useEffect as useEffect26, useContext as useContext24 } from "react";
 function NineSlice({
   src,
   width,
@@ -6232,9 +6382,9 @@ function NineSlice({
   borderLeft = 8,
   zIndex = 0
 }) {
-  const engine = useContext22(EngineContext);
-  const entityId = useContext22(EntityContext);
-  useEffect24(() => {
+  const engine = useContext24(EngineContext);
+  const entityId = useContext24(EntityContext);
+  useEffect26(() => {
     engine.ecs.addComponent(
       entityId,
       createNineSlice(src, width, height, {
@@ -6251,14 +6401,14 @@ function NineSlice({
 }
 
 // src/components/AssetLoader.tsx
-import { useEffect as useEffect26 } from "react";
+import { useEffect as useEffect28 } from "react";
 
 // src/hooks/usePreload.ts
-import { useState as useState6, useEffect as useEffect25, useContext as useContext23 } from "react";
+import { useState as useState6, useEffect as useEffect27, useContext as useContext25 } from "react";
 function usePreload(assets) {
-  const engine = useContext23(EngineContext);
+  const engine = useContext25(EngineContext);
   const [state, setState] = useState6({ progress: assets.length === 0 ? 1 : 0, loaded: assets.length === 0, error: null });
-  useEffect25(() => {
+  useEffect27(() => {
     if (assets.length === 0) {
       setState({ progress: 1, loaded: true, error: null });
       return;
@@ -6289,7 +6439,7 @@ function usePreload(assets) {
 import { Fragment as Fragment7, jsx as jsx13 } from "react/jsx-runtime";
 function AssetLoader({ assets, fallback = null, onError, children }) {
   const { loaded, error } = usePreload(assets);
-  useEffect26(() => {
+  useEffect28(() => {
     if (error && onError) onError(error);
   }, [error, onError]);
   if (!loaded) {
@@ -6299,18 +6449,18 @@ function AssetLoader({ assets, fallback = null, onError, children }) {
 }
 
 // src/hooks/useGame.ts
-import { useContext as useContext24 } from "react";
+import { useContext as useContext26 } from "react";
 function useGame() {
-  const engine = useContext24(EngineContext);
+  const engine = useContext26(EngineContext);
   if (!engine) throw new Error("useGame must be used inside <Game>");
   return engine;
 }
 
 // src/hooks/useCamera.ts
-import { useMemo as useMemo2 } from "react";
+import { useMemo } from "react";
 function useCamera() {
   const engine = useGame();
-  return useMemo2(() => ({
+  return useMemo(() => ({
     shake(intensity, duration) {
       const cams = engine.ecs.query("Camera2D");
       if (cams.length === 0) return;
@@ -6348,28 +6498,28 @@ function useCamera() {
 }
 
 // src/hooks/useSnapshot.ts
-import { useMemo as useMemo3 } from "react";
+import { useMemo as useMemo2 } from "react";
 function useSnapshot() {
   const engine = useGame();
-  return useMemo3(() => ({
+  return useMemo2(() => ({
     save: () => engine.ecs.getSnapshot(),
     restore: (snapshot) => engine.ecs.restoreSnapshot(snapshot)
   }), [engine]);
 }
 
 // src/hooks/useEntity.ts
-import { useContext as useContext25 } from "react";
+import { useContext as useContext27 } from "react";
 function useEntity() {
-  const id = useContext25(EntityContext);
+  const id = useContext27(EntityContext);
   if (id === null) throw new Error("useEntity must be used inside <Entity>");
   return id;
 }
 
 // src/hooks/useDestroyEntity.ts
-import { useCallback as useCallback2, useContext as useContext26 } from "react";
+import { useCallback as useCallback2, useContext as useContext28 } from "react";
 function useDestroyEntity() {
-  const engine = useContext26(EngineContext);
-  const entityId = useContext26(EntityContext);
+  const engine = useContext28(EngineContext);
+  const entityId = useContext28(EntityContext);
   if (!engine) throw new Error("useDestroyEntity must be used inside <Game>");
   if (entityId === null) throw new Error("useDestroyEntity must be used inside <Entity>");
   return useCallback2(() => {
@@ -6380,19 +6530,19 @@ function useDestroyEntity() {
 }
 
 // src/hooks/useInput.ts
-import { useContext as useContext27 } from "react";
+import { useContext as useContext29 } from "react";
 function useInput() {
-  const engine = useContext27(EngineContext);
+  const engine = useContext29(EngineContext);
   if (!engine) throw new Error("useInput must be used inside <Game>");
   return engine.input;
 }
 
 // src/hooks/useInputMap.ts
-import { useMemo as useMemo4 } from "react";
+import { useMemo as useMemo3 } from "react";
 function useInputMap(bindings) {
   const input = useInput();
-  const map = useMemo4(() => createInputMap(bindings), [JSON.stringify(bindings)]);
-  return useMemo4(() => ({
+  const map = useMemo3(() => createInputMap(bindings), [JSON.stringify(bindings)]);
+  return useMemo3(() => ({
     isActionDown: (action) => map.isActionDown(input, action),
     isActionPressed: (action) => map.isActionPressed(input, action),
     isActionReleased: (action) => map.isActionReleased(input, action),
@@ -6402,9 +6552,9 @@ function useInputMap(bindings) {
 }
 
 // src/hooks/useEvents.ts
-import { useContext as useContext28, useEffect as useEffect27, useRef as useRef9 } from "react";
+import { useContext as useContext30, useEffect as useEffect29, useRef as useRef9 } from "react";
 function useEvents() {
-  const engine = useContext28(EngineContext);
+  const engine = useContext30(EngineContext);
   if (!engine) throw new Error("useEvents must be used inside <Game>");
   return engine.events;
 }
@@ -6412,15 +6562,15 @@ function useEvent(event, handler) {
   const events = useEvents();
   const handlerRef = useRef9(handler);
   handlerRef.current = handler;
-  useEffect27(() => {
+  useEffect29(() => {
     return events.on(event, (data) => handlerRef.current(data));
   }, [events, event]);
 }
 
 // src/hooks/useCoordinates.ts
-import { useCallback as useCallback3, useContext as useContext29 } from "react";
+import { useCallback as useCallback3, useContext as useContext31 } from "react";
 function useCoordinates() {
-  const engine = useContext29(EngineContext);
+  const engine = useContext31(EngineContext);
   const worldToScreen = useCallback3((wx, wy) => {
     const canvas = engine.canvas;
     const camId = engine.ecs.queryOne("Camera2D");
@@ -6447,14 +6597,14 @@ function useCoordinates() {
 }
 
 // src/hooks/useInputContext.ts
-import { useEffect as useEffect28, useMemo as useMemo5 } from "react";
+import { useEffect as useEffect30, useMemo as useMemo4 } from "react";
 function useInputContext(ctx) {
-  useEffect28(() => {
+  useEffect30(() => {
     if (!ctx) return;
     globalInputContext.push(ctx);
     return () => globalInputContext.pop(ctx);
   }, [ctx]);
-  return useMemo5(() => ({
+  return useMemo4(() => ({
     push: (c) => globalInputContext.push(c),
     pop: (c) => globalInputContext.pop(c),
     get active() {
@@ -6464,17 +6614,17 @@ function useInputContext(ctx) {
 }
 
 // src/hooks/usePlayerInput.ts
-import { useMemo as useMemo6 } from "react";
+import { useMemo as useMemo5 } from "react";
 function usePlayerInput(playerId, bindings) {
   const input = useInput();
-  return useMemo6(() => createPlayerInput(playerId, bindings, input), [playerId, input, JSON.stringify(bindings)]);
+  return useMemo5(() => createPlayerInput(playerId, bindings, input), [playerId, input, JSON.stringify(bindings)]);
 }
 
 // src/hooks/useLocalMultiplayer.ts
-import { useMemo as useMemo7 } from "react";
+import { useMemo as useMemo6 } from "react";
 function useLocalMultiplayer(bindingsPerPlayer) {
   const input = useInput();
-  return useMemo7(
+  return useMemo6(
     () => bindingsPerPlayer.map((bindings, i) => createPlayerInput(i + 1, bindings, input)),
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [input, JSON.stringify(bindingsPerPlayer)]
@@ -6482,18 +6632,18 @@ function useLocalMultiplayer(bindingsPerPlayer) {
 }
 
 // src/hooks/useInputRecorder.ts
-import { useMemo as useMemo8 } from "react";
+import { useMemo as useMemo7 } from "react";
 function useInputRecorder() {
-  return useMemo8(() => createInputRecorder(), []);
+  return useMemo7(() => createInputRecorder(), []);
 }
 
 // src/hooks/useGamepad.ts
-import { useEffect as useEffect29, useRef as useRef10, useState as useState7 } from "react";
+import { useEffect as useEffect31, useRef as useRef10, useState as useState7 } from "react";
 var EMPTY_STATE = { connected: false, axes: [], buttons: [] };
 function useGamepad(playerIndex = 0) {
   const [state, setState] = useState7(EMPTY_STATE);
   const rafRef = useRef10(0);
-  useEffect29(() => {
+  useEffect31(() => {
     const poll = () => {
       const gp = navigator.getGamepads()[playerIndex];
       if (gp) {
@@ -6514,9 +6664,9 @@ function useGamepad(playerIndex = 0) {
 }
 
 // src/hooks/usePause.ts
-import { useContext as useContext30, useState as useState8, useCallback as useCallback4 } from "react";
+import { useContext as useContext32, useState as useState8, useCallback as useCallback4 } from "react";
 function usePause() {
-  const engine = useContext30(EngineContext);
+  const engine = useContext32(EngineContext);
   const [paused, setPaused] = useState8(false);
   const pause = useCallback4(() => {
     engine.loop.pause();
@@ -6534,7 +6684,7 @@ function usePause() {
 }
 
 // src/hooks/useProfiler.ts
-import { useContext as useContext31, useEffect as useEffect30, useRef as useRef11, useState as useState9 } from "react";
+import { useContext as useContext33, useEffect as useEffect32, useRef as useRef11, useState as useState9 } from "react";
 var EMPTY = {
   fps: 0,
   frameTime: 0,
@@ -6542,12 +6692,12 @@ var EMPTY = {
   systemTimings: /* @__PURE__ */ new Map()
 };
 function useProfiler() {
-  const engine = useContext31(EngineContext);
+  const engine = useContext33(EngineContext);
   const [data, setData] = useState9(EMPTY);
   const frameTimesRef = useRef11([]);
   const lastUpdateRef = useRef11(0);
   const prevTimeRef = useRef11(0);
-  useEffect30(() => {
+  useEffect32(() => {
     if (!engine) return;
     let rafId;
     const frameTimes = frameTimesRef.current;
@@ -6587,10 +6737,10 @@ function useProfiler() {
 }
 
 // src/hooks/usePostProcess.ts
-import { useEffect as useEffect31 } from "react";
+import { useEffect as useEffect33 } from "react";
 function usePostProcess(effect) {
   const engine = useGame();
-  useEffect31(() => {
+  useEffect33(() => {
     engine.postProcessStack.add(effect);
     return () => {
       engine.postProcessStack.remove(effect);
@@ -6650,19 +6800,19 @@ function useAISteering() {
 }
 
 // ../gameplay/src/hooks/useDamageZone.ts
-import { useContext as useContext32 } from "react";
+import { useContext as useContext34 } from "react";
 function useDamageZone(damage, opts = {}) {
-  const engine = useContext32(EngineContext);
+  const engine = useContext34(EngineContext);
   useTriggerEnter((other) => {
     engine.events.emit(`damage:${other}`, { amount: damage });
   }, { tag: opts.tag, layer: opts.layer });
 }
 
 // ../gameplay/src/hooks/useDropThrough.ts
-import { useContext as useContext33, useCallback as useCallback7 } from "react";
+import { useContext as useContext35, useCallback as useCallback7 } from "react";
 function useDropThrough(frames = 8) {
-  const engine = useContext33(EngineContext);
-  const entityId = useContext33(EntityContext);
+  const engine = useContext35(EngineContext);
+  const entityId = useContext35(EntityContext);
   const dropThrough = useCallback7(() => {
     const rb = engine.ecs.getComponent(entityId, "RigidBody");
     if (rb) rb.dropThrough = frames;
@@ -6671,14 +6821,14 @@ function useDropThrough(frames = 8) {
 }
 
 // ../gameplay/src/hooks/useGameStateMachine.ts
-import { useState as useState11, useRef as useRef12, useCallback as useCallback8, useEffect as useEffect32, useContext as useContext34 } from "react";
+import { useState as useState11, useRef as useRef12, useCallback as useCallback8, useEffect as useEffect34, useContext as useContext36 } from "react";
 function useGameStateMachine(states, initial) {
-  const engine = useContext34(EngineContext);
+  const engine = useContext36(EngineContext);
   const [state, setState] = useState11(initial);
   const stateRef = useRef12(initial);
   const statesRef = useRef12(states);
   statesRef.current = states;
-  useEffect32(() => {
+  useEffect34(() => {
     statesRef.current[initial]?.onEnter?.();
   }, []);
   const transition = useCallback8((to) => {
@@ -6689,7 +6839,7 @@ function useGameStateMachine(states, initial) {
     setState(to);
     statesRef.current[to]?.onEnter?.();
   }, []);
-  useEffect32(() => {
+  useEffect34(() => {
     const eid = engine.ecs.createEntity();
     engine.ecs.addComponent(eid, createScript((_id, _world, _input, dt) => {
       statesRef.current[stateRef.current]?.onUpdate?.(dt);
@@ -6702,19 +6852,19 @@ function useGameStateMachine(states, initial) {
 }
 
 // ../gameplay/src/hooks/useHealth.ts
-import { useRef as useRef13, useEffect as useEffect33, useContext as useContext35, useCallback as useCallback9 } from "react";
+import { useRef as useRef13, useEffect as useEffect35, useContext as useContext37, useCallback as useCallback9 } from "react";
 function useHealth(maxHp, opts = {}) {
-  const engine = useContext35(EngineContext);
-  const entityId = useContext35(EntityContext);
+  const engine = useContext37(EngineContext);
+  const entityId = useContext37(EntityContext);
   const hpRef = useRef13(maxHp);
   const invincibleRef = useRef13(false);
   const iFrameDuration = opts.iFrames ?? 1;
   const onDeathRef = useRef13(opts.onDeath);
   const onDamageRef = useRef13(opts.onDamage);
-  useEffect33(() => {
+  useEffect35(() => {
     onDeathRef.current = opts.onDeath;
   });
-  useEffect33(() => {
+  useEffect35(() => {
     onDamageRef.current = opts.onDamage;
   });
   const timerRef = useRef13(
@@ -6733,10 +6883,10 @@ function useHealth(maxHp, opts = {}) {
     if (hpRef.current <= 0) onDeathRef.current?.();
   }, [iFrameDuration]);
   const takeDamageRef = useRef13(takeDamage);
-  useEffect33(() => {
+  useEffect35(() => {
     takeDamageRef.current = takeDamage;
   }, [takeDamage]);
-  useEffect33(() => {
+  useEffect35(() => {
     return engine.events.on(`damage:${entityId}`, ({ amount }) => {
       takeDamageRef.current(amount);
     });
@@ -6771,10 +6921,10 @@ function useHealth(maxHp, opts = {}) {
 }
 
 // ../gameplay/src/hooks/useKinematicBody.ts
-import { useContext as useContext36, useCallback as useCallback10 } from "react";
+import { useContext as useContext38, useCallback as useCallback10 } from "react";
 function useKinematicBody() {
-  const engine = useContext36(EngineContext);
-  const entityId = useContext36(EntityContext);
+  const engine = useContext38(EngineContext);
+  const entityId = useContext38(EntityContext);
   const moveAndCollide = useCallback10((dx, dy) => {
     const transform = engine.ecs.getComponent(entityId, "Transform");
     if (!transform) return { dx: 0, dy: 0 };
@@ -6861,13 +7011,13 @@ function useLevelTransition(initial) {
 }
 
 // ../gameplay/src/hooks/usePlatformerController.ts
-import { useContext as useContext37, useEffect as useEffect34 } from "react";
+import { useContext as useContext39, useEffect as useEffect36 } from "react";
 function normalizeKeys(val, defaults) {
   if (!val) return defaults;
   return Array.isArray(val) ? val : [val];
 }
 function usePlatformerController(entityId, opts = {}) {
-  const engine = useContext37(EngineContext);
+  const engine = useContext39(EngineContext);
   const {
     speed = 200,
     jumpForce = -500,
@@ -6880,7 +7030,7 @@ function usePlatformerController(entityId, opts = {}) {
   const leftKeys = normalizeKeys(bindings?.left, ["ArrowLeft", "KeyA", "a"]);
   const rightKeys = normalizeKeys(bindings?.right, ["ArrowRight", "KeyD", "d"]);
   const jumpKeys = normalizeKeys(bindings?.jump, ["Space", "ArrowUp", "KeyW", "w"]);
-  useEffect34(() => {
+  useEffect36(() => {
     const state = {
       coyoteTimer: 0,
       jumpBuffer: 0,
@@ -6944,9 +7094,9 @@ function usePathfinding() {
 }
 
 // ../gameplay/src/hooks/usePersistedBindings.ts
-import { useState as useState13, useCallback as useCallback13, useMemo as useMemo9, useContext as useContext38 } from "react";
+import { useState as useState13, useCallback as useCallback13, useMemo as useMemo8, useContext as useContext40 } from "react";
 function usePersistedBindings(storageKey, defaults) {
-  const engine = useContext38(EngineContext);
+  const engine = useContext40(EngineContext);
   const input = engine.input;
   const [bindings, setBindings] = useState13(() => {
     try {
@@ -6956,7 +7106,7 @@ function usePersistedBindings(storageKey, defaults) {
     }
     return defaults;
   });
-  const normalized = useMemo9(() => {
+  const normalized = useMemo8(() => {
     const out = {};
     for (const [action, keys] of Object.entries(bindings)) {
       if (typeof keys === "string") out[action] = [keys];
@@ -6981,7 +7131,7 @@ function usePersistedBindings(storageKey, defaults) {
     }
     setBindings(defaults);
   }, [storageKey]);
-  return useMemo9(() => ({
+  return useMemo8(() => ({
     bindings,
     rebind,
     reset,
@@ -7051,11 +7201,11 @@ function useSave(key, defaultValue, opts = {}) {
 }
 
 // ../gameplay/src/hooks/useTopDownMovement.ts
-import { useContext as useContext39, useEffect as useEffect35 } from "react";
+import { useContext as useContext41, useEffect as useEffect37 } from "react";
 function useTopDownMovement(entityId, opts = {}) {
-  const engine = useContext39(EngineContext);
+  const engine = useContext41(EngineContext);
   const { speed = 200, normalizeDiagonal = true } = opts;
-  useEffect35(() => {
+  useEffect37(() => {
     const updateFn = (id, world, input) => {
       if (!world.hasEntity(id)) return;
       const rb = world.getComponent(id, "RigidBody");
@@ -7128,9 +7278,9 @@ function useDialogue() {
 }
 
 // ../gameplay/src/hooks/useCutscene.ts
-import { useState as useState16, useCallback as useCallback17, useRef as useRef17, useEffect as useEffect36, useContext as useContext40 } from "react";
+import { useState as useState16, useCallback as useCallback17, useRef as useRef17, useEffect as useEffect38, useContext as useContext42 } from "react";
 function useCutscene() {
-  const engine = useContext40(EngineContext);
+  const engine = useContext42(EngineContext);
   const [playing, setPlaying] = useState16(false);
   const [stepIndex, setStepIndex] = useState16(0);
   const stepsRef = useRef17([]);
@@ -7215,7 +7365,7 @@ function useCutscene() {
     }
     finish();
   }, [finish]);
-  useEffect36(() => {
+  useEffect38(() => {
     return () => {
       if (entityRef.current !== null && engine.ecs.hasEntity(entityRef.current)) {
         engine.ecs.destroyEntity(entityRef.current);
@@ -7262,7 +7412,7 @@ function useGameStore(key, initialState) {
 }
 
 // ../gameplay/src/hooks/useTween.ts
-import { useRef as useRef18, useCallback as useCallback19, useEffect as useEffect37 } from "react";
+import { useRef as useRef18, useCallback as useCallback19, useEffect as useEffect39 } from "react";
 function useTween(opts) {
   const rafRef = useRef18(null);
   const startTimeRef = useRef18(0);
@@ -7298,12 +7448,12 @@ function useTween(opts) {
     };
     rafRef.current = requestAnimationFrame(tick);
   }, [stop]);
-  useEffect37(() => {
+  useEffect39(() => {
     if (opts.autoStart) {
       start();
     }
   }, []);
-  useEffect37(() => {
+  useEffect39(() => {
     return () => {
       if (rafRef.current !== null) {
         cancelAnimationFrame(rafRef.current);
@@ -7322,7 +7472,7 @@ function useTween(opts) {
 }
 
 // ../gameplay/src/hooks/useObjectPool.ts
-import { useRef as useRef19, useMemo as useMemo10, useEffect as useEffect38 } from "react";
+import { useRef as useRef19, useMemo as useMemo9, useEffect as useEffect40 } from "react";
 function useObjectPool(factory, reset, initialSize) {
   const poolRef = useRef19([]);
   const activeRef = useRef19(0);
@@ -7330,7 +7480,7 @@ function useObjectPool(factory, reset, initialSize) {
   factoryRef.current = factory;
   const resetRef = useRef19(reset);
   resetRef.current = reset;
-  useEffect38(() => {
+  useEffect40(() => {
     if (initialSize != null && initialSize > 0) {
       const pool = poolRef.current;
       for (let i = 0; i < initialSize; i++) {
@@ -7338,7 +7488,7 @@ function useObjectPool(factory, reset, initialSize) {
       }
     }
   }, []);
-  return useMemo10(() => ({
+  return useMemo9(() => ({
     acquire() {
       activeRef.current++;
       if (poolRef.current.length > 0) {
@@ -7366,7 +7516,7 @@ function useObjectPool(factory, reset, initialSize) {
 }
 
 // ../../packages/audio/src/useSound.ts
-import { useEffect as useEffect39, useRef as useRef20 } from "react";
+import { useEffect as useEffect41, useRef as useRef20 } from "react";
 var _audioCtx = null;
 function getAudioCtx() {
   if (!_audioCtx) _audioCtx = new AudioContext();
@@ -7439,7 +7589,7 @@ function useSound(src, opts = {}) {
   const volRef = useRef20(opts.volume ?? 1);
   const loopRef = useRef20(opts.loop ?? false);
   const groupRef = useRef20(opts.group);
-  useEffect39(() => {
+  useEffect41(() => {
     let cancelled = false;
     loadBuffer(src).then((buf) => {
       if (!cancelled) bufferRef.current = buf;
@@ -7580,6 +7730,23 @@ function createAtlas(names, _columns) {
   return atlas;
 }
 
+// src/utils/animationHelpers.ts
+function playClip(world, entityId, clipName) {
+  const anim = world.getComponent(entityId, "AnimationState");
+  if (anim) anim.currentClip = clipName;
+}
+function setAnimationState(world, entityId, stateName) {
+  const animator = world.getComponent(entityId, "Animator");
+  if (animator) {
+    animator.currentState = stateName;
+    animator._entered = false;
+  }
+}
+function setAnimatorParam(world, entityId, name, value) {
+  const animator = world.getComponent(entityId, "Animator");
+  if (animator) animator.params[name] = value;
+}
+
 // src/utils/prefab.ts
 import { memo } from "react";
 function definePrefab(name, defaults, render) {
@@ -7593,6 +7760,7 @@ function definePrefab(name, defaults, render) {
 export {
   AnimatedSprite,
   Animation,
+  Animator,
   AssetLoader,
   BoxCollider,
   Camera2D,
@@ -7650,11 +7818,14 @@ export {
   overlapBox,
   overlapCircle,
   patrol,
+  playClip,
   preloadManifest,
   raycast,
   raycastAll,
   scanlineEffect,
   seek,
+  setAnimationState,
+  setAnimatorParam,
   setGroupMute,
   setGroupVolume,
   setMasterVolume,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cubeforge",
-  "version": "0.3.15",
+  "version": "0.3.16",
   "description": "React-first 2D browser game engine",
   "type": "module",
   "main": "./dist/index.js",