@vulfram/gltf-loader 0.22.2-alpha → 0.22.4-alpha

package/README.md

@@ -2,4 +2,5 @@
 
 Loads `.gltf` and `.glb` content into `@vulfram/engine` 3D worlds.
 
-Status: initial package scaffold. Runtime loading is not implemented yet.
+The loader follows the engine host-side math convention and exposes transforms as
+`gl-matrix` `vec3` / `quat`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vulfram/gltf-loader",
-  "version": "0.22.2-alpha",
+  "version": "0.22.4-alpha",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -19,11 +19,12 @@
   },
   "devDependencies": {
     "@types/bun": "^1.3.10",
-    "@vulfram/engine": "^0.22.2-alpha"
+    "@vulfram/engine": "^0.22.4-alpha"
   },
   "dependencies": {
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
-    "@gltf-transform/functions": "^4.3.0"
+    "@gltf-transform/functions": "^4.3.0",
+    "gl-matrix": "^3.4.4"
   }
 }

package/src/binary.ts

@@ -33,7 +33,7 @@ export function detectFormat(bytes: Uint8Array): GltfSourceFormat {
 
   throw new GltfLoaderError(
     'UNSUPPORTED_FORMAT',
-    'Unable to detect glTF format from payload bytes.',
+    'Unable to detect glTF format from payload bytes.'
   );
 }
 
@@ -59,7 +59,7 @@ export function decodeDataUri(uri: string): Uint8Array {
 
 /** Normalizes external resource map to Uint8Array values. */
 export function normalizeResourceMap(
-  resources?: Record<string, BinaryLike>,
+  resources?: Record<string, BinaryLike>
 ): Record<string, Uint8Array> {
   if (!resources) return {};
   const out: Record<string, Uint8Array> = {};

package/src/context.ts

@@ -25,8 +25,8 @@ export function createContext(input: GltfLoadInput): LoaderContext {
       entities: 0,
       geometries: 0,
       materials: 0,
-      textures: 0,
-    },
+      textures: 0
+    }
   };
 }
 
