@solidrt/3d 0.0.59 → 0.0.61

package/src/gltf.ts

@@ -32,8 +32,19 @@
 // layout for a static primitive, the skinned list plus aColor for a
 // rigged one. Skins ARE parsed: joints, inverse binds, and the "skinned"
 // vertex layout.
+//
+// Reuse is kept, not unrolled: a mesh several nodes reference becomes
+// ONE part per primitive whose `placements` list the further nodes
+// (Three shares the geometry, Unity and Godot the mesh asset; here the
+// runtime draws the part instanced, one entry for the population), and
+// EXT_mesh_gpu_instancing lands the same way, its per-instance TRS as
+// synthesized child nodes of the referencing node (Three's
+// InstancedMesh, Godot's MultiMesh). The file's `extras` ride through
+// where glTF puts them - root, node, mesh (onto the part), material -
+// the way Three fills userData, so app data authored as custom
+// properties arrives with the model.
 
-import { compose, decompose, det3, mat4, multiply } from "./math.ts"
+import { compose, decompose, det3, mat4, multiply, quatNormalize } from "./math.ts"
 import { linearToSrgb } from "./color.ts"
 import type { Mat4, Quat, Vec3 } from "./math.ts"
 import { attributeAccess, layoutKey, layoutStride, packIndices, packMorphTargets, vertexView } from "./geometry.ts"
@@ -79,8 +90,16 @@ export type ModelMaterial = {
    * null; createModel hands it to `material` as both maps.metalnessMap
    * and maps.roughnessMap, standard's two channel-select options. */
   metalnessRoughnessMap: number | null
+  /** The glTF material's `extras`, when it has any. */
+  extras?: ModelExtras
 }
 
+/** Application data carried beside the model: a JSON object, glTF's
+ * `extras` shape (Blender's custom properties export as it), what Three
+ * surfaces as `userData` and Godot as node metadata. Present only when
+ * non-empty. */
+export type ModelExtras = Record<string, unknown>
+
 /** One node of the model's retained hierarchy: a local TRS under `parent`
  * (an earlier index into ModelData.nodes, or null for a root). Parts and
  * - in rigged models - skin joints and animation tracks reference nodes
@@ -100,6 +119,8 @@ export type ModelNode = {
    * zeros), what the node's parts draw with until a clip or
    * setMorphWeights writes them. */
   weights?: number[]
+  /** The glTF node's `extras`, when it has any. */
+  extras?: ModelExtras
 }
 
 /** One drawable: a mesh node's primitive. Vertices are LOCAL to its
@@ -111,8 +132,19 @@ export type ModelPart = {
    * numbers them `name#<k>`. */
   name: string
   /** Index into ModelData.nodes - the node whose world transform places
-   * this part (unused for placement when `skin` is set). */
+   * this part (unused for placement when `skin` is set). With
+   * `placements` it is the FIRST placement. */
   node: number
+  /** The further nodes (indices into ModelData.nodes) placing the SAME
+   * geometry - a mesh several glTF nodes reference, or the instances of
+   * EXT_mesh_gpu_instancing as synthesized children of the referencing
+   * node. Present only when there is more than one placement; then the
+   * part is a population (createModel draws it as one InstancedMesh, an
+   * instance under every placement node) rather than a mesh per node.
+   * Never on a skinned or morphed part, and a placement whose world
+   * mirrors the first's (opposite determinant sign) is its own part,
+   * since the baked winding cannot serve both. */
+  placements?: number[]
   /** Index into ModelData.skins, or null. A skinned part's geometry has
    * the "skinned" layout (aJoints/aWeights after the base prefix). */
   skin: number | null
@@ -128,6 +160,9 @@ export type ModelPart = {
   geometry: Geometry
   /** Index into ModelData.materials. */
   material: number
+  /** The glTF MESH's `extras`, when it has any (every primitive of the
+   * mesh carries the same object). */
+  extras?: ModelExtras
 }
 
 /** One skin: the joints (as node-table indices) and each joint's inverse
@@ -203,6 +238,15 @@ export type ModelData = {
    * is conservative (not vertex-tight) for parts under rotated nodes and
    * for skinned parts. */
   bounds: Float32Array
