@forgeax/engine-gltf 0.1.28 → 0.1.30

package/src/animated-bounds.ts

@@ -0,0 +1,94 @@
+import {
+  type AnimatedBoundsMesh,
+  deriveConservativeAnimatedBounds,
+} from '@forgeax/engine-animation/animated-bounds';
+import { buildNodeParentMap, resolveNamedNodePath } from './node-path';
+import type { GltfDoc } from './parse-gltf';
+
+/** Source extras and sidecar bounds have already been applied before this producer runs. */
+export function deriveGltfAnimatedBounds(doc: GltfDoc): GltfDoc {
+  const parents = buildNodeParentMap(doc.nodes);
+  const paths = doc.nodes.map((_, index) => {
+    const path = resolveNamedNodePath(doc.nodes, parents, index);
+    return path.ok ? path.value.join('/') : undefined;
+  });
+  const nodes = doc.nodes.map((node, index) => ({
+    ...node.transform,
+    parent: parents.get(index) ?? null,
+  }));
+  const channels = doc.animationClips.flatMap((clip) =>
+    clip.channels.flatMap((channel) =>
+      channel.property === 'weights'
+        ? []
+        : [
+            {
+              node: channel.targetNodeIndex,
+              property: channel.property,
+              values: channel.sampler.output,
+              interpolation: channel.sampler.interpolation,
+            },
+          ],
+    ),
+  );
+  const primitiveStarts: number[] = [];
+  let offset = 0;
+  for (const count of doc.meshPrimitiveCount?.values() ?? doc.meshes.map(() => 1)) {
+    primitiveStarts.push(offset);
+    offset += count;
+  }
+  const skeletons = doc.skeletons.map((skeleton, skinIndex) => {
+    if (skeleton.bounds !== undefined) return skeleton;
+    const meshes: AnimatedBoundsMesh[] = [];
+    for (let index = 0; index < doc.nodes.length; index++) {
+      const node = doc.nodes[index];
+      if (node === undefined) return skeleton;
+      if (node.skinIndex !== skinIndex || node.meshIndex === null) continue;
+      const start = primitiveStarts[node.meshIndex];
+      if (start === undefined) return skeleton;
+      for (const mesh of doc.meshes.slice(
+        start,
+        start + (doc.meshPrimitiveCount?.get(node.meshIndex) ?? 1),
+      )) {
+        if (mesh.joints0 === undefined || mesh.weights0 === undefined) return skeleton;
+        let maxMorphWeight = Math.max(
+          0,
+          ...Array.from(node.morphWeights ?? mesh.morphWeights ?? [], Math.abs),
+        );
+        for (const clip of doc.animationClips)
+          for (const channel of clip.channels)
+            if (channel.targetNodeIndex === index && channel.property === 'weights')
+              for (const weight of channel.sampler.output)
+                maxMorphWeight = Math.max(maxMorphWeight, Math.abs(weight));
+        const morphExtent = Float32Array.from(mesh.positions, (_, component) =>
+          (mesh.morphTargets ?? []).reduce(
+            (sum, target) => sum + Math.abs(target.position?.[component] ?? 0) * maxMorphWeight,
+            0,
+          ),
+        );
+        meshes.push({
+          node: index,
+          positions: mesh.positions,
+          joints: mesh.joints0,
+          weights: mesh.weights0,
+          morphExtent,
+        });
+      }
+    }
+    const jointNodes = skeleton.jointPaths.map((path) => paths.indexOf(path));
+    if (
+      jointNodes.some(
+        (node, index) => node < 0 || paths.lastIndexOf(skeleton.jointPaths[index]) !== node,
+      )
+    )
+      return skeleton;
+    const bounds = deriveConservativeAnimatedBounds({
+      nodes,
+      channels,
+      jointNodes,
+      inverseBindMatrices: skeleton.inverseBindMatrices,
+      meshes,
+    });
+    return bounds === undefined ? skeleton : { ...skeleton, bounds };
+  });
+  return { ...doc, skeletons };
+}

package/src/bridge.ts

@@ -36,7 +36,6 @@ import type {
   RenderQueue,
   Result,
   SceneAsset,
-  SceneEntity,
   Submesh,
   VertexAttributeMap,
 } from '@forgeax/engine-types';
