@forgeax/engine-scene 0.1.28 → 0.1.30

package/src/assets/scene-decoder.ts

@@ -8,8 +8,9 @@ import {
   type Result,
   type SceneAsset,
   type SceneEntity,
-  type SceneInstanceMount,
+  type SceneInstanceOverride,
 } from '@forgeax/engine-types';
+import { normalizeLegacySceneAsset } from '../instances/legacy.js';
 
 export const sceneAssetKind: AssetKind<SceneAsset, 'scene'> = {
   kind: 'scene',
@@ -18,7 +19,7 @@ export const sceneAssetKind: AssetKind<SceneAsset, 'scene'> = {
 function invalidScene(guid: string, reason: string): Result<SceneAsset, AssetLoadError> {
   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 },
   });
@@ -54,24 +55,16 @@ function resolveWireRef(
   return { ok: true, value: guid };
 }
 
-function resolveMounts(
-  mounts: readonly SceneInstanceMount[] | undefined,
+function resolveInstanceSource(
+  source: unknown,
   refs: readonly string[],
-):
-  | { readonly ok: true; readonly value: readonly SceneInstanceMount[] | undefined }
-  | { readonly ok: false; readonly reason: string } {
-  if (mounts === undefined) return { ok: true, value: undefined };
-  const resolved: SceneInstanceMount[] = [];
-  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 });
+  location: string,
+): { readonly ok: true; readonly value: string } | { readonly ok: false; readonly reason: string } {
+  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(
@@ -98,11 +91,46 @@ function resolveSkinGuids(
   return { ok: true, value: resolved };
 }
 
-function resolveSceneWireRefs(payload: SceneAsset, refs: readonly string[]): SceneWireRefResult {
-  const entities: SceneEntity[] = [];
-  for (const entity of payload.entities) {
+function resolveSceneWireRefs(
+  payload: { readonly entities: unknown; readonly skinGuids?: unknown },
+  refs: readonly string[],
+): SceneWireRefResult {
+  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: Record<string, SceneEntity> = {};
+  for (const [key, rawEntity] of Object.entries(rawEntities as Record<string, unknown>)) {
+    const entity = rawEntity as
+      | {
+          readonly components?: unknown;
+          readonly instance?: {
+            readonly source?: unknown;
+            readonly overrides?: unknown;
+          };
+        }
+      | undefined;
+    if (key.length === 0 || entity === undefined || 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: Record<string, Record<string, unknown>> = {};
-    for (const [componentName, rawFields] of Object.entries(entity.components)) {
+    for (const [componentName, rawFields] of Object.entries(
+      entity.components as Record<string, unknown>,
+    )) {
+      if (rawFields === null || typeof rawFields !== 'object' || Array.isArray(rawFields)) {
+        return {
+          ok: false,
+          reason: `entities.${key}.components.${componentName} must be an object`,
+        };
+      }
       // Component schema lookup is World-local after the ECS core reduction.
       // The runtime projection owns the World-local schema and converts
       // authored GUID fields into World.sharedRefs handles. Keep this loader
@@ -110,17 +138,77 @@ function resolveSceneWireRefs(payload: SceneAsset, refs: readonly string[]): Sce
       // component registry.
       components[componentName] = { ...(rawFields as Record<string, unknown>) };
     }
-    entities.push({
-      localId: entity.localId,
-      ...(entity.bindingKey === undefined ? {} : { bindingKey: entity.bindingKey }),
+    const instance = entity.instance;
+    let resolvedInstance: SceneEntity['instance'];
+    if (instance !== undefined) {
+      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 !== undefined && !Array.isArray(instance.overrides)) {
+        return { ok: false, reason: `entities.${key}.instance.overrides must be an array` };
+      }
+      let overrides: NonNullable<SceneEntity['instance']>['overrides'] | undefined;
+      if (instance.overrides === undefined) {
+        overrides = undefined;
+      } else {
+        const resolvedOverrides: SceneInstanceOverride[] = [];
+        for (const [index, rawOverride] of (instance.overrides as readonly unknown[]).entries()) {
+          if (
+            rawOverride === null ||
+            typeof rawOverride !== 'object' ||
+            Array.isArray(rawOverride) ||
+            !Array.isArray((rawOverride as { readonly target?: unknown }).target) ||
+            (rawOverride as { readonly target?: unknown[] }).target?.some(
+              (part) => typeof part !== 'string' || part.length === 0,
+            )
+          ) {
+            return {
+              ok: false,
+              reason: `entities.${key}.instance.overrides[${index}] is malformed`,
+            };
+          }
+          const target = (rawOverride as { readonly target: readonly string[] }).target;
+          const rawComponents = (rawOverride as { readonly components?: unknown }).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] as [string, ...string[]],
+            components: rawComponents as SceneEntity['components'],
+          });
+        }
+        overrides = resolvedOverrides;
+      }
+      resolvedInstance = {
+        source: source.value,
+        ...(overrides === undefined ? {} : { overrides }),
+      };
+    }
+    entities[key] = {
       components,
-    });
+      ...(resolvedInstance === undefined ? {} : { instance: resolvedInstance }),
+    };
   }
 
-  const mounts = resolveMounts(payload.mounts, refs);
-  if (!mounts.ok) return mounts;
   const skinGuids = resolveSkinGuids(
-    payload.skinGuids as readonly (number | string)[] | undefined,
+    Array.isArray(payload.skinGuids)
+      ? (payload.skinGuids as readonly (number | string)[])
+      : payload.skinGuids === undefined
+        ? undefined
+        : ([] as readonly (number | string)[]),
     refs,
   );
   if (!skinGuids.ok) return skinGuids;
@@ -129,9 +217,7 @@ function resolveSceneWireRefs(payload: SceneAsset, refs: readonly string[]): Sce
     ok: true,
     value: {
       kind: 'scene',
-      ...(payload.sourceKey === undefined ? {} : { sourceKey: payload.sourceKey }),
       entities,
-      ...(mounts.value === undefined ? {} : { mounts: mounts.value }),
       ...(skinGuids.value === undefined ? {} : { skinGuids: skinGuids.value }),
     },
   };
@@ -141,8 +227,12 @@ function resolveSceneWireRefs(payload: SceneAsset, refs: readonly string[]): Sce
 export const sceneAssetDecoder: AssetDecoder<SceneAsset> = {
   async decode({ envelope }): Promise<Result<SceneAsset, AssetLoadError>> {
     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);

package/src/collect-subtree.ts

@@ -14,8 +14,8 @@ export function collectSubtree(
   if (visited.has(spawnRoot as number)) return visited;
   const queue: number[] = [spawnRoot as number];
   visited.add(spawnRoot as number);
-  while (queue.length > 0) {
-    const current = queue.shift() as number;
+  for (let cursor = 0; cursor < queue.length; cursor += 1) {
+    const current = queue[cursor] as number;
     const children = world.get(current as EntityHandle, Children);
     if (!children.ok) continue;
     const entities = children.value.entities as ArrayLike<number>;

package/src/index.ts

@@ -17,7 +17,8 @@ export {
   type SceneBindingError,
   type SceneEntityRef,
   sceneEntity,
-  validateSceneBindings,
+  sceneEntityAddressKey,
+  validateSceneEntityKeys,
 } from './instances/binding';
 export { SCENE_COLLECT_PROFILE, type SceneCollectProfile } from './instances/collect-profile';
 export {
@@ -26,6 +27,14 @@ export {
   type SceneComponentSchemaResolver,
   type SceneExternalizationError,
 } from './instances/externalization';
+export {
+  type CompiledSceneAsset,
+  type CompiledSceneEntity,
+  type CompiledSceneResult,
+  compileKeyedSceneAsset,
+  type KeyedSceneCompileContext,
+} from './instances/keyed';
+export type { MountOverride, SceneInstanceMount } from './instances/runtime-types';
 export {
   type SceneAssetResolver,
   type SceneInstanceStatePayload,

package/src/instances/binding.ts

@@ -1,5 +1,5 @@
 import type { EntityHandle } from '@forgeax/engine-ecs';
-import type { SceneEntityRef } from '@forgeax/engine-types';
+import type { SceneEntityAddress, SceneEntityRef } from '@forgeax/engine-types';
 import { err, ok, type Result } from '@forgeax/engine-types';
 
 export type { SceneEntityRef } from '@forgeax/engine-types';
@@ -8,19 +8,19 @@ export type SceneBindingError = {
   readonly code: 'scene-binding-missing' | 'scene-binding-wrong-instance';
   readonly expected: string;
   readonly hint: string;
-  readonly detail: { readonly sceneSourceKey: string; readonly bindingKey: string };
+  readonly detail: { readonly sceneSourceKey: string; readonly address: SceneEntityAddress };
 };
 
 export type SceneBindingDeclarationError = {
   readonly code: 'scene-binding-duplicate' | 'scene-binding-source-missing';
   readonly expected: string;
   readonly hint: string;
-  readonly detail: { readonly sceneSourceKey?: string; readonly bindingKey?: string };
+  readonly detail: { readonly sceneSourceKey?: string; readonly address?: SceneEntityAddress };
 };
 
-export function validateSceneBindings(
+export function validateSceneEntityKeys(
   sceneSourceKey: string,
-  bindingKeys: readonly string[],
+  entityKeys: readonly string[],
 ): Result<readonly string[], SceneBindingDeclarationError> {
   if (sceneSourceKey.length === 0) {
     return err({
@@ -31,22 +31,29 @@ export function validateSceneBindings(
     });
   }
   const seen = new Set<string>();
-  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 err({
         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 ok([...bindingKeys]);
+  return ok([...entityKeys]);
 }
 
-export function sceneEntity(sceneSourceKey: string, bindingKey: string): SceneEntityRef {
-  return { sceneSourceKey, bindingKey };
+export function sceneEntity(sceneSourceKey: string, address: SceneEntityAddress): SceneEntityRef {
+  return { sceneSourceKey, address };
+}
+
+/** Stable map key shared by direct and nested SceneEntityRef addresses. */
+export function sceneEntityAddressKey(address: SceneEntityAddress): string {
+  if (typeof address === 'string') return `s:${JSON.stringify(address)}`;
+  if (address.length === 1) return `s:${JSON.stringify(address[0] ?? '')}`;
+  return `a:${JSON.stringify(address)}`;
 }
 
 export function resolveSceneEntity(
@@ -61,16 +68,16 @@ export function resolveSceneEntity(
       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 === undefined) {
     return err({
       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 ok(value);

package/src/instances/externalization.ts

@@ -1,5 +1,6 @@
-import type { AssetRef, MountOverride, SceneAsset } from '@forgeax/engine-types';
+import type { AssetRef, SceneAsset, SceneInstanceOverride } from '@forgeax/engine-types';
 import { err, ok, type Result } from '@forgeax/engine-types';
+import { migrateLegacySceneComponentFields, normalizeLegacySceneAsset } from './legacy.js';
 
 export type SceneComponentSchemaResolver = (
   componentName: string,
@@ -21,123 +22,140 @@ function sharedKind(type: string | undefined): 'one' | 'many' | undefined {
   return undefined;
 }
 
-function overrideGuids(
-  override: MountOverride,
+interface RefContext {
+  readonly refs: AssetRef[];
+  readonly indexByGuid: Map<string, number>;
+}
+
+function addRef(
+  context: RefContext,
+  guid: string,
+  sourceField: NonNullable<AssetRef['sourceField']>,
+  sceneEntityKey?: string,
+): number {
+  const prior = context.indexByGuid.get(guid);
+  if (prior !== undefined) return prior;
+  const index = context.refs.length;
+  context.refs.push({
+    guid,
+    sourceField,
+    ...(sceneEntityKey === undefined ? {} : { sceneEntityKey }),
+  } as AssetRef);
+  context.indexByGuid.set(guid, index);
+  return index;
+}
+
+function externalizeFields(
+  componentName: string,
+  source: Record<string, unknown>,
   resolveSchema: SceneComponentSchemaResolver,
-): readonly { field: string; guid: string }[] {
-  const schema = resolveSchema(override.comp);
-  const values =
-    override.field !== undefined
-      ? [[override.field, override.value] as const]
-      : override.value !== null &&
-          typeof override.value === 'object' &&
-          !Array.isArray(override.value)
-        ? Object.entries(override.value as Record<string, unknown>)
-        : [];
-  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 }] : []));
+  context: RefContext,
+  sceneEntityKey: string | undefined,
+): Record<string, unknown> {
+  const schema = resolveSchema(componentName);
+  const fields: Record<string, unknown> = {};
+  for (const [fieldName, value] of Object.entries(
+    migrateLegacySceneComponentFields(componentName, source),
+  )) {
+    if (value === undefined) 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 [];
-  });
+  }
+  return fields;
 }
 
-/** Project a SceneAsset's shared asset fields into a payload plus indexed refs. */
+function externalizeOverride(
+  override: SceneInstanceOverride,
+  resolveSchema: SceneComponentSchemaResolver,
+  context: RefContext,
+  sceneEntityKey: string,
+): SceneInstanceOverride {
+  const components: Record<string, Record<string, unknown>> = {};
+  for (const [componentName, rawFields] of Object.entries(override.components)) {
+    components[componentName] = externalizeFields(
+      componentName,
+      { ...(rawFields as Record<string, unknown>) },
+      resolveSchema,
+      context,
+      sceneEntityKey,
+    );
+  }
+  return {
+    target: [...override.target],
+    components,
+  };
+}
+
+/** Project a keyed SceneAsset's shared asset fields into a payload plus refs. */
 export function externalizeSceneAsset(
   scene: SceneAsset,
   resolveSchema: SceneComponentSchemaResolver,
 ): Result<ExternalizedSceneAsset, SceneExternalizationError> {
-  const refs: AssetRef[] = [];
-  const indexByGuid = new Map<string, number>();
-  const addRef = (
-    guid: string,
-    sourceField: NonNullable<AssetRef['sourceField']>,
-    sceneEntityId?: number,
-  ): number => {
-    const prior = indexByGuid.get(guid);
-    if (prior !== undefined) return prior;
-    const index = refs.length;
-    refs.push({ guid, sourceField, ...(sceneEntityId === undefined ? {} : { sceneEntityId }) });
-    indexByGuid.set(guid, index);
-    return index;
-  };
-
-  const entities = scene.entities.map((entity) => {
+  const normalized = normalizeLegacySceneAsset(scene);
+  const context: RefContext = { refs: [], indexByGuid: new Map() };
+  const entities: Record<string, Record<string, unknown>> = {};
+  for (const [key, entity] of Object.entries(normalized.entities)) {
     const components: Record<string, Record<string, unknown>> = {};
-    for (const componentName of Object.keys(entity.components)) {
-      const schema = resolveSchema(componentName);
-      const source = entity.components[componentName] as Record<string, unknown> | undefined;
+    for (const [componentName, raw] of Object.entries(entity.components)) {
+      const source = raw as Record<string, unknown> | undefined;
       if (source === undefined) continue;
-      const fields: Record<string, unknown> = {};
-      for (const fieldName of Object.keys(source)) {
-        const value = source[fieldName];
-        if (value === undefined) continue;
-        const kind = sharedKind(schema?.[fieldName]);
-        if (kind === 'one' && typeof value === 'string') {
-          fields[fieldName] = addRef(value, { componentName, fieldName }, entity.localId as number);
-        } else if (kind === 'many' && Array.isArray(value)) {
-          fields[fieldName] = value.map((item, arrayIndex) =>
-            typeof item === 'string'
-              ? addRef(item, { componentName, fieldName, arrayIndex }, entity.localId as number)
-              : item,
-          );
-        } else {
-          fields[fieldName] = value;
-        }
-      }
-      if (Object.keys(fields).length > 0 || Object.keys(schema ?? {}).length === 0) {
-        components[componentName] = fields;
-      }
+      components[componentName] = externalizeFields(
+        componentName,
+        source,
+        resolveSchema,
+        context,
+        key,
+      );
     }
-    return {
-      localId: entity.localId as number,
-      ...(entity.bindingKey === undefined ? {} : { bindingKey: entity.bindingKey }),
+    const instance = entity.instance;
+    entities[key] = {
       components,
-    };
-  });
-
-  const mounts = scene.mounts?.map((mount) => {
-    const source =
-      typeof mount.source === 'string'
-        ? addRef(
-            mount.source,
-            { componentName: 'SceneInstance', fieldName: 'source' },
-            mount.localId as number,
-          )
-        : (mount.source as number);
-    for (const { field, guid } of (mount.overrides ?? []).flatMap((override) =>
-      overrideGuids(override, resolveSchema),
-    )) {
-      addRef(guid, { componentName: 'SceneInstance', fieldName: `overrides.${field}` });
-    }
-    return {
-      localId: mount.localId as number,
-      source,
-      memberFirst: mount.memberFirst as number,
-      memberCount: mount.memberCount,
-      ...(mount.parent === undefined ? {} : { parent: mount.parent as number }),
-      ...(mount.publicationFence === undefined ? {} : { publicationFence: mount.publicationFence }),
-      ...(mount.overrides === undefined
+      ...(instance === undefined
         ? {}
-        : { overrides: mount.overrides.map((item) => ({ ...item })) }),
+        : {
+            instance: {
+              source: addRef(
+                context,
+                instance.source,
+                { componentName: 'SceneInstance', fieldName: 'source' },
+                key,
+              ),
+              ...(instance.overrides === undefined
+                ? {}
+                : {
+                    overrides: instance.overrides.map((override) =>
+                      externalizeOverride(override, resolveSchema, context, key),
+                    ),
+                  }),
+            },
+          }),
     };
-  });
-  for (const [arrayIndex, guid] of (scene.skinGuids ?? []).entries()) {
+  }
+
+  for (const [arrayIndex, guid] of (normalized.skinGuids ?? []).entries()) {
     if (typeof guid !== 'string') return err({ field: 'skinGuids', value: guid });
-    addRef(guid, { componentName: '<scene>', fieldName: 'skinGuids', arrayIndex });
+    addRef(context, guid, { componentName: '<scene>', fieldName: 'skinGuids', arrayIndex });
   }
   return ok({
     payload: {
       kind: 'scene',
-      ...(scene.sourceKey === undefined ? {} : { sourceKey: scene.sourceKey }),
       entities,
-      ...(mounts === undefined || mounts.length === 0 ? {} : { mounts }),
-      ...(scene.skinGuids === undefined
+      ...(normalized.skinGuids === undefined
         ? {}
-        : { skinGuids: scene.skinGuids.map((guid) => indexByGuid.get(guid) as number) }),
+        : {
+            skinGuids: normalized.skinGuids.map((guid) => context.indexByGuid.get(guid) as number),
+          }),
     },
-    refs,
+    refs: context.refs,
   });
 }