@haiyue/extensions 0.1.0

package/src/canvas-text/CanvasText2DRenderSystem.ts

@@ -0,0 +1,292 @@
+import {
+  beginRenderCommandPass,
+  getExtensionGPUResourceTracker,
+  requireEngineDevice,
+  type IEngine,
+  type RenderCommandContext,
+} from '@haiyue/engine/extension-authoring';
+import { Transform2D } from '@haiyue/engine/components';
+import { Entity, type World } from '@haiyue/engine/ecs';
+import { CanvasTextComponent } from './CanvasTextComponent';
+import { RenderSystem2DBase, type RenderSystem2DBaseOptions } from '../utils/RenderSystem2DBase';
+import {
+  createCamera2DGpu,
+  createObject2DLayout,
+  createTexture2DGpu,
+  destroyCamera2DGpu,
+  destroyTexture2DGpu,
+  writeObjectMatrixIfChanged,
+  type Camera2DGpu,
+  type Object2DGpu,
+  type Texture2DGpu,
+} from '../utils/render2dGpu';
+import canvasText2dWgsl from '../shaders/generated/2d-ui-canvas-text-2d.generated.wgsl';
+
+export type CanvasText2DRenderSystemOptions = RenderSystem2DBaseOptions;
+
+const CANVAS_TEXT_2D_WGSL = canvasText2dWgsl;
+
+interface EntityGpu {
+  vertexBuffer: GPUBuffer;
+  vertexBufferSize: number;
+  vertexData: Float32Array;
+  vertexDirty: boolean;
+  vertexWidth: number;
+  vertexHeight: number;
+  objectGpu: Object2DGpu;
+  texture: GPUTexture | null;
+  textureSource: unknown;
+  textureVersion: number;
+  textureWidth: number;
+  textureHeight: number;
+  textureBindGroup: GPUBindGroup | null;
+}
+
+function textureSize(source: ImageBitmap | HTMLCanvasElement | HTMLImageElement): { width: number; height: number } {
+  return {
+    width: Math.max(1, source instanceof HTMLImageElement ? source.naturalWidth || source.width : source.width),
+    height: Math.max(1, source instanceof HTMLImageElement ? source.naturalHeight || source.height : source.height),
+  };
+}
+
+export class CanvasText2DRenderSystem extends RenderSystem2DBase {
+  private rendererReady = false;
+
+  private cameraGpu!: Camera2DGpu;
+  private objectLayout!: GPUBindGroupLayout;
+  private textureGpu!: Texture2DGpu;
+  private shaderModule!: GPUShaderModule;
+  private pipelineLayout!: GPUPipelineLayout;
+  private pipelineCache = new Map<number, GPURenderPipeline>();
+  private entityGpu = new Map<number, EntityGpu>();
+
+  constructor(engine: IEngine, cameraEntity: Entity, options: CanvasText2DRenderSystemOptions = {}) {
+    super(
+      { all: [CanvasTextComponent, Transform2D] },
+      engine,
+      cameraEntity,
+      options,
+      'CanvasText2DRenderSystem',
+    );
+  }
+
+  record(world: World, context: RenderCommandContext): this {
+    if (this.disabled) return this;
+    const { device } = context;
+    if (!this.rendererReady) this.prepare();
+    const liveEntities = this.beginLiveEntityTracking();
+
+    if (!this.writeCameraBuffer(device.queue, this.cameraGpu.buffer, context)) return this;
+
+    const { passEncoder, ownsPass } = beginRenderCommandPass(context);
+    passEncoder.setPipeline(this.getPipeline(
+      context.view?.reverseZ ?? this.engine.reverseZ,
+      context.view?.sampleCount ?? this.engine.msaaSamples,
+    ));
+    passEncoder.setBindGroup(0, this.cameraGpu.bindGroup);
+
+    const entities = this.entitySet.get(world);
+    if (entities) for (const entity of entities) {
+      if (!this.isEntityRenderable(entity)) continue;
+      const component = entity.getComponent(CanvasTextComponent);
+      if (!component) continue;
+      const textureBindGroup = this.getTextureBindGroup(entity, component);
+      const gpu = this.getEntityGpu(entity);
+      const vertices = this.buildVertices(component, gpu);
+      let shouldUploadVertices = gpu.vertexDirty;
+      if (vertices.byteLength > gpu.vertexBufferSize) {
+        getExtensionGPUResourceTracker(this.engine)?.untrackBuffer(gpu.vertexBuffer);
+        gpu.vertexBuffer.destroy();
+        gpu.vertexBufferSize = Math.max(vertices.byteLength, gpu.vertexBufferSize * 2);
+        gpu.vertexBuffer = device.createBuffer({
+          size: gpu.vertexBufferSize,
+          usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+        });
+        getExtensionGPUResourceTracker(this.engine)?.trackBuffer(gpu.vertexBuffer, 'CanvasText2D.vertexBuffer', gpu.vertexBufferSize);
+        shouldUploadVertices = true;
+      }
+      if (shouldUploadVertices) {
+        device.queue.writeBuffer(gpu.vertexBuffer, 0, vertices.buffer as ArrayBuffer, vertices.byteOffset, vertices.byteLength);
+        gpu.vertexDirty = false;
+      }
+      const worldMatrix = this.getWorldMatrix2D(entity, context);
+      writeObjectMatrixIfChanged(device.queue, gpu.objectGpu, worldMatrix);
+      passEncoder.setBindGroup(1, gpu.objectGpu.bindGroup);
+      passEncoder.setBindGroup(2, textureBindGroup);
+      passEncoder.setVertexBuffer(0, gpu.vertexBuffer);
+      passEncoder.draw(6);
+      this.markEntityLive(entity);
+    }
+
+    if (ownsPass) passEncoder.end();
+    this.releaseEntityGpuEntriesNotIn(this.entityGpu, gpu => this.destroyEntityGpu(gpu), liveEntities);
+    return this;
+  }
+
+  override destroy(): this {
+    this.releaseGpuResourcesForRecovery();
+    return super.destroy();
+  }
+
+  protected releaseGpuResourcesForRecovery(): void {
+    if (this.cameraGpu) destroyCamera2DGpu(this.cameraGpu);
+    if (this.textureGpu) destroyTexture2DGpu(this.textureGpu);
+    this.destroyEntityGpuEntries(this.entityGpu, gpu => this.destroyEntityGpu(gpu));
+    this.pipelineCache.clear();
+    this.rendererReady = false;
+  }
+
+  private prepare(): void {
+    this.rendererReady = true;
+    const device = requireEngineDevice(this.engine);
+    this.cameraGpu = createCamera2DGpu(device, getExtensionGPUResourceTracker(this.engine));
+    this.objectLayout = createObject2DLayout(device);
+    this.textureGpu = createTexture2DGpu(device, 0, getExtensionGPUResourceTracker(this.engine));
+    this.shaderModule = device.createShaderModule({ code: CANVAS_TEXT_2D_WGSL });
+    this.pipelineLayout = device.createPipelineLayout({
+      bindGroupLayouts: [this.cameraGpu.layout, this.objectLayout, this.textureGpu.layout],
+    });
+  }
+
+  private getPipeline(reverseZ: boolean, sampleCount: 1 | 4): GPURenderPipeline {
+    const key = (reverseZ ? 1 : 0) | ((sampleCount > 1 ? 1 : 0) << 1);
+    const cached = this.pipelineCache.get(key);
+    if (cached) return cached;
+
+    const device = requireEngineDevice(this.engine);
+    const { format } = this.engine;
+    const pipeline = device.createRenderPipeline({
+      layout: this.pipelineLayout,
+      vertex: {
+        module: this.shaderModule,
+        entryPoint: 'vs_main',
+        buffers: [{
+          arrayStride: 16,
+          attributes: [
+            { shaderLocation: 0, offset: 0, format: 'float32x2' },
+            { shaderLocation: 1, offset: 8, format: 'float32x2' },
+          ],
+        }],
+      },
+      fragment: {
+        module: this.shaderModule,
+        entryPoint: 'fs_main',
+        targets: [{
+          format,
+          blend: {
+            color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+            alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+          },
+        }],
+      },
+      primitive: { topology: 'triangle-list', cullMode: 'none' },
+      depthStencil: {
+        format: this.engine.getDepthFormat(reverseZ),
+        depthWriteEnabled: false,
+        depthCompare: 'always',
+      },
+      multisample: { count: sampleCount },
+    });
+    this.pipelineCache.set(key, pipeline);
+    return pipeline;
+  }
+
+  private getEntityGpu(entity: Entity): EntityGpu {
+    return this.getOrCreateEntityGpu(this.entityGpu, entity, () => {
+      const device = requireEngineDevice(this.engine);
+      const gpu = {
+        vertexBuffer: device.createBuffer({ size: 96, usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST }),
+        vertexBufferSize: 96,
+        vertexData: new Float32Array(24),
+        vertexDirty: true,
+        vertexWidth: 0,
+        vertexHeight: 0,
+        objectGpu: this.createObjectGpu(this.objectLayout),
+        texture: null,
+        textureSource: null,
+        textureVersion: -1,
+        textureWidth: 0,
+        textureHeight: 0,
+        textureBindGroup: null,
+      };
+      getExtensionGPUResourceTracker(this.engine)?.trackBuffer(gpu.vertexBuffer, 'CanvasText2D.vertexBuffer', gpu.vertexBufferSize);
+      return gpu;
+    });
+  }
+
+  private getTextureBindGroup(entity: Entity, component: CanvasTextComponent): GPUBindGroup {
+    const device = requireEngineDevice(this.engine);
+    const source = component.material.texture;
+    if (!source || !(source instanceof ImageBitmap || source instanceof HTMLCanvasElement || source instanceof HTMLImageElement)) {
+      return this.textureGpu.fallbackBindGroup;
+    }
+    const gpu = this.getEntityGpu(entity);
+    const size = textureSize(source);
+    const textureVersion = component.material.textureVersion;
+    if (
+      gpu.textureBindGroup &&
+      gpu.textureSource === source &&
+      gpu.textureVersion === textureVersion &&
+      gpu.textureWidth === size.width &&
+      gpu.textureHeight === size.height
+    ) {
+      return gpu.textureBindGroup;
+    }
+
+    const canReuseTexture = gpu.texture && gpu.textureWidth === size.width && gpu.textureHeight === size.height;
+    if (!canReuseTexture) {
+      if (gpu.texture) getExtensionGPUResourceTracker(this.engine)?.untrackTexture(gpu.texture);
+      gpu.texture?.destroy();
+      const texture = device.createTexture({
+        size: [size.width, size.height],
+        format: 'rgba8unorm',
+        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT,
+      });
+      gpu.texture = texture;
+      getExtensionGPUResourceTracker(this.engine)?.trackTexture(texture, 'CanvasText2D.texture', size.width * size.height * 4);
+      gpu.textureBindGroup = device.createBindGroup({
+        layout: this.textureGpu.layout,
+        entries: [
+          { binding: 0, resource: texture.createView() },
+          { binding: 1, resource: this.textureGpu.sampler },
+        ],
+      });
+    }
+    const texture = gpu.texture;
+    const textureBindGroup = gpu.textureBindGroup;
+    if (!texture || !textureBindGroup) throw new Error('CanvasText2D texture GPU state is incomplete.');
+    device.queue.copyExternalImageToTexture({ source }, { texture }, [size.width, size.height]);
+    gpu.textureSource = source;
+    gpu.textureVersion = textureVersion;
+    gpu.textureWidth = size.width;
+    gpu.textureHeight = size.height;
+    return textureBindGroup;
+  }
+
+  private buildVertices(component: CanvasTextComponent, gpu: EntityGpu): Float32Array {
+    const width = Math.max(1, Number(component.style.width ?? 256));
+    const height = Math.max(1, Number(component.style.height ?? 96));
+    if (gpu.vertexWidth !== width || gpu.vertexHeight !== height) {
+      gpu.vertexWidth = width;
+      gpu.vertexHeight = height;
+      gpu.vertexData.set([
+        0, 0, 0, 1,
+        width, 0, 1, 1,
+        width, height, 1, 0,
+        0, 0, 0, 1,
+        width, height, 1, 0,
+        0, height, 0, 0,
+      ]);
+      gpu.vertexDirty = true;
+    }
+    return gpu.vertexData;
+  }
+
+  private destroyEntityGpu(gpu: EntityGpu): void {
+    getExtensionGPUResourceTracker(this.engine)?.untrackBuffer(gpu.vertexBuffer);
+    gpu.vertexBuffer.destroy();
+    this.destroyObjectGpu(gpu.objectGpu);
+    if (gpu.texture) getExtensionGPUResourceTracker(this.engine)?.untrackTexture(gpu.texture);
+    gpu.texture?.destroy();
+  }
+}

