three-vat 1.0.0 → 2.0.0

package/dist/carrier-BFCPmcQK.d.ts

@@ -0,0 +1,472 @@
+import { DataTexture, BufferGeometry, Material, Box3, InstancedMesh, BatchedMesh } from 'three';
+
+/**
+ * How an instance repeats its clip — the numbers `THREE.LoopRepeat`,
+ * `THREE.LoopOnce` and `THREE.LoopPingPong` name, in three's own order, as
+ * values a `Float32Array` can carry.
+ *
+ * What each one *means* is {@link resolveVATFrame}, in one place, transcribed
+ * by both decode paths.
+ */
+declare const LoopMode: {
+    /** Play the clip end to end, forever (or `repetitions` times). */
+    readonly Repeat: 0;
+    /** Play the clip through once. */
+    readonly Once: 1;
+    /** Play forward, then backward, without baking the reversed frames. */
+    readonly PingPong: 2;
+};
+type LoopMode = (typeof LoopMode)[keyof typeof LoopMode];
+/**
+ * What an instance does once it has finished — three's `clampWhenFinished`, as
+ * a pair of numbers.
+ *
+ * `Clamp` is first because it is this library's default, where three's
+ * `clampWhenFinished` defaults to `false`. A one-shot in a crowd — a death, an
+ * impact — almost always has to *stay* in its final state, and a rewinding
+ * corpse standing back up is the failure a crowd library should not ship by
+ * default. The divergence is deliberate.
+ */
+declare const EndMode: {
+    /** Hold the last frame. */
+    readonly Clamp: 0;
+    /** Return to the first frame. */
+    readonly Rewind: 1;
+};
+type EndMode = (typeof EndMode)[keyof typeof EndMode];
+/**
+ * An endless repeat count, as the pack spells it. `Infinity` does not survive a
+ * `Float32Array` usefully, so it is converted once, here, at the boundary.
+ */
+declare const INFINITE_REPETITIONS = -1;
+/**
+ * The longest fade {@link setVATInstance} will honour, in seconds.
+ *
+ * The cap exists because of what this fade *is*: one frozen pose of the
+ * outgoing clip, blended away — not a second playback running alongside the
+ * first. Over a tenth of a second that is invisible; over half a second the
+ * instance visibly skates, because whatever it was doing stopped dead the
+ * moment the transition began. A longer fade would not be a better fade, it
+ * would be a more visible bug, so the number is clamped rather than trusted.
+ *
+ * Provisional, like the fade itself: a real two-clip crossfade (#30) replaces
+ * both, and nothing else should be built on top of them.
+ */
+declare const MAX_FADE_DURATION = 0.25;
+/**
+ * The frozen pose a fade blends away from: one phase of the clip an instance
+ * was playing when its animation changed, and the band that phase indexes.
+ *
+ * Not a second playback state — there is no start time and no speed here,
+ * because nothing about it moves. That is the whole of the freeze, and the
+ * whole of its limit; see {@link MAX_FADE_DURATION}.
+ */
+interface VATFadeFrom {
+    /** First texture row of the outgoing clip's band. */
+    startFrame: number;
+    /** Rows in that band. */
+    frames: number;
+    /** The phase of that band the instance was at, in `[0, 1]`. */
+    phase: number;
+}
+/**
+ * Per-instance playback state consumed by both decode paths.
+ *
+ * Every policy field is optional because the clip already answers it: a bake
+ * handed a configured `AnimationAction` records the answer in the clip table
+ * ({@link VATClipDefaults}), and an instance that says nothing inherits it. A
+ * crowd of a thousand deaths says "once, clamped" once, at the bake.
+ */
+interface VATInstance {
+    /**
+     * The clip band to play, straight out of `vat.clips`. Its playback defaults
+     * come along with it; a clip table assembled by hand may carry none, and then
+     * the library defaults below apply.
+     */
+    clip: Pick<VAT['clips'][number], 'startFrame' | 'frames' | 'fps'> & Partial<VATClipDefaults>;
+    /**
+     * Absolute clock time, in seconds, at which this animation began. May be in
+     * the past — and **desync is exactly that**: give each instance of a crowd its
+     * own start time a little way back and they stop moving in lockstep.
+     *
+     * The one field with no clip-level default: when an animation began is a fact
+     * about the instance and nothing else.
+     */
+    startTime: number;
+    /**
+     * Playback rate multiplier, `>= 0`. Defaults to the clip's speed, then to
+     * `1`. A negative rate is refused when the instance is written: a VAT plays
+     * forward, and a clip that must run backwards is baked as a reversed clip.
+     * `0` is legal — the instance holds its clip's first row.
+     */
+    speed?: number;
+    /** How the clip repeats. Defaults to the clip's, then {@link LoopMode.Repeat}. */
+    loopMode?: LoopMode;
+    /**
+     * How many times to play the clip, or {@link INFINITE_REPETITIONS}. Defaults
+     * to the clip's count, then to endless for {@link LoopMode.Repeat} and a
+     * single play for anything else — the counts three's own `LoopRepeat` and
+     * `LoopOnce` imply.
+     *
+     * A count belongs to the mode it was configured under: replace the clip's
+     * `loopMode` and say nothing here, and the count comes from the new mode
+     * rather than from the clip — a one-shot over a looping clip finishes.
+     */
+    repetitions?: number;
+    /**
+     * What to do once the repetitions run out. Defaults to the clip's, then
+     * {@link EndMode.Clamp} — where three's `clampWhenFinished` defaults to
+     * `false`; see {@link EndMode}.
+     */
+    endMode?: EndMode;
+    /**
+     * The frozen outgoing pose to fade away from. Normally you do not write this
+     * yourself: {@link setVATInstance} freezes whatever the instance was playing
+     * and fills it in when you ask for a {@link fadeDuration}.
+     */
+    from?: VATFadeFrom;
+    /**
+     * Seconds to blend {@link from} away over, capped at {@link MAX_FADE_DURATION}.
+     * Wall-clock seconds from {@link startTime}: the clip's `speed` does not
+     * stretch a fade.
+     *
+     * Ignored without a `from` to fade away from — and at creation there is
+     * nothing to fade away from, so this is `setVATInstance`'s field in practice.
+     */
+    fadeDuration?: number;
+}
+/**
+ * Where in its VAT an instance is at a given moment: the two frame rows to
+ * sample, the blend between them, and the two facts a decode cannot re-derive
+ * from the rows alone.
+ */
+interface VATFrame {
+    /** The frame row to sample — an absolute texture row, clip band included. */
+    row: number;
+    /** The row it interpolates toward. */
+    rowNext: number;
+    /** Blend between {@link row} and {@link rowNext}, in `[0, 1)`. */
+    mix: number;
+    /**
+     * Whether {@link rowNext} crossed the clip's last row back into its first.
+     * True only while a clip is genuinely looping: a ping-pong bounces rather
+     * than wraps, and a finished one-shot must not wrap at all or the corpse
+     * stands back up for a frame.
+     */
+    wraps: boolean;
+    /** Whether the repetitions have run out and the instance is holding an end pose. */
+    finished: boolean;
+    /** How far through the clip this is, in `[0, 1]` — what {@link row} is derived from. */
+    phase: number;
+    /**
+     * The frozen outgoing row a fade blends away from. Equal to {@link row} when
+     * the instance is not fading, so a reader that ignores {@link fade} — the
+     * demo's texture-panel cursors among them — never points at a row this
+     * instance is not sampling.
+     */
+    fadeRow: number;
+    /**
+     * How much of {@link fadeRow} is still showing: `1` at the moment of the
+     * write, falling to `0` across `fadeDuration`, and `0` for an instance that
+     * is not fading. The decode mixes the sampled clip toward the frozen pose by
+     * exactly this weight — the weight of the fade, not the fade itself, which is
+     * the pose-freeze fade `CONTEXT.md` names.
+     */
+    fadeWeight: number;
+}
+/**
+ * What the vertex shader computes, as a pure function of `(instance, time)` —
+ * the **one definition** of the playback semantics. Both decode paths
+ * transcribe it (`DECODE_PRELUDE` in src/webgl.ts, `vatDecode` in src/tsl.ts);
+ * neither invents it.
+ *
+ * It exists in TypeScript because the arithmetic is otherwise reachable only
+ * inside a GLSL string and a TSL node graph, neither of which CI can evaluate
+ * without a GPU — and because a caller scheduling what happens after a one-shot
+ * needs to ask the same question the shader answers.
+ *
+ * There is no accumulated state anywhere in here: an instance is written once,
+ * at the moment its animation changes, and every frame after that is this
+ * function of the shared clock.
+ */
+declare function resolveVATFrame(instance: VATInstance, time: number): VATFrame;
+/**
+ * What carries the pack to the shader: one `DataTexture`, three texels wide,
+ * one row per instance, read by the instance's *logical* index (ADR-0016).
+ *
+ * Held by the caller rather than hidden behind the geometry, because a
+ * `BufferGeometry` has nowhere to put a texture and a side channel — a
+ * `WeakMap`, or a `userData` the first `clone()` loses — would not say what
+ * {@link setVATInstance} writes into. `createVATMesh` hands one back on either
+ * decode path; build your own with {@link createVATPlaybackTexture} when you
+ * are assembling a crowd by hand.
+ */
+interface VATPlaybackTexture {
+    /**
+     * The texture both decode paths bind: `x = field`, `y = instance`, RGBA
+     * float, {@link PACK_WIDTH} texels wide.
+     */
+    texture: DataTexture;
+    /** Instances it carries — the rows of {@link texture}. */
+    count: number;
+}
+/**
+ * Write a crowd's instance playback into a new playback texture. Call once,
+ * before rendering, and bind the result into the decode — `createVATMesh` does
+ * both for you.
+ *
+ * The layout below is the shared contract, spelled once in {@link PACK_TEXELS}.
+ * Both decode paths read exactly these three texels of row `instanceIndex` —
+ * `DECODE_PRELUDE` in `src/webgl.ts` with `texelFetch`, `texturePlayback` in
+ * `src/tsl.ts` with `textureLoad`.
+ *
+ * | Texel            | r                   | g            | b             | a             |
+ * | ---------------- | ------------------- | ------------ | ------------- | ------------- |
+ * | `x = 0` clip     | clip start row      | clip frames  | clip fps      | speed         |
+ * | `x = 1` playback | start time          | loop mode    | repetitions   | end mode      |
+ * | `x = 2` fade     | from clip start row | from frames  | from phase    | fade duration |
+ *
+ * **A texture, not three instanced attributes.** An attribute with divisor 1 is
+ * indexed by the *drawn slot*, and the drawn slot stops being the instance the
+ * moment a renderer culls or sorts per instance — on a `BatchedMesh` every
+ * vertex would read element 0 and the whole crowd would play instance 0's clip
+ * (ADR-0016). A row keyed by the logical index is what three itself does for
+ * the same problem, in `_matricesTexture`.
+ *
+ * **Three texels, not thirteen floats.** The move to a texture touched no
+ * decode arithmetic, because the layout did not change with it: the pack was
+ * already three RGBA-shaped `vec4`s (ADR-0009). Published 1.x is the other
+ * story — five one-float attributes there, so a 1.x caller meets both changes
+ * at once.
+ *
+ * **`FloatType`, and it stays that way.** A `startTime` in seconds does not
+ * survive half precision — one second of resolution at 2 048 s — so a narrower
+ * encoding for the VAT textures does not reach this one.
+ *
+ * The policy fields, and the clip texel's speed, come from the instance where
+ * it names them and from the clip's baked defaults where it does not — resolved
+ * in the one place those tiers are spelled — and both decode paths read them as
+ * {@link resolveVATFrame} defines them. The fade texel is written as zeroes,
+ * which is what "not fading" is: a crowd being created has no pose to fade away
+ * from. Fades belong to {@link setVATInstance}, where an instance's animation
+ * changes and there is something to fade out of.
+ */
+declare function createVATPlaybackTexture(instances: VATInstance[]): VATPlaybackTexture;
+/**
+ * Change one instance's animation, after the crowd is built. The single write
+ * the whole event-driven half of this library is made of: an enemy hit at
+ * `t = 12.3s` becomes a dying enemy here, and the CPU does not touch it again.
+ *
+ * ```ts
+ * // the moment it is hit — and nothing per frame afterwards
+ * setVATInstance(playback, enemyId, {
+ *   clip: vat.clips[2],      // "once, clamped" came with the bake
+ *   startTime: time.value,
+ *   fadeDuration: 0.1,       // blend out of whatever it was doing
+ * })
+ * ```
+ *
+ * `playback` is the crowd's playback texture — `createVATMesh` hands it back
+ * beside the mesh and the clock — and `index` the instance's index in the array
+ * the crowd was built from, the same one `setMatrixAt` takes.
+ *
+ * Only that instance's row is marked for upload, so a crowd of a thousand costs
+ * one small write rather than a full re-upload. Everything else about the
+ * instance — its matrix, its clip's defaults — is untouched. On the TSL path
+ * the range is recorded and ignored: three's WebGPU backend re-uploads the
+ * whole image on `needsUpdate`, which is 48 bytes per instance once per frame
+ * in which anything changed (docs/usage.md says what that costs).
+ *
+ * Ask for a `fadeDuration` and the pose the instance is in *at `startTime`* is
+ * frozen and blended away over that many wall-clock seconds, so the change does
+ * not pop. It is a frozen pose and not a second playback: see
+ * {@link MAX_FADE_DURATION} for what that costs and how far it can be pushed.
+ * One pose, too — writing an instance that is *already* fading freezes the clip
+ * it had switched to and drops the older pose, because the pack holds one.
+ *
+ * A written instance is a pure function of the clock from here on, so what
+ * happens *after* it is a matter of scheduling one more of these writes —
+ * {@link endsAt} says exactly when. Chaining stays yours: the GPU never learns
+ * about a next clip.
+ *
+ * This is deliberately a function over a playback texture rather than an
+ * `InstancedMesh` method. The primitives stay composable for a crowd rendered
+ * onto something else, which is the escape hatch ADR-0009 and ADR-0014 commit
+ * to — and the playback texture is the object such a caller holds (ADR-0016).
+ */
+declare function setVATInstance(playback: VATPlaybackTexture, index: number, instance: VATInstance): void;
+/**
+ * The exact clock time this instance stops animating — when
+ * {@link resolveVATFrame} first reports `finished` — or `null` for an animation
+ * that never gets there: an endless loop, or a speed of zero.
+ *
+ * This is what makes chaining one clip to the next a single scheduled write
+ * rather than a per-frame poll:
+ *
+ * ```ts
+ * const hit = { clip: vat.clips[1], startTime: now, loopMode: LoopMode.Once }
+ * setVATInstance(playback, id, hit)
+ *
+ * const at = endsAt(hit)
+ * if (at !== null) schedule(at, () => setVATInstance(playback, id, { clip: walk, startTime: at }))
+ * ```
+ *
+ * Nothing about the chain reaches the GPU: it reads one pack, and the next clip
+ * does not exist to it until that write happens.
+ */
+declare function endsAt(instance: VATInstance): number | null;
+
+/**
+ * The playback policy a clip carries for every instance that plays it —
+ * declared once, at the bake, instead of repeated at every instance. Hand
+ * `bakeVAT` a configured `AnimationAction` rather than a bare `AnimationClip`
+ * and these come from it; hand it a clip and they are the library defaults
+ * (repeat, forever, speed 1, clamping when finished).
+ *
+ * Defaults, never decisions: an instance overrides any of them, field by field
+ * ({@link VATInstance}). Nothing in the texels changes between "once" and
+ * "forever" — a bake produces poses, and this is the policy those poses are
+ * played under.
+ */
+interface VATClipDefaults {
+    /** How the clip repeats, from the action's `loop`. */
+    loopMode: LoopMode;
+    /**
+     * How many times it plays, from the action's `repetitions` — `Infinity`
+     * converted to `INFINITE_REPETITIONS`, because a `Float32Array` cannot carry
+     * the former.
+     */
+    repetitions: number;
+    /**
+     * What it does once finished — {@link EndMode.Clamp} from the bake, whichever
+     * of the two inputs it came from.
+     *
+     * three defaults `clampWhenFinished` to `false`, and a crowd's answer to a
+     * one-shot is to hold the last frame: a corpse standing back up is the worse
+     * default to ship (see {@link EndMode}). A bare `AnimationClip` says nothing,
+     * and an untouched action's `false` is not a statement either — it is what
+     * the field already holds — so the bake gives both the same answer rather
+     * than punishing the caller who configured an action. `clampWhenFinished =
+     * true` agrees with it; three's rewind is asked for per instance, with
+     * `endMode: EndMode.Rewind` (ADR-0017).
+     */
+    endMode: EndMode;
+    /**
+     * Playback rate, from the action's `timeScale`. `>= 0`: a band is sampled
+     * forward from its own first row, so a negative rate is refused at the bake
+     * rather than held on that row for ever. `0` is a held first row, on purpose.
+     */
+    speed: number;
+}
+/**
+ * One baked animation range within a VAT's stacked frame rows, and the playback
+ * defaults every instance of it inherits.
+ */
+interface VATClip extends VATClipDefaults {
+    /** Clip name, taken from the source `AnimationClip`. */
+    name: string;
+    /** First frame row (y) of this clip in the texture. */
+    startFrame: number;
+    /** Number of frame rows baked for this clip. */
+    frames: number;
+    /** Effective frames-per-second of the bake (`frames / duration`). */
+    fps: number;
+    /** Source clip duration in seconds. */
+    duration: number;
+    /**
+     * Largest per-vertex position-delta magnitude (metres) across the clip.
+     * Near-zero means the clip baked as a frozen pose — the diagnostic for a
+     * mis-targeted or genuinely static clip.
+     */
+    maxDelta: number;
+}
+/**
+ * A baked Vertex Animation Texture: the position `DataTexture` (and the normal
+ * one, unless the bake was told to skip it), the geometry they are indexed by,
+ * and the clip table and bounds needed to decode and render them. Produced
+ * exactly one way — {@link bakeVAT}, at runtime, from a loaded glTF (ADR-0010).
+ *
+ * The merged vertex ordering is the baker's own invention and the textures are
+ * indexed by it (`x = gl_VertexID`), so the caller cannot bring its own
+ * geometry — it must render the one baked here. `materials` is ordered to match
+ * `geometry.groups[].materialIndex`, giving one draw call per material.
+ *
+ * The typed array behind either texture's `image.data` is the bake's choice,
+ * not part of this contract: `Float32Array` today, and a narrower encoding may
+ * change it in a minor release. Move the buffer, hand it to {@link makeVATTexture};
+ * do not read numbers out of it.
+ */
+interface VAT {
+    /** RGBA float texture of per-vertex position deltas (`x = vertex`, `y = frame`). */
+    positionTexture: DataTexture;
+    /**
+     * RGBA float texture of per-vertex absolute normals (`x = vertex`, `y = frame`),
+     * or `null` when the bake was told to skip it (`bakeNormals: false`) — halving
+     * the VAT for a crowd that never reads a normal. Neither decode path samples
+     * it when it is absent; a smooth-shaded lit material paired with such a VAT is
+     * refused rather than lit by its rest pose.
+     */
+    normalTexture: DataTexture | null;
+    /**
+     * Merged, root-space rest-pose geometry. Its `position` is the delta
+     * reference. Carries `normal` always, and `uv`, `color` and `tangent` when
+     * every source mesh carried them; skinning attributes and morph targets are
+     * dropped, the VAT having replaced them.
+     */
+    geometry: BufferGeometry;
+    /** Source materials, indexed by `geometry.groups[].materialIndex`. */
+    materials: Material[];
+    /** Clip table: name → `{ startFrame, frames, fps, ... }`. */
+    clips: VATClip[];
+    /** Union of every baked frame's bounds; use as the geometry bounding box. */
+    bounds: Box3;
+    /** Vertex count (texture width). */
+    vertexCount: number;
+    /** Total frame rows across all clips (texture height). */
+    totalFrames: number;
+    /** Position encoding. Only `'delta'` in v1. */
+    encoding: 'delta';
+}
+/**
+ * The shared playback clock: one `{ value }` in seconds, read by every material
+ * of every VAT mesh driven by it. Set it once per frame. Deliberately the
+ * narrowest shape both decode paths satisfy — a WebGL `IUniform<number>` and a
+ * TSL uniform node are both one of these — so `createVATMesh` returns the same
+ * thing on either renderer.
+ */
+interface VATClock {
+    value: number;
+}
+/**
+ * A **crowd** ready to render: the mesh to add to the scene, and the clock to
+ * advance. What `createVATMesh` returns on either decode path, so moving a
+ * crowd between renderers is an import change and nothing else. Named for what
+ * it is rather than for its `mesh` field — the clock is half of it.
+ */
+interface VATCrowd {
+    /** Add to the scene. Its instance matrices are yours to write. */
+    mesh: InstancedMesh;
+    /** The shared playback clock — set `.value` once per frame. */
+    time: VATClock;
+    /**
+     * The crowd's **playback texture**: what carries each instance's clip, phase
+     * and policy to the shader, and what `setVATInstance` writes one row of
+     * (ADR-0016). Exposed rather than hidden behind the mesh because it is the
+     * object a caller has to hold to change an instance after the crowd is
+     * built — a `BufferGeometry` cannot carry a texture, so there is nowhere
+     * else honest to keep it.
+     */
+    playback: VATPlaybackTexture;
+}
+
+/**
+ * A mesh a VAT crowd can ride.
+ *
+ * `InstancedMesh` is what `createVATMesh` builds on either path.
+ * `BatchedMesh` is reached through the primitives, and buys per-instance
+ * frustum culling and depth sorting from three.js itself — see
+ * docs/usage.md, which also says what it does *not* buy.
+ */
+type VATCarrier = InstancedMesh | BatchedMesh;
+
+export { EndMode as E, INFINITE_REPETITIONS as I, LoopMode as L, MAX_FADE_DURATION as M, type VAT as V, type VATCarrier as a, type VATClip as b, type VATClipDefaults as c, type VATClock as d, type VATCrowd as e, type VATFadeFrom as f, type VATFrame as g, type VATInstance as h, type VATPlaybackTexture as i, createVATPlaybackTexture as j, endsAt as k, resolveVATFrame as r, setVATInstance as s };

