@forgeax/engine-scene 0.1.20 → 0.1.23

package/src/assets/scene-decoder.ts

@@ -110,7 +110,11 @@ function resolveSceneWireRefs(payload: SceneAsset, refs: readonly string[]): Sce
       // component registry.
       components[componentName] = { ...(rawFields as Record<string, unknown>) };
     }
-    entities.push({ localId: entity.localId, components });
+    entities.push({
+      localId: entity.localId,
+      ...(entity.bindingKey === undefined ? {} : { bindingKey: entity.bindingKey }),
+      components,
+    });
   }
 
   const mounts = resolveMounts(payload.mounts, refs);
@@ -125,6 +129,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 }),

package/src/components/child-of.ts

@@ -64,24 +64,31 @@ export { ChildOf } from './children';
  *
  * Store the parent `Entity` handle (returned by `world.spawn(...).unwrap()`)
  * in the `parent` field; `propagateTransforms` reads it each frame to
- * compose the child's derived `Transform.world` mat4 (child.world =
- * parent.world x child local). Despawning a child auto-detaches it from the
+ * compose the child's derived `GlobalTransform.world` mat4 (child.world =
+ * parent.world x child local). `Transform` declares `GlobalTransform` as a
+ * generic ECS requirement, so normal spawn/add/command paths materialize the
+ * pair without scene-specific repair. Propagation still fails closed when an
+ * owner explicitly removes one half. Despawning a child auto-detaches it from the
  * parent's Children list (relationship `onRemove` hook). Despawning the
  * parent does not auto-clean the child's ChildOf; the consumer removes the
  * stale ChildOf (`world.removeComponent`) or checks `world.get(parent, Entity)` for liveness.
  *
- * Because ChildOf declares a `relationship` mirror, the engine keeps the
- * parent's `Children.entities` reverse list consistent automatically: adding
- * ChildOf appends the child to the parent's Children, removing it (or
- * reparenting via the `exclusive` arm) prunes the stale entry. AI users no
- * longer hand-maintain both sides (the prior OOS-10 contract is retired).
+ * Because ChildOf declares a `relationship` mirror and a structural
+ * `Transform` requirement, the engine keeps the parent's `Children.entities`
+ * reverse list consistent automatically and materializes the local/world pair
+ * when the child did not author one: adding ChildOf appends the child to the
+ * parent's Children, removing it (or reparenting via the `exclusive` arm)
+ * prunes the stale entry. AI users no longer hand-maintain both sides (the
+ * prior OOS-10 contract is retired).
  * Reparenting is a plain re-add: `world.addComponent(child, { component:
  * ChildOf, data: { parent: newParent } })` on an entity that already carries
  * ChildOf auto-reparents (exclusive arm), or use `world.reparent(child,
  * newParent)`.
  *
  * @example Spawn a child entity referencing an already-spawned root:
- *   const root = world.spawn({ component: Transform, data: {...} }).unwrap();
+ *   const root = world.spawn(
+ *     { component: Transform, data: {...} },
+ *   ).unwrap();
  *   const child = world.spawn(
  *     { component: Transform, data: {...} },
  *     { component: ChildOf, data: { parent: root } },

package/src/components/children.ts

@@ -60,6 +60,7 @@
 // generic relationship-mirror shape, not a ChildOf special case).
 
 import { defineRelationship } from '@forgeax/engine-ecs';
+import { Transform } from './transform';
 
 /**
  * Hierarchy forward-list of child entities.
@@ -108,6 +109,11 @@ export const { source: ChildOf, target: Children } = defineRelationship({
   sourceField: 'parent',
   targetName: 'Children',
   targetField: 'entities',
+  // Every scene hierarchy node is spatial.  Adding ChildOf therefore
+  // materializes the local/derived transform pair at the same structural
+  // boundary, so render- and scene-authored children cannot enter a frame
+  // with an incomplete hierarchy node.
+  sourceRequires: [Transform],
   exclusive: true,
   linkedSpawn: true,
 });

package/src/components/transform.ts

@@ -1,89 +1,31 @@
-// @forgeax/engine-runtime - Transform (local TRS + world mat4).
-//
-// Schema: three local array<f32, N> columns -- pos (3-vec position), quat
-// (4-quat rotation, component order [x, y, z, w]), scale (3-vec scale) --
-// plus one `world: array<f32, 16>` field carrying the resolved world-space
-// mat4 (column-major 16 floats, written by the propagate kernel each frame).
-// Inline stride-N array columns (feat-20260602) store each row's N floats
-// contiguously, so per-row xyz locality is native to the column layout; the
-// former per-axis scalar decomposition (10 f32 columns) predates
-// inline array columns and was retired in feat-20260709 M2.
-//
-// The world column is the SSOT for the resolved world transform: a root's
-// world equals its local mat4; a child's world equals parent.world x local.
-// AI users author the local TRS arrays and read the derived world mat4 via
-// the ECS column-level array view (`world.get(e, Transform).world` -> live
-// Float32Array of 16 column-major floats). They MUST NOT hand-write the
-// world column -- it is overwritten by propagate.
-//
-// charter mapping: P1 (progressive disclosure via defaults map -- AI users
-// spawn with data: {} and get identity local TRS + identity world mat4),
-// F1 (context-limited: single-import barrel; 3 array keys replace 10 scalar
-// keys at every spawn call-site), P4 (consistent abstraction: pos / quat /
-// scale array columns follow the same access pattern as `world` -- learn
-// the flat column form once, apply it to every array<f32, N> field),
-// P3 (machine-readable schema > prose).
+// @forgeax/engine-runtime - authored local transform and derived world output.
 
 import { defineComponent } from '@forgeax/engine-ecs';
 
-// Column-major identity mat4 (16 floats) used as the world-column default so
-// `spawn({ component: Transform, data: {} })` lands an identity world view
-// before the first propagate pass writes the resolved transform.
 const IDENTITY_MAT4 = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
 
+/** Scene-owned derived world transform. Only TransformPropagation writes it. */
+export const GlobalTransform = defineComponent(
+  'GlobalTransform',
+  {
+    world: { type: 'array<f32, 16>', default: IDENTITY_MAT4 },
+  },
+  { transient: true },
+);
+
 /**
- * Transform: local position `pos` (xyz), rotation `quat` (quaternion,
- * component order [x, y, z, w]), scale `scale` (xyz), plus the resolved
- * `world` mat4 (column-major 16 floats).
- *
- * Local TRS is stored as three inline stride-N array<f32, N> columns. The
- * propagate kernel composes each entity's local TRS into a mat4 and writes it
- * into the `world` column (root: world = local; child: world = parent.world x
- * local) using `@forgeax/engine-math` mat4 / vec3 / quat APIs (charter P4: do
- * not reinvent math). MVP recomposes every frame; dirty-flag optimization is
- * owned by feat-future-render-world.
- *
- * The `world` column is a fixed-capacity `array<f32, 16>` (feat-20260602):
- * the 16 contiguous floats live inline in a stride-16 column -- no BufferPool
- * slot. Read it via `world.get(e, Transform).world` which returns a live
- * `Float32Array` aliasing the column buffer. The view is transient: it aliases
- * the archetype column buffer and is valid only until the next structural
- * change (spawn / despawn / addComponent / removeComponent). Re-fetch the view
- * on every access; holding a view across a structural change is undefined
- * behaviour (the backing `ArrayBuffer` is detached on column growth, and
- * swap-remove at the same row index points to the wrong entity). All existing
- * hot paths (propagate / render-extract / pick) already comply -- see
- * `packages/ecs/README.md` Transient view contract section.
- *
- * All three local columns carry explicit layer-2 defaults (identity
- * transform): `pos: [0, 0, 0]`, `quat: [0, 0, 0, 1]` (identity quaternion,
- * [x, y, z, w]), `scale: [1, 1, 1]`. quat and scale MUST stay explicit: the
- * layer-3 fallback for array<f32, N> is all-zero, which would land an invalid
- * zero quaternion / zero scale. The `world` field defaults to the identity
- * mat4. AI users spawn with `data: {}` or with only the fields they need to
- * override.
- *
- * @example Minimal spawn (local defaulted to identity, world = identity mat4):
- *   world.spawn({ component: Transform, data: {} });
- *
- * @example Override only the position, leaving rotation/scale at identity:
- *   world.spawn({ component: Transform, data: { pos: [0, 6, 0] } });
+ * Authored local position, rotation and scale columns.
  *
- * @example Full explicit local form (defaults are opt-in):
- *   world.spawn({ component: Transform, data: {
- *     pos: [1, 2, 3],
- *     quat: [0, 0, 0, 1], // [x, y, z, w]
- *     scale: [1, 1, 1],
- *   } });
+ * The ECS `requires` declaration is the generic structural invariant: callers
+ * add `Transform`, while `GlobalTransform` is materialized once at spawn/add.
  */
-export const Transform = defineComponent('Transform', {
-  pos: { type: 'array<f32, 3>', default: new Float32Array([0, 0, 0]) },
-  // Component order [x, y, z, w] end to end (glTF-aligned; E6).
-  quat: { type: 'array<f32, 4>', default: new Float32Array([0, 0, 0, 1]) },
-  scale: { type: 'array<f32, 3>', default: new Float32Array([1, 1, 1]) },
-  // `world` is field-level transient (D-5): scene collect skips it. The resolved
-  // world mat4 is derived by the propagate kernel from the persisted local TRS
-  // each frame, so serializing it would store reconstructable data (SSOT: local
-  // TRS). Round-trip re-derives an equivalent world on the first propagate pass.
-  world: { type: 'array<f32, 16>', default: IDENTITY_MAT4, transient: true },
-});
+export const Transform = defineComponent(
+  'Transform',
+  {
+    pos: { type: 'array<f32, 3>', default: new Float32Array([0, 0, 0]) },
+    // Component order [x, y, z, w] is shared with glTF.
+    quat: { type: 'array<f32, 4>', default: new Float32Array([0, 0, 0, 1]) },
+    scale: { type: 'array<f32, 3>', default: new Float32Array([1, 1, 1]) },
+  },
+  { requires: [GlobalTransform] },
+);

package/src/errors.ts

@@ -1,4 +1,4 @@
-import type { EntityHandle } from '@forgeax/engine-ecs';
+import type { EcsError, EntityHandle } from '@forgeax/engine-ecs';
 
 export type SceneErrorCode = 'hierarchy-broken' | 'hierarchy-cycle';
 
@@ -7,11 +7,35 @@ export type SceneInstanceErrorCode = 'component-not-defined' | 'scene-override-t
 
 export { ComponentNotDefinedError } from '@forgeax/engine-ecs/projection';
 
-export interface SceneErrorDetail {
+/** The structured ECS failure retained by a Scene derived-write diagnostic. */
+export interface SceneErrorCause {
+  readonly code: EcsError['code'];
+  readonly expected?: string;
+  readonly hint?: string;
+  readonly detail?: unknown;
+}
+
+/** Location detail shared by hierarchy diagnostics and derived-write errors. */
+export interface SceneHierarchyErrorDetail {
+  readonly kind?: 'hierarchy';
   readonly entity: EntityHandle;
   readonly parent: EntityHandle;
 }
 
+/** A flat derived publication failure with its original ECS error intact. */
+export interface SceneDerivedWriteErrorDetail {
+  readonly kind: 'derived-write';
+  readonly entity: EntityHandle;
+  readonly parent: EntityHandle;
+  readonly bindingIndex: number;
+  readonly base: number;
+  readonly start: number;
+  readonly count: number;
+  readonly cause: SceneErrorCause;
+}
+
+export type SceneErrorDetail = SceneHierarchyErrorDetail | SceneDerivedWriteErrorDetail;
+
 export class SceneError extends Error {
   readonly code: SceneErrorCode;
   readonly expected: string;

package/src/index.ts

@@ -4,13 +4,21 @@ export { ChildOf } from './components/child-of';
 export { Children } from './components/children';
 export { MorphWeights } from './components/morph-weights';
 export { Name } from './components/name';
-export { Transform } from './components/transform';
+export { GlobalTransform, Transform } from './components/transform';
 export {
   ComponentNotDefinedError,
   SceneError,
   type SceneErrorCode,
   type SceneInstanceErrorCode,
 } from './errors';
+export {
+  resolveSceneEntity,
+  type SceneBindingDeclarationError,
+  type SceneBindingError,
+  type SceneEntityRef,
+  sceneEntity,
+  validateSceneBindings,
+} from './instances/binding';
 export { SCENE_COLLECT_PROFILE, type SceneCollectProfile } from './instances/collect-profile';
 export {
   type ExternalizedSceneAsset,
@@ -44,6 +52,7 @@ export {
   worldRemoveSceneOverride,
   worldResolveMountSource,
   worldResolveSceneAsset,
+  worldResolveSceneEntity,
   worldResolveSceneInstanceStatePayload,
   worldSetSceneAssetResolver,
   worldSetSceneOverride,

package/src/instances/binding.ts

@@ -0,0 +1,77 @@
+import type { EntityHandle } from '@forgeax/engine-ecs';
+import type { SceneEntityRef } from '@forgeax/engine-types';
+import { err, ok, type Result } from '@forgeax/engine-types';
+
+export type { SceneEntityRef } from '@forgeax/engine-types';
+
+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 };
+};
+
+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 };
+};
+
+export function validateSceneBindings(
+  sceneSourceKey: string,
+  bindingKeys: readonly string[],
+): Result<readonly string[], SceneBindingDeclarationError> {
+  if (sceneSourceKey.length === 0) {
+    return err({
+      code: 'scene-binding-source-missing',
+      expected: 'a non-empty scene sourceKey',
+      hint: 'declare the scene sourceKey in the author inventory',
+      detail: {},
+    });
+  }
+  const seen = new Set<string>();
+  for (const bindingKey of bindingKeys) {
+    if (bindingKey.length === 0 || seen.has(bindingKey)) {
+      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 },
+      });
+    }
+    seen.add(bindingKey);
+  }
+  return ok([...bindingKeys]);
+}
+
+export function sceneEntity(sceneSourceKey: string, bindingKey: string): SceneEntityRef {
+  return { sceneSourceKey, bindingKey };
+}
+
+export function resolveSceneEntity(
+  ref: SceneEntityRef,
+  instance: {
+    readonly sceneSourceKey: string;
+    readonly bindings: ReadonlyMap<string, EntityHandle | number>;
+  },
+): Result<EntityHandle | number, SceneBindingError> {
+  if (ref.sceneSourceKey !== instance.sceneSourceKey) {
+    return err({
+      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 },
+    });
+  }
+  const value = instance.bindings.get(ref.bindingKey);
+  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 },
+    });
+  }
+  return ok(value);
+}

package/src/instances/externalization.ts

@@ -91,7 +91,11 @@ export function externalizeSceneAsset(
         components[componentName] = fields;
       }
     }
-    return { localId: entity.localId as number, components };
+    return {
+      localId: entity.localId as number,
+      ...(entity.bindingKey === undefined ? {} : { bindingKey: entity.bindingKey }),
+      components,
+    };
   });
 
   const mounts = scene.mounts?.map((mount) => {
@@ -126,6 +130,8 @@ export function externalizeSceneAsset(
   }
   return ok({
     payload: {
+      kind: 'scene',
+      ...(scene.sourceKey === undefined ? {} : { sourceKey: scene.sourceKey }),
       entities,
       ...(mounts === undefined || mounts.length === 0 ? {} : { mounts }),
       ...(scene.skinGuids === undefined

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,
@@ -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>>
@@ -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());