rig-play 1.3.0 → 1.5.0

package/README.md

@@ -263,6 +263,38 @@ box, an inverse clip removes nothing, and bounding boxes, paths and points do
 not draw and do not count. Both cost nothing until called and read the same
 numbers in `dom` and `canvas` mode.
 
+### Several tracks
+
+A base on track 0, a layer over it, a one-shot played once and mixed back out —
+rig-c's live tracks (`openTracks`), whose mixing is the Spine runtime's
+`AnimationState` held at tolerance 0:
+
+```ts
+player.play('idle');                                        // track 0, as always
+player.play('smile', { track: 1, loop: false, mix: 0.2 });  // held at its end, mixed in over 0.2 s
+player.play('wave', { track: 2, loop: false, mix: 0.1 });   // a one-shot…
+player.queueClear(2, { mix: 0.1 });                         // …mixed back out over its last 0.1 s
+player.queue('idle_b', { track: 0, mix: 0.3 });             // after the current idle cycle completes
+player.clear(1, { mix: 0.2 });                              // the layer gone, the base showing through
+player.entry(2);                                            // { animation, loop, trackTime, animationTime, duration } | null
+```
+
+`play(name)` keeps meaning what it meant: a plain play on track 0 runs on rig-c's
+single live track, which poses everything the core poses. The first call that
+composes — a `mix`, a `track` above 0, a `queue`, a `clear` — moves the player onto
+the tracks, carrying the single track over by replay (its animation set, pose 0
+taken, stepped to its time); from then on `seek` and `skin` are refused by name,
+since the player cannot replay a composition to a time — step it forward instead.
+Every entry mixes from the setup pose each step, so `adjust` writes still last one
+pose. **What the tracks do not mix**, in rig-c's words at `play`/`queue`: an
+animation keying a constraint (ik, transform, path, physics, slider), a sequence,
+the draw order, or a path's deform is refused when it is set on the tracks — it
+plays on the single track only. `'event'` carries `track`; a one-shot that is
+mixing out fires nothing. `'complete'` is per track, the player's rule: a looping
+entry each cycle, a held one when it reaches its duration, and an entry that is
+replaced — by `play`, or by the queued entry that starts at its completion less the
+mix — completes no more than it fires.
+
 ### Adjusting bones
 
 A per-pose write to bone locals — a breath's scale, a look's rotation, a mouth
@@ -338,6 +370,23 @@ calling it twice is a no-op. Load once for the page's lifetime and you can
 ignore it; load and unload repeatedly without it and you leak an atlas per
 cycle.
 
+### Loading for the canvas mode only, and `data:` regions
+
+The region cut makes the rigid tier's bitmaps, which only the DOM mode draws.
+`loadModel({ regions })` says what to do about it:
+
+- `'blob'` (default) — `blob:` URLs the load owns; `assets.dispose()` frees them.
+- `'data'` — `data:` URLs instead, for a content policy or a snapshot that does
+  not carry `blob:`. The same PNG bytes, inline; nothing is minted, so there is
+  nothing to free, and the base64 lives as long as the map does.
+- `'none'` — no cut: the pages load, `assets.regionImages` is empty, and the
+  load is for the canvas mode. A DOM-mode player opened on it — `new RigPlayer`
+  without `mode: 'canvas'`, or `player.mode = 'dom'` — is refused by name, and
+  a refused mode change leaves the player as it was.
+
+`assets.regions` records the choice. `unpackRegions` takes the same thing as
+`{ encoding: 'blob' | 'data' }`.
+
 ### Pages that ship at another resolution
 
 A page image may ship at a resolution its document does not declare — a
@@ -389,7 +438,8 @@ the page's own URL holds premultiplied pixels (see below).
 ### What unloading frees
 
 `revokeRegions()` — and `assets.dispose()`, which calls it — frees the blob URLs
-`unpackRegions` minted, and nothing else. The page images are held by
+`unpackRegions` minted, and nothing else (a `regions: 'data'` or `'none'` load
+minted none, so it frees nothing). The page images are held by
 `assets.pageImages` and by every player drawing from them, so a page is
 released once you drop the assets and every player is disposed. With the
 `webgl` mesh backend the shared blitter also uploads each page image on first
