@aethervtt/shard-scene 0.0.1

package/dist/prefab-file.d.ts

@@ -0,0 +1,40 @@
+import { type Entity, ShardError, World } from '@aethervtt/shard-core';
+import { type Overrides, type PrefabFile } from './format.js';
+/**
+ * Every problem in a prefab file, each with a JSON pointer. `catalog: false` (importing) checks
+ * asset paths only when they're file-local (`#name`); scenes check the rest when they validate.
+ */
+export declare function validatePrefab(world: World, json: unknown, options?: {
+    id?: string;
+    catalog?: boolean;
+}): ShardError[];
+/**
+ * Flattens a variant onto its (resolved) base: root components merge field by field, children are
+ * added, overrides apply to the tree (paths inside nested instances land in their overrides).
+ */
+export declare function applyVariant(base: PrefabFile, variant: PrefabFile): PrefabFile;
+/** `*.prefab.json`: a validated entity tree; variants are flattened onto their base here. */
+export declare const PrefabImporter: import("@aethervtt/shard-assets").ImporterDef;
+/**
+ * Registers a prefab from JSON without a file (tests, tools, generated content), under `path`.
+ * Registering the same path again replaces it: instances update as if the file was saved, and
+ * variants registered on top of it are re-resolved. Throws with every validation error.
+ */
+export declare function registerPrefab(world: World, path: string, json: unknown): void;
+/** Registered prefab JSON as it was given (before variants are flattened), or undefined. */
+export declare function registeredPrefab(world: World, path: string): PrefabFile | undefined;
+/** File access for `applyToPrefab` (the project folder). */
+export interface PrefabFiles {
+    readText(path: string): Promise<string>;
+    writeText(path: string, text: string): Promise<void>;
+}
+/**
+ * "Apply to prefab": writes an instance's overrides into its prefab (the file, re-imported; or the
+ * registered JSON), then clears the instance's overrides. Every instance picks up the change, and
+ * this one ends up with nothing left to override.
+ */
+export declare function applyToPrefab(world: World, entity: Entity, files?: PrefabFiles): Promise<{
+    prefab: string;
+    applied: Overrides;
+    file?: string;
+}>;

package/dist/prefab-file.js

