@forgeax/engine-scene 0.1.27 → 0.1.29

package/dist/index.mjs

@@ -3,13 +3,81 @@ import {
   err,
   ok
 } from "@forgeax/engine-types";
+
+// src/instances/legacy.ts
+function migrateLegacySceneComponentFields(componentName, source, addressByLocalId) {
+  const fields = { ...source };
+  const address = (value) => Number.isSafeInteger(value) ? addressByLocalId?.get(value) ?? String(value) : value;
+  if (componentName === "DirectionalLight" && Object.hasOwn(fields, "pcfKernelSize")) {
+    const kernel = fields.pcfKernelSize;
+    const shadowFilter = kernel === 1 ? 1 : kernel === 3 ? 2 : kernel === 5 ? 3 : void 0;
+    if (shadowFilter !== void 0 && !Object.hasOwn(fields, "shadowFilter")) {
+      delete fields.pcfKernelSize;
+      fields.shadowFilter = shadowFilter;
+    }
+  }
+  if (componentName === "ChildOf" && Number.isSafeInteger(fields.parent)) {
+    fields.parent = address(fields.parent);
+  }
+  if (componentName === "Children" && Array.isArray(fields.entities)) {
+    fields.entities = fields.entities.map(address);
+  }
+  return fields;
+}
+function normalizeLegacySceneAsset(scene) {
+  if (scene === null || typeof scene !== "object") return scene;
+  const candidate = scene;
+  if (!Array.isArray(candidate.entities))
+    return scene;
+  const rows = candidate.entities;
+  const addressByLocalId = /* @__PURE__ */ new Map();
+  const rowKeys = [];
+  const used = /* @__PURE__ */ new Set();
+  for (const [index, row] of rows.entries()) {
+    const localId = Number.isSafeInteger(row?.localId) ? row.localId : index;
+    const bindingKey = typeof row?.bindingKey === "string" && row.bindingKey.length > 0 ? row.bindingKey : String(localId);
+    const key = used.has(bindingKey) ? String(localId) : bindingKey;
+    used.add(key);
+    addressByLocalId.set(localId, key);
+    rowKeys.push(key);
+  }
+  const entities = {};
+  for (const [index, row] of rows.entries()) {
+    const key = rowKeys[index];
+    const rawComponents = row?.components;
+    const components = {};
+    if (rawComponents !== null && typeof rawComponents === "object" && !Array.isArray(rawComponents)) {
+      for (const [componentName, rawFields] of Object.entries(
+        rawComponents
+      )) {
+        if (rawFields === null || typeof rawFields !== "object" || Array.isArray(rawFields))
+          continue;
+        components[componentName] = migrateLegacySceneComponentFields(
+          componentName,
+          rawFields,
+          addressByLocalId
+        );
+      }
+    }
+    entities[key] = {
+      components,
+      ...row?.instance === void 0 ? {} : { instance: row.instance }
+    };
+  }
+  return {
+    ...scene,
+    entities
+  };
+}
+
+// src/assets/scene-decoder.ts
 var sceneAssetKind = {
   kind: "scene"
 };
 function invalidScene(guid, reason) {
   return err({
     code: "asset-package-invalid",
-    expected: "a scene payload with an entities array",
+    expected: "a scene payload with keyed entities",
     hint: "recook the SceneAsset and publish its complete envelope",
     detail: { guid, reason }
   });
@@ -25,19 +93,12 @@ function resolveWireRef(refs, value, location) {
   }
   return { ok: true, value: guid };
 }
