@galfus/gltf-loader 0.0.0-stage → 0.31.1-alpha

package/README.md

@@ -1,3 +1,94 @@
-# Temporary Holding Version
+# @galfus/gltf-loader
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Canonical **glTF 2.0** and **GLB** asset loader for the **Galfus Engine** ecosystem.
+
+Implements the official Khronos glTF 2.0 specification with automatic compression decoders (Draco, Meshopt), two-stage GPU asset caching, skeletal skinning, animation clips, GPU instancing (`EXT_mesh_gpu_instancing`), and modular sub-factories.
+
+---
+
+## Features
+
+- **Dual Format Support**: Seamlessly loads both binary `.glb` containers and text `.gltf` files with embedded Base64 data URIs or binary chunks.
+- **Two-Stage Asset Lifecycle**:
+  - `GltfAssetFactory`: Uploads shared geometries (packed into Galfus canonical 136-byte stride), PBR materials, and textures to the GPU **once**.
+  - `GltfInstance`: Spawns lightweight, independent ECS entities sharing the pre-uploaded GPU assets.
+- **Modular Sub-Factories (`createSubFactory`)**: Isolate and instantiate individual sub-trees or alternate scenes from modular asset packs without duplicating VRAM.
+- **Auto-Decoders (Zero Configuration)**: Automatically detects `KHR_draco_mesh_compression` and `EXT_meshopt_compression` extensions in headers and initializes decoders on demand.
+- **Hardware GPU Instancing**: Automatically maps `EXT_mesh_gpu_instancing` nodes to Galfus native 32-float instance buffers, rendering thousands of objects in a single draw call.
+- **Skeletal Skinning & Animations**: Binds glTF skins to `Skin3DComponent` (solved via `HierarchyCoordinator`) and compiles multi-channel animations for `AnimationPlayer3DComponent`.
+
+---
+
+## Installation
+
+```bash
+bun add @galfus/gltf-loader @galfus/model-loader-types @galfus/engine
+```
+
+---
+
+## Usage
+
+### 1. Basic Loading and Instantiation
+
+```typescript
+import { createBunTransport } from '@galfus/transport-bun';
+import { createRuntime } from '@galfus/engine';
+import { loadGltfAsset } from '@galfus/gltf-loader';
+
+// Initialize engine and 3D Realm
+const transport = await createBunTransport({ targetFps: 60 });
+const runtime = createRuntime(transport);
+const realm3d = runtime.createRealm3D(1);
+
+// Load GLB file bytes
+const glbData = await Bun.file('models/character.glb').bytes();
+const factory = await loadGltfAsset(realm3d, glbData);
+
+// Spawn multiple characters sharing the same GPU mesh & textures
+const char1 = factory.instantiate({ transform: { position: [0, 0, 0] } });
+const char2 = factory.instantiate({ transform: { position: [5, 0, 0] } });
+
+// Play animations
+char1.animationPlayer?.play('Run', 'repeat');
+
+// Cleanup:
+char1.dispose(); // Destroys only char1 ECS entities
+factory.dispose(); // Destroys all instances and purges VRAM textures/meshes
+```
+
+---
+
+### 2. Modular Sub-Factories (Asset Kits)
+
+```typescript
+// Load a dungeon kit containing multiple modular pieces in one GLB
+const dungeonKit = await loadGltfAsset(realm3d, dungeonKitBytes);
+
+// Create sub-factories for specific modular pieces
+const wallFactory = dungeonKit.createSubFactory('Wall_Straight');
+const doorFactory = dungeonKit.createSubFactory('Door_Arch');
+
+// Instantiate 20 walls with zero VRAM duplication
+for (let i = 0; i < 20; i++) {
+  wallFactory.instantiate({ transform: { position: [i * 2, 0, 0] } });
+}
+
+// Destroy only the walls
+wallFactory.disposeAllInstances();
+```
+
+---
+
+### 3. Granular Entity Queries and Attachment
+
+```typescript
+const instance = factory.instantiate();
+
+// Query entity by name assigned in authoring tool (e.g. Blender)
+const handEntity = instance.getEntityByName('RightHand');
+if (handEntity !== undefined) {
+  // Attach accessory to bone
+  realm3d.hierarchy.attach(swordEntity, handEntity);
+}
+```

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@galfus/gltf-loader",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.31.1-alpha",
+  "description": "Fast, comprehensive glTF / GLB 2.0 asset loader for Galfus Engine",
+  "author": "Renato Rodrigues (morbden) <renato@vulppi.dev>",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/galfus-lang/galfus-engine.git",
+    "directory": "host/gltf-loader"
+  },
+  "bugs": {
+    "url": "https://github.com/galfus-lang/galfus-engine/issues"
+  },
+  "homepage": "https://github.com/galfus-lang/galfus-engine#readme",
+  "keywords": [
+    "galfus",
+    "game-engine",
+    "gltf",
+    "glb",
+    "3d",
+    "loader",
+    "assets",
+    "mesh",
+    "skinning"
+  ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@galfus/engine": "^0.31.1-alpha",
+    "@galfus/model-loader-types": "^0.31.1-alpha",
+    "fflate": "^0.8.3"
+  },
+  "devDependencies": {
+    "@galfus/transport-types": "^0.31.1-alpha"
+  }
+}

