@solidrt/3d 0.0.60 → 0.0.62

package/src/model-data.ts

@@ -0,0 +1,27 @@
+// @solidrt/3d/model - the model DATA side of the package without the
+// runtime: the glTF parser, the .srtm container and the pure geometry kit,
+// for a script that bakes an app's own geometry under bun (or any host
+// with no flux). The package root imports `flux:*` and so loads only on
+// the runtime; this entry imports nothing that does. tools/model.ts (the
+// glTF bake) runs on exactly this surface, so an app's bake script and
+// the tool share one path:
+//
+//   import { box, encodeModel, transformGeometry } from "@solidrt/3d/model"
+//   writeFileSync("assets/terrain.srtm", encodeModel({ nodes, parts, ... }))
+//
+// createModel / loadModel on the runtime read what it writes. Keep this
+// entry pure: tests/model-data.test.ts imports it under bun and fails the
+// moment a runtime import creeps into the chain.
+
+export { gltfExternalUris, isGlb, parseGltf } 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 { arrowHelper, axesHelper, box, box3Helper, capsule, capsuleHelper, circle, cone, cylinder, dodecahedron, fillAttribute, fillColors, edgesGeometry, mergeVertices, normalsHelper, toNonIndexed, withNormals, geometryBounds, geometryTopology, gridHelper, icosahedron, attributeAccess, geometryAttribute, geometryKey, geometryLayouts, geometrySlot, geometryStreams, geometryVertexCount, isFloatFormat, isFloatLayout, layoutAttributes, layoutKey, layoutSlot, layoutStride, mergeGeometries, octahedron, packGeometry, packMorphTargets, plane, planeHelper, polyhedron, ring, sphere, tetrahedron, torus, torusKnot, transformGeometry, validateGeometry, wireframeGeometry, vertexBytes, vertexCount, vertexView, withAttribute, withColors, withMorphTargets, MORPH_ENTRY_TEXELS, MORPH_TEXEL_FLOATS, BASE_FLOATS, VERTEX_FORMATS, VERTEX_LAYOUTS } from "./geometry.ts"
+export type { ArrowHelperOptions, AttributeAccess, AttributeFill, VertexStream, WithAttributeOptions, AxesHelperOptions, BoxOptions, CapsuleHelperOptions, CapsuleOptions, CircleOptions, ColorFill, ConeOptions, CylinderOptions, FormatCodec, Geometry, GeometryOptions, GridHelperOptions, MorphTarget, MorphTargets, NormalsHelperOptions, PlaneHelperOptions, PlaneOptions, PolyhedronOptions, RingOptions, SphereOptions, TorusKnotOptions, TorusOptions, VertexLayout } from "./geometry.ts"
+export { fillet, roundRect, triangulate } from "./profile.ts"
+export type { Profile, ProfilePoint } from "./profile.ts"
+export { extrude, lathe, pathFrames, polygon, sweep, tube } from "./sweep.ts"
+export type { ExtrudeOptions, LatheOptions, PathFrames, PathPoint, SweepPath, TubeOptions } from "./sweep.ts"
+export { linearColor, linearToSrgb, premultipliedColor, srgbToLinear } from "./color.ts"
+export { rayBoxDistance, compose, copy, eulerFromQuat, identity, lookAt, mat4, multiply, normalMatrix, orthographic, perspective, quat, quatFromAxisAngle, quatFromEuler, quatFromFrame, quatFromTo, quatMultiply, quatNormalize, quatSlerp } from "./math.ts"
+export type { Mat4, Quat, Vec2, Vec3 } from "./math.ts"

package/src/model-file.ts

@@ -7,12 +7,19 @@
 //   "SRTM" u32 | version u32 | jsonLength u32 | json (padded to 4) | payload
 // The JSON header describes each block's byte range into the payload; every
 // block starts 4-aligned so Float32Array/Uint32Array views sit on it
-// directly. Images travel as their encoded files (PNG/JPEG bytes).
+// directly. Images travel as their encoded files (PNG/JPEG bytes), app
+// data as the header's `extras` (JSON) and named `blobs` (aligned blocks).
+// Geometry is a table the parts index, and a buffer view is written once
+// however many geometries read it: parts sharing a Geometry object (a
+// skinned or morphed mesh several nodes place) share one entry, and two
+// geometries over one vertex buffer (a mirrored copy: same vertices, the
+// flipped index order) share the vertex block - decodeModel restores the
+// same identities, so the runtime uploads shared bytes once.
 