@@ -578,12 +628,13 @@ name, and unloading is still elements first, bitmaps second.
 | `DomTexture` | none | Not exported; there is no atlas page to attach a texture to. |
 | `new Skeleton(assets.data)` and `new AnimationState(new AnimationStateData(assets.data))` | `new RigPlayer(root, assets, options?)` | The player holds the pose and the track. |
 | `state.setAnimation(0, 'walk', true)` | `player.play('walk', { loop: true })` | `loop` defaults to true. `play` opens the animation at its first pose with the physics reset there. `player.current` names what is playing. |
+| `state.setAnimation(1, 'smile', false)` with a mix, `addAnimation`, `setEmptyAnimation`, `addEmptyAnimation`, `getCurrent(track)` | `player.play(name, { track, loop, mix })`, `player.queue(name, { track, loop, mix, delay })`, `player.clear(track, { mix })`, `player.queueClear(track, { mix, delay })`, `player.entry(track)` | Since 1.5.0, rig-c's live tracks: the runtime's mixing at tolerance 0. Constraint, sequence, draw-order and path-deform timelines are not mixed and are refused on the tracks. See *Several tracks*. |
 | `state.update(delta)`, `state.apply(skeleton)`, `skeleton.update(delta)`, `skeleton.updateWorldTransform(Physics.update)`, `renderer.render(skeleton)` | `player.frame(dt)` | Or `player.advance(dt)` then `player.draw()`, to time the two apart. |
 | time scale (the caller's own, on the spine-core side) | `player.timeScale` | Multiplies every step. 0 holds the pose without re-posing it; a negative value is not stepped. |
 | holding a pose (the caller stopped advancing) | `player.pause()`, `player.resume()` | `frame` keeps drawing the held pose. |
 | moving to a time (the caller's own, on the spine-core side) | `player.seek(time)`, `RigPlayerOptions.seekStep`, `player.time` | A seek reopens the animation and steps forward in `seekStep` increments (1/60 s by default). Events and completes crossed on the way are not fired. |
-| events (the caller's own listener on the spine-core side) | `player.on('event', listener)`, `player.on('complete', listener)` | `'event'` hands a `RigEvent` (`name`, `time`, `int`, `float`, `string`); `'complete'` hands `{ animation }`. `on` returns a function that removes the listener. |
-| skin (set by the caller on its `Skeleton`) | `RigPlayerOptions.skin` | A constructor option. The names are in `ModelAssets.skins`. Without it the rig is posed with no skin set. |
+| events (the caller's own listener on the spine-core side) | `player.on('event', listener)`, `player.on('complete', listener)` | `'event'` hands a `RigEvent` (`name`, `time`, `int`, `float`, `string`, `track`); `'complete'` hands `{ animation, track }`. `on` returns a function that removes the listener. |
+| skin (set by the caller on its `Skeleton`) | `RigPlayerOptions.skin`, `player.skin` | A constructor option, and settable on a live player since 1.4.0: the pose re-resolves under the new skin and the track keeps its animation, loop and time (reopened and stepped there, as `seek` does). The names are in `ModelAssets.skins`. Without it the rig is posed with no skin set. |
 | `SpineHtmlRenderer` | `DomRenderer`, reached as `player.renderer` | In `mode: 'dom'`, the default. `mode: 'canvas'` is new and makes `player.renderer` a `CanvasRenderer`. |
 | `new SpineHtmlRenderer(root, regionImages)` | `new DomRenderer(root, regionImages, pages?)` | Only for drawing your own frames; `RigPlayer` constructs its renderer. `pages` is the page-image map the mesh tier samples (`ModelAssets.pageImages`). A hand-built `regionImages` map is still accepted. |
 | `renderer.render(skeleton)` | `renderer.render(frame)` | Takes a `PosedFrame`, not a skeleton. `player.posedFrame()` returns the one the player would draw. |
@@ -616,11 +667,6 @@ export, for which 1.0.0 declares nothing:
 - **One unpacked atlas shared by different skeletons.** A document is one rig, and each
   `loadModel` cuts its own regions and owns its own blob URLs. Sharing is per rig: one
   load, several players.
-- **More than one track, mixing between animations, or queueing one after another.**
-  `RigPlayer` declares one track; `play` reopens it at the animation's first pose.
-- **Changing the skin after construction.** `skin` is a `RigPlayerOptions` field and
-  `RigPlayer` declares no way to change it later; a second player over the same assets
-  is the declared route.
 - **Changing one slot from code** (its attachment, its colour). `RigPlayer` declares only
   the whole-rig `color`. The frame record is a plain object, so a caller that draws its
   own frames through `DomRenderer.render` or `CanvasRenderer.render` decides what is in

package/dist/DomTexture.d.ts

@@ -90,6 +90,16 @@ export declare function straightAlphaDerivations(): number;
  * happens once it has.
  */
 export declare function straightAlphaSource(page: HTMLImageElement, pma: boolean): PageSource;
+/**
+ * How a cut region's PNG is handed to the `<img>`: a `blob:` URL this module
+ * owns and `revokeRegions` frees (the default), or a `data:` URL that owns
+ * nothing and needs no revoke.
+ */
+export type RegionEncoding = 'blob' | 'data';
+export interface UnpackRegionsOptions {
+    /** `'blob'` by default. */
+    encoding?: RegionEncoding;
+}
 /**
  * Cuts every region of a page layout — a model document's `pages` section —
  * out of its page image into its own bitmap once at load time, restoring 90°
@@ -151,7 +161,7 @@ export declare function straightAlphaSource(page: HTMLImageElement, pma: boolean
  * unpackRegions() with a revokeRegions(); a caller that loads once for the
  * page lifetime can ignore it.
  */
-export declare function unpackRegions(pages: readonly PageLayout[], pageImages: ReadonlyMap<string, HTMLImageElement>): Promise<Map<string, RegionImage>>;
+export declare function unpackRegions(pages: readonly PageLayout[], pageImages: ReadonlyMap<string, HTMLImageElement>, options?: UnpackRegionsOptions): Promise<Map<string, RegionImage>>;
 /**
  * Frees the blob URLs unpackRegions minted for `images` — the counterpart of
  * unpackRegions, to call once the skeletons using them are gone (after

package/dist/DomTexture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DomTexture.d.ts","sourceRoot":"","sources":["../src/DomTexture.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;CAChC;AAQD,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;;OASG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;CAChB;AAkBD;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,gBAAgB,GAAG,iBAAiB,CAAC;AAqC9D;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,EAAE,GAAG,EAAE,OAAO,GAAG,UAAU,CAcpF;AAgSD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAChD,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CA0EnC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,IAAI,CAEpE"}
+{"version":3,"file":"DomTexture.d.ts","sourceRoot":"","sources":["../src/DomTexture.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;CAChC;AAQD,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;;OASG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;CAChB;AAkBD;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,gBAAgB,GAAG,iBAAiB,CAAC;AAqC9D;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,EAAE,GAAG,EAAE,OAAO,GAAG,UAAU,CAcpF;AAuSD;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,CAAC;AAE7C,MAAM,WAAW,oBAAoB;IACnC,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,gBAAgB,CAAC,EACjD,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CA4EnC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,IAAI,CAEpE"}

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { type CanvasBackend, CanvasRenderer, type CanvasViewport } from './CanvasRenderer.js';
 export { DomRenderer, type MeshBackend } from './DomRenderer.js';
-export { type PageLayout, type PageRegion, type RegionImage, revokeRegions, unpackRegions } from './DomTexture.js';
-export { type LoadModelOptions, loadModel, type ModelAssets, type ModelDocument } from './loadModel.js';
-export { type AdjustableBones, type BoneAdjust, type BoneLocals, type BoneWorld, type PoseBounds, type RenderMode, type RigEvent, RigPlayer, type RigPlayerOptions } from './player.js';
+export { type PageLayout, type PageRegion, type RegionEncoding, type RegionImage, revokeRegions, type UnpackRegionsOptions, unpackRegions } from './DomTexture.js';
+export { type LoadModelOptions, loadModel, type ModelAssets, type ModelDocument, type RegionLoading } from './loadModel.js';
+export { type AdjustableBones, type BoneAdjust, type BoneLocals, type BoneWorld, type PlayOptions, type PoseBounds, type QueueOptions, type RenderMode, type RigComplete, type RigEvent, RigPlayer, type RigPlayerOptions, type TrackEntry } from './player.js';
 export type { BlendMode, PosedClip, PosedFrame, PosedMesh, PosedRegion, PosedSlot, } from './posedFrame.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC9F,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACnH,OAAO,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACxG,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACxL,YAAY,EACV,SAAS,EACT,SAAS,EACT,UAAU,EACV,SAAS,EACT,WAAW,EACX,SAAS,GACV,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC9F,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,KAAK,WAAW,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACnK,OAAO,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC5H,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,QAAQ,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAChQ,YAAY,EACV,SAAS,EACT,SAAS,EACT,UAAU,EACV,SAAS,EACT,WAAW,EACX,SAAS,GACV,MAAM,iBAAiB,CAAC"}