@forgeax/engine-gltf 0.1.4 → 0.1.6

package/README.md

@@ -12,7 +12,7 @@ identifier is invented by the glTF bridge.
 
 If a source requests a UV set that the primitive does not provide, handle `gltf-material-uv-set-missing` using its material, primitive, slot, requested set, and available sets. Add the source UV set and re-import; do not substitute a custom mesh or discard the slot transform.
 
-> 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 uses typed `assets.load(sceneGuid, sceneAssetKind)`, one World shared ref, and `world.instantiateScene` (no `loadGltf(url)` parallel API).
+> 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).
 
 > [!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.
@@ -110,7 +110,7 @@ only its slot index. Canonical `SceneAsset` nodes carry `MeshFilter` plus an
 empty `MeshRenderer.materials` override vector, so imported defaults remain
 mesh-owned and reimport-safe.
 
-Out of scope (each routed to its own `feat-future-*` anchor in `requirements.md` OOS-1 .. OOS-15): KHR extensions (note: `EXT_mesh_gpu_instancing` happy-path is supported, see feat-20260518-gltf-instancing-and-name-component) / morph targets other than the explicit `COLOR_0` deferred signal / orthographic camera / sparse accessors / inspector future fields / pixel-parity vs three.js. Dense interleaved `COLOR_0` is supported; other interleaved accessor consumers retain their existing scope. v1.1 OOS additions (locked by feat-20260518-gltf-instancing-and-name-component): multi-primitive instancing / mesh-level + material-level + scene-level Name (only node.name lands as ECS `Name`) / instancing hard cap / SoA TRS direct-to-GPU pipe / IR-to-GPU direct path / ROTATION BYTE/SHORT normalized encoding / Babylon thin-instances style SoA channel / Bevy multi-tier Name propagation.
+Out of scope (each routed to its own `feat-future-*` anchor in `requirements.md` OOS-1 .. OOS-15): KHR extensions other than the supported `EXT_mesh_gpu_instancing` and `KHR_texture_transform` paths / morph targets other than the explicit `COLOR_0` deferred signal / orthographic camera / sparse accessors / inspector future fields / pixel-parity vs three.js. Dense interleaved `COLOR_0` is supported; other interleaved accessor consumers retain their existing scope. v1.1 OOS additions (locked by feat-20260518-gltf-instancing-and-name-component): multi-primitive instancing / mesh-level + material-level + scene-level Name (only node.name lands as ECS `Name`) / instancing hard cap / SoA TRS direct-to-GPU pipe / IR-to-GPU direct path / ROTATION BYTE/SHORT normalized encoding / Babylon thin-instances style SoA channel / Bevy multi-tier Name propagation.
 
 ## Importer sub-asset PODs (7 kinds)
 
@@ -126,7 +126,7 @@ Out of scope (each routed to its own `feat-future-*` anchor in `requirements.md`
 | `skin` | `SkinAsset` | skeleton GUID |
 | `animation-clip` | `AnimationClip` | -- |
 
-Skinned glTFs (e.g. Khronos `Fox.glb` with 24 joints + 3 clips) flow through the same typed `assets.load(sceneGuid, sceneAssetKind)` + World `SceneAsset` shared-ref spine as static glTFs. The bridge (`gltfDocToSceneAsset`) auto-emits `Skin { skeleton: <skeleton-guid-string> }` on every node with `NodeIr.skinIndex !== null` when the caller passes `skeletonGuidBySkinIndex`; the World scene owner resolves the GUID to a shared ref at instantiate time, while mesh material dependencies load recursively from `MeshAsset.materialSlots[]`. `postSpawnResolveJoints` (`@forgeax/engine-runtime`) fills `Skin.joints[]` by walking `SkinAsset.jointPaths` against the spawn root's `ChildOf`-descendant subtree, so multiple `world.instantiateScene()` calls on the same skinned `SceneAsset` produce independently-posed instances (no cross-spawn joint sharing).
+Skinned glTFs (e.g. Khronos `Fox.glb` with 24 joints + 3 clips) flow through the same `loadByGuid<SceneAsset>` + `assets.instantiate` spine as static glTFs. The bridge (`gltfDocToSceneAsset`) auto-emits `Skin { skeleton: <skeleton-guid-string> }` on every node with `NodeIr.skinIndex !== null` when the caller passes `skeletonGuidBySkinIndex`; `AssetRegistry._resolveSceneGuids` resolves the GUID to a runtime Handle at instantiate time, while mesh material dependencies load recursively from `MeshAsset.materialSlots[]`. `postSpawnResolveJoints` (`@forgeax/engine-runtime`) fills `Skin.joints[]` by walking `SkinAsset.jointPaths` against the spawn root's `ChildOf`-descendant subtree, so multiple `instantiate()` calls on the same skinned `SceneAsset` produce independently-posed instances (no cross-spawn joint sharing).
 
 Sample reference: `apps/hello/skin` -- 3 Khronos Fox foxes side-by-side, each running a different clip (Survey / Walk / Run). Asset source under `forgeax-engine-assets/khronos-gltf-samples/Fox/` (CC BY 4.0; ATTRIBUTION.md alongside).
 
@@ -141,7 +141,7 @@ Sample reference: `apps/hello/skin` -- 3 Khronos Fox foxes side-by-side, each ru
 | `gltf-malformed-header` | GLB magic / version / length header rejection or missing JSON chunk |
 | `gltf-version-unsupported` | `asset.version` is not `'2.0'` |
 | `gltf-buffer-out-of-bounds` | accessor reads past `bufferView.byteLength` |
-| `gltf-extension-unsupported` | `extensionsRequired[]` lists an extension outside the v1 allowlist (`['EXT_mesh_gpu_instancing']`) |
+| `gltf-extension-unsupported` | `extensionsRequired[]` lists an extension outside the supported allowlist (`EXT_mesh_gpu_instancing`, `KHR_texture_transform`) |
 | `gltf-accessor-type-mismatch` | sparse / morph / interleaved / unknown componentType accessor (4 reasons) |
 | `gltf-texture-load-failed` | `externalLoader` rejected for a texture `uri`; `detail.uri` carries the failing URI; hint: `'check sidecar meta.json + textures/ directory + vite-plugin-pack /__pack/lookup'` |
 | `gltf-meta-missing` | sidecar `<source>.meta.json` is absent next to the `.gltf` / `.glb` source file |
@@ -154,6 +154,11 @@ Sample reference: `apps/hello/skin` -- 3 Khronos Fox foxes side-by-side, each ru
 | `gltf-color-accessor-unsupported` | `COLOR_0` type/component/normalized combination, sparse input, or morph-target input is deferred |
 | `gltf-color-accessor-malformed` | `COLOR_0` count, finite/range, buffer bounds, or reference validation failed |
 
+Source-key conflicts are producer failures, not automatic renames. A
+`duplicate-source-key` or `ambiguous-source-key` detail includes the semantic
+`key` and the smallest conflicting `entries` (`kind`, `name`, and
+`sourceIndex`); repair the source or its metadata and retry the same GUID.
+
 When `ImporterRegistry` + `runImport` consumes a glTF source, malformed base64 in a buffer data URI is returned as the existing `ImportError` `source-validation-failed` with `detail.diagnostics[].code === 'gltf-buffer-data-uri-invalid'`. The failed attempt publishes no Pack; after repairing the same source, Meta, and GUID declarations, the same registry/process can retry normally.
 
 ## Skin & Animation importer (feat-20260523)
@@ -166,17 +171,19 @@ When `ImporterRegistry` + `runImport` consumes a glTF source, malformed base64 i
 ## 4-step runtime recipe (apps/hello/gltf, M5)
 
 ```ts
-import { sceneAssetKind } from '@forgeax/engine-scene';
+// 1. configure pack index (vite-plugin-pack provides /__pack/lookup/:guid in dev mode)
+engine.assets.configurePackIndex('/box-pack-index.json');
 
-// 1. load the published SceneAsset through the typed owner decoder
-const sceneResult = await assets.load(sceneGuid, sceneAssetKind);
+// 2-4. load mesh / material / scene by GUID, then instantiate scene into world
+const sceneResult = await engine.assets.loadByGuid<SceneAsset>(sceneGuid);
 if (!sceneResult.ok) {
+  // GltfError surfaced upstream from the importer is converted into an AssetError
+  // here; the runtime AssetRegistry uses the existing 4-member AssetErrorCode.
   return;
 }
-// 2-3. World owns the ordinary shared ref and instantiates the scene
-const sceneHandle = world.internSharedRef('SceneAsset', sceneResult.value);
-const root = world.instantiateScene(sceneHandle);
-if (!root.ok) return;
+const root = engine.assets.instantiate(sceneResult.value, world);
+// `root` is the synthetic root Entity (carries SceneInstance + identity Transform);
+// equivalent to world.instantiateScene(handle).
 ```
 
 ## CLI plugin — `forgeax-engine-remote-gltf`