@vulfram/gltf-loader 0.19.1-alpha

package/README.md

@@ -0,0 +1,5 @@
+# @vulfram/gltf-loader
+
+Loads `.gltf` and `.glb` content into `@vulfram/engine` 3D worlds.
+
+Status: initial package scaffold. Runtime loading is not implemented yet.

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@vulfram/gltf-loader",
+  "version": "0.19.1-alpha",
+  "module": "src/index.ts",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@vulfram/engine": "^0.19.2-alpha"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.10",
+    "@vulfram/engine": "^0.19.2-alpha"
+  },
+  "dependencies": {
+    "@gltf-transform/core": "^4.3.0",
+    "@gltf-transform/extensions": "^4.3.0",
+    "@gltf-transform/functions": "^4.3.0"
+  }
+}

package/src/binary.ts

@@ -0,0 +1,70 @@
+import { GLB_MAGIC, GLB_VERSION_2 } from './constants';
+import { GltfLoaderError } from './errors';
+import type { BinaryLike, GltfSourceFormat } from './types';
+
+/** Converts supported binary-like inputs to Uint8Array with zero-copy when possible. */
+export function toUint8Array(data: BinaryLike): Uint8Array {
+  if (data instanceof Uint8Array) return data;
+  if (data instanceof ArrayBuffer) return new Uint8Array(data);
+  if (ArrayBuffer.isView(data)) {
+    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+  }
+  throw new GltfLoaderError('INVALID_INPUT', 'Unsupported binary input type.');
+}
+
+/** Detects whether payload appears to be .glb or .gltf JSON. */
+export function detectFormat(bytes: Uint8Array): GltfSourceFormat {
+  if (bytes.byteLength >= 12) {
+    const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const magic = dv.getUint32(0, true);
+    const version = dv.getUint32(4, true);
+    if (magic === GLB_MAGIC && version === GLB_VERSION_2) {
+      return 'glb';
+    }
+  }
+
+  for (let i = 0; i < bytes.length; i++) {
+    const c = bytes[i];
+    if (c === undefined) continue;
+    if (c <= 0x20) continue;
+    if (c === 0x7b) return 'gltf'; // '{'
+    break;
+  }
+
+  throw new GltfLoaderError(
+    'UNSUPPORTED_FORMAT',
+    'Unable to detect glTF format from payload bytes.',
+  );
+}
+
+/** Decodes data URI payload into raw bytes. */
+export function decodeDataUri(uri: string): Uint8Array {
+  if (!uri.startsWith('data:')) {
+    throw new GltfLoaderError('UNSUPPORTED_FORMAT', `Invalid data URI: ${uri}`);
+  }
+  const commaIdx = uri.indexOf(',');
+  if (commaIdx < 0) {
+    throw new GltfLoaderError('UNSUPPORTED_FORMAT', `Malformed data URI: ${uri}`);
+  }
+
+  const meta = uri.slice('data:'.length, commaIdx);
+  const payload = uri.slice(commaIdx + 1);
+  const isBase64 = meta.includes(';base64');
+
+  if (isBase64) {
+    return new Uint8Array(Buffer.from(payload, 'base64'));
+  }
+  return new Uint8Array(Buffer.from(decodeURIComponent(payload), 'utf8'));
+}
+
+/** Normalizes external resource map to Uint8Array values. */
+export function normalizeResourceMap(
+  resources?: Record<string, BinaryLike>,
+): Record<string, Uint8Array> {
+  if (!resources) return {};
+  const out: Record<string, Uint8Array> = {};
+  for (const [key, value] of Object.entries(resources)) {
+    out[key] = toUint8Array(value);
+  }
+  return out;
+}

package/src/constants.ts

@@ -0,0 +1,4 @@
+export const GLB_MAGIC = 0x46546c67;
+export const GLB_VERSION_2 = 2;
+export const BUFFER_ID_BASE = 100_000_000;
+export const U16_MAX = 0xffff;

package/src/context.ts

