@forgeax/engine-scene 0.1.28 → 0.1.30

package/README.md

@@ -25,6 +25,56 @@ branch on `error.code` and repair a diagnosable stale edge, mirror mismatch, or
 cycle through `World.set`/`World.removeComponent` (or the owning structural
 command) before retrying while the World is healthy.
 
+## Keyed SceneAsset authoring
+
+`SceneAsset` is authored as ordinary data. The key in `entities` is the only
+persistent local identity; runtime numeric slots and mount windows are derived
+inside this package and never belong in source files.
+
+```ts
+const level: SceneAsset = {
+  kind: 'scene',
+  entities: {
+    root: { components: { Transform: {} } },
+    house: {
+      components: { ChildOf: { parent: 'root' } },
+      instance: {
+        source: houseSceneGuid,
+        overrides: [{ target: ['door'], components: { Name: { value: 'front-door' } } }],
+      },
+    },
+  },
+};
+```
+
+| Source value | Meaning |
+|:--|:--|
+| `'root'` | Entity in the current scene |
+| `['house', 'door']` | Entity `door` inside instance `house`; every segment is a key |
+| `sceneEntity(guid, address)` | Reference bound to one catalog identity and address |
+| `sceneEntity('', address)` | Reference to an anonymous direct POD scene |
+
+> [!IMPORTANT]
+> Unknown components, unknown fields, missing targets, hierarchy cycles, and
+> recursive instance graphs fail before entity creation. A direct POD scene has
+> no persistent source identity; choose a Pack output key before saving it.
+
+### Publication fence for loaded scenes
+
+Catalog-loaded scenes carry their publication evidence in the producer/loading
+context, not in the authored `instance` declaration. Acquire the current fence
+from that context, then pass it to
+`AssetRegistry.instantiateWithPublicationFence` or
+`instantiateFlatWithPublicationFence`; the call compares the complete tuple:
+source path and revision, generation, package digest, output-set digest, and
+receipt identity. Ordinary `instantiate`/`instantiateFlat` still validate every
+nested scene output against the parent publication before spawning. A missing or
+mismatched tuple returns `asset-generation-fence-mismatch` with `expected`,
+`actual`, `currentGeneration`, `lastKnownGood`, and recovery actions; repair or
+recook the producer, then open the current publication and retry. Direct
+anonymous POD scenes have no Catalog fence and remain addressable only for their
+current in-memory instance; saving one requires an explicit Pack/output key.
+
 When the plugin runs from the scheduled path, `world.update(deltaSeconds)`
 wraps a thrown Scene failure as `system-failed`; the wrapper's
 `error.detail.cause` is the original `SceneError` (including its structured

package/dist/__tests__/keyed-scene.integration.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=keyed-scene.integration.test.d.ts.map

package/dist/__tests__/keyed-scene.integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyed-scene.integration.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/keyed-scene.integration.test.ts"],"names":[],"mappings":""}

package/dist/assets/scene-decoder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scene-decoder.d.ts","sourceRoot":"","sources":["../../src/assets/scene-decoder.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,wBAAwB,EAC7B,KAAK,SAAS,EAKd,KAAK,UAAU,EAGhB,MAAM,uBAAuB,CAAC;AAE/B,eAAO,MAAM,cAAc,EAAE,SAAS,CAAC,UAAU,EAAE,OAAO,CAEvB,CAAC;AAqBpC,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAEnF;AAoGD,qFAAqF;AACrF,eAAO,MAAM,iBAAiB,EAAE,YAAY,CAAC,UAAU,CAWtD,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,wBAAwB,CAAC,UAAU,EAAE,OAAO,CAIhF,CAAC"}
+{"version":3,"file":"scene-decoder.d.ts","sourceRoot":"","sources":["../../src/assets/scene-decoder.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,wBAAwB,EAC7B,KAAK,SAAS,EAKd,KAAK,UAAU,EAGhB,MAAM,uBAAuB,CAAC;AAG/B,eAAO,MAAM,cAAc,EAAE,SAAS,CAAC,UAAU,EAAE,OAAO,CAEvB,CAAC;AAqBpC,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAEnF;AAyLD,qFAAqF;AACrF,eAAO,MAAM,iBAAiB,EAAE,YAAY,CAAC,UAAU,CAetD,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,wBAAwB,CAAC,UAAU,EAAE,OAAO,CAIhF,CAAC"}

package/dist/index.d.ts

@@ -6,9 +6,11 @@ export { MorphWeights } from './components/morph-weights';
 export { Name } from './components/name';
 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 { resolveSceneEntity, type SceneBindingDeclarationError, type SceneBindingError, type SceneEntityRef, sceneEntity, sceneEntityAddressKey, validateSceneEntityKeys, } from './instances/binding';
 export { SCENE_COLLECT_PROFILE, type SceneCollectProfile } from './instances/collect-profile';
 export { type ExternalizedSceneAsset, externalizeSceneAsset, 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, type SceneInstantiateDiagnostic, type SceneInstantiateFlatOk, type SceneInstantiateOk, type SceneMembersSpawn, worldApplyMountOverride, worldBuildSceneEntityComponentDatas, worldDespawnDescendants, worldDespawnScene, worldDetachSceneMember, worldGetSceneAssetForInstance, worldGetSceneAssetResolver, worldGetSceneInstanceState, worldInstantiateScene, worldInstantiateSceneAsset, worldInstantiateSceneAssetFlat, worldInstantiateSceneFlat, worldInstantiateScenePayload, worldInstantiateSceneRec, worldMountOverridesToStateMap, worldReattachSceneMember, worldRemoveSceneOverride, worldResolveMountSource, worldResolveSceneAsset, worldResolveSceneEntity, worldResolveSceneInstanceStatePayload, worldSetSceneAssetResolver, worldSetSceneOverride, worldSpawnMountEntity, worldSpawnSceneMembers, worldValidateMountOverrides, } from './instances/scene-instances';
 export { scenePlugin } from './plugin';
 export { projectHierarchy, type SceneHierarchyDiagnostic, type SceneHierarchySnapshot, } from './systems/hierarchy-projection';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACpE,OAAO,EACL,wBAAwB,EACxB,UAAU,EACV,KAAK,cAAc,EACnB,KAAK,sBAAsB,GAC5B,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,kBAAkB,EAClB,KAAK,4BAA4B,EACjC,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,WAAW,EACX,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,qBAAqB,EAAE,KAAK,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAC9F,OAAO,EACL,KAAK,sBAAsB,EAC3B,qBAAqB,EACrB,KAAK,4BAA4B,EACjC,KAAK,yBAAyB,GAC/B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,uBAAuB,EACvB,mCAAmC,EACnC,uBAAuB,EACvB,iBAAiB,EACjB,sBAAsB,EACtB,6BAA6B,EAC7B,0BAA0B,EAC1B,0BAA0B,EAC1B,qBAAqB,EACrB,0BAA0B,EAC1B,8BAA8B,EAC9B,yBAAyB,EACzB,4BAA4B,EAC5B,wBAAwB,EACxB,6BAA6B,EAC7B,wBAAwB,EACxB,wBAAwB,EACxB,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACvB,qCAAqC,EACrC,0BAA0B,EAC1B,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACtB,2BAA2B,GAC5B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EACL,gBAAgB,EAChB,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,GAC5B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,2BAA2B,EAC3B,YAAY,GACb,MAAM,gCAAgC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACpE,OAAO,EACL,wBAAwB,EACxB,UAAU,EACV,KAAK,cAAc,EACnB,KAAK,sBAAsB,GAC5B,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,kBAAkB,EAClB,KAAK,4BAA4B,EACjC,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,WAAW,EACX,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,qBAAqB,EAAE,KAAK,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAC9F,OAAO,EACL,KAAK,sBAAsB,EAC3B,qBAAqB,EACrB,KAAK,4BAA4B,EACjC,KAAK,yBAAyB,GAC/B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,sBAAsB,EACtB,KAAK,wBAAwB,GAC9B,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACnF,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,uBAAuB,EACvB,mCAAmC,EACnC,uBAAuB,EACvB,iBAAiB,EACjB,sBAAsB,EACtB,6BAA6B,EAC7B,0BAA0B,EAC1B,0BAA0B,EAC1B,qBAAqB,EACrB,0BAA0B,EAC1B,8BAA8B,EAC9B,yBAAyB,EACzB,4BAA4B,EAC5B,wBAAwB,EACxB,6BAA6B,EAC7B,wBAAwB,EACxB,wBAAwB,EACxB,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACvB,qCAAqC,EACrC,0BAA0B,EAC1B,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACtB,2BAA2B,GAC5B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EACL,gBAAgB,EAChB,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,GAC5B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,2BAA2B,EAC3B,YAAY,GACb,MAAM,gCAAgC,CAAC"}