package/src/canvas-text/CanvasTextComponent.ts

@@ -0,0 +1,47 @@
+import { Component } from '@haiyue/engine';
+import { UniqueCheckType } from '@haiyue/engine/ecs';
+import { CssMaterial, type CssMaterialStyle } from '@haiyue/engine/material';
+
+export interface CanvasTextComponentOptions {
+  text?: string;
+  style?: CssMaterialStyle;
+  material?: CssMaterial;
+}
+
+export class CanvasTextComponent extends Component {
+  static override UniqueCheckType = UniqueCheckType.SYMBOL | UniqueCheckType.REPLACE;
+  static override UniqueSymbol = Symbol.for('CanvasTextComponent');
+
+  material: CssMaterial;
+
+  constructor(options: CanvasTextComponentOptions = {}) {
+    super('CanvasTextComponent');
+    this.material = options.material ?? new CssMaterial({
+      ...(options.text === undefined ? {} : { text: options.text }),
+      ...(options.style === undefined ? {} : { style: options.style }),
+    });
+  }
+
+  get text(): string {
+    return this.material.text;
+  }
+
+  set text(value: string) {
+    this.material.setText(value);
+  }
+
+  get style(): CssMaterialStyle {
+    return this.material.style;
+  }
+
+  set style(value: CssMaterialStyle) {
+    this.material.setStyle(value);
+  }
+
+  override clone(): CanvasTextComponent {
+    return new CanvasTextComponent({
+      text: this.text,
+      style: { ...this.style },
+    });
+  }
+}