@@ -0,0 +1,48 @@
+import { uploadBuffer } from '@vulfram/engine/core';
+import { BUFFER_ID_BASE } from './constants';
+import type { GltfLoadInput, LoaderContext } from './types';
+
+let nextUploadBufferId = BUFFER_ID_BASE;
+
+/** Creates mutable loader context for one import operation. */
+export function createContext(input: GltfLoadInput): LoaderContext {
+  return {
+    worldId: input.worldId,
+    warnings: [],
+    labelPrefix: input.labelPrefix ?? 'gltf',
+    materialMode: input.materialMode ?? 'pbr',
+    defaultMaterialId: undefined,
+    geometryByPrimitive: new WeakMap(),
+    materialBySource: new WeakMap(),
+    textureBySource: new WeakMap(),
+    textureColorSpaceHint: new WeakMap(),
+    uploadedVertexByAccessor: new WeakMap(),
+    uploadedIndexByAccessor: new WeakMap(),
+    createdGeometryIds: new Set(),
+    createdMaterialIds: new Set(),
+    createdTextureIds: new Set(),
+    counters: {
+      entities: 0,
+      geometries: 0,
+      materials: 0,
+      textures: 0,
+    },
+  };
+}
+
+function allocBufferId(): number {
+  const id = nextUploadBufferId;
+  nextUploadBufferId += 1;
+  return id;
+}
+
+/** Uploads bytes to engine buffer system and returns allocated buffer id. */
+export function uploadBytes(
+  _ctx: LoaderContext,
+  usage: 'image-data' | 'vertex-data' | 'index-data',
+  bytes: Uint8Array,
+): number {
+  const bufferId = allocBufferId();
+  uploadBuffer(bufferId, usage, bytes);
+  return bufferId;
+}

package/src/convert.ts

@@ -0,0 +1,167 @@
+import { Accessor, TextureInfo } from '@gltf-transform/core';
+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 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 semanticToPrimitiveType(
+  semantic: string,
+): GeometryPrimitiveEntry['primitiveType'] | null {
+  switch (semantic) {
+    case 'POSITION':
+      return 'position';
+    case 'NORMAL':
+      return 'normal';
+    case 'TANGENT':
+      return 'tangent';
+    case 'COLOR_0':
+      return 'color';
+    case 'TEXCOORD_0':
+    case 'TEXCOORD_1':
+      return 'u-v';
+    case 'JOINTS_0':
+      return 'skin-joints';
+    case 'WEIGHTS_0':
+      return 'skin-weights';
+    default:
+      return null;
+  }
+}
+
+export function samplerFromTextureInfo(
+  info: {
+    getWrapS(): number;
+    getWrapT(): number;
+    getMagFilter(): number | null;
+    getMinFilter(): number | null;
+  } | null,
+): SamplerMode {
+  const WRAP_REPEAT = TextureInfo.WrapMode.REPEAT;
+  const WRAP_MIRRORED_REPEAT = TextureInfo.WrapMode.MIRRORED_REPEAT;
+  const MAG_LINEAR = TextureInfo.MagFilter.LINEAR;
+  const MIN_LINEAR = TextureInfo.MinFilter.LINEAR;
+  const MIN_LINEAR_MIPMAP_LINEAR = TextureInfo.MinFilter.LINEAR_MIPMAP_LINEAR;
+  const MIN_LINEAR_MIPMAP_NEAREST = TextureInfo.MinFilter.LINEAR_MIPMAP_NEAREST;
+
+  const wrapS = info?.getWrapS() ?? WRAP_REPEAT;
+  const wrapT = info?.getWrapT() ?? WRAP_REPEAT;
+  const mag = info?.getMagFilter();
+  const min = info?.getMinFilter();
+
+  const 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;
+
+  if (repeat) return linear ? 'linear-repeat' : 'point-repeat';
+  return linear ? 'linear-clamp' : 'point-clamp';
+}
+
+export function asBytes(array: ArrayBufferView): Uint8Array {
+  return new Uint8Array(array.buffer, array.byteOffset, array.byteLength);
+}
+
+function toFloatArray(accessor: Accessor, components: number, fillTail = 0): Float32Array {
+  const count = accessor.getCount();
+  const srcArray = accessor.getArray();
+  const elementSize = accessor.getElementSize();
+
+  if (
+    srcArray instanceof Float32Array
+    && !accessor.getNormalized()
+    && elementSize === components
+  ) {
+    return srcArray;
+  }
+
+  const out = new Float32Array(count * components);
+  const tmp: number[] = [];
+  for (let i = 0; i < count; i++) {
+    accessor.getElement(i, tmp);
+    for (let c = 0; c < components; c++) {
+      const v = tmp[c];
+      out[i * components + c] = v ?? (c === 3 ? 1 : fillTail);
+    }
+  }
+  return out;
+}
+
+function toUint16Vec4(accessor: Accessor): Uint16Array {
+  const count = accessor.getCount();
+  const out = new Uint16Array(count * 4);
+  const srcArray = accessor.getArray();
+
+  if (srcArray instanceof Uint16Array && accessor.getElementSize() === 4) {
+    return srcArray;
+  }
+
+  const tmp: number[] = [];
+  for (let i = 0; i < count; i++) {
+    accessor.getElement(i, tmp);
+    out[i * 4 + 0] = Math.max(0, Math.min(U16_MAX, Math.round(tmp[0] ?? 0)));
+    out[i * 4 + 1] = Math.max(0, Math.min(U16_MAX, Math.round(tmp[1] ?? 0)));
+    out[i * 4 + 2] = Math.max(0, Math.min(U16_MAX, Math.round(tmp[2] ?? 0)));
+    out[i * 4 + 3] = Math.max(0, Math.min(U16_MAX, Math.round(tmp[3] ?? 0)));
+  }
+  return out;
+}
+
+function toUint32Indices(accessor: Accessor): Uint32Array {
+  const src = accessor.getArray();
+  if (!src) {
+    throw new GltfLoaderError('PARSE_ERROR', 'Index accessor has no backing array.');
+  }
+  if (src instanceof Uint32Array) {
+    return src;
+  }
+  const out = new Uint32Array(src.length);
+  for (let i = 0; i < src.length; i++) {
+    out[i] = src[i] ?? 0;
+  }
+  return out;
+}
+
+/** Converts accessor data to core-compatible stream bytes by semantic. */
+export function accessorToStreamBytes(accessor: Accessor, semantic: string): Uint8Array {
+  if (semantic === 'POSITION' || semantic === 'NORMAL') {
+    return asBytes(toFloatArray(accessor, 3));
+  }
+  if (semantic === 'TANGENT') {
+    return asBytes(toFloatArray(accessor, 4));
+  }
+  if (semantic === 'COLOR_0') {
+    return asBytes(toFloatArray(accessor, 4, 1));
+  }
+  if (semantic === 'TEXCOORD_0' || semantic === 'TEXCOORD_1') {
+    return asBytes(toFloatArray(accessor, 2));
+  }
+  if (semantic === 'JOINTS_0') {
+    return asBytes(toUint16Vec4(accessor));
+  }
+  if (semantic === 'WEIGHTS_0') {
+    return asBytes(toFloatArray(accessor, 4));
+  }
+
+  throw new GltfLoaderError('UNSUPPORTED_FEATURE', `Unsupported accessor semantic: ${semantic}`);
+}
+
+/** Converts glTF index accessor to u32 index stream bytes required by core. */
+export function accessorToIndexBytes(accessor: Accessor): Uint8Array {
+  return asBytes(toUint32Indices(accessor));
+}

