@aethervtt/shard-scene 0.0.1

package/dist/instances.js

@@ -0,0 +1,1295 @@
+import { assetServer } from "@aethervtt/shard-assets";
+import {
+  ChildOf,
+  Children,
+  Commands,
+  defineSystem,
+  isPlainObject,
+  onAdd,
+  onRemove,
+  onSet,
+  PreUpdate,
+  pointer,
+  ShardError,
+  World
+} from "@aethervtt/shard-core";
+import { LogResource } from "@aethervtt/shard-runtime";
+import { Transform } from "@aethervtt/shard-transform";
+import * as componentsModule from "./components.js";
+import {
+  InstancePart,
+  PrefabAssets,
+  PrefabInstance,
+  SceneAssets,
+  SceneIndex,
+  SceneInstance,
+  SceneMember
+} from "./components.js";
+import * as prefabFileModule from "./prefab-file.js";
+import {
+  ALIASES,
+  componentDef,
+  equal,
+  expandAliases,
+  rebase,
+  resolveAssets,
+  serializeComponents
+} from "./scene.js";
+let nestedCounter = 0;
+function sourceFile(world, entry) {
+  if (entry.type === "Prefab") return world.tryResource(PrefabAssets)?.byGuid(entry.guid);
+  if (entry.type === "Scene") return world.tryResource(SceneAssets)?.byGuid(entry.guid);
+  return void 0;
+}
+function expandComponents(components) {
+  const out = {};
+  if (!isPlainObject(components)) return out;
+  for (const [name, raw] of Object.entries(components)) {
+    if (isPlainObject(raw))
+      out[name] = expandAliases(name, raw, "", []);
+  }
+  return out;
+}
+function instanceDefOf(components) {
+  if (components[PrefabInstance.name]) return PrefabInstance;
+  if (components[SceneInstance.name]) return SceneInstance;
+  return void 0;
+}
+function handleOf(json, field) {
+  const ref = json?.[field];
+  return isPlainObject(ref) ? ref : void 0;
+}
+function flattenSource(world, entry, stack) {
+  if (stack.includes(entry.guid)) {
+    throw new ShardError(
+      "prefab/cycle",
+      `${entry.path} contains itself (${[...stack.map((g) => assetServer(world).entry(g)?.path ?? g), entry.path].join(" \u2192 ")})`,
+      {
+        path: entry.path,
+        hint: "A prefab can\u2019t contain or extend itself, directly or through others."
+      }
+    );
+  }
+  const file = sourceFile(world, entry);
+  const flat = {
+    root: void 0,
+    rootName: void 0,
+    nodes: [],
+    index: /* @__PURE__ */ new Map(),
+    removed: /* @__PURE__ */ new Set(),
+    touched: /* @__PURE__ */ new Set(),
+    assets: { ...file?.assets ?? {} },
+    deps: /* @__PURE__ */ new Map([[entry.guid, entry.version]]),
+    missing: /* @__PURE__ */ new Set(),
+    warnings: []
+  };
+  if (!file) return flat;
+  let children;
+  if (entry.type === "Prefab") {
+    const root = file.root;
+    flat.root = expandComponents(root?.components);
+    flat.rootName = root?.name;
+    children = root?.children ?? [];
+  } else {
+    children = file.entities ?? [];
+  }
+  const add = (list, prefix, parent) => {
+    for (const e of list) {
+      const path = prefix === "" ? e.name : `${prefix}/${e.name}`;
+      const i = flat.nodes.length;
+      flat.nodes.push({
+        name: e.name,
+        path,
+        parent,
+        components: expandComponents(e.components),
+        nested: false
+      });
+      flat.index.set(path, i);
+      if (Array.isArray(e.children)) add(e.children, path, i);
+    }
+  };
+  add(children, "", -1);
+  const own = flat.nodes.length;
+  const server = assetServer(world);
+  const next = [...stack, entry.guid];
+  for (let i = flat.root ? -1 : 0; i < own; i++) {
+    const components = i === -1 ? flat.root : flat.nodes[i].components;
+    const def = instanceDefOf(components);
+    if (!def) continue;
+    const instance = components[def.name];
+    const ref = handleOf(instance, def === PrefabInstance ? "prefab" : "scene");
+    const nested = ref && server.entry(ref);
+    if (!nested) continue;
+    if (nested.state === "unloaded" || nested.state === "loading") {
+      server.request(nested.guid);
+      flat.missing.add(nested.guid);
+      continue;
+    }
+    if (nested.state !== "loaded") continue;
+    inline(flat, i, flattenSource(world, nested, next));
+    if (i === -1) delete components[def.name];
+    const overrides = instance.overrides;
+    const at = i === -1 ? "" : flat.nodes[i].path;
+    if (isPlainObject(overrides)) {
+      applyOverrides(flat, overrides, at, (key, error) => {
+        flat.warnings.push(stale(`${entry.path}: ${at || flat.rootName}`, key, error));
+      });
+    }
+  }
+  return flat;
+}
+function stale(where, key, error) {
+  return new ShardError("prefab/stale-override", `${where}: override "${key}": ${error.message}`, {
+    path: error.path,
+    hint: "The prefab changed (a renamed or removed entity?). The override is kept in the file; fix or delete it."
+  });
+}
+function inline(flat, at, nested) {
+  const hostPath = at === -1 ? "" : flat.nodes[at].path;
+  const hostComponents = at === -1 ? flat.root : flat.nodes[at].components;
+  const prefix = `n${nestedCounter++}~`;
+  for (const [name, asset] of Object.entries(nested.assets)) flat.assets[`${prefix}${name}`] = asset;
+  const move = (components) => {
+    const out = {};
+    for (const [name, json] of Object.entries(components))
+      out[name] = rebaseJson(name, json, hostPath, prefix);
+    return out;
+  };
+  if (nested.root) {
+    const root = move(nested.root);
+    for (const [name, json] of Object.entries(root)) {
+      hostComponents[name] = { ...json, ...hostComponents[name] ?? {} };
+    }
+  }
+  const offset = flat.nodes.length;
+  for (let k = 0; k < nested.nodes.length; k++) {
+    const n = nested.nodes[k];
+    const path = hostPath === "" ? n.path : `${hostPath}/${n.path}`;
+    flat.nodes.push({
+      name: n.name,
+      path,
+      parent: n.parent === -1 ? at : n.parent + offset,
+      components: move(n.components),
+      nested: n.nested
+    });
+    flat.index.set(path, offset + k);
+    if (nested.removed.has(k)) flat.removed.add(offset + k);
+  }
+  if (at !== -1) flat.nodes[at].nested = true;
+  for (const [g, v] of nested.deps) flat.deps.set(g, v);
+  for (const g of nested.missing) flat.missing.add(g);
+  flat.warnings.push(...nested.warnings);
+}
+function rebaseJson(name, json, base, prefix) {
+  const def = componentDef(name);
+  const renameAssets = (value) => {
+    if (Array.isArray(value)) return value.map(renameAssets);
+    if (!isPlainObject(value)) return value;
+    const out2 = {};
+    for (const [k, v] of Object.entries(value)) {
+      out2[k] = k === "path" && typeof v === "string" && v.startsWith("#") ? `#${prefix}${v.slice(1)}` : renameAssets(v);
+    }
+    return out2;
+  };
+  const out = renameAssets(json);
+  if (def) {
+    for (const { name: field, field: type } of def.layout) {
+      const v = out[field];
+      if (type.kind === "entity" && typeof v === "string" && base !== "")
+        out[field] = v === "." ? base : `${base}/${v}`;
+    }
+  }
+  return out;
+}
+function fork(flat) {
+  return {
+    ...flat,
+    nodes: flat.nodes.slice(),
+    removed: new Set(flat.removed),
+    touched: /* @__PURE__ */ new Set(),
+    warnings: []
+  };
+}
+function touch(flat, i) {
+  if (flat.touched.has(i)) return flat.nodes[i];
+  const node = { ...flat.nodes[i], components: { ...flat.nodes[i].components } };
+  flat.nodes[i] = node;
+  flat.touched.add(i);
+  return node;
+}
+function isRemoved(flat, i) {
+  for (let k = i; k !== -1; k = flat.nodes[k].parent) if (flat.removed.has(k)) return true;
+  return false;
+}
+function splitComponentKey(flat, key) {
+  const parts = key.split("/");
+  if (parts.length < 3) return void 0;
+  const component = parts.slice(-2).join("/");
+  const i = flat.index.get(parts.slice(0, -2).join("/"));
+  return i === void 0 || !componentDef(component) ? void 0 : { i, component };
+}
+function applyOverrides(flat, overrides, prefix, report, validate) {
+  for (const [key, value] of Object.entries(overrides)) {
+    const at = pointer("", key);
+    const full = prefix === "" ? key : `${prefix}/${key}`;
+    if (value === null) {
+      const i2 = flat.index.get(full);
+      if (i2 !== void 0) {
+        flat.removed.add(i2);
+        continue;
+      }
+      const cut = splitComponentKey(flat, full);
+      if (cut) delete touch(flat, cut.i).components[cut.component];
+      else report(key, unknownPath(key, at, flat));
+      continue;
+    }
+    if (!isPlainObject(value)) {
+      report(
+        key,
+        new ShardError("schema/type-mismatch", `Override "${key}" must be an object or null`, {
+          path: at,
+          hint: 'Give { "<component>": { fields } } to change an entity, or null to remove it.'
+        })
+      );
+      continue;
+    }
+    const i = flat.index.get(full);
+    if (i === void 0) {
+      report(key, unknownPath(key, at, flat));
+      continue;
+    }
+    for (const [name, patch] of Object.entries(value)) {
+      const where = pointer(at, name);
+      const def = componentDef(name);
+      if (!def) {
+        report(
+          key,
+          new ShardError("scene/unknown-component", `Unknown component "${name}"`, {
+            path: where,
+            hint: 'Use a registered name like "core/Transform" or "render/Camera3d" (see .agents/components.md).'
+          })
+        );
+        continue;
+      }
+      if (!def.serializable || def === ChildOf) {
+        report(
+          key,
+          new ShardError("scene/derived-component", `"${name}" can't be overridden`, {
+            path: where
+          })
+        );
+        continue;
+      }
+      if (patch === null) {
+        delete touch(flat, i).components[name];
+        continue;
+      }
+      if (!isPlainObject(patch)) {
+        report(
+          key,
+          new ShardError("schema/type-mismatch", `"${name}" must be an object or null`, {
+            path: where
+          })
+        );
+        continue;
+      }
+      const errors = [];
+      const expanded = expandAliases(name, patch, where, errors);
+      const merged = { ...flat.nodes[i].components[name] ?? {}, ...expanded };
+      if (validate) for (const e of validate(def, merged)) errors.push(rebase(e, where));
+      if (errors.length > 0) {
+        for (const e of errors) report(key, e);
+        continue;
+      }
+      touch(flat, i).components[name] = merged;
+    }
+  }
+}
+function unknownPath(key, at, flat) {
+  const names = flat.nodes.filter((n) => n.parent === -1).map((n) => n.name);
+  return new ShardError("prefab/unknown-path", `No generated entity at "${key}"`, {
+    path: at,
+    hint: names.length ? `Paths are relative to the instance, e.g. "${names[0]}"${flat.nodes.find((n) => n.parent !== -1) ? ` or "${flat.nodes.find((n) => n.parent !== -1).path}"` : ""}. End a path with a component name to remove that component.` : "This instance generates no entities."
+  });
+}
+function compileNode(world, flat, components, path, parent, ctx) {
+  const defs = [];
+  const values = [];
+  const refs = [];
+  for (const [name, json] of Object.entries(components)) {
+    const def = componentDef(name);
+    if (!def?.serializable || def === ChildOf) continue;
+    let value;
+    try {
+      value = def.deserialize(json, ctx);
+    } catch (err) {
+      world.tryResource(LogResource)?.error(
+        new ShardError(
+          "prefab/invalid-component",
+          `${path || "(root)"} ${name}: ${err.message}`,
+          {
+            hint: err.hint
+          }
+        )
+      );
+      continue;
+    }
+    for (const { name: field, field: type } of def.layout) {
+      const v = json[field];
+      if (type.kind !== "entity" || typeof v !== "string") continue;
+      refs.push({ component: defs.length, field, target: v === "." ? -1 : flat.index.get(v) });
+      value[field] = null;
+    }
+    defs.push(def);
+    values.push(value);
+  }
+  const childOf = { parent: -1 };
+  const part = { instance: -1, path };
+  const inits = defs.map((d, k) => [d, values[k]]);
+  inits.push([ChildOf, childOf], [InstancePart, part]);
+  return { path, parent, defs, values, refs, inits, childOf, part };
+}
+function compileContext(world, flat, id, requested) {
+  return {
+    resolveAsset: resolveAssets(world, flat, id, "create", requested),
+    resolveEntity: (path) => path === "." || flat.index.has(path) ? 0 : void 0
+  };
+}
+function compileTemplate(world, entry) {
+  const flat = flattenSource(world, entry, []);
+  const requested = /* @__PURE__ */ new Set();
+  const ctx = compileContext(world, flat, entry.path, requested);
+  const template = {
+    entry,
+    flat,
+    root: flat.root ? compileNode(world, flat, flat.root, "", -1, ctx) : void 0,
+    entities: [],
+    requested,
+    ctx,
+    canonical: void 0
+  };
+  for (let i = 0; i < flat.nodes.length; i++) {
+    const n = flat.nodes[i];
+    template.entities.push(
+      isRemoved(flat, i) ? void 0 : compileNode(world, flat, n.components, n.path, n.parent, ctx)
+    );
+  }
+  const log = world.tryResource(LogResource);
+  for (const w of flat.warnings) warn(log, w);
+  return template;
+}
+function warn(log, error) {
+  log?.log("warn", error.message, { code: error.code, path: error.path, hint: error.hint });
+}
+function planFor(world, template, overrides, report) {
+  if (!overrides || Object.keys(overrides).length === 0) return template;
+  const flat = fork(template.flat);
+  const check = checkContext(world, flat, template.entry.path);
+  applyOverrides(flat, overrides, "", report, (def, json) => def.validate(json, check));
+  const ctx = template.ctx;
+  const entities = [];
+  for (let i = 0; i < flat.nodes.length; i++) {
+    if (isRemoved(flat, i)) entities.push(void 0);
+    else if (flat.touched.has(i)) {
+      const n = flat.nodes[i];
+      entities.push(compileNode(world, flat, n.components, n.path, n.parent, ctx));
+    } else entities.push(template.entities[i]);
+  }
+  return { flat, root: template.root, entities };
+}
+function checkContext(world, flat, id) {
+  return {
+    resolveAsset: resolveAssets(world, flat, id, "check"),
+    resolveEntity: (path) => path === "." || flat.index.has(path) ? 0 : void 0
+  };
+}
+function handleEntry(world, ref) {
+  return ref ? assetServer(world).entry(ref) : void 0;
+}
+const sceneInstanceKind = {
+  def: SceneInstance,
+  source: (world, value) => handleEntry(world, value.scene)
+};
+const prefabInstanceKind = {
+  def: PrefabInstance,
+  source: (world, value) => handleEntry(world, value.prefab)
+};
+const kinds = [sceneInstanceKind, prefabInstanceKind];
+function defineInstanceKind(kind) {
+  const i = kinds.findIndex((k) => k.def.name === kind.def.name);
+  if (i === -1) kinds.push(kind);
+  else kinds[i] = kind;
+  return kind;
+}
+function instanceKinds() {
+  return kinds;
+}
+function instanceKindOf(def) {
+  return kinds.find((k) => k.def === def);
+}
+const perWorld = /* @__PURE__ */ new WeakMap();
+function stateOf(world) {
+  let s = perWorld.get(world);
+  if (!s) {
+    const off = assetServer(world).onEvent((e) => {
+      if (e.kind !== "loaded" && e.kind !== "modified") return;
+      const type = assetServer(world).entry(e.guid)?.type;
+      if (type === "Scene" || type === "Prefab") updateInstances(world);
+    });
+    s = { states: /* @__PURE__ */ new Map(), templates: /* @__PURE__ */ new Map(), off, dirty: true, observed: /* @__PURE__ */ new Set() };
+    perWorld.set(world, s);
+  }
+  if (s.observed.size !== kinds.length) {
+    const state = s;
+    const mark = () => {
+      state.dirty = true;
+    };
+    for (const { def } of kinds) {
+      if (state.observed.has(def)) continue;
+      state.observed.add(def);
+      world.observe(onAdd(def), mark);
+      world.observe(onSet(def), mark);
+      world.observe(onRemove(def), mark);
+    }
+  }
+  return s;
+}
+function hookInstances(world) {
+  stateOf(world);
+}
+function releaseSceneHooks(world) {
+  perWorld.get(world)?.off();
+  perWorld.delete(world);
+}
+function isCurrent(world, template) {
+  const server = assetServer(world);
+  for (const [guid, version] of template.flat.deps) {
+    const e = server.entry(guid);
+    if (!e || e.version !== version) return false;
+  }
+  return true;
+}
+function templateFor(world, entry) {
+  const s = stateOf(world);
+  const cached = s.templates.get(entry.guid);
+  if (cached && isCurrent(world, cached) && cached.flat.missing.size === 0) return cached;
+  const template = compileTemplate(world, entry);
+  s.templates.set(entry.guid, template);
+  return template;
+}
+function resolveRefs(t, ids, instance) {
+  for (const r of t.refs) {
+    const value = { ...t.values[r.component] };
+    value[r.field] = r.target === -1 ? instance : (ids[r.target] ?? -1) < 0 ? null : ids[r.target];
+    t.inits[r.component][1] = value;
+  }
+}
+function reserve(world, plan) {
+  const ids = new Array(plan.entities.length);
+  for (let i = 0; i < plan.entities.length; i++)
+    ids[i] = plan.entities[i] ? world.reserveEntity() : -1;
+  return ids;
+}
+function spawnReserved(world, plan, instance, ids, member, paths, mark) {
+  const scene = member ? world.tryResource(SceneIndex)?.get(member.scene) : void 0;
+  for (let i = 0; i < plan.entities.length; i++) {
+    const t = plan.entities[i];
+    const id = ids[i];
+    if (!t || id < 0) continue;
+    const parent = t.parent === -1 ? instance : ids[t.parent];
+    if (parent < 0) continue;
+    t.childOf.parent = parent;
+    t.part.instance = instance;
+    if (t.refs.length > 0) resolveRefs(t, ids, instance);
+    if (member) {
+      const path = `${member.path}/${t.path}`;
+      const inits = [
+        ...t.inits,
+        [SceneMember, { scene: member.scene, path }]
+      ];
+      if (mark) inits.push([mark, {}]);
+      world.spawnReserved(id, inits);
+      scene?.entities.set(path, id);
+      paths?.push(path);
+    } else {
+      world.spawnReserved(id, mark ? [...t.inits, [mark, {}]] : t.inits);
+    }
+  }
+}
+function despawnGenerated(world, state, keepUnder) {
+  if (keepUnder !== void 0 && world.isAlive(keepUnder)) {
+    const generated = new Set(state.ids);
+    const foreign = [];
+    for (const id of state.ids) {
+      if (id < 0 || !world.isAlive(id)) continue;
+      const children = world.tryGet(id, Children)?.entities;
+      if (!children) continue;
+      for (const child of children) {
+        if (child === null || generated.has(child) || !world.isAlive(child)) continue;
+        if (world.has(child, InstancePart)) continue;
+        foreign.push(child);
+      }
+    }
+    for (const child of foreign) world.add(child, ChildOf, { parent: keepUnder });
+  }
+  for (let i = 0; i < state.ids.length; i++) {
+    const t = state.plan.entities[i];
+    const id = state.ids[i];
+    if (t && t.parent === -1 && world.isAlive(id)) world.despawn(id);
+  }
+  const scene = state.sceneId === void 0 ? void 0 : world.tryResource(SceneIndex)?.get(state.sceneId);
+  if (scene) for (const path of state.paths) scene.entities.delete(path);
+}
+function memberOf(world, entity) {
+  const m = world.tryGet(entity, SceneMember);
+  return m ? { scene: m.scene, path: m.path } : void 0;
+}
+function ownFields(world, entity) {
+  const out = /* @__PURE__ */ new Map();
+  const member = world.tryGet(entity, SceneMember);
+  const authored = member ? world.tryResource(SceneIndex)?.get(member.scene)?.authored.get(entity) : void 0;
+  if (authored) {
+    for (const [name, json] of Object.entries(expandComponents(authored.components)))
+      out.set(name, new Set(Object.keys(json)));
+    return out;
+  }
+  for (const def of world.componentsOf(entity)) {
+    if (!def.serializable || def === ChildOf) continue;
+    const now = def.serialize(world.get(entity, def));
+    const defaults = def.serialize(def.defaults());
+    const fields = Object.keys(now).filter((f) => !equal(now[f], defaults[f]));
+    if (fields.length > 0) out.set(def.name, new Set(fields));
+  }
+  return out;
+}
+function applyRoot(world, entity, state) {
+  const root = state.plan.root;
+  if (!root) return;
+  const canonical = canonicalOf(state.template).get(-1);
+  const prev = state.applied;
+  resolveRefs(root, state.ids, entity);
+  const member = world.tryGet(entity, SceneMember);
+  const loaded = member ? world.tryResource(SceneIndex)?.get(member.scene)?.loaded.get(entity) : void 0;
+  for (let k = 0; k < root.defs.length; k++) {
+    const def = root.defs[k];
+    const value = root.inits[k][1];
+    if (!world.has(entity, def)) {
+      if (prev?.has(def.name)) continue;
+      world.add(entity, def, value);
+      loaded?.set(def.name, def.serialize(world.get(entity, def)));
+      continue;
+    }
+    const own = state.own.get(def.name);
+    const before = prev?.get(def.name);
+    const current = before ? def.serialize(world.get(entity, def)) : void 0;
+    const partial = {};
+    const written = [];
+    for (const field of Object.keys(def.fields)) {
+      if (own?.has(field)) continue;
+      const isEntity = def.fields[field].kind === "entity";
+      if (!isEntity && before && current && !equal(current[field], before[field])) continue;
+      partial[field] = value[field];
+      written.push(field);
+    }
+    if (written.length === 0) continue;
+    world.set(entity, def, partial);
+    if (loaded) {
+      const now = def.serialize(world.get(entity, def));
+      const base = { ...loaded.get(def.name) ?? now };
+      for (const field of written) base[field] = now[field];
+      loaded.set(def.name, base);
+    }
+  }
+  if (prev) {
+    for (const name of prev.keys()) {
+      if (canonical.has(name) || state.own.has(name)) continue;
+      const def = componentDef(name);
+      if (def) world.remove(entity, def);
+    }
+  }
+  state.applied = canonical;
+}
+function reportTo(world, where) {
+  const log = world.tryResource(LogResource);
+  return (key, error) => warn(log, stale(where, key, error));
+}
+function overridesOf(value) {
+  return isPlainObject(value) ? value : {};
+}
+function instantiate(world, entity, def, template, overrides, previous, keep = false, mark) {
+  const member = memberOf(world, entity);
+  const where = member ? `${member.scene}:${member.path}` : `entity ${entity}`;
+  const plan = planFor(world, template, overrides, reportTo(world, where));
+  const paths = [];
+  let ids;
+  if (keep && previous) {
+    ids = respawnKeeping(world, previous, plan, entity, member, paths, mark);
+  } else {
+    if (previous) despawnGenerated(world, previous, entity);
+    ids = reserve(world, plan);
+    spawnReserved(world, plan, entity, ids, member, paths, mark);
+  }
+  const state = {
+    def,
+    template,
+    plan,
+    overridesKey: JSON.stringify(overrides),
+    overrides,
+    ids,
+    sceneId: member?.scene,
+    paths,
+    own: previous?.own ?? ownFields(world, entity),
+    applied: previous?.applied
+  };
+  if (def === PrefabInstance) applyRoot(world, entity, state);
+  const scene = member ? world.tryResource(SceneIndex)?.get(member.scene) : void 0;
+  if (scene) for (const g of template.requested) scene.assets.add(g);
+  return state;
+}
+function respawnKeeping(world, old, plan, instance, member, paths, mark) {
+  const byPath = /* @__PURE__ */ new Map();
+  for (let i = 0; i < old.ids.length; i++) {
+    const id = old.ids[i];
+    if (id >= 0 && world.isAlive(id)) byPath.set(old.plan.flat.nodes[i].path, i);
+  }
+  const ids = new Array(plan.entities.length);
+  const reused = /* @__PURE__ */ new Set();
+  for (let i = 0; i < plan.entities.length; i++) {
+    if (!plan.entities[i]) {
+      ids[i] = -1;
+      continue;
+    }
+    const k = byPath.get(plan.flat.nodes[i].path);
+    const id = k === void 0 ? -1 : old.ids[k];
+    if (id >= 0) {
+      ids[i] = id;
+      reused.add(id);
+    } else ids[i] = world.reserveEntity();
+  }
+  const generated = new Set(old.ids);
+  for (let i = 0; i < old.ids.length; i++) {
+    const id = old.ids[i];
+    if (id < 0 || reused.has(id) || !world.isAlive(id)) continue;
+    const children = world.tryGet(id, Children)?.entities;
+    if (children) {
+      for (const child of [...children]) {
+        if (child === null || generated.has(child) || !world.isAlive(child)) continue;
+        if (!world.has(child, InstancePart)) world.add(child, ChildOf, { parent: instance });
+      }
+    }
+    world.despawnSingle(id);
+  }
+  const scene = old.sceneId === void 0 ? void 0 : world.tryResource(SceneIndex)?.get(old.sceneId);
+  if (scene) for (const path of old.paths) scene.entities.delete(path);
+  const sceneNow = member ? world.tryResource(SceneIndex)?.get(member.scene) : void 0;
+  const oldDefs = /* @__PURE__ */ new Map();
+  for (let i = 0; i < old.ids.length; i++) {
+    const t = old.plan.entities[i];
+    if (t && reused.has(old.ids[i])) oldDefs.set(old.ids[i], t.defs);
+  }
+  for (let i = 0; i < plan.entities.length; i++) {
+    const t = plan.entities[i];
+    const id = ids[i];
+    if (!t || id < 0) continue;
+    const parent = t.parent === -1 ? instance : ids[t.parent];
+    if (parent < 0) continue;
+    t.childOf.parent = parent;
+    t.part.instance = instance;
+    if (t.refs.length > 0) resolveRefs(t, ids, instance);
+    const path = member ? `${member.path}/${t.path}` : void 0;
+    const inits = member ? [...t.inits, [SceneMember, { scene: member.scene, path }]] : [...t.inits];
+    if (mark) inits.push([mark, {}]);
+    if (reused.has(id)) {
+      const next = new Set(t.defs);
+      for (const d of oldDefs.get(id) ?? [])
+        if (!next.has(d) && world.has(id, d)) world.remove(id, d);
+      for (const [d, value] of inits) world.add(id, d, value);
+      if (!member && world.has(id, SceneMember)) world.remove(id, SceneMember);
+    } else {
+      world.spawnReserved(id, inits);
+    }
+    if (path !== void 0) {
+      sceneNow?.entities.set(path, id);
+      paths.push(path);
+    }
+  }
+  return ids;
+}
+const sceneInstancesSystem = defineSystem({
+  name: "scene/instances",
+  description: "Spawns and respawns SceneInstance and PrefabInstance children.",
+  run: (_, world) => {
+    const s = perWorld.get(world);
+    if (s?.dirty) updateInstances(world);
+  }
+});
+const ScenePlugin = {
+  name: "scene",
+  provides: [componentsModule, prefabFileModule, sceneInstanceKind, prefabInstanceKind],
+  build(app) {
+    hookInstances(app.world);
+    app.addSystems(PreUpdate, sceneInstancesSystem);
+  }
+};
+function updateInstances(world) {
+  const s = stateOf(world);
+  s.dirty = false;
+  const server = assetServer(world);
+  for (const [entity, state] of [...s.states]) {
+    if (world.isAlive(entity) && world.has(entity, state.def)) continue;
+    despawnGenerated(world, state, entity);
+    s.states.delete(entity);
+  }
+  const todo = [];
+  for (const kind of kinds) {
+    const def = kind.def;
+    const q = world.query(kind.nested ? { with: [def] } : { with: [def], without: [InstancePart] });
+    for (const table of q.tables) {
+      for (let i = 0; i < table.count; i++) {
+        const entity = table.entities[i];
+        const value = world.get(entity, def);
+        let entry;
+        try {
+          entry = kind.source(world, value, entity);
+        } catch (err) {
+          world.tryResource(LogResource)?.error(err);
+          continue;
+        }
+        if (!entry) continue;
+        if (entry.state === "unloaded") {
+          server.request(entry.guid);
+          continue;
+        }
+        if (entry.state !== "loaded") continue;
+        const state = s.states.get(entity);
+        const o = overridesOf(value.overrides);
+        if (state && state.def === def && state.template.entry.guid === entry.guid && isCurrent(world, state.template) && state.template.flat.missing.size === 0 && state.overridesKey === JSON.stringify(o)) {
+          continue;
+        }
+        todo.push([entity, kind, entry, o]);
+      }
+    }
+  }
+  for (const [entity, kind, entry, overrides] of todo) {
+    if (!world.isAlive(entity)) continue;
+    let template;
+    try {
+      template = templateFor(world, entry);
+    } catch (err) {
+      world.tryResource(LogResource)?.error(err);
+      continue;
+    }
+    if (template.flat.missing.size > 0) continue;
+    const old = s.states.get(entity);
+    const keep = kind.keepIds === true && old?.def === kind.def;
+    s.states.set(
+      entity,
+      instantiate(world, entity, kind.def, template, overrides, old, keep, kind.mark)
+    );
+  }
+}
+async function settleInstances(world) {
+  const server = assetServer(world);
+  for (let round = 0; round < 8; round++) {
+    updateInstances(world);
+    const pending = /* @__PURE__ */ new Set();
+    for (const kind of kinds) {
+      const def = kind.def;
+      const q = world.query(
+        kind.nested ? { with: [def] } : { with: [def], without: [InstancePart] }
+      );
+      for (const table of q.tables) {
+        for (let i = 0; i < table.count; i++) {
+          const entity = table.entities[i];
+          let entry;
+          try {
+            entry = kind.source(world, world.get(entity, def), entity);
+          } catch {
+            continue;
+          }
+          if (entry && (entry.state === "loading" || entry.state === "unloaded"))
+            pending.add(entry.guid);
+        }
+      }
+    }
+    for (const t of stateOf(world).templates.values())
+      for (const g of t.flat.missing) pending.add(g);
+    if (pending.size === 0) return;
+    await server.whenSettled(pending);
+  }
+}
+function prefabEntry(world, ref) {
+  const entry = assetServer(world).entry(ref);
+  const label = typeof ref === "string" ? ref : ref.path ?? ref.guid;
+  if (entry?.type !== "Prefab") {
+    throw new ShardError("prefab/not-found", `No prefab "${label}" in the catalog`, {
+      hint: "Pass a *.prefab.json path under an asset root (run `shard import` for new files), or register one with registerPrefab."
+    });
+  }
+  return entry;
+}
+async function loadPrefab(world, ref) {
+  const entry = prefabEntry(world, ref);
+  const server = assetServer(world);
+  for (let round = 0; round < 8; round++) {
+    await server.load(entry.guid);
+    const template = templateFor(world, entry);
+    if (template.flat.missing.size === 0) return;
+    await server.whenSettled(template.flat.missing);
+  }
+}
+function spawnPrefab(target, ref, options = {}) {
+  const world = target instanceof Commands ? target.world : target;
+  const entry = prefabEntry(world, ref);
+  let template;
+  if (entry.state === "loaded") {
+    const s = stateOf(world);
+    const cached = s.templates.get(entry.guid);
+    template = cached && isCurrent(world, cached) ? cached : templateFor(world, entry);
+  }
+  if (!template || template.flat.missing.size > 0) {
+    throw new ShardError("prefab/not-loaded", `Prefab ${entry.path} isn't loaded`, {
+      hint: "Preload it with `await loadPrefab(world, path)`, or place it with scene/PrefabInstance, which waits for it to load."
+    });
+  }
+  const overrides = options.overrides;
+  const plan = overrides ? planFor(world, template, overrides, reportTo(world, `spawnPrefab ${entry.path}`)) : template;
+  const root = world.reserveEntity();
+  const ids = reserve(world, plan);
+  const spawn = (w) => spawnInstance(w, entry, template, plan, root, ids, options);
+  if (target instanceof Commands) target.run(spawn);
+  else spawn(world);
+  return root;
+}
+function spawnInstance(world, entry, template, plan, root, ids, options) {
+  const inits = [];
+  const own = /* @__PURE__ */ new Map();
+  if (plan.root) {
+    resolveRefs(plan.root, ids, root);
+    for (let k = 0; k < plan.root.defs.length; k++) inits.push(plan.root.inits[k]);
+  }
+  if (options.transform) {
+    const k = inits.findIndex(([d]) => d === Transform);
+    const value = { ...k === -1 ? {} : inits[k][1], ...options.transform };
+    if (k === -1) inits.push([Transform, value]);
+    else inits[k] = [Transform, value];
+    own.set(Transform.name, new Set(Object.keys(options.transform)));
+  }
+  inits.push([
+    PrefabInstance,
+    {
+      prefab: { type: "Prefab", guid: entry.guid, path: entry.path },
+      overrides: options.overrides ?? {}
+    }
+  ]);
+  if (options.parent !== void 0)
+    inits.push([ChildOf, { parent: options.parent }]);
+  const parent = options.parent === void 0 ? void 0 : memberOf(world, options.parent);
+  const member = parent && {
+    scene: parent.scene,
+    path: `${parent.path}/${template.flat.rootName ?? "prefab"}`
+  };
+  const paths = [];
+  if (member) {
+    inits.push([SceneMember, member]);
+    world.tryResource(SceneIndex)?.get(member.scene)?.entities.set(member.path, root);
+    paths.push(member.path);
+  }
+  world.spawnReserved(root, inits);
+  spawnReserved(world, plan, root, ids, member, paths);
+  const s = stateOf(world);
+  s.states.set(root, {
+    def: PrefabInstance,
+    template,
+    plan,
+    overridesKey: JSON.stringify(options.overrides ?? {}),
+    overrides: options.overrides ?? {},
+    ids,
+    sceneId: member?.scene,
+    paths,
+    own,
+    applied: template.root ? canonicalOf(template).get(-1) : void 0
+  });
+}
+function instanceEntities(world, entity) {
+  const state = perWorld.get(world)?.states.get(entity);
+  const out = /* @__PURE__ */ new Map();
+  if (!state) return out;
+  for (let i = 0; i < state.ids.length; i++) {
+    const id = state.ids[i];
+    if (id >= 0 && world.isAlive(id)) out.set(state.plan.flat.nodes[i].path, id);
+  }
+  return out;
+}
+function prefabRootComponents(world, entity) {
+  const state = perWorld.get(world)?.states.get(entity);
+  if (!state || state.def !== PrefabInstance) return void 0;
+  return canonicalOf(state.template).get(-1);
+}
+function instanceOf(world, entity) {
+  if (perWorld.get(world)?.states.has(entity)) return entity;
+  const part = world.tryGet(entity, InstancePart);
+  return part?.instance ?? void 0;
+}
+let scratch;
+function canonicalOf(template) {
+  if (template.canonical) return template.canonical;
+  const out = /* @__PURE__ */ new Map();
+  const nodes = template.flat.nodes;
+  const pathOf = (target) => target === -1 ? "." : nodes[target].path;
+  const add = (i, t) => out.set(i, canonicalComponents(t, pathOf));
+  if (template.root) add(-1, template.root);
+  else out.set(-1, /* @__PURE__ */ new Map());
+  for (let i = 0; i < template.entities.length; i++) {
+    const t = template.entities[i];
+    if (t) add(i, t);
+  }
+  template.canonical = out;
+  return out;
+}
+function canonicalComponents(t, pathOf) {
+  scratch ??= new World();
+  const e = scratch.spawn(
+    ...t.defs.map((d, k) => [d, t.values[k]])
+  );
+  const json = serializeComponents(scratch, e);
+  scratch.despawn(e);
+  for (const r of t.refs) {
+    const comp = json.get(t.defs[r.component].name);
+    if (comp) comp[r.field] = pathOf(r.target);
+  }
+  return json;
+}
+function liveComponents(world, entity, pathOf) {
+  const json = serializeComponents(world, entity);
+  for (const [name, value] of json) {
+    const def = componentDef(name);
+    for (const { name: field, field: type } of def.layout) {
+      const v = value[field];
+      if (type.kind === "entity" && typeof v === "number" && pathOf.has(v))
+        value[field] = pathOf.get(v);
+    }
+  }
+  return json;
+}
+function diffFields(name, authored, now, loaded, base) {
+  const out = {};
+  const aliases = ALIASES[name] ?? {};
+  const covered = /* @__PURE__ */ new Set();
+  for (const [key, value] of Object.entries(authored)) {
+    const field = aliases[key]?.field ?? key;
+    covered.add(field);
+    if (loaded && equal(now[field], loaded[field])) out[key] = value;
+    else if (base && equal(now[field], base[field])) continue;
+    else if (field in now) out[field] = now[field];
+  }
+  const reference = base ?? loaded;
+  for (const field of Object.keys(now)) {
+    if (covered.has(field)) continue;
+    if (!reference || !equal(now[field], reference[field])) out[field] = now[field];
+  }
+  return out;
+}
+function currentOverrides(world, entity) {
+  const state = perWorld.get(world)?.states.get(entity);
+  if (!state) return void 0;
+  const { template, plan, ids } = state;
+  const nodes = plan.flat.nodes;
+  const base = canonicalOf(template);
+  const pathOf = /* @__PURE__ */ new Map([[entity, "."]]);
+  for (let i = 0; i < ids.length; i++) if (ids[i] >= 0) pathOf.set(ids[i], nodes[i].path);
+  const alive = (i) => ids[i] >= 0 && world.isAlive(ids[i]);
+  const loadedCache = /* @__PURE__ */ new Map();
+  const loadedOf = (i) => {
+    if (!plan.flat.touched.has(i)) return base.get(i);
+    let m = loadedCache.get(i);
+    if (!m && plan.entities[i]) {
+      m = canonicalComponents(plan.entities[i], (t) => t === -1 ? "." : nodes[t].path);
+      loadedCache.set(i, m);
+    }
+    return m;
+  };
+  const live = /* @__PURE__ */ new Map();
+  const liveOf = (i) => {
+    let m = live.get(i);
+    if (!m) {
+      m = liveComponents(world, ids[i], pathOf);
+      live.set(i, m);
+    }
+    return m;
+  };
+  const out = {};
+  const handled = /* @__PURE__ */ new Set();
+  const gone = /* @__PURE__ */ new Set();
+  for (const [key, value] of Object.entries(state.overrides)) {
+    const i = plan.flat.index.get(key);
+    if (value === null) {
+      if (i !== void 0) {
+        if (!alive(i)) {
+          out[key] = null;
+          gone.add(i);
+        }
+        continue;
+      }
+      const cut = splitComponentKey(plan.flat, key);
+      if (!cut)
+        out[key] = null;
+      else if (alive(cut.i) && !liveOf(cut.i).has(cut.component)) {
+        out[key] = null;
+        handled.add(`${cut.i}|${cut.component}`);
+      }
+      continue;
+    }
+    if (i === void 0 || !isPlainObject(value)) {
+      out[key] = value;
+      continue;
+    }
+    if (!alive(i)) continue;
+    const entry = {};
+    for (const [name, patch] of Object.entries(value)) {
+      const now = liveOf(i).get(name);
+      if (patch === null) {
+        if (!now) {
+          entry[name] = null;
+          handled.add(`${i}|${name}`);
+        }
+        continue;
+      }
+      if (!now || !isPlainObject(patch)) continue;
+      handled.add(`${i}|${name}`);
+      const b = base.get(i)?.get(name);
+      const fields = diffFields(name, patch, now, loadedOf(i)?.get(name), b);
+      if (Object.keys(fields).length > 0 || !b) entry[name] = fields;
+    }
+    if (Object.keys(entry).length > 0) out[key] = entry;
+  }
+  for (let i = 0; i < nodes.length; i++) {
+    if (!template.entities[i]) continue;
+    const path = nodes[i].path;
+    const parent = nodes[i].parent;
+    if (!alive(i)) {
+      const parentGone = parent !== -1 && (!alive(parent) || gone.has(parent));
+      if (!parentGone && !gone.has(i)) out[path] = null;
+      gone.add(i);
+      continue;
+    }
+    const b = base.get(i) ?? /* @__PURE__ */ new Map();
+    const now = liveOf(i);
+    const existing = out[path];
+    const entry = isPlainObject(existing) ? existing : {};
+    const loaded = loadedOf(i);
+    for (const name of b.keys()) {
+      if (handled.has(`${i}|${name}`) || now.has(name) || !loaded?.has(name)) continue;
+      out[`${path}/${name}`] = null;
+    }
+    for (const [name, value] of now) {
+      if (handled.has(`${i}|${name}`)) continue;
+      const before = b.get(name);
+      if (!before) {
+        const spawned = loaded?.get(name);
+        if (!spawned || !equal(spawned, value)) entry[name] = value;
+        continue;
+      }
+      const fields = {};
+      for (const field of Object.keys(value))
+        if (!equal(value[field], before[field])) fields[field] = value[field];
+      if (Object.keys(fields).length > 0) entry[name] = fields;
+    }
+    if (Object.keys(entry).length > 0) out[path] = entry;
+  }
+  return out;
+}
+function mergeOverridesIntoPrefab(file, overrides, onUnknown) {
+  const out = structuredClone(file);
+  if (out.extends !== void 0 || !out.root) {
+    const merged = { ...out.overrides ?? {} };
+    for (const [key, value] of Object.entries(overrides)) {
+      const prev = merged[key];
+      merged[key] = isPlainObject(prev) && isPlainObject(value) ? mergePatch(prev, value) : value;
+    }
+    out.overrides = merged;
+    return out;
+  }
+  const root = out.root;
+  const find = (path) => {
+    const parts = path.split("/");
+    let list = root.children ?? [];
+    let parent = root;
+    for (let k = 0; k < parts.length; k++) {
+      const e = list.find((c) => c.name === parts[k]);
+      if (!e) {
+        if (k > 0 && instanceDefOf(expandComponents(parent.components)))
+          return { entity: parent, rest: parts.slice(k).join("/") };
+        return void 0;
+      }
+      if (k === parts.length - 1) return { entity: e, rest: "", parent };
+      parent = e;
+      list = e.children ?? [];
+    }
+    return void 0;
+  };
+  const nestedOverrides = (entity) => {
+    entity.components ??= {};
+    const comps = entity.components;
+    const def = instanceDefOf(comps);
+    const inst = comps[def.name];
+    if (!isPlainObject(inst.overrides)) inst.overrides = {};
+    return inst.overrides;
+  };
+  const setNested = (host, key, value) => {
+    const target = nestedOverrides(host);
+    const prev = target[key];
+    target[key] = isPlainObject(prev) && isPlainObject(value) ? mergePatch(prev, value) : value;
+  };
+  for (const [key, value] of Object.entries(overrides)) {
+    const parts = key.split("/");
+    const component = parts.slice(-2).join("/");
+    const owner = value === null && parts.length >= 3 && componentDef(component) && !find(key) ? find(parts.slice(0, -2).join("/")) : void 0;
+    if (owner) {
+      if (owner.rest === "") delete owner.entity.components?.[component];
+      else setNested(owner.entity, `${owner.rest}/${component}`, null);
+      continue;
+    }
+    const hit = find(key);
+    if (!hit) {
+      onUnknown?.(key);
+      continue;
+    }
+    if (hit.rest !== "") {
+      setNested(hit.entity, hit.rest, value);
+      continue;
+    }
+    if (value === null) {
+      const siblings = hit.parent?.children;
+      if (siblings) siblings.splice(siblings.indexOf(hit.entity), 1);
+      continue;
+    }
+    hit.entity.components ??= {};
+    const comps = hit.entity.components;
+    for (const [name, patch] of Object.entries(value)) {
+      if (patch === null) delete comps[name];
+      else comps[name] = { ...stripAliases(name, comps[name] ?? {}, patch), ...patch };
+    }
+  }
+  return out;
+}
+function stripAliases(name, authored, patch) {
+  const aliases = ALIASES[name];
+  if (!aliases) return authored;
+  const out = { ...authored };
+  for (const [alias, { field }] of Object.entries(aliases)) {
+    if (field in patch) delete out[alias];
+    if (alias in patch) delete out[field];
+  }
+  return out;
+}
+function mergePatch(a, b) {
+  const out = { ...a };
+  for (const [name, patch] of Object.entries(b)) {
+    const prev = out[name];
+    out[name] = patch && prev ? { ...prev, ...patch } : patch;
+  }
+  return out;
+}
+function prefabOfInstance(world, entity) {
+  const state = perWorld.get(world)?.states.get(entity);
+  return state?.def === PrefabInstance ? state.template.entry : void 0;
+}
+function validateInstance(world, def, json, base, f, errors, options) {
+  const overrides = json.overrides;
+  const at = `${base}/overrides`;
+  if (overrides === void 0 || overrides === null) return;
+  if (!isPlainObject(overrides)) {
+    errors.push(
+      new ShardError("schema/type-mismatch", '"overrides" must be an object', {
+        path: at,
+        hint: 'Map paths to component patches: { "Exhaust": { "particles/ParticleSystem": { "timeScale": 2 } } }.'
+      })
+    );
+    return;
+  }
+  if (!options.catalog) return;
+  const ref = handleOf(json, def === PrefabInstance ? "prefab" : "scene");
+  const entry = ref && assetServer(world).entry(ref);
+  if (entry?.state !== "loaded") return;
+  let flat;
+  try {
+    flat = fork(flattenSource(world, entry, []));
+  } catch (err) {
+    if (err instanceof ShardError)
+      errors.push(new ShardError(err.code, err.message, { path: base, hint: err.hint }));
+    return;
+  }
+  const check = checkContext(world, flat, entry.path);
+  applyOverrides(
+    flat,
+    overrides,
+    "",
+    (_, e) => errors.push(rebase(e, at)),
+    (d, j) => d.validate(j, check)
+  );
+  for (const [k, child] of (f.entity.children ?? []).entries()) {
+    if (typeof child?.name === "string" && flat.index.has(child.name)) {
+      errors.push(
+        new ShardError(
+          "prefab/duplicate-name",
+          `"${child.name}" is also the name of an entity the instance generates`,
+          {
+            path: `${f.pointer}/children/${k}/name`,
+            hint: 'Rename the child, or change the generated one with "overrides" instead.'
+          }
+        )
+      );
+    }
+  }
+}
+async function loadInstanceAssets(world, json) {
+  const server = assetServer(world);
+  const refs = /* @__PURE__ */ new Set();
+  const walk = (entities) => {
+    if (!Array.isArray(entities)) return;
+    for (const e of entities) {
+      if (!isPlainObject(e)) continue;
+      const comps = e.components;
+      if (isPlainObject(comps)) {
+        for (const [name, field] of [
+          [PrefabInstance.name, "prefab"],
+          [SceneInstance.name, "scene"]
+        ]) {
+          const ref = handleOf(comps[name], field);
+          const entry = ref && server.entry(ref);
+          if (entry) refs.add(entry.guid);
+        }
+      }
+      walk(e.children);
+    }
+  };
+  if (isPlainObject(json)) {
+    walk(json.entities);
+    if (isPlainObject(json.root)) walk([json.root]);
+  }
+  await server.whenSettled(refs);
+}
+export {
+  ScenePlugin,
+  currentOverrides,
+  defineInstanceKind,
+  hookInstances,
+  instanceEntities,
+  instanceKindOf,
+  instanceKinds,
+  instanceOf,
+  loadInstanceAssets,
+  loadPrefab,
+  mergeOverridesIntoPrefab,
+  prefabInstanceKind,
+  prefabOfInstance,
+  prefabRootComponents,
+  releaseSceneHooks,
+  sceneInstanceKind,
+  sceneInstancesSystem,
+  settleInstances,
+  spawnPrefab,
+  updateInstances,
+  validateInstance
+};