@@ -40,7 +40,7 @@ function allocBufferId(): number {
 export function uploadBytes(
   _ctx: LoaderContext,
   usage: 'image-data' | 'vertex-data' | 'index-data',
-  bytes: Uint8Array,
+  bytes: Uint8Array
 ): number {
   const bufferId = allocBufferId();
   uploadBuffer(bufferId, usage, bytes);

package/src/convert.ts

@@ -1,18 +1,30 @@
 import { Accessor, TextureInfo } from '@gltf-transform/core';
+import {
+  quat,
+  vec3,
+  vec4,
+  type quat as Quat,
+  type vec3 as Vec3,
+  type vec4 as Vec4
+} from 'gl-matrix';
 import type { GeometryPrimitiveEntry, SamplerMode } from '@vulfram/engine/types';
 import { U16_MAX } from './constants';
 import { GltfLoaderError } from './errors';
 
-export function toArray3(v: ArrayLike<number>): [number, number, number] {
-  return [v[0] ?? 0, v[1] ?? 0, v[2] ?? 0];
+export function toVec3(v: ArrayLike<number>): Vec3 {
+  return vec3.fromValues(v[0] ?? 0, v[1] ?? 0, v[2] ?? 0);
 }
 
-export function toArray4(v: ArrayLike<number>, fallbackW = 1): [number, number, number, number] {
-  return [v[0] ?? 0, v[1] ?? 0, v[2] ?? 0, v[3] ?? fallbackW];
+export function toVec4(v: ArrayLike<number>, fallbackW = 1): Vec4 {
+  return vec4.fromValues(v[0] ?? 0, v[1] ?? 0, v[2] ?? 0, v[3] ?? fallbackW);
+}
+
+export function toQuat(v: ArrayLike<number>, fallbackW = 1): Quat {
+  return quat.fromValues(v[0] ?? 0, v[1] ?? 0, v[2] ?? 0, v[3] ?? fallbackW);
 }
 
 export function semanticToPrimitiveType(
-  semantic: string,
+  semantic: string
 ): GeometryPrimitiveEntry['primitiveType'] | null {
   switch (semantic) {
     case 'POSITION':
@@ -41,7 +53,7 @@ export function samplerFromTextureInfo(
     getWrapT(): number;
     getMagFilter(): number | null;
     getMinFilter(): number | null;
-  } | null,
+  } | null
 ): SamplerMode {
   const WRAP_REPEAT = TextureInfo.WrapMode.REPEAT;
   const WRAP_MIRRORED_REPEAT = TextureInfo.WrapMode.MIRRORED_REPEAT;
@@ -56,18 +68,18 @@ export function samplerFromTextureInfo(
   const min = info?.getMinFilter();
 
   const repeat =
-    wrapS === WRAP_REPEAT
-    || wrapS === WRAP_MIRRORED_REPEAT
-    || wrapT === WRAP_REPEAT
-    || wrapT === WRAP_MIRRORED_REPEAT;
+    wrapS === WRAP_REPEAT ||
+    wrapS === WRAP_MIRRORED_REPEAT ||
+    wrapT === WRAP_REPEAT ||
+    wrapT === WRAP_MIRRORED_REPEAT;
 
   const linear =
-    mag === null
-    || mag === MAG_LINEAR
-    || min === null
-    || min === MIN_LINEAR
-    || min === MIN_LINEAR_MIPMAP_LINEAR
-    || min === MIN_LINEAR_MIPMAP_NEAREST;
+    mag === null ||
+    mag === MAG_LINEAR ||
+    min === null ||
+    min === MIN_LINEAR ||
+    min === MIN_LINEAR_MIPMAP_LINEAR ||
+    min === MIN_LINEAR_MIPMAP_NEAREST;
 
   if (repeat) return linear ? 'linear-repeat' : 'point-repeat';
   return linear ? 'linear-clamp' : 'point-clamp';
@@ -82,11 +94,7 @@ function toFloatArray(accessor: Accessor, components: number, fillTail = 0): Flo
   const srcArray = accessor.getArray();
   const elementSize = accessor.getElementSize();
 
-  if (
-    srcArray instanceof Float32Array
-    && !accessor.getNormalized()
-    && elementSize === components
-  ) {
+  if (srcArray instanceof Float32Array && !accessor.getNormalized() && elementSize === components) {
     return srcArray;
   }
 

package/src/errors.ts

@@ -2,7 +2,10 @@ import type { GltfLoaderErrorCode } from './types';
 
 /** Loader error with stable error code for callers. */
 export class GltfLoaderError extends Error {
-  constructor(public readonly code: GltfLoaderErrorCode, message: string) {
+  constructor(
+    public readonly code: GltfLoaderErrorCode,
+    message: string
+  ) {
     super(message);
     this.name = 'GltfLoaderError';
   }

package/src/index.ts

@@ -1,8 +1,4 @@
-import {
-  dispose3DGeometry,
-  dispose3DMaterial,
-  dispose3DTexture,
-} from '@vulfram/engine/world3d';
+import { dispose3DGeometry, dispose3DMaterial, dispose3DTexture } from '@vulfram/engine/world3d';
 import { createContext } from './context';
 import { GltfLoaderError } from './errors';
 import { readDocument } from './parse';
@@ -12,7 +8,7 @@ import type {
   GltfLoadInput,
   GltfLoadResult,
   GltfInstance,
-  LoadedGltfAsset,
+  LoadedGltfAsset
 } from './types';
 
 export type {
@@ -27,7 +23,7 @@ export type {
   NodeTemplate,
   SceneTemplate,
   GltfSourceFormat,
-  RootTransform,
+  RootTransform
 } from './types';
 export { GltfLoaderError } from './errors';
 
@@ -78,7 +74,7 @@ export async function loadGltfAsset(input: GltfLoadInput): Promise<LoadedGltfAss
     if (disposedAll) {
       throw new GltfLoaderError(
         'INVALID_INPUT',
-        'Cannot instantiate from a disposed glTF asset. Load it again.',
+        'Cannot instantiate from a disposed glTF asset. Load it again.'
       );
     }
 
@@ -99,11 +95,11 @@ export async function loadGltfAsset(input: GltfLoadInput): Promise<LoadedGltfAss
     resources: {
       geometries: [...ctx.createdGeometryIds],
       materials: [...ctx.createdMaterialIds],
-      textures: [...ctx.createdTextureIds],
+      textures: [...ctx.createdTextureIds]
     },
     instantiate,
     disposeEntities,
-    disposeAll,
+    disposeAll
   };
 }
 
@@ -115,7 +111,7 @@ export async function loadGltfAsset(input: GltfLoadInput): Promise<LoadedGltfAss
 export async function loadGltfScene(input: GltfLoadInput): Promise<GltfLoadResult> {
   const asset = await loadGltfAsset(input);
   const instance = asset.instantiate({
-    rootTransform: input.rootTransform,
+    rootTransform: input.rootTransform
   });
 
   return {
@@ -124,6 +120,6 @@ export async function loadGltfScene(input: GltfLoadInput): Promise<GltfLoadResul
     geometryCount: asset.resources.geometries.length,
     materialCount: asset.resources.materials.length,
     textureCount: asset.resources.textures.length,
-    warnings: asset.warnings,
+    warnings: asset.warnings
   };
 }

package/src/parse.ts

@@ -5,7 +5,7 @@ import type { GltfLoadInput } from './types';
 
 function parseGltfJsonDocument(
   bytes: Uint8Array,
-  resources?: Record<string, import('./types').BinaryLike>,
+  resources?: Record<string, import('./types').BinaryLike>
 ): JSONDocument {
   const decoder = new TextDecoder('utf-8');
   let json: GLTF.IGLTF;
@@ -26,7 +26,7 @@ function parseGltfJsonDocument(
     }
     throw new GltfLoaderError(
       'MISSING_RESOURCE',
-      `External resource not provided for URI "${uri}". Provide it in input.resources.`,
+      `External resource not provided for URI "${uri}". Provide it in input.resources.`
     );
   };
 
@@ -39,7 +39,7 @@ function parseGltfJsonDocument(
 
   return {
     json,
-    resources: resourceMap as unknown as { [s: string]: Uint8Array<ArrayBuffer> },
+    resources: resourceMap as unknown as { [s: string]: Uint8Array<ArrayBuffer> }
   };
 }
 

package/src/resources.ts

@@ -5,8 +5,9 @@ import {
   create3DTexture,
   type GeometryId,
   type MaterialId,
-  type TextureId,
+  type TextureId
 } from '@vulfram/engine/world3d';
+import { vec4 } from 'gl-matrix';
 import type { GeometryPrimitiveEntry } from '@vulfram/engine/types';
 import { uploadBytes } from './context';
 import {
@@ -14,15 +15,11 @@ import {
   accessorToStreamBytes,
   samplerFromTextureInfo,
   semanticToPrimitiveType,
-  toArray4,
+  toVec4
 } from './convert';
 import type { LoaderContext } from './types';
 
-function uploadVertexAccessor(
-  ctx: LoaderContext,
-  accessor: Accessor,
-  semantic: string,
-): number {
+function uploadVertexAccessor(ctx: LoaderContext, accessor: Accessor, semantic: string): number {
   const cached = ctx.uploadedVertexByAccessor.get(accessor);
   if (cached !== undefined) return cached;
 
@@ -46,14 +43,14 @@ function uploadIndexAccessor(ctx: LoaderContext, accessor: Accessor): number {
 export function ensureTexture(
   ctx: LoaderContext,
   texture: Texture,
-  srgb: boolean,
+  srgb: boolean
 ): TextureId | null {
   const existing = ctx.textureBySource.get(texture);
   if (existing !== undefined) {
     const previous = ctx.textureColorSpaceHint.get(texture);
     if (previous !== undefined && previous !== srgb) {
       ctx.warnings.push(
-        `Texture "${texture.getName() || 'unnamed'}" reused with mixed color-space expectations; keeping first value (srgb=${previous}).`,
+        `Texture "${texture.getName() || 'unnamed'}" reused with mixed color-space expectations; keeping first value (srgb=${previous}).`
       );
     }
     return existing;
@@ -62,7 +59,7 @@ export function ensureTexture(
   const image = texture.getImage();
   if (!image) {
     ctx.warnings.push(
-      `Texture "${texture.getName() || 'unnamed'}" has no image bytes and was skipped.`,
+      `Texture "${texture.getName() || 'unnamed'}" has no image bytes and was skipped.`
     );
     return null;
   }
@@ -72,7 +69,7 @@ export function ensureTexture(
     label: `${ctx.labelPrefix}:tex:${texture.getName() || 'unnamed'}`,
     source: { type: 'buffer', bufferId },
     srgb,
-    mode: 'standalone',
+    mode: 'standalone'
   });
 
   ctx.textureBySource.set(texture, textureId);
@@ -98,11 +95,11 @@ function ensureDefaultMaterial(ctx: LoaderContext): MaterialId {
       options: {
         type: 'standard',
         content: {
-          baseColor: [1, 1, 1, 1],
+          baseColor: vec4.fromValues(1, 1, 1, 1),
           surfaceType: 'opaque',
-          flags: 0,
-        },
-      },
+          flags: 0
+        }
+      }
     });
 
     ctx.defaultMaterialId = id;
@@ -117,16 +114,16 @@ function ensureDefaultMaterial(ctx: LoaderContext): MaterialId {
     options: {
       type: 'pbr',
       content: {
-        baseColor: [1, 1, 1, 1],
+        baseColor: vec4.fromValues(1, 1, 1, 1),
         surfaceType: 'opaque',
-        emissiveColor: [0, 0, 0, 1],
+        emissiveColor: vec4.fromValues(0, 0, 0, 1),
         metallic: 0,
         roughness: 1,
         ao: 1,
         normalScale: 1,
-        flags: 0,
-      },
-    },
+        flags: 0
+      }
+    }
   });
 
   ctx.defaultMaterialId = id;
@@ -169,14 +166,14 @@ export function ensureMaterial(ctx: LoaderContext, material: Material | null): M
         ? {
             type: 'pbr' as const,
             content: {
-              baseColor: toArray4(material.getBaseColorFactor(), 1),
+              baseColor: toVec4(material.getBaseColorFactor(), 1),
               surfaceType: alphaModeToSurfaceType(material.getAlphaMode()),
-              emissiveColor: [
+              emissiveColor: vec4.fromValues(
                 emissiveFactor[0] ?? 0,
                 emissiveFactor[1] ?? 0,
                 emissiveFactor[2] ?? 0,
-                1,
-              ] as [number, number, number, number],
+                1
+              ),
               metallic: material.getMetallicFactor(),
               roughness: material.getRoughnessFactor(),
               ao: material.getOcclusionStrength(),
@@ -191,20 +188,20 @@ export function ensureMaterial(ctx: LoaderContext, material: Material | null): M
               emissiveSampler,
               aoTexId,
               aoSampler,
-              flags: material.getDoubleSided() ? 1 : 0,
-            },
+              flags: material.getDoubleSided() ? 1 : 0
+            }
           }
         : {
             type: 'standard' as const,
             content: {
-              baseColor: toArray4(material.getBaseColorFactor(), 1),
+              baseColor: toVec4(material.getBaseColorFactor(), 1),
               surfaceType: alphaModeToSurfaceType(material.getAlphaMode()),
-              specColor: [
+              specColor: vec4.fromValues(
                 material.getMetallicFactor(),
                 material.getRoughnessFactor(),
                 material.getOcclusionStrength(),
-                1,
-              ] as [number, number, number, number],
+                1
+              ),
               specPower: 32,
               baseTexId,
               baseSampler,
@@ -212,10 +209,10 @@ export function ensureMaterial(ctx: LoaderContext, material: Material | null): M
               normalSampler,
               specTexId: mrTexId,
               specSampler: mrSampler,
-              flags: material.getDoubleSided() ? 1 : 0,
-            },
-          }),
-    },
+              flags: material.getDoubleSided() ? 1 : 0
+            }
+          })
+    }
   });
 
   ctx.materialBySource.set(material, materialId);
