@forgeax/engine-scene 0.1.21 → 0.1.24

package/src/instances/scene-instances.ts

@@ -21,6 +21,7 @@ import type {
   PackErrorCode,
   PackErrorDetail,
   SceneAsset,
+  SceneEntityRef,
   SceneInstanceMount,
 } from '@forgeax/engine-types';
 import {
@@ -32,6 +33,16 @@ import {
   unwrapHandle,
 } from '@forgeax/engine-types';
 import { ComponentNotDefinedError } from '../errors';
+import { resolveSceneEntity, validateSceneBindings } from './binding.js';
+import {
+  isPrimitiveScalarFieldType,
+  mountOverrideStateKey,
+  primitiveJsType,
+  type SceneInstanceStatePayload,
+  sceneWorldState,
+} from './state.js';
+
+export type { SceneInstanceStatePayload } from './state.js';
 
 const entityIndex = (entity: EntityHandle): number => (entity as number) & 0x00ffffff;
 const entityGeneration = (entity: EntityHandle): number => ((entity as number) >>> 24) & 0xff;
@@ -136,21 +147,6 @@ export type SceneAssetResolver = (
   parentHandle: Handle<'SceneAsset', 'shared'>,
 ) => Result<Handle<'SceneAsset', 'shared'>, unknown>;
 
-interface SceneWorldState {
-  resolver: SceneAssetResolver | null;
-  readonly statePayloads: Map<number, unknown>;
-}
-
-const sceneWorldStates = new WeakMap<World, SceneWorldState>();
-
-function sceneWorldState(world: World): SceneWorldState {
-  const current = sceneWorldStates.get(world);
-  if (current !== undefined) return current;
-  const created = { resolver: null, statePayloads: new Map<number, unknown>() };
-  sceneWorldStates.set(world, created);
-  return created;
-}
-
 /** @internal */
 export function worldSetSceneAssetResolver(world: World, resolver: SceneAssetResolver): void {
   sceneWorldState(world).resolver = resolver;
@@ -158,7 +154,7 @@ export function worldSetSceneAssetResolver(world: World, resolver: SceneAssetRes
 
 /** @internal */
 export function worldGetSceneAssetResolver(world: World): SceneAssetResolver | null {
-  return sceneWorldState(world).resolver;
+  return sceneWorldState(world).resolver as SceneAssetResolver | null;
 }
 
 /**
@@ -339,6 +335,15 @@ export function worldSpawnSceneMembers(
 
   const ownEntities = asset.entities;
   const ownMounts = asset.mounts ?? [];
+  const bindingKeys = ownEntities.flatMap((entity) =>
+    entity.bindingKey === undefined ? [] : [entity.bindingKey],
+  );
+  if (bindingKeys.length > 0) {
+    const bindingCheck = validateSceneBindings(asset.sourceKey ?? '', bindingKeys);
+    if (!bindingCheck.ok) {
+      return err(bindingCheck.error as unknown as EcsError);
+    }
+  }
   const memberSum = ownMounts.reduce((s, m) => s + m.memberCount, 0);
   const countBaseline = ownEntities.length + ownMounts.length + memberSum;
   // C-R1 (studio-issues #6): mapping table must be sized to maxLocalId+1,
@@ -641,8 +646,8 @@ export function worldInstantiateSceneAsset(
   const mappingPlain: number[] = Array.from(mapping);
   // The synthetic root is the ChildOf parent of every owned root entity
   // (step 5 below) and may itself become a ChildOf parent of a caller-
-  // supplied `parent` chain. propagateTransforms walks ChildOf parents
-  // through the Transform liveMap and treats a parent missing Transform
+  // supplied `parent` chain. propagateTransforms expands the ECS-maintained
+  // Children lists parent-first and treats a parent missing Transform
   // as `hierarchy-broken`, so the synthetic root must carry Transform
   // (identity TRS via layer-2 defaults) when Transform is defined.
   const rootComponents: ComponentData[] = [
@@ -701,8 +706,18 @@ export function worldInstantiateSceneAsset(
   }
 
   const detached = new Set<LocalEntityId>();
+  const bindings = new Map<string, EntityHandle>();
+  for (const entity of asset.entities) {
+    if (entity.bindingKey === undefined) continue;
+    const live = mapping[entity.localId as unknown as number];
+    if (live !== undefined && live !== ENTITY_NULL_RAW) {
+      bindings.set(entity.bindingKey, live as unknown as EntityHandle);
+    }
+  }
   const state: Record<string, unknown> = {
     source: handle,
+    sceneSourceKey: asset.sourceKey,
+    bindings,
     entityToLocalId,
     detachedLocalIds: detached,
     // Convert overrides Map<LocalEntityId, Map<string, MountOverride>>
@@ -1033,7 +1048,7 @@ export function worldValidateMountOverrides(
  * chain `cube -> innerSyntheticRoot -> mountEntity -> outerSyntheticRoot`,
  * so it MUST carry Transform whenever Transform is registered (mirrors
  * the D-V-0 synthetic-root invariant). Otherwise propagateTransforms
- * walking the chain hits a Transform-less parent and emits per-frame
+ * expanding the chain hits a Transform-less parent and emits per-frame
  * `RhiError(hierarchy-broken)` (verify R1 root cause of the
  * hello-scene-nesting demo black frames).
  */
@@ -1049,7 +1064,7 @@ export function worldSpawnMountEntity(
   };
   const cdRes = worldBuildSceneEntityComponentDatas(world, fakeNode, mapping, diagnostics);
   if (!cdRes.ok) return cdRes;
-  // R2/B-1: ensure Transform is attached so propagateTransforms can walk
+  // R2/B-1: ensure Transform is attached so propagateTransforms can expand
   // through this entity. Layer-2 defaults supply identity TRS; the
   // mount.components overlay (when present and including Transform) takes
   // precedence and is already in cdRes.value.
@@ -1179,6 +1194,22 @@ export function worldGetSceneInstanceState(
 ): Result<SceneInstanceStatePayload, EcsError> {
   return worldResolveSceneInstanceStatePayload(world, root);
 }
+
+/** Resolve a generated SceneEntityRef against one concrete SceneInstance. */
+export function worldResolveSceneEntity(
+  world: World,
+  root: EntityHandle,
+  ref: SceneEntityRef,
+): Result<EntityHandle, EcsError> {
+  const state = worldResolveSceneInstanceStatePayload(world, root);
+  if (!state.ok) return state;
+  const resolved = resolveSceneEntity(ref, {
+    sceneSourceKey: state.value.sceneSourceKey ?? ref.sceneSourceKey,
+    bindings: state.value.bindings,
+  });
+  if (!resolved.ok) return err(resolved.error as unknown as EcsError);
+  return ok(resolved.value as EntityHandle);
+}
 /**
  * Despawn a SceneInstance root + all its members. `opts.keepDetached`
  * preserves members marked via `worldDetachSceneMember` (plan-strategy
@@ -1452,27 +1483,6 @@ export function worldGetSceneAssetForInstance(
   return ok(stateRes.value.source);
 }
 
-// SceneInstanceStatePayload — internal echo of the runtime
-// `SceneInstanceState` interface for ECS-side consumption (engine-ecs cannot
-// value-import engine-runtime by AC-29; structural shape only).
-// ────────────────────────────────────────────────────────────────────────────
-
-/** @internal Structural payload behind `SceneInstance.state` ref column. */
-export interface SceneInstanceStatePayload {
-  readonly source: Handle<'SceneAsset', 'shared'>;
-  readonly entityToLocalId: Map<EntityHandle, LocalEntityId>;
-  readonly detachedLocalIds: Set<LocalEntityId>;
-  readonly overrides: Map<
-    LocalEntityId,
-    Map<string, { readonly comp: string; readonly field?: string; readonly value: unknown }>
-  >;
-  readonly rootEntities: EntityHandle[];
-  /** Synthetic roots of recursively mounted SceneAssets owned by this instance. */
-  readonly mountRoots: EntityHandle[];
-  readonly totalSlots: number;
-  readonly mountTimeOverrides: readonly MountOverride[];
-}
-
 /**
  * Topological sort over the implicit ChildOf graph (parents before children).
  * Cycle-free input always covers all n nodes; cyclic input emits whatever was
@@ -1523,42 +1533,3 @@ function sceneTopoSort(
   }
   return order;
 }
-
-/**
- * @internal feat-20260713 M2 / w8: SceneInstanceState map key for a
- * MountOverride. Field-patch form keys by `comp:field` (one entry per patched
- * field); component-add form keys by `comp` (one entry per added component). The
- * two key shapes cannot collide because a field-patch always carries a `:field`
- * suffix. Later array entries for the same key overwrite earlier ones, matching
- * the array-order apply semantics.
- */
-function mountOverrideStateKey(ov: MountOverride): string {
-  return ov.field !== undefined ? `${ov.comp}:${ov.field}` : ov.comp;
-}
-
-/** Schema field types that are JS primitives (typeof checkable). */
-function isPrimitiveScalarFieldType(fieldType: string): boolean {
-  if (
-    fieldType === 'f32' ||
-    fieldType === 'f64' ||
-    fieldType === 'u32' ||
-    fieldType === 'i32' ||
-    fieldType === 'u8' ||
-    fieldType === 'i8' ||
-    fieldType === 'u16' ||
-    fieldType === 'i16' ||
-    fieldType === 'bool' ||
-    fieldType === 'string'
-  ) {
-    return true;
-  }
-  if (fieldType.startsWith('enum<')) return true;
-  return false;
-}
-
-/** Map a primitive scalar field type to the runtime `typeof` it should narrow to. */
-function primitiveJsType(fieldType: string): string {
-  if (fieldType === 'bool') return 'boolean';
-  if (fieldType === 'string') return 'string';
-  return 'number';
-}

package/src/instances/state.ts

@@ -0,0 +1,62 @@
+import type { EntityHandle, World } from '@forgeax/engine-ecs';
+import type { Handle, LocalEntityId, MountOverride } from '@forgeax/engine-types';
+
+/** Internal state retained by a SceneInstance root. */
+export interface SceneInstanceStatePayload {
+  readonly source: Handle<'SceneAsset', 'shared'>;
+  readonly sceneSourceKey?: string;
+  readonly bindings: Map<string, EntityHandle>;
+  readonly entityToLocalId: Map<EntityHandle, LocalEntityId>;
+  readonly detachedLocalIds: Set<LocalEntityId>;
+  readonly overrides: Map<
+    LocalEntityId,
+    Map<string, { readonly comp: string; readonly field?: string; readonly value: unknown }>
+  >;
+  readonly rootEntities: EntityHandle[];
+  readonly mountRoots: EntityHandle[];
+  readonly totalSlots: number;
+  readonly mountTimeOverrides: readonly MountOverride[];
+}
+
+export interface SceneWorldState {
+  resolver: unknown;
+  readonly statePayloads: Map<number, unknown>;
+}
+
+const sceneWorldStates = new WeakMap<World, SceneWorldState>();
+
+export function sceneWorldState(world: World): SceneWorldState {
+  const current = sceneWorldStates.get(world);
+  if (current !== undefined) return current;
+  const created: SceneWorldState = { resolver: null, statePayloads: new Map<number, unknown>() };
+  sceneWorldStates.set(world, created);
+  return created;
+}
+
+export function mountOverrideStateKey(ov: MountOverride): string {
+  return ov.field !== undefined ? `${ov.comp}:${ov.field}` : ov.comp;
+}
+
+export function isPrimitiveScalarFieldType(fieldType: string): boolean {
+  if (
+    fieldType === 'f32' ||
+    fieldType === 'f64' ||
+    fieldType === 'u32' ||
+    fieldType === 'i32' ||
+    fieldType === 'u8' ||
+    fieldType === 'i8' ||
+    fieldType === 'u16' ||
+    fieldType === 'i16' ||
+    fieldType === 'bool' ||
+    fieldType === 'string'
+  ) {
+    return true;
+  }
+  return fieldType.startsWith('enum<');
+}
+
+export function primitiveJsType(fieldType: string): string {
+  if (fieldType === 'bool') return 'boolean';
+  if (fieldType === 'string') return 'string';
+  return 'number';
+}

package/src/plugin.ts

@@ -4,10 +4,17 @@ import { ChildOf } from './components/child-of';
 import { Children } from './components/children';
 import { MorphWeights } from './components/morph-weights';
 import { Name } from './components/name';
-import { Transform } from './components/transform';
+import { GlobalTransform, Transform } from './components/transform';
 import { registerPropagateTransforms } from './systems/propagate-transforms';
 
-const SCENE_COMPONENTS: readonly Component[] = [ChildOf, Children, MorphWeights, Name, Transform];
+const SCENE_COMPONENTS: readonly Component[] = [
+  ChildOf,
+  Children,
+  MorphWeights,
+  Name,
+  Transform,
+  GlobalTransform,
+];
 
 function registerSceneComponents(world: World): () => void {
   const leases = SCENE_COMPONENTS.map((component) => world.components.register(component).unwrap());

package/src/systems/hierarchy-projection.ts

@@ -1,5 +1,4 @@
-import { Entity, type EntityHandle, type World } from '@forgeax/engine-ecs';
-import { createWorldProjection } from '@forgeax/engine-ecs/projection';
+import { Entity, type EntityHandle, type Query, type World } from '@forgeax/engine-ecs';
 import { ChildOf } from '../components/child-of';
 import type { SceneErrorCode, SceneErrorDetail } from '../errors';
 
@@ -17,7 +16,8 @@ export interface SceneHierarchySnapshot {
 }
 
 interface HierarchyProjectionCacheEntry {
-  readonly changes: ReturnType<typeof createWorldProjection>;
+  readonly structureEpoch: number;
+  readonly childOfChanges: Query;
   readonly snapshot: SceneHierarchySnapshot;
 }
 
@@ -30,6 +30,18 @@ interface HierarchyProjectionCacheEntry {
 // writes are internal-only and must not mutate authored hierarchy state.
 const HIERARCHY_PROJECTION_CACHE = new WeakMap<World, HierarchyProjectionCacheEntry>();
 
+function createChildOfChangeQuery(world: World): Query {
+  const result = world.query({ changed: [ChildOf] });
+  if (!result.ok) throw result.error;
+  return result.value;
+}
+
+function drainChanges(query: Query): boolean {
+  let changed = false;
+  for (const span of query.spans().unwrap()) changed ||= span.length > 0;
+  return changed;
+}
+
 function diagnostic(
   code: SceneErrorCode,
   entity: EntityHandle,
@@ -54,10 +66,12 @@ function diagnostic(
 /** Build the only World-local projection of ChildOf parent facts. */
 export function projectHierarchy(world: World): SceneHierarchySnapshot {
   const cached = HIERARCHY_PROJECTION_CACHE.get(world);
-  const changes = cached?.changes ?? createWorldProjection(world, { components: [ChildOf] });
-  if (cached !== undefined) {
-    const evidence = changes.poll();
-    if (evidence.status === 'delta' && evidence.changes.length === 0) return cached.snapshot;
+  if (
+    cached !== undefined &&
+    cached.structureEpoch === world.getStructureEpoch() &&
+    !drainChanges(cached.childOfChanges)
+  ) {
+    return cached.snapshot;
   }
   const liveEntities = new Set<EntityHandle>();
   const authoredParents = new Map<EntityHandle, EntityHandle>();
@@ -126,8 +140,11 @@ export function projectHierarchy(world: World): SceneHierarchySnapshot {
       return stableParentOf.get(entity);
     },
   };
+  const childOfChanges = createChildOfChangeQuery(world);
+  drainChanges(childOfChanges);
   HIERARCHY_PROJECTION_CACHE.set(world, {
-    changes,
+    structureEpoch: world.getStructureEpoch(),
+    childOfChanges,
     snapshot,
   });
   return snapshot;

package/src/systems/index.ts

@@ -4,8 +4,11 @@ export {
   type SceneHierarchySnapshot,
 } from './hierarchy-projection';
 export {
+  PROPAGATE_TRANSFORMS_FIXED_SYSTEM,
   PROPAGATE_TRANSFORMS_SYSTEM,
+  PropagateTransformsFixed,
   propagateTransforms,
   registerPropagateTransforms,
+  TransformFixedSet,
   TransformSet,
 } from './propagate-transforms';