@@ -0,0 +1,446 @@
+import { assetServer, defineImporter } from "@aethervtt/shard-assets";
+import {
+  defineSchema,
+  isPlainObject,
+  pointer,
+  ShardError,
+  World
+} from "@aethervtt/shard-core";
+import { PrefabAssets, PrefabInstance } from "./components.js";
+import { PREFAB_VERSION } from "./format.js";
+import { currentOverrides, mergeOverridesIntoPrefab, prefabOfInstance } from "./instances.js";
+import {
+  ALIASES,
+  dedupeErrors,
+  flatten,
+  validateAssetsBlock,
+  validateTree
+} from "./scene.js";
+const PREFAB_FIELDS = [
+  "$schema",
+  "version",
+  "assets",
+  "root",
+  "extends",
+  "rootComponents",
+  "overrides",
+  "children"
+];
+const VARIANT_FIELDS = ["extends", "rootComponents", "overrides", "children"];
+function validatePrefab(world, json, options = {}) {
+  const errors = [];
+  if (!isPlainObject(json)) {
+    return [
+      new ShardError("prefab/invalid", "A prefab file must be a JSON object", {
+        path: "",
+        hint: 'Write { "version": 1, "root": { "name": "...", "components": {...}, "children": [...] } }, or a variant with "extends".'
+      })
+    ];
+  }
+  const file = json;
+  if (file.version !== PREFAB_VERSION) {
+    errors.push(
+      new ShardError(
+        "prefab/unsupported-version",
+        `Prefab version ${JSON.stringify(file.version)} is not supported`,
+        { path: "/version", hint: `Use "version": ${PREFAB_VERSION}.` }
+      )
+    );
+  }
+  for (const key of Object.keys(file)) {
+    if (!PREFAB_FIELDS.includes(key)) {
+      errors.push(
+        new ShardError("prefab/unknown-field", `Unknown prefab field "${key}"`, {
+          path: pointer("", key),
+          hint: 'A prefab has "root" (an entity), or "extends" plus "rootComponents", "overrides", and "children" (a variant).'
+        })
+      );
+    }
+  }
+  validateAssetsBlock(file.assets, errors);
+  const id = options.id ?? "prefab";
+  const catalog = options.catalog ?? true;
+  const isVariant = file.extends !== void 0;
+  if (isVariant && file.root !== void 0) {
+    errors.push(
+      new ShardError("prefab/invalid", 'A prefab has "root" or "extends", not both', {
+        path: "/root",
+        hint: 'A variant takes its root from its base: change it with "rootComponents" and "overrides".'
+      })
+    );
+  }
+  if (!isVariant) {
+    for (const key of VARIANT_FIELDS) {
+      if (key !== "extends" && key in file) {
+        errors.push(
+          new ShardError("prefab/unknown-field", `Only variants (with "extends") have "${key}"`, {
+            path: pointer("", key),
+            hint: 'Write the change into "root" directly.'
+          })
+        );
+      }
+    }
+    if (!isPlainObject(file.root)) {
+      errors.push(
+        new ShardError("prefab/invalid", 'A prefab needs a "root" entity (or "extends")', {
+          path: "/root",
+          hint: 'Give { "name": "ship", "components": {...}, "children": [...] }.'
+        })
+      );
+      return dedupeErrors(errors);
+    }
+    const flat = [
+      { path: ".", parent: void 0, entity: file.root, pointer: "/root" }
+    ];
+    if (Array.isArray(file.root.children))
+      flatten(file.root.children, "/root/children", void 0, flat);
+    else if (file.root.children !== void 0) {
+      errors.push(
+        new ShardError("schema/type-mismatch", '"children" must be an array', {
+          path: "/root/children"
+        })
+      );
+    }
+    validateTree(world, file, flat, errors, { id, catalog, root: true });
+    return dedupeErrors(errors);
+  }
+  const base = file.extends;
+  if (!isPlainObject(base) || typeof base.path !== "string" && typeof base.guid !== "string" || Object.keys(base).some((k) => k !== "path" && k !== "guid")) {
+    errors.push(
+      new ShardError("schema/type-mismatch", '"extends" must be a prefab reference', {
+        path: "/extends",
+        hint: 'Give { "path": "prefabs/ship.prefab.json" }.'
+      })
+    );
+  }
+  if (file.rootComponents !== void 0) {
+    if (!isPlainObject(file.rootComponents)) {
+      errors.push(
+        new ShardError("schema/type-mismatch", '"rootComponents" must be an object', {
+          path: "/rootComponents"
+        })
+      );
+    } else {
+      const root = {
+        path: ".",
+        parent: void 0,
+        entity: { name: "root", components: file.rootComponents },
+        pointer: ""
+      };
+      const before = errors.length;
+      validateTree(world, file, [root], errors, { id, catalog, root: true, inheritsAssets: true });
+      for (let i = before; i < errors.length; i++) {
+        const e = errors[i];
+        errors[i] = new ShardError(
+          e.code,
+          e.message.replace(" at /components", " at /rootComponents"),
+          {
+            path: e.path?.replace(/^\/components/, "/rootComponents"),
+            hint: e.hint
+          }
+        );
+      }
+    }
+  }
+  if (file.children !== void 0) {
+    if (!Array.isArray(file.children)) {
+      errors.push(
+        new ShardError("schema/type-mismatch", '"children" must be an array', {
+          path: "/children"
+        })
+      );
+    } else {
+      const flat = [];
+      flatten(file.children, "/children", void 0, flat);
+      validateTree(world, file, flat, errors, {
+        id,
+        catalog,
+        extraPaths: ["."],
+        inheritsAssets: true
+      });
+    }
+  }
+  if (file.overrides !== void 0 && !isPlainObject(file.overrides)) {
+    errors.push(
+      new ShardError("schema/type-mismatch", '"overrides" must be an object', {
+        path: "/overrides",
+        hint: 'Map paths to component patches: { "Exhaust": { "particles/ParticleSystem": { "timeScale": 2 } } }.'
+      })
+    );
+  }
+  return dedupeErrors(errors);
+}
+function applyVariant(base, variant) {
+  const unknown = [];
+  const merged = mergeOverridesIntoPrefab(
+    { version: PREFAB_VERSION, assets: base.assets, root: base.root },
+    variant.overrides ?? {},
+    (key) => unknown.push(key)
+  );
+  if (unknown.length > 0) {
+    throw new ShardError("prefab/unknown-path", `No entity at "${unknown[0]}" in the base prefab`, {
+      path: pointer("/overrides", unknown[0]),
+      hint: 'Override paths are relative to the root, e.g. "Hull" or "Hull/Cockpit".'
+    });
+  }
+  const root = merged.root;
+  const components = { ...root.components ?? {} };
+  for (const [name, patch] of Object.entries(variant.rootComponents ?? {})) {
+    const own = { ...components[name] ?? {} };
+    for (const [alias, { field }] of Object.entries(ALIASES[name] ?? {})) {
+      if (field in patch) delete own[alias];
+      if (alias in patch) delete own[field];
+    }
+    components[name] = { ...own, ...patch };
+  }
+  const out = {
+    version: PREFAB_VERSION,
+    root: {
+      ...root,
+      components,
+      ...variant.children?.length || root.children ? { children: [...root.children ?? [], ...variant.children ?? []] } : {}
+    }
+  };
+  const assets = { ...base.assets ?? {}, ...variant.assets ?? {} };
+  if (Object.keys(assets).length > 0) out.assets = assets;
+  return out;
+}
+function referencedPaths(file) {
+  const out = /* @__PURE__ */ new Set();
+  const collect = (value) => {
+    if (Array.isArray(value)) value.forEach(collect);
+    else if (isPlainObject(value)) {
+      for (const [k, v] of Object.entries(value)) {
+        if (k === "path" && typeof v === "string") {
+          if (!v.startsWith("#") && !v.startsWith("procedural:")) out.add(v);
+        } else collect(v);
+      }
+    }
+  };
+  collect(file.root);
+  return [...out];
+}
+function prefabRefs(json) {
+  const out = [];
+  if (typeof json.extends?.path === "string") out.push(json.extends.path);
+  const walk = (entities) => {
+    if (!Array.isArray(entities)) return;
+    for (const e of entities) {
+      const ref = e?.components?.["scene/PrefabInstance"]?.prefab;
+      if (isPlainObject(ref) && typeof ref.path === "string") out.push(ref.path);
+      walk(e?.children);
+    }
+  };
+  walk(json.root ? [json.root] : []);
+  walk(json.children);
+  return out;
+}
+function parse(text, path) {
+  let json;
+  try {
+    json = JSON.parse(text);
+  } catch (cause) {
+    throw new ShardError("assets/import-failed", `${path} isn't valid JSON`, { path, cause });
+  }
+  if (isPlainObject(json) && "$schema" in json) {
+    const { $schema: _, ...rest } = json;
+    json = rest;
+  }
+  return json;
+}
+function invalid(path, errors) {
+  const first = errors[0];
+  return new ShardError(
+    first.code.startsWith("prefab/") ? first.code : "assets/import-failed",
+    `${path}: ${first.message}${errors.length > 1 ? ` (+${errors.length - 1} more)` : ""}`,
+    { path: first.path, hint: first.hint, details: errors }
+  );
+}
+let bare;
+async function resolvePrefab(path, json, read, chain) {
+  bare ??= new World();
+  const errors = validatePrefab(bare, json, { id: path, catalog: false });
+  if (errors.length > 0) throw invalid(path, errors);
+  const seen = [...chain, path];
+  const visit = async (file, stack) => {
+    for (const ref of prefabRefs(file)) {
+      const next = await read(ref);
+      if (stack.includes(next.path)) {
+        throw new ShardError(
+          "prefab/cycle",
+          `${seen[0]} contains or extends itself (${[...stack, next.path].join(" \u2192 ")})`,
+          {
+            path: seen[0],
+            hint: "A prefab can\u2019t contain or extend itself, directly or through others."
+          }
+        );
+      }
+      await visit(next.json, [...stack, next.path]);
+    }
+  };
+  await visit(json, seen);
+  if (json.extends === void 0) return { file: json, bases: [] };
+  const base = await read(json.extends.path);
+  const resolved = await resolvePrefab(base.path, base.json, read, seen);
+  return { file: applyVariant(resolved.file, json), bases: [base.path, ...resolved.bases] };
+}
+function countEntities(root) {
+  const out = [];
+  const walk = (list, prefix) => {
+    for (const e of list ?? []) {
+      const path = prefix ? `${prefix}/${e.name}` : e.name;
+      out.push(path);
+      walk(e.children, path);
+    }
+  };
+  walk(root?.children, "");
+  return out;
+}
+const NoSettings = defineSchema(
+  "scene/PrefabSettings",
+  {},
+  { description: "None: the prefab is the file." }
+);
+const PrefabImporter = defineImporter({
+  name: "prefab",
+  version: 1,
+  extensions: [".prefab.json"],
+  settings: NoSettings,
+  async import(source, ctx) {
+    const json = parse(source.text(), source.path);
+    const decoder = new TextDecoder();
+    const read = async (p) => {
+      const full = ctx.resolve(p);
+      let bytes;
+      try {
+        bytes = await ctx.read(p);
+      } catch (cause) {
+        throw new ShardError(
+          "prefab/not-found",
+          `${source.path} refers to ${p}, which can't be read`,
+          {
+            path: p,
+            hint: 'Check the path: prefab paths start at an asset root, e.g. "prefabs/ship.prefab.json".',
+            cause
+          }
+        );
+      }
+      return { path: full, json: parse(decoder.decode(bytes), full) };
+    };
+    const { file, bases } = await resolvePrefab(source.path, json, read, []);
+    const paths = countEntities(file.root);
+    const dependencies = referencedPaths(file);
+    return {
+      assets: [
+        {
+          label: "",
+          type: "Prefab",
+          json: file,
+          ...dependencies.length ? { dependencies } : {},
+          info: {
+            root: file.root?.name ?? null,
+            entities: paths.length + 1,
+            tree: paths.slice(0, 200),
+            ...bases.length ? { extends: bases } : {}
+          }
+        }
+      ]
+    };
+  }
+});
+const registered = /* @__PURE__ */ new WeakMap();
+function registerPrefab(world, path, json) {
+  const file = json;
+  const errors = validatePrefab(world, json, { id: path, catalog: false });
+  if (errors.length > 0) {
+    throw new ShardError(
+      "prefab/invalid",
+      `Prefab "${path}" has ${errors.length} error${errors.length === 1 ? "" : "s"}; first: ${errors[0].message}`,
+      { path: errors[0].path, hint: errors[0].hint, details: errors }
+    );
+  }
+  let files = registered.get(world);
+  if (!files) {
+    files = /* @__PURE__ */ new Map();
+    registered.set(world, files);
+  }
+  files.set(path, file);
+  const server = assetServer(world);
+  const resolve = (p, f, chain) => {
+    if (chain.includes(p)) {
+      throw new ShardError(
+        "prefab/cycle",
+        `${chain[0]} extends itself (${[...chain, p].join(" \u2192 ")})`,
+        {
+          path: chain[0],
+          hint: "A prefab can\u2019t contain or extend itself, directly or through others."
+        }
+      );
+    }
+    if (f.extends === void 0) return f;
+    const basePath = f.extends.path ?? server.entry({ guid: f.extends.guid })?.path ?? "";
+    const own = files.get(basePath);
+    const entry = server.entry(f.extends);
+    const base = own ? resolve(basePath, own, [...chain, p]) : entry ? world.resource(PrefabAssets).byGuid(entry.guid) : void 0;
+    if (!base) {
+      throw new ShardError("prefab/not-loaded", `${p} extends ${basePath}, which isn't loaded`, {
+        hint: "Register (or load) the base prefab first."
+      });
+    }
+    return applyVariant(base, f);
+  };
+  const publish = (p, f) => {
+    const resolved = resolve(p, f, []);
+    server.updateVirtual(`mem:prefab:${p}`, p, "Prefab", () => resolved);
+  };
+  publish(path, file);
+  const dependsOn = (f, target, depth = 0) => {
+    const base = f.extends?.path;
+    if (!base || depth > 16) return false;
+    return base === target || files.has(base) && dependsOn(files.get(base), target, depth + 1);
+  };
+  for (const [p, f] of files) if (p !== path && dependsOn(f, path)) publish(p, f);
+}
+function registeredPrefab(world, path) {
+  return registered.get(world)?.get(path);
+}
+async function applyToPrefab(world, entity, files) {
+  const entry = prefabOfInstance(world, entity);
+  if (!entry) {
+    throw new ShardError(
+      "prefab/not-an-instance",
+      `Entity ${entity} isn't a spawned prefab instance`,
+      {
+        hint: 'Pass the entity that has scene/PrefabInstance (e.g. "player-ship"), once it has spawned.'
+      }
+    );
+  }
+  const overrides = currentOverrides(world, entity) ?? {};
+  const own = registeredPrefab(world, entry.path);
+  const clear = () => world.set(entity, PrefabInstance, { overrides: {} });
+  if (own) {
+    clear();
+    registerPrefab(world, entry.path, mergeOverridesIntoPrefab(own, overrides));
+    return { prefab: entry.path, applied: overrides };
+  }
+  if (!entry.source || !files) {
+    throw new ShardError("prefab/read-only", `Can't write ${entry.path} from this host`, {
+      hint: "Apply from the CLI or Studio, which can write the project folder."
+    });
+  }
+  const json = JSON.parse(await files.readText(entry.source));
+  const merged = mergeOverridesIntoPrefab(json, overrides);
+  await files.writeText(entry.source, `${JSON.stringify(merged, null, 2)}
+`);
+  clear();
+  await assetServer(world).reimport(entry.source);
+  return { prefab: entry.path, applied: overrides, file: entry.source };
+}
+export {
+  PrefabImporter,
+  applyToPrefab,
+  applyVariant,
+  registerPrefab,
+  registeredPrefab,
+  validatePrefab
+};

