@aethervtt/shard-gltf 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Dias
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# @aethervtt/shard-gltf
+
+Part of [Shard](https://github.com/aethervtt/shard), a WebGPU-first 2D/3D game engine in TypeScript. See the repository for documentation.

package/dist/accessors.d.ts

@@ -0,0 +1,20 @@
+import type { GltfDocument } from './document.js';
+export interface AccessorData {
+    values: Float64Array;
+    count: number;
+    components: number;
+}
+/**
+ * Decodes accessors into flat arrays, handling strides, normalization, and sparse storage. `buffer`
+ * returns a buffer's bytes (resolved by the importer: GLB chunk, data URI, or external file).
+ */
+export declare class Accessors {
+    private readonly doc;
+    private readonly buffers;
+    private readonly cache;
+    constructor(doc: GltfDocument, buffers: Uint8Array[]);
+    /** Accessor `index` as doubles (exact for every glTF component type). */
+    read(index: number): AccessorData;
+    floats(index: number): Float32Array;
+    private viewOf;
+}

package/dist/accessors.js

@@ -0,0 +1,137 @@
+import { ShardError } from "@aethervtt/shard-core";
+const COMPONENTS = {
+  SCALAR: 1,
+  VEC2: 2,
+  VEC3: 3,
+  VEC4: 4,
+  MAT2: 4,
+  MAT3: 9,
+  MAT4: 16
+};
+const SIZES = { 5120: 1, 5121: 1, 5122: 2, 5123: 2, 5125: 4, 5126: 4 };
+function reader(view, type, normalized) {
+  switch (type) {
+    case 5120:
+      return normalized ? (o) => Math.max(view.getInt8(o) / 127, -1) : (o) => view.getInt8(o);
+    case 5121:
+      return normalized ? (o) => view.getUint8(o) / 255 : (o) => view.getUint8(o);
+    case 5122:
+      return normalized ? (o) => Math.max(view.getInt16(o, true) / 32767, -1) : (o) => view.getInt16(o, true);
+    case 5123:
+      return normalized ? (o) => view.getUint16(o, true) / 65535 : (o) => view.getUint16(o, true);
+    case 5125:
+      return (o) => view.getUint32(o, true);
+    case 5126:
+      return (o) => view.getFloat32(o, true);
+    default:
+      throw new ShardError("gltf/invalid", `Unknown component type ${type}`);
+  }
+}
+class Accessors {
+  doc;
+  buffers;
+  cache = /* @__PURE__ */ new Map();
+  constructor(doc, buffers) {
+    this.doc = doc;
+    this.buffers = buffers;
+  }
+  /** Accessor `index` as doubles (exact for every glTF component type). */
+  read(index) {
+    const cached = this.cache.get(index);
+    if (cached) return cached;
+    const acc = this.doc.accessors?.[index];
+    const ptr = `/accessors/${index}`;
+    if (!acc) throw new ShardError("gltf/invalid", `No accessor ${index}`, { path: ptr });
+    const components = COMPONENTS[acc.type];
+    const size = SIZES[acc.componentType];
+    if (!components || !size) {
+      throw new ShardError("gltf/invalid", `Accessor ${index} has an unknown type`, { path: ptr });
+    }
+    const values = new Float64Array(acc.count * components);
+    if (acc.bufferView !== void 0) {
+      const { view, stride, base } = this.viewOf(
+        acc.bufferView,
+        acc.byteOffset ?? 0,
+        components * size,
+        ptr
+      );
+      const needed = base + (acc.count - 1) * stride + components * size;
+      if (acc.count > 0 && needed > view.byteLength) {
+        throw new ShardError(
+          "gltf/accessor-out-of-range",
+          `Accessor ${index} reads past the end of buffer view ${acc.bufferView}`,
+          { path: ptr, hint: "The file is truncated or its byteOffset/count are wrong." }
+        );
+      }
+      const read = reader(view, acc.componentType, acc.normalized ?? false);
+      for (let i = 0; i < acc.count; i++) {
+        const o = base + i * stride;
+        for (let c = 0; c < components; c++) values[i * components + c] = read(o + c * size);
+      }
+    }
+    if (acc.sparse) {
+      const s = acc.sparse;
+      const idx = this.viewOf(
+        s.indices.bufferView,
+        s.indices.byteOffset ?? 0,
+        SIZES[s.indices.componentType],
+        `${ptr}/sparse/indices`
+      );
+      const val = this.viewOf(
+        s.values.bufferView,
+        s.values.byteOffset ?? 0,
+        components * size,
+        `${ptr}/sparse/values`
+      );
+      const readIndex = reader(idx.view, s.indices.componentType, false);
+      const readValue = reader(val.view, acc.componentType, acc.normalized ?? false);
+      const indexSize = SIZES[s.indices.componentType];
+      for (let i = 0; i < s.count; i++) {
+        const target = readIndex(idx.base + i * indexSize);
+        if (target >= acc.count) {
+          throw new ShardError(
+            "gltf/accessor-out-of-range",
+            `Sparse index ${target} is past accessor ${index}'s count`,
+            {
+              path: `${ptr}/sparse`
+            }
+          );
+        }
+        for (let c = 0; c < components; c++) {
+          values[target * components + c] = readValue(val.base + (i * components + c) * size);
+        }
+      }
+    }
+    const data = { values, count: acc.count, components };
+    this.cache.set(index, data);
+    return data;
+  }
+  floats(index) {
+    return Float32Array.from(this.read(index).values);
+  }
+  viewOf(viewIndex, byteOffset, elementSize, ptr) {
+    const bv = this.doc.bufferViews?.[viewIndex];
+    if (!bv) {
+      throw new ShardError("gltf/invalid", `No buffer view ${viewIndex}`, { path: ptr });
+    }
+    const buffer = this.buffers[bv.buffer];
+    if (!buffer) {
+      throw new ShardError("gltf/buffer-missing", `Buffer ${bv.buffer} couldn't be loaded`, {
+        path: `/buffers/${bv.buffer}`
+      });
+    }
+    const start = bv.byteOffset ?? 0;
+    if (start + bv.byteLength > buffer.byteLength) {
+      throw new ShardError(
+        "gltf/accessor-out-of-range",
+        `Buffer view ${viewIndex} is past the end of buffer ${bv.buffer}`,
+        { path: `/bufferViews/${viewIndex}` }
+      );
+    }
+    const view = new DataView(buffer.buffer, buffer.byteOffset + start, bv.byteLength);
+    return { view, stride: bv.byteStride ?? elementSize, base: byteOffset };
+  }
+}
+export {
+  Accessors
+};

package/dist/document.d.ts

@@ -0,0 +1,157 @@
+/** The parts of the glTF 2.0 JSON the importer reads. */
+export interface GltfDocument {
+    asset: {
+        version: string;
+    };
+    scene?: number;
+    scenes?: {
+        name?: string;
+        nodes?: number[];
+    }[];
+    nodes?: GltfNode[];
+    meshes?: {
+        name?: string;
+        primitives: GltfPrimitive[];
+        weights?: number[];
+    }[];
+    materials?: GltfMaterial[];
+    accessors?: GltfAccessor[];
+    bufferViews?: {
+        buffer: number;
+        byteOffset?: number;
+        byteLength: number;
+        byteStride?: number;
+    }[];
+    buffers?: {
+        uri?: string;
+        byteLength: number;
+    }[];
+    cameras?: {
+        type: 'perspective' | 'orthographic';
+        perspective?: {
+            yfov: number;
+            znear: number;
+            zfar?: number;
+        };
+        orthographic?: {
+            xmag: number;
+            ymag: number;
+            znear: number;
+            zfar: number;
+        };
+    }[];
+    skins?: {
+        name?: string;
+        joints: number[];
+        inverseBindMatrices?: number;
+        skeleton?: number;
+    }[];
+    animations?: {
+        name?: string;
+        channels: {
+            sampler: number;
+            target: {
+                node?: number;
+                path: string;
+            };
+        }[];
+        samplers: {
+            input: number;
+            output: number;
+            interpolation?: string;
+        }[];
+    }[];
+    textures?: {
+        source?: number;
+        sampler?: number;
+        extensions?: Record<string, unknown>;
+    }[];
+    images?: {
+        uri?: string;
+        bufferView?: number;
+        mimeType?: string;
+        name?: string;
+    }[];
+    samplers?: {
+        magFilter?: number;
+        minFilter?: number;
+        wrapS?: number;
+        wrapT?: number;
+    }[];
+    extensionsUsed?: string[];
+    extensionsRequired?: string[];
+    extensions?: Record<string, unknown>;
+}
+export interface GltfNode {
+    name?: string;
+    children?: number[];
+    mesh?: number;
+    camera?: number;
+    skin?: number;
+    matrix?: number[];
+    translation?: number[];
+    rotation?: number[];
+    scale?: number[];
+    weights?: number[];
+    extensions?: Record<string, unknown>;
+    extras?: unknown;
+}
+export interface GltfPrimitive {
+    attributes: Record<string, number>;
+    indices?: number;
+    material?: number;
+    mode?: number;
+    targets?: Record<string, number>[];
+}
+export interface TextureInfo {
+    index: number;
+    texCoord?: number;
+    scale?: number;
+    strength?: number;
+    extensions?: Record<string, unknown>;
+}
+export interface GltfMaterial {
+    name?: string;
+    pbrMetallicRoughness?: {
+        baseColorFactor?: number[];
+        metallicFactor?: number;
+        roughnessFactor?: number;
+        baseColorTexture?: TextureInfo;
+        metallicRoughnessTexture?: TextureInfo;
+    };
+    normalTexture?: TextureInfo;
+    occlusionTexture?: TextureInfo;
+    emissiveTexture?: TextureInfo;
+    emissiveFactor?: number[];
+    alphaMode?: 'OPAQUE' | 'MASK' | 'BLEND';
+    alphaCutoff?: number;
+    doubleSided?: boolean;
+    extensions?: Record<string, unknown>;
+}
+export interface GltfAccessor {
+    bufferView?: number;
+    byteOffset?: number;
+    componentType: number;
+    normalized?: boolean;
+    count: number;
+    type: 'SCALAR' | 'VEC2' | 'VEC3' | 'VEC4' | 'MAT2' | 'MAT3' | 'MAT4';
+    sparse?: {
+        count: number;
+        indices: {
+            bufferView: number;
+            byteOffset?: number;
+            componentType: number;
+        };
+        values: {
+            bufferView: number;
+            byteOffset?: number;
+        };
+    };
+}
+export interface ParsedGltf {
+    json: GltfDocument;
+    /** The GLB binary chunk, if the file is a .glb. */
+    bin: Uint8Array | undefined;
+}
+/** Reads a .glb container or .gltf JSON. */
+export declare function parseGltf(bytes: Uint8Array): ParsedGltf;

package/dist/document.js

@@ -0,0 +1,49 @@
+import { ShardError } from "@aethervtt/shard-core";
+const GLB_MAGIC = 1179937895;
+const CHUNK_JSON = 1313821514;
+const CHUNK_BIN = 5130562;
+function parseGltf(bytes) {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  let json;
+  let bin;
+  if (bytes.byteLength >= 12 && view.getUint32(0, true) === GLB_MAGIC) {
+    const version = view.getUint32(4, true);
+    if (version !== 2) {
+      throw new ShardError("gltf/invalid", `GLB version ${version} isn't supported (need 2)`, {
+        path: ""
+      });
+    }
+    const length = Math.min(view.getUint32(8, true), bytes.byteLength);
+    let offset = 12;
+    while (offset + 8 <= length) {
+      const chunkLength = view.getUint32(offset, true);
+      const type = view.getUint32(offset + 4, true);
+      const data = bytes.subarray(offset + 8, offset + 8 + chunkLength);
+      if (type === CHUNK_JSON) json = JSON.parse(new TextDecoder().decode(data));
+      else if (type === CHUNK_BIN && !bin) bin = data;
+      offset += 8 + chunkLength;
+    }
+    if (json === void 0)
+      throw new ShardError("gltf/invalid", "GLB has no JSON chunk", { path: "" });
+  } else {
+    try {
+      json = JSON.parse(new TextDecoder().decode(bytes));
+    } catch (cause) {
+      throw new ShardError("gltf/invalid", "Not a .glb and not valid glTF JSON", {
+        path: "",
+        cause
+      });
+    }
+  }
+  const doc = json;
+  if (!doc?.asset || typeof doc.asset.version !== "string" || !doc.asset.version.startsWith("2")) {
+    throw new ShardError("gltf/invalid", 'Missing asset.version "2.x"', {
+      path: "/asset/version",
+      hint: "Only glTF 2.0 files are supported."
+    });
+  }
+  return { json: doc, bin };
+}
+export {
+  parseGltf
+};

package/dist/importer.d.ts

@@ -0,0 +1,12 @@
+import { type JsonValue } from '@aethervtt/shard-core';
+export declare const GltfImportSettings: import("@aethervtt/shard-core").ComponentDef<{
+    readonly scale: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly forward: import("@aethervtt/shard-core").FieldType<"+z" | "-z", "u8">;
+    readonly emissiveLuminance: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly cameras: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly lights: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly generateNormals: import("@aethervtt/shard-core").FieldType<"always" | "missing" | "never", "u8">;
+    readonly lods: import("@aethervtt/shard-core").FieldType<"auto" | "none", "u8">;
+    readonly materialTypes: import("@aethervtt/shard-core").FieldType<JsonValue, "object">;
+}>;
+export declare const GltfImporter: import("@aethervtt/shard-assets").ImporterDef;