castle-web-cli 0.4.84 → 0.4.86

package/kits/physics-2d/behaviors/Collider.jsx

@@ -0,0 +1,213 @@
+import React, { useState } from 'react';
+import { Icon, NumberField, Panel, SelectField } from '../engine/ui';
+import { AutoFields, overrideProps } from '../engine/autoInspector';
+import { computeAutoFit, getColliderRect, getColliderShape, intersects } from '../engine/collider';
+import { extensionDefaultProps } from '../engine/behaviorExtensions';
+
+// Collapsible "Dimensions" section. The header row's label lines up exactly with
+// the field labels above/below (both start at the panel body's 16px left pad);
+// the open/closed caret floats in the left gutter without shifting the label.
+// `margin-bottom: 12px` matches a field row's `padding-bottom`, so the gap to
+// the next entry is the same whether the section is open or closed.
+const dimHeaderRowStyle = {
+  position: 'relative',
+  display: 'flex',
+  alignItems: 'center',
+  gap: 10,
+  minHeight: 28,
+  margin: '0 0 12px',
+};
+const dimToggleStyle = {
+  display: 'inline-flex',
+  alignItems: 'center',
+  background: 'none',
+  border: 'none',
+  padding: 0,
+  margin: 0,
+  color: 'var(--castle-inspector-text)',
+  fontFamily: 'inherit',
+  fontSize: 14,
+  cursor: 'pointer',
+};
+// The caret sits in the panel's left gutter (label column starts at x=16).
+const dimCaretStyle = {
+  position: 'absolute',
+  left: -14,
+  top: '50%',
+  transform: 'translateY(-50%)',
+  display: 'inline-flex',
+  alignItems: 'center',
+  fontSize: 11,
+  opacity: 0.65,
+};
+const autoFitLinkStyle = {
+  background: 'none',
+  border: 'none',
+  padding: 0,
+  color: '#4aa3ff',
+  fontFamily: 'inherit',
+  fontSize: 13,
+  cursor: 'pointer',
+};
+const dimBodyStyle = { paddingLeft: 14 };
+
+export class Collider {
+  static behaviorName = 'Collider';
+
+  static defaultProps = {
+    shape: 'box',
+    // width/height/radius are intentionally NOT defaulted: an unset size means
+    // "match the actor's Layout box" (see engine/collider.js manualRect and the
+    // effective values in the inspector). Defaulting them to a fixed number made
+    // every collider shrink to that number instead of tracking the actor.
+    radius: 0,
+    offsetX: 0,
+    offsetY: 0,
+    // `isTrigger` marks a sensor: it still reports overlaps (draws yellow, reads
+    // as a pass-through zone for pickup/goal logic) but does not block on its
+    // own -- collisions are data you act on. Kit modules can register MORE
+    // Collider fields from outside this file (the physics module adds
+    // bounciness/friction material); see engine/behaviorExtensions.js. That's
+    // why this file is byte-identical across kits -- the physics-only fields
+    // live in physics/extensions/, not here.
+    isTrigger: false,
+    debug: false,
+    ...extensionDefaultProps('Collider'),
+  };
+
+  constructor(props) {
+    this.props = props;
+  }
+
+  // Seed props when the collider is first added to an actor: snap it to the
+  // sprite's opaque-pixel bounds (what "Auto-fit to sprite" computes) so a new
+  // collider frames the art rather than the whole Layout box. Falls back to the
+  // unset (Layout-box) size when there's nothing to fit to -- no sprite, tile
+  // mode, or transparent art. The editor's addBehavior calls this (see
+  // editors/SceneEditor.jsx initialBehaviorProps).
+  static initialProps(actor, ctx) {
+    const fit = computeAutoFit(actor, ctx?.sprites);
+    return fit ? { ...Collider.defaultProps, ...fit } : { ...Collider.defaultProps };
+  }
+
+  draw(actor, scene, ctx, options) {
+    if (!options.showDebugColliders && !this.props.debug) return;
+    const geom = getColliderShape(actor, scene.sprites);
+    if (!geom) return;
+    // A sensor (isTrigger) reads as a pass-through zone; a solid as a wall.
+    const isSensor = Boolean(this.props.isTrigger) || this.props.kind === 'pickup';
+    ctx.save();
+    ctx.strokeStyle = isSensor ? '#ffe17a' : '#8db7ff';
+    ctx.lineWidth = 2;
+    if (geom.shape === 'circle') {
+      ctx.beginPath();
+      ctx.arc(geom.cx, geom.cy, geom.radius, 0, Math.PI * 2);
+      ctx.stroke();
+    } else {
+      ctx.strokeRect(geom.x + 1, geom.y + 1, geom.width - 2, geom.height - 2);
+    }
+    ctx.restore();
+  }
+
+  static Inspector({ actor, component, sprites, setComponent, override }) {
+    const [dimOpen, setDimOpen] = useState(true);
+    const layout = actor?.components?.Layout ?? {};
+    const shape = component.shape ?? Collider.defaultProps.shape;
+    // Unset width/height/radius track the actor's Layout box; surface that
+    // effective value so a field never reads blank while the collider is sized.
+    const width = component.width ?? layout.width ?? 50;
+    const height = component.height ?? layout.height ?? 50;
+    const effectiveRadius = component.radius > 0 ? component.radius : Math.min(width, height) / 2;
+
+    // "Auto-fit to sprite": the explicit dims/offset that match the sprite's
+    // opaque-pixel bounds. Only offered when the collider isn't already fitted.
+    const autoFit = computeAutoFit(actor, sprites);
+    let autoFitPatch = null;
+    if (autoFit) {
+      autoFitPatch =
+        shape === 'circle'
+          ? { radius: Math.round(Math.min(autoFit.width, autoFit.height) / 2), offsetX: autoFit.offsetX, offsetY: autoFit.offsetY }
+          : { width: autoFit.width, height: autoFit.height, offsetX: autoFit.offsetX, offsetY: autoFit.offsetY };
+    }
+    const currentValue = (key) => {
+      if (key === 'radius') return effectiveRadius;
+      if (key === 'width') return width;
+      if (key === 'height') return height;
+      return component[key] ?? 0;
+    };
+    const alreadyFitted =
+      autoFitPatch && Object.entries(autoFitPatch).every(([key, value]) => Math.abs(currentValue(key) - value) < 0.6);
+
+    return (
+      <Panel title="Collider" overridden={override?.anyOverridden()}>
+        <SelectField
+          label="Shape"
+          value={component.shape}
+          onChange={(value) => setComponent({ shape: value })}
+          options={['box', 'circle']}
+          {...overrideProps(override, 'shape')}
+        />
+        <div style={dimHeaderRowStyle}>
+          <span style={dimCaretStyle}>
+            <Icon name={dimOpen ? 'chevron-down' : 'chevron-right'} />
+          </span>
+          <button type="button" onClick={() => setDimOpen((open) => !open)} style={dimToggleStyle}>
+            Dimensions
+          </button>
+          {autoFitPatch && !alreadyFitted ? (
+            <button type="button" onClick={() => setComponent(autoFitPatch)} style={autoFitLinkStyle}>
+              Auto-fit to sprite
+            </button>
+          ) : null}
+        </div>
+        {dimOpen ? (
+          <div style={dimBodyStyle}>
+            {shape === 'circle' ? (
+              <NumberField
+                label="Radius"
+                value={effectiveRadius}
+                onChange={(value) => setComponent({ radius: value })}
+                {...overrideProps(override, 'radius')}
+              />
+            ) : (
+              <>
+                <NumberField
+                  label="Width"
+                  value={width}
+                  onChange={(value) => setComponent({ width: value })}
+                  {...overrideProps(override, 'width')}
+                />
+                <NumberField
+                  label="Height"
+                  value={height}
+                  onChange={(value) => setComponent({ height: value })}
+                  {...overrideProps(override, 'height')}
+                />
+              </>
+            )}
+            <AutoFields
+              defaultProps={Collider.defaultProps}
+              component={component}
+              setComponent={setComponent}
+              only={['offsetX', 'offsetY']}
+              override={override}
+            />
+          </div>
+        ) : null}
+        <AutoFields
+          defaultProps={Collider.defaultProps}
+          component={component}
+          setComponent={setComponent}
+          exclude={['shape', 'width', 'height', 'radius', 'offsetX', 'offsetY']}
+          override={override}
+        />
+      </Panel>
+    );
+  }
+}
+
+// Re-exported for callers that need the rect / overlap test outside a running
+// scene (e.g. editors/SelectionOverlay.jsx, which passes the merged preview
+// actors plus the sprites map). See engine/collider.js for the single
+// implementation.
+export { getColliderRect, getColliderShape, intersects };

