castle-web-cli 0.4.84 → 0.4.85

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'));
+}

package/kits/physics-2d/behaviors/tint.js

@@ -0,0 +1,47 @@
+// Tint helpers for the pixel-art Sprite behavior. A tint is a hex color
+// (#rrggbb / #rrggbbaa) multiplied channel-wise into each source pixel. White
+// (#ffffffff) means "no change".
+
+// Parse a hex color into [r, g, b, a] channels (0-255). Returns null when the
+// string is not a hex color so callers can fall back to the raw color.
+export function parseHexColor(color) {
+  const hex = String(color).trim().replace(/^#/, '');
+  if (hex.length !== 6 && hex.length !== 8) return null;
+  if (!/^[0-9a-fA-F]+$/.test(hex)) return null;
+  const r = parseInt(hex.slice(0, 2), 16);
+  const g = parseInt(hex.slice(2, 4), 16);
+  const b = parseInt(hex.slice(4, 6), 16);
+  const a = hex.length === 8 ? parseInt(hex.slice(6, 8), 16) : 255;
+  return [r, g, b, a];
+}
+
+// Returns the tint as [r, g, b, a] channels, or null when there is no tint or
+// the tint is white (#ffffffff) -- both meaning "no change".
+export function parseTint(tint) {
+  if (!tint) return null;
+  const rgba = parseHexColor(tint);
+  if (!rgba) return null;
+  if (rgba[0] === 255 && rgba[1] === 255 && rgba[2] === 255 && rgba[3] === 255) {
+    return null;
+  }
+  return rgba;
+}
+
+// Multiply each channel of a pixel color (hex string) by the tint (0-255).
+export function applyTint(color, tint) {
+  const rgba = parseHexColor(color);
+  if (!rgba) return color;
+  const out = rgba.map((channel, i) => Math.round((channel * tint[i]) / 255));
+  return '#' + out.map((channel) => channel.toString(16).padStart(2, '0')).join('');
+}
+
+// Multiply an ImageData buffer's RGBA channels in place by the tint (0-255).
+// Used to tint an already-rendered offscreen canvas (the Sprite path).
+export function tintImageData(data, tint) {
+  for (let i = 0; i < data.length; i += 4) {
+    data[i] = Math.round((data[i] * tint[0]) / 255);
+    data[i + 1] = Math.round((data[i + 1] * tint[1]) / 255);
+    data[i + 2] = Math.round((data[i + 2] * tint[2]) / 255);
+    data[i + 3] = Math.round((data[i + 3] * tint[3]) / 255);
+  }
+}

package/kits/physics-2d/blueprints/ball.scene

@@ -0,0 +1,14 @@
+{
+  "name": "Ball",
+  "actors": [
+    {
+      "components": {
+        "Layout": { "width": 44, "height": 44, "z": 2 },
+        "Sprite": { "file": "drawings/cauldron.pxart", "mode": "fit" },
+        "Collider": { "shape": "circle", "width": 40, "height": 40, "bounciness": 0.6, "friction": 0.05 },
+        "RigidBody": { "bodyType": "dynamic", "gravityScale": 1, "drag": 0.005 },
+        "Slingshot": { "speed": 0.1, "maxDrag": 200 }
+      }
+    }
+  ]
+}

package/kits/physics-2d/blueprints/block.scene

@@ -0,0 +1,12 @@
+{
+  "name": "Block",
+  "actors": [
+    {
+      "components": {
+        "Layout": { "width": 100, "height": 40, "z": 1 },
+        "Sprite": { "file": "drawings/block.pxart", "mode": "tile", "tileSize": 20 },
+        "Collider": { "bounciness": 0.4, "friction": 0.2 }
+      }
+    }
+  ]
+}

package/kits/physics-2d/blueprints/cauldron.scene

@@ -0,0 +1,18 @@
+{
+  "name": "Cauldron",
+  "actors": [
+    {
+      "components": {
+        "Layout": {
+          "width": 100,
+          "height": 100,
+          "z": 1
+        },
+        "Sprite": {
+          "file": "drawings/cauldron.pxart"
+        },
+        "Collider": {}
+      }
+    }
+  ]
+}

package/kits/physics-2d/blueprints/crate.scene

@@ -0,0 +1,14 @@
+{
+  "name": "Crate",
+  "actors": [
+    {
+      "components": {
+        "Layout": { "width": 48, "height": 48, "z": 2 },
+        "Sprite": { "file": "drawings/block.pxart", "mode": "fit" },
+        "Collider": { "shape": "box", "width": 46, "height": 46, "bounciness": 0.2, "friction": 0.3 },
+        "RigidBody": { "bodyType": "dynamic", "gravityScale": 1, "drag": 0.02 },
+        "Draggable": {}
+      }
+    }
+  ]
+}

package/kits/physics-2d/blueprints/goal.scene

@@ -0,0 +1,12 @@
+{
+  "name": "Goal",
+  "actors": [
+    {
+      "components": {
+        "Layout": { "width": 110, "height": 34, "z": 3 },
+        "Collider": { "width": 110, "height": 34, "isTrigger": true },
+        "Goal": {}
+      }
+    }
+  ]
+}

package/kits/physics-2d/castle.json

@@ -0,0 +1,13 @@
+{
+  "editor": {
+    "initialPanels": [
+      {
+        "width": 400,
+        "column": [{ "type": "playtest" }, { "type": "files" }]
+      },
+      { "type": "editor", "file": "scenes/main.scene" }
+    ],
+    "hiddenPaths": [],
+    "visiblePaths": ["drawings/**", "scenes/**", "blueprints/**", "behaviors/**"]
+  }
+}