package/src/errors.ts

@@ -0,0 +1,9 @@
+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) {
+    super(message);
+    this.name = 'GltfLoaderError';
+  }
+}

package/src/index.ts

@@ -0,0 +1,129 @@
+import {
+  dispose3DGeometry,
+  dispose3DMaterial,
+  dispose3DTexture,
+} from '@vulfram/engine/world3d';
+import { createContext } from './context';
+import { GltfLoaderError } from './errors';
+import { readDocument } from './parse';
+import { buildSceneTemplate, instantiateTemplate } from './scene';
+import type {
+  GltfInstantiateOptions,
+  GltfLoadInput,
+  GltfLoadResult,
+  GltfInstance,
+  LoadedGltfAsset,
+} from './types';
+
+export type {
+  BinaryLike,
+  GltfInstantiateOptions,
+  GltfInstance,
+  GltfLoadInput,
+  GltfLoadResult,
+  GltfLoaderErrorCode,
+  LoadedGltfAsset,
+  LoadedResourceIds,
+  NodeTemplate,
+  SceneTemplate,
+  GltfSourceFormat,
+  RootTransform,
+} from './types';
+export { GltfLoaderError } from './errors';
+
+/**
+ * Loads glTF/GLB resources and returns a reusable asset template.
+ *
+ * The returned asset can instantiate entity graphs multiple times, reusing
+ * uploaded textures/materials/geometries across instances.
+ */
+export async function loadGltfAsset(input: GltfLoadInput): Promise<LoadedGltfAsset> {
+  const document = await readDocument(input);
+  const ctx = createContext(input);
+
+  const root = document.getRoot();
+  const scene = root.getDefaultScene() ?? root.listScenes()[0] ?? null;
+  if (!scene) {
+    throw new GltfLoaderError('PARSE_ERROR', 'Document has no scene to import.');
+  }
+
+  const template = buildSceneTemplate(ctx, scene);
+  const instances = new Set<GltfInstance>();
+  let disposedAll = false;
+
+  const disposeEntities = () => {
+    for (const instance of [...instances]) {
+      instance.disposeEntities();
+      instances.delete(instance);
+    }
+  };
+
+  const disposeAll = () => {
+    if (disposedAll) return;
+    disposedAll = true;
+    disposeEntities();
+
+    for (const geometryId of ctx.createdGeometryIds) {
+      dispose3DGeometry(input.worldId, geometryId);
+    }
+    for (const materialId of ctx.createdMaterialIds) {
+      dispose3DMaterial(input.worldId, materialId);
+    }
+    for (const textureId of ctx.createdTextureIds) {
+      dispose3DTexture(input.worldId, textureId);
+    }
+  };
+
+  const instantiate = (options?: GltfInstantiateOptions): GltfInstance => {
+    if (disposedAll) {
+      throw new GltfLoaderError(
+        'INVALID_INPUT',
+        'Cannot instantiate from a disposed glTF asset. Load it again.',
+      );
+    }
+
+    const instance = instantiateTemplate(input.worldId, template, options);
+    const originalDispose = instance.disposeEntities;
+    instance.disposeEntities = () => {
+      originalDispose();
+      instances.delete(instance);
+    };
+    instances.add(instance);
+    return instance;
+  };
+
+  return {
+    worldId: input.worldId,
+    warnings: ctx.warnings,
+    template,
+    resources: {
+      geometries: [...ctx.createdGeometryIds],
+      materials: [...ctx.createdMaterialIds],
+      textures: [...ctx.createdTextureIds],
+    },
+    instantiate,
+    disposeEntities,
+    disposeAll,
+  };
+}
+
+/**
+ * Legacy one-shot API.
+ *
+ * Loads resources and immediately instantiates one entity graph.
+ */
+export async function loadGltfScene(input: GltfLoadInput): Promise<GltfLoadResult> {
+  const asset = await loadGltfAsset(input);
+  const instance = asset.instantiate({
+    rootTransform: input.rootTransform,
+  });
+
+  return {
+    rootEntityId: instance.rootEntityId,
+    entityCount: instance.entityIds.length,
+    geometryCount: asset.resources.geometries.length,
+    materialCount: asset.resources.materials.length,
+    textureCount: asset.resources.textures.length,
+    warnings: asset.warnings,
+  };
+}