@@ -459,6 +458,13 @@ export interface GltfBridgeContext {
    * matching SkinAsset.jointPaths against the spawn subtree to fill Skin.joints[].
    */
   readonly skeletonGuidBySkinIndex?: ReadonlyMap<number, string>;
+  /**
+   * glTF node index -> a live renderer-owned instance collection identity.
+   * The bridge is intentionally pure and cannot mint collection ids or copy
+   * matrix bytes into ECS. Runtime consumers create collections through their
+   * Renderer first, then provide this map when lowering the SceneAsset.
+   */
+  readonly instanceCollectionIdsByNodeIndex?: ReadonlyMap<number, number>;
 }
 
 interface MutableSceneEntity {
@@ -547,7 +553,7 @@ function composeMat4(
 export function gltfDocToSceneAsset(doc: GltfDoc, ctx: GltfBridgeContext): SceneAsset {
   const sceneIr = doc.scenes[doc.defaultSceneIndex];
   const resultNodes: MutableSceneEntity[] = [];
-  if (sceneIr === undefined) return { kind: 'scene', entities: [] };
+  if (sceneIr === undefined) return { kind: 'scene', entities: {} } as unknown as SceneAsset;
   const importedLights = doc.lights ?? doc.extensions?.KHR_lights_punctual?.lights ?? [];
   const animationTargetIds = new Map<number, string>();
   for (const clip of doc.animationClips) {
@@ -705,9 +711,16 @@ export function gltfDocToSceneAsset(doc: GltfDoc, ctx: GltfBridgeContext): Scene
       components.MeshRenderer = { materials: [] };
     }
 
-    // Instances on the same entity as MeshFilter/MeshRenderer.
+    // Instances on the same entity as MeshFilter/MeshRenderer. The bridge
+    // only carries the renderer-owned identity; IR matrix bytes stay in the
+    // caller's collection and never become an ECS managed array. Build-time
+    // consumers that do not have a Renderer omit this optional association and
+    // must materialise the collection at their runtime boundary.
     if (ir.instancing !== undefined) {
-      components.Instances = { transforms: ir.instancing.transforms };
+      const collectionId = ctx.instanceCollectionIdsByNodeIndex?.get(gltfNodeIdx);
+      if (collectionId !== undefined) {
+        components.Instances = { collectionId };
+      }
     }
 
     if (isCamera) {
@@ -751,10 +764,21 @@ export function gltfDocToSceneAsset(doc: GltfDoc, ctx: GltfBridgeContext): Scene
 
   for (const rootIdx of sceneIr.nodes) visit(rootIdx, null);
 
-  const frozen: SceneEntity[] = resultNodes.map((n) => ({
-    localId: n.localId,
-    components: n.components,
-  }));
+  const keyByLocalId = new Map<number, string>();
+  for (const node of resultNodes) keyByLocalId.set(node.localIdx, `node-${node.localIdx}`);
+  const entities: Record<string, { readonly components: Record<string, Record<string, unknown>> }> =
+    {};
+  for (const node of resultNodes) {
+    const components = { ...node.components };
+    const childOf = components.ChildOf;
+    if (childOf !== undefined && typeof childOf.parent === 'number') {
+      const parentKey = keyByLocalId.get(childOf.parent);
+      if (parentKey === undefined)
+        throw new Error(`gltfDocToSceneAsset: missing parent node ${childOf.parent}`);
+      components.ChildOf = { ...childOf, parent: parentKey };
+    }
+    entities[`node-${node.localIdx}`] = { components };
+  }
   const lightFacts = importedLights.map((light) => ({
     kind: light.type,
     intensity: light.intensity,
@@ -763,9 +787,9 @@ export function gltfDocToSceneAsset(doc: GltfDoc, ctx: GltfBridgeContext): Scene
   }));
   return {
     kind: 'scene',
-    entities: frozen,
+    entities,
     ...(lightFacts.length === 0 ? {} : { lights: lightFacts }),
-  } as SceneAsset;
+  } as unknown as SceneAsset;
 }
 
 /** Internal helper: mark GltfNodeIr usable so future surface evolutions stay typed. */

package/src/gltf-importer.ts

@@ -51,10 +51,12 @@ import type {
 import {
   IMPORT_ERROR_HINTS,
   ImportError,
+  readConservativeAnimatedBounds,
   reconcileMeshMaterialSlotTopology,
   resolveMeshMaterialSlotDefaultGuid,
   toShared,
 } from '@forgeax/engine-types';
+import { deriveGltfAnimatedBounds } from './animated-bounds';
 import {
   gltfDocToSceneAsset,
   meshIrToMeshAsset,
@@ -72,7 +74,6 @@ import { parseGlbForImporter, parseGltfForImporter } from './parse-gltf.js';
 type ParseDocResult =
   | { readonly ok: true; readonly value: GltfDoc }
   | { readonly ok: false; readonly error: ImportError };
-
 function isGlbBytes(source: string): boolean {
   return source.toLowerCase().endsWith('.glb');
 }
@@ -83,6 +84,23 @@ function publishesCatalogProduct(input: {
   return input.importSettings.geometry !== 'procedural';
 }
 
+function applyImportSettingsBounds(
+  doc: GltfDoc,
+  importSettings: Readonly<Record<string, unknown>>,
+): GltfDoc {
+  let changed = false;
+  const skeletons = doc.skeletons.map((record, sourceIndex) => {
+    // Source extras are the primary producer path. The sidecar row is an
+    // explicit external-producer override for sources whose authoring tool
+    // cannot carry ForgeaX extras; neither path derives a bind-pose AABB.
+    const bounds = readConservativeAnimatedBounds(importSettings, sourceIndex);
+    if (bounds === undefined || record.bounds !== undefined) return record;
+    changed = true;
+    return { ...record, bounds };
+  });
+  return changed ? { ...doc, skeletons } : doc;
+}
+
 function previousMaterialSlotTopology(
   ctx: ImportContext,
   meshSourceKey: string | undefined,
@@ -527,7 +545,7 @@ async function importGltf(
   }
   const parsed = await parseDoc(ctx.source, read.value, ctx, meshopt);
   if (!parsed.ok) return parsed;
-  const doc = parsed.value;
+  const doc = deriveGltfAnimatedBounds(applyImportSettingsBounds(parsed.value, ctx.importSettings));
   const maps = buildHandleMaps(ctx.subAssets, doc);
 
   // Pre-derive each images[] row's colorSpace from material slot bindings
@@ -921,30 +939,30 @@ async function importGltf(
       // SkinAsset.jointPaths.
       //
       // D-2 / D-3: refs carries structured edge metadata (AssetRef[]).
-      // Walk scene entities to build a handle-value -> (entityLocalId,
+      // Walk keyed scene entities to build a handle-value -> (entityKey,
       // componentName, fieldName, arrayIndex?) provenance map, then
-      // produce AssetRef[] with sourceField / sceneEntityId filled for mesh
+      // produce AssetRef[] with sourceField / sceneEntityKey filled for mesh
       // handle-field edges. Skeleton edges: sourceField from Skin.skeleton if entity
       // carries that GUID. Skin edges: sourceField=undefined (cross-edge
       // with no entity-component representation).
       const handleValueProvenance = new Map<
         number,
-        { sceneEntityId: number; componentName: string; fieldName: string; arrayIndex?: number }
+        { sceneEntityKey: string; componentName: string; fieldName: string; arrayIndex?: number }
       >();
-      const skeletonGuidProvenance = new Map<string, { sceneEntityId: number }>();
-      for (const entity of scene.entities) {
+      const skeletonGuidProvenance = new Map<string, { sceneEntityKey: string }>();
+      for (const [sceneEntityKey, entity] of Object.entries(scene.entities)) {
         const comps = entity.components as Record<string, Record<string, unknown>>;
         const mf = comps.MeshFilter;
         if (mf !== undefined && typeof mf.assetHandle === 'number') {
           handleValueProvenance.set(mf.assetHandle, {
-            sceneEntityId: entity.localId,
+            sceneEntityKey,
             componentName: 'MeshFilter',
             fieldName: 'assetHandle',
           });
         }
         const skin = comps.Skin;
         if (skin !== undefined && typeof skin.skeleton === 'string') {
-          skeletonGuidProvenance.set(skin.skeleton, { sceneEntityId: entity.localId });
+          skeletonGuidProvenance.set(skin.skeleton, { sceneEntityKey });
         }
       }
 
@@ -960,7 +978,7 @@ async function importGltf(
               fieldName: prov.fieldName,
               ...(prov.arrayIndex !== undefined ? { arrayIndex: prov.arrayIndex } : {}),
             },
-            sceneEntityId: prov.sceneEntityId,
+            sceneEntityKey: prov.sceneEntityKey,
           };
         }
         return { guid };
@@ -981,7 +999,7 @@ async function importGltf(
               ? {
                   guid,
                   sourceField: { componentName: 'Skin', fieldName: 'skeleton' },
-                  sceneEntityId: skProv.sceneEntityId,
+                  sceneEntityKey: skProv.sceneEntityKey,
                 }
               : { guid },
           );
@@ -1025,6 +1043,7 @@ async function importGltf(
         kind: 'skeleton' as const,
         inverseBindMatrices: rec.inverseBindMatrices,
         jointCount: rec.jointCount,
+        ...(rec.bounds === undefined ? {} : { bounds: rec.bounds }),
       };
       out.push({ guid: sub.guid, kind: 'skeleton', payload, refs: [], artifacts: {} });
     } else if (sub.kind === 'skin') {

package/src/parse-gltf.ts

@@ -400,6 +400,11 @@ interface RootGltfJson extends GltfExtensionsJson {
     readonly name?: string;
     readonly joints: readonly number[];
     readonly inverseBindMatrices?: number;
+    readonly extras?: {
+      readonly forgeax?: {
+        readonly conservativeAnimatedBounds?: unknown;
+      };
+    };
   }>;
   readonly meshes?: readonly MeshJson[];
   readonly materials?: ReadonlyArray<GltfMaterialJson>;

package/src/parse-skin.ts

@@ -8,10 +8,10 @@
 //   - plan-strategy D-1 (3-asset separation: IBM / skin binding / animation clip)
 //   - plan-strategy D-2 (skin index dedupe via reimport reuse managed by toAssetPack)
 //   - requirements AC-03 (skin index dedupe), AC-05 (jointPaths + Name missing fail-fast)
-//   - requirements AC-10 (IR extension), AC-27 (BindPose static AABB)
-//   - plan-strategy D-11 (BindPose AABB importer-phase, per-frame zero cost)
+//   - requirements AC-10 (IR extension)
 //   - charter P3 (fail-fast on invalid data)
 
+import { parseConservativeAnimatedBounds } from '@forgeax/engine-types';
 import { decodeF32Accessor } from './accessor/decode-accessor.js';
 import { err, type GltfError, gltfErr, ok, type Result } from './errors.js';
 import { buildNodeParentMap, resolveNamedNodePath } from './node-path.js';
@@ -33,12 +33,20 @@ export interface GltfSkeletonRecord {
   readonly inverseBindMatrices: Float32Array;
   /** Per-joint Name path from scene root (parallel to joints array). */
   readonly jointPaths: readonly string[];
+  /** Producer-authored conservative animated local bounds when supplied. */
+  readonly bounds?: Float32Array;
 }
 
 interface SkinJson {
   readonly name?: string;
   readonly joints: readonly number[];
   readonly inverseBindMatrices?: number;
+  /** glTF source metadata authored by the ForgeaX asset producer. */
+  readonly extras?: {
+    readonly forgeax?: {
+      readonly conservativeAnimatedBounds?: unknown;
+    };
+  };
 }
 
 interface NodeJson {
@@ -185,54 +193,19 @@ export function parseSkin(
       jointPaths.push(pathResult.value.join('/'));
     }
 
+    const bounds = parseConservativeAnimatedBounds(
+      skin.extras?.forgeax?.conservativeAnimatedBounds,
+    );
     records.push({
       jointCount: joints.length,
       inverseBindMatrices: ibm,
       jointPaths,
+      ...(bounds === undefined ? {} : { bounds }),
     });
   }
 
   return ok(records);
 }
 
-/**
- * Compute the BindPose static AABB for a skinned mesh's vertex positions.
- *
- * At bind pose, joint_bind = IBM^{-1}, so skinning collapses:
- *   world_pos = Sum(w_i * joint_bind_i * IBM_i * local_pos) = local_pos
- * Therefore the BindPose AABB is simply the local position bounds.
- *
- * Per-frame zero cost: stored in mesh asset metadata at importer time.
- * Dynamic AABB for animated poses is deferred to OOS-skin-dyn-bounds.
- *
- * Returns { min: [x,y,z], max: [x,y,z] } or undefined if positions is empty.
- */
-export function computeBindPoseAABB(positions: Float32Array):
-  | {
-      readonly min: readonly [number, number, number];
-      readonly max: readonly [number, number, number];
-    }
-  | undefined {
-  if (positions.length < 3) return undefined;
-  let minX = positions[0] ?? 0;
-  let minY = positions[1] ?? 0;
-  let minZ = positions[2] ?? 0;
-  let maxX = minX;
-  let maxY = minY;
-  let maxZ = minZ;
-  for (let i = 3; i < positions.length; i += 3) {
-    const x = positions[i] ?? 0;
-    const y = positions[i + 1] ?? 0;
-    const z = positions[i + 2] ?? 0;
-    if (x < minX) minX = x;
-    if (y < minY) minY = y;
-    if (z < minZ) minZ = z;
-    if (x > maxX) maxX = x;
-    if (y > maxY) maxY = y;
-    if (z > maxZ) maxZ = z;
-  }
-  return { min: [minX, minY, minZ], max: [maxX, maxY, maxZ] };
-}
-
 /** Re-export MAX_JOINTS for use by downstream modules. */
 export { MAX_JOINTS };