@forgeax/engine-gltf 0.1.27 → 0.1.29

package/README.md

@@ -51,7 +51,7 @@ reflection, Pack refs, Catalog/load, and runtime sampling.
 > structured `material-tangent-required` error. The importer persists generated
 > tangents in `MeshAsset.attributes.tangent` and never writes an identity guess.
 
-> Runtime glTF 2.0 importer (Tier-C subset). Pure-function pipeline `parseGlb` / `parseGltf` / `toAssetPack` consumed by build-time CLI plugin bin `forgeax-engine-remote-gltf` (resolved via PATH-prefix scan for `forgeax-engine-remote-`) writing `<source>.meta.json` (external-asset-package; dispatch on top-level `importer: 'gltf'`); runtime spawn happens via the existing `loadByGuid<SceneAsset>` plus `world.instantiateScene` 4-step recipe (no `loadGltf(url)` parallel API).
+> Runtime glTF 2.0 importer (Tier-C subset). Pure-function pipeline `parseGlb` / `parseGltf` / `toAssetPack` is selected by the unified `forgeax asset import` producer, which writes `<source>.meta.json` (external-asset-package; dispatch on top-level `importer: 'gltf'`); runtime spawn happens via the existing `loadByGuid<SceneAsset>` plus `world.instantiateScene` 4-step recipe (no `loadGltf(url)` parallel API).
 
 > [!IMPORTANT]
 > `toAssetPack` and `reimportReuseMeta` return `Result` values. The producer derives semantic `sourceKey` values before GUID reuse; duplicate or ambiguous identities return `duplicate-source-key` / `ambiguous-source-key` and the CLI leaves the previous sidecar untouched. `sourceIndex` is a locator only, never a generated identity.
@@ -228,7 +228,7 @@ When `ImporterRegistry` + `runImport` consumes a glTF source, malformed base64 i
 > Two submodules: `parse-skin.ts` (skin index dedupe via UUIDv5 + IBM decoding + jointPath derivation) + `parse-animation.ts` (LINEAR/STEP samplers, CUBICSPLINE/morph fail-fast). Called inside `parseGltfWithBin` -> `toAssetPack` which extends sub-asset output from 3 kinds (mesh/material/scene) to 6 (+ skeleton + skin + animation-clip).
 
 - **Limitations**: CUBICSPLINE interpolation not supported; morph weight animation not supported; jointPath resolution uses leaf-name first-match (same-name sibling is warn-only).
-- **BindPose AABB** derived at importer time (per skinned mesh-primitive, static BindPose) and written to mesh asset metadata for frustum cull; dynamic AABB deferred to OOS-skin-dyn-bounds.
+- **Animated skin bounds** are producer-authored facts. The primary source is `skins[].extras.forgeax.conservativeAnimatedBounds`; `importSettings.conservativeAnimatedBounds[sourceIndex]` is accepted only when source extras do not provide bounds. The importer publishes the six-float bounds on `SkeletonAsset`. If both sources are absent, bounds remain absent and Render keeps the skin on the `cpu-deformation` lane; no BindPose AABB is derived as an animation-bound fallback.
 
 ## 4-step runtime recipe (apps/hello/gltf, M5)
 
@@ -248,19 +248,21 @@ const root = engine.assets.instantiate(sceneResult.value, world);
 // equivalent to world.instantiateScene(handle).
 ```
 
-## CLI plugin — `forgeax-engine-remote-gltf`
+## Unified asset producer
 
-The build-time CLI subcommand `import` ships as a standalone plugin bin `forgeax-engine-remote-gltf` (entry `dist/cli-gltf.mjs`) declared in this package's `package.json#bin`, discovered via PATH-prefix scan for `forgeax-engine-remote-`.
+The glTF producer is selected by the unified `asset import` command. DevKit
+loads this package's producer only when a `.gltf` or `.glb` source is passed;
+the package no longer publishes an independent executable.
 
 | Subcommand | Description | Exit code |
 |:--|:--|:--|
-| `forgeax-engine-remote-gltf import <path>` | Parse `.gltf` / `.glb`; write sidecar `<source>.meta.json` (top-level `importer: 'gltf'`) next to source; UUIDv7 GUIDs assigned per sub-asset in document order | 0 success / 1 `GltfError` |
-| `forgeax-engine-remote-gltf import <path> --check` | Dry-run mode — no sidecar write; surfaces `gltf-meta-missing` route b (cf. importer route a) | 0 if sidecar already present / 1 if missing |
+| `forgeax asset import <path> --root <project>` | Parse `.gltf` / `.glb`; write sidecar `<source>.meta.json` (top-level `importer: 'gltf'`) next to source; UUIDv7 GUIDs assigned per sub-asset in document order | 0 success / 1 `GltfError` |
+| `forgeax asset import <path> --dry-run --root <project>` | Validate the producer path without writing a sidecar | 0 if valid / 1 if missing or invalid |
 
 ```bash
-# Direct invocation (after pnpm -F @forgeax/engine-gltf build)
-forgeax-engine-remote-gltf import apps/hello/gltf/assets/box.glb
-forgeax-engine-remote-gltf import apps/hello/gltf/assets/ --check
+# Unified invocation
+forgeax asset import apps/hello/gltf/assets/box.glb --root ./game --json
+forgeax asset import apps/hello/gltf/assets/ --dry-run --root ./game --json
 ```
 
 ### End-to-end source-to-Pack route