package/kits/physics-2d/behaviors/Goal.jsx

@@ -0,0 +1,29 @@
+// Goal: a sensor zone that counts when a physics body enters it, and flashes
+// green briefly. Demonstrates the physics collision callbacks + a Collider with
+// `isTrigger: true`. Put it on an actor with a Layout and a trigger Collider.
+export class Goal {
+  static behaviorName = 'Goal';
+
+  static defaultProps = {};
+
+  constructor(props) {
+    this.props = props;
+  }
+
+  onCollisionEnter(actor, scene, other) {
+    if (!other.components.RigidBody) return; // only score moving bodies
+    actor.runtime.scored = (actor.runtime.scored ?? 0) + 1;
+    actor.runtime.flashUntil = scene.time + 0.6;
+  }
+
+  draw(actor, scene, ctx) {
+    const layout = actor.components.Layout;
+    const lit = (actor.runtime.flashUntil ?? 0) > scene.time;
+    ctx.save();
+    ctx.strokeStyle = lit ? '#5ac54f' : 'rgba(255, 235, 87, 0.9)';
+    ctx.lineWidth = 4;
+    ctx.setLineDash([6, 4]);
+    ctx.strokeRect(layout.x + 2, layout.y + 2, layout.width - 4, layout.height - 4);
+    ctx.restore();
+  }
+}