-import type { ModelChannel, ModelData, ModelMaterial, ModelNode, ModelSkin } from "./gltf.ts"
+import type { ModelChannel, ModelData, ModelExtras, ModelMaterial, ModelNode, ModelSkin } from "./gltf.ts"
 import { layoutStride, vertexView, VERTEX_FORMATS } from "./geometry.ts"
 import type { VertexAttribute } from "@solidrt/core/gpu"
-import type { VertexLayout } from "./geometry.ts"
+import type { Geometry, VertexLayout } from "./geometry.ts"
 
 /** "SRTM" read as a little-endian u32. */
 const MAGIC = 0x4d545253
@@ -39,7 +46,15 @@ const MAGIC = 0x4d545253
 // Version 9 names the plain layout "base" (position, normal, uv - the
 // prefix "colored" and "skinned" extend) where version 8 wrote
 // "standard"; a version-8 file's layout word does not parse.
-const VERSION = 9
+// Version 10 carries app data and reuse: `extras` (JSON) on the root, the
+// nodes, the parts and the materials, named binary `blobs` as payload
+// blocks, a part's `placements` (the further nodes drawing the same
+// geometry), and geometry as a table the parts index (shared entries and
+// shared blocks, see the header). A version-9 file has none of these and is rejected like
+// every earlier version rather than read as a file without them, so a
+// stale bake never silently drops the data an app relies on. Re-bake
+// with `srt tool 3d/model`.
+const VERSION = 10
 
 // The named layouts the container writes by name; a custom attribute-list
 // layout (a skinned primitive with COLOR_0, a withAttribute channel) is
@@ -61,17 +76,29 @@ function decodeLayout(layout: string | VertexAttribute[], name: string): VertexL
 
 type Block = { offset: number; bytes: number }
 
