castle-web-cli 0.4.78 → 0.4.80

package/kits/basic-2d/engine/blueprint.js

@@ -0,0 +1,423 @@
+// Blueprint system: every actor in a scene is an instance of a blueprint (a
+// `.scene` file under `blueprints/` whose `actors[0]` is the template, with no
+// `id`). An instance stores only sparse per-property overrides in its own
+// `components`; blueprint template values are the base, merged live from the
+// current `files` map (never a load-time snapshot) so a blueprint edit in one
+// panel propagates to every scene that places it. Shared by the runtime
+// (`scene.js`, so play mode and `PlayOnly` resolve blueprints too) and the
+// editors (which also mint/fork/migrate/cascade-delete blueprint files).
+import { formatJson } from './files';
+import { DEFAULT_RESOLUTION, TRANSPARENT, serializeCompact } from './pxart';
+import { cardSize, mintActorId } from './scene';
+
+export const BLUEPRINTS_DIR = 'blueprints';
+export const DRAWINGS_DIR = 'drawings';
+
+export function isBlueprintPath(path) {
+  return typeof path === 'string' && path.startsWith(`${BLUEPRINTS_DIR}/`) && path.endsWith('.scene');
+}
+
+// Per-property inherit metadata for a behavior prop. Behaviors opt a prop out
+// of inheritance via `static propertyMeta = { propName: { inherit: false } }`
+// (see behaviors/Layout.jsx for x/y/rotation); anything absent defaults to
+// inherited. A non-inherited prop is always written as an instance value at
+// placement time -- the blueprint's value for it is only a default for newly
+// placed instances, and future blueprint edits never move an existing
+// instance's copy of that prop.
+export function getPropertyMeta(Behavior, prop) {
+  return Behavior?.propertyMeta?.[prop] ?? { inherit: true };
+}
+
+export function isInheritedProp(Behavior, prop) {
+  return getPropertyMeta(Behavior, prop).inherit !== false;
+}
+
+// Parse a blueprint file's text into { name, components } (the template
+// actor's components), or null if the text isn't a valid blueprint (used to
+// treat a tombstoned/deleted blueprint file as absent).
+function parseBlueprintText(text) {
+  if (typeof text !== 'string') return null;
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  const actor = data?.actors?.[0];
+  if (!actor || typeof actor !== 'object' || !actor.components) return null;
+  const name = typeof data.name === 'string' && data.name.trim() ? data.name : 'Blueprint';
+  return { name, components: actor.components };
+}
+
+// Resolve a blueprint's template from the LIVE files map -- the load-bearing
+// call for live propagation. Returns null when the file is missing, deleted,
+// or malformed (a dangling `blueprint` ref degrades to "no template" rather
+// than throwing).
+export function getBlueprintTemplate(files, blueprintPath) {
+  return parseBlueprintText(files?.[blueprintPath]);
+}
+
+// Every blueprint currently in the deck, for the library/hotbar. Skips
+// unparseable / tombstoned files (see `cascadeDeleteBlueprint`).
+export function listBlueprints(files) {
+  const out = [];
+  for (const path of Object.keys(files ?? {})) {
+    if (!isBlueprintPath(path)) continue;
+    const template = parseBlueprintText(files[path]);
+    if (!template) continue;
+    out.push({ path, name: template.name, components: template.components });
+  }
+  out.sort((a, b) => a.path.localeCompare(b.path));
+  return out;
+}
+
+// Per-property merge: the blueprint template is the base, instance overrides
+// win per-property within each component (not whole-component replacement). A
+// component present on only one side appears whole.
+export function mergeComponents(templateComponents, instanceComponents) {
+  const merged = {};
+  const names = new Set([
+    ...Object.keys(templateComponents ?? {}),
+    ...Object.keys(instanceComponents ?? {}),
+  ]);
+  for (const name of names) {
+    const templateProps = templateComponents?.[name];
+    const instanceProps = instanceComponents?.[name];
+    if (templateProps === undefined) merged[name] = { ...instanceProps };
+    else if (instanceProps === undefined) merged[name] = { ...templateProps };
+    else merged[name] = { ...templateProps, ...instanceProps };
+  }
+  return merged;
+}
+
+// The fully resolved components for one actor: its blueprint's template
+// merged with its own sparse overrides, or its raw components when it carries
+// no `blueprint` ref (the blueprint's own template actor, or a not-yet
+// migrated legacy actor).
+export function resolveActorComponents(files, actor) {
+  if (!actor?.blueprint) return actor?.components ?? {};
+  const template = getBlueprintTemplate(files, actor.blueprint);
+  return mergeComponents(template?.components, actor.components);
+}
+
+function countMatches(text, regex) {
+  let max = 0;
+  const re = new RegExp(regex);
+  const m = re.exec(text ?? '');
+  return m ? Number(m[1]) : max;
+}
+
+// "Blueprint N" -- N is one more than the highest existing "Blueprint <n>"
+// name (not just existing.length + 1, so a gap left by a deleted blueprint
+// doesn't get reused and collide with intent elsewhere).
+function mintBlueprintName(existingNames) {
+  let max = 0;
+  for (const name of existingNames) max = Math.max(max, countMatches(name, /^Blueprint (\d+)$/));
+  return `Blueprint ${max + 1}`;
+}
+
+// `blueprints/blueprint-N.scene` -- the filename is a stable slug minted once
+// at creation; nothing ever renames it afterward (renaming edits only `name`).
+function mintBlueprintPath(existingPaths) {
+  let max = 0;
+  for (const path of existingPaths) {
+    max = Math.max(max, countMatches(path, new RegExp(`^${BLUEPRINTS_DIR}/blueprint-(\\d+)\\.scene$`)));
+  }
+  return `${BLUEPRINTS_DIR}/blueprint-${max + 1}.scene`;
+}
+
+export function formatBlueprintFileText(name, components) {
+  return formatJson({ name, actors: [{ components }] });
+}
+
+// Rename a blueprint: replace its top-level `name`, preserving actors and any
+// hand-added extras. Returns the next file text, or null when the file is
+// missing/unparseable (caller should treat that as "blueprint gone" and skip
+// the write). Empty/whitespace names are stored as-is; readers fall back to
+// "Blueprint" for display (see getBlueprintTemplate).
+export function setBlueprintName(files, blueprintPath, name) {
+  let data;
+  try {
+    data = JSON.parse(files?.[blueprintPath] ?? '');
+  } catch {
+    return null;
+  }
+  if (!data || typeof data !== 'object') return null;
+  data.name = name;
+  return formatJson(data);
+}
+
+// Replace a blueprint file's template components, preserving every other
+// top-level field (name, hand-added extras). Returns the next file text, or
+// null when the file is missing/unparseable/tombstoned (caller should treat
+// that as "blueprint gone" and skip the write).
+export function setBlueprintTemplateComponents(files, blueprintPath, components) {
+  let data;
+  try {
+    data = JSON.parse(files?.[blueprintPath] ?? '');
+  } catch {
+    return null;
+  }
+  if (!data?.actors?.[0]) return null;
+  data.actors[0].components = components;
+  return formatJson(data);
+}
+
+// Mint a brand new blueprint file descriptor ({ path, name, text }) for the
+// given template components. Does not write the file -- callers write it
+// (via the SDK's `writeFile`) and, for the current scene, place an instance
+// referencing `path`.
+export function mintBlueprintFile(files, components) {
+  const existing = listBlueprints(files);
+  const name = mintBlueprintName(existing.map((blueprint) => blueprint.name));
+  const path = mintBlueprintPath(existing.map((blueprint) => blueprint.path));
+  return { path, name, text: formatBlueprintFileText(name, components) };
+}
+
+// Split a resolved component's props into { inherited, overridden } by each
+// prop's propertyMeta. Used by migration and fork to decide what belongs in a
+// new blueprint template vs. what must stay an explicit instance value.
+function splitByInherit(Behavior, props) {
+  const inherited = {};
+  const overridden = {};
+  for (const [prop, value] of Object.entries(props ?? {})) {
+    if (isInheritedProp(Behavior, prop)) inherited[prop] = value;
+    else overridden[prop] = value;
+  }
+  return { inherited, overridden };
+}
+
+function findBehavior(behaviors, name) {
+  return behaviors.find((candidate) => candidate.behaviorName === name);
+}
+
+// Apply an inspector-style partial patch (`{ propName: value, ... }`) to one
+// actor's component, IN PLACE. For a blueprint's own template actor (no
+// `blueprint` ref) this is a plain merge -- there's no baseline to diff
+// against. For an instance, each patched prop is diffed against the
+// blueprint's current value (falling back to the behavior's defaultProps):
+// an inherited prop that becomes equal to the blueprint again drops its
+// override (so it goes back to tracking blueprint edits); anything else is
+// recorded as an override. Never writes a full component copy.
+export function applyComponentPatch(files, behaviors, actor, behaviorName, nextProps) {
+  actor.components ??= {};
+  if (!actor.blueprint) {
+    actor.components[behaviorName] = { ...(actor.components[behaviorName] ?? {}), ...nextProps };
+    return;
+  }
+  const template = getBlueprintTemplate(files, actor.blueprint);
+  const templateProps = template?.components?.[behaviorName] ?? {};
+  const Behavior = findBehavior(behaviors, behaviorName);
+  const defaultProps = Behavior?.defaultProps ?? {};
+  const overrides = { ...(actor.components[behaviorName] ?? {}) };
+  for (const [prop, value] of Object.entries(nextProps)) {
+    const baseline = prop in templateProps ? templateProps[prop] : defaultProps[prop];
+    if (isInheritedProp(Behavior, prop) && Object.is(value, baseline)) delete overrides[prop];
+    else overrides[prop] = value;
+  }
+  if (Object.keys(overrides).length === 0) delete actor.components[behaviorName];
+  else actor.components[behaviorName] = overrides;
+}
+
+// Single-actor convenience wrapper around `applyComponentPatch` for the
+// inspector: clones the scene, patches the one actor's component, returns the
+// next scene (or the original when the actor is missing).
+export function setInstanceComponent(files, behaviors, sceneData, actorId, behaviorName, nextProps) {
+  const next = structuredClone(sceneData);
+  const actor = next.actors?.find((candidate) => candidate.id === actorId);
+  if (!actor) return sceneData;
+  applyComponentPatch(files, behaviors, actor, behaviorName, nextProps);
+  return next;
+}
+
+function snapValue(value, snap) {
+  if (!snap?.enabled) return Math.round(value);
+  return Math.round(value / snap.gridSize) * snap.gridSize;
+}
+
+// "Add actor" = mint a new blueprint AND place its first instance in one
+// gesture. Returns the next scene, the new instance id, and the new
+// blueprint's { path, name, text } for the caller to write to disk.
+// A blank 16x16 (DEFAULT_RESOLUTION) compact `.pxart`: all-transparent grid,
+// empty palette. This is what a brand-new blueprint's sprite points at, so the
+// "add actor" button always yields a fresh empty canvas to draw into rather
+// than reusing whatever art happened to be first in drawings/.
+export function blankPxArtText() {
+  const { width, height } = DEFAULT_RESOLUTION;
+  const grid = Array.from({ length: height }, () => TRANSPARENT.repeat(width));
+  return serializeCompact({ palette: {}, grid });
+}
+
+// `drawings/drawing-N.pxart` -- next free numbered slug, so repeated adds don't
+// collide and a deleted drawing's number isn't reused.
+function mintDrawingPath(files) {
+  const re = new RegExp(`^${DRAWINGS_DIR}/drawing-(\\d+)\\.pxart$`);
+  let max = 0;
+  for (const path of Object.keys(files ?? {})) {
+    const m = path.match(re);
+    if (m) max = Math.max(max, Number(m[1]));
+  }
+  return `${DRAWINGS_DIR}/drawing-${max + 1}.pxart`;
+}
+
+export function addActorWithBlueprint(sceneData, files) {
+  const width = 64;
+  const height = 64;
+  const drawingFile = { path: mintDrawingPath(files), text: blankPxArtText() };
+  const components = {
+    Layout: { width, height, z: 0 },
+    Sprite: { file: drawingFile.path },
+  };
+  const blueprintFile = mintBlueprintFile(files, components);
+  const next = structuredClone(sceneData);
+  const existingIds = new Set(next.actors.map((actor) => actor.id));
+  const newId = mintActorId(existingIds);
+  const x = Math.round((cardSize.width - width) / 2);
+  const y = Math.round((cardSize.height - height) / 2);
+  next.actors.push({ id: newId, blueprint: blueprintFile.path, components: { Layout: { x, y } } });
+  return { sceneData: next, newId, blueprintFile, drawingFile };
+}
+
+// Centered, grid-snapped Layout x/y for a blueprint's template at a
+// card-space point. Shared by initial drag-in placement and the subsequent
+// moves while the drag is still in progress, so both snap identically.
+export function blueprintDropXY(files, blueprintPath, position, snap) {
+  const template = getBlueprintTemplate(files, blueprintPath);
+  const layout = template?.components?.Layout ?? {};
+  const width = layout.width ?? 64;
+  const height = layout.height ?? 64;
+  const dropX = position?.x ?? cardSize.width / 2;
+  const dropY = position?.y ?? cardSize.height / 2;
+  return {
+    x: snapValue(dropX - width / 2, snap),
+    y: snapValue(dropY - height / 2, snap),
+  };
+}
+
+// Place a new instance of an existing blueprint at a drop point (card units,
+// pre-snap), grid-snapped and centered on the point using the template's
+// Layout size. Only Layout x/y are written on the instance -- everything else
+// inherits from the blueprint.
+export function placeBlueprintInstance(sceneData, files, blueprintPath, position, snap) {
+  const next = structuredClone(sceneData);
+  const existingIds = new Set(next.actors.map((actor) => actor.id));
+  const newId = mintActorId(existingIds);
+  const { x, y } = blueprintDropXY(files, blueprintPath, position, snap);
+  next.actors.push({ id: newId, blueprint: blueprintPath, components: { Layout: { x, y } } });
+  return { sceneData: next, newId };
+}
+
+// "New blueprint from this actor": mint a blueprint whose template is the
+// instance's fully merged components, with non-inherited props reset to their
+// behavior defaults in the TEMPLATE (a fresh blueprint has no instances yet to
+// carry position, so its own template position is a neutral default).
+// Reparent the instance to the new blueprint, keeping only its non-inherited
+// prop values (Layout position et al) as instance overrides -- everything
+// else now matches the new template exactly, so no override is needed for it.
+export function forkActorToBlueprint(files, behaviors, sceneData, actorId) {
+  const next = structuredClone(sceneData);
+  const actor = next.actors?.find((candidate) => candidate.id === actorId);
+  if (!actor) return null;
+  const merged = resolveActorComponents(files, actor);
+  const templateComponents = {};
+  const instanceOverrides = {};
+  for (const [behaviorName, props] of Object.entries(merged)) {
+    if (!props) continue;
+    const Behavior = findBehavior(behaviors, behaviorName);
+    const { inherited, overridden } = splitByInherit(Behavior, props);
+    if (Object.keys(overridden).length > 0) instanceOverrides[behaviorName] = overridden;
+    // The new template's non-inherited props reset to the behavior's default
+    // (a fresh blueprint has no instances yet to carry a real position); its
+    // inherited props keep the actor's current (merged) values verbatim.
+    const defaultProps = Behavior?.defaultProps ?? {};
+    const resetOverridden = Object.fromEntries(
+      Object.keys(overridden).map((prop) => [prop, prop in defaultProps ? defaultProps[prop] : overridden[prop]])
+    );
+    if (Object.keys(inherited).length > 0 || Object.keys(resetOverridden).length > 0) {
+      templateComponents[behaviorName] = { ...inherited, ...resetOverridden };
+    }
+  }
+  const blueprintFile = mintBlueprintFile(files, templateComponents);
+  actor.blueprint = blueprintFile.path;
+  actor.components = instanceOverrides;
+  return { sceneData: next, blueprintFile };
+}
+
+// Every `scenes/*.scene` file's parsed data, for callers that need to scan
+// every scene in the deck (cascade delete, the instance-count badge/confirm).
+// Skips unparseable files rather than throwing -- a mid-edit scene with
+// invalid JSON just doesn't count towards these scans.
+function parseSceneFiles(files) {
+  const out = [];
+  for (const [path, text] of Object.entries(files ?? {})) {
+    if (!path.startsWith('scenes/') || !path.endsWith('.scene')) continue;
+    try {
+      out.push({ path, data: JSON.parse(text) });
+    } catch {
+      // skip
+    }
+  }
+  return out;
+}
+
+// Every `scenes/*.scene` file's actor count referencing a blueprint, for the
+// delete-confirm dialog and the library's per-blueprint badge.
+export function countBlueprintInstances(files, blueprintPath) {
+  let count = 0;
+  for (const { data } of parseSceneFiles(files)) {
+    for (const actor of data?.actors ?? []) {
+      if (actor?.blueprint === blueprintPath) count += 1;
+    }
+  }
+  return count;
+}
+
+// Cascade-delete a blueprint: every instance in every scene is removed, and
+// the blueprint file itself is tombstoned (overwritten with an empty scene --
+// `listBlueprints` skips it and it stops resolving). Returns the list of
+// { path, text } writes for the caller to apply (the currently open scene
+// should go through that editor's own history/onChange so undo still works
+// for it; every other file is a direct `writeFile`).
+export function cascadeDeleteBlueprint(files, blueprintPath) {
+  const writes = [];
+  for (const { path, data } of parseSceneFiles(files)) {
+    const actors = data.actors ?? [];
+    const filtered = actors.filter((actor) => actor?.blueprint !== blueprintPath);
+    if (filtered.length !== actors.length) {
+      writes.push({ path, text: formatJson({ ...data, actors: filtered }) });
+    }
+  }
+  writes.push({ path: blueprintPath, text: formatJson({}) });
+  return writes;
+}
+
+// Auto-migrate a scene's orphan actors (no `blueprint` field -- the pre-v1
+// shape) into blueprint instances: mint one blueprint per orphan (its
+// authored components split by propertyMeta, same as fork), rewrite the actor
+// to reference it with only the non-inherited props as overrides. Mechanical
+// and safe: never touches an actor that already has a `blueprint`.
+export function migrateOrphanActors(files, behaviors, sceneData) {
+  const next = structuredClone(sceneData);
+  const newBlueprintFiles = [];
+  let knownBlueprints = listBlueprints(files);
+  for (const actor of next.actors ?? []) {
+    if (actor.blueprint) continue;
+    const templateComponents = {};
+    const instanceOverrides = {};
+    for (const [behaviorName, props] of Object.entries(actor.components ?? {})) {
+      if (!props) continue;
+      const Behavior = findBehavior(behaviors, behaviorName);
+      const { inherited, overridden } = splitByInherit(Behavior, props);
+      if (Object.keys(inherited).length > 0) templateComponents[behaviorName] = inherited;
+      if (Object.keys(overridden).length > 0) instanceOverrides[behaviorName] = overridden;
+    }
+    const name = mintBlueprintName(knownBlueprints.map((blueprint) => blueprint.name));
+    const path = mintBlueprintPath(knownBlueprints.map((blueprint) => blueprint.path));
+    const text = formatBlueprintFileText(name, templateComponents);
+    newBlueprintFiles.push({ path, text });
+    knownBlueprints = [...knownBlueprints, { path, name, components: templateComponents }];
+    actor.blueprint = path;
+    actor.components = instanceOverrides;
+  }
+  return { sceneData: next, newBlueprintFiles };
+}

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

