castle-web-cli 0.4.84 → 0.4.86

package/kits/physics-2d/engine/collider.js

@@ -0,0 +1,200 @@
+// Single source of truth for the Collider rect. Lives in engine/ (not
+// behaviors/) so SceneRuntime can use it directly, with behaviors/Collider.jsx
+// (its `draw`, and its `getColliderRect`/`intersects` re-exports) delegating
+// here instead of keeping a second, drifting copy.
+import { frameCount, renderSpriteFrame } from './pxart';
+import { spriteDestRect } from './spriteGeometry';
+
+// Union bounding box (fraction of native resolution, 0..1) of every opaque
+// (alpha > 0) pixel across ALL animation frames of a sprite, or null when the
+// art is fully transparent. Unioning across frames keeps an animated sprite's
+// collider from pulsing frame to frame. Cached in a WeakMap keyed by the
+// sprite object -- a sprite edit produces a fresh object (same invalidation
+// lifecycle as Sprite.jsx's rendered-canvas cache), so a stale entry never
+// outlives the art it was computed from.
+const opaqueBoundsCache = new WeakMap();
+
+// Expand `acc` (in pixel units) to cover every opaque pixel of the canvas's
+// current contents.
+function accumulateOpaquePixels(acc, ctx, canvas) {
+  if (!ctx || canvas.width === 0 || canvas.height === 0) return;
+  const { data } = ctx.getImageData(0, 0, canvas.width, canvas.height);
+  for (let y = 0; y < canvas.height; y++) {
+    for (let x = 0; x < canvas.width; x++) {
+      if (data[(y * canvas.width + x) * 4 + 3] === 0) continue;
+      if (x < acc.minX) acc.minX = x;
+      if (y < acc.minY) acc.minY = y;
+      if (x + 1 > acc.maxX) acc.maxX = x + 1;
+      if (y + 1 > acc.maxY) acc.maxY = y + 1;
+    }
+  }
+}
+
+function opaqueBoundsFraction(sprite) {
+  if (opaqueBoundsCache.has(sprite)) return opaqueBoundsCache.get(sprite);
+
+  const { width, height } = sprite.resolution;
+  const canvas = document.createElement('canvas');
+  const ctx = canvas.getContext('2d');
+  const acc = { minX: Infinity, minY: Infinity, maxX: -Infinity, maxY: -Infinity };
+  const total = frameCount(sprite);
+  for (let frame = 0; frame < total; frame++) {
+    renderSpriteFrame(sprite, frame, canvas);
+    accumulateOpaquePixels(acc, ctx, canvas);
+  }
+
+  const bounds =
+    acc.minX <= acc.maxX && acc.minY <= acc.maxY && width > 0 && height > 0
+      ? {
+          x: acc.minX / width,
+          y: acc.minY / height,
+          width: (acc.maxX - acc.minX) / width,
+          height: (acc.maxY - acc.minY) / height,
+        }
+      : null;
+  opaqueBoundsCache.set(sprite, bounds);
+  return bounds;
+}
+
+// True when a resolved sprite has no opaque pixels across any frame -- fully
+// transparent art (e.g. a brand-new blank drawing). The editor draws an
+// empty-actor placeholder for these so a blank actor isn't invisible. Shares
+// `opaqueBoundsFraction`'s per-sprite cache (a sprite edit yields a fresh
+// object, which invalidates it).
+export function spriteIsEmpty(sprite) {
+  return !sprite || opaqueBoundsFraction(sprite) === null;
+}
+
+// The `mode: 'auto'` rect (before offsets), in world units, or null when auto
+// falls back to the full Layout box: no Sprite, an unresolved sprite file,
+// `Sprite.mode === 'tile'` (tiled art fills its cell by definition, so a
+// per-cell bbox doesn't compose), or fully transparent art. Deliberately does
+// NOT follow Sprite.jsx's FALLBACK_FILE placeholder-art fallback -- an
+// unresolvable file means the Layout box, period.
+function autoRect(layout, spriteProps, sprite) {
+  if (!sprite || spriteProps.mode === 'tile') return null;
+  const bounds = opaqueBoundsFraction(sprite);
+  if (!bounds) return null;
+  const dest = spriteDestRect(spriteProps.mode, layout, sprite.resolution);
+  const rect = {
+    x: dest.x + bounds.x * dest.width,
+    y: dest.y + bounds.y * dest.height,
+    width: bounds.width * dest.width,
+    height: bounds.height * dest.height,
+  };
+  // `cover`'s dest overflows the Layout box and the draw clips to it, so the
+  // opaque-bounds rect can spill outside the actor -- clamp to the visible box.
+  // A no-op for `stretch`/`fit`, whose dest already sits inside the box.
+  if (spriteProps.mode === 'cover') return intersectRect(rect, layout);
+  return rect;
+}
+
+// Rect intersection in world units; zero-size (never negative) when disjoint.
+function intersectRect(rect, box) {
+  const x0 = Math.max(rect.x, box.x);
+  const y0 = Math.max(rect.y, box.y);
+  const x1 = Math.min(rect.x + rect.width, box.x + box.width);
+  const y1 = Math.min(rect.y + rect.height, box.y + box.height);
+  return { x: x0, y: y0, width: Math.max(0, x1 - x0), height: Math.max(0, y1 - y0) };
+}
+
+// `mode: 'manual'` rect (before offsets): `width`/`height`, centered in the
+// Layout box.
+function manualRect(layout, collider) {
+  const width = collider.width ?? layout.width;
+  const height = collider.height ?? layout.height;
+  return {
+    x: layout.x + (layout.width - width) / 2,
+    y: layout.y + (layout.height - height) / 2,
+    width,
+    height,
+  };
+}
+
+const fullLayoutRect = (layout) => ({ x: layout.x, y: layout.y, width: layout.width, height: layout.height });
+
+// The un-offset rect. Colliders are sized by their explicit `width`/`height`
+// (the "auto vs manual" mode is gone -- use the inspector's "Auto-fit to sprite"
+// action to snap those to the sprite). Legacy decks that still carry
+// `mode: 'auto'` keep their dynamic sprite fit for back-compat.
+function modeRect(layout, collider, spriteProps, sprites) {
+  if (collider.mode === 'auto') {
+    const sprite = spriteProps ? sprites?.[spriteProps.file] : null;
+    return autoRect(layout, spriteProps, sprite) ?? fullLayoutRect(layout);
+  }
+  return manualRect(layout, collider);
+}
+
+// The Collider rect for an actor, from its Layout + Collider (+ Sprite, for
+// `mode: 'auto'`), or null if it lacks a Layout or Collider. `sprites` is the
+// scene's sprite map (file path -> parsed sprite); omit it (or pass a map
+// missing the actor's file) to force the Layout-box fallback, e.g. from a
+// caller that only has raw scene data and no loaded sprites.
+export function getColliderRect(actor, sprites) {
+  const layout = actor?.components?.Layout;
+  const collider = actor?.components?.Collider;
+  if (!layout || !collider) return null;
+
+  const rect = modeRect(layout, collider, actor.components.Sprite, sprites);
+  return {
+    x: rect.x + (collider.offsetX ?? 0),
+    y: rect.y + (collider.offsetY ?? 0),
+    width: rect.width,
+    height: rect.height,
+  };
+}
+
+// Full collider geometry: the AABB rect (`x/y/width/height`, offset-applied)
+// PLUS the shape and, for circles, the center + radius. This is the SINGLE
+// SOURCE OF TRUTH for collider shape -- the physics body (matterBridge), the
+// play-mode debug draw (Collider.draw), and the editor selection overlay all
+// derive their geometry from here, so the visual preview always matches the
+// simulated collider. `radius` of 0 means "derive from the rect" (min side / 2),
+// so a circle shows a real size even before you set an explicit radius.
+export function getColliderShape(actor, sprites) {
+  const rect = getColliderRect(actor, sprites);
+  if (!rect) return null;
+  const collider = actor.components.Collider;
+  const shape = collider.shape === 'circle' ? 'circle' : 'box';
+  const radius = collider.radius > 0 ? collider.radius : Math.min(rect.width, rect.height) / 2;
+  return {
+    shape,
+    x: rect.x,
+    y: rect.y,
+    width: rect.width,
+    height: rect.height,
+    cx: rect.x + rect.width / 2,
+    cy: rect.y + rect.height / 2,
+    radius,
+  };
+}
+
+// The explicit `width`/`height`/`offsetX`/`offsetY` a collider would need to
+// exactly match its sprite's opaque-pixel fit -- what "auto" used to compute
+// dynamically. Returns null when there's nothing to fit to (no Sprite, tile
+// mode, or fully transparent art). Powers the inspector's "Auto-fit to sprite".
+export function computeAutoFit(actor, sprites) {
+  const rawLayout = actor?.components?.Layout;
+  const spriteProps = actor?.components?.Sprite;
+  if (!rawLayout || !spriteProps) return null;
+  // Blueprint templates omit x/y (position is instance-local). x/y cancel out of
+  // the offset delta below, so default them to 0 -- otherwise an undefined x/y
+  // (auto-fitting a template, e.g. on add) turns the offsets into NaN.
+  const layout = { ...rawLayout, x: rawLayout.x ?? 0, y: rawLayout.y ?? 0 };
+  const rect = autoRect(layout, spriteProps, sprites?.[spriteProps.file]);
+  if (!rect || rect.width <= 0 || rect.height <= 0) return null;
+  // manualRect centers a width x height box in the Layout box; the offset is the
+  // delta from that centered position to the sprite-fit rect.
+  const centeredX = layout.x + (layout.width - rect.width) / 2;
+  const centeredY = layout.y + (layout.height - rect.height) / 2;
+  return {
+    width: Math.round(rect.width),
+    height: Math.round(rect.height),
+    offsetX: Math.round(rect.x - centeredX),
+    offsetY: Math.round(rect.y - centeredY),
+  };
+}
+
+export function intersects(a, b) {
+  return a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y;
+}

