castle-web-cli 0.4.71 → 0.4.73

package/kits/basic-2d/editors/pxArtPlayback.js

@@ -0,0 +1,92 @@
+import { useEffect, useRef, useState } from 'react';
+import { frameCount } from '../engine/pxart';
+
+// Preview-playback helpers for the PxArt editor. These mirror the Sprite
+// behavior's runtime semantics (frame stepping by durationMs, tag range +
+// direction, repeat) so the in-editor preview agrees with how the sprite plays
+// at runtime — but they run on a rAF clock and drive a React index rather than
+// the engine's actor state.
+
+// Resolve the tag that should drive the preview: an explicit name, else the
+// sprite's defaultTag, else null (whole-timeline forward loop).
+export function resolveActiveTag(sprite, name) {
+  const wanted = name || sprite.defaultTag;
+  if (!wanted) return null;
+  return sprite.tags.find((tag) => tag.name === wanted) ?? null;
+}
+
+function tagBounds(tag, total) {
+  if (!tag) return { lo: 0, hi: total - 1, dir: 'forward' };
+  let lo = Math.min(Math.max(tag.from, 0), total - 1);
+  let hi = Math.min(Math.max(tag.to, 0), total - 1);
+  if (lo > hi) [lo, hi] = [hi, lo];
+  return { lo, hi, dir: tag.direction };
+}
+
+// The ordered frame indices the preview steps through for a tag (or the whole
+// timeline). Pingpong appends the interior frames in reverse; reverse flips.
+export function playbackOrder(sprite, tag) {
+  const total = Math.max(frameCount(sprite), 1);
+  const { lo, hi, dir } = tagBounds(tag, total);
+  const order = [];
+  for (let f = lo; f <= hi; f++) order.push(f);
+  if (dir === 'reverse') order.reverse();
+  else if (dir === 'pingpong') for (let f = hi - 1; f > lo; f--) order.push(f);
+  return order.length ? order : [0];
+}
+
+// The per-step durations (ms) aligned to a playback order.
+export function frameDurations(sprite, order) {
+  return order.map((f) => sprite.frames[f]?.durationMs ?? sprite.defaultDurationMs);
+}
+
+// Advance a mutable playhead {pos, acc, loops, done} by the elapsed budget in
+// `acc`, honoring repeat (0 = forever; otherwise hold the final step).
+function step(state, durations, length, repeat) {
+  let guard = 0;
+  while (!state.done && guard++ < 1000) {
+    const dur = durations[state.pos] > 0 ? durations[state.pos] : 100;
+    if (state.acc < dur) break;
+    state.acc -= dur;
+    state.pos += 1;
+    if (state.pos < length) continue;
+    state.loops += 1;
+    if (repeat !== 0 && state.loops >= repeat) {
+      state.pos = length - 1;
+      state.done = true;
+    } else {
+      state.pos = 0;
+    }
+  }
+}
+
+// Drive a preview frame index while `playing`. Reads the latest order/durations
+// through a ref so a re-derived sprite object doesn't restart playback; only
+// toggling `playing` (re)starts the clock. Returns `fallbackIndex` when paused.
+export function usePreviewPlayback({ order, durations, repeat }, playing, fallbackIndex) {
+  const [pos, setPos] = useState(0);
+  const dataRef = useRef({ order, durations, repeat });
+  dataRef.current = { order, durations, repeat };
+
+  useEffect(() => {
+    if (!playing) return undefined;
+    const playhead = { pos: 0, acc: 0, loops: 0, done: false };
+    setPos(0);
+    let raf = 0;
+    let last = performance.now();
+    const tick = (now) => {
+      const data = dataRef.current;
+      playhead.acc += now - last;
+      last = now;
+      step(playhead, data.durations, data.order.length, data.repeat);
+      setPos(Math.min(playhead.pos, data.order.length - 1));
+      raf = requestAnimationFrame(tick);
+    };
+    raf = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(raf);
+  }, [playing]);
+
+  if (!playing) return fallbackIndex;
+  const order2 = dataRef.current.order;
+  return order2[Math.min(pos, order2.length - 1)] ?? fallbackIndex;
+}