SkeletonAnimator

A generic, event-driven clip state machine that loops one skeletal animation and plays one-shot reactions on top of it.

What it does

The SkeletonAnimatorSystem drives a single rigged model's clips through the active renderer: it loops one clip and plays one-shot reactions over it, returning to the loop when each one-shot ends (or freezing on the last frame for a terminal hold clip like a death). It is renderer- and domain-agnostic — any producer (an AI brain, a game director, a hit system) drives it by emitting skeletonAnimator.setLoop and skeletonAnimator.playOnce, and it emits skeletonAnimator.completed when a one-shot finishes. It waits for the sibling Mesh's mesh.loaded before touching playback (so it never grabs another entity's clip of the same name) and buffers a loop request received before the model is ready.

Use it in a scene

A scene is just data — a list of entities, each with its components. At startup the SceneLoader turns this JSON into a live world; edit the file and reload to rebuild it.

Fastest path

bjs download scene SkeletonAnimator

Pulls this exact scene into your project and runs it — no copy-paste. Add --all to grab the components and assets it needs too.

Or build it from scratch with the bjs CLI:

1Scaffold a project
```
npm create @babylonjsmarket/arcade@latest my-game
```
World, renderer, and dev server — ready to run.
2Install dependencies
```
cd my-game && npm install
```
3Add SkeletonAnimator
```
bjs download SkeletonAnimator
```
Copies its source into src/ so the scene resolves.
First time? Run bjs login once.
4Paste the scene into src/scenes/arcade-room.ts and run
```
npm run dev
```
SceneLoader builds the world from the JSON; reload to rebuild.

JSON

{
  "Character": {
    "components": {
      "Mesh": {
        "src": "/models/character.glb",
        "instanced": true,
        "follow": true,
        "scale": 1,
        "autoLoad": true
      },
      "SkeletonAnimator": { "defaultLoopClip": "Idle", "defaultOnceSeconds": 1.0 }
    }
  }
}

Props

defaultLoopClip (string, default '') — clip looped once the model is ready, until a setLoop event changes it.
defaultOnceSeconds (number, default 1.0) — fallback one-shot length in seconds, used when a playOnce event omits a duration and the renderer reports a clip length of 0.

Events

listens skeletonAnimator.setLoop — { entityId, clip }. Switch the looping clip (idempotent). Buffered if received before the model is loaded.
listens skeletonAnimator.playOnce — { entityId, clip, durationSeconds?, hold? }. Play a one-shot, then resume the loop. With hold: true the one-shot is terminal and freezes on its last frame instead of resuming. Dropped if the model isn't loaded yet.
emits skeletonAnimator.completed — { entityId, clip }. Fired when a one-shot finishes.

Dependencies

Mesh — provides the loaded, rigged model under the entity id and emits mesh.loaded, which gates all playback.

Notes

Playback is keyed by entity.id; the renderer falls back to a global clip lookup if a clip isn't found under that id, so the system never plays/stops for an entity until it has seen mesh.loaded.
A setLoop received early is stored and applied on load; a playOnce received early is dropped.
Pooling-aware: parking an entity (active === false) stops its clips and clears the loop but keeps the loaded state, so a re-acquired slot must re-receive setLoop; a true destroy forgets everything.