@forgeax/engine-scene 0.1.2

package/dist/components/child-of.d.ts

@@ -0,0 +1,31 @@
+export { ChildOf } from './children';
+/**
+ * Hierarchy back-reference: pointer from child entity to its parent.
+ *
+ * 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
+ * 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).
+ * 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 child = world.spawn(
+ *     { component: Transform, data: {...} },
+ *     { component: ChildOf, data: { parent: root } },
+ *   ).unwrap();
+ *   // root now carries Children with [child] in its `entities` list.
+ */
+//# sourceMappingURL=child-of.d.ts.map

package/dist/components/child-of.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"child-of.d.ts","sourceRoot":"","sources":["../../src/components/child-of.ts"],"names":[],"mappings":"AA2DA,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG"}

package/dist/components/children.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Hierarchy forward-list of child entities.
+ *
+ * `entities` is a variable-length `array<entity>` field; each element is
+ * an `Entity` u32 the AI user pushed via
+ * `world.push(parent, Children, 'entities', child)`. The value returned by
+ * `world.get(parent, Children).unwrap().entities` is a read-only
+ * `Uint32Array` snapshot rematerialised fresh on every read (D-4 no-cache);
+ * the snapshot's `length` equals the live element count.
+ *
+ * Invariants:
+ *   - Children is NOT consumed by `propagateTransforms` (which walks ChildOf
+ *     upward, D-P2). The forward list is for AI-user traversal / debug /
+ *     inspection.
+ *   - Children <-> ChildOf consistency is maintained by the engine via the
+ *     ChildOf `relationship` mirror hook (see ./child-of.ts): adding /
+ *     removing / reparenting ChildOf on a child auto-updates the parent's
+ *     `entities` list. AI users do not hand-sync the two sides for the
+ *     hierarchy.
+ *   - Stored entity u32s are NOT auto-cleared when the referenced entity is
+ *     despawned (OOS-01 above); a `world.get(despawnedChild, ...)` call
+ *     returns `Result.err(...)` so AI users discover the dangling state
+ *     through the engine's structured-error channel.
+ *
+ * @example Spawn a parent and two children via ChildOf (engine maintains Children):
+ *   const parent = world.spawn({ component: Transform, data: identityXf() }).unwrap();
+ *   const a = world.spawn(
+ *     { component: Transform, data: identityXf() },
+ *     { component: ChildOf, data: { parent } },
+ *   ).unwrap();
+ *   const b = world.spawn(
+ *     { component: Transform, data: identityXf() },
+ *     { component: ChildOf, data: { parent } },
+ *   ).unwrap();
+ *   // Read back via the read-only snapshot - engine appended a, b:
+ *   const snap = world.get(parent, Children).unwrap().entities;
+ *   for (let i = 0; i < snap.length; i++) {
+ *     const child = snap[i];
+ *     // ... consume; world.get(child, ...) surfaces a structured error
+ *     // if the child has been despawned (OOS-01 dangling-entity surface).
+ *   }
+ */
+export declare const ChildOf: import("@forgeax/engine-ecs").Component<"ChildOf", {
+    parent: "entity";
+}>, Children: import("@forgeax/engine-ecs").RelationshipTargetComponent<import("@forgeax/engine-ecs").Component<"Children", {
+    entities: "array<entity>";
+}>>;
+//# sourceMappingURL=children.d.ts.map

package/dist/components/children.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"children.d.ts","sourceRoot":"","sources":["../../src/components/children.ts"],"names":[],"mappings":"AA+DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,eAAO,MAAgB,OAAO;;IAAU,QAAQ;;GAO9C,CAAC"}

package/dist/components/morph-weights.d.ts

@@ -0,0 +1,5 @@
+/** Per-entity morph weights; length is validated against the mesh target count. */
+export declare const MorphWeights: import("@forgeax/engine-ecs").Component<"MorphWeights", {
+    readonly weights: "array<f32>";
+}>;
+//# sourceMappingURL=morph-weights.d.ts.map

package/dist/components/morph-weights.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"morph-weights.d.ts","sourceRoot":"","sources":["../../src/components/morph-weights.ts"],"names":[],"mappings":"AAEA,mFAAmF;AACnF,eAAO,MAAM,YAAY;;EAEvB,CAAC"}

package/dist/components/name.d.ts

@@ -0,0 +1,4 @@
+export declare const Name: import("@forgeax/engine-ecs").Component<"Name", {
+    readonly value: "string";
+}>;
+//# sourceMappingURL=name.d.ts.map

package/dist/components/name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"name.d.ts","sourceRoot":"","sources":["../../src/components/name.ts"],"names":[],"mappings":"AAqBA,eAAO,MAAM,IAAI;;EAAyD,CAAC"}

package/dist/components/transform.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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] } });
+ *
+ * @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],
+ *   } });
+ */
+export declare const Transform: import("@forgeax/engine-ecs").Component<"Transform", {
+    readonly pos: "array<f32, 3>";
+    readonly quat: "array<f32, 4>";
+    readonly scale: "array<f32, 3>";
+    readonly world: "array<f32, 16>";
+}>;
+//# sourceMappingURL=transform.d.ts.map