package/kits/physics-2d/behaviors/Layout.jsx

@@ -0,0 +1,53 @@
+export class Layout {
+  static behaviorName = 'Layout';
+
+  static defaultProps = {
+    x: 0,
+    y: 0,
+    z: 0,
+    rotation: 0,
+    width: 50,
+    height: 50,
+    // Show the Layout box (the invisible frame the sprite fills and the collider
+    // derives from) as a dashed outline, in editor and play. Per-actor toggle.
+    debug: false,
+  };
+
+  // Position/rotation/z never inherit from a blueprint: they're always written
+  // as instance values at placement time (z gets an explicit top-of-stack value
+  // on spawn), and a blueprint edit to its own template x/y/z/rotation only
+  // affects newly placed instances, never moves ones already placed. Because
+  // they're always instance-local, they're also never surfaced as blueprint
+  // "overrides" in the inspector. width/height default to inherited (absent).
+  //
+  // Size is width/height in card units -- the same space you compose in. A
+  // user-facing scaleX/scaleY (relative to the sprite's native pixels) was
+  // tried and reverted: it only pays off under pixel-perfect (integer scales),
+  // and in today's card-units model it just adds a conversion + couples Layout
+  // to the Sprite. Revisit scale fields when pixel-perfect mode lands. See
+  // ~/castle/cauldron-rendering-scale-model.md.
+  static propertyMeta = {
+    x: { inherit: false },
+    y: { inherit: false },
+    z: { inherit: false },
+    rotation: { inherit: false },
+  };
+
+  constructor(props) {
+    this.props = props;
+  }
+
+  // Outline the Layout box when `debug` is on. Drawn in the actor's own rotated
+  // frame (so it rotates with the actor), with a distinct dashed lavender style
+  // so it reads separately from the solid collider debug and the selection box.
+  draw(actor, scene, ctx) {
+    if (!this.props.debug) return;
+    const { x, y, width, height } = this.props;
+    ctx.save();
+    ctx.strokeStyle = 'rgba(190, 178, 255, 0.75)';
+    ctx.setLineDash([4, 3]);
+    ctx.lineWidth = 1.5;
+    ctx.strokeRect(x + 0.5, y + 0.5, width - 1, height - 1);
+    ctx.restore();
+  }
+}