package/src/canvas-text.ts

@@ -0,0 +1,4 @@
+export { CanvasTextComponent } from './canvas-text/CanvasTextComponent';
+export type { CanvasTextComponentOptions } from './canvas-text/CanvasTextComponent';
+export { CanvasText2DRenderSystem } from './canvas-text/CanvasText2DRenderSystem';
+export type { CanvasText2DRenderSystemOptions } from './canvas-text/CanvasText2DRenderSystem';

package/src/experimental-gltf-worker.ts

@@ -0,0 +1,18 @@
+/** Experimental worker transport and low-level parsing contracts for glTF. */
+export {
+  GltfAssetWorkerClient,
+  createGltfAssetWorkerClientFromUrl,
+  createGltfAssetWorkerSource,
+  createInlineGltfAssetWorkerClient,
+} from './gltf/GltfAssetWorkerClient';
+export {
+  loadParsedGltfAsset,
+  prepareGltfGeometryPayloads,
+} from './gltf/gltfLoader';
+export type {
+  GltfAnimationChannelRuntime,
+  GltfAnimationTarget,
+  GltfGeometryPayloadMatrix,
+  GltfParsedAsset,
+  GltfPrimitiveGeometryPayload,
+} from './gltf/gltfLoader';

package/src/experimental-spine-worker.ts