package/src/animation.ts

@@ -0,0 +1,160 @@
+/**
+ * Skeletal skin binding and animation clip compilation for glTF assets.
+ */
+
+import type { AnimationClip, InterpolationMode, KeyframeTrack, Realm3D } from '@galfus/engine';
+import { readAccessor } from './parser';
+import type { SpawnedSceneResult } from './scene';
+import type { GlTF } from './types';
+
+/**
+ * Creates and registers Skin3D components for all skinned models in a spawned scene.
+ *
+ * @param realm The target Realm3D.
+ * @param gltf The root glTF descriptor.
+ * @param buffers Array of resolved binary buffers.
+ * @param sceneResult Result of the scene spawning phase.
+ *
+ * @example
+ * ```typescript
+ * setupSkins(realm, gltf, buffers, sceneResult);
+ * ```
+ */
+export function setupSkins(
+  realm: Realm3D,
+  gltf: GlTF,
+  buffers: Uint8Array[],
+  sceneResult: SpawnedSceneResult
+): void {
+  if (!gltf.nodes || !gltf.skins) return;
+
+  for (let nIdx = 0; nIdx < gltf.nodes.length; nIdx++) {
+    const node = gltf.nodes[nIdx]!;
+    if (node.skin === undefined || node.mesh === undefined) continue;
+
+    const modelEntityId = sceneResult.nodeEntityMap.get(nIdx);
+    if (modelEntityId === undefined) continue;
+
+    const skin = gltf.skins[node.skin];
+    if (!skin) continue;
+
+    // Resolve joint entity IDs
+    const joints: number[] = [];
+    for (const jointNodeIdx of skin.joints) {
+      const jointEntityId = sceneResult.nodeEntityMap.get(jointNodeIdx);
+      if (jointEntityId !== undefined) {
+        joints.push(jointEntityId);
+      } else {
+        throw new Error(`Skin ${node.skin} references missing joint node ${jointNodeIdx}`);
+      }
+    }
+
+    if (joints.length === 0) continue;
+
+    // Extract inverse bind matrices (16 floats per joint)
+    let inverseBindMatrices: Float32Array;
+    if (skin.inverseBindMatrices !== undefined) {
+      inverseBindMatrices = readAccessor(gltf, buffers, skin.inverseBindMatrices) as Float32Array;
+    } else {
+      // Fallback: 16-float identity matrices
+      inverseBindMatrices = new Float32Array(joints.length * 16);
+      for (let j = 0; j < joints.length; j++) {
+        const offset = j * 16;
+        inverseBindMatrices[offset + 0] = 1;
+        inverseBindMatrices[offset + 5] = 1;
+        inverseBindMatrices[offset + 10] = 1;
+        inverseBindMatrices[offset + 15] = 1;
+      }
+    }
+
+    for (const entityId of sceneResult.primitiveEntities.get(nIdx) ?? [modelEntityId]) {
+      const { entityId: skinEntityId } = realm.createSkin(entityId, joints, inverseBindMatrices);
+      sceneResult.entities.push(skinEntityId);
+    }
+  }
+}
+
+/**
+ * Compiles raw glTF animation channels and samplers into native Galfus AnimationClips.
+ *
+ * @param gltf The root glTF descriptor.
+ * @param buffers Array of resolved binary buffers.
+ * @param nodeEntityMap Mapping from glTF node indices to instantiated ECS entity IDs.
+ * @returns Array of compiled, ready-to-play AnimationClips.
+ *
+ * @example
+ * ```typescript
+ * const clips = compileAnimationClips(gltf, buffers, sceneResult.nodeEntityMap);
+ * console.log(`Compiled ${clips.length} animation clips`);
+ * ```
+ */
+export function compileAnimationClips(
+  gltf: GlTF,
+  buffers: Uint8Array[],
+  nodeEntityMap: Map<number, number>,
+  primitiveEntities?: Map<number, number[]>
+): AnimationClip[] {
+  if (!gltf.animations || gltf.animations.length === 0) {
+    return [];
+  }
+
+  const clips: AnimationClip[] = [];
+
+  for (let aIdx = 0; aIdx < gltf.animations.length; aIdx++) {
+    const anim = gltf.animations[aIdx]!;
+    const tracks: KeyframeTrack[] = [];
+    let maxDuration = 0;
+
+    for (let cIdx = 0; cIdx < anim.channels.length; cIdx++) {
+      const channel = anim.channels[cIdx]!;
+      const targetNodeIdx = channel.target.node;
+      if (targetNodeIdx === undefined) continue;
+
+      const targetEntityId = nodeEntityMap.get(targetNodeIdx);
+      if (targetEntityId === undefined) continue;
+
+      const sampler = anim.samplers[channel.sampler];
+      if (!sampler) continue;
+
+      const timestamps = readAccessor(gltf, buffers, sampler.input) as Float32Array;
+      const values = readAccessor(gltf, buffers, sampler.output) as Float32Array;
+
+      if (timestamps.length > 0) {
+        const lastTime = timestamps[timestamps.length - 1] ?? 0;
+        if (lastTime > maxDuration) {
+          maxDuration = lastTime;
+        }
+      }
+
+      const interpolation: InterpolationMode =
+        sampler.interpolation === 'STEP'
+          ? 'step'
+          : sampler.interpolation === 'CUBICSPLINE'
+            ? 'cubicspline'
+            : 'linear';
+
+      const targets =
+        channel.target.path === 'weights'
+          ? (primitiveEntities?.get(targetNodeIdx) ?? [targetEntityId])
+          : [targetEntityId];
+      for (const targetEntity of targets)
+        tracks.push({
+          targetEntity,
+          path: channel.target.path,
+          timestamps,
+          values,
+          interpolation
+        });
+    }
+
+    if (tracks.length > 0) {
+      clips.push({
+        name: anim.name ?? `Animation_${aIdx}`,
+        duration: maxDuration,
+        tracks
+      });
+    }
+  }
+
+  return clips;
+}