-type PartHeader = Block & {
-  name: string
-  node: number
-  skin: number | null
-  material: number
+/** One geometry of the table: its interleaved vertex block, index block
+ * and packed morph targets. Blocks may be shared between entries. */
+type GeometryHeader = {
+  vertices: Block
   layout: string | VertexAttribute[]
   vertexCount: number
   indexBits: 16 | 32
   index: Block
-  /** The part's packed morph targets, when it has any. */
+  /** The packed morph targets, when it has any. */
   morphs?: { names: string[]; texels: Block; extent: number[] }
+  label?: string
+}
+
+type PartHeader = {
+  name: string
+  node: number
+  skin: number | null
+  material: number
+  /** Index into the header's geometry table. */
+  geometry: number
+  /** The further nodes placing the part's geometry (ModelPart.placements). */
+  placements?: number[]
+  extras?: ModelExtras
 }
 
 type SkinHeader = { joints: number[]; inverseBind: Block; jointBounds: Block }
@@ -90,10 +117,16 @@ type Header = {
   nodes: ModelNode[]
   materials: ModelMaterial[]
   images: Block[]
+  geometries: GeometryHeader[]
   parts: PartHeader[]
   skins: SkinHeader[]
   clips: ClipHeader[]
   bounds: number[]
+  /** The root extras (ModelData.extras); node and material extras ride
+   * inside their own records. */
+  extras?: ModelExtras
+  /** The named binary sections (ModelData.blobs), each its own block. */
+  blobs?: Record<string, Block>
 }
 
 /** Serialize a model into the .srtm container. */
@@ -112,29 +145,49 @@ export function encodeModel(data: ModelData): Uint8Array {
     return block
   }
 
-  let parts: PartHeader[] = data.parts.map((part) => {
-    let g = part.geometry
+  // A buffer view is written once however many geometries read it, and a
+  // Geometry object gets one table entry however many parts draw it.
+  let views = new Map<ArrayBufferView, Block>()
+  let pushOnce = (view: ArrayBufferView): Block => {
+    let have = views.get(view)
+    if (have !== undefined) return have
+    let block = push(new Uint8Array(view.buffer, view.byteOffset, view.byteLength))
+    views.set(view, block)
+    return block
+  }
+  let geometries: GeometryHeader[] = []
+  let geometryIds = new Map<Geometry, number>()
+  let geometryId = (g: Geometry, name: string): number => {
+    let id = geometryIds.get(g)
+    if (id !== undefined) return id
     if (g.streams !== undefined && g.streams.length > 0) {
-      throw new Error("encodeModel: part '" + part.name + "' carries extra vertex streams; the container writes one interleaved buffer per part")
+      throw new Error("encodeModel: part '" + name + "' carries extra vertex streams; the container writes one interleaved buffer per geometry")
     }
     let layout = g.layout === undefined ? "base" : g.layout
-    let vertices = push(new Uint8Array(g.vertices.buffer, g.vertices.byteOffset, g.vertices.byteLength))
-    let index = push(new Uint8Array(g.indices.buffer, g.indices.byteOffset, g.indices.byteLength))
+    let header: GeometryHeader = {
+      vertices: pushOnce(g.vertices),
+      layout,
+      vertexCount: g.vertices.byteLength / layoutStride(layout),
+      indexBits: g.indices instanceof Uint32Array ? 32 : 16,
+      index: pushOnce(g.indices),
+    }
+    if (g.morphs !== undefined) header.morphs = { names: g.morphs.names, texels: pushOnce(g.morphs.texels), extent: Array.from(g.morphs.extent) }
+    if (g.label !== undefined) header.label = g.label
+    id = geometries.length
+    geometries.push(header)
+    geometryIds.set(g, id)
+    return id
+  }
+  let parts: PartHeader[] = data.parts.map((part) => {
     let header: PartHeader = {
-      ...vertices,
       name: part.name,
       node: part.node,
       skin: part.skin,
       material: part.material,
-      layout,
-      vertexCount: g.vertices.byteLength / layoutStride(layout),
-      indexBits: g.indices instanceof Uint32Array ? 32 : 16,
-      index,
-    }
-    if (g.morphs !== undefined) {
-      let texels = push(new Uint8Array(g.morphs.texels.buffer, g.morphs.texels.byteOffset, g.morphs.texels.byteLength))
-      header.morphs = { names: g.morphs.names, texels, extent: Array.from(g.morphs.extent) }
+      geometry: geometryId(part.geometry, part.name),
     }
+    if (part.placements !== undefined && part.placements.length > 0) header.placements = part.placements
+    if (part.extras !== undefined) header.extras = part.extras
     return header
   })
   let images = data.images.map((image) => push(image))
@@ -151,7 +204,12 @@ export function encodeModel(data: ModelData): Uint8Array {
       values: floats(c.values),
     })),
   }))
-  let header: Header = { nodes: data.nodes, materials: data.materials, images, parts, skins, clips, bounds: Array.from(data.bounds) }
+  let header: Header = { nodes: data.nodes, materials: data.materials, images, geometries, parts, skins, clips, bounds: Array.from(data.bounds) }
+  if (data.extras !== undefined) header.extras = data.extras
+  if (data.blobs !== undefined) {
+    header.blobs = {}
+    for (let [name, bytes] of Object.entries(data.blobs)) header.blobs[name] = push(bytes)
+  }
 
   let json = new TextEncoder().encode(JSON.stringify(header))
   let jsonPadded = json.byteLength + ((4 - (json.byteLength % 4)) % 4)