package/dist/chunk-2PGZ44TP.js

@@ -0,0 +1,202 @@
+import { FloatType, DataTexture, RGBAFormat, NearestFilter } from 'three';
+
+// src/vat-texture.ts
+var MAX_TEXTURE_SIZE = 16384;
+function makeVATTexture(data, width, height, type = FloatType) {
+  const tex = new DataTexture(data, width, height, RGBAFormat, type);
+  tex.minFilter = NearestFilter;
+  tex.magFilter = NearestFilter;
+  tex.generateMipmaps = false;
+  tex.needsUpdate = true;
+  return tex;
+}
+
+// src/instance-playback.ts
+var PACK_TEXELS = {
+  clip: 0,
+  playback: 1,
+  fade: 2
+};
+var PACK_WIDTH = 3;
+var PACK_STRIDE = PACK_WIDTH * 4;
+var LoopMode = {
+  /** Play the clip end to end, forever (or `repetitions` times). */
+  Repeat: 0,
+  /** Play the clip through once. */
+  Once: 1,
+  /** Play forward, then backward, without baking the reversed frames. */
+  PingPong: 2
+};
+var EndMode = {
+  /** Hold the last frame. */
+  Clamp: 0,
+  /** Return to the first frame. */
+  Rewind: 1
+};
+var INFINITE_REPETITIONS = -1;
+var MAX_FADE_DURATION = 0.25;
+function defaultRepetitions(loopMode) {
+  return loopMode === LoopMode.Repeat ? INFINITE_REPETITIONS : 1;
+}
+var LIBRARY_PLAYBACK_DEFAULTS = {
+  loopMode: LoopMode.Repeat,
+  repetitions: defaultRepetitions(LoopMode.Repeat),
+  endMode: EndMode.Clamp,
+  speed: 1
+};
+function resolvedPlaybackOf(instance) {
+  const { clip } = instance;
+  const clipLoopMode = clip.loopMode ?? LIBRARY_PLAYBACK_DEFAULTS.loopMode;
+  const loopMode = instance.loopMode ?? clipLoopMode;
+  const clipRepetitions = loopMode === clipLoopMode ? clip.repetitions : void 0;
+  return {
+    loopMode,
+    repetitions: instance.repetitions ?? clipRepetitions ?? defaultRepetitions(loopMode),
+    endMode: instance.endMode ?? clip.endMode ?? LIBRARY_PLAYBACK_DEFAULTS.endMode,
+    speed: instance.speed ?? clip.speed ?? LIBRARY_PLAYBACK_DEFAULTS.speed
+  };
+}
+function fadeOf(instance) {
+  const duration = Math.min(instance.fadeDuration ?? 0, MAX_FADE_DURATION);
+  const from = instance.from;
+  if (!from || duration <= 0 || from.frames <= 0) return null;
+  return { from, duration };
+}
+function fadeRowOf(from) {
+  return from.startFrame + Math.max(Math.min(Math.floor(from.phase * from.frames), from.frames - 1), 0);
+}
+function resolveVATFrame(instance, time) {
+  const { clip } = instance;
+  const frames = clip.frames;
+  const last = frames - 1;
+  const duration = frames / clip.fps;
+  const { loopMode, repetitions, endMode, speed } = resolvedPlaybackOf(instance);
+  const local = (time - instance.startTime) * speed;
+  const loops = local / duration;
+  const started = local >= 0;
+  const finished = started && repetitions !== INFINITE_REPETITIONS && loops >= repetitions;
+  let phase;
+  let wraps;
+  if (!started) {
+    phase = 0;
+    wraps = false;
+  } else if (finished) {
+    phase = endMode === EndMode.Clamp ? 1 : 0;
+    wraps = false;
+  } else if (loopMode === LoopMode.PingPong) {
+    const m = loops % 2;
+    phase = m < 1 ? m : 2 - m;
+    wraps = false;
+  } else {
+    phase = loops % 1;
+    wraps = true;
+  }
+  const f = phase * (wraps ? frames : last);
+  const f0 = Math.min(Math.floor(f), last);
+  const f1 = wraps ? (f0 + 1) % frames : Math.min(f0 + 1, last);
+  const row = clip.startFrame + f0;
+  const fading = fadeOf(instance);
+  const elapsed = fading ? (time - instance.startTime) / fading.duration : 0;
+  return {
+    row,
+    rowNext: clip.startFrame + f1,
+    mix: f - f0,
+    wraps,
+    finished,
+    phase,
+    fadeRow: fading ? fadeRowOf(fading.from) : row,
+    fadeWeight: fading ? 1 - Math.min(Math.max(elapsed, 0), 1) : 0
+  };
+}
+function createVATPlaybackTexture(instances) {
+  const count = instances.length;
+  if (count < 1) {
+    throw new Error(
+      "three-vat: a crowd needs at least one instance \u2014 a playback texture is one row per instance, and there is no zero-row texture to carry none"
+    );
+  }
+  if (count > MAX_TEXTURE_SIZE) {
+    throw new Error(
+      `three-vat: a crowd of ${count} instances needs ${count} rows of playback texture, past the ${MAX_TEXTURE_SIZE}-row ceiling \u2014 the playback texture holds one row per instance, so MAX_TEXTURE_SIZE is the instance ceiling.`
+    );
+  }
+  const data = new Float32Array(count * PACK_STRIDE);
+  for (let i = 0; i < count; i++) writePack(data, i, instances[i]);
+  return { texture: makeVATTexture(data, PACK_WIDTH, count), count };
+}
+var FORWARD_ONLY_REASON = "a baked band plays forward from its own first row, so a negative speed would freeze it on that row rather than run it backwards \u2014 bake a reversed clip instead. A speed of 0 is a held first row, and is fine";
+var rowStart = (index) => index * PACK_STRIDE;
+var texelStart = (index, field) => rowStart(index) + field * 4;
+function writePack(data, index, instance) {
+  const clip = texelStart(index, PACK_TEXELS.clip);
+  const playback = texelStart(index, PACK_TEXELS.playback);
+  const fade = texelStart(index, PACK_TEXELS.fade);
+  const policy = resolvedPlaybackOf(instance);
+  if (policy.speed < 0) {
+    throw new Error(`three-vat: instance ${index} has speed ${policy.speed}; ${FORWARD_ONLY_REASON}.`);
+  }
+  data[clip] = instance.clip.startFrame;
+  data[clip + 1] = instance.clip.frames;
+  data[clip + 2] = instance.clip.fps;
+  data[clip + 3] = policy.speed;
+  data[playback] = instance.startTime;
+  data[playback + 1] = policy.loopMode;
+  data[playback + 2] = policy.repetitions;
+  data[playback + 3] = policy.endMode;
+  const fading = fadeOf(instance);
+  data[fade] = fading ? fading.from.startFrame : 0;
+  data[fade + 1] = fading ? fading.from.frames : 0;
+  data[fade + 2] = fading ? fading.from.phase : 0;
+  data[fade + 3] = fading ? fading.duration : 0;
+}
+function readPack(data, index) {
+  const clip = texelStart(index, PACK_TEXELS.clip);
+  const playback = texelStart(index, PACK_TEXELS.playback);
+  return {
+    clip: { startFrame: data[clip], frames: data[clip + 1], fps: data[clip + 2] },
+    startTime: data[playback],
+    speed: data[clip + 3],
+    loopMode: data[playback + 1],
+    repetitions: data[playback + 2],
+    endMode: data[playback + 3]
+  };
+}
+function assertInstance(playback, index) {
+  if (!Number.isInteger(index) || index < 0 || index >= playback.count) {
+    throw new Error(`three-vat: instance ${index} is outside this crowd of ${playback.count}`);
+  }
+}
+function setVATInstance(playback, index, instance) {
+  assertInstance(playback, index);
+  const data = playback.texture.image.data;
+  const fading = instance.from === void 0 && (instance.fadeDuration ?? 0) > 0 ? { ...instance, from: freezeOf(data, index, instance.startTime) } : instance;
+  writePack(data, index, fading);
+  playback.texture.addUpdateRange(rowStart(index), PACK_STRIDE);
+  playback.texture.needsUpdate = true;
+}
+function freezeOf(data, index, time) {
+  const outgoing = readPack(data, index);
+  const { row } = resolveVATFrame(outgoing, time);
+  return {
+    startFrame: outgoing.clip.startFrame,
+    frames: outgoing.clip.frames,
+    // The row the instance is actually displaying at that moment — so a fade
+    // out of a finished one-shot freezes the end pose it was holding, not the
+    // first row of a clip it stopped playing seconds ago.
+    //
+    // Named as the phase at the *centre* of that row rather than the playback
+    // phase itself, because {@link fadeRowOf} is what reads it back and the two
+    // do not spread a phase the same way: a bouncing ping-pong is up to a row
+    // apart between them, and rounding in a shader could cost another. Half a
+    // row of slack costs nothing and lands all three decodes on this row.
+    phase: (row - outgoing.clip.startFrame + 0.5) / outgoing.clip.frames
+  };
+}
+function endsAt(instance) {
+  const { repetitions, speed } = resolvedPlaybackOf(instance);
+  if (repetitions === INFINITE_REPETITIONS || speed <= 0) return null;
+  const duration = instance.clip.frames / instance.clip.fps;
+  return instance.startTime + duration * repetitions / speed;
+}
+
+export { EndMode, FORWARD_ONLY_REASON, INFINITE_REPETITIONS, LIBRARY_PLAYBACK_DEFAULTS, LoopMode, MAX_FADE_DURATION, MAX_TEXTURE_SIZE, PACK_TEXELS, createVATPlaybackTexture, endsAt, makeVATTexture, resolveVATFrame, setVATInstance };