package/dist/components/transform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../../src/components/transform.ts"],"names":[],"mappings":"AAiCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,eAAO,MAAM,SAAS;;;;;EAUpB,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,22 @@
+import type { EntityHandle } from '@forgeax/engine-ecs';
+export type SceneErrorCode = 'hierarchy-broken' | 'hierarchy-cycle';
+/** Scene-instantiation failures owned by the scene package. */
+export type SceneInstanceErrorCode = 'component-not-defined' | 'scene-override-type-mismatch';
+export { ComponentNotDefinedError } from '@forgeax/engine-ecs/projection';
+export interface SceneErrorDetail {
+    readonly entity: EntityHandle;
+    readonly parent: EntityHandle;
+}
+export declare class SceneError extends Error {
+    readonly code: SceneErrorCode;
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: SceneErrorDetail | undefined;
+    constructor(args: {
+        code: SceneErrorCode;
+        expected: string;
+        hint: string;
+        detail?: SceneErrorDetail;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,MAAM,MAAM,cAAc,GAAG,kBAAkB,GAAG,iBAAiB,CAAC;AAEpE,+DAA+D;AAC/D,MAAM,MAAM,sBAAsB,GAAG,uBAAuB,GAAG,8BAA8B,CAAC;AAE9F,OAAO,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAE1E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;CAC/B;AAED,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,SAAS,CAAC;gBAElC,IAAI,EAAE;QAChB,IAAI,EAAE,cAAc,CAAC;QACrB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,CAAC,EAAE,gBAAgB,CAAC;KAC3B;CAQF"}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { sceneAssetContribution, sceneAssetDecoder, sceneAssetKind, } from './assets/scene-decoder';
+export { projectSceneAsset, SCENE_ASSET_MESH_DEFAULT_RESOLVER_RESOURCE_KEY, SCENE_ASSET_SKIN_RESOLVER_RESOURCE_KEY, type SceneAssetMeshDefaultResolver, type SceneAssetProjectionError, type SceneAssetReferenceLoader, type SceneAssetSkinResolver, } from './assets/scene-projection';
+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 { ComponentNotDefinedError, SceneError, type SceneErrorCode, type SceneInstanceErrorCode, } from './errors';
+export { SCENE_COLLECT_PROFILE, type SceneCollectProfile } from './instances/collect-profile';
+export { type ExternalizedSceneAsset, externalizeSceneAsset, type SceneComponentSchemaResolver, type SceneExternalizationError, } from './instances/externalization';
+export { type SceneAssetResolver, type SceneInstanceStatePayload, type SceneInstantiateDiagnostic, type SceneInstantiateFlatOk, type SceneInstantiateHook, type SceneInstantiateOk, type SceneMembersSpawn, worldApplyMountOverride, worldBuildSceneEntityComponentDatas, worldDespawnDescendants, worldDespawnScene, worldDetachSceneMember, worldGetSceneAssetForInstance, worldGetSceneAssetResolver, worldGetSceneInstanceState, worldInstantiateScene, worldInstantiateSceneAsset, worldInstantiateSceneAssetFlat, worldInstantiateSceneFlat, worldInstantiateSceneRec, worldMountOverridesToStateMap, worldReattachSceneMember, worldRemoveSceneOverride, worldResolveMountSource, worldResolveSceneAsset, worldResolveSceneInstanceStatePayload, worldSetSceneAssetResolver, worldSetSceneInstantiateHook, worldSetSceneOverride, worldSpawnMountEntity, worldSpawnSceneMembers, worldValidateMountOverrides, } from './instances/scene-instances';
+export { scenePlugin } from './plugin';
+export { projectHierarchy, type SceneHierarchyDiagnostic, type SceneHierarchySnapshot, } from './systems/hierarchy-projection';
+export { PROPAGATE_TRANSFORMS_SYSTEM, propagateTransforms, registerPropagateTransforms, TransformSet, } from './systems/propagate-transforms';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,cAAc,GACf,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,iBAAiB,EACjB,8CAA8C,EAC9C,sCAAsC,EACtC,KAAK,6BAA6B,EAClC,KAAK,yBAAyB,EAC9B,KAAK,yBAAyB,EAC9B,KAAK,sBAAsB,GAC5B,MAAM,2BAA2B,CAAC;AACnC,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,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EACL,wBAAwB,EACxB,UAAU,EACV,KAAK,cAAc,EACnB,KAAK,sBAAsB,GAC5B,MAAM,UAAU,CAAC;AAClB,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,oBAAoB,EACzB,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,wBAAwB,EACxB,6BAA6B,EAC7B,wBAAwB,EACxB,wBAAwB,EACxB,uBAAuB,EACvB,sBAAsB,EACtB,qCAAqC,EACrC,0BAA0B,EAC1B,4BAA4B,EAC5B,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"}