package/dist/procedural.d.ts

@@ -0,0 +1,36 @@
+import { type ResolvedAsset, type World } from '@aethervtt/shard-core';
+import { type Mesh } from '@aethervtt/shard-mesh';
+type Factory = (params: Record<string, number>) => Mesh;
+/** Procedural mesh sources, by name, with the parameters each accepts. */
+export declare const PROCEDURAL_MESHES: Record<string, {
+    params: readonly string[];
+    create: Factory;
+}>;
+export interface ProceduralRef {
+    source: string;
+    params: Record<string, number>;
+    /** Canonical key: equal refs share one mesh (and instance together). */
+    key: string;
+}
+/** Parses `procedural:box?x=4&y=1` (or a name + params object). Throws with a hint on bad input. */
+export declare function parseProcedural(source: string, params?: Record<string, unknown>, path?: string): ProceduralRef;
+/**
+ * A kind of `procedural:` ref beyond the built-in meshes, e.g. project generators
+ * (`procedural:star-explorer/Rock?seed=3`). `spec` is everything after `procedural:`.
+ */
+export interface ProceduralSource {
+    /** Whether this source handles refs named `name` (the part before `?`). */
+    handles(name: string): boolean;
+    /** Checks a ref without making anything; throws a ShardError (with `path`) if it's invalid. */
+    check(spec: string, path?: string): {
+        type: string;
+    };
+    /** The asset for a ref, registered with the world's asset server (it may still be loading). */
+    resolve(world: World, spec: string): ResolvedAsset;
+}
+/** Adds a source of `procedural:` refs. Once per source. */
+export declare function defineProceduralSource(source: ProceduralSource): ProceduralSource;
+export declare function allProceduralSources(): readonly ProceduralSource[];
+/** The source for a `procedural:` spec, if it isn't a built-in mesh. */
+export declare function proceduralSourceFor(spec: string): ProceduralSource | undefined;
+export {};