package/src/parse.ts

@@ -0,0 +1,63 @@
+import { WebIO, type Document, type GLTF, type JSONDocument } from '@gltf-transform/core';
+import { decodeDataUri, detectFormat, normalizeResourceMap, toUint8Array } from './binary';
+import { GltfLoaderError } from './errors';
+import type { GltfLoadInput } from './types';
+
+function parseGltfJsonDocument(
+  bytes: Uint8Array,
+  resources?: Record<string, import('./types').BinaryLike>,
+): JSONDocument {
+  const decoder = new TextDecoder('utf-8');
+  let json: GLTF.IGLTF;
+  try {
+    json = JSON.parse(decoder.decode(bytes)) as GLTF.IGLTF;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new GltfLoaderError('PARSE_ERROR', `Failed parsing glTF JSON: ${message}`);
+  }
+
+  const resourceMap = normalizeResourceMap(resources);
+
+  const registerUri = (uri: string) => {
+    if (resourceMap[uri]) return;
+    if (uri.startsWith('data:')) {
+      resourceMap[uri] = decodeDataUri(uri);
+      return;
+    }
+    throw new GltfLoaderError(
+      'MISSING_RESOURCE',
+      `External resource not provided for URI "${uri}". Provide it in input.resources.`,
+    );
+  };
+
+  for (const buffer of json.buffers ?? []) {
+    if (buffer.uri) registerUri(buffer.uri);
+  }
+  for (const image of json.images ?? []) {
+    if (image.uri) registerUri(image.uri);
+  }
+
+  return {
+    json,
+    resources: resourceMap as unknown as { [s: string]: Uint8Array<ArrayBuffer> },
+  };
+}
+
+/** Reads input payload into a glTF Transform document. */
+export async function readDocument(input: GltfLoadInput): Promise<Document> {
+  const io = new WebIO();
+  const bytes = toUint8Array(input.data);
+  const format = input.format ?? detectFormat(bytes);
+
+  try {
+    if (format === 'glb') {
+      return await io.readBinary(bytes);
+    }
+    const jsonDoc = parseGltfJsonDocument(bytes, input.resources);
+    return await io.readJSON(jsonDoc);
+  } catch (error) {
+    if (error instanceof GltfLoaderError) throw error;
+    const message = error instanceof Error ? error.message : String(error);
+    throw new GltfLoaderError('PARSE_ERROR', `Failed to read glTF document: ${message}`);
+  }
+}

package/src/resources.ts