-function resolveMounts(mounts, refs) {
-  if (mounts === void 0) return { ok: true, value: void 0 };
-  const resolved = [];
-  for (const mount of mounts) {
-    if (typeof mount.source !== "number" || !Number.isInteger(mount.source)) {
-      resolved.push(mount);
-      continue;
-    }
-    const ref = resolveWireRef(refs, mount.source, `mount ${mount.localId} source`);
-    if (!ref.ok) return ref;
-    resolved.push({ ...mount, source: ref.value });
+function resolveInstanceSource(source, refs, location) {
+  if (typeof source === "string" && source.length > 0) return { ok: true, value: source };
+  if (typeof source !== "number" || !Number.isInteger(source)) {
+    return { ok: false, reason: `${location} must be a GUID or refs index` };
   }
-  return { ok: true, value: resolved };
+  return resolveWireRef(refs, source, location);
 }
 function resolveSkinGuids(skinGuids, refs) {
   if (skinGuids === void 0) return { ok: true, value: void 0 };
@@ -58,22 +119,88 @@ function resolveSkinGuids(skinGuids, refs) {
   return { ok: true, value: resolved };
 }
 function resolveSceneWireRefs(payload, refs) {
-  const entities = [];
-  for (const entity of payload.entities) {
+  const normalized = normalizeLegacySceneAsset({ kind: "scene", entities: payload.entities });
+  const rawEntities = normalized.entities;
+  if (rawEntities === null || typeof rawEntities !== "object" || Array.isArray(rawEntities)) {
+    return { ok: false, reason: "entities must be a keyed object" };
+  }
+  const entities = {};
+  for (const [key, rawEntity] of Object.entries(rawEntities)) {
+    const entity = rawEntity;
+    if (key.length === 0 || entity === void 0 || typeof entity !== "object") {
+      return { ok: false, reason: `entities[${JSON.stringify(key)}] is malformed` };
+    }
+    if (entity.components === null || typeof entity.components !== "object" || Array.isArray(entity.components)) {
+      return { ok: false, reason: `entities.${key}.components must be an object` };
+    }
     const components = {};
-    for (const [componentName, rawFields] of Object.entries(entity.components)) {
+    for (const [componentName, rawFields] of Object.entries(
+      entity.components
+    )) {
+      if (rawFields === null || typeof rawFields !== "object" || Array.isArray(rawFields)) {
+        return {
+          ok: false,
+          reason: `entities.${key}.components.${componentName} must be an object`
+        };
+      }
       components[componentName] = { ...rawFields };
     }
-    entities.push({
-      localId: entity.localId,
-      ...entity.bindingKey === void 0 ? {} : { bindingKey: entity.bindingKey },
-      components
-    });
+    const instance = entity.instance;
+    let resolvedInstance;
+    if (instance !== void 0) {
+      if (instance === null || typeof instance !== "object") {
+        return { ok: false, reason: `entities.${key}.instance must be an object` };
+      }
+      const source = resolveInstanceSource(
+        instance.source,
+        refs,
+        `entities.${key}.instance.source`
+      );
+      if (!source.ok) return source;
+      if (instance.overrides !== void 0 && !Array.isArray(instance.overrides)) {
+        return { ok: false, reason: `entities.${key}.instance.overrides must be an array` };
+      }
+      let overrides;
+      if (instance.overrides === void 0) {
+        overrides = void 0;
+      } else {
+        const resolvedOverrides = [];
+        for (const [index, rawOverride] of instance.overrides.entries()) {
+          if (rawOverride === null || typeof rawOverride !== "object" || Array.isArray(rawOverride) || !Array.isArray(rawOverride.target) || rawOverride.target?.some(
+            (part) => typeof part !== "string" || part.length === 0
+          )) {
+            return {
+              ok: false,
+              reason: `entities.${key}.instance.overrides[${index}] is malformed`
+            };
+          }
+          const target = rawOverride.target;
+          const rawComponents = rawOverride.components;
+          if (rawComponents === null || typeof rawComponents !== "object" || Array.isArray(rawComponents)) {
+            return {
+              ok: false,
+              reason: `entities.${key}.instance.overrides[${index}].components is malformed`
+            };
+          }
+          resolvedOverrides.push({
+            target: [...target],
+            components: rawComponents
+          });
+        }
+        overrides = resolvedOverrides;
+      }
+      resolvedInstance = {
+        source: source.value,
+        ...overrides === void 0 ? {} : { overrides }
+      };
+    }
+    entities[key] = {
+      components,
+      ...resolvedInstance === void 0 ? {} : { instance: resolvedInstance }
+    };
   }
-  const mounts = resolveMounts(payload.mounts, refs);
-  if (!mounts.ok) return mounts;
   const skinGuids = resolveSkinGuids(
-    payload.skinGuids,
+    Array.isArray(payload.skinGuids) ? payload.skinGuids : payload.skinGuids === void 0 ? void 0 : [],
     refs
   );
   if (!skinGuids.ok) return skinGuids;
@@ -81,9 +208,7 @@ function resolveSceneWireRefs(payload, refs) {
     ok: true,
     value: {
       kind: "scene",
-      ...payload.sourceKey === void 0 ? {} : { sourceKey: payload.sourceKey },
       entities,
-      ...mounts.value === void 0 ? {} : { mounts: mounts.value },
       ...skinGuids.value === void 0 ? {} : { skinGuids: skinGuids.value }
     }
   };
@@ -91,8 +216,8 @@ function resolveSceneWireRefs(payload, refs) {
 var sceneAssetDecoder = {
   async decode({ envelope }) {
     const payload = envelope.payload;
-    if (payload.kind !== "scene" || !Array.isArray(payload.entities)) {
-      return invalidScene(envelope.guid, "scene payload is missing entities");
+    if (payload.kind !== "scene" || payload.entities === null || typeof payload.entities !== "object") {
+      return invalidScene(envelope.guid, "scene payload is missing keyed entities");
     }
     const resolved = resolveSceneWireRefs(payload, envelope.refs);
     if (!resolved.ok) return invalidScene(envelope.guid, resolved.reason);
@@ -151,8 +276,8 @@ function collectSubtree(world, spawnRoot, visited) {
   if (visited.has(spawnRoot)) return visited;
   const queue = [spawnRoot];
   visited.add(spawnRoot);
-  while (queue.length > 0) {
-    const current = queue.shift();
+  for (let cursor = 0; cursor < queue.length; cursor += 1) {
+    const current = queue[cursor];
     const children = world.get(current, Children);
     if (!children.ok) continue;
     const entities = children.value.entities;
@@ -195,7 +320,7 @@ var SceneError = class extends Error {
 
 // src/instances/binding.ts
 import { err as err2, ok as ok2 } from "@forgeax/engine-types";
-function validateSceneBindings(sceneSourceKey, bindingKeys) {
+function validateSceneEntityKeys(sceneSourceKey, entityKeys) {
   if (sceneSourceKey.length === 0) {
     return err2({
       code: "scene-binding-source-missing",
@@ -205,21 +330,26 @@ function validateSceneBindings(sceneSourceKey, bindingKeys) {
     });
   }
   const seen = /* @__PURE__ */ new Set();
-  for (const bindingKey of bindingKeys) {
-    if (bindingKey.length === 0 || seen.has(bindingKey)) {
+  for (const entityKey of entityKeys) {
+    if (entityKey.length === 0 || seen.has(entityKey)) {
       return err2({
         code: "scene-binding-duplicate",
-        expected: "unique non-empty bindingKey values within one scene",
-        hint: "rename the duplicate bindingKey in the scene producer",
-        detail: { sceneSourceKey, bindingKey }
+        expected: "unique non-empty entity keys within one scene",
+        hint: "rename the duplicate entity key in the scene producer",
+        detail: { sceneSourceKey, address: entityKey }
       });
     }
-    seen.add(bindingKey);
+    seen.add(entityKey);
   }
-  return ok2([...bindingKeys]);
+  return ok2([...entityKeys]);
 }
-function sceneEntity(sceneSourceKey, bindingKey) {
-  return { sceneSourceKey, bindingKey };
+function sceneEntity(sceneSourceKey, address) {
+  return { sceneSourceKey, address };
+}
+function sceneEntityAddressKey(address) {
+  if (typeof address === "string") return `s:${JSON.stringify(address)}`;
+  if (address.length === 1) return `s:${JSON.stringify(address[0] ?? "")}`;
+  return `a:${JSON.stringify(address)}`;
 }
 function resolveSceneEntity(ref, instance) {
   if (ref.sceneSourceKey !== instance.sceneSourceKey) {
@@ -227,16 +357,16 @@ function resolveSceneEntity(ref, instance) {
       code: "scene-binding-wrong-instance",
       expected: `scene instance ${ref.sceneSourceKey}`,
       hint: "resolve the SceneEntityRef against its owning SceneInstance",
-      detail: { sceneSourceKey: ref.sceneSourceKey, bindingKey: ref.bindingKey }
+      detail: { sceneSourceKey: ref.sceneSourceKey, address: ref.address }
     });
   }
-  const value = instance.bindings.get(ref.bindingKey);
+  const value = instance.bindings.get(sceneEntityAddressKey(ref.address));
   if (value === void 0) {
     return err2({
       code: "scene-binding-missing",
-      expected: "bindingKey declared by the scene producer",
-      hint: "declare the bindingKey in the scene producer before consuming it",
-      detail: { sceneSourceKey: ref.sceneSourceKey, bindingKey: ref.bindingKey }
+      expected: "entity key declared by the scene producer",
+      hint: "declare the entity key in the scene producer before consuming it",
+      detail: { sceneSourceKey: ref.sceneSourceKey, address: ref.address }
     });
   }
   return ok2(value);
@@ -255,108 +385,488 @@ function sharedKind(type) {
   if (type?.startsWith("array<shared<")) return "many";
   return void 0;
 }
-function overrideGuids(override, resolveSchema) {
-  const schema = resolveSchema(override.comp);
-  const values = override.field !== void 0 ? [[override.field, override.value]] : override.value !== null && typeof override.value === "object" && !Array.isArray(override.value) ? Object.entries(override.value) : [];
-  return values.flatMap(([field, value]) => {
-    const kind = sharedKind(schema?.[field]);
-    if (kind === "one" && typeof value === "string") return [{ field, guid: value }];
-    if (kind === "many" && Array.isArray(value)) {
-      return value.flatMap((item) => typeof item === "string" ? [{ field, guid: item }] : []);
-    }
-    return [];
+function addRef(context, guid, sourceField, sceneEntityKey) {
+  const prior = context.indexByGuid.get(guid);
+  if (prior !== void 0) return prior;
+  const index = context.refs.length;
+  context.refs.push({
+    guid,
+    sourceField,
+    ...sceneEntityKey === void 0 ? {} : { sceneEntityKey }
   });
+  context.indexByGuid.set(guid, index);
+  return index;
+}
+function externalizeFields(componentName, source, resolveSchema, context, sceneEntityKey) {
+  const schema = resolveSchema(componentName);
+  const fields = {};
+  for (const [fieldName, value] of Object.entries(
+    migrateLegacySceneComponentFields(componentName, source)
+  )) {
+    if (value === void 0) continue;
+    const kind = sharedKind(schema?.[fieldName]);
+    if (kind === "one" && typeof value === "string") {
+      fields[fieldName] = addRef(context, value, { componentName, fieldName }, sceneEntityKey);
+    } else if (kind === "many" && Array.isArray(value)) {
+      fields[fieldName] = value.map(
+        (item, arrayIndex) => typeof item === "string" ? addRef(context, item, { componentName, fieldName, arrayIndex }, sceneEntityKey) : item
+      );
+    } else {
+      fields[fieldName] = value;
+    }
+  }
+  return fields;
 }
-function externalizeSceneAsset(scene, resolveSchema) {
-  const refs = [];
-  const indexByGuid = /* @__PURE__ */ new Map();
-  const addRef = (guid, sourceField, sceneEntityId) => {
-    const prior = indexByGuid.get(guid);
-    if (prior !== void 0) return prior;
-    const index = refs.length;
-    refs.push({ guid, sourceField, ...sceneEntityId === void 0 ? {} : { sceneEntityId } });
-    indexByGuid.set(guid, index);
-    return index;
+function externalizeOverride(override, resolveSchema, context, sceneEntityKey) {
+  const components = {};
+  for (const [componentName, rawFields] of Object.entries(override.components)) {
+    components[componentName] = externalizeFields(
+      componentName,
+      { ...rawFields },
+      resolveSchema,
+      context,
+      sceneEntityKey
+    );
+  }
+  return {
+    target: [...override.target],
+    components
   };
-  const entities = scene.entities.map((entity) => {
+}
+function externalizeSceneAsset(scene, resolveSchema) {
+  const normalized = normalizeLegacySceneAsset(scene);
+  const context = { refs: [], indexByGuid: /* @__PURE__ */ new Map() };
+  const entities = {};
+  for (const [key, entity] of Object.entries(normalized.entities)) {
     const components = {};
-    for (const componentName of Object.keys(entity.components)) {
-      const schema = resolveSchema(componentName);
-      const source = entity.components[componentName];
+    for (const [componentName, raw] of Object.entries(entity.components)) {
+      const source = raw;
       if (source === void 0) continue;
-      const fields = {};
-      for (const fieldName of Object.keys(source)) {
-        const value = source[fieldName];
-        if (value === void 0) continue;
-        const kind = sharedKind(schema?.[fieldName]);
-        if (kind === "one" && typeof value === "string") {
-          fields[fieldName] = addRef(value, { componentName, fieldName }, entity.localId);
-        } else if (kind === "many" && Array.isArray(value)) {
-          fields[fieldName] = value.map(
-            (item, arrayIndex) => typeof item === "string" ? addRef(item, { componentName, fieldName, arrayIndex }, entity.localId) : item
-          );
-        } else {
-          fields[fieldName] = value;
+      components[componentName] = externalizeFields(
+        componentName,
+        source,
+        resolveSchema,
+        context,
+        key
+      );
+    }
+    const instance = entity.instance;
+    entities[key] = {
+      components,
+      ...instance === void 0 ? {} : {
+        instance: {
+          source: addRef(
+            context,
+            instance.source,
+            { componentName: "SceneInstance", fieldName: "source" },
+            key
+          ),
+          ...instance.overrides === void 0 ? {} : {
+            overrides: instance.overrides.map(
+              (override) => externalizeOverride(override, resolveSchema, context, key)
+            )
+          }
         }
       }
-      if (Object.keys(fields).length > 0 || Object.keys(schema ?? {}).length === 0) {
-        components[componentName] = fields;
-      }
-    }
-    return {
-      localId: entity.localId,
-      ...entity.bindingKey === void 0 ? {} : { bindingKey: entity.bindingKey },
-      components
     };
-  });
-  const mounts = scene.mounts?.map((mount) => {
-    const source = typeof mount.source === "string" ? addRef(
-      mount.source,
-      { componentName: "SceneInstance", fieldName: "source" },
-      mount.localId
-    ) : mount.source;
-    for (const { field, guid } of (mount.overrides ?? []).flatMap(
-      (override) => overrideGuids(override, resolveSchema)
-    )) {
-      addRef(guid, { componentName: "SceneInstance", fieldName: `overrides.${field}` });
-    }
-    return {
-      localId: mount.localId,
-      source,
-      memberFirst: mount.memberFirst,
-      memberCount: mount.memberCount,
-      ...mount.parent === void 0 ? {} : { parent: mount.parent },
-      ...mount.publicationFence === void 0 ? {} : { publicationFence: mount.publicationFence },
-      ...mount.overrides === void 0 ? {} : { overrides: mount.overrides.map((item) => ({ ...item })) }
-    };
-  });
-  for (const [arrayIndex, guid] of (scene.skinGuids ?? []).entries()) {
+  }
+  for (const [arrayIndex, guid] of (normalized.skinGuids ?? []).entries()) {
     if (typeof guid !== "string") return err3({ field: "skinGuids", value: guid });
-    addRef(guid, { componentName: "<scene>", fieldName: "skinGuids", arrayIndex });
+    addRef(context, guid, { componentName: "<scene>", fieldName: "skinGuids", arrayIndex });
   }
   return ok3({
     payload: {
       kind: "scene",
-      ...scene.sourceKey === void 0 ? {} : { sourceKey: scene.sourceKey },
       entities,
-      ...mounts === void 0 || mounts.length === 0 ? {} : { mounts },
-      ...scene.skinGuids === void 0 ? {} : { skinGuids: scene.skinGuids.map((guid) => indexByGuid.get(guid)) }
+      ...normalized.skinGuids === void 0 ? {} : {
+        skinGuids: normalized.skinGuids.map((guid) => context.indexByGuid.get(guid))
+      }
     },
-    refs
+    refs: context.refs
+  });
+}
+
+// src/instances/keyed.ts
+import { classifyEntityField, remapEntityFieldValue } from "@forgeax/engine-ecs/externalization";
+import { componentSchema } from "@forgeax/engine-ecs/internal";
+import {
+  err as err4,
+  ok as ok4,
+  PACK_ERROR_HINTS
+} from "@forgeax/engine-types";
+function fail(reason, detail = {}) {
+  return err4({
+    code: "asset-package-invalid",
+    expected: "a keyed SceneAsset with valid entity and instance addresses",
+    hint: "repair the SceneAsset source and recook the asset",
+    detail: { reason, ...detail }
+  });
+}
+function keyList(entities) {
+  return Object.keys(entities).sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+}
+function addressParts(value) {
+  if (typeof value === "string" && value.length > 0) return [value];
+  if (Number.isSafeInteger(value)) return [String(value)];
+  if (!Array.isArray(value) || value.length === 0) return void 0;
+  if (!value.every((part) => typeof part === "string" && part.length > 0)) return void 0;
+  return value;
+}
+function fieldRemap(world, componentName, fields, resolveAddress, entityKey) {
+  const token = world.components.resolve(componentName);
+  if (token === void 0) return fail("unknown component", { component: componentName });
+  const schema = componentSchema(token);
+  const out = {};
+  for (const [fieldName, value] of Object.entries(
+    migrateLegacySceneComponentFields(componentName, fields)
+  )) {
+    const fieldType = schema[fieldName];
+    if (fieldType === void 0) {
+      return fail("unknown component field", {
+        component: componentName,
+        field: fieldName,
+        ...entityKey === void 0 ? {} : { entity: entityKey }
+      });
+    }
+    const kind = classifyEntityField(token, fieldName);
+    if (kind === null) {
+      out[fieldName] = value;
+      continue;
+    }
+    const remap = (address) => resolveAddress(address, `${componentName}.${fieldName}`) ?? address;
+    if (kind.isArray) {
+      if (!Array.isArray(value))
+        return fail("array entity field is not an array", {
+          component: componentName,
+          field: fieldName
+        });
+      const numeric = [];
+      for (const item of value) {
+        const parts2 = addressParts(item);
+        if (parts2 === void 0)
+          return fail("invalid entity address", {
+            component: componentName,
+            field: fieldName,
+            address: item
+          });
+        const slot2 = resolveAddress(parts2, `${componentName}.${fieldName}`);
+        if (slot2 === void 0)
+          return fail("missing entity address target", {
+            component: componentName,
+            field: fieldName,
+            address: parts2
+          });
+        numeric.push(slot2);
+      }
+      out[fieldName] = remapEntityFieldValue(numeric, kind, remap);
+      continue;
+    }
+    if (value === null) {
+      out[fieldName] = null;
+      continue;
+    }
+    const parts = addressParts(value);
+    if (parts === void 0)
+      return fail("invalid entity address", {
+        component: componentName,
+        field: fieldName,
+        address: value
+      });
+    const slot = resolveAddress(parts, `${componentName}.${fieldName}`);
+    if (slot === void 0)
+      return fail("missing entity address target", {
+        component: componentName,
+        field: fieldName,
+        address: parts
+      });
+    out[fieldName] = remapEntityFieldValue(slot, kind, remap);
+  }
+  return ok4(out);
+}
+function compileKeyedSceneAsset(world, handle, asset, context) {
+  asset = normalizeLegacySceneAsset(asset);
+  if (asset.kind !== "scene" || asset.entities === null || typeof asset.entities !== "object" || Array.isArray(asset.entities)) {
+    return fail("entities must be a keyed object");
+  }
+  const currentRaw = Number(handle);
+  const activeStack = context.stack.has(currentRaw) ? context.stack : /* @__PURE__ */ new Set([...context.stack, currentRaw]);
+  const keys = keyList(asset.entities);
+  if (keys.some((key) => key.length === 0)) return fail("entity keys must be non-empty");
+  const ownKeys = keys.filter((key) => asset.entities[key]?.instance === void 0);
+  const instanceKeys = keys.filter((key) => asset.entities[key]?.instance !== void 0);
+  const ownSlotByKey = /* @__PURE__ */ new Map();
+  const instanceSlotByKey = /* @__PURE__ */ new Map();
+  const keyByLocalId = /* @__PURE__ */ new Map();
+  for (let index = 0; index < ownKeys.length; index += 1) {
+    const key = ownKeys[index];
+    ownSlotByKey.set(key, index);
+    keyByLocalId.set(index, key);
+  }
+  for (let index = 0; index < instanceKeys.length; index += 1) {
+    const key = instanceKeys[index];
+    const slot = ownKeys.length + index;
+    instanceSlotByKey.set(key, slot);
+    keyByLocalId.set(slot, key);
+  }
+  const childCompiled = /* @__PURE__ */ new Map();
+  for (const key of instanceKeys) {
+    const declaration = asset.entities[key]?.instance;
+    if (declaration === void 0 || typeof declaration.source !== "string" || declaration.source.length === 0) {
+      return fail("instance source must be a non-empty GUID", { entity: key });
+    }
+    const childHandle = context.resolveSource(declaration.source, handle);
+    if (!childHandle.ok) return childHandle;
+    const childRaw = Number(childHandle.value);
+    if (activeStack.has(childRaw)) {
+      return err4({
+        code: "pack-cyclic-reference",
+        expected: "acyclic SceneAsset instance graph",
+        hint: PACK_ERROR_HINTS["pack-cyclic-reference"],
+        detail: {
+          code: "pack-cyclic-reference",
+          kind: "mount-asset",
+          cycle: [...activeStack, childRaw].map(String)
+        }
+      });
+    }
+    const childAsset = context.resolveAsset(childHandle.value);
+    if (!childAsset.ok) return childAsset;
+    const childContext = {
+      ...context,
+      stack: activeStack
+    };
+    const compiled = compileKeyedSceneAsset(
+      world,
+      childHandle.value,
+      childAsset.value,
+      childContext
+    );
+    if (!compiled.ok) return compiled;
+    childCompiled.set(key, { handle: childHandle.value, compiled: compiled.value });
+  }
+  const mountKeyByLocalId = /* @__PURE__ */ new Map();
+  const mounts = [];
+  let nextMemberFirst = ownKeys.length + instanceKeys.length;
+  for (let index = 0; index < instanceKeys.length; index += 1) {
+    const key = instanceKeys[index];
+    const slot = instanceSlotByKey.get(key);
+    const child = childCompiled.get(key);
+    const node = asset.entities[key];
+    mountKeyByLocalId.set(slot, key);
+    mounts.push({
+      localId: slot,
+      source: Number(child.handle),
+      memberFirst: nextMemberFirst,
+      memberCount: child.compiled.asset.entities.length + (child.compiled.asset.mounts?.length ?? 0) + (child.compiled.asset.mounts ?? []).reduce((sum, mount) => sum + mount.memberCount, 0),
+      ...Object.keys(node.components).length > 0 ? { components: node.components } : {}
+    });
+    nextMemberFirst += mounts[index]?.memberCount ?? 0;
+  }
+  const mountByKey = /* @__PURE__ */ new Map();
+  for (const mount of mounts)
+    mountByKey.set(mountKeyByLocalId.get(Number(mount.localId)), mount);
+  const resolveInChild = (childResult, value, _field) => {
+    const parts = addressParts(value);
+    if (parts === void 0) return void 0;
+    return childResult.resolveAddress(parts);
+  };
+  const resolveAddress = (value, field) => {
+    const parts = addressParts(value);
+    if (parts === void 0) return void 0;
+    const first = parts[0];
+    if (first === void 0) return void 0;
+    const own = ownSlotByKey.get(first) ?? instanceSlotByKey.get(first);
+    if (own !== void 0 && parts.length === 1) return own;
+    const mount = mountByKey.get(first);
+    if (mount === void 0) return void 0;
+    const child = childCompiled.get(first);
+    if (child === void 0) return void 0;
+    const childSlot = resolveInChild(child.compiled, parts.slice(1), field);
+    return childSlot === void 0 ? void 0 : mount.memberFirst + childSlot;
+  };
+  for (const key of instanceKeys) {
+    const node = asset.entities[key];
+    const mount = mountByKey.get(key);
+    const convertedFields = Object.fromEntries(
+      Object.entries(node.components).map(([componentName, raw]) => [
+        componentName,
+        fieldRemap(
+          world,
+          componentName,
+          { ...raw },
+          resolveAddress,
+          key
+        )
+      ])
+    );
+    const bad = Object.values(convertedFields).find((result) => !result.ok);
+    if (bad !== void 0 && !bad.ok) return bad;
+    const components = {};
+    for (const [componentName, result] of Object.entries(convertedFields)) {
+      if (!result.ok) return result;
+      components[componentName] = result.value;
+    }
+    const index = mounts.findIndex((item) => item.localId === mount.localId);
+    if (index >= 0) {
+      const childOf = components.ChildOf?.parent;
+      if (typeof childOf === "number") {
+        const { ChildOf: _ignored, ...mountComponents } = components;
+        void _ignored;
+        mounts[index] = { ...mount, components: mountComponents, parent: childOf };
+      } else {
+        mounts[index] = { ...mount, components };
+      }
+    }
+  }
+  const converted = [];
+  for (const key of ownKeys) {
+    const node = asset.entities[key];
+    const components = {};
+    for (const [componentName, raw] of Object.entries(node.components)) {
+      const convertedFields = fieldRemap(
+        world,
+        componentName,
+        { ...raw },
+        resolveAddress,
+        key
+      );
+      if (!convertedFields.ok) return convertedFields;
+      components[componentName] = convertedFields.value;
+    }
+    converted.push({ localId: ownSlotByKey.get(key), components });
+  }
+  const childHasComponent = (result, target, componentName) => {
+    const own = result.asset.entities.find((entity) => Number(entity.localId) === target);
+    if (own !== void 0 && own.components[componentName] !== void 0) return true;
+    const mount = result.asset.mounts?.find((entry) => Number(entry.localId) === target);
+    return mount?.components?.[componentName] !== void 0;
+  };
+  for (const key of instanceKeys) {
+    const node = asset.entities[key];
+    const declaration = node.instance;
+    const mount = mountByKey.get(key);
+    const child = childCompiled.get(key);
+    const childSlot = (target) => resolveInChild(child.compiled, target, `${key}.instance`);
+    const overrides = [];
+    for (const override of declaration.overrides ?? []) {
+      const target = childSlot(override.target);
+      if (target === void 0)
+        return fail("instance override target does not exist", {
+          entity: key,
+          target: override.target
+        });
+      for (const [componentName, fields] of Object.entries(override.components)) {
+        const convertedFields = fieldRemap(
+          world,
+          componentName,
+          { ...fields },
+          resolveAddress,
+          `${key}.instance.${override.target.join(".")}`
+        );
+        if (!convertedFields.ok) return convertedFields;
+        if (!childHasComponent(child.compiled, target, componentName)) {
+          overrides.push({
+            localId: mount.memberFirst + target,
+            comp: componentName,
+            value: convertedFields.value
+          });
+        } else {
+          overrides.push(
+            ...Object.entries(convertedFields.value).map(([field, value]) => ({
+              localId: mount.memberFirst + target,
+              comp: componentName,
+              field,
+              value
+            }))
+          );
+        }
+      }
+    }
+    if (overrides.length > 0) {
+      const index = mounts.findIndex((item) => item.localId === mount.localId);
+      const existing = mounts[index];
+      if (index >= 0 && existing !== void 0) mounts[index] = { ...existing, overrides };
+    }
+  }
+  const rootLocalIds = [
+    ...convertedRootLocalIds(converted),
+    ...mounts.filter((mount) => mount.parent === void 0).map((mount) => Number(mount.localId))
+  ];
+  const hierarchyParentByLocalId = /* @__PURE__ */ new Map();
+  for (const node of converted) {
+    const parent = node.components.ChildOf?.parent;
+    if (typeof parent === "number" && parent >= 0) {
+      hierarchyParentByLocalId.set(Number(node.localId), parent);
+    }
+  }
+  for (const mount of mounts) {
+    if (mount.parent !== void 0) {
+      hierarchyParentByLocalId.set(Number(mount.localId), mount.parent);
+    }
+    const key = mountKeyByLocalId.get(Number(mount.localId));
+    const child = key === void 0 ? void 0 : childCompiled.get(key);
+    if (child !== void 0) {
+      for (const [childLocalId, childParent] of child.compiled.hierarchyParentByLocalId) {
+        hierarchyParentByLocalId.set(
+          Number(mount.memberFirst) + childLocalId,
+          Number(mount.memberFirst) + childParent
+        );
+      }
+      for (const childRoot of child.compiled.rootLocalIds) {
+        hierarchyParentByLocalId.set(Number(mount.memberFirst) + childRoot, Number(mount.localId));
+      }
+    }
+    for (const override of mount.overrides ?? []) {
+      if (override.comp !== "ChildOf") continue;
+      if (override.field === "parent" && typeof override.value === "number") {
+        hierarchyParentByLocalId.set(Number(override.localId), override.value);
+      } else if (override.field === void 0 && typeof override.value === "object" && override.value !== null) {
+        const parentValue = override.value.parent;
+        if (typeof parentValue === "number") {
+          hierarchyParentByLocalId.set(Number(override.localId), parentValue);
+        }
+      }
+    }
+  }
+  for (const start of hierarchyParentByLocalId.keys()) {
+    const seen = /* @__PURE__ */ new Set();
+    let current = start;
+    while (current !== void 0 && hierarchyParentByLocalId.has(current)) {
+      if (seen.has(current))
+        return fail("hierarchy cycle", { entity: keyByLocalId.get(start), address: [...seen] });
+      seen.add(current);
+      current = hierarchyParentByLocalId.get(current);
+    }
+  }
+  return ok4({
+    asset: {
+      kind: "scene",
+      entities: converted,
+      ...mounts.length > 0 ? { mounts } : {},
+      ...asset.skinGuids === void 0 ? {} : { skinGuids: asset.skinGuids }
+    },
+    keyByLocalId,
+    mountKeyByLocalId,
+    rootLocalIds,
+    hierarchyParentByLocalId,
+    resolveAddress
   });
 }
+function convertedRootLocalIds(nodes) {
+  return nodes.filter((node) => node.components.ChildOf === void 0).map((node) => Number(node.localId));
+}
 
 // src/instances/scene-instances.ts
 import {
   ENTITY_NULL_RAW
 } from "@forgeax/engine-ecs";
-import { classifyEntityField, remapEntityFieldValue } from "@forgeax/engine-ecs/externalization";
-import { componentSchema } from "@forgeax/engine-ecs/internal";
+import { classifyEntityField as classifyEntityField2, remapEntityFieldValue as remapEntityFieldValue2 } from "@forgeax/engine-ecs/externalization";
+import { componentSchema as componentSchema2 } from "@forgeax/engine-ecs/internal";
 import { fillComponentDefaults, StaleEntityError } from "@forgeax/engine-ecs/projection";
 import {
-  err as err4,
-  ok as ok4,
-  PACK_ERROR_HINTS,
+  err as err5,
+  ok as ok5,
+  PACK_ERROR_HINTS as PACK_ERROR_HINTS2,
   toUnique,
   unwrapHandle
 } from "@forgeax/engine-types";
@@ -388,18 +898,50 @@ function primitiveJsType(fieldType) {
 // src/instances/scene-instances.ts
 var entityIndex = (entity) => entity & 16777215;
 var entityGeneration = (entity) => entity >>> 24 & 255;
+function collectSceneEntityBindings(world, root, prefix, bindings, visited = /* @__PURE__ */ new Set()) {
+  const rootRaw = root;
+  if (visited.has(rootRaw)) return;
+  visited.add(rootRaw);
+  const state = worldResolveSceneInstanceStatePayload(world, root);
+  if (!state.ok) return;
+  const sceneInstance = world.components.resolve("SceneInstance");
+  if (sceneInstance === void 0) return;
+  const component = world.get(root, sceneInstance);
+  if (!component.ok) return;
+  const mapping = component.value.mapping;
+  for (const [slot, key] of state.value.keyByLocalId) {
+    const raw = mapping[slot];
+    if (raw === void 0 || raw === ENTITY_NULL_RAW) continue;
+    const address = prefix.length === 0 ? key : [...prefix, key];
+    bindings.set(sceneEntityAddressKey(address), raw);
+  }
+  for (const childRoot of state.value.mountRoots) {
+    const childState = worldResolveSceneInstanceStatePayload(world, childRoot);
+    const childKey = childState.ok ? childState.value.instanceKey : void 0;
+    if (childKey === void 0) continue;
+    collectSceneEntityBindings(world, childRoot, [...prefix, childKey], bindings, visited);
+  }
+}
 function worldSetSceneAssetResolver(world, resolver) {
   sceneWorldState(world).resolver = resolver;
 }
 function worldGetSceneAssetResolver(world) {
   return sceneWorldState(world).resolver;
 }
-function worldInstantiateScene(world, handle, parent) {
+function worldInstantiateScene(world, handle, parent, sceneSourceKey) {
   const stack = /* @__PURE__ */ new Set();
   const diagnostics = [];
-  const r = worldInstantiateSceneRec(world, handle, parent, stack, diagnostics);
+  const r = worldInstantiateSceneRec(
+    world,
+    handle,
+    parent,
+    stack,
+    diagnostics,
+    void 0,
+    sceneSourceKey
+  );
   if (!r.ok) return r;
-  return ok4({ root: r.value, diagnostics });
+  return ok5({ root: r.value, diagnostics });
 }
 function worldInstantiateScenePayload(world, asset, parent) {
   const handle = world.allocSharedRef("SceneAsset", asset);
@@ -423,9 +965,9 @@ function worldInstantiateSceneFlat(world, handle) {
     stack.delete(handleKey);
   }
   if (!r.ok) return r;
-  return ok4({ ...r.value, diagnostics });
+  return ok5({ ...r.value, diagnostics });
 }
-function worldInstantiateSceneRec(world, handle, parent, stack, diagnostics) {
+function worldInstantiateSceneRec(world, handle, parent, stack, diagnostics, instanceKey, sceneSourceKey) {
   const handleKey = unwrapHandle(handle);
   if (stack.has(handleKey)) {
     const cycleArr = [];
@@ -436,10 +978,10 @@ function worldInstantiateSceneRec(world, handle, parent, stack, diagnostics) {
       kind: "mount-asset",
       cycle: cycleArr
     };
-    return err4({
+    return err5({
       code: "pack-cyclic-reference",
       expected: "acyclic SceneAsset mount graph",
-      hint: PACK_ERROR_HINTS["pack-cyclic-reference"],
+      hint: PACK_ERROR_HINTS2["pack-cyclic-reference"],
       detail
     });
   }
@@ -448,7 +990,16 @@ function worldInstantiateSceneRec(world, handle, parent, stack, diagnostics) {
   const asset = resolved.value;
   stack.add(handleKey);
   try {
-    return worldInstantiateSceneAsset(world, handle, asset, parent, stack, diagnostics);
+    return worldInstantiateSceneAsset(
+      world,
+      handle,
+      asset,
+      parent,
+      stack,
+      diagnostics,
+      instanceKey,
+      sceneSourceKey
+    );
   } finally {
     stack.delete(handleKey);
   }
@@ -456,27 +1007,18 @@ function worldInstantiateSceneRec(world, handle, parent, stack, diagnostics) {
 function worldResolveSceneAsset(world, handle) {
   const r = world.sharedRefs.resolve(handle);
   if (!r.ok) {
-    return err4(r.error);
+    return err5(r.error);
   }
-  return ok4(r.value);
+  return ok5(r.value);
 }
-function worldSpawnSceneMembers(world, handle, asset, stack, diagnostics) {
+function worldSpawnSceneMembers(world, handle, asset, stack, diagnostics, mountKeys) {
   const sceneInstanceToken = world.components.resolve("SceneInstance");
   if (sceneInstanceToken === void 0) {
-    return err4(new ComponentNotDefinedError("SceneInstance"));
+    return err5(new ComponentNotDefinedError("SceneInstance"));
   }
   const childOfToken = world.components.resolve("ChildOf");
   const ownEntities = asset.entities;
   const ownMounts = asset.mounts ?? [];
-  const bindingKeys = ownEntities.flatMap(
-    (entity) => entity.bindingKey === void 0 ? [] : [entity.bindingKey]
-  );
-  if (bindingKeys.length > 0) {
-    const bindingCheck = validateSceneBindings(asset.sourceKey ?? "", bindingKeys);
-    if (!bindingCheck.ok) {
-      return err4(bindingCheck.error);
-    }
-  }
   const memberSum = ownMounts.reduce((s, m) => s + m.memberCount, 0);
   const countBaseline = ownEntities.length + ownMounts.length + memberSum;
   let maxLocalId = ownEntities.reduce((m, e) => Math.max(m, e.localId), -1);
@@ -517,10 +1059,10 @@ function worldSpawnSceneMembers(world, handle, asset, stack, diagnostics) {
     }
     if (overlapLids.size > 0) {
       const overlapping = Array.from(overlapLids).sort((a, b) => a - b);
-      return err4({
+      return err5({
         code: "pack-mount-localid-overlap",
         expected: "each LocalEntityId claimed by exactly one entity or mount slot",
-        hint: PACK_ERROR_HINTS["pack-mount-localid-overlap"],
+        hint: PACK_ERROR_HINTS2["pack-mount-localid-overlap"],
         detail: {
           code: "pack-mount-localid-overlap",
           overlapping,
@@ -550,17 +1092,29 @@ function worldSpawnSceneMembers(world, handle, asset, stack, diagnostics) {
     const childHandleRes = worldResolveMountSource(world, mount.source, handle);
     if (!childHandleRes.ok) return childHandleRes;
     const childHandle = childHandleRes.value;
-    const childRes = worldInstantiateSceneRec(world, childHandle, mountEntity, stack, diagnostics);
+    const childRes = worldInstantiateSceneRec(
+      world,
+      childHandle,
+      mountEntity,
+      stack,
+      diagnostics,
+      mountKeys?.get(mountLid)
+    );
     if (!childRes.ok) return childRes;
     const childInstRes = world.get(childRes.value, sceneInstanceToken);
     if (!childInstRes.ok) return childInstRes;
     const childMapping = childInstRes.value.mapping;
-    mountInstances.push({ mount, root: childRes.value, mapping: childMapping });
+    mountInstances.push({
+      mount,
+      root: childRes.value,
+      mapping: childMapping,
+      ...mountKeys?.get(mountLid) === void 0 ? {} : { key: mountKeys.get(mountLid) }
+    });
     if (childMapping.length !== mount.memberCount) {
-      return err4({
+      return err5({
         code: "pack-mount-count-mismatch",
         expected: "mount.memberCount === child SceneAsset totalSlots",
-        hint: PACK_ERROR_HINTS["pack-mount-count-mismatch"],
+        hint: PACK_ERROR_HINTS2["pack-mount-count-mismatch"],
         detail: {
           code: "pack-mount-count-mismatch",
           mountLocalId: mountLid,
@@ -628,7 +1182,7 @@ function worldSpawnSceneMembers(world, handle, asset, stack, diagnostics) {
       }
     }
   }
-  return ok4({
+  return ok5({
     mapping,
     entityToLocalId,
     rootEntities,
@@ -638,17 +1192,31 @@ function worldSpawnSceneMembers(world, handle, asset, stack, diagnostics) {
     totalSlots
   });
 }
-function worldInstantiateSceneAsset(world, handle, asset, parent, stack, diagnostics) {
+function worldInstantiateSceneAsset(world, handle, asset, parent, stack, diagnostics, instanceKey, sceneSourceKey) {
   const sceneInstanceToken = world.components.resolve("SceneInstance");
   if (sceneInstanceToken === void 0) {
-    return err4(new ComponentNotDefinedError("SceneInstance"));
+    return err5(new ComponentNotDefinedError("SceneInstance"));
   }
   const childOfToken = world.components.resolve("ChildOf");
-  const membersRes = worldSpawnSceneMembers(world, handle, asset, stack, diagnostics);
+  const compiled = compileKeyedSceneAsset(world, handle, asset, {
+    resolveSource: (source, parentHandle) => worldResolveMountSource(world, source, parentHandle),
+    resolveAsset: (childHandle) => worldResolveSceneAsset(world, childHandle),
+    stack
+  });
+  if (!compiled.ok) return err5(compiled.error);
+  const compiledAsset = compiled.value.asset;
+  const membersRes = worldSpawnSceneMembers(
+    world,
+    handle,
+    compiledAsset,
+    stack,
+    diagnostics,
+    compiled.value.mountKeyByLocalId
+  );
   if (!membersRes.ok) return membersRes;
   const { mapping, entityToLocalId, rootEntities, mountEntitiesNeedingRootParent, totalSlots } = membersRes.value;
   const { mountInstances } = membersRes.value;
-  const ownMounts = asset.mounts ?? [];
+  const ownMounts = compiledAsset.mounts ?? [];
   let stateRef;
   stateRef = world.allocUniqueRef("SceneInstanceState", null, () => {
     sceneWorldState(world).statePayloads.delete(Number(stateRef));
@@ -691,7 +1259,11 @@ function worldInstantiateSceneAsset(world, handle, asset, parent, stack, diagnos
       const memberEntityRaw = mapping[lid];
       if (memberEntityRaw !== void 0 && memberEntityRaw !== ENTITY_NULL_RAW) {
         const memberEntity = memberEntityRaw;
-        const applyRes = worldApplyMountOverride(world, memberEntity, ov);
+        const applyRes = worldApplyMountOverride(
+          world,
+          memberEntity,
+          worldRemapMountOverride(world, ov, mapping)
+        );
         if (!applyRes.ok) {
           return applyRes;
         }
@@ -700,16 +1272,11 @@ function worldInstantiateSceneAsset(world, handle, asset, parent, stack, diagnos
   }
   const detached = /* @__PURE__ */ new Set();
   const bindings = /* @__PURE__ */ new Map();
-  for (const entity of asset.entities) {
-    if (entity.bindingKey === void 0) continue;
-    const live = mapping[entity.localId];
-    if (live !== void 0 && live !== ENTITY_NULL_RAW) {
-      bindings.set(entity.bindingKey, live);
-    }
-  }
   const state = {
     source: handle,
-    sceneSourceKey: asset.sourceKey,
+    ...sceneSourceKey === void 0 ? {} : { sceneSourceKey },
+    keyByLocalId: new Map(compiled.value.keyByLocalId),
+    ...instanceKey === void 0 ? {} : { instanceKey },
     bindings,
     entityToLocalId,
     detachedLocalIds: detached,
@@ -722,6 +1289,7 @@ function worldInstantiateSceneAsset(world, handle, asset, parent, stack, diagnos
     mountTimeOverrides: ownMounts.flatMap((m) => m.overrides ?? [])
   };
   worldSetUniqueRefPayload(world, stateRef, state);
+  collectSceneEntityBindings(world, rootEntity, [], bindings);
   if (childOfToken !== void 0) {
     for (const rootE of rootEntities) {
       const has = world.get(rootE, childOfToken);
@@ -751,10 +1319,23 @@ function worldInstantiateSceneAsset(world, handle, asset, parent, stack, diagnos
       if (!r.ok) return r;
     }
   }
-  return ok4(rootEntity);
+  return ok5(rootEntity);
 }
 function worldInstantiateSceneAssetFlat(world, handle, asset, stack, diagnostics) {
-  const membersRes = worldSpawnSceneMembers(world, handle, asset, stack, diagnostics);
+  const compiled = compileKeyedSceneAsset(world, handle, asset, {
+    resolveSource: (source, parentHandle) => worldResolveMountSource(world, source, parentHandle),
+    resolveAsset: (childHandle) => worldResolveSceneAsset(world, childHandle),
+    stack
+  });
+  if (!compiled.ok) return err5(compiled.error);
+  const membersRes = worldSpawnSceneMembers(
+    world,
+    handle,
+    compiled.value.asset,
+    stack,
+    diagnostics,
+    compiled.value.mountKeyByLocalId
+  );
   if (!membersRes.ok) return membersRes;
   const { rootEntities, mountEntitiesNeedingRootParent, mountEntities, mountInstances } = membersRes.value;
   const childOfToken = world.components.resolve("ChildOf");
@@ -766,7 +1347,11 @@ function worldInstantiateSceneAssetFlat(world, handle, asset, stack, diagnostics
       const memberEntityRaw = childMapping[childLocalId];
       if (memberEntityRaw === void 0 || memberEntityRaw === ENTITY_NULL_RAW) continue;
       const memberEntity = memberEntityRaw;
-      const applyRes = worldApplyMountOverride(world, memberEntity, ov);
+      const applyRes = worldApplyMountOverride(
+        world,
+        memberEntity,
+        worldRemapMountOverride(world, ov, childMapping)
+      );
       if (!applyRes.ok) {
         return applyRes;
       }
@@ -790,34 +1375,43 @@ function worldInstantiateSceneAssetFlat(world, handle, asset, stack, diagnostics
       }
     }
   }
-  return ok4({ roots: [...rootEntities, ...mountEntitiesNeedingRootParent], mountEntities });
+  return ok5({ roots: [...rootEntities, ...mountEntitiesNeedingRootParent], mountEntities });
 }
-function worldBuildSceneEntityComponentDatas(world, node, mapping, diagnostics) {
+function worldBuildSceneEntityComponentDatas(world, node, mapping, _diagnostics) {
   const out = [];
   const nodeLocalId = node.localId;
   for (const compName of Object.keys(node.components)) {
     const token = world.components.resolve(compName);
     if (token === void 0) {
-      return err4(new ComponentNotDefinedError(compName));
+      return err5(new ComponentNotDefinedError(compName));
     }
     const raw = node.components[compName] ?? {};
-    const schema = componentSchema(token);
+    const schema = componentSchema2(token);
     const remappedRaw = {};
     for (const fieldName of Object.keys(raw)) {
       const fieldType = schema[fieldName];
       if (fieldType === void 0) {
-        diagnostics.push({ component: compName, field: fieldName, localId: nodeLocalId });
-        continue;
+        return err5({
+          code: "spawn-data-unknown-field",
+          expected: `field name in {${Object.keys(schema).sort().join(", ")}}`,
+          hint: `unknown field '${fieldName}' on component '${compName}' at scene localId ${nodeLocalId}`,
+          detail: {
+            component: compName,
+            field: fieldName,
+            entity: nodeLocalId,
+            knownFields: Object.keys(schema).sort()
+          }
+        });
       }
       const value = raw[fieldName];
-      const kind = classifyEntityField(token, fieldName);
+      const kind = classifyEntityField2(token, fieldName);
       if (kind !== null) {
         const sceneRemap = (localId) => {
           if (localId < 0 || localId >= mapping.length) return ENTITY_NULL_RAW;
           const live = mapping[localId];
           return live === void 0 || live === ENTITY_NULL_RAW ? ENTITY_NULL_RAW : live;
         };
-        remappedRaw[fieldName] = remapEntityFieldValue(value, kind, sceneRemap);
+        remappedRaw[fieldName] = remapEntityFieldValue2(value, kind, sceneRemap);
       } else {
         remappedRaw[fieldName] = value;
       }
@@ -825,11 +1419,35 @@ function worldBuildSceneEntityComponentDatas(world, node, mapping, diagnostics)
     const filled = fillComponentDefaults(token, remappedRaw);
     out.push({ component: token, data: filled });
   }
-  return ok4(out);
+  return ok5(out);
+}
+function worldRemapMountOverride(world, override, mapping) {
+  const token = world.components.resolve(override.comp);
+  if (token === void 0) return override;
+  const remapField = (field, value2) => {
+    const kind = classifyEntityField2(token, field);
+    if (kind === null) return value2;
+    const toLive = (slot) => {
+      if (slot < 0 || slot >= mapping.length) return ENTITY_NULL_RAW;
+      return mapping[slot] ?? ENTITY_NULL_RAW;
+    };
+    return remapEntityFieldValue2(value2, kind, toLive);
+  };
+  if (override.field !== void 0) {
+    return { ...override, value: remapField(override.field, override.value) };
+  }
+  if (typeof override.value !== "object" || override.value === null || Array.isArray(override.value)) {
+    return override;
+  }
+  const value = {};
+  for (const [field, fieldValue] of Object.entries(override.value)) {
+    value[field] = remapField(field, fieldValue);
+  }
+  return { ...override, value };
 }
 function worldApplyMountOverride(world, member, ov) {
   const ovToken = world.components.resolve(ov.comp);
-  if (ovToken === void 0) return ok4(void 0);
+  if (ovToken === void 0) return ok5(void 0);
   if (ov.field !== void 0) {
     return world.set(member, ovToken, { [ov.field]: ov.value });
   }
@@ -843,7 +1461,7 @@ function worldApplyMountOverride(world, member, ov) {
 }
 function worldValidateMountOverrides(world, mount) {
   const overrides = mount.overrides;
-  if (overrides === void 0) return ok4(void 0);
+  if (overrides === void 0) return ok5(void 0);
   const memberFirst = mount.memberFirst;
   const memberCount = mount.memberCount;
   const memberLast = memberFirst + memberCount;
@@ -851,10 +1469,10 @@ function worldValidateMountOverrides(world, mount) {
   for (const ov of overrides) {
     const ovLid = ov.localId;
     if (ovLid < memberFirst || ovLid >= memberLast) {
-      return err4({
+      return err5({
         code: "pack-mount-override-localid-out-of-range",
         expected: `override.localId in [${memberFirst}, ${memberLast})`,
-        hint: PACK_ERROR_HINTS["pack-mount-override-localid-out-of-range"],
+        hint: PACK_ERROR_HINTS2["pack-mount-override-localid-out-of-range"],
         detail: {
           code: "pack-mount-override-localid-out-of-range",
           overrideLocalId: ovLid,
@@ -866,12 +1484,12 @@ function worldValidateMountOverrides(world, mount) {
     const ovToken = world.components.resolve(ov.comp);
     if (ov.field !== void 0) {
       if (ovToken !== void 0) {
-        const schema = componentSchema(ovToken);
+        const schema = componentSchema2(ovToken);
         if (!(ov.field in schema)) {
-          return err4({
+          return err5({
             code: "pack-mount-override-unknown-field",
             expected: `override.field defined on component '${ov.comp}'`,
-            hint: PACK_ERROR_HINTS["pack-mount-override-unknown-field"],
+            hint: PACK_ERROR_HINTS2["pack-mount-override-unknown-field"],
             detail: {
               code: "pack-mount-override-unknown-field",
               comp: ov.comp,
@@ -883,16 +1501,16 @@ function worldValidateMountOverrides(world, mount) {
       }
     } else {
       if (ovToken === void 0) {
-        return err4(new ComponentNotDefinedError(ov.comp));
+        return err5(new ComponentNotDefinedError(ov.comp));
       }
-      const schema = componentSchema(ovToken);
+      const schema = componentSchema2(ovToken);
       const valueMap = ov.value ?? {};
       for (const key of Object.keys(valueMap)) {
         if (!(key in schema)) {
-          return err4({
+          return err5({
             code: "pack-mount-override-unknown-field",
             expected: `override.value keys defined on component '${ov.comp}'`,
-            hint: PACK_ERROR_HINTS["pack-mount-override-unknown-field"],
+            hint: PACK_ERROR_HINTS2["pack-mount-override-unknown-field"],
             detail: {
               code: "pack-mount-override-unknown-field",
               comp: ov.comp,
@@ -904,7 +1522,7 @@ function worldValidateMountOverrides(world, mount) {
       }
     }
   }
-  return ok4(void 0);
+  return ok5(void 0);
 }
 function worldSpawnMountEntity(world, mount, mapping, diagnostics) {
   const fakeNode = {
@@ -923,7 +1541,7 @@ function worldSpawnMountEntity(world, mount, mapping, diagnostics) {
   if (cdRes.value.length === 0) {
     const childOfToken = world.components.resolve("ChildOf");
     if (childOfToken === void 0) {
-      return err4(new ComponentNotDefinedError("ChildOf"));
+      return err5(new ComponentNotDefinedError("ChildOf"));
     }
     cdRes.value.push({
       component: childOfToken,
@@ -935,7 +1553,7 @@ function worldSpawnMountEntity(world, mount, mapping, diagnostics) {
 function worldResolveMountSource(world, source, parentHandle) {
   const resolver = worldGetSceneAssetResolver(world);
   if (resolver === null) {
-    return err4({
+    return err5({
       code: "stale-entity",
       expected: "wired SceneAssetResolver (auto-wired by engine.assets.instantiate)",
       hint: "engine.assets.instantiate sugar wires this for you; call worldSetSceneAssetResolver before nested scene expansion.",
@@ -944,9 +1562,9 @@ function worldResolveMountSource(world, source, parentHandle) {
   }
   const r = resolver(source, parentHandle);
   if (!r.ok) {
-    return err4(r.error);
+    return err5(r.error);
   }
-  return ok4(r.value);
+  return ok5(r.value);
 }
 function worldMountOverridesToStateMap(src) {
   const out = /* @__PURE__ */ new Map();
@@ -969,7 +1587,7 @@ function worldSetUniqueRefPayload(world, handle, payload) {
 function worldResolveSceneInstanceStatePayload(world, root) {
   const sceneInstanceToken = world.components.resolve("SceneInstance");
   if (sceneInstanceToken === void 0) {
-    return err4(new ComponentNotDefinedError("SceneInstance"));
+    return err5(new ComponentNotDefinedError("SceneInstance"));
   }
   const r = world.get(root, sceneInstanceToken);
   if (!r.ok) return r;
@@ -977,7 +1595,7 @@ function worldResolveSceneInstanceStatePayload(world, root) {
   const stateRefHandle = toUnique(stateRefRaw);
   const payload = sceneWorldState(world).statePayloads.get(Number(stateRefHandle));
   if (payload === void 0) {
-    return err4(
+    return err5(
       new StaleEntityError(root, entityIndex(root), entityGeneration(root), {
         operation: "resolveSceneInstanceState",
         component: "SceneInstance",
@@ -986,7 +1604,7 @@ function worldResolveSceneInstanceStatePayload(world, root) {
       })
     );
   }
-  return ok4(payload);
+  return ok5(payload);
 }
 function worldGetSceneInstanceState(world, root) {
   return worldResolveSceneInstanceStatePayload(world, root);
@@ -995,18 +1613,18 @@ function worldResolveSceneEntity(world, root, ref) {
   const state = worldResolveSceneInstanceStatePayload(world, root);
   if (!state.ok) return state;
   const resolved = resolveSceneEntity(ref, {
-    sceneSourceKey: state.value.sceneSourceKey ?? ref.sceneSourceKey,
+    sceneSourceKey: state.value.sceneSourceKey ?? "",
     bindings: state.value.bindings
   });
-  if (!resolved.ok) return err4(resolved.error);
-  return ok4(resolved.value);
+  if (!resolved.ok) return err5(resolved.error);
+  return ok5(resolved.value);
 }
 function worldDespawnScene(world, root, opts) {
   const dRes = worldDespawnDescendants(world, root, opts);
   if (!dRes.ok) return dRes;
   const drop = world.despawn(root);
   if (!drop.ok) return drop;
-  return ok4(dRes.value + 1);
+  return ok5(dRes.value + 1);
 }
 function worldDespawnDescendants(world, root, opts) {
   let detached = null;
@@ -1083,7 +1701,7 @@ function worldDespawnDescendants(world, root, opts) {
     }
     count += 1;
   }
-  return ok4(count);
+  return ok5(count);
 }
 function worldSetSceneOverride(world, root, member, component, field, value) {
   const stateRes = worldResolveSceneInstanceStatePayload(world, root);
@@ -1091,7 +1709,7 @@ function worldSetSceneOverride(world, root, member, component, field, value) {
   const state = stateRes.value;
   const lid = state.entityToLocalId.get(member);
   if (lid === void 0) {
-    return err4(
+    return err5(
       new StaleEntityError(
         member,
         entityIndex(member),
@@ -1105,12 +1723,12 @@ function worldSetSceneOverride(world, root, member, component, field, value) {
       )
     );
   }
-  const schemaType = componentSchema(component)[field];
+  const schemaType = componentSchema2(component)[field];
   if (schemaType !== void 0 && isPrimitiveScalarFieldType(schemaType)) {
     const expectJsType = primitiveJsType(schemaType);
     const actualJsType = typeof value;
     if (expectJsType !== actualJsType) {
-      return err4({
+      return err5({
         code: "scene-override-type-mismatch",
         expected: `value typeof === ${expectJsType}`,
         hint: `setSceneOverride(${component.name}.${field}) expected ${expectJsType}, got ${actualJsType}; coerce or pick a different override path.`,
@@ -1136,14 +1754,14 @@ function worldSetSceneOverride(world, root, member, component, field, value) {
     field,
     value
   });
-  return ok4(void 0);
+  return ok5(void 0);
 }
 function worldRemoveSceneOverride(world, root, member, component, field) {
   const stateRes = worldResolveSceneInstanceStatePayload(world, root);
   if (!stateRes.ok) return stateRes;
   const state = stateRes.value;
   const lid = state.entityToLocalId.get(member);
-  if (lid === void 0) return ok4(void 0);
+  if (lid === void 0) return ok5(void 0);
   const fieldMap = state.overrides.get(lid);
   if (fieldMap !== void 0) {
     fieldMap.delete(`${component.name}:${field}`);
@@ -1151,42 +1769,41 @@ function worldRemoveSceneOverride(world, root, member, component, field) {
   }
   const assetRes = worldResolveSceneAsset(world, state.source);
   if (!assetRes.ok) return assetRes;
-  const node = assetRes.value.entities.find(
-    (n) => n.localId === lid
-  );
+  const key = state.keyByLocalId.get(lid);
+  const node = key === void 0 ? void 0 : assetRes.value.entities[key];
   const layer1 = node?.components[component.name];
   if (layer1 !== void 0 && field in layer1) {
     const r = world.set(member, component, { [field]: layer1[field] });
     if (!r.ok) return r;
   }
-  return ok4(void 0);
+  return ok5(void 0);
 }
 function worldDetachSceneMember(world, root, member) {
   const sceneInstanceToken = world.components.resolve("SceneInstance");
   if (sceneInstanceToken === void 0) {
-    return err4(new ComponentNotDefinedError("SceneInstance"));
+    return err5(new ComponentNotDefinedError("SceneInstance"));
   }
   const stateRes = worldResolveSceneInstanceStatePayload(world, root);
   if (!stateRes.ok) return stateRes;
   const state = stateRes.value;
   const lid = state.entityToLocalId.get(member);
-  if (lid === void 0) return ok4(void 0);
+  if (lid === void 0) return ok5(void 0);
   state.detachedLocalIds.add(lid);
-  return ok4(void 0);
+  return ok5(void 0);
 }
 function worldReattachSceneMember(world, root, member) {
   const stateRes = worldResolveSceneInstanceStatePayload(world, root);
   if (!stateRes.ok) return stateRes;
   const state = stateRes.value;
   const lid = state.entityToLocalId.get(member);
-  if (lid === void 0) return ok4(void 0);
+  if (lid === void 0) return ok5(void 0);
   state.detachedLocalIds.delete(lid);
-  return ok4(void 0);
+  return ok5(void 0);
 }
 function worldGetSceneAssetForInstance(world, root) {
   const stateRes = worldResolveSceneInstanceStatePayload(world, root);
   if (!stateRes.ok) return stateRes;
-  return ok4(stateRes.value.source);
+  return ok5(stateRes.value.source);
 }
 function sceneTopoSort(nodes) {
   const n = nodes.length;
@@ -1243,7 +1860,7 @@ import {
 } from "@forgeax/engine-ecs/internal";
 import { worldRead } from "@forgeax/engine-ecs/world-read";
 import { mat4 } from "@forgeax/engine-math";
-import { err as err5, ok as ok5 } from "@forgeax/engine-types";
+import { err as err6, ok as ok6 } from "@forgeax/engine-types";
 var PROPAGATE_TRANSFORMS_SYSTEM = "propagateTransforms";
 var PROPAGATE_TRANSFORMS_FIXED_SYSTEM = "propagateTransformsFixed";
 var TransformSet = defineSystemSet({ name: "transform" });
@@ -1261,7 +1878,7 @@ function countPropagation(name) {
 var SCRATCH = /* @__PURE__ */ new WeakMap();
 var REGISTRATION_LEASES = /* @__PURE__ */ new WeakMap();
 function pairError(entity, expected) {
-  return err5(
+  return err6(
     new SceneError({
       code: "hierarchy-broken",
       expected,
@@ -1272,7 +1889,7 @@ function pairError(entity, expected) {
 }
 function ensureQueries(world, scratch) {
   if (scratch.flatQuery !== void 0 && scratch.hierarchyQuery !== void 0 && scratch.transformQuery !== void 0 && scratch.hierarchyWriter !== void 0 && scratch.transformWriter !== void 0 && scratch.missingGlobalQuery !== void 0 && scratch.missingTransformQuery !== void 0) {
-    return ok5(void 0);
+    return ok6(void 0);
   }
   const flatOutput = world.query({
     read: [Transform],
@@ -1299,7 +1916,7 @@ function ensureQueries(world, scratch) {
   scratch.transformWriter = transformWriter.value;
   scratch.missingGlobalQuery = missingGlobal.value;
   scratch.missingTransformQuery = missingTransform.value;
-  return ok5(void 0);
+  return ok6(void 0);
 }
 function validateTransformPairs(world, scratch) {
   const queryResult = ensureQueries(world, scratch);
@@ -1315,7 +1932,7 @@ function validateTransformPairs(world, scratch) {
   for (const row of missingTransform) {
     return pairError(row.entity, "each GlobalTransform entity to carry a Transform pair");
   }
-  return ok5(void 0);
+  return ok6(void 0);
 }
 function scratchFor(world) {
   const existing = SCRATCH.get(world);
@@ -1406,7 +2023,7 @@ function composeFlatColumns(positions, rotations, scales, worlds, count) {
 function propagateFlat(world, scratch) {
   const query = scratch.flatQuery;
   if (query === void 0)
-    return err5(
+    return err6(
       new SceneError({
         code: "hierarchy-broken",
         expected: "a valid changed Transform write query",
@@ -1425,7 +2042,7 @@ function propagateFlat(world, scratch) {
     }
   } catch (cause) {
     const error = cause;
-    return err5(derivedWriteError(error, bindingIndex));
+    return err6(derivedWriteError(error, bindingIndex));
   }
   const transformWriter = scratch.transformWriter;
   if (transformWriter === void 0) {
@@ -1433,7 +2050,7 @@ function propagateFlat(world, scratch) {
   }
   const transformBindings = transformWriter.bindings;
   const structureEpoch = world.getStructureEpoch();
-  if (scratch.flatStructureEpoch === structureEpoch) return ok5(void 0);
+  if (scratch.flatStructureEpoch === structureEpoch) return ok6(void 0);
   ensureFlatBuffers(scratch, transformBindings);
   resetFlatBuffers(scratch);
   for (let bindingIndex2 = 0; bindingIndex2 < transformBindings.length; bindingIndex2 += 1) {
@@ -1452,10 +2069,10 @@ function propagateFlat(world, scratch) {
     const changed = scratch.flatChanged[bindingIndex2];
     if (changed === void 0) continue;
     const published = transformWriter.publishChangedRows(bindingIndex2, changed);
-    if (!published.ok) return err5(derivedWriteError(published.error, bindingIndex2));
+    if (!published.ok) return err6(derivedWriteError(published.error, bindingIndex2));
   }
   scratch.flatStructureEpoch = structureEpoch;
-  return ok5(void 0);
+  return ok6(void 0);
 }
 function transformColumns(binding) {
   return binding.read;
@@ -2007,7 +2624,7 @@ function propagateHierarchy(world, scratch) {
   const hierarchyWriter = scratch.hierarchyWriter;
   const transformWriter = scratch.transformWriter;
   if (hierarchyWriter === void 0 || transformWriter === void 0) {
-    return err5(
+    return err6(
       new SceneError({
         code: "hierarchy-broken",
         expected: "paired Transform and GlobalTransform derived bindings",
@@ -2022,7 +2639,7 @@ function propagateHierarchy(world, scratch) {
     scratch.hierarchyBindingRows.length = 0;
     scratch.hierarchyStates.length = 0;
     scratch.hierarchyChanged.length = 0;
-    return ok5(void 0);
+    return ok6(void 0);
   }
   ensureHierarchyBuffers(scratch, hierarchyBindings);
   resetHierarchyBuffers(scratch);
@@ -2080,7 +2697,7 @@ function propagateHierarchy(world, scratch) {
       report(derivedWriteError(cause, bindingIndex));
     }
   }
-  return firstError === void 0 ? ok5(void 0) : err5(firstError);
+  return firstError === void 0 ? ok6(void 0) : err6(firstError);
 }
 function propagateTransforms(world) {
   const scratch = scratchFor(world);
@@ -2291,6 +2908,7 @@ export {
   Transform,
   TransformSet,
   collectSubtree,
+  compileKeyedSceneAsset,
   externalizeSceneAsset,
   projectHierarchy,
   propagateTransforms,
@@ -2298,8 +2916,9 @@ export {
   resolveSceneEntity,
   sceneAssetContribution,
   sceneEntity,
+  sceneEntityAddressKey,
   scenePlugin,
-  validateSceneBindings,
+  validateSceneEntityKeys,
   worldApplyMountOverride,
   worldBuildSceneEntityComponentDatas,
   worldDespawnDescendants,