package/kits/physics-2d/behaviors/Sprite.jsx

@@ -0,0 +1,352 @@
+import React from 'react';
+import { frameCount, renderSpriteFrame } from '../engine/pxart';
+import { renderSmoothSpriteFrame } from '../engine/pxartSmooth';
+import { spriteDestRect } from '../engine/spriteGeometry';
+import { Panel, SelectField } from '../engine/ui';
+import { AutoFields, overrideProps } from '../engine/autoInspector';
+import { parseTint, tintImageData } from './tint';
+
+// Runtime behavior for the pixel-art Sprite format (.pxart). It looks up the
+// parsed Sprite from the scene's sprite map, composites the current animation
+// frame into a cached offscreen canvas (tinted), and blits it into the actor's
+// Layout box with smoothing disabled — unless the FILE itself opts into a
+// `cornerRadius` (a property of the .pxart asset, not a Sprite prop) greater
+// than 0, in which case the cached canvas holds a corner-rounded vector
+// render instead and gets blitted with smoothing on.
+//
+// Animation plays in `update` and is stored on `actor.runtime.spriteAnim` (the
+// behavior instance is recreated every frame, but the actor object persists in
+// the runtime). In edit-mode previews `update` never runs, so the actor holds
+// frame 0.
+const FALLBACK_FILE = 'drawings/cauldron.pxart';
+
+export class Sprite {
+  static behaviorName = 'Sprite';
+
+  static defaultProps = {
+    file: FALLBACK_FILE,
+    tint: '#ffffffff',
+    playing: true,
+    tag: '',
+    mode: 'cover',
+    tileSize: 50,
+  };
+
+  constructor(props) {
+    this.props = props;
+  }
+
+  resolveSprite(scene) {
+    return scene.sprites?.[this.props.file] ?? scene.sprites?.[FALLBACK_FILE] ?? null;
+  }
+
+  update(actor, scene, dt) {
+    if (!actor.runtime || actor.runtime.collected) return;
+    const sprite = this.resolveSprite(scene);
+    if (!sprite) return;
+    const tag = resolveTag(sprite, this.props.tag);
+    const sequence = frameSequence(sprite, tag);
+    const state = ensureAnimState(actor, sprite, this.props, sequence);
+    if (!this.props.playing) {
+      resetAnimState(state, sequence);
+      state.frameIndex = 0;
+      return;
+    }
+    advanceAnim(state, sprite, sequence, tag, dt);
+  }
+
+  draw(actor, scene, ctx) {
+    if (actor.runtime?.collected) return;
+    const layout = actor.components.Layout;
+    if (!layout) return;
+    const sprite = this.resolveSprite(scene);
+    if (!sprite) return;
+    const total = frameCount(sprite);
+    const frameIndex = Math.min(Math.max(actor.runtime?.spriteAnim?.frameIndex ?? 0, 0), total - 1);
+    const canvas = getSpriteCanvas(sprite, frameIndex, this.props.tint);
+    const prevSmoothing = ctx.imageSmoothingEnabled;
+    // File-level `cornerRadius > 0` sprites are pre-rendered as supersampled,
+    // corner-rounded vector fills (see engine/pxartSmooth.js); blit those with
+    // smoothing on so downscaling to the Layout box stays antialiased. Plain
+    // pixel sprites (`cornerRadius === 0`) keep nearest-neighbor blitting.
+    const smoothing = sprite.cornerRadius > 0;
+
+    // Snap the destination rect to whole device pixels so tiles that abut
+    // exactly in card units (e.g. adjacent 100-unit-wide tiles) land on the
+    // same device-pixel edge instead of each getting its own antialiased
+    // partial-coverage edge, which otherwise leaves faint hairline seams
+    // between them. Rounding each of the four device-space coordinates
+    // independently (rather than rounding position+size) is what makes two
+    // neighbors sharing a card-unit edge compute and round to the identical
+    // device pixel. Skipped when the ctx is rotated/skewed (nonzero b or c,
+    // set by the runtime for `Layout.rotation`), since a rotated rect has no
+    // axis-aligned device edges to snap to.
+    const transform = ctx.getTransform();
+    const tiling = this.props.mode === 'tile';
+    // `cover` scales the art to fill the box preserving aspect ratio, so `dest`
+    // overflows the Layout box and the overflow must be clipped to the box.
+    const covering = this.props.mode === 'cover';
+    // Everything downstream (snapping, tiling's clip box) works off `dest`: the
+    // Layout box itself for every mode except `fit`/`cover`, which resize to the
+    // art's own aspect ratio (see `spriteDestRect`).
+    const dest = spriteDestRect(this.props.mode, layout, canvas);
+    if (transform.b === 0 && transform.c === 0) {
+      const x0 = dest.x * transform.a + transform.e;
+      const y0 = dest.y * transform.d + transform.f;
+      const x1 = (dest.x + dest.width) * transform.a + transform.e;
+      const y1 = (dest.y + dest.height) * transform.d + transform.f;
+      const rx0 = Math.round(x0);
+      const ry0 = Math.round(y0);
+      const rx1 = Math.round(x1);
+      const ry1 = Math.round(y1);
+      ctx.save();
+      ctx.setTransform(1, 0, 0, 1, 0, 0);
+      ctx.imageSmoothingEnabled = smoothing;
+      if (tiling) {
+        drawTilesSnapped(ctx, canvas, this.props.tileSize, dest, transform, x0, y0, rx0, ry0, rx1, ry1);
+      } else {
+        // Clip cover's overflow to the snapped Layout box (undone by restore).
+        if (covering) {
+          const lx0 = Math.round(layout.x * transform.a + transform.e);
+          const ly0 = Math.round(layout.y * transform.d + transform.f);
+          const lx1 = Math.round((layout.x + layout.width) * transform.a + transform.e);
+          const ly1 = Math.round((layout.y + layout.height) * transform.d + transform.f);
+          ctx.beginPath();
+          ctx.rect(lx0, ly0, lx1 - lx0, ly1 - ly0);
+          ctx.clip();
+        }
+        ctx.drawImage(canvas, rx0, ry0, rx1 - rx0, ry1 - ry0);
+      }
+      ctx.restore();
+    } else {
+      ctx.imageSmoothingEnabled = smoothing;
+      if (tiling) {
+        drawTilesUnsnapped(ctx, canvas, this.props.tileSize, dest);
+      } else if (covering) {
+        // Rotated: clip cover's overflow to the Layout box in card units.
+        ctx.save();
+        ctx.beginPath();
+        ctx.rect(layout.x, layout.y, layout.width, layout.height);
+        ctx.clip();
+        ctx.drawImage(canvas, dest.x, dest.y, dest.width, dest.height);
+        ctx.restore();
+      } else {
+        ctx.drawImage(canvas, dest.x, dest.y, dest.width, dest.height);
+      }
+      ctx.imageSmoothingEnabled = prevSmoothing;
+    }
+  }
+
+  static Inspector({ component, setComponent, files, override }) {
+    const spriteFiles = getSpriteFiles(files);
+    return (
+      <Panel title="Sprite" overridden={override?.anyOverridden()}>
+        <SelectField
+          label="File"
+          value={component.file}
+          onChange={(file) => setComponent({ file })}
+          options={spriteFiles}
+          {...overrideProps(override, 'file')}
+        />
+        <SelectField
+          label="Mode"
+          value={component.mode}
+          onChange={(mode) => setComponent({ mode })}
+          options={['stretch', 'fit', 'cover', 'tile']}
+          {...overrideProps(override, 'mode')}
+        />
+        <AutoFields
+          defaultProps={Sprite.defaultProps}
+          component={component}
+          setComponent={setComponent}
+          only={['playing', 'tint', 'tileSize']}
+          override={override}
+        />
+      </Panel>
+    );
+  }
+}
+
+// Guard against non-finite or non-positive tileSize props (e.g. cleared
+// inspector fields), falling back to one 50-unit grid cell.
+function validTileSize(value) {
+  return Number.isFinite(value) && value > 0 ? value : 50;
+}
+
+// Repeat the sprite in device space, clipped to the snapped box. Tile edges
+// are rounded independently from the box's unrounded device origin (x0/y0)
+// using the same per-edge-rounding discipline as the box snap in `draw`, so
+// neighboring tiles within this actor land on identical device pixels with
+// no hairline seams.
+function drawTilesSnapped(ctx, canvas, tileSize, layout, transform, x0, y0, rx0, ry0, rx1, ry1) {
+  const cellHeight = validTileSize(tileSize);
+  const cellWidth = cellHeight * (canvas.width / canvas.height);
+  const cellDeviceWidth = cellWidth * transform.a;
+  const cellDeviceHeight = cellHeight * transform.d;
+  const cols = Math.ceil(layout.width / cellWidth);
+  const rows = Math.ceil(layout.height / cellHeight);
+  ctx.save();
+  ctx.beginPath();
+  ctx.rect(rx0, ry0, rx1 - rx0, ry1 - ry0);
+  ctx.clip();
+  for (let row = 0; row < rows; row++) {
+    const edgeY0 = Math.round(y0 + row * cellDeviceHeight);
+    const edgeY1 = Math.round(y0 + (row + 1) * cellDeviceHeight);
+    for (let col = 0; col < cols; col++) {
+      const edgeX0 = Math.round(x0 + col * cellDeviceWidth);
+      const edgeX1 = Math.round(x0 + (col + 1) * cellDeviceWidth);
+      ctx.drawImage(canvas, edgeX0, edgeY0, edgeX1 - edgeX0, edgeY1 - edgeY0);
+    }
+  }
+  ctx.restore();
+}
+
+// Rotated actors have no axis-aligned device edges to snap to, so tile
+// unsnapped in card units, matching the unsnapped stretch fallback in `draw`.
+function drawTilesUnsnapped(ctx, canvas, tileSize, layout) {
+  const cellHeight = validTileSize(tileSize);
+  const cellWidth = cellHeight * (canvas.width / canvas.height);
+  const cols = Math.ceil(layout.width / cellWidth);
+  const rows = Math.ceil(layout.height / cellHeight);
+  ctx.save();
+  ctx.beginPath();
+  ctx.rect(layout.x, layout.y, layout.width, layout.height);
+  ctx.clip();
+  for (let row = 0; row < rows; row++) {
+    const ty = layout.y + row * cellHeight;
+    for (let col = 0; col < cols; col++) {
+      const tx = layout.x + col * cellWidth;
+      ctx.drawImage(canvas, tx, ty, cellWidth, cellHeight);
+    }
+  }
+  ctx.restore();
+}
+
+// Cache of native-resolution offscreen canvases keyed by sprite, then by
+// `${frameIndex}|${tint}`. A sprite edit produces a fresh Sprite object, so a
+// new object naturally misses the WeakMap and rebuilds.
+const spriteCanvasCache = new WeakMap();
+
+function getSpriteCanvas(sprite, frameIndex, tint) {
+  const key = `${frameIndex}|${tint ?? ''}`;
+  let byKey = spriteCanvasCache.get(sprite);
+  if (!byKey) {
+    byKey = new Map();
+    spriteCanvasCache.set(sprite, byKey);
+  }
+  const cached = byKey.get(key);
+  if (cached) return cached;
+
+  const canvas = document.createElement('canvas');
+  if (sprite.cornerRadius > 0) {
+    renderSmoothSpriteFrame(sprite, frameIndex, canvas, { cornerRadius: sprite.cornerRadius });
+  } else {
+    renderSpriteFrame(sprite, frameIndex, canvas);
+  }
+  const tintRgba = parseTint(tint);
+  if (tintRgba) {
+    const octx = canvas.getContext('2d');
+    if (octx && canvas.width > 0 && canvas.height > 0) {
+      const image = octx.getImageData(0, 0, canvas.width, canvas.height);
+      tintImageData(image.data, tintRgba);
+      octx.putImageData(image, 0, 0);
+    }
+  }
+  byKey.set(key, canvas);
+  return canvas;
+}
+
+// Resolve the active tag: the `tag` prop when it names an existing tag,
+// otherwise the sprite's defaultTag, otherwise null (whole-timeline loop).
+function resolveTag(sprite, tagProp) {
+  const name = tagProp || sprite.defaultTag;
+  if (!name) return null;
+  return sprite.tags.find((candidate) => candidate.name === name) ?? null;
+}
+
+// The ordered list of frame indices to step through, honoring the tag range and
+// direction. No tag => the whole timeline, forward.
+function frameSequence(sprite, tag) {
+  const total = Math.max(frameCount(sprite), 1);
+  let from = 0;
+  let to = total - 1;
+  let direction = 'forward';
+  if (tag) {
+    from = clampIndex(tag.from, total);
+    to = clampIndex(tag.to, total);
+    if (from > to) [from, to] = [to, from];
+    direction = tag.direction;
+  }
+  if (from === to) return [from];
+  const forward = [];
+  for (let i = from; i <= to; i++) forward.push(i);
+  if (direction === 'reverse') return forward.slice().reverse();
+  if (direction === 'pingpong') {
+    const back = [];
+    for (let i = to - 1; i > from; i--) back.push(i);
+    return [...forward, ...back];
+  }
+  return forward;
+}
+
+function clampIndex(value, total) {
+  if (!Number.isInteger(value)) return 0;
+  return Math.min(Math.max(value, 0), total - 1);
+}
+
+function animKey(props) {
+  return `${props.file}|${props.tag ?? ''}`;
+}
+
+// Reset playback state when the sprite identity or active tag changes.
+function ensureAnimState(actor, sprite, props, sequence) {
+  const key = animKey(props);
+  let state = actor.runtime.spriteAnim;
+  if (!state || state.sprite !== sprite || state.key !== key) {
+    state = { sprite, key, pos: 0, elapsedMs: 0, loops: 0, done: false, frameIndex: sequence[0] };
+    actor.runtime.spriteAnim = state;
+  }
+  return state;
+}
+
+function resetAnimState(state, sequence) {
+  state.pos = 0;
+  state.elapsedMs = 0;
+  state.loops = 0;
+  state.done = false;
+  state.frameIndex = sequence[0];
+}
+
+// Advance the playhead by `dt` seconds, stepping frames by their durationMs and
+// honoring `repeat` (0 = loop forever; otherwise hold the last frame when done).
+function advanceAnim(state, sprite, sequence, tag, dt) {
+  if (state.done) {
+    state.frameIndex = sequence[state.pos];
+    return;
+  }
+  const repeat = tag ? tag.repeat : 0;
+  state.elapsedMs += dt * 1000;
+  let guard = 0;
+  while (guard++ < 1000) {
+    const frame = sequence[state.pos];
+    const duration = sprite.frames[frame]?.durationMs ?? sprite.defaultDurationMs;
+    if (!(duration > 0) || state.elapsedMs < duration) break;
+    state.elapsedMs -= duration;
+    state.pos += 1;
+    if (state.pos >= sequence.length) {
+      state.loops += 1;
+      if (repeat !== 0 && state.loops >= repeat) {
+        state.pos = sequence.length - 1;
+        state.done = true;
+        state.elapsedMs = 0;
+        break;
+      }
+      state.pos = 0;
+    }
+  }
+  state.frameIndex = sequence[state.pos];
+}
+
+function getSpriteFiles(files) {
+  return Object.keys(files).filter((path) => path.endsWith('.pxart'));
+}