@3driseai/3drise-viewer 0.1.24 → 0.1.26

package/dist/animationsV2/ClipsRuntime.js

@@ -0,0 +1,476 @@
+import { getAtPath, sampleTrack } from './clipUtils.js';
+import { applyValue, clearApplierCaches } from './appliers.js';
+import { restoreNodeTrack } from './nodeTracks.js';
+import { entryLocalTime, isEntryActive, resolveSequence, } from './sequenceUtils.js';
+const targetKey = (state, node, path) => `${state}|${node ?? ''}|${path}`;
+class ClipsRuntime {
+    clips = new Map();
+    sequences = new Map();
+    ctx = null;
+    order = 0;
+    version = 0;
+    listeners = new Set();
+    eventListeners = new Set();
+    /** tracks whose authored value must be written back on the next tick */
+    pendingRestore = [];
+    /** last written value per property (targetKey -> JSON) */
+    written = new Map();
+    // --- wiring -------------------------------------------------------------------
+    setContext(ctx) {
+        this.ctx = ctx;
+        this.written.clear();
+        clearApplierCaches();
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    getVersion() { return this.version; }
+    on(listener) {
+        this.eventListeners.add(listener);
+        return () => this.eventListeners.delete(listener);
+    }
+    // --- clips ----------------------------------------------------------------------
+    play(clip, opts = {}) {
+        const existing = this.clips.get(clip.id);
+        const direction = opts.reverse ? -1 : 1;
+        let time = opts.from ?? existing?.time ?? 0;
+        // Restart from the edge when playing past the end.
+        if (direction === 1 && time >= clip.duration)
+            time = 0;
+        if (direction === -1 && time <= 0)
+            time = clip.duration;
+        this.clips.set(clip.id, { clip, time, speed: opts.speed ?? 1, direction, playing: true, order: ++this.order });
+        this.emit({ type: 'start', kind: 'clip', id: clip.id });
+        this.bump();
+    }
+    pause(clipId) {
+        const inst = this.clips.get(clipId);
+        if (!inst)
+            return;
+        inst.playing = false;
+        this.bump();
+    }
+    resume(clipId) {
+        const inst = this.clips.get(clipId);
+        if (!inst)
+            return;
+        inst.playing = true;
+        this.bump();
+    }
+    /** Stop and put the clip's properties back to their authored values. */
+    stop(clipId) {
+        const inst = this.clips.get(clipId);
+        if (!inst)
+            return;
+        this.clips.delete(clipId);
+        this.pendingRestore.push(...inst.clip.tracks);
+        this.bump();
+    }
+    /** Hold the clip at t (seconds) — the editor playhead, or seek() from outside. */
+    pose(clip, t) {
+        const inst = this.clips.get(clip.id);
+        const time = Math.min(clip.duration, Math.max(0, t));
+        if (inst) {
+            inst.clip = clip;
+            inst.time = time;
+        }
+        else {
+            this.clips.set(clip.id, { clip, time, speed: 1, direction: 1, playing: false, order: ++this.order });
+        }
+        this.bump();
+    }
+    /** The clip data changed (editor edit): keep time and play state, use the new tracks. */
+    updateClip(clip) {
+        const inst = this.clips.get(clip.id);
+        if (!inst)
+            return;
+        const removed = inst.clip.tracks.filter(t => !clip.tracks.some(n => n.id === t.id));
+        if (removed.length)
+            this.pendingRestore.push(...removed);
+        inst.clip = clip;
+        inst.time = Math.min(inst.time, clip.duration);
+        this.written.clear(); // values may have changed under the same time
+        this.bump();
+    }
+    getTime(clipId) { return this.clips.get(clipId)?.time ?? 0; }
+    isPlaying(clipId) { return !!this.clips.get(clipId)?.playing; }
+    isActive(clipId) { return this.clips.has(clipId); }
+    /** Value of a track at the clip's current time (the panel's value column). */
+    sampleAt(clip, track) {
+        return sampleTrack(track, this.getTime(clip.id));
+    }
+    // --- sequences ------------------------------------------------------------------
+    /**
+     * Play a sequence. `reverse` defaults to the sequence's own; `from` is sequence
+     * seconds (defaults to the current time, or the start edge of the run).
+     */
+    playSequence(seq, clips, opts = {}) {
+        const existing = this.sequences.get(seq.id);
+        const schedule = resolveSequence(seq, clips);
+        const direction = (opts.reverse ?? seq.reverse) ? -1 : 1;
+        const driven = isDriven(seq);
+        let time = opts.from ?? existing?.time ?? (direction === 1 ? 0 : schedule.duration);
+        // A played sequence restarts from its start edge; a driven one stays where it is.
+        if (!driven && direction === 1 && time >= schedule.duration)
+            time = 0;
+        if (!driven && direction === -1 && time <= 0)
+            time = schedule.duration;
+        this.sequences.set(seq.id, {
+            driven,
+            target: time,
+            seq,
+            schedule,
+            time,
+            speed: opts.speed ?? 1,
+            direction,
+            baseDirection: direction,
+            playing: true,
+            order: ++this.order,
+            active: existing?.active ?? new Set(),
+        });
+        this.emit({ type: 'start', kind: 'sequence', id: seq.id });
+        this.bump();
+    }
+    // --- input drivers --------------------------------------------------------------
+    /** Driven sequences that are running — what the input layer (ClipPlayer) feeds. */
+    getDrivenSequences() {
+        const out = [];
+        for (const inst of this.sequences.values()) {
+            if (!inst.driven || !inst.playing)
+                continue;
+            out.push({ id: inst.seq.id, driver: inst.seq.driver, settings: inst.seq.driverSettings, progress: this.progressOf(inst, inst.target) });
+        }
+        return out;
+    }
+    /**
+     * Set a sequence's position, 0–1 along its own direction (reverse flips it). A
+     * driven sequence eases there (its smoothing); any other is posed there at once.
+     */
+    setSequenceProgress(seqId, progress) {
+        const inst = this.sequences.get(seqId);
+        if (!inst)
+            return false;
+        const T = this.timeOf(inst, progress);
+        inst.target = T;
+        if (!inst.driven)
+            inst.time = T;
+        this.bump();
+        return true;
+    }
+    /**
+     * Move a driven sequence's target by `delta` of its length (the wheel). Returns
+     * false when it is already at that end — the caller then lets the event through
+     * (page scroll), so a visitor is never trapped inside the canvas.
+     */
+    nudgeSequenceProgress(seqId, delta) {
+        const inst = this.sequences.get(seqId);
+        if (!inst)
+            return false;
+        const p = this.progressOf(inst, inst.target);
+        const next = Math.min(1, Math.max(0, p + delta));
+        if (Math.abs(next - p) < 1e-6)
+            return false;
+        inst.target = this.timeOf(inst, next);
+        this.bump();
+        return true;
+    }
+    getSequenceProgress(seqId) {
+        const inst = this.sequences.get(seqId);
+        return inst ? this.progressOf(inst, inst.time) : 0;
+    }
+    progressOf(inst, T) {
+        const total = inst.schedule.duration;
+        if (total <= 0)
+            return 0;
+        const p = Math.min(1, Math.max(0, T / total));
+        return inst.seq.reverse ? 1 - p : p;
+    }
+    timeOf(inst, progress) {
+        const p = Math.min(1, Math.max(0, Number.isFinite(progress) ? progress : 0));
+        return (inst.seq.reverse ? 1 - p : p) * inst.schedule.duration;
+    }
+    pauseSequence(seqId) {
+        const inst = this.sequences.get(seqId);
+        if (!inst)
+            return;
+        inst.playing = false;
+        this.bump();
+    }
+    resumeSequence(seqId) {
+        const inst = this.sequences.get(seqId);
+        if (!inst)
+            return;
+        inst.playing = true;
+        this.bump();
+    }
+    /** Stop and put every property the sequence drove back to its authored value. */
+    stopSequence(seqId) {
+        const inst = this.sequences.get(seqId);
+        if (!inst)
+            return;
+        this.sequences.delete(seqId);
+        inst.schedule.entries.forEach(e => this.pendingRestore.push(...e.clip.tracks));
+        this.bump();
+    }
+    /** Hold the sequence at T (sequence seconds) — the panel's scrub, or seek(). */
+    poseSequence(seq, clips, T) {
+        const inst = this.sequences.get(seq.id);
+        if (inst) {
+            // Edited data goes through the re-resolve path (restores what the old schedule drove).
+            if (inst.seq !== seq)
+                this.updateSequence(seq, clips);
+            inst.time = Math.min(inst.schedule.duration, Math.max(0, T));
+            inst.target = inst.time;
+        }
+        else {
+            const schedule = resolveSequence(seq, clips);
+            const time = Math.min(schedule.duration, Math.max(0, T));
+            this.sequences.set(seq.id, {
+                seq, schedule, time, target: time, driven: false,
+                speed: 1, direction: 1, baseDirection: 1, playing: false, order: ++this.order, active: new Set(),
+            });
+        }
+        this.bump();
+    }
+    /** The sequence or one of its clips changed: re-resolve, keep time and play state. */
+    updateSequence(seq, clips) {
+        const inst = this.sequences.get(seq.id);
+        if (!inst)
+            return;
+        // Restore everything the old schedule drove; whatever is still driven re-writes this frame.
+        inst.schedule.entries.forEach(e => this.pendingRestore.push(...e.clip.tracks));
+        inst.seq = seq;
+        inst.schedule = resolveSequence(seq, clips);
+        inst.time = Math.min(inst.time, inst.schedule.duration);
+        inst.target = Math.min(inst.target, inst.schedule.duration);
+        // The driver can change while it runs (editing): a running sequence switches mode.
+        if (inst.playing)
+            inst.driven = isDriven(seq);
+        inst.active = new Set();
+        this.bump();
+    }
+    getSequenceTime(seqId) { return this.sequences.get(seqId)?.time ?? 0; }
+    getSequenceDuration(seqId) { return this.sequences.get(seqId)?.schedule.duration ?? 0; }
+    isSequencePlaying(seqId) { return !!this.sequences.get(seqId)?.playing; }
+    isSequenceActive(seqId) { return this.sequences.has(seqId); }
+    // --- frame ------------------------------------------------------------------
+    tick(delta) {
+        const ctx = this.ctx;
+        if (!ctx)
+            return;
+        const dt = Math.min(delta, 0.1);
+        let anyPlaying = false;
+        for (const inst of this.clips.values()) {
+            if (!inst.playing)
+                continue;
+            anyPlaying = true;
+            this.advanceClip(inst, dt);
+        }
+        for (const inst of [...this.sequences.values()]) {
+            if (!inst.playing)
+                continue;
+            anyPlaying = true;
+            this.advanceSequence(inst, dt);
+        }
+        // Sequence entries that stopped writing (scrubbed back before their start, or
+        // a 'restore' clip past its end) give their properties back.
+        for (const inst of this.sequences.values()) {
+            const now = new Set();
+            for (const e of inst.schedule.entries)
+                if (isEntryActive(e, inst.time))
+                    now.add(e.id);
+            for (const id of inst.active) {
+                if (now.has(id))
+                    continue;
+                const e = inst.schedule.entries.find(x => x.id === id);
+                if (e)
+                    this.pendingRestore.push(...e.clip.tracks);
+            }
+            inst.active = now;
+        }
+        if (this.pendingRestore.length)
+            this.runRestores(ctx);
+        // Proposals in priority order; the last one per property wins.
+        const winners = new Map();
+        for (const p of this.proposals())
+            winners.set(targetKey(p.state, p.node, p.path), p);
+        for (const [key, p] of winners) {
+            const json = JSON.stringify(p.value);
+            if (this.written.get(key) === json)
+                continue;
+            // Recorded only when it landed: a target that is not mounted yet (a model still
+            // loading) is retried next frame instead of being skipped for good.
+            if (applyValue(ctx, p.state, p.path, p.value, p.node))
+                this.written.set(key, json);
+        }
+        if (anyPlaying)
+            this.bump();
+    }
+    /** Every driver's values for this frame, lowest priority first. */
+    *proposals() {
+        const drivers = [];
+        for (const inst of this.clips.values()) {
+            drivers.push({ order: inst.order, run: () => sampleTracks(inst.clip.tracks, inst.time) });
+        }
+        for (const inst of this.sequences.values()) {
+            drivers.push({
+                order: inst.order,
+                run: function* () {
+                    for (const e of inst.schedule.entries) {
+                        if (!inst.active.has(e.id))
+                            continue;
+                        yield* sampleTracks(e.clip.tracks, entryLocalTime(e, inst.time));
+                    }
+                },
+            });
+        }
+        drivers.sort((a, b) => a.order - b.order);
+        for (const d of drivers)
+            yield* d.run();
+    }
+    runRestores(ctx) {
+        const tracks = this.pendingRestore;
+        this.pendingRestore = [];
+        const done = new Set();
+        for (const track of tracks) {
+            const key = targetKey(track.state, track.node, track.path);
+            if (done.has(key))
+                continue;
+            done.add(key);
+            this.written.delete(key);
+            if (track.node) {
+                // Node tracks restore their exact pre-animation snapshot (see nodeTracks).
+                const node = track.node;
+                restoreNodeTrack(track.state, node, track.path, (path) => this.isDriven(track.state, node, path));
+                continue;
+            }
+            // Another driver may still own this property; it re-writes this frame.
+            const authored = getAtPath(ctx.getSettings(track.state), track.path);
+            if (authored !== undefined)
+                applyValue(ctx, track.state, track.path, authored);
+        }
+    }
+    /** Whether any active driver still has a track on (state, node, path). */
+    isDriven(state, node, path) {
+        const hit = (t) => t.state === state && t.node === node && t.path === path && !t.muted;
+        for (const inst of this.clips.values())
+            if (inst.clip.tracks.some(hit))
+                return true;
+        for (const inst of this.sequences.values()) {
+            for (const e of inst.schedule.entries)
+                if (inst.active.has(e.id) && e.clip.tracks.some(hit))
+                    return true;
+        }
+        return false;
+    }
+    advanceClip(inst, delta) {
+        const { clip } = inst;
+        inst.time += delta * inst.speed * inst.direction;
+        const atEnd = inst.direction === 1 ? inst.time >= clip.duration : inst.time <= 0;
+        if (!atEnd)
+            return;
+        if (clip.yoyo) {
+            // Bounce at either edge. Without loop, stop after the return leg.
+            const returning = inst.direction === -1;
+            inst.time = inst.direction === 1 ? clip.duration : 0;
+            if (returning && !clip.loop)
+                return this.finishClip(inst);
+            inst.direction = inst.direction === 1 ? -1 : 1;
+            if (returning)
+                this.emit({ type: 'loop', kind: 'clip', id: clip.id });
+            return;
+        }
+        if (clip.loop) {
+            inst.time = inst.direction === 1 ? inst.time - clip.duration : inst.time + clip.duration;
+            this.emit({ type: 'loop', kind: 'clip', id: clip.id });
+            return;
+        }
+        inst.time = inst.direction === 1 ? clip.duration : 0;
+        this.finishClip(inst);
+    }
+    finishClip(inst) {
+        inst.playing = false;
+        this.emit({ type: 'end', kind: 'clip', id: inst.clip.id });
+        if (inst.clip.endMode === 'restore')
+            this.stop(inst.clip.id);
+    }
+    /**
+     * Same edge rules as a clip, on the sequence clock. "Forward" is the run's base
+     * direction: a reversed run starts at the end and finishes at 0.
+     */
+    advanceSequence(inst, delta) {
+        const { seq } = inst;
+        const total = inst.schedule.duration;
+        if (inst.driven) {
+            // Ease toward the input's target. `smoothing` ≈ seconds to settle; 0 = exact.
+            const diff = inst.target - inst.time;
+            if (Math.abs(diff) < 1e-4) {
+                inst.time = inst.target;
+                return;
+            }
+            const smoothing = Math.max(0, seq.driverSettings?.smoothing ?? 0);
+            const k = smoothing <= 0 ? 1 : 1 - Math.exp(-delta * 4 / smoothing);
+            inst.time += diff * k;
+            return;
+        }
+        if (total <= 0) {
+            inst.time = 0;
+            return this.finishSequence(inst);
+        }
+        inst.time += delta * inst.speed * inst.direction;
+        const atEnd = inst.direction === 1 ? inst.time >= total : inst.time <= 0;
+        if (!atEnd)
+            return;
+        const edge = inst.direction === 1 ? total : 0;
+        const returning = inst.direction !== inst.baseDirection;
+        if (seq.yoyo) {
+            inst.time = edge;
+            if (returning && !seq.loop)
+                return this.finishSequence(inst);
+            inst.direction = inst.direction === 1 ? -1 : 1;
+            if (returning)
+                this.emit({ type: 'loop', kind: 'sequence', id: seq.id });
+            return;
+        }
+        if (seq.loop) {
+            // Jump back to the run's start edge. Entries past their window restore next tick.
+            inst.time = inst.direction === 1 ? inst.time - total : inst.time + total;
+            this.emit({ type: 'loop', kind: 'sequence', id: seq.id });
+            return;
+        }
+        inst.time = edge;
+        this.finishSequence(inst);
+    }
+    finishSequence(inst) {
+        inst.playing = false;
+        this.emit({ type: 'end', kind: 'sequence', id: inst.seq.id });
+        if (inst.seq.endMode === 'restore')
+            this.stopSequence(inst.seq.id);
+    }
+    emit(e) {
+        this.eventListeners.forEach(l => { try {
+            l(e);
+        }
+        catch (err) {
+            console.error('[ClipsRuntime] listener failed', err);
+        } });
+    }
+    bump() {
+        this.version += 1;
+        this.listeners.forEach(l => l());
+    }
+}
+const isDriven = (seq) => !!seq.driver && seq.driver !== 'time';
+function* sampleTracks(tracks, t) {
+    for (const track of tracks) {
+        if (track.muted || track.keys.length === 0)
+            continue;
+        const value = sampleTrack(track, t);
+        if (value === undefined)
+            continue;
+        yield { state: track.state, node: track.node, path: track.path, value };
+    }
+}
+const clipsRuntime = new ClipsRuntime();
+export default clipsRuntime;

package/dist/animationsV2/appliers.d.ts

@@ -0,0 +1,16 @@
+import type { PerspectiveCamera } from 'three';
+import type { KeyValue } from './types';
+export interface ApplyContext {
+    camera: PerspectiveCamera | null;
+    /** drei OrbitControls (makeDefault), when present */
+    controls: any;
+    /** Authored settings for an element (object id or 'camera'), action patches included. */
+    getSettings: (state: string) => any;
+}
+export declare function clearApplierCaches(): void;
+/** Write one value. Unknown paths are ignored (the track picker never offers them). */
+/** Write one value to the live scene. False when its target is not mounted yet. */
+export declare function applyValue(ctx: ApplyContext, state: string, path: string, value: KeyValue, node?: string): boolean;
+/** Whether a (state, path) has an applier — used by the track picker. */
+export declare function isApplicable(state: string, path: string): boolean;
+//# sourceMappingURL=appliers.d.ts.map

package/dist/animationsV2/appliers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appliers.d.ts","sourceRoot":"","sources":["../../src/animationsV2/appliers.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAC;AAc/C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGxC,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACjC,qDAAqD;IACrD,QAAQ,EAAE,GAAG,CAAC;IACd,yFAAyF;IACzF,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,GAAG,CAAC;CACrC;AAWD,wBAAgB,kBAAkB,IAAI,IAAI,CAIzC;AAqKD,uFAAuF;AACvF,mFAAmF;AACnF,wBAAgB,UAAU,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAIlH;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjE"}