+  /** The document's root `extras`, when it has any: app data authored
+   * beside the model, or written by a bake of the app's own geometry. */
+  extras?: ModelExtras
+  /** Named binary sections for app data that does not belong in JSON (an
+   * occupancy grid, a nav mesh, a collider set): a bake writes them, the
+   * container stores each as its own 4-aligned block, and decodeModel
+   * hands them back as views onto the file's bytes. glTF has no
+   * counterpart; parseGltf never fills it. */
+  blobs?: Record<string, Uint8Array>
 }
 
 /** Resolves a relative uri of a .gltf (its .bin buffers, image files) to
@@ -315,15 +359,45 @@ export function isGlb(bytes: Uint8Array): boolean {
   return bytes.length >= 12 && new DataView(bytes.buffer, bytes.byteOffset, 12).getUint32(0, true) === GLB_MAGIC
 }
 
-/** The external uris a document references (buffers and images), so an
- * async caller can fetch them before parseGltf. Usually empty for .glb -
- * but a .glb MAY reference external files (some exporters write image
- * uris), so this reads its JSON chunk rather than assuming. data: uris
- * are never listed. */
+// The texture references the material map (parseGltf's `materials`)
+// samples, and so the only images the parser ever opens: the prefetch
+// list (gltfExternalUris) and the parser's demand set are both derived
+// from this one table, so a channel added to the map is added here too or
+// checks/gltf-check.ts fails on its all-channels fixture.
+const SAMPLED_TEXTURES: ((material: any) => any)[] = [
+  (m) => m.pbrMetallicRoughness?.baseColorTexture,
+  (m) => m.normalTexture,
+  (m) => m.emissiveTexture,
+  (m) => m.pbrMetallicRoughness?.metallicRoughnessTexture,
+]
+
+// The image indices a document's materials sample (SAMPLED_TEXTURES
+// through textures[].source), the demand set imageSlot will meet.
+function sampledImages(gltf: any): Set<number> {
+  let images = new Set<number>()
+  for (let m of gltf.materials ?? []) {
+    for (let channel of SAMPLED_TEXTURES) {
+      let ref = channel(m)
+      let source = ref === undefined ? undefined : gltf.textures?.[ref.index]?.source
+      if (source !== undefined) images.add(source)
+    }
+  }
+  return images
+}
+
+/** The external uris parseGltf will open on a document: every buffer,
+ * and the images a material samples (an image nothing samples is never
+ * read, so it is not listed), so an async caller can fetch exactly that
+ * set before the synchronous parse. Usually empty for .glb - but a .glb
+ * MAY reference external files (some exporters write image uris), so
+ * this reads its JSON chunk rather than assuming. data: uris are never
+ * listed. */
 export function gltfExternalUris(bytes: Uint8Array): string[] {
   let gltf = isGlb(bytes) ? readGlb(bytes).json : JSON.parse(new TextDecoder().decode(bytes))
+  let sampled = sampledImages(gltf)
+  let items: any[] = [...(gltf.buffers ?? []), ...(gltf.images ?? []).filter((_: any, i: number) => sampled.has(i))]
   let uris: string[] = []
-  for (let item of [...(gltf.buffers ?? []), ...(gltf.images ?? [])]) {
+  for (let item of items) {
     if (typeof item.uri === "string" && !item.uri.startsWith("data:")) uris.push(item.uri)
   }
   return uris
@@ -354,9 +428,10 @@ export function parseGltf(bytes: Uint8Array, resolve?: UriResolver): ModelData {
       throw new Error("parseGltf: the file's meshes are compressed (" + ext + "), which is not supported: re-export without mesh compression")
     }
     // Quantized attributes read through the normalized-integer path,
-    // emissive strength is the emissive intensity; every other required
-    // extension changes what the file means.
-    if (ext !== "KHR_mesh_quantization" && ext !== "KHR_materials_emissive_strength") {
+    // emissive strength is the emissive intensity, GPU instancing is
+    // read as placements; every other required extension changes what
+    // the file means.
+    if (ext !== "KHR_mesh_quantization" && ext !== "KHR_materials_emissive_strength" && ext !== "EXT_mesh_gpu_instancing") {
       throw new Error("parseGltf: the file requires the " + ext + " extension, which is not supported")
     }
   }
@@ -405,6 +480,8 @@ export function parseGltf(bytes: Uint8Array, resolve?: UriResolver): ModelData {
   // A texture reference's image slot, or null (the reference absent, or
   // its texture imageless). Further UV sets are outside the subset, so a
   // non-zero texCoord is ignored and the map samples the one UV set.
+  // Every reference the map below passes here is one of SAMPLED_TEXTURES
+  // (the prefetch list): a new channel goes in the table first.
   let textureSlot = (ref: any): number | null => {
     if (ref === undefined) return null
     let texture = gltf.textures?.[ref.index]
@@ -416,7 +493,7 @@ export function parseGltf(bytes: Uint8Array, resolve?: UriResolver): ModelData {
     let emissiveFactor: number[] = m.emissiveFactor ?? [0, 0, 0]
     let strength = m.extensions?.KHR_materials_emissive_strength?.emissiveStrength ?? 1
     // glTF factors are linear; the material options are sRGB.
-    return {
+    let material: ModelMaterial = {
       name: m.name ?? "material" + i,
       color: [linearToSrgb(factor[0]), linearToSrgb(factor[1]), linearToSrgb(factor[2]), factor[3] ?? 1],
       map: textureSlot(pbr.baseColorTexture),
@@ -433,6 +510,9 @@ export function parseGltf(bytes: Uint8Array, resolve?: UriResolver): ModelData {
       roughness: typeof pbr.roughnessFactor === "number" ? pbr.roughnessFactor : 1,
       metalnessRoughnessMap: textureSlot(pbr.metallicRoughnessTexture),
     }
+    let extras = extrasOf(m)
+    if (extras !== undefined) material.extras = extras
+    return material
   })
   // Primitives without a material draw the spec's default; it is appended
   // only when something uses it.
@@ -489,16 +569,46 @@ export function parseGltf(bytes: Uint8Array, resolve?: UriResolver): ModelData {
   // part somewhere below it needs the chain (materialize walks ancestors
   // first, so the table stays in pre-order), which is what prunes cameras,
   // lights and unused empties.
-  type PendingNode = { name: string; parent: PendingNode | null; position: Vec3; rotation: Quat; scale: Vec3; world: Mat4; index: number | null }
+  type PendingNode = { name: string; parent: PendingNode | null; position: Vec3; rotation: Quat; scale: Vec3; world: Mat4; index: number | null; extras: ModelExtras | undefined }
   let nodes: ModelNode[] = []
   let materialize = (p: PendingNode): number => {
     if (p.index !== null) return p.index
     let parent = p.parent === null ? null : materialize(p.parent)
     p.index = nodes.length
-    nodes.push({ name: p.name, parent, position: p.position, rotation: p.rotation, scale: p.scale })
+    let node: ModelNode = { name: p.name, parent, position: p.position, rotation: p.rotation, scale: p.scale }
+    if (p.extras !== undefined) node.extras = p.extras
+    nodes.push(node)
     return p.index
   }
 
+  /** One node placing a mesh: its table slot, name, rest-pose world, the
+   * file's skin index it draws with (null for a rigid placement) and its
+   * position in the walk, which orders the parts. */
+  type Placement = { slot: number; name: string; world: Mat4; skin: number | null; seq: number }
+  // A mesh's placements collected over the walk, keyed by the file's
+  // mesh index in first-use order, folded into parts after it.
+  let meshUses = new Map<number, { mesh: any; uses: Placement[] }>()
+  let sequence = 0
+  let place = (meshIndex: number, mesh: any, pending: PendingNode, skin: number | null, nodeWeights: unknown): void => {
+    let slot = materialize(pending)
+    let prims: any[] = mesh.primitives ?? []
+    // Morph target names and the initial weights are the MESH's (a node
+    // may override the weights); the weights land on the placing node,
+    // which is what a weights channel and setMorphWeights address.
+    let targetCount = Math.max(0, ...prims.map((p: any): number => p?.targets?.length ?? 0))
+    if (targetCount > 0) {
+      let weights: number[] = Array.isArray(nodeWeights) ? nodeWeights : Array.isArray(mesh.weights) ? mesh.weights : []
+      if (weights.length !== targetCount) {
+        if (weights.length !== 0) throw new Error("parseGltf: node " + pending.name + " has " + weights.length + " weights for " + targetCount + " morph targets")
+        weights = new Array(targetCount).fill(0)
+      }
+      nodes[slot]!.weights = weights.map(Number)
+    }
+    let use: Placement = { slot, name: pending.name, world: pending.world, skin, seq: sequence++ }
+    let uses = meshUses.get(meshIndex)
+    if (uses === undefined) meshUses.set(meshIndex, { mesh, uses: [use] })
+    else uses.uses.push(use)
+  }
   let parts: ModelPart[] = []
   let pendingJointBounds: { skin: number; positions: Float32Array; count: number; joints: Float32Array; weights: Float32Array; slack: number }[] = []
   let bounds = new Float32Array([Infinity, Infinity, Infinity, -Infinity, -Infinity, -Infinity])
@@ -521,8 +631,27 @@ export function parseGltf(bytes: Uint8Array, resolve?: UriResolver): ModelData {
     }
   }
 
-  let emit = (prim: any, name: string, node: number, world: Mat4, skin: number | null, targetNames: string[] | null): void => {
+  /** A primitive's built geometry per variant ("rigid"/"skinned", with or
+   * without the winding flip), shared by every part emitted from it: a
+   * skinned mesh two nodes place, a morphed one, a mirrored copy - each
+   * its own part, one set of bytes. `box` is the local rest box (morph
+   * extent included) for the bounds, null for a skinned build (its box
+   * comes from the joints); `indexed` says the vertices are the authored
+   * ones (not the flat-shading un-index), so a twin under the other
+   * winding sign can share them and differ in index order alone. */
+  type Built = { geometry: Geometry; box: number[] | null; indexed: boolean }
+  type PrimitiveCache = Map<string, Built>
+
+  // One part from one primitive under its placements: the first names and
+  // owns it (`node`), the rest are `placements`. Every placement shares
+  // the skin (null, for more than one) and the winding sign, which the
+  // fold below guarantees.
+  let emit = (prim: any, name: string, placed: Placement[], targetNames: string[] | null, extras: ModelExtras | undefined, shared: PrimitiveCache): void => {
     if (prim.attributes?.POSITION === undefined) return
+    let first = placed[0]!
+    let node = first.slot
+    let world = first.world
+    let skin = first.skin
     let mode: number = prim.mode ?? MODE_TRIANGLES
     let pos = accessorFloats(prim.attributes.POSITION, name + " POSITION")
     if (pos.elements !== 3) throw new Error("parseGltf: " + name + " POSITION is not VEC3")
@@ -616,6 +745,49 @@ export function parseGltf(bytes: Uint8Array, resolve?: UriResolver): ModelData {
     // points have no winding.
     let flip = triangles && !skinned && det3(world) < 0
 
+    // The part from a built geometry: the bounds through every placement
+    // (a skinned build parks its joint boxes instead), the material, the
+    // record. Shared by the first build and every later part over it.
+    let finish = (built: Built): void => {
+      if (built.box !== null) {
+        for (let p of placed) growBounds(bounds, built.box, p.world)
+      } else {
+        // Joint boxes need the skin's inverse binds, and skins are built
+        // after the walk (their joints are ordinary nodes the walk
+        // registers), so the arrays are parked under the FILE's skin index
+        // and grown then - each box padded by the largest morph delta, as
+        // a morph moves a vertex in whichever joint's space.
+        let m = built.geometry.morphs
+        let slack = m === undefined ? 0 : Math.max(...Array.from(m.extent, Math.abs))
+        pendingJointBounds.push({ skin: skin!, positions: pos.data, count: pos.count, joints: joints!.data, weights: weights!.data, slack })
+      }
+      let material = prim.material
+      if (material === undefined) {
+        if (defaultMaterial < 0) {
+          defaultMaterial = materials.length
+          materials.push({ ...DEFAULT_MATERIAL })
+        }
+        material = defaultMaterial
+      }
+      let part: ModelPart = { name, node, skin, geometry: built.geometry, material }
+      if (placed.length > 1) part.placements = placed.slice(1).map((p) => p.slot)
+      if (extras !== undefined) part.extras = extras
+      parts.push(part)
+    }
+    // The same primitive built before for this variant: one geometry for
+    // every part over it.
+    let variant = skinned ? "skinned" : "rigid"
+    let key = variant + (flip ? "|flipped" : "")
+    let built = shared.get(key)
+    if (built !== undefined) {
+      finish(built)
+      return
+    }
+    // The other winding sign's build, when it exists: an indexed one holds
+    // the very vertices this variant needs.
+    let twin = shared.get(variant + (flip ? "" : "|flipped"))
+    if (twin !== undefined && !twin.indexed) twin = undefined
+
     // The channels of the part's buffer, written through the accessors:
     // whatever a channel's format, the writer takes floats.
     let source: VertexSource = { pos: pos.data, nrm, uv: uv?.data ?? null, color: color === null ? null : { data: color.data, elements: color.elements }, joints: joints?.data ?? null, weights: weights?.data ?? null }
@@ -626,12 +798,20 @@ export function parseGltf(bytes: Uint8Array, resolve?: UriResolver): ModelData {
     // interleave (the morph targets): null while the slots are the
     // source order, the un-index's corner table otherwise.
     let remap: number[] | null = null
-    if (nrm !== null || !triangles) {
+    let indexed = nrm !== null || !triangles
+    if (indexed) {
       // Indexed as authored. Lines and points without normals get zero
-      // ones (there is no face to take one from; nothing lights them).
-      vertices = vertexView(layout, new ArrayBuffer(count * layoutStride(layout)))
-      writer = vertexWriter(vertices, layout)
-      for (let i = 0; i < count; i++) writeVertex(writer, i, source, i)
+      // ones (there is no face to take one from; nothing lights them). A
+      // twin under the other winding sign already holds these vertices:
+      // share its buffer, only the index order differs.
+      if (twin !== undefined) {
+        vertices = twin.geometry.vertices
+        writer = vertexWriter(vertices, layout)
+      } else {
+        vertices = vertexView(layout, new ArrayBuffer(count * layoutStride(layout)))
+        writer = vertexWriter(vertices, layout)
+        for (let i = 0; i < count; i++) writeVertex(writer, i, source, i)
+      }
       packedIndices = Array.from(indices)
       if (flip) {
         for (let i = 0; i < packedIndices.length; i += 3) {
@@ -684,7 +864,8 @@ export function parseGltf(bytes: Uint8Array, resolve?: UriResolver): ModelData {
     // sparse by vertex onto the geometry. Names come from the mesh's
     // extras.targetNames (what Blender writes), else "target<t>".
     let targets: any[] = prim.targets ?? []
-    let morphs = targets.length === 0 ? undefined : packMorphTargets(count, targets.map((target: any, t: number): MorphTarget => {
+    // A twin's packed targets are these exactly (both indexed, no remap).
+    let morphs = twin !== undefined ? twin.geometry.morphs : targets.length === 0 ? undefined : packMorphTargets(count, targets.map((target: any, t: number): MorphTarget => {
       let what = name + " target " + t
       let deltas = (attribute: string): Float32Array | null => {
         if (target?.[attribute] === undefined) return null
@@ -703,12 +884,13 @@ export function parseGltf(bytes: Uint8Array, resolve?: UriResolver): ModelData {
       return { name: targetNames?.[t] ?? "target" + t, position: deltas("POSITION") ?? new Float32Array(count * 3), normal: remap === null ? deltas("NORMAL") : null }
     }))
 
-    // Model bounds: the part's local box through the node's rest-pose
-    // world transform (8 corners - conservative under rotation, exact
-    // under translation and axis-aligned scale), grown by the morph
-    // extent first so a morphed shape stays inside. A skinned part's
-    // vertices are placed by its joints, not its node, so its box is
-    // folded in after the skins exist (growBounds over the joint boxes).
+    // The local rest box (8 corners through each placement's world in
+    // finish - conservative under rotation, exact under translation and
+    // axis-aligned scale), grown by the morph extent first so a morphed
+    // shape stays inside. A skinned build's vertices are placed by its
+    // joints, not its node, so it has none here: its box is folded in
+    // after the skins exist (growBounds over the joint boxes).
+    let box: number[] | null = null
     if (!skinned) {
       let lo: Vec3 = [Infinity, Infinity, Infinity]
       let hi: Vec3 = [-Infinity, -Infinity, -Infinity]
@@ -725,30 +907,16 @@ export function parseGltf(bytes: Uint8Array, resolve?: UriResolver): ModelData {
           hi[k] = hi[k]! + morphs.extent[3 + k]!
         }
       }
-      growBounds(bounds, [lo[0], lo[1], lo[2], hi[0], hi[1], hi[2]], world)
-    } else {
-      // Joint boxes need the skin's inverse binds, and skins are built
-      // after the walk (their joints are ordinary nodes the walk
-      // registers), so the arrays are parked under the FILE's skin index
-      // and grown then - each box padded by the largest morph delta, as
-      // a morph moves a vertex in whichever joint's space.
-      let slack = morphs === undefined ? 0 : Math.max(...Array.from(morphs.extent, Math.abs))
-      pendingJointBounds.push({ skin: skin!, positions: pos.data, count: pos.count, joints: joints!.data, weights: weights!.data, slack })
+      box = [lo[0], lo[1], lo[2], hi[0], hi[1], hi[2]]
     }
 
-    let material = prim.material
-    if (material === undefined) {
-      if (defaultMaterial < 0) {
-        defaultMaterial = materials.length
-        materials.push({ ...DEFAULT_MATERIAL })
-      }
-      material = defaultMaterial
-    }
     let geometry: Geometry = { vertices, indices: packIndices(packedIndices, count), label: name }
     if (layout !== undefined) geometry.layout = layout
     if (morphs !== undefined) geometry.morphs = morphs
     if (!triangles) geometry.topology = topology
-    parts.push({ name, node, skin, geometry, material })
+    built = { geometry, box, indexed }
+    shared.set(key, built)
+    finish(built)
   }
 
   let local = mat4()
@@ -756,6 +924,10 @@ export function parseGltf(bytes: Uint8Array, resolve?: UriResolver): ModelData {
   let walk = (index: number, parent: PendingNode | null, parentWorld: Mat4): void => {
     let node = gltf.nodes[index]
     if (node === undefined) throw new Error("parseGltf: scene names a missing node " + index)
+    // glTF's hierarchy is a strict tree: a node reached twice has two
+    // parents, or the children form a cycle - which would otherwise
+    // recurse until the stack goes.
+    if (pendingByIndex.has(index)) throw new Error("parseGltf: node " + index + " appears twice in the hierarchy (two parents, or a cycle in children)")
     let position: Vec3 = [0, 0, 0]
     let rotation: Quat = [0, 0, 0, 1]
     let scale: Vec3 = [1, 1, 1]
@@ -771,38 +943,108 @@ export function parseGltf(bytes: Uint8Array, resolve?: UriResolver): ModelData {
     // winding and bounds match what the runtime will render.
     let world = mat4()
     multiply(world, parentWorld, compose(local, position, rotation, scale))
-    let pending: PendingNode = { name: node.name ?? "node" + index, parent, position, rotation, scale, world, index: null }
+    let pending: PendingNode = { name: node.name ?? "node" + index, parent, position, rotation, scale, world, index: null, extras: extrasOf(node) }
     pendingByIndex.set(index, pending)
     if (node.mesh !== undefined) {
       let mesh = gltf.meshes[node.mesh]
       if (mesh === undefined) throw new Error("parseGltf: node " + index + " names a missing mesh " + node.mesh)
       if (node.name === undefined && mesh.name !== undefined) pending.name = mesh.name
-      let slot = materialize(pending)
       let skin = typeof node.skin === "number" ? node.skin : null
-      let prims: any[] = mesh.primitives ?? []
-      // Morph target names and the initial weights are the MESH's (a
-      // node may override the weights); the weights land on the node,
-      // which is what a weights channel and setMorphWeights address.
-      let targetCount = Math.max(0, ...prims.map((p: any): number => p?.targets?.length ?? 0))
-      let targetNames: string[] | null = Array.isArray(mesh.extras?.targetNames) ? mesh.extras.targetNames.map(String) : null
-      if (targetCount > 0) {
-        let weights: number[] = Array.isArray(node.weights) ? node.weights : Array.isArray(mesh.weights) ? mesh.weights : []
-        if (weights.length !== targetCount) {
-          if (weights.length !== 0) throw new Error("parseGltf: node " + pending.name + " has " + weights.length + " weights for " + targetCount + " morph targets")
-          weights = new Array(targetCount).fill(0)
+      let instancing = node.extensions?.EXT_mesh_gpu_instancing
+      if (instancing === undefined) place(node.mesh, mesh, pending, skin, node.weights)
+      else {
+        // EXT_mesh_gpu_instancing: the node's mesh is drawn once per
+        // instance, each a TRS in the node's local space, and not at
+        // the node itself. Every instance becomes a synthesized child
+        // node ("<name>[i]"), so the hierarchy stays one table and an
+        // instance moves like any node; the per-instance custom
+        // attributes the extension allows (underscore-prefixed) are
+        // dropped, as Three drops them.
+        let what = "node " + pending.name + " EXT_mesh_gpu_instancing"
+        let attrs = instancing.attributes ?? {}
+        let read = (attribute: string, elements: number): Float32Array | null => {
+          if (attrs[attribute] === undefined) return null
+          let acc = accessorFloats(attrs[attribute], what + " " + attribute)
+          if (acc.elements !== elements) throw new Error("parseGltf: " + what + " " + attribute + " is not VEC" + elements)
+          return acc.data
+        }
+        let t = read("TRANSLATION", 3)
+        let r = read("ROTATION", 4)
+        let s = read("SCALE", 3)
+        let counts = [t === null ? null : t.length / 3, r === null ? null : r.length / 4, s === null ? null : s.length / 3].filter((c): c is number => c !== null)
+        if (counts.length === 0) throw new Error("parseGltf: " + what + " has no TRANSLATION, ROTATION or SCALE attribute")
+        if (counts.some((c) => c !== counts[0])) throw new Error("parseGltf: " + what + " attributes disagree on the instance count")
+        for (let i = 0; i < counts[0]!; i++) {
+          let p: Vec3 = t === null ? [0, 0, 0] : [t[i * 3]!, t[i * 3 + 1]!, t[i * 3 + 2]!]
+          // A quantized rotation (normalized int16, which the extension
+          // allows) is unit only to its precision; renormalized so the
+          // node stores a unit quaternion like every other.
+          let q: Quat = [0, 0, 0, 1]
+          if (r !== null) quatNormalize(q, [r[i * 4]!, r[i * 4 + 1]!, r[i * 4 + 2]!, r[i * 4 + 3]!])
+          let sc: Vec3 = s === null ? [1, 1, 1] : [s[i * 3]!, s[i * 3 + 1]!, s[i * 3 + 2]!]
+          let instanceWorld = mat4()
+          multiply(instanceWorld, world, compose(local, p, q, sc))
+          place(node.mesh, mesh, { name: pending.name + "[" + i + "]", parent: pending, position: p, rotation: q, scale: sc, world: instanceWorld, index: null, extras: undefined }, skin, node.weights)
         }
-        nodes[slot]!.weights = weights.map(Number)
       }
-      for (let k = 0; k < prims.length; k++) emit(prims[k], prims.length > 1 ? pending.name + "#" + k : pending.name, slot, world, skin, targetNames)
     }
     for (let child of node.children ?? []) walk(child, pending, world)
   }
 
   let scene = gltf.scenes?.[gltf.scene ?? 0]
-  let roots: number[] = scene?.nodes ?? (gltf.nodes ?? []).map((_: unknown, i: number) => i)
+  let allNodes: any[] = gltf.nodes ?? []
+  // No scene (both `scene` and `scenes` are optional): draw everything,
+  // from the true roots - the nodes no other node lists as a child - so a
+  // nested node is visited once under its parent, never a second time as
+  // a root against the identity.
+  let listedAsChild = new Set<number>()
+  if (scene === undefined) for (let n of allNodes) for (let c of n?.children ?? []) listedAsChild.add(c)
+  let roots: number[] = scene?.nodes ?? allNodes.map((_: unknown, i: number) => i).filter((i) => !listedAsChild.has(i))
   let root = mat4()
   for (let index of roots) walk(index, null, root)
 
+  // Parts, after the walk: one primitive under its placements. A mesh
+  // several nodes use folds into one part per primitive with the further
+  // nodes as placements (the runtime draws it instanced) - except what
+  // cannot share one draw, which stays a part of its own per use: a
+  // skinned use (bind-pose model space, placed by its skin; a second
+  // reference draws the same thing per spec), a morphed one (its weights
+  // are the node's), and a use whose rest-pose winding sign differs from
+  // the bucket's (the flip is baked into the indices). Those parts still
+  // share the primitive's built geometry (one cache per primitive, see
+  // emit), so the bytes exist once. Parts are emitted in WALK order -
+  // each bucket where its first placement was visited, a node's
+  // primitives in order - so a file's part order does not depend on how
+  // its meshes interleave.
+  let queue: { seq: number; k: number; run: () => void }[] = []
+  for (let { mesh, uses } of meshUses.values()) {
+    let prims: any[] = mesh.primitives ?? []
+    let targetNames: string[] | null = Array.isArray(mesh.extras?.targetNames) ? mesh.extras.targetNames.map(String) : null
+    let extras = extrasOf(mesh)
+    for (let k = 0; k < prims.length; k++) {
+      let prim = prims[k]
+      let morphed = (prim?.targets?.length ?? 0) > 0
+      let buckets: { alone: boolean; mirrored: boolean; placed: Placement[] }[] = []
+      for (let use of uses) {
+        let alone = use.skin !== null || morphed
+        let mirrored = det3(use.world) < 0
+        let bucket = alone ? undefined : buckets.find((b) => !b.alone && b.mirrored === mirrored)
+        if (bucket === undefined) {
+          bucket = { alone, mirrored, placed: [] }
+          buckets.push(bucket)
+        }
+        bucket.placed.push(use)
+      }
+      let shared: PrimitiveCache = new Map()
+      for (let b of buckets) {
+        let name = b.placed[0]!.name
+        queue.push({ seq: b.placed[0]!.seq, k, run: () => emit(prim, prims.length > 1 ? name + "#" + k : name, b.placed, targetNames, extras, shared) })
+      }
+    }
+  }
+  queue.sort((a, b) => a.seq - b.seq || a.k - b.k)
+  for (let item of queue) item.run()
+
   // Skins, after the walk: joints are ordinary nodes (usually meshless),
   // materialized here so the retained table carries them; part.skin
   // remaps from the file's skin index to the compact list.
@@ -940,7 +1182,19 @@ export function parseGltf(bytes: Uint8Array, resolve?: UriResolver): ModelData {
   // Nothing grew the box (no parts, or skinned parts whose weights reach
   // no joint): an empty model sits at the origin.
   if (!(bounds[0]! <= bounds[3]!)) bounds.fill(0)
-  return { nodes, parts, skins, clips, materials, images, bounds }
+  let data: ModelData = { nodes, parts, skins, clips, materials, images, bounds }
+  let extras = extrasOf(gltf)
+  if (extras !== undefined) data.extras = extras
+  return data
+}
+
+/** An object's glTF `extras` as a JSON object, or undefined when absent,
+ * not an object, or empty - so the field appears only where there is
+ * data. */
+function extrasOf(owner: any): ModelExtras | undefined {
+  let extras = owner?.extras
+  if (typeof extras !== "object" || extras === null || Array.isArray(extras)) return undefined
+  return Object.keys(extras).length > 0 ? (extras as ModelExtras) : undefined
 }
 
 function readGlb(bytes: Uint8Array): { json: any; bin: Uint8Array | null } {

package/src/index.ts

@@ -49,7 +49,7 @@ export { extrude, lathe, pathFrames, polygon, sweep, tube } from "./sweep.ts"
 export type { ExtrudeOptions, LatheOptions, PathFrames, PathPoint, SweepPath, TubeOptions } from "./sweep.ts"
 export { phong, shaderMaterial, shaderMaterialClass, sprite, standard, unlit } from "./material.ts"
 export type { LitOptions, Material, PhongOptions, ShaderMaterialClass, ShaderMaterialClassOptions, ShaderMaterialInstanceOptions, ShaderMaterialOptions, SpriteOptions, StandardOptions, UnlitOptions } from "./material.ts"
-export { DirectionalLight, FirstPersonCamera, Group, HemisphereLight, Instance, InstancedLod, InstancedMesh, Lod, Mesh, OrbitCamera, PerspectiveCamera, PointLight, RecordMesh, Scene, SpotLight, Sprite, View3d, useScene } from "./components/index.ts"
+export { DirectionalLight, FirstPersonCamera, Group, HemisphereLight, Instance, InstancedLod, InstancedMesh, Lod, Mesh, OrbitCamera, PerspectiveCamera, PointLight, RecordMesh, Scene, SpotLight, Sprite, View3d, useScene, Shot, Shots } from "./components/index.ts"
 export type {
   CameraTarget,
   DirectionalLightProps,
@@ -73,13 +73,16 @@ export type {
   SpriteProps,
   TransformProps,
   View3dProps,
+  ShotProps,
+  ShotsProps,
 } from "./components/index.ts"
 export { gltfExternalUris, isGlb, parseGltf } from "./gltf.ts"
-export type { ModelChannel, ModelClip, ModelData, ModelMaterial, ModelNode, ModelPart, ModelSkin, UriResolver } from "./gltf.ts"
+export type { ModelChannel, ModelClip, ModelData, ModelExtras, ModelMaterial, ModelNode, ModelPart, ModelSkin, UriResolver } from "./gltf.ts"
 export { decodeModel, encodeModel } from "./model-file.ts"
 export { createModel, loadGltf, loadModel } from "./model.ts"
 export type { Model, ModelMaps, ModelOptions } from "./model.ts"
 export { bindSkeleton } from "./skeleton.ts"
+export type { BindSkeletonOptions } from "./skeleton.ts"
 export { createMixer } from "./mixer.ts"
 export type { Mixer, MixerOptions, MixerPlayOptions } from "./mixer.ts"
 export { channelElements, sampleChannel } from "./clip.ts"
@@ -87,7 +90,9 @@ export { createOrbitCamera } from "./orbit.ts"
 export type { OrbitAxes, OrbitCamera as OrbitCameraHandle, OrbitCameraOptions, OrbitPose, OrbitPoseState, OrbitTarget } from "./orbit.ts"
 export { createFirstPersonCamera } from "./first-person.ts"
 export type { FirstPersonAxes, FirstPersonCamera as FirstPersonCameraHandle, FirstPersonCameraOptions, FirstPersonPose, FirstPersonPoseState, FirstPersonTarget } from "./first-person.ts"
-export { firstPersonActions, firstPersonBindings, orbitActions, orbitBindings } from "./input.ts"
+export { createShots, mixCamera } from "./shots.ts"
+export type { ShotsHandle, ShotsOwner, ShotTarget } from "./shots.ts"
+export { firstPersonActions, firstPersonBindings, mapBindings, orbitActions, orbitBindings } from "./input.ts"
 export type { CameraDevices } from "./input.ts"
 // math's lookAt (the camera view matrix) stays on the /math subpath: the
 // root's lookAt is the scene verb, the same split as `add`.