@@ -270,14 +272,14 @@ Pack/DDC publication path. Keep these steps together when adding a glTF LOD:
 
 ```mermaid
 flowchart LR
-    source["source .gltf/.glb"] --> cli["remote-gltf import"]
+    source["source .gltf/.glb"] --> cli["forgeax asset import"]
     cli --> meta["source.meta.json"]
     meta --> registry["ImporterRegistry + gltfImporter"]
     registry --> runner["runImport"]
     runner --> pack["Pack/DDC + Catalog"]
 ```
 
-1. Run `forgeax-engine-remote-gltf import <source>` to create or refresh the
+1. Run `forgeax asset import <source> --root <project>` to create or refresh the
    adjacent `<source>.meta.json` and its stable sub-asset GUIDs.
 2. Register `gltfImporter` with the build-time `ImporterRegistry` and pass the
    sidecar to `runImport`; this validates the declared LOD GUID closure and

package/dist/bridge.d.ts

@@ -53,6 +53,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>;
 }
 /**
  * Convert a parsed GltfDoc into a SceneAsset POD. Caller supplies registry

package/dist/bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EACV,SAAS,EACT,MAAM,EAEN,aAAa,EACb,aAAa,EAEb,SAAS,EAIT,MAAM,EACN,UAAU,EAIX,MAAM,uBAAuB,CAAC;AAQ/B,OAAO,EAA4B,KAAK,SAAS,EAAe,MAAM,aAAa,CAAC;AACpF,OAAO,KAAK,EACV,OAAO,EACP,cAAc,EACd,UAAU,EACV,UAAU,EAGX,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,SAAS,GAAE;IACT,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnD,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpD,GACL,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,CA0V9B;AAED,MAAM,WAAW,iBAAiB;IAChC,oEAAoE;IACpE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;IACzE,4DAA4D;IAC5D,QAAQ,CAAC,eAAe,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,eAAe,EAAE,QAAQ,CAAC,CAAC,CAAC;IACjF;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChE;AA+DD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB,GAAG,UAAU,CA8NpF;AAED,uFAAuF;AACvF,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC;AAEtC,MAAM,WAAW,qBAAqB;IACpC,0DAA0D;IAC1D,QAAQ,CAAC,cAAc,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC,CAAC;IAChF,0DAA0D;IAC1D,QAAQ,CAAC,cAAc,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC,CAAC;IAChF,8EAA8E;IAC9E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,CAAC;IACtC;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAuKD,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,cAAc,EACnB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,SAAS,MAAM,EAAE,GAC/B,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC,CAsC7B;AAED,wBAAgB,6BAA6B,CAC3C,GAAG,EAAE,cAAc,EACnB,IAAI,EAAE,UAAU,EAChB,KAAK,SAAc,GAClB,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC,CAoD7B;AAED,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,GAAG,EAAE,cAAc,EAAE,GAAG,CAAC,EAAE,qBAAqB,GAAG,aAAa,CA2H/F"}
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EACV,SAAS,EACT,MAAM,EAEN,aAAa,EACb,aAAa,EAEb,SAAS,EAIT,MAAM,EACN,UAAU,EAGX,MAAM,uBAAuB,CAAC;AAQ/B,OAAO,EAA4B,KAAK,SAAS,EAAe,MAAM,aAAa,CAAC;AACpF,OAAO,KAAK,EACV,OAAO,EACP,cAAc,EACd,UAAU,EACV,UAAU,EAGX,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,SAAS,GAAE;IACT,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnD,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpD,GACL,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,CA0V9B;AAED,MAAM,WAAW,iBAAiB;IAChC,oEAAoE;IACpE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;IACzE,4DAA4D;IAC5D,QAAQ,CAAC,eAAe,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,eAAe,EAAE,QAAQ,CAAC,CAAC,CAAC;IACjF;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/D;;;;;OAKG;IACH,QAAQ,CAAC,gCAAgC,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzE;AA+DD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB,GAAG,UAAU,CAgPpF;AAED,uFAAuF;AACvF,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC;AAEtC,MAAM,WAAW,qBAAqB;IACpC,0DAA0D;IAC1D,QAAQ,CAAC,cAAc,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC,CAAC;IAChF,0DAA0D;IAC1D,QAAQ,CAAC,cAAc,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC,CAAC;IAChF,8EAA8E;IAC9E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,CAAC;IACtC;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAuKD,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,cAAc,EACnB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,SAAS,MAAM,EAAE,GAC/B,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC,CAsC7B;AAED,wBAAgB,6BAA6B,CAC3C,GAAG,EAAE,cAAc,EACnB,IAAI,EAAE,UAAU,EAChB,KAAK,SAAc,GAClB,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC,CAoD7B;AAED,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,GAAG,EAAE,cAAc,EAAE,GAAG,CAAC,EAAE,qBAAqB,GAAG,aAAa,CA2H/F"}

package/dist/cli-gltf.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-gltf.d.ts","sourceRoot":"","sources":["../src/cli-gltf.ts"],"names":[],"mappings":";AAgCA,UAAU,QAAQ;IAChB,QAAQ,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,QAAQ,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9C;AAkCD,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAe/E"}
+{"version":3,"file":"cli-gltf.d.ts","sourceRoot":"","sources":["../src/cli-gltf.ts"],"names":[],"mappings":";AA8BA,UAAU,QAAQ;IAChB,QAAQ,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,QAAQ,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9C;AAkCD,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAe/E"}

package/dist/cli-gltf.mjs

@@ -3,7 +3,7 @@ import { realpath, stat, readFile, writeFile, readdir } from 'fs/promises';
 import { resolve, dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { parseArgs } from 'util';
-import { err, reconcileMeshMaterialSlotTopology, MESH_MATERIAL_SLOT_SOURCE_OVERRIDE_PAYLOAD_SCHEMA, ok, ImportError, IMPORT_ERROR_HINTS } from '@forgeax/engine-types';
+import { err, reconcileMeshMaterialSlotTopology, MESH_MATERIAL_SLOT_SOURCE_OVERRIDE_PAYLOAD_SCHEMA, ok, ImportError, IMPORT_ERROR_HINTS, parseConservativeAnimatedBounds } from '@forgeax/engine-types';
 import { vec3, quat, mat4 } from '@forgeax/engine-math';
 import { deriveDefaultLodScreenCoverages, reconcileMeshLodMeta } from '@forgeax/engine-import';
 import { deriveAnimationTargetId } from '@forgeax/engine-animation/target-id';
@@ -14,7 +14,7 @@ var GLTF_MESHOPT_FILTERS = ["NONE", "OCTAHEDRAL", "QUATERNION", "EXPONENTIAL"];
 var 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"',
@@ -50,7 +50,7 @@ var 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",
@@ -78,7 +78,7 @@ var 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: "mesh primitive declares JOINTS_0 and WEIGHTS_0 symmetrically (both present or both absent)",
@@ -1320,8 +1320,6 @@ function parseGlbChunks(buffer, filePath) {
     ...binChunk === void 0 ? {} : { binChunk }
   });
 }
-
-// src/parse-skin.ts
 var MAX_JOINTS = 256;
 var SKIN_ACCESSOR_TYPES = ["MAT4"];
 function identityMat4() {
@@ -1402,10 +1400,14 @@ function parseSkin(skinsJson, nodesJson, accessors, bufferViews, buffers) {
       if (!pathResult.ok) return err(pathResult.error);
       jointPaths.push(pathResult.value.join("/"));
     }
+    const bounds = parseConservativeAnimatedBounds(
+      skin.extras?.forgeax?.conservativeAnimatedBounds
+    );
     records.push({
       jointCount: joints.length,
       inverseBindMatrices: ibm,
-      jointPaths
+      jointPaths,
+      ...bounds === void 0 ? {} : { bounds }
     });
   }
   return ok(records);
@@ -2612,14 +2614,14 @@ function emitError(ctx, err3) {
 }
 function helpBody() {
   return [
-    "forgeax-engine-remote-gltf \u2014 glTF / GLB sidecar importer (produces texture/mesh/material/scene sub-assets)",
+    "forgeax asset import \u2014 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");
 }
@@ -2633,7 +2635,7 @@ async function runCliGltf(rest, ctx) {
     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 }
     });
   }
@@ -2655,8 +2657,8 @@ async function runImport(rest, ctx) {
     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 }
     });
   }
@@ -2664,7 +2666,7 @@ async function runImport(rest, ctx) {
   if (target === void 0) {
     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>",
+      expected: check ? "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"
     });
   }
@@ -2730,7 +2732,7 @@ async function runCheck(target, ctx) {
     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 }
     });