package/kits/physics-2d/engine/files.js

@@ -0,0 +1,117 @@
+// Seed the file map by scanning the deck dir. Vite module-cache is invalidated
+// on restart, so a newly-created file just shows up on the next reload.
+const rawModules = import.meta.glob(
+  ['../scenes/*.scene', '../blueprints/*.scene', '../drawings/*.pxart', '../behaviors/*.jsx'],
+  { query: '?raw', import: 'default', eager: true }
+);
+export const initialFiles = Object.fromEntries(
+  Object.entries(rawModules)
+    .map(([globPath, text]) => [globPath.replace(/^\.\.\//, ''), text])
+    .sort(([a], [b]) => a.localeCompare(b))
+);
+export function getFileKind(path) {
+  if (path.endsWith('.scene')) return 'scene';
+  if (path.endsWith('.pxart')) return 'pxart';
+  if (path.endsWith('.js') || path.endsWith('.jsx')) return 'code';
+  return 'text';
+}
+export function parseJsonFile(path, text) {
+  try {
+    return { value: JSON.parse(text), error: null };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { value: null, error: `${path}: ${message}` };
+  }
+}
+export function formatJson(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+export function basename(path) {
+  return path.split('/').pop() ?? path;
+}
+// Parent directory of a path ('' for a root-level path).
+export function dirname(path) {
+  const index = path.lastIndexOf('/');
+  return index === -1 ? '' : path.slice(0, index);
+}
+// Join a directory and a name, tolerating a '' (root) directory.
+export function joinPath(dir, name) {
+  return dir ? `${dir}/${name}` : name;
+}
+// Split a filename into stem + extension (the extension includes the leading
+// dot). Leading-dot names (e.g. '.gitignore') count as all-stem.
+export function splitFileName(name) {
+  const dot = name.lastIndexOf('.');
+  if (dot <= 0) return { stem: name, ext: '' };
+  return { stem: name.slice(0, dot), ext: name.slice(dot) };
+}
+// A filename in `dir` that doesn't collide with any existing path. If
+// `desiredName` is free it's returned as-is; otherwise '-2', '-3', ... is
+// inserted before the extension until a free name is found.
+export function uniqueFileName(existingPaths, dir, desiredName) {
+  const taken = new Set(existingPaths);
+  if (!taken.has(joinPath(dir, desiredName))) return desiredName;
+  const { stem, ext } = splitFileName(desiredName);
+  for (let n = 2; ; n++) {
+    const candidate = `${stem}-${n}${ext}`;
+    if (!taken.has(joinPath(dir, candidate))) return candidate;
+  }
+}
+// Top-level child segment names (files and virtual folders) directly inside
+// `parentDir`. Used to keep new sibling folder names collision-free.
+export function childNamesIn(existingPaths, parentDir) {
+  const prefix = parentDir ? `${parentDir}/` : '';
+  const names = new Set();
+  for (const path of existingPaths) {
+    if (prefix && !path.startsWith(prefix)) continue;
+    const segment = path.slice(prefix.length).split('/')[0];
+    if (segment) names.add(segment);
+  }
+  return names;
+}
+// A folder name inside `parentDir` that doesn't collide with an existing
+// sibling file or folder. Appends '-2', '-3', ... until free.
+export function uniqueFolderName(existingPaths, parentDir, desiredName) {
+  const taken = childNamesIn(existingPaths, parentDir);
+  if (!taken.has(desiredName)) return desiredName;
+  for (let n = 2; ; n++) {
+    const candidate = `${desiredName}-${n}`;
+    if (!taken.has(candidate)) return candidate;
+  }
+}
+// All file paths under a virtual folder (paths prefixed with `dirPath/`).
+export function filesUnder(existingPaths, dirPath) {
+  const prefix = `${dirPath}/`;
+  return existingPaths.filter((path) => path.startsWith(prefix));
+}
+// Flat list of file paths in the order FileBrowser renders them: a
+// depth-first walk of the directory tree, mirroring buildFileTree there.
+export function flatFileOrder(paths) {
+  const root = { isFile: false, path: '', children: [], childMap: new Map() };
+  for (const path of paths) {
+    const parts = path.split('/');
+    let parent = root;
+    for (let index = 0; index < parts.length; index++) {
+      const name = parts[index];
+      const nodePath = parts.slice(0, index + 1).join('/');
+      const isFile = index === parts.length - 1;
+      if (!parent.childMap.has(name)) {
+        const node = { isFile, path: nodePath, children: [], childMap: new Map() };
+        parent.childMap.set(name, node);
+        parent.children.push(node);
+      }
+      const child = parent.childMap.get(name);
+      if (!child || child.isFile) break;
+      parent = child;
+    }
+  }
+  const order = [];
+  const walk = (node) => {
+    for (const child of node.children) {
+      if (child.isFile) order.push(child.path);
+      else walk(child);
+    }
+  };
+  walk(root);
+  return order;
+}

package/kits/physics-2d/engine/liveReload.js

@@ -0,0 +1,88 @@
+// Consumer side of the serve's `files_changed` broadcast. The engine decides
+// what a change means for this bundle:
+//   - data files (.scene / .pxart / .drawing) are re-read over the serve's
+//     files API and folded into React state — live re-render, no reload.
+//   - code the bundle imports (per the event's module-graph closure), html,
+//     or added/deleted code files (import.meta.glob may pick them up) mean
+//     this context is stale — requestReload() (save-state hooks run first).
+import { useEffect, useRef, useState } from 'react';
+import { onFilesChanged, requestReload } from 'castle-web-sdk';
+import { initialFiles } from './files';
+
+const DATA_EXTS = ['.scene', '.pxart', '.drawing'];
+const CODE_EXTS = ['.js', '.jsx', '.ts', '.tsx', '.css'];
+
+export function isDataFile(path) {
+  return DATA_EXTS.some((ext) => path.endsWith(ext));
+}
+
+function needsContextReload(change) {
+  if (isDataFile(change.path)) return false;
+  if (change.path.endsWith('.html')) return true;
+  // In the module graph (directly or as someone's import) -> our code changed.
+  if (change.affected.length > 0) return true;
+  // A new/removed code file isn't in the graph yet but a glob may scan it.
+  if (change.event !== 'change') return CODE_EXTS.some((ext) => change.path.endsWith(ext));
+  return false;
+}
+
+async function readDeckFile(path) {
+  const res = await fetch(`/__castle/files/read?path=${encodeURIComponent(path)}`);
+  if (!res.ok) throw new Error(`read failed: ${res.status}`);
+  const data = await res.json();
+  return typeof data.contents === 'string' ? data.contents : '';
+}
+
+// Deck files as live state: starts from the build-time glob snapshot and stays
+// current as files change on disk from any source (editors, agents, terminal).
+// `shouldSkipPath` lets an editor keep its own in-flight edits from being
+// clobbered by the fs echo of a stale write. `dataVersion` bumps on every
+// applied data change — key a player on it to rebuild from fresh data.
+export function useLiveDeckFiles({ shouldSkipPath } = {}) {
+  const [files, setFiles] = useState(initialFiles);
+  const [dataVersion, setDataVersion] = useState(0);
+  const skipRef = useRef(shouldSkipPath);
+  skipRef.current = shouldSkipPath;
+
+  useEffect(
+    () =>
+      onFilesChanged((event) => {
+        if (event.changes.some(needsContextReload)) {
+          requestReload();
+          return;
+        }
+        const dataChanges = event.changes.filter(
+          (change) => isDataFile(change.path) && !skipRef.current?.(change.path)
+        );
+        if (dataChanges.length === 0) return;
+        void applyDataChanges(dataChanges, setFiles, setDataVersion);
+      }),
+    []
+  );
+
+  return { files, setFiles, dataVersion };
+}
+
+async function applyDataChanges(changes, setFiles, setDataVersion) {
+  const updates = await Promise.all(
+    changes.map(async (change) => {
+      if (change.event === 'delete') return { path: change.path, text: null };
+      try {
+        return { path: change.path, text: await readDeckFile(change.path) };
+      } catch {
+        return null; // read raced a delete / serve hiccup — skip this path
+      }
+    })
+  );
+  const applied = updates.filter(Boolean);
+  if (applied.length === 0) return;
+  setFiles((current) => {
+    const next = { ...current };
+    for (const { path, text } of applied) {
+      if (text === null) delete next[path];
+      else next[path] = text;
+    }
+    return next;
+  });
+  setDataVersion((version) => version + 1);
+}