@forgeax/engine-gltf 0.1.27 → 0.1.29

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/cli-gltf.ts

@@ -1,18 +1,16 @@
 #!/usr/bin/env node
-// @forgeax/engine-gltf/src/cli-gltf — `forgeax-engine-remote-gltf` plugin
-// bin (feat-20260516-console-dependency-inversion plan-strategy section
-// 2.9). Discovered by the base bin via the kubectl 4th-path
-// `forgeax-engine-remote-` prefix scanner.
+// @forgeax/engine-gltf/src/cli-gltf — internal producer used by DevKit's
+// unified `forgeax asset import` command. It is deliberately not a package bin.
 //
 // Single subcommand `import` for v1 (UX break vs the prior
-// `forgeax-engine-remote-asset import`):
+// `forgeax asset import`):
 //
-//   write mode  `forgeax-engine-remote-gltf import <gltf-or-glb>`
+//   write mode  `forgeax asset import <gltf-or-glb> --root <project>`
 //                Parses the source via parseGlb / parseGltf and writes the
 //                sibling `<source>.meta.json` sidecar (sorted-keys, LF line
 //                ending — byte-stable so a clean reimport produces no diff).
 //
-//   --check     `forgeax-engine-remote-gltf import --check <dir>`
+//   --check     `forgeax asset import <dir> --dry-run --root <project>`
 //                Dry-run: traverse <dir> reusing SCANNER_BLACKLIST from
 //                @forgeax/engine-pack/scanner and surface the first orphan
 //                .gltf / .glb whose `<source>.meta.json` is absent as
@@ -55,14 +53,14 @@ function emitError(ctx: AssetCtx, err: ErrShape): number {
 
 function helpBody(): string {
   return [
-    'forgeax-engine-remote-gltf — glTF / GLB sidecar importer (produces texture/mesh/material/scene sub-assets)',
+    'forgeax asset import — glTF / GLB sidecar importer (internal producer)',
     '',
     'Usage:',
-    '  forgeax-engine-remote-gltf import <path.gltf|path.glb>',
-    '  forgeax-engine-remote-gltf import --check <dir>',
+    '  forgeax asset import <path.gltf|path.glb> --root <project>',
+    '  forgeax asset import <dir> --dry-run --root <project>',
     '',
-    'Produces a sibling <source>.meta.json sidecar with sub-asset entries',
-    'for every glTF asset category: texture, mesh, material, scene.',
+    'produces texture, mesh, material, and scene sub-asset entries in a sibling',
+    '<source>.meta.json sidecar.',
     '',
   ].join('\n');
 }
@@ -77,7 +75,7 @@ export async function runCliGltf(rest: string[], ctx: AssetCtx): Promise<number>
     return emitError(ctx, {
       code: 'unknown-subcommand',
       expected: "subcommand 'import'",
-      hint: "run 'forgeax-engine-remote-gltf --help' for usage",
+      hint: "run 'forgeax help asset import' for usage",
       detail: { subcommand: sub },
     });
   }
@@ -100,8 +98,8 @@ async function runImport(rest: string[], ctx: AssetCtx): Promise<number> {
     const message = e instanceof Error ? e.message : String(e);
     return emitError(ctx, {
       code: 'cli-parse-error',
-      expected: 'forgeax-engine-remote-gltf import [--check] <path>',
-      hint: "run 'forgeax-engine-remote-gltf --help' for usage",
+      expected: 'forgeax asset import [--dry-run] <path> --root <project>',
+      hint: "run 'forgeax help asset import' for usage",
       detail: { message },
     });
   }
@@ -110,8 +108,8 @@ async function runImport(rest: string[], ctx: AssetCtx): Promise<number> {
     return emitError(ctx, {
       code: 'cli-parse-error',
       expected: check
-        ? 'forgeax-engine-remote-gltf import --check <dir>'
-        : 'forgeax-engine-remote-gltf import <path.gltf|path.glb>',
+        ? 'forgeax asset import <dir> --dry-run --root <project>'
+        : 'forgeax asset import <path.gltf|path.glb> --root <project>',
       hint: 'pass a positional <gltf-or-glb> argument; with --check pass a directory',
     });
   }
@@ -192,7 +190,7 @@ async function runCheck(target: string, ctx: AssetCtx): Promise<number> {
     const message = e instanceof Error ? e.message : String(e);
     return emitError(ctx, {
       code: 'cli-parse-error',
-      expected: 'forgeax-engine-remote-gltf import --check <dir>',
+      expected: 'forgeax asset import <dir> --dry-run --root <project>',
       hint: 'pass a directory that exists and is readable',
       detail: { path: target, message },
     });

package/src/errors.ts

@@ -267,7 +267,7 @@ const gltfErrorPolicy = {
   'gltf-malformed-header': {
     expected:
       'GLB 12-byte header (magic 0x46546C67 + version=2 + length) plus mandatory JSON chunk',
-    hint: 'verify .glb is not truncated; rerun: forgeax-engine-remote-gltf import <path>',
+    hint: 'verify .glb is not truncated; rerun: forgeax asset import <path> --root <project> --json',
   },
   'gltf-version-unsupported': {
     expected: 'asset.version === "2.0"',
@@ -305,7 +305,7 @@ const gltfErrorPolicy = {
   },
   'gltf-meta-missing': {
     expected: "sidecar <source>.meta.json (importer: 'gltf') present in same directory",
-    hint: 'run: forgeax-engine-remote-gltf import <path>',
+    hint: 'run: forgeax asset import <path> --root <project> --json',
   },
   'gltf-instancing-count-mismatch': {
     expected: 'all instance attribute accessors share the same count',
@@ -334,7 +334,7 @@ const gltfErrorPolicy = {
   'gltf-image-extract-failed': {
     expected:
       'image bytes extractable from bufferView / data-URI / external URI without corruption',
-    hint: 'verify the bufferView byte range / data: URI base64 / external URI sibling file is intact next to the .gltf source; rerun: forgeax-engine-remote-gltf import <path>',
+    hint: 'verify the bufferView byte range / data: URI base64 / external URI sibling file is intact next to the .gltf source; rerun: forgeax asset import <path> --root <project> --json',
   },
   'gltf-skin-attr-asymmetric': {
     expected:

package/src/gltf-importer.ts

@@ -51,6 +51,7 @@ import type {
 import {
   IMPORT_ERROR_HINTS,
   ImportError,
+  readConservativeAnimatedBounds,
   reconcileMeshMaterialSlotTopology,
   resolveMeshMaterialSlotDefaultGuid,
   toShared,
@@ -72,7 +73,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 +83,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 +544,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 = applyImportSettingsBounds(parsed.value, ctx.importSettings);
   const maps = buildHandleMaps(ctx.subAssets, doc);
 
   // Pre-derive each images[] row's colorSpace from material slot bindings
@@ -921,30 +938,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 +977,7 @@ async function importGltf(
               fieldName: prov.fieldName,
               ...(prov.arrayIndex !== undefined ? { arrayIndex: prov.arrayIndex } : {}),
             },
-            sceneEntityId: prov.sceneEntityId,
+            sceneEntityKey: prov.sceneEntityKey,
           };
         }
         return { guid };
@@ -981,7 +998,7 @@ async function importGltf(
               ? {
                   guid,
                   sourceField: { componentName: 'Skin', fieldName: 'skeleton' },
-                  sceneEntityId: skProv.sceneEntityId,
+                  sceneEntityKey: skProv.sceneEntityKey,
                 }
               : { guid },
           );
@@ -1025,6 +1042,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 };