@@ -227,14 +224,14 @@ export function ensureMaterial(ctx: LoaderContext, material: Material | null): M
 /** Ensures a core geometry exists for source primitive. */
 export function ensurePrimitiveGeometry(
   ctx: LoaderContext,
-  primitive: Primitive,
+  primitive: Primitive
 ): GeometryId | null {
   const existing = ctx.geometryByPrimitive.get(primitive);
   if (existing !== undefined) return existing;
 
   if (primitive.getMode() !== Primitive.Mode.TRIANGLES) {
     ctx.warnings.push(
-      `Primitive mode ${primitive.getMode()} is not supported in v1 loader (triangles only). Primitive skipped.`,
+      `Primitive mode ${primitive.getMode()} is not supported in v1 loader (triangles only). Primitive skipped.`
     );
     return null;
   }
@@ -244,7 +241,7 @@ export function ensurePrimitiveGeometry(
   if (indexAccessor) {
     entries.push({
       primitiveType: 'index',
-      bufferId: uploadIndexAccessor(ctx, indexAccessor),
+      bufferId: uploadIndexAccessor(ctx, indexAccessor)
     });
   }
 
@@ -254,7 +251,7 @@ export function ensurePrimitiveGeometry(
     'TANGENT',
     'COLOR_0',
     'TEXCOORD_0',
-    'TEXCOORD_1',
+    'TEXCOORD_1'
   ] as const;
 
   let hasPosition = false;
@@ -273,7 +270,7 @@ export function ensurePrimitiveGeometry(
 
     entries.push({
       primitiveType,
-      bufferId: uploadVertexAccessor(ctx, accessor, semantic),
+      bufferId: uploadVertexAccessor(ctx, accessor, semantic)
     });
   }
 
@@ -285,7 +282,7 @@ export function ensurePrimitiveGeometry(
   const geometryId = create3DGeometry(ctx.worldId, {
     type: 'custom',
     label: `${ctx.labelPrefix}:geo:${primitive.getName() || 'unnamed'}`,
-    entries,
+    entries
   });
 
   ctx.geometryByPrimitive.set(primitive, geometryId);

package/src/scene.ts

@@ -1,4 +1,5 @@
 import type { Node, Scene } from '@gltf-transform/core';
+import type { quat as Quat, vec3 as Vec3 } from 'gl-matrix';
 import {
   create3DEntity,
   create3DModel,
@@ -6,16 +7,19 @@ import {
   set3DParent,
   update3DTransform,
   type EntityId,
-  type World3DId,
+  type World3DId
 } from '@vulfram/engine/world3d';
-import { toArray3, toArray4 } from './convert';
+import { toQuat, toVec3 } from './convert';
 import { ensureMaterial, ensurePrimitiveGeometry } from './resources';
-import type {
-  GltfInstance,
-  GltfInstantiateOptions,
-  LoaderContext,
-  SceneTemplate,
-} from './types';
+import type { GltfInstance, GltfInstantiateOptions, LoaderContext, SceneTemplate } from './types';
+
+function isIdentityVec3(value: Vec3, identity: number): boolean {
+  return value[0] === identity && value[1] === identity && value[2] === identity;
+}
+
+function isIdentityQuat(value: Quat): boolean {
+  return value[0] === 0 && value[1] === 0 && value[2] === 0 && value[3] === 1;
+}
 
 function createNodeTemplate(ctx: LoaderContext, node: Node, nodes: SceneTemplate['nodes']): number {
   const mesh = node.getMesh();
@@ -33,11 +37,11 @@ function createNodeTemplate(ctx: LoaderContext, node: Node, nodes: SceneTemplate
   const nodeIndex = nodes.length;
   nodes.push({
     name: node.getName() || undefined,
-    translation: toArray3(node.getTranslation()),
-    rotation: toArray4(node.getRotation(), 1),
-    scale: toArray3(node.getScale()),
+    translation: toVec3(node.getTranslation()),
+    rotation: toQuat(node.getRotation(), 1),
+    scale: toVec3(node.getScale()),
     children: [],
-    primitives,
+    primitives
   });
 
   for (const child of node.listChildren()) {
@@ -63,21 +67,18 @@ export function buildSceneTemplate(ctx: LoaderContext, scene: Scene): SceneTempl
 function setInstanceRootTransform(
   worldId: World3DId,
   rootEntityId: EntityId,
-  options: GltfInstantiateOptions | undefined,
+  options: GltfInstantiateOptions | undefined
 ): void {
   const rootTransform = options?.rootTransform;
-  update3DTransform(worldId, rootEntityId, {
-    position: rootTransform?.position ?? [0, 0, 0],
-    rotation: rootTransform?.rotation ?? [0, 0, 0, 1],
-    scale: rootTransform?.scale ?? [1, 1, 1],
-  });
+  if (!rootTransform) return;
+  update3DTransform(worldId, rootEntityId, rootTransform);
 }
 
 /** Instantiates entities/models/parents from a previously built scene template. */
 export function instantiateTemplate(
   worldId: World3DId,
   template: SceneTemplate,
-  options?: GltfInstantiateOptions,
+  options?: GltfInstantiateOptions
 ): GltfInstance {
   const entityIds: EntityId[] = [];
   let disposed = false;
@@ -96,11 +97,12 @@ export function instantiateTemplate(
     nodeEntityIds[i] = nodeEntityId;
     entityIds.push(nodeEntityId);
 
-    update3DTransform(worldId, nodeEntityId, {
-      position: node.translation,
-      rotation: node.rotation,
-      scale: node.scale,
-    });
+    const transformPatch = {
+      position: isIdentityVec3(node.translation, 0) ? undefined : node.translation,
+      rotation: isIdentityQuat(node.rotation) ? undefined : node.rotation,
+      scale: isIdentityVec3(node.scale, 1) ? undefined : node.scale
+    };
+    update3DTransform(worldId, nodeEntityId, transformPatch);
   }
 
   for (const rootIndex of template.roots) {
@@ -126,7 +128,7 @@ export function instantiateTemplate(
       const primitive = node.primitives[0]!;
       create3DModel(worldId, parentEntity, {
         geometryId: primitive.geometryId,
-        materialId: primitive.materialId,
+        materialId: primitive.materialId
       });
       continue;
     }
@@ -134,15 +136,10 @@ export function instantiateTemplate(
     for (const primitive of node.primitives) {
       const modelEntity = create3DEntity(worldId);
       entityIds.push(modelEntity);
-      update3DTransform(worldId, modelEntity, {
-        position: [0, 0, 0],
-        rotation: [0, 0, 0, 1],
-        scale: [1, 1, 1],
-      });
       set3DParent(worldId, modelEntity, parentEntity);
       create3DModel(worldId, modelEntity, {
         geometryId: primitive.geometryId,
-        materialId: primitive.materialId,
+        materialId: primitive.materialId
       });
     }
   }
@@ -159,6 +156,6 @@ export function instantiateTemplate(
           remove3DEntity(worldId, entityId);
         }
       }
-    },
+    }
   };
 }

package/src/types.ts

@@ -1,10 +1,11 @@
 import type { Accessor, Material, Node, Primitive, Texture } from '@gltf-transform/core';
+import type { quat, vec3 } from 'gl-matrix';
 import type {
   EntityId,
   GeometryId,
   MaterialId,
   TextureId,
-  World3DId,
+  World3DId
 } from '@vulfram/engine/world3d';
 
 /** Supported source formats for glTF scene loading. */
@@ -15,9 +16,9 @@ export type BinaryLike = Uint8Array | ArrayBuffer | ArrayBufferView;
 
 /** Optional root transform applied to the imported scene root entity. */
 export type RootTransform = {
-  position?: [number, number, number];
-  rotation?: [number, number, number, number];
-  scale?: [number, number, number];
+  position?: vec3;
+  rotation?: quat;
+  scale?: vec3;
 };
 
 /** Instantiation options for a loaded glTF asset template. */
@@ -35,9 +36,9 @@ export interface GltfInstance {
 /** Static template node with local transform and mesh primitive bindings. */
 export interface NodeTemplate {
   name?: string;
-  translation: [number, number, number];
-  rotation: [number, number, number, number];
-  scale: [number, number, number];
+  translation: vec3;
+  rotation: quat;
+  scale: vec3;
   children: number[];
   primitives: Array<{
     geometryId: GeometryId;

package/tsconfig.json

@@ -1,7 +1,11 @@
 {
   "compilerOptions": {
-    "lib": ["ESNext"],
-    "types": ["bun"],
+    "lib": [
+      "ESNext"
+    ],
+    "types": [
+      "bun"
+    ],
     "target": "ESNext",
     "module": "Preserve",
     "moduleDetection": "force",
@@ -16,5 +20,7 @@
     "noUncheckedIndexedAccess": true,
     "noImplicitOverride": true
   },
-  "include": ["src"]
-}
+  "include": [
+    "src"
+  ]
+}