@@ -0,0 +1,295 @@
+import { Primitive, type Accessor, type Material, type Texture } from '@gltf-transform/core';
+import {
+  create3DGeometry,
+  create3DMaterial,
+  create3DTexture,
+  type GeometryId,
+  type MaterialId,
+  type TextureId,
+} from '@vulfram/engine/world3d';
+import type { GeometryPrimitiveEntry } from '@vulfram/engine/types';
+import { uploadBytes } from './context';
+import {
+  accessorToIndexBytes,
+  accessorToStreamBytes,
+  samplerFromTextureInfo,
+  semanticToPrimitiveType,
+  toArray4,
+} from './convert';
+import type { LoaderContext } from './types';
+
+function uploadVertexAccessor(
+  ctx: LoaderContext,
+  accessor: Accessor,
+  semantic: string,
+): number {
+  const cached = ctx.uploadedVertexByAccessor.get(accessor);
+  if (cached !== undefined) return cached;
+
+  const bytes = accessorToStreamBytes(accessor, semantic);
+  const bufferId = uploadBytes(ctx, 'vertex-data', bytes);
+  ctx.uploadedVertexByAccessor.set(accessor, bufferId);
+  return bufferId;
+}
+
+function uploadIndexAccessor(ctx: LoaderContext, accessor: Accessor): number {
+  const cached = ctx.uploadedIndexByAccessor.get(accessor);
+  if (cached !== undefined) return cached;
+
+  const bytes = accessorToIndexBytes(accessor);
+  const bufferId = uploadBytes(ctx, 'index-data', bytes);
+  ctx.uploadedIndexByAccessor.set(accessor, bufferId);
+  return bufferId;
+}
+
+/** Ensures a core texture exists for source texture. */
+export function ensureTexture(
+  ctx: LoaderContext,
+  texture: Texture,
+  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}).`,
+      );
+    }
+    return existing;
+  }
+
+  const image = texture.getImage();
+  if (!image) {
+    ctx.warnings.push(
+      `Texture "${texture.getName() || 'unnamed'}" has no image bytes and was skipped.`,
+    );
+    return null;
+  }
+
+  const bufferId = uploadBytes(ctx, 'image-data', image);
+  const textureId = create3DTexture(ctx.worldId, {
+    label: `${ctx.labelPrefix}:tex:${texture.getName() || 'unnamed'}`,
+    source: { type: 'buffer', bufferId },
+    srgb,
+    mode: 'standalone',
+  });
+
+  ctx.textureBySource.set(texture, textureId);
+  ctx.textureColorSpaceHint.set(texture, srgb);
+  ctx.createdTextureIds.add(textureId);
+  ctx.counters.textures += 1;
+  return textureId;
+}
+
+function alphaModeToSurfaceType(alphaMode: string): 'opaque' | 'transparent' | 'masked' {
+  if (alphaMode === 'BLEND') return 'transparent';
+  if (alphaMode === 'MASK') return 'masked';
+  return 'opaque';
+}
+
+function ensureDefaultMaterial(ctx: LoaderContext): MaterialId {
+  if (ctx.defaultMaterialId !== undefined) return ctx.defaultMaterialId;
+
+  if (ctx.materialMode === 'standard') {
+    const id = create3DMaterial(ctx.worldId, {
+      kind: 'standard',
+      label: `${ctx.labelPrefix}:mat:default`,
+      options: {
+        type: 'standard',
+        content: {
+          baseColor: [1, 1, 1, 1],
+          surfaceType: 'opaque',
+          flags: 0,
+        },
+      },
+    });
+
+    ctx.defaultMaterialId = id;
+    ctx.createdMaterialIds.add(id);
+    ctx.counters.materials += 1;
+    return id;
+  }
+
+  const id = create3DMaterial(ctx.worldId, {
+    kind: 'pbr',
+    label: `${ctx.labelPrefix}:mat:default`,
+    options: {
+      type: 'pbr',
+      content: {
+        baseColor: [1, 1, 1, 1],
+        surfaceType: 'opaque',
+        emissiveColor: [0, 0, 0, 1],
+        metallic: 0,
+        roughness: 1,
+        ao: 1,
+        normalScale: 1,
+        flags: 0,
+      },
+    },
+  });
+
+  ctx.defaultMaterialId = id;
+  ctx.createdMaterialIds.add(id);
+  ctx.counters.materials += 1;
+  return id;
+}
+
+/** Ensures a core material exists for source material. */
+export function ensureMaterial(ctx: LoaderContext, material: Material | null): MaterialId {
+  if (!material) return ensureDefaultMaterial(ctx);
+
+  const existing = ctx.materialBySource.get(material);
+  if (existing !== undefined) return existing;
+
+  const baseTexture = material.getBaseColorTexture();
+  const normalTexture = material.getNormalTexture();
+  const mrTexture = material.getMetallicRoughnessTexture();
+  const emissiveTexture = material.getEmissiveTexture();
+  const aoTexture = material.getOcclusionTexture();
+
+  const baseTexId = baseTexture ? ensureTexture(ctx, baseTexture, true) : null;
+  const normalTexId = normalTexture ? ensureTexture(ctx, normalTexture, false) : null;
+  const mrTexId = mrTexture ? ensureTexture(ctx, mrTexture, false) : null;
+  const emissiveTexId = emissiveTexture ? ensureTexture(ctx, emissiveTexture, true) : null;
+  const aoTexId = aoTexture ? ensureTexture(ctx, aoTexture, false) : null;
+
+  const baseSampler = samplerFromTextureInfo(material.getBaseColorTextureInfo());
+  const normalSampler = samplerFromTextureInfo(material.getNormalTextureInfo());
+  const mrSampler = samplerFromTextureInfo(material.getMetallicRoughnessTextureInfo());
+  const emissiveSampler = samplerFromTextureInfo(material.getEmissiveTextureInfo());
+  const aoSampler = samplerFromTextureInfo(material.getOcclusionTextureInfo());
+  const emissiveFactor = material.getEmissiveFactor();
+
+  const materialId = create3DMaterial(ctx.worldId, {
+    kind: ctx.materialMode === 'pbr' ? 'pbr' : 'standard',
+    label: `${ctx.labelPrefix}:mat:${material.getName() || 'unnamed'}`,
+    options: {
+      ...(ctx.materialMode === 'pbr'
+        ? {
+            type: 'pbr' as const,
+            content: {
+              baseColor: toArray4(material.getBaseColorFactor(), 1),
+              surfaceType: alphaModeToSurfaceType(material.getAlphaMode()),
+              emissiveColor: [
+                emissiveFactor[0] ?? 0,
+                emissiveFactor[1] ?? 0,
+                emissiveFactor[2] ?? 0,
+                1,
+              ] as [number, number, number, number],
+              metallic: material.getMetallicFactor(),
+              roughness: material.getRoughnessFactor(),
+              ao: material.getOcclusionStrength(),
+              normalScale: material.getNormalScale(),
+              baseTexId,
+              baseSampler,
+              normalTexId,
+              normalSampler,
+              metallicRoughnessTexId: mrTexId,
+              metallicRoughnessSampler: mrSampler,
+              emissiveTexId,
+              emissiveSampler,
+              aoTexId,
+              aoSampler,
+              flags: material.getDoubleSided() ? 1 : 0,
+            },
+          }
+        : {
+            type: 'standard' as const,
+            content: {
+              baseColor: toArray4(material.getBaseColorFactor(), 1),
+              surfaceType: alphaModeToSurfaceType(material.getAlphaMode()),
+              specColor: [
+                material.getMetallicFactor(),
+                material.getRoughnessFactor(),
+                material.getOcclusionStrength(),
+                1,
+              ] as [number, number, number, number],
+              specPower: 32,
+              baseTexId,
+              baseSampler,
+              normalTexId,
+              normalSampler,
+              specTexId: mrTexId,
+              specSampler: mrSampler,
+              flags: material.getDoubleSided() ? 1 : 0,
+            },
+          }),
+    },
+  });
+
+  ctx.materialBySource.set(material, materialId);
+  ctx.createdMaterialIds.add(materialId);
+  ctx.counters.materials += 1;
+  return materialId;
+}
+
+/** Ensures a core geometry exists for source primitive. */
+export function ensurePrimitiveGeometry(
+  ctx: LoaderContext,
+  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.`,
+    );
+    return null;
+  }
+
+  const entries: GeometryPrimitiveEntry[] = [];
+  const indexAccessor = primitive.getIndices();
+  if (indexAccessor) {
+    entries.push({
+      primitiveType: 'index',
+      bufferId: uploadIndexAccessor(ctx, indexAccessor),
+    });
+  }
+
+  const orderedSemantics = [
+    'POSITION',
+    'NORMAL',
+    'TANGENT',
+    'COLOR_0',
+    'TEXCOORD_0',
+    'TEXCOORD_1',
+  ] as const;
+
+  let hasPosition = false;
+
+  for (const semantic of orderedSemantics) {
+    const accessor = primitive.getAttribute(semantic);
+    if (!accessor) continue;
+
+    const primitiveType = semanticToPrimitiveType(semantic);
+    if (!primitiveType) {
+      ctx.warnings.push(`Unsupported semantic "${semantic}" ignored.`);
+      continue;
+    }
+
+    if (semantic === 'POSITION') hasPosition = true;
+
+    entries.push({
+      primitiveType,
+      bufferId: uploadVertexAccessor(ctx, accessor, semantic),
+    });
+  }
+
+  if (!hasPosition) {
+    ctx.warnings.push('Primitive without POSITION stream skipped.');
+    return null;
+  }
+
+  const geometryId = create3DGeometry(ctx.worldId, {
+    type: 'custom',
+    label: `${ctx.labelPrefix}:geo:${primitive.getName() || 'unnamed'}`,
+    entries,
+  });
+
+  ctx.geometryByPrimitive.set(primitive, geometryId);
+  ctx.createdGeometryIds.add(geometryId);
+  ctx.counters.geometries += 1;
+  return geometryId;
+}