package/dist/procedural.js

@@ -0,0 +1,84 @@
+import { ShardError } from "@aethervtt/shard-core";
+import {
+  box,
+  capsule,
+  cone,
+  cube,
+  cylinder,
+  plane,
+  sphere,
+  torus
+} from "@aethervtt/shard-mesh";
+const PROCEDURAL_MESHES = {
+  box: { params: ["x", "y", "z"], create: (p) => box(p) },
+  cube: { params: ["size"], create: (p) => cube(p) },
+  sphere: { params: ["radius", "segments", "rings"], create: (p) => sphere(p) },
+  plane: { params: ["size", "subdivisions"], create: (p) => plane(p) },
+  cylinder: { params: ["radius", "radiusTop", "height", "segments"], create: (p) => cylinder(p) },
+  cone: { params: ["radius", "height", "segments"], create: (p) => cone(p) },
+  capsule: { params: ["radius", "height", "segments", "rings"], create: (p) => capsule(p) },
+  torus: {
+    params: ["radius", "tube", "radialSegments", "tubularSegments"],
+    create: (p) => torus(p)
+  }
+};
+function parseProcedural(source, params = {}, path) {
+  let name = source;
+  const all = { ...params };
+  const q = source.indexOf("?");
+  if (q !== -1) {
+    name = source.slice(0, q);
+    for (const pair of source.slice(q + 1).split("&")) {
+      if (!pair) continue;
+      const [k, v] = pair.split("=");
+      all[k] = v === void 0 ? void 0 : Number(v);
+    }
+  }
+  const def = PROCEDURAL_MESHES[name];
+  if (!def) {
+    throw new ShardError("scene/unknown-procedural", `Unknown procedural mesh "${name}"`, {
+      path,
+      hint: `Use one of: ${Object.keys(PROCEDURAL_MESHES).join(", ")}.`
+    });
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(all)) {
+    if (!def.params.includes(k)) {
+      throw new ShardError("scene/unknown-procedural-param", `"${name}" has no parameter "${k}"`, {
+        path,
+        hint: `Parameters: ${def.params.join(", ")}.`
+      });
+    }
+    if (typeof v !== "number" || !Number.isFinite(v)) {
+      throw new ShardError(
+        "scene/invalid-procedural-param",
+        `"${name}" parameter "${k}" must be a number`,
+        { path }
+      );
+    }
+    out[k] = v;
+  }
+  const key = `procedural:${name}?${Object.keys(out).sort().map((k) => `${k}=${out[k]}`).join("&")}`;
+  return { source: name, params: out, key };
+}
+const sources = [];
+function defineProceduralSource(source) {
+  if (!sources.includes(source)) sources.push(source);
+  return source;
+}
+function allProceduralSources() {
+  return sources;
+}
+function proceduralSourceFor(spec) {
+  const q = spec.indexOf("?");
+  const name = q === -1 ? spec : spec.slice(0, q);
+  if (PROCEDURAL_MESHES[name]) return void 0;
+  return sources.find((s) => s.handles(name));
+}
+export {
+  PROCEDURAL_MESHES,
+  allProceduralSources,
+  defineProceduralSource,
+  parseProcedural,
+  proceduralSourceFor
+};