@@ -187,26 +245,37 @@ export function decodeModel(bytes: Uint8Array): ModelData {
   let header: Header = JSON.parse(new TextDecoder().decode(new Uint8Array(buffer, base + 12, jsonLength)))
   let payload = base + 12 + jsonLength + ((4 - (jsonLength % 4)) % 4)
 
-  let parts = header.parts.map((part) => {
-    let layout = decodeLayout(part.layout, part.name)
-    let indexCount = part.index.bytes / (part.indexBits / 8)
-    let geometry: ModelData["parts"][0]["geometry"] = {
-      vertices: vertexView(layout, buffer, payload + part.offset, part.vertexCount * layoutStride(layout)),
-      indices: part.indexBits === 32 ? new Uint32Array(buffer, payload + part.index.offset, indexCount) : new Uint16Array(buffer, payload + part.index.offset, indexCount),
-      label: part.name,
+  // The geometry table first: one Geometry object per entry, so parts
+  // naming the same entry share it (and the runtime shares its buffers).
+  let geometries: Geometry[] = header.geometries.map((g, i) => {
+    let name = g.label ?? "geometry " + i
+    let layout = decodeLayout(g.layout, name)
+    let indexCount = g.index.bytes / (g.indexBits / 8)
+    let geometry: Geometry = {
+      vertices: vertexView(layout, buffer, payload + g.vertices.offset, g.vertexCount * layoutStride(layout)),
+      indices: g.indexBits === 32 ? new Uint32Array(buffer, payload + g.index.offset, indexCount) : new Uint16Array(buffer, payload + g.index.offset, indexCount),
     }
-    if (part.layout !== "base") geometry.layout = layout
-    if (part.morphs !== undefined) {
-      let m = part.morphs
+    if (g.label !== undefined) geometry.label = g.label
+    if (g.layout !== "base") geometry.layout = layout
+    if (g.morphs !== undefined) {
+      let m = g.morphs
       geometry.morphs = { names: m.names, texels: new Float32Array(buffer, payload + m.texels.offset, m.texels.bytes / 4), extent: Float32Array.from(m.extent) }
     }
-    return {
+    return geometry
+  })
+  let parts = header.parts.map((part) => {
+    let geometry = geometries[part.geometry]
+    if (geometry === undefined) throw new Error("decodeModel: part '" + part.name + "' names a missing geometry " + part.geometry)
+    let out: ModelData["parts"][0] = {
       name: part.name,
       node: part.node,
       skin: part.skin,
       material: part.material,
       geometry,
     }
+    if (part.placements !== undefined) out.placements = part.placements
+    if (part.extras !== undefined) out.extras = part.extras
+    return out
   })
   let images = header.images.map((block) => new Uint8Array(buffer, payload + block.offset, block.bytes))
   let floats = (block: Block): Float32Array => new Float32Array(buffer, payload + block.offset, block.bytes / 4)
@@ -222,5 +291,11 @@ export function decodeModel(bytes: Uint8Array): ModelData {
       values: floats(c.values),
     })),
   }))
-  return { nodes: header.nodes, parts, skins, clips, materials: header.materials, images, bounds: Float32Array.from(header.bounds) }
+  let data: ModelData = { nodes: header.nodes, parts, skins, clips, materials: header.materials, images, bounds: Float32Array.from(header.bounds) }
+  if (header.extras !== undefined) data.extras = header.extras
+  if (header.blobs !== undefined) {
+    data.blobs = {}
+    for (let [name, block] of Object.entries(header.blobs)) data.blobs[name] = new Uint8Array(buffer, payload + block.offset, block.bytes)
+  }
+  return data
 }

package/src/model.ts

@@ -3,11 +3,17 @@
 // local TRS, each part's mesh under its node - with the images uploaded as
 // textures and a material per glTF material: Three's `gltf.scene`, an
 // object you add to the scene and place with setTransform, whose named
-// nodes (`model.nodes`) can be moved individually. The model owns what it
-// created (geometry buffers, textures): dispose() frees them and detaches
-// the group. loadGltf / loadModel are the read-then-create conveniences
-// over flux:fs; parseGltf / decodeModel + createModel are the primitives
-// under them, for bytes obtained any other way (a binary import, a fetch).
+// nodes (`model.nodes`) can be moved individually. A part several nodes
+// place (ModelPart.placements: a reused mesh, EXT_mesh_gpu_instancing) is
+// ONE InstancedMesh at identity under the model root with an instance
+// under every placement node, so the copies are one draw entry and still
+// ride, animate, pick and cull as nodes of the hierarchy. The file's
+// extras and blobs come along as plain data. The model owns what it
+// created (geometry buffers, record buffers, textures): dispose() frees
+// them and detaches the group. loadGltf / loadModel are the
+// read-then-create conveniences over flux:fs; parseGltf / decodeModel +
+// createModel are the primitives under them, for bytes obtained any other
+// way (a binary import, a fetch).
 
 import { file } from "flux:fs"
 import * as spatial from "flux:spatial"