package/src/scene.ts

@@ -0,0 +1,164 @@
+import type { Node, Scene } from '@gltf-transform/core';
+import {
+  create3DEntity,
+  create3DModel,
+  remove3DEntity,
+  set3DParent,
+  update3DTransform,
+  type EntityId,
+  type World3DId,
+} from '@vulfram/engine/world3d';
+import { toArray3, toArray4 } from './convert';
+import { ensureMaterial, ensurePrimitiveGeometry } from './resources';
+import type {
+  GltfInstance,
+  GltfInstantiateOptions,
+  LoaderContext,
+  SceneTemplate,
+} from './types';
+
+function createNodeTemplate(ctx: LoaderContext, node: Node, nodes: SceneTemplate['nodes']): number {
+  const mesh = node.getMesh();
+  const primitives: SceneTemplate['nodes'][number]['primitives'] = [];
+
+  if (mesh) {
+    for (const primitive of mesh.listPrimitives()) {
+      const geometryId = ensurePrimitiveGeometry(ctx, primitive);
+      if (!geometryId) continue;
+      const materialId = ensureMaterial(ctx, primitive.getMaterial());
+      primitives.push({ geometryId, materialId });
+    }
+  }
+
+  const nodeIndex = nodes.length;
+  nodes.push({
+    name: node.getName() || undefined,
+    translation: toArray3(node.getTranslation()),
+    rotation: toArray4(node.getRotation(), 1),
+    scale: toArray3(node.getScale()),
+    children: [],
+    primitives,
+  });
+
+  for (const child of node.listChildren()) {
+    const childIndex = createNodeTemplate(ctx, child, nodes);
+    nodes[nodeIndex]!.children.push(childIndex);
+  }
+
+  return nodeIndex;
+}
+
+/** Builds an immutable scene template and uploads all required resources. */
+export function buildSceneTemplate(ctx: LoaderContext, scene: Scene): SceneTemplate {
+  const nodes: SceneTemplate['nodes'] = [];
+  const roots: number[] = [];
+
+  for (const node of scene.listChildren()) {
+    roots.push(createNodeTemplate(ctx, node, nodes));
+  }
+
+  return { roots, nodes };
+}
+
+function setInstanceRootTransform(
+  worldId: World3DId,
+  rootEntityId: EntityId,
+  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],
+  });
+}
+
+/** Instantiates entities/models/parents from a previously built scene template. */
+export function instantiateTemplate(
+  worldId: World3DId,
+  template: SceneTemplate,
+  options?: GltfInstantiateOptions,
+): GltfInstance {
+  const entityIds: EntityId[] = [];
+  let disposed = false;
+
+  const rootEntityId = create3DEntity(worldId);
+  entityIds.push(rootEntityId);
+  setInstanceRootTransform(worldId, rootEntityId, options);
+
+  const nodeEntityIds: EntityId[] = new Array(template.nodes.length);
+
+  for (let i = 0; i < template.nodes.length; i++) {
+    const node = template.nodes[i];
+    if (!node) continue;
+
+    const nodeEntityId = create3DEntity(worldId);
+    nodeEntityIds[i] = nodeEntityId;
+    entityIds.push(nodeEntityId);
+
+    update3DTransform(worldId, nodeEntityId, {
+      position: node.translation,
+      rotation: node.rotation,
+      scale: node.scale,
+    });
+  }
+
+  for (const rootIndex of template.roots) {
+    const rootNodeEntity = nodeEntityIds[rootIndex];
+    if (rootNodeEntity === undefined) continue;
+    set3DParent(worldId, rootNodeEntity, rootEntityId);
+  }
+
+  for (let i = 0; i < template.nodes.length; i++) {
+    const node = template.nodes[i];
+    const parentEntity = nodeEntityIds[i];
+    if (!node || parentEntity === undefined) continue;
+
+    for (const childIndex of node.children) {
+      const childEntity = nodeEntityIds[childIndex];
+      if (childEntity === undefined) continue;
+      set3DParent(worldId, childEntity, parentEntity);
+    }
+
+    if (node.primitives.length === 0) continue;
+
+    if (node.primitives.length === 1) {
+      const primitive = node.primitives[0]!;
+      create3DModel(worldId, parentEntity, {
+        geometryId: primitive.geometryId,
+        materialId: primitive.materialId,
+      });
+      continue;
+    }
+
+    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,
+      });
+    }
+  }
+
+  return {
+    rootEntityId,
+    entityIds,
+    disposeEntities() {
+      if (disposed) return;
+      disposed = true;
+      for (let i = entityIds.length - 1; i >= 0; i--) {
+        const entityId = entityIds[i];
+        if (entityId !== undefined) {
+          remove3DEntity(worldId, entityId);
+        }
+      }
+    },
+  };
+}