@@ -0,0 +1,9 @@
+export { SPINE_ASSET_PARSER, parseSpineAssetPayload } from './spine/SpineAssetParser';
+export type { SpineAssetParserInput, SpineParsedAsset } from './spine/SpineAssetParser';
+export {
+  SpineAssetWorkerClient,
+  createInlineSpineAssetWorkerClient,
+  createSpineAssetWorkerClientFromUrl,
+  createSpineAssetWorkerSource,
+} from './spine/SpineAssetWorkerClient';
+export type { SpineAssetWorker } from './spine/SpineAssetWorkerContract';

package/src/gltf/GltfAccessorReader.ts

@@ -0,0 +1,271 @@
+import type {
+  GltfAccessor,
+  GltfAccessorType,
+  GltfAsset,
+  GltfBufferView,
+  GltfComponentType,
+} from './GltfSchema';
+import { gltfDataError } from './GltfLoaderErrors';
+
+const COMPONENT_BYTE_SIZE: Record<GltfComponentType, number> = {
+  5120: 1,
+  5121: 1,
+  5122: 2,
+  5123: 2,
+  5125: 4,
+  5126: 4,
+};
+
+const TYPE_SIZE: Record<GltfAccessorType, number> = {
+  SCALAR: 1,
+  VEC2: 2,
+  VEC3: 3,
+  VEC4: 4,
+  MAT2: 4,
+  MAT3: 9,
+  MAT4: 16,
+};
+
+export function readAccessorFloat(
+  gltf: GltfAsset,
+  buffers: ArrayBuffer[],
+  accessorIndex: number,
+  expectedSize: number,
+): Float32Array {
+  const accessor = getAccessor(gltf, accessorIndex);
+  const itemSize = TYPE_SIZE[accessor.type];
+  if (itemSize < expectedSize) throw gltfDataError(`Accessor ${accessorIndex} has ${itemSize} components, expected ${expectedSize}.`);
+  const out = new Float32Array(accessor.count * expectedSize);
+  readAccessorValues(gltf, buffers, accessor, (values, index) => {
+    for (let i = 0; i < expectedSize; i++) out[index * expectedSize + i] = values[i] ?? 0;
+  });
+  return out;
+}
+
+export function readAccessorMat4(gltf: GltfAsset, buffers: ArrayBuffer[], accessorIndex: number): Float32Array[] {
+  const accessor = getAccessor(gltf, accessorIndex);
+  if (TYPE_SIZE[accessor.type] !== 16) throw gltfDataError(`Accessor ${accessorIndex} is not MAT4.`);
+  const out: Float32Array[] = [];
+  readAccessorValues(gltf, buffers, accessor, values => {
+    const matrix = new Float32Array(16);
+    for (let i = 0; i < 16; i++) matrix[i] = values[i] ?? 0;
+    out.push(matrix);
+  });
+  return out;
+}
+
+export function readAccessorUnsigned(
+  gltf: GltfAsset,
+  buffers: ArrayBuffer[],
+  accessorIndex: number,
+  expectedSize: number,
+): Uint16Array | Uint32Array {
+  const accessor = getAccessor(gltf, accessorIndex);
+  const itemSize = TYPE_SIZE[accessor.type];
+  if (itemSize < expectedSize) throw gltfDataError(`Accessor ${accessorIndex} has ${itemSize} components, expected ${expectedSize}.`);
+  const out = accessor.componentType === 5125
+    ? new Uint32Array(accessor.count * expectedSize)
+    : new Uint16Array(accessor.count * expectedSize);
+  readAccessorValues(gltf, buffers, accessor, (values, index) => {
+    for (let i = 0; i < expectedSize; i++) out[index * expectedSize + i] = values[i] ?? 0;
+  });
+  return out;
+}
+
+export function readAccessorIndices(
+  gltf: GltfAsset,
+  buffers: ArrayBuffer[],
+  accessorIndex: number,
+): Uint16Array | Uint32Array {
+  const accessor = getAccessor(gltf, accessorIndex);
+  const out = accessor.componentType === 5125 ? new Uint32Array(accessor.count) : new Uint16Array(accessor.count);
+  readAccessorValues(gltf, buffers, accessor, (values, index) => {
+    out[index] = values[0] ?? 0;
+  });
+  return out;
+}
+
+export function generateFlatNormals(
+  positions: Float32Array,
+  indices: Uint16Array | Uint32Array | null,
+): Float32Array {
+  const normals = new Float32Array(positions.length);
+  const triangleCount = indices ? indices.length / 3 : positions.length / 9;
+  for (let tri = 0; tri < triangleCount; tri++) {
+    const ia = indices ? indices[tri * 3] : tri * 3;
+    const ib = indices ? indices[tri * 3 + 1] : tri * 3 + 1;
+    const ic = indices ? indices[tri * 3 + 2] : tri * 3 + 2;
+    if (ia === undefined || ib === undefined || ic === undefined) continue;
+    const ax = requiredFiniteArrayValue(positions, ia * 3, 'POSITION');
+    const ay = requiredFiniteArrayValue(positions, ia * 3 + 1, 'POSITION');
+    const az = requiredFiniteArrayValue(positions, ia * 3 + 2, 'POSITION');
+    const bx = requiredFiniteArrayValue(positions, ib * 3, 'POSITION');
+    const by = requiredFiniteArrayValue(positions, ib * 3 + 1, 'POSITION');
+    const bz = requiredFiniteArrayValue(positions, ib * 3 + 2, 'POSITION');
+    const cx = requiredFiniteArrayValue(positions, ic * 3, 'POSITION');
+    const cy = requiredFiniteArrayValue(positions, ic * 3 + 1, 'POSITION');
+    const cz = requiredFiniteArrayValue(positions, ic * 3 + 2, 'POSITION');
+    const abx = bx - ax, aby = by - ay, abz = bz - az;
+    const acx = cx - ax, acy = cy - ay, acz = cz - az;
+    const nx = aby * acz - abz * acy;
+    const ny = abz * acx - abx * acz;
+    const nz = abx * acy - aby * acx;
+    const len = Math.sqrt(nx * nx + ny * ny + nz * nz) || 1;
+    const nnx = nx / len;
+    const nny = ny / len;
+    const nnz = nz / len;
+    addNormal(normals, ia, nnx, nny, nnz);
+    addNormal(normals, ib, nnx, nny, nnz);
+    addNormal(normals, ic, nnx, nny, nnz);
+  }
+  for (let i = 0; i < normals.length; i += 3) {
+    const nx = requiredFiniteArrayValue(normals, i, 'generated normals');
+    const ny = requiredFiniteArrayValue(normals, i + 1, 'generated normals');
+    const nz = requiredFiniteArrayValue(normals, i + 2, 'generated normals');
+    const len = Math.sqrt(nx * nx + ny * ny + nz * nz) || 1;
+    normals[i] = nx / len;
+    normals[i + 1] = ny / len;
+    normals[i + 2] = nz / len;
+  }
+  return normals;
+}
+
+function readAccessorValues(
+  gltf: GltfAsset,
+  buffers: ArrayBuffer[],
+  accessor: GltfAccessor,
+  write: (values: ArrayLike<number>, index: number) => void,
+): void {
+  const itemSize = TYPE_SIZE[accessor.type];
+  const componentSize = COMPONENT_BYTE_SIZE[accessor.componentType];
+  const values = new Float64Array(itemSize);
+  if (accessor.bufferView !== undefined) {
+    const view = getBufferView(gltf, accessor.bufferView);
+    const dataView = new DataView(getBuffer(buffers, view.buffer));
+    const stride = view.byteStride ?? itemSize * componentSize;
+    const start = (view.byteOffset ?? 0) + (accessor.byteOffset ?? 0);
+    for (let index = 0; index < accessor.count; index++) {
+      readAccessorTuple(dataView, start + index * stride, itemSize, componentSize, accessor.componentType, Boolean(accessor.normalized), values);
+      write(values, index);
+    }
+  } else {
+    values.fill(0);
+    for (let index = 0; index < accessor.count; index++) write(values, index);
+  }
+  if (accessor.sparse?.count) readSparseAccessorValues(gltf, buffers, accessor, values, write);
+}
+
+function readSparseAccessorValues(
+  gltf: GltfAsset,
+  buffers: ArrayBuffer[],
+  accessor: GltfAccessor,
+  values: Float64Array,
+  write: (values: ArrayLike<number>, index: number) => void,
+): void {
+  const sparse = accessor.sparse;
+  if (!sparse) return;
+  const itemSize = TYPE_SIZE[accessor.type];
+  const componentSize = COMPONENT_BYTE_SIZE[accessor.componentType];
+  const indexComponentSize = COMPONENT_BYTE_SIZE[sparse.indices.componentType];
+  const indicesView = getBufferView(gltf, sparse.indices.bufferView);
+  const valuesView = getBufferView(gltf, sparse.values.bufferView);
+  const indicesData = new DataView(getBuffer(buffers, indicesView.buffer));
+  const valuesData = new DataView(getBuffer(buffers, valuesView.buffer));
+  const indicesStart = (indicesView.byteOffset ?? 0) + (sparse.indices.byteOffset ?? 0);
+  const valuesStart = (valuesView.byteOffset ?? 0) + (sparse.values.byteOffset ?? 0);
+  for (let sparseIndex = 0; sparseIndex < sparse.count; sparseIndex++) {
+    const index = readSparseIndex(indicesData, indicesStart + sparseIndex * indexComponentSize, sparse.indices.componentType);
+    if (index < 0 || index >= accessor.count) throw gltfDataError(`Sparse accessor index ${index} is out of bounds.`);
+    readAccessorTuple(
+      valuesData,
+      valuesStart + sparseIndex * itemSize * componentSize,
+      itemSize,
+      componentSize,
+      accessor.componentType,
+      Boolean(accessor.normalized),
+      values,
+    );
+    write(values, index);
+  }
+}
+
+function readAccessorTuple(
+  dataView: DataView,
+  offset: number,
+  itemSize: number,
+  componentSize: number,
+  componentType: GltfComponentType,
+  normalized: boolean,
+  out: Float64Array,
+): void {
+  for (let component = 0; component < itemSize; component++) {
+    out[component] = readComponent(dataView, offset + component * componentSize, componentType, normalized);
+  }
+}
+
+function readSparseIndex(view: DataView, offset: number, componentType: 5121 | 5123 | 5125): number {
+  switch (componentType) {
+    case 5121: return view.getUint8(offset);
+    case 5123: return view.getUint16(offset, true);
+    case 5125: return view.getUint32(offset, true);
+  }
+}
+
+function getBufferView(gltf: GltfAsset, bufferViewIndex: number): GltfBufferView {
+  const view = gltf.bufferViews?.[bufferViewIndex];
+  if (!view) throw gltfDataError(`Missing bufferView ${bufferViewIndex}.`);
+  return view;
+}
+
+function getBuffer(buffers: ArrayBuffer[], bufferIndex: number): ArrayBuffer {
+  const buffer = buffers[bufferIndex];
+  if (!buffer) throw gltfDataError(`Missing buffer ${bufferIndex}.`);
+  return buffer;
+}
+
+function getAccessor(gltf: GltfAsset, accessorIndex: number): GltfAccessor {
+  const accessor = gltf.accessors?.[accessorIndex];
+  if (!accessor) throw gltfDataError(`Missing accessor ${accessorIndex}.`);
+  return accessor;
+}
+
+function readComponent(view: DataView, offset: number, componentType: GltfComponentType, normalized: boolean): number {
+  switch (componentType) {
+    case 5120: {
+      const value = view.getInt8(offset);
+      return normalized ? Math.max(value / 127, -1) : value;
+    }
+    case 5121: {
+      const value = view.getUint8(offset);
+      return normalized ? value / 255 : value;
+    }
+    case 5122: {
+      const value = view.getInt16(offset, true);
+      return normalized ? Math.max(value / 32767, -1) : value;
+    }
+    case 5123: {
+      const value = view.getUint16(offset, true);
+      return normalized ? value / 65535 : value;
+    }
+    case 5125: return view.getUint32(offset, true);
+    case 5126: return view.getFloat32(offset, true);
+  }
+}
+
+function addNormal(normals: Float32Array, index: number, x: number, y: number, z: number): void {
+  const offset = index * 3;
+  if (offset < 0 || offset + 2 >= normals.length) {
+    throw gltfDataError(`Triangle index ${index} is outside the POSITION accessor.`);
+  }
+  normals[offset] = (normals[offset] ?? 0) + x;
+  normals[offset + 1] = (normals[offset + 1] ?? 0) + y;
+  normals[offset + 2] = (normals[offset + 2] ?? 0) + z;
+}
+
+export function requiredFiniteArrayValue(values: ArrayLike<number>, index: number, label: string): number {
+  const value = values[index];
+  if (value === undefined || !Number.isFinite(value)) {
+    throw gltfDataError(`${label} is missing a finite value at index ${index}.`);
+  }
+  return value;
+}