@@ -16,7 +22,7 @@ import type { Owner } from "@solidrt/core"
 import { createMutableTexture, createTexture, destroyTexture } from "@solidrt/core/gpu"
 import type { TextureId } from "@solidrt/core/gpu"
 import { gltfExternalUris, parseGltf } from "./gltf.ts"
-import type { ModelClip, ModelData, ModelMaterial } from "./gltf.ts"
+import type { ModelClip, ModelData, ModelExtras, ModelMaterial } from "./gltf.ts"
 import { decodeModel } from "./model-file.ts"
 import { disposeGeometry } from "./geometry-gpu.ts"
 import { layoutSlot } from "./geometry.ts"
@@ -24,8 +30,8 @@ import { standard } from "./material.ts"
 import type { Material } from "./material.ts"
 import { add, afterFree, createGroup, createMorphState, remove, setTransform } from "./node.ts"
 import type { SceneNode } from "./node.ts"
-import { createMesh } from "./mesh.ts"
-import type { Mesh } from "./mesh.ts"
+import { addInstance, createInstancedMesh, createMesh, disposeInstances } from "./mesh.ts"
+import type { InstancedMesh, InstanceNode, Mesh } from "./mesh.ts"
 import { refreshJointBounds, unbindSkeleton } from "./skeleton.ts"
 import type { WornPiece } from "./skeleton.ts"
 
@@ -61,9 +67,13 @@ export type ModelOptions = {
    * `vertexColors` is true when the part carries COLOR_0 in aColor (pass
    * it through, or read aColor yourself); `morphed` is true when the part
    * carries morph targets (pass it through as `morph`, or splice
-   * MORPH_DECLS/MORPH_APPLY yourself). `data.materials` is in file order,
-   * so the calls arrive in file order too. */
-  material?: (material: ModelMaterial, maps: ModelMaps, skinned: boolean, vertexColors: boolean, morphed: boolean) => Material
+   * MORPH_DECLS/MORPH_APPLY yourself); `instanced` is true when the part
+   * is a population (ModelPart.placements: drawn as one InstancedMesh),
+   * so the material must be instanced (pass it through as `instanced`,
+   * or declare INSTANCE_MATRIX_ATTRIBUTES and splice INSTANCE_MATRIX
+   * yourself). `data.materials` is in file order, so the calls arrive in
+   * file order too. */
+  material?: (material: ModelMaterial, maps: ModelMaps, skinned: boolean, vertexColors: boolean, morphed: boolean, instanced: boolean) => Material
   /** Debug name for the textures. */
   label?: string
   /** Free the model with the owning reactive scope (default true, like
@@ -77,15 +87,31 @@ export type ModelOptions = {
  * nested Groups, with each part's mesh a child of its node. */
 export type Model = SceneNode & {
   kind: "group"
-  /** The parts by name, in file order; each `mesh` sits under its node. */
-  parts: { name: string; mesh: Mesh }[]
+  /** The parts by name, in file order; each `mesh` sits under its node.
+   * A part with placements (a mesh several nodes place) is instead ONE
+   * InstancedMesh at identity under the model root, with `instances` in
+   * placement order (the part's node first, then its placements), each
+   * an instance node at identity under its placement node in `nodes`:
+   * move the placement node and its copy follows; a pick on a copy
+   * reports `hit.mesh` = this mesh and `hit.instance` one of these
+   * (its `parent` is the placement node). A material swap on the mesh
+   * applies to every copy. `extras` is the glTF mesh's, when it has
+   * any. */
+  parts: { name: string; mesh: Mesh; instances?: InstanceNode[]; extras?: ModelExtras }[]
   /** The file's retained nodes in table order (parents first), each an
    * ordinary Group under the model: `setTransform` on one moves its
    * subtree - a wheel spins relative to the axle it hangs from. Names
-   * repeat when the file's do; find yours with `.find()`/`.filter()`. */
-  nodes: { name: string; node: SceneNode }[]
+   * repeat when the file's do; find yours with `.find()`/`.filter()`.
+   * `extras` is the glTF node's, when it has any. */
+  nodes: { name: string; node: SceneNode; extras?: ModelExtras }[]
   /** One per glTF material, in file order. */
   materials: Material[]
+  /** The file's root extras (glTF `extras`, or what a bake wrote), when
+   * it has any. */
+  extras?: ModelExtras
+  /** The file's named binary sections (a bake's), when it has any: views
+   * onto the loaded bytes. */
+  blobs?: Record<string, Uint8Array>
   /** The file's animation clips (empty when it has none); createMixer
    * plays them. Channel node indices resolve through `nodes`. */
   clips: ModelClip[]
@@ -144,7 +170,7 @@ export function createModel(data: ModelData, opts: ModelOptions = {}): Model {
       label: label ? label + "-image" + i : undefined,
     })
   })