package/src/types.ts

@@ -0,0 +1,124 @@
+import type { Accessor, Material, Node, Primitive, Texture } from '@gltf-transform/core';
+import type {
+  EntityId,
+  GeometryId,
+  MaterialId,
+  TextureId,
+  World3DId,
+} from '@vulfram/engine/world3d';
+
+/** Supported source formats for glTF scene loading. */
+export type GltfSourceFormat = 'gltf' | 'glb';
+
+/** Binary-like payload accepted by the loader. */
+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];
+};
+
+/** Instantiation options for a loaded glTF asset template. */
+export interface GltfInstantiateOptions {
+  rootTransform?: RootTransform;
+}
+
+/** One instantiated scene graph from a loaded glTF asset. */
+export interface GltfInstance {
+  rootEntityId: EntityId;
+  entityIds: EntityId[];
+  disposeEntities(): void;
+}
+
+/** 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];
+  children: number[];
+  primitives: Array<{
+    geometryId: GeometryId;
+    materialId: MaterialId;
+  }>;
+}
+
+/** Immutable scene template produced from glTF document parsing. */
+export interface SceneTemplate {
+  roots: number[];
+  nodes: NodeTemplate[];
+}
+
+/** Resource IDs allocated for one loaded glTF asset. */
+export interface LoadedResourceIds {
+  geometries: GeometryId[];
+  materials: MaterialId[];
+  textures: TextureId[];
+}
+
+/** Loaded glTF asset with reusable resources and instantiation API. */
+export interface LoadedGltfAsset {
+  worldId: World3DId;
+  warnings: string[];
+  template: SceneTemplate;
+  resources: LoadedResourceIds;
+  instantiate(options?: GltfInstantiateOptions): GltfInstance;
+  disposeEntities(): void;
+  disposeAll(): void;
+}
+
+/** Input descriptor for glTF/GLB loading. */
+export interface GltfLoadInput {
+  worldId: World3DId;
+  data: BinaryLike;
+  format?: GltfSourceFormat;
+  materialMode?: 'pbr' | 'standard';
+  resources?: Record<string, BinaryLike>;
+  rootTransform?: RootTransform;
+  labelPrefix?: string;
+}
+
+/** Result summary for a loaded glTF scene. */
+export interface GltfLoadResult {
+  rootEntityId: EntityId;
+  entityCount: number;
+  geometryCount: number;
+  materialCount: number;
+  textureCount: number;
+  warnings: string[];
+}
+
+/** Stable loader error codes for caller handling. */
+export type GltfLoaderErrorCode =
+  | 'INVALID_INPUT'
+  | 'UNSUPPORTED_FORMAT'
+  | 'PARSE_ERROR'
+  | 'UNSUPPORTED_FEATURE'
+  | 'MISSING_RESOURCE';
+
+export type LoaderCounters = {
+  entities: number;
+  geometries: number;
+  materials: number;
+  textures: number;
+};
+
+export type LoaderContext = {
+  worldId: World3DId;
+  warnings: string[];
+  labelPrefix: string;
+  materialMode: 'pbr' | 'standard';
+  defaultMaterialId?: MaterialId;
+  geometryByPrimitive: WeakMap<Primitive, GeometryId>;
+  materialBySource: WeakMap<Material, MaterialId>;
+  textureBySource: WeakMap<Texture, TextureId>;
+  textureColorSpaceHint: WeakMap<Texture, boolean>;
+  uploadedVertexByAccessor: WeakMap<Accessor, number>;
+  uploadedIndexByAccessor: WeakMap<Accessor, number>;
+  createdGeometryIds: Set<GeometryId>;
+  createdMaterialIds: Set<MaterialId>;
+  createdTextureIds: Set<TextureId>;
+  counters: LoaderCounters;
+};

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "allowJs": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true
+  },
+  "include": ["src"]
+}