@@ -1,7 +1,7 @@
 // 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', '../drawings/*.pxart', '../behaviors/*.jsx'],
+  ['../scenes/*.scene', '../blueprints/*.scene', '../drawings/*.pxart', '../behaviors/*.jsx'],
   { query: '?raw', import: 'default', eager: true }
 );
 export const initialFiles = Object.fromEntries(

package/kits/basic-2d/engine/scene.js

@@ -1,4 +1,5 @@
 import { initialFiles, parseJsonFile } from './files';
+import { getBlueprintTemplate, mergeComponents } from './blueprint';
 
 const CARD_WIDTH = 500;
 const CARD_HEIGHT = 700;
@@ -25,9 +26,14 @@ function resolveSceneFileKey(name) {
 }
 
 export class SceneRuntime {
-  constructor(sceneData, behaviors, sprites) {
+  // `files` is the live deck files map (path -> text), used to resolve every
+  // actor's `blueprint` ref against the CURRENT blueprint file content -- not
+  // a load-time snapshot -- so a blueprint edit propagates to every scene that
+  // places it, in both the editor and play mode / `PlayOnly`.
+  constructor(sceneData, behaviors, sprites, files) {
     this.behaviors = new Map(behaviors.map((Behavior) => [Behavior.behaviorName, Behavior]));
     this.sprites = sprites ?? {};
+    this.files = files ?? {};
     this.time = 0;
     this.keys = new Set();
     this.pointer = { x: 0, y: 0, down: false };
@@ -43,6 +49,10 @@ export class SceneRuntime {
     this.actors = new Map();
     for (const actor of this.data.actors ?? []) {
       actor.runtime = {};
+      if (actor.blueprint) {
+        const template = getBlueprintTemplate(this.files, actor.blueprint);
+        actor.components = mergeComponents(template?.components, actor.components);
+      }
       this.actors.set(actor.id, actor);
       for (const [behaviorName, Behavior] of this.behaviors) {
         const component = actor.components[behaviorName];
@@ -77,7 +87,7 @@ export class SceneRuntime {
   }
 
   clone() {
-    return new SceneRuntime(this.serialize(), [...this.behaviors.values()], this.sprites);
+    return new SceneRuntime(this.serialize(), [...this.behaviors.values()], this.sprites, this.files);
   }
 
   serialize() {
@@ -126,6 +136,10 @@ export class SceneRuntime {
     return Boolean(a && b && intersects(a, b));
   }
 
+  // Raw spawn: `actor.components` is used as-is (already-resolved values),
+  // just filled out with each behavior's defaultProps. Internal use -- prefer
+  // `spawnFromBlueprint` so a runtime-spawned actor is a blueprint instance
+  // like every other actor.
   spawnActor(actor) {
     const id = actor.id ?? mintActorId(new Set(this.actors.keys()));
     const components = {};
@@ -139,6 +153,16 @@ export class SceneRuntime {
     return next;
   }
 
+  // The blessed spawn path: resolve `blueprintPath` from the live `files`,
+  // merge with `overrides.components` (sparse, same shape as a placed
+  // instance's file overrides), and spawn the result. `overrides.id`, when
+  // given, is used as the new actor's id.
+  spawnFromBlueprint(blueprintPath, overrides = {}) {
+    const template = getBlueprintTemplate(this.files, blueprintPath);
+    const components = mergeComponents(template?.components, overrides.components);
+    return this.spawnActor({ id: overrides.id, blueprint: blueprintPath, components });
+  }
+
   despawnActor(actorId) {
     const actor = this.actors.get(actorId);
     if (!actor) return false;
@@ -261,8 +285,8 @@ export class SceneRuntime {
   }
 }
 
-export function makeScene(sceneData, behaviors, sprites) {
-  return new SceneRuntime(sceneData, behaviors, sprites);
+export function makeScene(sceneData, behaviors, sprites, files) {
+  return new SceneRuntime(sceneData, behaviors, sprites, files);
 }
 
 export function setActorComponent(sceneData, actorId, behaviorName, nextProps) {
@@ -437,31 +461,7 @@ export function getSelectionBounds(sceneData, actorIds) {
   return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
 }
 
-export function addActor(sceneData, _files, sprites) {
-  const next = structuredClone(sceneData);
-  const existingIds = new Set(next.actors.map((actor) => actor.id));
-  const id = mintActorId(existingIds);
-  const width = 64;
-  const height = 64;
-  const layout = {
-    x: Math.round((CARD_WIDTH - width) / 2),
-    y: Math.round((CARD_HEIGHT - height) / 2),
-    width,
-    height,
-    z: 0,
-    rotation: 0,
-  };
-  const components = { Layout: layout };
-  // Give a fresh actor the first available .pxart sprite so it shows art.
-  const spritePath = Object.keys(sprites ?? {}).sort()[0];
-  if (spritePath) {
-    components.Sprite = { file: spritePath };
-  }
-  next.actors.push({ id, components });
-  return { sceneData: next, newId: id };
-}
-
-function mintActorId(existing) {
+export function mintActorId(existing) {
   for (let attempt = 0; attempt < 64; attempt++) {
     const candidate = Math.floor(Math.random() * 0xffffffff)
       .toString(16)