package/src/bounds.ts

@@ -0,0 +1,160 @@
+/**
+ * Spatial bounding box and sphere computation for glTF 2.0 assets.
+ */
+
+import { mat4, quat } from '@galfus/engine';
+import type { ModelBounds } from '@galfus/model-loader-types';
+import type { GlTF, GlTFNode } from './types';
+
+/**
+ * Computes local 4x4 matrix for a glTF node from either matrix or TRS parameters.
+ */
+function getNodeLocalMatrix(node: GlTFNode, outMat: mat4.Mat4): void {
+  if (node.matrix) {
+    for (let i = 0; i < 16; i++) {
+      outMat[i] = node.matrix[i] ?? (i % 5 === 0 ? 1 : 0);
+    }
+    return;
+  }
+
+  const t: [number, number, number] = node.translation ?? [0, 0, 0];
+  const r: [number, number, number, number] = node.rotation ?? [0, 0, 0, 1];
+  const s: [number, number, number] = node.scale ?? [1, 1, 1];
+
+  mat4.fromRotationTranslationScale(outMat, r as unknown as quat.ReadonlyQuat, t, s);
+}
+
+/**
+ * Transforms a 3D point by a 4x4 column-major matrix.
+ */
+function transformPoint(p: [number, number, number], m: mat4.Mat4): [number, number, number] {
+  return [
+    p[0] * m[0] + p[1] * m[4] + p[2] * m[8] + m[12],
+    p[0] * m[1] + p[1] * m[5] + p[2] * m[9] + m[13],
+    p[0] * m[2] + p[1] * m[6] + p[2] * m[10] + m[14]
+  ];
+}
+
+/**
+ * Calculates the axis-aligned bounding box (AABB) and bounding radius for a glTF asset.
+ *
+ * Traverses the node hierarchy from root scenes, applies accumulated world matrices,
+ * and transforms the min/max extents of all mesh primitive POSITION accessors.
+ *
+ * @param gltf The parsed glTF 2.0 JSON structure.
+ * @returns Spatial ModelBounds containing min, max, center, size, and radius, or undefined if empty.
+ *
+ * @example
+ * ```typescript
+ * const bounds = computeGltfBounds(gltf);
+ * if (bounds) {
+ *   console.log(`Model extents: ${bounds.size.join('x')} m`);
+ *   console.log(`Bounding radius: ${bounds.radius.toFixed(2)} m`);
+ * }
+ * ```
+ */
+export function computeGltfBounds(gltf: GlTF): ModelBounds | undefined {
+  if (!gltf.nodes || gltf.nodes.length === 0 || !gltf.meshes || gltf.meshes.length === 0) {
+    return undefined;
+  }
+
+  const globalMin: [number, number, number] = [Infinity, Infinity, Infinity];
+  const globalMax: [number, number, number] = [-Infinity, -Infinity, -Infinity];
+  let foundAnyVertex = false;
+
+  const identityMat = mat4.create();
+
+  function traverseNode(nodeIndex: number, parentWorldMat: mat4.Mat4): void {
+    const node = gltf.nodes?.[nodeIndex];
+    if (!node) return;
+
+    const localMat = mat4.create();
+    getNodeLocalMatrix(node, localMat);
+
+    const worldMat = mat4.create();
+    mat4.multiply(worldMat, parentWorldMat, localMat);
+
+    if (node.mesh !== undefined) {
+      const mesh = gltf.meshes?.[node.mesh];
+      if (mesh) {
+        for (const prim of mesh.primitives) {
+          const posAccIndex = prim.attributes?.POSITION;
+          if (posAccIndex !== undefined) {
+            const acc = gltf.accessors?.[posAccIndex];
+            if (acc?.min && acc?.max && acc.min.length >= 3 && acc.max.length >= 3) {
+              const minX = acc.min[0]!;
+              const minY = acc.min[1]!;
+              const minZ = acc.min[2]!;
+              const maxX = acc.max[0]!;
+              const maxY = acc.max[1]!;
+              const maxZ = acc.max[2]!;
+
+              const corners: [number, number, number][] = [
+                [minX, minY, minZ],
+                [maxX, minY, minZ],
+                [minX, maxY, minZ],
+                [maxX, maxY, minZ],
+                [minX, minY, maxZ],
+                [maxX, minY, maxZ],
+                [minX, maxY, maxZ],
+                [maxX, maxY, maxZ]
+              ];
+
+              for (const corner of corners) {
+                const [tx, ty, tz] = transformPoint(corner, worldMat);
+                if (tx < globalMin[0]) globalMin[0] = tx;
+                if (tx > globalMax[0]) globalMax[0] = tx;
+                if (ty < globalMin[1]) globalMin[1] = ty;
+                if (ty > globalMax[1]) globalMax[1] = ty;
+                if (tz < globalMin[2]) globalMin[2] = tz;
+                if (tz > globalMax[2]) globalMax[2] = tz;
+                foundAnyVertex = true;
+              }
+            }
+          }
+        }
+      }
+    }
+
+    if (node.children) {
+      for (const childIdx of node.children) {
+        traverseNode(childIdx, worldMat);
+      }
+    }
+  }
+
+  // Traverse through active scene roots (or all root candidates)
+  const activeSceneIdx = gltf.scene ?? 0;
+  const activeScene = gltf.scenes?.[activeSceneIdx];
+  const rootNodeIndices = activeScene?.nodes ?? (gltf.nodes.length > 0 ? [0] : []);
+
+  for (const rootIdx of rootNodeIndices) {
+    traverseNode(rootIdx, identityMat);
+  }
+
+  if (!foundAnyVertex || !isFinite(globalMin[0]) || !isFinite(globalMax[0])) {
+    return undefined;
+  }
+
+  const size: [number, number, number] = [
+    globalMax[0] - globalMin[0],
+    globalMax[1] - globalMin[1],
+    globalMax[2] - globalMin[2]
+  ];
+
+  const center: [number, number, number] = [
+    (globalMin[0] + globalMax[0]) * 0.5,
+    (globalMin[1] + globalMax[1]) * 0.5,
+    (globalMin[2] + globalMax[2]) * 0.5
+  ];
+
+  const radius = Math.hypot(size[0], size[1], size[2]) * 0.5;
+
+  return {
+    min: globalMin,
+    max: globalMax,
+    center,
+    size,
+    radius
+  };
+}