-  let make = opts.material ?? ((m: ModelMaterial, maps: ModelMaps, skinned: boolean, vertexColors: boolean, morphed: boolean): Material => {
+  let make = opts.material ?? ((m: ModelMaterial, maps: ModelMaps, skinned: boolean, vertexColors: boolean, morphed: boolean, instanced: boolean): Material => {
     // An emissive factor of zero is emission OFF (the glTF product rule:
     // factor times texture), so the map is skipped too - no sampler for
     // a term that cannot show.
@@ -167,18 +193,20 @@ export function createModel(data: ModelData, opts: ModelOptions = {}): Model {
       skinned: skinned || undefined,
       vertexColors: vertexColors || undefined,
       morph: morphed || undefined,
+      instanced: instanced || undefined,
     })
   })
   let slot = (index: number | null): TextureId | null => (index === null ? null : textures[index]!)
   // One instance per glTF material as today, plus a skinned variant per
-  // material the skinned parts bring and a vertex-colored one per material
-  // the COLOR_0 parts bring (a material shared by parts that differ in
-  // either needs two programs - different vertex stages).
+  // material the skinned parts bring, a vertex-colored one per material
+  // the COLOR_0 parts bring, a morphed and an instanced one likewise (a
+  // material shared by parts that differ in any needs two programs -
+  // different vertex stages).
   let variants = new Map<string, Material>()
-  let materialFor = (index: number, skinned: boolean, vertexColors: boolean, morphed: boolean): Material => {
+  let materialFor = (index: number, skinned: boolean, vertexColors: boolean, morphed: boolean, instanced: boolean): Material => {
     let m = data.materials[index]
     if (m === undefined) throw new Error("createModel: a part names a missing material " + index)
-    let key = index + (skinned ? "|skinned" : "") + (vertexColors ? "|colored" : "") + (morphed ? "|morphed" : "")
+    let key = index + (skinned ? "|skinned" : "") + (vertexColors ? "|colored" : "") + (morphed ? "|morphed" : "") + (instanced ? "|instanced" : "")
     let made = variants.get(key)
     if (made === undefined) {
       made = make(
@@ -193,12 +221,13 @@ export function createModel(data: ModelData, opts: ModelOptions = {}): Model {
         skinned,
         vertexColors,
         morphed,
+        instanced,
       )
       variants.set(key, made)
     }
     return made
   }
-  let materials = data.materials.map((_, i) => materialFor(i, false, false, false))
+  let materials = data.materials.map((_, i) => materialFor(i, false, false, false, false))
 
   let model = createGroup() as Model
   model._skins = []
@@ -213,7 +242,7 @@ export function createModel(data: ModelData, opts: ModelOptions = {}): Model {
     return group
   })
   data.nodes.forEach((n, i) => add(n.parent === null ? model : groups[n.parent]!, groups[i]!))
-  model.nodes = data.nodes.map((n, i) => ({ name: n.name, node: groups[i]! }))
+  model.nodes = data.nodes.map((n, i) => (n.extras === undefined ? { name: n.name, node: groups[i]! } : { name: n.name, node: groups[i]!, extras: n.extras }))
   // A glTF node with morph targets owns its parts' weights (the file's
   // node.weights / mesh.weights seed them): one register, one weights
   // texture, every part of the mesh reads it - so setMorphWeights on
@@ -268,10 +297,37 @@ export function createModel(data: ModelData, opts: ModelOptions = {}): Model {
   // Each joint's influence box, in joint space: culling-only bounds the
   // flush carries through the pose, united over every skin reaching it.
   refreshJointBounds(model)
+  let groupOf = (part: ModelData["parts"][0], index: number): SceneNode => {
+    let node = groups[index]
+    if (node === undefined) throw new Error("createModel: part '" + part.name + "' names a missing node " + index)
+    return node
+  }
   model.parts = data.parts.map((part) => {
     let skinned = part.skin !== null
     let morphed = part.geometry.morphs !== undefined
-    let material = materialFor(part.material, skinned, layoutSlot(part.geometry.layout, "aColor") !== null, morphed)
+    let colored = layoutSlot(part.geometry.layout, "aColor") !== null
+    let extras = part.extras
+    let placements = part.placements ?? []
+    if (placements.length > 0) {
+      // A population: the geometry once, drawn per placement. The mesh
+      // sits at identity under the model root, which anchors its records,
+      // and each placement node - the first is `part.node` - carries an
+      // instance at identity, so the record the core writes is that
+      // node's model-relative world: moving the node (setTransform, a
+      // clip, a transition) moves the copy, hiding it hides the copy,
+      // and a pick lands on the instance. Skins place by palette and
+      // morph weights are per node, so neither can share one geometry;
+      // parseGltf never folds them, and a hand-built ModelData that does
+      // is refused rather than drawn wrong.
+      if (skinned) throw new Error("createModel: part '" + part.name + "' is skinned and has placements; a skinned part cannot be shared")
+      if (morphed) throw new Error("createModel: part '" + part.name + "' has morph targets and placements; a morphed part cannot be shared")
+      let material = materialFor(part.material, false, colored, false, true)
+      let mesh = createInstancedMesh(part.geometry, material, { capacity: placements.length + 1, anchor: model, label: label ? label + "-" + part.name : part.name })
+      add(model, mesh)
+      let instances = [part.node, ...placements].map((index) => addInstance(mesh, undefined, groupOf(part, index)))
+      return extras === undefined ? { name: part.name, mesh, instances } : { name: part.name, mesh, instances, extras }
+    }
+    let material = materialFor(part.material, skinned, colored, morphed, false)
     let mesh = createMesh(part.geometry, material)
     // The part's weights are its glTF node's (above), not its own.
     if (morphed) mesh._morphOwner = groups[part.node] ?? mesh
@@ -287,15 +343,15 @@ export function createModel(data: ModelData, opts: ModelOptions = {}): Model {
       mesh._cullJoints = skin.joints.slice()
       add(model, mesh)
     } else {
-      let node = groups[part.node]
-      if (node === undefined) throw new Error("createModel: part '" + part.name + "' names a missing node " + part.node)
-      add(node, mesh)
+      add(groupOf(part, part.node), mesh)
     }
-    return { name: part.name, mesh }
+    return extras === undefined ? { name: part.name, mesh } : { name: part.name, mesh, extras }
   })
   model.materials = materials
   model.clips = data.clips
   model.bounds = data.bounds
+  if (data.extras !== undefined) model.extras = data.extras
+  if (data.blobs !== undefined) model.blobs = data.blobs
   let disposed = false
   model.dispose = () => {
     if (disposed) return
@@ -311,7 +367,12 @@ export function createModel(data: ModelData, opts: ModelOptions = {}): Model {
     // destroyed texture.
     if (afterFree(model, () => model.dispose())) return
     disposed = true
-    for (let part of model.parts) disposeGeometry(part.mesh.geometry)
+    for (let part of model.parts) {
+      // A population's record buffers are mesh-owned (the one explicit
+      // free); its geometry buffers are shared like any part's.
+      if (part.instances !== undefined) disposeInstances(part.mesh as InstancedMesh)
+      disposeGeometry(part.mesh.geometry)
+    }
     for (let id of textures) destroyTexture(id)
     textures.length = 0
     // The nodes' weights textures (the parts' entries are off the scene

package/src/node.ts

@@ -163,7 +163,7 @@ export type SceneHooks = {
   _setLayers(mesh: Mesh): void
   /** A light's castShadow/shadow options changed. */
   _shadowChanged(light: CastingLight): void
-  _reorder(): void
+  _reorder(mesh: Mesh): void
   /** The node's transform changed (for the sort and light bookkeeping). */
   _moved(node: SceneNode): void
   /** Push the node's LOD declaration (`_lod`) to the core: at scene enter