castle-web-cli 0.4.83 → 0.4.85

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

@@ -0,0 +1,521 @@
+// 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, dedupeActorId } 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`;
+}
+
+// "auto-tetris" -> "Auto Tetris". Splits on non-alphanumeric runs (covers the
+// hyphen/underscore ids actors typically use) and title-cases each word.
+function humanizeActorId(id) {
+  return id
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map((word) => word[0].toUpperCase() + word.slice(1))
+    .join(' ');
+}
+
+// "Auto Tetris" -> "auto-tetris" for the filename slug. Kept independent of
+// the actor id's own formatting (an id could already be any casing/shape).
+function slugifyActorId(id) {
+  return id
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+// Mint a readable, unique actor id from a display name (a blueprint's `name`):
+// slugified and slug-suffix-deduped against `existing` (`cauldron`,
+// `cauldron-2`, ...). This is the editor's placement/creation default, so a
+// freshly placed actor reads as `cauldron` rather than an opaque hex id.
+// `mintActorId` (hex) still backs runtime spawns and the dedup fallback.
+export function mintActorIdFromName(existing, name) {
+  const base = slugifyActorId(typeof name === 'string' ? name : '');
+  return dedupeActorId(existing, base);
+}
+
+// Derive a migration blueprint's { name, path } from the orphan actor's own
+// `id` -- the one meaningful signal available at migration time (vs. the
+// anonymous "Blueprint N" counter), so e.g. an actor `id: "logo"` mints
+// `blueprints/logo.scene` named "Logo" instead of "Blueprint 1". Returns null
+// when the id doesn't yield a usable name/slug, so the caller falls back to
+// the counter-based mint functions.
+//
+// Collision safety is load-bearing: `knownBlueprints` includes every
+// already-migrated blueprint in this same run (see the caller's loop), so two
+// orphan actors that humanize to the same name, or that collide with a
+// pre-existing blueprint, must never mint the same path or duplicate name.
+// Deterministically disambiguate with a numeric suffix instead.
+function deriveBlueprintName(actorId, knownBlueprints) {
+  if (typeof actorId !== 'string') return null;
+  const baseSlug = slugifyActorId(actorId);
+  const baseName = humanizeActorId(actorId.trim());
+  if (!baseSlug || !baseName) return null;
+  const existingNames = new Set(knownBlueprints.map((blueprint) => blueprint.name));
+  const existingPaths = new Set(knownBlueprints.map((blueprint) => blueprint.path));
+  const MAX_ATTEMPTS = 1000;
+  for (let suffix = 1; suffix <= MAX_ATTEMPTS; suffix += 1) {
+    const name = suffix === 1 ? baseName : `${baseName} ${suffix}`;
+    const path = suffix === 1 ? `${BLUEPRINTS_DIR}/${baseSlug}.scene` : `${BLUEPRINTS_DIR}/${baseSlug}-${suffix}.scene`;
+    if (!existingNames.has(name) && !existingPaths.has(path)) return { name, path };
+  }
+  // Pathological: 1000 colliding suffixes. Let the caller fall back to the
+  // counter-based mint functions rather than looping forever.
+  return null;
+}
+
+// { name, path } for a freshly minted migration blueprint: the actor id's
+// derived name/slug when usable and collision-free, else the anonymous
+// counter (see `deriveBlueprintName`). Factored out so the branching here
+// doesn't add to `migrateOrphanActors`'s own complexity.
+function mintMigrationBlueprintName(actorId, knownBlueprints) {
+  const derived = deriveBlueprintName(actorId, knownBlueprints);
+  if (derived) return derived;
+  return {
+    name: mintBlueprintName(knownBlueprints.map((blueprint) => blueprint.name)),
+    path: mintBlueprintPath(knownBlueprints.map((blueprint) => blueprint.path)),
+  };
+}
+
+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`;
+}
+
+// The z that draws on top of every current actor: max effective z + 1 (0 for
+// an empty scene). An actor's effective z resolves its own Layout override
+// first, then its blueprint template, then 0 -- so this beats instances that
+// only inherit z from their blueprint.
+function topZ(actors, files) {
+  let max = -Infinity;
+  for (const actor of actors ?? []) {
+    const template = actor.blueprint ? getBlueprintTemplate(files, actor.blueprint) : null;
+    const z = actor.components?.Layout?.z ?? template?.components?.Layout?.z ?? 0;
+    if (z > max) max = z;
+  }
+  return max === -Infinity ? 0 : max + 1;
+}
+
+export function addActorWithBlueprint(sceneData, files) {
+  const width = 50;
+  const height = 50;
+  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 = mintActorIdFromName(existingIds, blueprintFile.name);
+  const x = Math.round((cardSize.width - width) / 2);
+  const y = Math.round((cardSize.height - height) / 2);
+  // Guarantee the new actor renders on top of whatever's already there.
+  const z = topZ(next.actors, files);
+  next.actors.push({ id: newId, blueprint: blueprintFile.path, components: { Layout: { x, y, z } } });
+  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 ?? 50;
+  const height = layout.height ?? 50;
+  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 template = getBlueprintTemplate(files, blueprintPath);
+  const newId = mintActorIdFromName(existingIds, template?.name);
+  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);
+      // A behavior attached with no props at all (e.g. `AutoTetris: {}`) has
+      // both `inherited` and `overridden` empty. It must still land somewhere,
+      // or the attachment itself -- not just some prop of it -- silently
+      // vanishes from the resolved actor. Fall back to the template side (as
+      // `{}`) so the instance keeps referencing the behavior exactly once.
+      if (Object.keys(inherited).length > 0 || Object.keys(overridden).length === 0) {
+        templateComponents[behaviorName] = inherited;
+      }
+      if (Object.keys(overridden).length > 0) instanceOverrides[behaviorName] = overridden;
+    }
+    // The actor's own id is the one meaningful signal available here (vs. an
+    // anonymous "Blueprint N") -- see `mintMigrationBlueprintName`.
+    const { name, path } = mintMigrationBlueprintName(actor.id, knownBlueprints);
+    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 };
+}