package/src/decoders/resolver.ts

@@ -0,0 +1,131 @@
+/**
+ * Automatic lazy decoder resolution for compressed glTF extensions (Draco, Meshopt).
+ *
+ * Automatically sniffs extensions in glTF headers and loads decompression runtimes
+ * on demand without adding overhead for standard uncompressed models.
+ */
+
+import type { GlTF } from '../types';
+
+export interface DracoAttributeMapping {
+  position?: Float32Array;
+  normal?: Float32Array;
+  uv?: Float32Array;
+  uv1?: Float32Array;
+  tangent?: Float32Array;
+  color?: Float32Array;
+  joints?: Uint16Array | Uint32Array;
+  weights?: Float32Array;
+  indices?: Uint16Array | Uint32Array;
+}
+
+export interface DracoDecoder {
+  decode(
+    buffer: Uint8Array,
+    attributeIds: Record<string, number>
+  ): Promise<DracoAttributeMapping> | DracoAttributeMapping;
+}
+
+export interface MeshoptDecoder {
+  decodeGpuBuffer(
+    count: number,
+    byteStride: number,
+    source: Uint8Array,
+    mode: 'ATTRIBUTES' | 'TRIANGLES' | 'INDICES',
+    filter?: 'NONE' | 'OCTAHEDRAL' | 'QUATERNION' | 'EXPONENTIAL'
+  ): Promise<Uint8Array> | Uint8Array;
+}
+
+export interface ResolvedDecoders {
+  draco?: DracoDecoder;
+  meshopt?: MeshoptDecoder;
+}
+
+// Global cached decoder singletons to avoid repeated initialization
+let cachedDracoDecoder: DracoDecoder | undefined;
+let cachedMeshoptDecoder: MeshoptDecoder | undefined;
+
+/**
+ * Registers a global Draco decoder instance shared across all asset loaders.
+ */
+export function registerGlobalDracoDecoder(decoder: DracoDecoder): void {
+  cachedDracoDecoder = decoder;
+}
+
+/**
+ * Registers a global Meshopt decoder instance shared across all asset loaders.
+ */
+export function registerGlobalMeshoptDecoder(decoder: MeshoptDecoder): void {
+  cachedMeshoptDecoder = decoder;
+}
+
+/**
+ * Sniffs glTF header extensions and automatically resolves required decoders.
+ *
+ * @param gltf The parsed glTF root structure.
+ * @param userDecoders Optional explicit decoder overrides provided by the user.
+ * @returns Object holding resolved decoders.
+ * @throws Error if an extension is strictly required but no compatible decoder is available.
+ *
+ * @example
+ * ```typescript
+ * const decoders = await resolveDecoders(gltf, options?.decoders);
+ * ```
+ */
+export async function resolveDecoders(
+  gltf: GlTF,
+  userDecoders?: Record<string, unknown>
+): Promise<ResolvedDecoders> {
+  const required = gltf.extensionsRequired ?? [];
+  const used = gltf.extensionsUsed ?? [];
+  const allExts = new Set([...required, ...used]);
+
+  const resolved: ResolvedDecoders = {};
+
+  // 1. Draco Compression (KHR_draco_mesh_compression)
+  if (allExts.has('KHR_draco_mesh_compression')) {
+    if (userDecoders?.['draco']) {
+      resolved.draco = userDecoders['draco'] as DracoDecoder;
+    } else if (cachedDracoDecoder) {
+      resolved.draco = cachedDracoDecoder;
+    } else {
+      // Attempt dynamic on-demand import if available in runtime
+      try {
+        const dynamicModule = (await import(/* @vite-ignore */ 'draco3d' as string).catch(
+          () => null
+        )) as { createDecoderModule?: () => Promise<unknown> } | null;
+        if (dynamicModule?.createDecoderModule) {
+          // Wrapped adapter if draco3d is present in environment
+          // (Can be populated when package is installed)
+        }
+      } catch {
+        // Ignored; handled below if strictly required
+      }
+
+      if (!resolved.draco && required.includes('KHR_draco_mesh_compression')) {
+        throw new Error(
+          'glTF asset requires "KHR_draco_mesh_compression", but no Draco decoder is registered. ' +
+            'Provide one via ModelImportOptions.decoders or registerGlobalDracoDecoder().'
+        );
+      }
+    }
+  }
+
+  // 2. Meshopt Compression (EXT_meshopt_compression)
+  if (allExts.has('EXT_meshopt_compression')) {
+    if (userDecoders?.['meshopt']) {
+      resolved.meshopt = userDecoders['meshopt'] as MeshoptDecoder;
+    } else if (cachedMeshoptDecoder) {
+      resolved.meshopt = cachedMeshoptDecoder;
+    } else {
+      if (required.includes('EXT_meshopt_compression')) {
+        throw new Error(
+          'glTF asset requires "EXT_meshopt_compression", but no Meshopt decoder is registered. ' +
+            'Provide one via ModelImportOptions.decoders or registerGlobalMeshoptDecoder().'
+        );
+      }
+    }
+  }
+
+  return resolved;
+}