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

package/src/factory.ts

@@ -0,0 +1,303 @@
+/**
+ * Two-stage glTF asset factory and modular sub-factory implementations.
+ */
+
+import type { Realm3D, TextureId } from '@galfus/engine';
+import { createAnimationPlayer3D } from '@galfus/engine';
+import type {
+  ModelAssetFactory,
+  ModelBounds,
+  ModelImportOptions,
+  ModelInstance,
+  ModelInstantiateOptions,
+  SubModelAssetFactory
+} from '@galfus/model-loader-types';
+import { compileAnimationClips, setupSkins } from './animation';
+import { computeGltfBounds } from './bounds';
+import { GltfInstance } from './instance';
+import type { UploadedGltfResources } from './resources';
+import { spawnSceneGraph } from './scene';
+import type { GlTF } from './types';
+
+export interface GltfAssetFactoryInit {
+  assetName: string;
+  realm: Realm3D;
+  gltf: GlTF;
+  buffers: Uint8Array[];
+  resources: UploadedGltfResources;
+  importOptions?: ModelImportOptions;
+}
+
+/**
+ * Concrete SubModelAssetFactory spawning a specific sub-tree or scene
+ * while sharing the GPU resources uploaded by the parent GltfAssetFactory.
+ */
+export class SubGltfAssetFactory implements SubModelAssetFactory {
+  readonly name: string;
+  private readonly _parent: GltfAssetFactory;
+  private readonly _targetNodeIndices: number[];
+  private readonly _activeInstances = new Set<GltfInstance>();
+  private readonly _forgetInstance = (instance: GltfInstance): void => {
+    this._activeInstances.delete(instance);
+  };
+
+  constructor(name: string, parent: GltfAssetFactory, targetNodeIndices: number[]) {
+    this.name = name;
+    this._parent = parent;
+    this._targetNodeIndices = [...targetNodeIndices];
+  }
+
+  /**
+   * Spawns a new independent instance of this specific sub-tree.
+   */
+  instantiate(options?: ModelInstantiateOptions): ModelInstance {
+    const instance = this._parent._instantiateInternal(
+      options,
+      this._targetNodeIndices,
+      this._forgetInstance
+    );
+    this._activeInstances.add(instance);
+    return instance;
+  }
+
+  /**
+   * Destroys all active instances spawned through this sub-factory.
+   */
+  disposeAllInstances(): void {
+    for (const inst of this._activeInstances) {
+      inst.dispose();
+    }
+  }
+}
+
+/**
+ * Primary glTF asset factory.
+ *
+ * Holds all shared GPU resources (geometries, materials, textures) in VRAM and
+ * provides high-performance instantiation of ECS entities and sub-factories.
+ *
+ * @example
+ * ```typescript
+ * const factory = await loadGltfAsset(realm, data);
+ * const character1 = factory.instantiate({ transform: { position: [0, 0, 0] } });
+ * const character2 = factory.instantiate({ transform: { position: [5, 0, 0] } });
+ *
+ * // Full cleanup
+ * factory.dispose();
+ * ```
+ */
+export class GltfAssetFactory implements ModelAssetFactory {
+  readonly assetName: string;
+  readonly createdGeometryIds: readonly number[];
+  readonly createdMaterialIds: readonly number[];
+  readonly createdTextureIds: readonly number[];
+  readonly animationNames: readonly string[];
+  readonly bounds?: ModelBounds;
+
+  private readonly _realm: Realm3D;
+  private readonly _gltf: GlTF;
+  private readonly _buffers: Uint8Array[];
+  private readonly _resources: UploadedGltfResources;
+  private readonly _importOptions?: ModelImportOptions;
+  private readonly _activeInstances = new Set<GltfInstance>();
+  private _nextInstanceId = 1;
+  private _isDisposed = false;
+
+  constructor(init: GltfAssetFactoryInit) {
+    this.assetName = init.assetName;
+    this._realm = init.realm;
+    this._gltf = init.gltf;
+    this._buffers = init.buffers;
+    this._resources = init.resources;
+    this._importOptions = init.importOptions;
+
+    this.createdGeometryIds = Object.freeze([...init.resources.createdGeometryIds]);
+    this.createdMaterialIds = Object.freeze([...init.resources.createdMaterialIds]);
+    this.createdTextureIds = Object.freeze([...init.resources.createdTextureIds]);
+    this.animationNames = Object.freeze(
+      (init.gltf.animations ?? []).map((a, i) => a.name ?? `Animation_${i}`)
+    );
+    this.bounds = computeGltfBounds(init.gltf);
+  }
+
+  /** Indicates whether this factory and its GPU resources have been destroyed. */
+  get isDisposed(): boolean {
+    return this._isDisposed;
+  }
+
+  /**
+   * Spawns a new independent instance of the complete model graph in the ECS.
+   */
+  instantiate(options?: ModelInstantiateOptions): ModelInstance {
+    return this._instantiateInternal(options);
+  }
+
+  /**
+   * Internal instantiation driver supporting scoped root node filtering for sub-factories.
+   * @internal
+   */
+  _instantiateInternal(
+    options?: ModelInstantiateOptions,
+    rootNodeIndices?: number[],
+    onDispose?: (instance: GltfInstance) => void
+  ): GltfInstance {
+    if (this._isDisposed) {
+      throw new Error(`Cannot instantiate from disposed GltfAssetFactory '${this.assetName}'`);
+    }
+
+    const instanceId = this._nextInstanceId++;
+
+    // 1. Spawn Scene Graph entities in the ECS
+    const sceneResult = spawnSceneGraph(
+      this._realm,
+      this._gltf,
+      this._buffers,
+      this._resources,
+      options,
+      this._importOptions,
+      rootNodeIndices
+    );
+
+    // 2. Bind Skeletal Skins if present
+    setupSkins(this._realm, this._gltf, this._buffers, sceneResult);
+
+    // 3. Compile Animation Clips and bind AnimationPlayer3D
+    const clips = compileAnimationClips(
+      this._gltf,
+      this._buffers,
+      sceneResult.nodeEntityMap,
+      sceneResult.primitiveEntities
+    );
+    let animationPlayer: ReturnType<typeof createAnimationPlayer3D> | undefined;
+
+    if (clips.length > 0) {
+      animationPlayer = createAnimationPlayer3D();
+      for (const clip of clips) {
+        animationPlayer.addClip(clip);
+      }
+      this._realm.world.attachComponent(sceneResult.rootEntityId, animationPlayer);
+    }
+
+    // 4. Construct GltfInstance wrapper
+    const instance = new GltfInstance({
+      instanceId,
+      realm: this._realm,
+      rootEntityId: sceneResult.rootEntityId,
+      entities: sceneResult.entities,
+      instancedModelIds: sceneResult.instancedModelIds,
+      animationPlayer,
+      onDispose: (inst) => {
+        this._activeInstances.delete(inst);
+        onDispose?.(inst);
+      }
+    });
+
+    this._activeInstances.add(instance);
+    return instance;
+  }
+
+  /**
+   * Creates a sub-factory focused on a specific node or sub-tree by name or numerical index.
+   *
+   * @param nodeNameOrIndex The target node name or index.
+   * @returns SubModelAssetFactory for modular instantiation.
+   */
+  createSubFactory(nodeNameOrIndex: string | number): SubModelAssetFactory {
+    if (this._isDisposed) {
+      throw new Error(
+        `Cannot create sub-factory from disposed GltfAssetFactory '${this.assetName}'`
+      );
+    }
+
+    let nodeIdx: number | undefined;
+    if (typeof nodeNameOrIndex === 'number') {
+      nodeIdx = nodeNameOrIndex;
+    } else {
+      const nodes = this._gltf.nodes ?? [];
+      for (let i = 0; i < nodes.length; i++) {
+        if (nodes[i]!.name === nodeNameOrIndex) {
+          nodeIdx = i;
+          break;
+        }
+      }
+    }
+
+    if (nodeIdx === undefined || !this._gltf.nodes?.[nodeIdx]) {
+      throw new Error(`Node '${nodeNameOrIndex}' not found in glTF asset '${this.assetName}'`);
+    }
+
+    const subName = `${this.assetName}::${this._gltf.nodes[nodeIdx]!.name ?? `Node_${nodeIdx}`}`;
+    return new SubGltfAssetFactory(subName, this, [nodeIdx]);
+  }
+
+  /**
+   * Creates a sub-factory focused on an alternative scene by index.
+   *
+   * @param sceneIndex The zero-based scene index.
+   * @returns SubModelAssetFactory for scene-scoped instantiation.
+   */
+  createSubFactoryByScene(sceneIndex: number): SubModelAssetFactory {
+    if (this._isDisposed) {
+      throw new Error(
+        `Cannot create sub-factory from disposed GltfAssetFactory '${this.assetName}'`
+      );
+    }
+
+    const scene = this._gltf.scenes?.[sceneIndex];
+    if (!scene) {
+      throw new Error(`Scene index ${sceneIndex} out of bounds in glTF asset '${this.assetName}'`);
+    }
+
+    const subName = `${this.assetName}::${scene.name ?? `Scene_${sceneIndex}`}`;
+    return new SubGltfAssetFactory(subName, this, scene.nodes ?? []);
+  }
+
+  /**
+   * Destroys all currently active instances spawned by this factory.
+   */
+  disposeAllInstances(): void {
+    for (const inst of this._activeInstances) {
+      inst.dispose();
+    }
+    this._activeInstances.clear();
+  }
+
+  /**
+   * Terminal teardown: destroys all instances and frees all geometries, materials,
+   * and textures from the Realm and GPU.
+   */
+  dispose(): void {
+    if (this._isDisposed) return;
+    this._isDisposed = true;
+
+    // 1. Destroy all spawned instances
+    this.disposeAllInstances();
+
+    // 2. Free shared Realm Geometries
+    for (const geoId of this.createdGeometryIds) {
+      try {
+        this._realm.destroyGeometry(geoId);
+      } catch {
+        // Ignored during shutdown
+      }
+    }
+
+    // 3. Free shared Realm Materials
+    for (const matId of this.createdMaterialIds) {
+      try {
+        this._realm.destroyMaterial(matId);
+      } catch {
+        // Ignored during shutdown
+      }
+    }
+
+    // 4. Free shared GPU Textures
+    for (const texId of this.createdTextureIds) {
+      try {
+        this._realm.resources.disposeTexture(texId as unknown as TextureId);
+      } catch {
+        // Ignored during shutdown
+      }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,185 @@
+/**
+ * @module @galfus/gltf-loader
+ *
+ * Canonical glTF 2.0 and GLB asset loader for Galfus Engine.
+ * Supports auto-decoders, two-stage GPU asset caching, skeletal skinning,
+ * animation clips, GPU instancing, and modular sub-factories.
+ */
+
+import type { Realm3D } from '@galfus/engine';
+import type { ModelImportOptions } from '@galfus/model-loader-types';
+import { resolveDecoders } from './decoders/resolver';
+import { GltfAssetFactory } from './factory';
+import { parseGltf } from './parser';
+import { uploadGltfResources } from './resources';
+import type { GlTF, GltfMaterialAlphaModeResolver } from './types';
+import { createZipResolver, findPrimaryGltfPath, isZipContainer, unpackZipArchive } from './zip';
+
+export * from './animation';
+export * from './bounds';
+export * from './decoders/resolver';
+export * from './factory';
+export * from './instance';
+export * from './parser';
+export * from './resources';
+export * from './scene';
+export * from './types';
+export * from './zip';
+export * from '@galfus/model-loader-types';
+
+export interface GltfLoadOptions extends ModelImportOptions {
+  /** Overrides a material's alpha mode for applications that need a specific rendering policy. */
+  resolveMaterialAlphaMode?: GltfMaterialAlphaModeResolver;
+}
+
+/**
+ * Resolves source input into a contiguous Uint8Array byte buffer.
+ */
+async function resolveSourceBytes(source: Uint8Array | ArrayBuffer | string): Promise<Uint8Array> {
+  if (typeof source !== 'string') {
+    return source instanceof Uint8Array ? source : new Uint8Array(source);
+  }
+
+  // HTTP(S) URL
+  if (source.startsWith('http://') || source.startsWith('https://')) {
+    const res = await fetch(source);
+    if (!res.ok) {
+      throw new Error(`Failed to fetch glTF asset from "${source}": HTTP ${res.status}`);
+    }
+    const buf = await res.arrayBuffer();
+    return new Uint8Array(buf);
+  }
+
+  // Node.js or Bun local filesystem path
+  if (typeof process !== 'undefined' && process.versions?.node) {
+    const { readFile } = await import('node:fs/promises');
+    const nodeBuf = await readFile(source);
+    return new Uint8Array(nodeBuf.buffer, nodeBuf.byteOffset, nodeBuf.byteLength);
+  }
+
+  // Fallback fetch for browser environments
+  const res = await fetch(source);
+  if (!res.ok) {
+    throw new Error(`Failed to load glTF asset from "${source}": HTTP ${res.status}`);
+  }
+  const buf = await res.arrayBuffer();
+  return new Uint8Array(buf);
+}
+
+/**
+ * Loads a glTF 2.0 (.gltf, .glb, or .zip archive) asset into a high-performance two-stage GltfAssetFactory.
+ *
+ * Transparently accepts:
+ * 1. Monolithic binary .glb containers (in memory or file path).
+ * 2. Standalone .gltf JSON files with embedded data URIs.
+ * 3. Compact .zip archives containing .gltf, .bin buffers, and texture subdirectories.
+ *
+ * Uploads all shared geometries, PBR materials, and textures to the GPU once,
+ * resolving compression extensions (Draco, Meshopt) automatically.
+ *
+ * @param realm The destination Realm3D where resources and entities are instantiated.
+ * @param source Raw glTF binary (.glb), JSON (.gltf), ZIP (.zip) bytes, or file path / URL.
+ * @param options Optional import filters, node renamers, and camera/light toggles.
+ * @returns Ready-to-use GltfAssetFactory for spawning ECS instances.
+ *
+ * @example
+ * ```typescript
+ * import { loadGltfAsset } from '@galfus/gltf-loader';
+ *
+ * // 1. Load from ZIP archive file path
+ * const factoryA = await loadGltfAsset(realm, './models/character.zip');
+ *
+ * // 2. Load from raw GLB bytes
+ * const factoryB = await loadGltfAsset(realm, glbData);
+ *
+ * const instance = factoryA.instantiate({ transform: { position: [0, 0, 0] } });
+ * ```
+ */
+export async function loadGltfAsset(
+  realm: Realm3D,
+  source: Uint8Array | ArrayBuffer | string,
+  options?: GltfLoadOptions
+): Promise<GltfAssetFactory> {
+  const bytes = await resolveSourceBytes(source);
+
+  let gltf: GlTF;
+  let buffers: Uint8Array[];
+  let externalResolver: ((uri: string) => Promise<Uint8Array>) | undefined;
+
+  // A) Check if source is a ZIP archive
+  if (isZipContainer(bytes)) {
+    const fileMap = unpackZipArchive(bytes);
+    const primaryGltfPath = findPrimaryGltfPath(fileMap);
+    if (!primaryGltfPath) {
+      throw new Error(
+        'Invalid ZIP model archive: no .gltf or .glb file found in the decompressed directory tree'
+      );
+    }
+    const primaryBytes = fileMap.get(primaryGltfPath)!;
+    externalResolver = createZipResolver(fileMap, primaryGltfPath);
+    const parsed = await parseGltf(primaryBytes, externalResolver);
+    gltf = parsed.gltf;
+    buffers = parsed.buffers;
+  } else {
+    // B) Standard GLB binary or standalone glTF JSON
+    if (typeof source === 'string') {
+      if (/^https?:\/\//i.test(source)) {
+        externalResolver = async (uri) => resolveSourceBytes(new URL(uri, source).href);
+      } else if (typeof process !== 'undefined' && process.versions?.node) {
+        const path = await import('node:path');
+        externalResolver = async (uri) =>
+          resolveSourceBytes(path.resolve(path.dirname(source), decodeURIComponent(uri)));
+      }
+    }
+    const parsed = await parseGltf(bytes, externalResolver);
+    gltf = parsed.gltf;
+    buffers = parsed.buffers;
+  }
+
+  // 2. Automatically resolve required compression decoders (Draco, Meshopt)
+  const decoders = await resolveDecoders(gltf, options?.decoders);
+
+  if (decoders.meshopt) {
+    for (const view of gltf.bufferViews ?? []) {
+      const ext = view.extensions?.EXT_meshopt_compression;
+      if (!ext) continue;
+      const sourceBuffer = buffers[ext.buffer];
+      if (!sourceBuffer) throw new Error('Missing Meshopt source buffer');
+      const offset = ext.byteOffset ?? 0;
+      const decoded = await decoders.meshopt.decodeGpuBuffer(
+        ext.count,
+        ext.byteStride,
+        sourceBuffer.subarray(offset, offset + ext.byteLength),
+        ext.mode,
+        ext.filter
+      );
+      if (decoded.byteLength !== ext.count * ext.byteStride)
+        throw new Error('Invalid Meshopt decoded buffer length');
+      view.buffer = buffers.length;
+      view.byteOffset = 0;
+      view.byteLength = decoded.byteLength;
+      buffers.push(decoded);
+    }
+  }
+
+  // 3. Upload shared GPU resources (geometries in canonical 136-byte format, PBR materials, textures)
+  const resources = await uploadGltfResources(
+    realm,
+    gltf,
+    buffers,
+    decoders,
+    externalResolver,
+    options?.resolveMaterialAlphaMode
+  );
+
+  // 4. Construct and return primary asset factory
+  const assetName = gltf.asset.generator ?? 'glTF_Asset';
+  return new GltfAssetFactory({
+    assetName,
+    realm,
+    gltf,
+    buffers,
+    resources,
+    importOptions: options
+  });
+}

package/src/instance.ts

@@ -0,0 +1,126 @@
+/**
+ * Concrete implementation of ModelInstance for spawned glTF scene graphs.
+ */
+
+import type { AnimationPlayer3DComponent, Realm3D } from '@galfus/engine';
+import type { ModelInstance } from '@galfus/model-loader-types';
+
+export interface GltfInstanceInit {
+  instanceId: number;
+  realm: Realm3D;
+  rootEntityId: number;
+  entities: number[];
+  instancedModelIds?: number[];
+  animationPlayer?: AnimationPlayer3DComponent;
+  onDispose?: (instance: GltfInstance) => void;
+}
+
+/**
+ * Concrete ModelInstance representing a live glTF scene graph in the ECS.
+ *
+ * @example
+ * ```typescript
+ * const instance = factory.instantiate();
+ * const head = instance.getEntityByName('Head');
+ * instance.dispose(); // Destroys entities while preserving shared GPU assets
+ * ```
+ */
+export class GltfInstance implements ModelInstance {
+  readonly instanceId: number;
+  readonly rootEntityId: number;
+  readonly entities: readonly number[];
+  readonly animationPlayer?: AnimationPlayer3DComponent;
+
+  private readonly _realm: Realm3D;
+  private readonly _instancedModelIds: number[];
+  private readonly _onDispose?: (instance: GltfInstance) => void;
+  private _isDisposed = false;
+
+  constructor(init: GltfInstanceInit) {
+    this.instanceId = init.instanceId;
+    this._realm = init.realm;
+    this.rootEntityId = init.rootEntityId;
+    this.entities = Object.freeze([...init.entities]);
+    this._instancedModelIds = init.instancedModelIds ? [...init.instancedModelIds] : [];
+    this.animationPlayer = init.animationPlayer;
+    this._onDispose = init.onDispose;
+  }
+
+  /** Indicates whether this instance has already been destroyed. */
+  get isDisposed(): boolean {
+    return this._isDisposed;
+  }
+
+  /**
+   * Resolves an entity ID by its assigned name within this instance.
+   *
+   * @param name The entity name to look up.
+   * @returns Entity ID or undefined if not found.
+   */
+  getEntityByName(name: string): number | undefined {
+    if (this._isDisposed) return undefined;
+    for (const entityId of this.entities) {
+      if (this._realm.getEntityName(entityId) === name) {
+        return entityId;
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Queries all entities within this instance matching a metadata key and optional value.
+   *
+   * @param key The metadata key.
+   * @param value Optional expected value to match.
+   * @returns Array of matching entity IDs.
+   */
+  getEntitiesByMetadata(key: string, value?: unknown): number[] {
+    if (this._isDisposed) return [];
+    const results: number[] = [];
+    for (const entityId of this.entities) {
+      const val = this._realm.getMetadataKV(entityId, key);
+      if (val !== undefined) {
+        if (value === undefined || val === value) {
+          results.push(entityId);
+        }
+      }
+    }
+    return results;
+  }
+
+  /**
+   * Destroys all ECS entities, stop bound animations, and frees hardware instanced draws.
+   *
+   * Safe and idempotent. Shared textures, materials, and geometries in the factory remain alive.
+   */
+  dispose(): void {
+    if (this._isDisposed) return;
+    this._isDisposed = true;
+
+    // 1. Stop animation player if present
+    if (this.animationPlayer) {
+      this.animationPlayer.stop();
+    }
+
+    // 2. Destroy hardware instanced models
+    for (const instId of this._instancedModelIds) {
+      try {
+        this._realm.destroyInstancedModel(instId);
+      } catch {
+        // Ignored during shutdown
+      }
+    }
+
+    // 3. Destroy all ECS entities belonging to this instance
+    for (const entityId of this.entities) {
+      try {
+        this._realm.destroyEntity(entityId);
+      } catch {
+        // Ignored if entity was already destroyed
+      }
+    }
+
+    // 4. Notify parent factory of disposal
+    this._onDispose?.(this);
+  }
+}