@umicat/three-sdk 1.17.1 → 1.19.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,5 +1,5 @@
1
1
  import * as THREE from 'three';
2
- import { type Scene3D, type Manifest3D, type Entity3D, type Sky3D } from './scene3d.js';
2
+ import { type Scene3D, type Manifest3D, type Entity3D, type Vec3, type Sky3D } from './scene3d.js';
3
3
  import { type WornMap } from './Attachments.js';
4
4
  export interface LoadSceneOptions {
5
5
  /** Base url assets resolve against (the project's asset host). */
@@ -59,6 +59,17 @@ export declare const MATERIAL_LIBRARY: Record<string, {
59
59
  color: string;
60
60
  roughness: string;
61
61
  }>;
62
+ /**
63
+ * ADR-050 — the surface mesh for a heightfield, from the row-major
64
+ * `[iz * (n+1) + ix]` grid `resampleHeights` produces.
65
+ *
66
+ * Centred on the entity's origin in x/z and rising from it in y — the base
67
+ * sits AT the origin rather than straddling it, so a terrain dropped at y=0
68
+ * has its lowest point on the ground. That matches how every modular ground
69
+ * tile in the public library is authored and is the thing a person expects
70
+ * when they drag one in.
71
+ */
72
+ export declare function heightfieldGeometry(heights: Float32Array, n: number, size: Vec3): THREE.BufferGeometry;
62
73
  export declare function makePrimitive(e: Entity3D): THREE.Mesh;
63
74
  /**
64
75
  * Turn scene3d design data into a running three.js scene.
@@ -1,12 +1,95 @@
1
1
  import * as THREE from 'three';
2
2
  import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
3
3
  import { clone as cloneRigged } from 'three/examples/jsm/utils/SkeletonUtils.js';
4
- import { validateScene, IDENTITY_QUAT, wedgeVertices, cornerWedgeVertices, defaultColliderForPrimitive, } from './scene3d.js';
4
+ import { validateScene, IDENTITY_QUAT, wedgeVertices, cornerWedgeVertices, defaultColliderForPrimitive, resampleHeights, heightfieldColliderArgs, } from './scene3d.js';
5
5
  import { applySkin } from './Skin.js';
6
6
  import { applyAttachments } from './Attachments.js';
7
7
  function toVec(v, d = 0) {
8
8
  return new THREE.Vector3(v?.x ?? d, v?.y ?? d, v?.z ?? d);
9
9
  }
10
+ /**
11
+ * Collect everything an entity RENDERS into the vertex + index buffers
12
+ * `Rapier.ColliderDesc.trimesh` wants — the collider that follows a concave
13
+ * shape instead of shrink-wrapping it, which is the whole reason the schema
14
+ * offers `trimesh` for static geometry. A convex hull seals every opening: a
15
+ * cave you can see into and not enter, an arch with no gap under it.
16
+ *
17
+ * Vertices come out in the entity ROOT's local frame WITH its authored scale
18
+ * baked in, because that is the frame the rigid body is placed in: the body
19
+ * carries the entity's position and rotation (see the caller) but Rapier
20
+ * bodies have no scale, so unlike `box`/`sphere` — whose authored half-extents
21
+ * already describe final size — a trimesh must carry the scaling itself.
22
+ *
23
+ * `S(root.scale) * inv(root.matrixWorld) * mesh.matrixWorld` is that frame:
24
+ * inverting the root's world matrix removes its position, rotation AND scale,
25
+ * and the scale is then put back deliberately.
26
+ *
27
+ * Returns null when the entity renders no triangles at all, so the caller can
28
+ * skip one collider rather than fail the scene.
29
+ */
30
+ function trimeshData(root, otherEntities) {
31
+ root.updateWorldMatrix(true, true);
32
+ const toRootLocal = new THREE.Matrix4().copy(root.matrixWorld).invert();
33
+ const rescale = new THREE.Matrix4().makeScale(root.scale.x, root.scale.y, root.scale.z);
34
+ const verts = [];
35
+ const idx = [];
36
+ const toCollider = new THREE.Matrix4();
37
+ const v = new THREE.Vector3();
38
+ // Hand-rolled instead of `root.traverse`, because traverse cannot be
39
+ // pruned: a scene can PARENT one entity to another (`Entity3D.parent`),
40
+ // and parenting runs before colliders are built, so a traversal would
41
+ // happily fold a prop's geometry into the scenery it sits on — silently
42
+ // doubling that prop's collision (it owns a collider of its own) and
43
+ // bloating the host's trimesh. A model's own sub-meshes are a different
44
+ // thing entirely and MUST be included, and the only way to tell the two
45
+ // apart is that one of them is itself a registered entity.
46
+ const walk = (o) => {
47
+ if (o !== root && otherEntities.has(o))
48
+ return;
49
+ visit(o);
50
+ for (const child of o.children)
51
+ walk(child);
52
+ };
53
+ const visit = (o) => {
54
+ const mesh = o;
55
+ if (!mesh.isMesh || !mesh.geometry)
56
+ return;
57
+ // Visibility is respected for DESCENDANTS and ignored for the ROOT, and
58
+ // the asymmetry is deliberate. A hidden sub-mesh inside a model is art
59
+ // the author switched off (a variant, an LOD) and must not collide. But
60
+ // an entity hidden in its entirety and given a trimesh collider is the
61
+ // INVISIBLE COLLISION PROXY pattern — real scenes ship exactly that
62
+ // (the editor's `pickEntityAt` has a comment about picking around them)
63
+ // — and skipping it would leave that author with no collider at all,
64
+ // which is the silent-nothing this whole phase exists to remove.
65
+ if (o !== root && mesh.visible === false)
66
+ return;
67
+ const pos = mesh.geometry.getAttribute('position');
68
+ if (!pos)
69
+ return;
70
+ toCollider.copy(toRootLocal).multiply(mesh.matrixWorld).premultiply(rescale);
71
+ const base = verts.length / 3;
72
+ for (let i = 0; i < pos.count; i++) {
73
+ v.fromBufferAttribute(pos, i).applyMatrix4(toCollider);
74
+ verts.push(v.x, v.y, v.z);
75
+ }
76
+ const index = mesh.geometry.getIndex();
77
+ if (index) {
78
+ for (let i = 0; i < index.count; i++)
79
+ idx.push(base + index.getX(i));
80
+ }
81
+ else {
82
+ // Non-indexed geometry is already triangle soup — every three
83
+ // consecutive vertices form a face.
84
+ for (let i = 0; i < pos.count; i++)
85
+ idx.push(base + i);
86
+ }
87
+ };
88
+ walk(root);
89
+ if (idx.length < 3)
90
+ return null;
91
+ return { vertices: new Float32Array(verts), indices: new Uint32Array(idx) };
92
+ }
10
93
  /** `Rapier.ColliderDesc.convexHull` wants a flat `[x,y,z, x,y,z, ...]` buffer. */
11
94
  function flattenPoints(points) {
12
95
  const out = new Float32Array(points.length * 3);
@@ -182,6 +265,89 @@ function materialRepeatFor(kind, size, tileUnit) {
182
265
  }
183
266
  return new THREE.Vector2(u(size.x), u(size.z));
184
267
  }
268
+ /**
269
+ * ADR-050 — the surface mesh for a heightfield, from the row-major
270
+ * `[iz * (n+1) + ix]` grid `resampleHeights` produces.
271
+ *
272
+ * Centred on the entity's origin in x/z and rising from it in y — the base
273
+ * sits AT the origin rather than straddling it, so a terrain dropped at y=0
274
+ * has its lowest point on the ground. That matches how every modular ground
275
+ * tile in the public library is authored and is the thing a person expects
276
+ * when they drag one in.
277
+ */
278
+ export function heightfieldGeometry(heights, n, size) {
279
+ const side = n + 1;
280
+ const positions = new Float32Array(side * side * 3);
281
+ const uvs = new Float32Array(side * side * 2);
282
+ for (let iz = 0; iz < side; iz++) {
283
+ for (let ix = 0; ix < side; ix++) {
284
+ const i = iz * side + ix;
285
+ positions[i * 3] = (ix / n - 0.5) * size.x;
286
+ positions[i * 3 + 1] = heights[i] * size.y;
287
+ positions[i * 3 + 2] = (iz / n - 0.5) * size.z;
288
+ uvs[i * 2] = ix / n;
289
+ uvs[i * 2 + 1] = 1 - iz / n;
290
+ }
291
+ }
292
+ const indices = [];
293
+ for (let iz = 0; iz < n; iz++) {
294
+ for (let ix = 0; ix < n; ix++) {
295
+ const a = iz * side + ix, b = a + 1, c = a + side, d = c + 1;
296
+ // (a, c, b) and (b, c, d) — this winding is what faces the triangles
297
+ // UP. Reversed, the terrain is invisible from above and solid-looking
298
+ // from underneath, with backface culling making it look like the mesh
299
+ // simply failed to load.
300
+ indices.push(a, c, b, b, c, d);
301
+ }
302
+ }
303
+ const geom = new THREE.BufferGeometry();
304
+ geom.setAttribute('position', new THREE.BufferAttribute(positions, 3));
305
+ geom.setAttribute('uv', new THREE.BufferAttribute(uvs, 2));
306
+ geom.setIndex(indices);
307
+ geom.computeVertexNormals();
308
+ return geom;
309
+ }
310
+ const heightmapPixelCache = new Map();
311
+ /**
312
+ * Decode a heightmap image to normalised 0..1 luminance, row-major.
313
+ *
314
+ * Browser-only by necessity (it draws to a canvas to read pixels back), and
315
+ * cached per url because several entities commonly share one heightmap — a
316
+ * tiled landscape being the obvious case.
317
+ */
318
+ function heightmapPixels(url) {
319
+ const hit = heightmapPixelCache.get(url);
320
+ if (hit)
321
+ return hit;
322
+ const p = new THREE.ImageLoader().setCrossOrigin('anonymous').loadAsync(url).then((img) => {
323
+ const width = img.width;
324
+ const height = img.height;
325
+ const canvas = document.createElement('canvas');
326
+ canvas.width = width;
327
+ canvas.height = height;
328
+ const ctx = canvas.getContext('2d', { willReadFrequently: true });
329
+ if (!ctx)
330
+ throw new Error('[umicat] heightmap decode needs a 2d canvas context');
331
+ ctx.drawImage(img, 0, 0);
332
+ const rgba = ctx.getImageData(0, 0, width, height).data;
333
+ const data = new Float32Array(width * height);
334
+ for (let i = 0; i < data.length; i++) {
335
+ // Rec.601 luma. A heightmap is normally greyscale, where any channel
336
+ // would do; weighting correctly means a coloured one still produces
337
+ // the brightness a person sees rather than whatever red happens to be.
338
+ data[i] = (0.299 * rgba[i * 4] + 0.587 * rgba[i * 4 + 1] + 0.114 * rgba[i * 4 + 2]) / 255;
339
+ }
340
+ return { data, width, height };
341
+ });
342
+ heightmapPixelCache.set(url, p);
343
+ p.catch(() => heightmapPixelCache.delete(url));
344
+ return p;
345
+ }
346
+ /** Resolution actually used, with the documented defaults applied. */
347
+ function heightfieldSegments(h) {
348
+ const render = h.segments ?? 128;
349
+ return { render, collider: h.colliderSegments ?? render };
350
+ }
185
351
  /**
186
352
  * ADR-047 — rebuilds a `THREE.BufferGeometry` from a baked CSG result's
187
353
  * flat position/index arrays (`Entity3D.primitive.mesh`). `normals` is
@@ -239,34 +405,63 @@ export function makePrimitive(e) {
239
405
  // CDN-texture consumer in this SDK). A missing/renamed material name, or
240
406
  // a failed fetch, silently keeps the flat color rather than erroring —
241
407
  // this is cosmetic, not a thing worth surfacing as a broken scene.
242
- const libEntry = p.material ? MATERIAL_LIBRARY[p.material] : undefined;
243
- if (libEntry) {
244
- const repeat = materialRepeatFor(p.kind, s, MATERIAL_TILE_UNIT[p.material] ?? 1);
245
- void Promise.all([
246
- loadMaterialTexture(libEntry.color, THREE.SRGBColorSpace),
247
- loadMaterialTexture(libEntry.roughness, THREE.NoColorSpace),
248
- ]).then(([colorTex, roughTex]) => {
249
- // Cloned, not assigned directly — the cache shares ONE texture per
250
- // url across every Part using this material, and `.repeat` is
251
- // per-INSTANCE (a 1×1 block and a 10×10 platform using the same
252
- // "brick" material need different repeat counts). Assigning the
253
- // cached texture directly would make every Part sharing a material
254
- // fight over the last-set repeat value — the exact "clones share
255
- // materials" trap `Skin.ts` already documents, one level up (here
256
- // it's the TEXTURE being shared, not the material).
257
- const map = colorTex.clone();
258
- const roughnessMap = roughTex.clone();
259
- map.repeat.copy(repeat);
260
- roughnessMap.repeat.copy(repeat);
261
- map.needsUpdate = true;
262
- roughnessMap.needsUpdate = true;
263
- material.map = map;
264
- material.roughnessMap = roughnessMap;
265
- material.needsUpdate = true;
266
- }).catch(() => { });
267
- }
408
+ applyMaterialLibrary(material, p.material, s, p.kind);
268
409
  return mesh;
269
410
  }
411
+ /**
412
+ * ADR-044 — paint a library material onto an already-built material, async.
413
+ *
414
+ * Shared by Parts and (ADR-050) heightfields, which is the reuse boundary
415
+ * ADR-044 names: the library, the cache and this loading dance carry over
416
+ * between geometry kinds, while the FIELD does not — `material` lives on
417
+ * `primitive` and on `heightfield` separately, because an entity-level one
418
+ * would be meaningless on a model (models bring their own materials, and
419
+ * `skin` already covers retexturing them).
420
+ *
421
+ * Flat colour renders immediately; textures arrive and patch the material in
422
+ * place. A missing/renamed name or a failed fetch silently keeps the flat
423
+ * colour — this is cosmetic, not a thing worth surfacing as a broken scene.
424
+ */
425
+ function applyMaterialLibrary(material, name, size, kind) {
426
+ const libEntry = name ? MATERIAL_LIBRARY[name] : undefined;
427
+ if (!libEntry)
428
+ return;
429
+ const repeat = materialRepeatFor(kind, size, MATERIAL_TILE_UNIT[name] ?? 1);
430
+ void Promise.all([
431
+ loadMaterialTexture(libEntry.color, THREE.SRGBColorSpace),
432
+ loadMaterialTexture(libEntry.roughness, THREE.NoColorSpace),
433
+ ]).then(([colorTex, roughTex]) => {
434
+ // Cloned, not assigned directly — the cache shares ONE texture per url
435
+ // across every surface using this material, and `.repeat` is
436
+ // per-INSTANCE (a 1×1 block and a 200×200 terrain using the same
437
+ // "grass" need wildly different repeat counts). Assigning the cached
438
+ // texture directly would make every user of a material fight over the
439
+ // last-set repeat value — the "clones share materials" trap `Skin.ts`
440
+ // documents, one level up: here it is the TEXTURE being shared.
441
+ const map = colorTex.clone();
442
+ const roughnessMap = roughTex.clone();
443
+ map.repeat.copy(repeat);
444
+ roughnessMap.repeat.copy(repeat);
445
+ // Anisotropic filtering, which three.js leaves at 1 by default. Without
446
+ // it a surface with a high repeat count seen at a grazing angle — which
447
+ // is EVERY large surface: a terrain, a long platform, a floor — minifies
448
+ // to a flat average colour. Measured: a 60x60-unit heightfield with the
449
+ // `grass` material rendered as a single uniform green until this line
450
+ // existed, while reporting a perfectly healthy 512x512 texture with a
451
+ // repeat of 60. The symptom looks exactly like "the texture failed to
452
+ // load", which is the wrong thing to go and debug.
453
+ //
454
+ // 16 is a request, not an assumption: three clamps it to the device's
455
+ // own maximum at upload, so this needs no renderer handle to be correct.
456
+ map.anisotropy = 16;
457
+ roughnessMap.anisotropy = 16;
458
+ map.needsUpdate = true;
459
+ roughnessMap.needsUpdate = true;
460
+ material.map = map;
461
+ material.roughnessMap = roughnessMap;
462
+ material.needsUpdate = true;
463
+ }).catch(() => { });
464
+ }
270
465
  /**
271
466
  * Turn scene3d design data into a running three.js scene.
272
467
  *
@@ -404,6 +599,28 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
404
599
  needed.add(a.modelAssetId);
405
600
  }
406
601
  }
602
+ // ADR-050 — heightmaps are fetched and decoded up front, same contract the
603
+ // models above follow: a caller that awaits `loadScene3D` gets a finished
604
+ // scene, not one whose terrain pops in flat and then rises a frame later.
605
+ const heightmaps = new Map((manifest.heightmaps ?? []).map((h) => [h.id, h]));
606
+ const heightmapPixelsById = new Map();
607
+ const heightmapJobs = [];
608
+ for (const e of scene3d.entities) {
609
+ if (!e.heightfield)
610
+ continue;
611
+ const entry = heightmaps.get(e.heightfield.assetId);
612
+ if (!entry) {
613
+ throw new Error(`entity '${e.id}' uses heightmap '${e.heightfield.assetId}', which the manifest does not define. ` +
614
+ `It has: ${[...heightmaps.keys()].join(', ') || '(none)'}`);
615
+ }
616
+ if (heightmapPixelsById.has(entry.id))
617
+ continue;
618
+ heightmapPixelsById.set(entry.id, { data: new Float32Array(1), width: 1, height: 1 });
619
+ heightmapJobs.push(heightmapPixels((opts.assetBase ?? '') + entry.path)
620
+ .then((px) => { heightmapPixelsById.set(entry.id, px); }));
621
+ }
622
+ if (heightmapJobs.length)
623
+ await Promise.all(heightmapJobs);
407
624
  const loaded = new Map();
408
625
  if (needed.size) {
409
626
  const loader = new GLTFLoader();
@@ -416,6 +633,9 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
416
633
  }));
417
634
  }
418
635
  const entities = new Map();
636
+ /** ADR-050 — each heightfield's COLLIDER grid, kept for the physics pass
637
+ * below (which runs after every entity exists). */
638
+ const heightfieldGrids = new Map();
419
639
  const mixers = [];
420
640
  const mixerFor = new Map();
421
641
  const clips = new Map();
@@ -509,6 +729,35 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
509
729
  .then((worn) => { attachments.set(e.id, worn); }));
510
730
  }
511
731
  }
732
+ else if (e.heightfield) {
733
+ if (e.attachments?.length) {
734
+ throw new Error(`entity '${e.id}' has attachments but no model to hang them on`);
735
+ }
736
+ const hf = e.heightfield;
737
+ const px = heightmapPixelsById.get(hf.assetId);
738
+ const seg = heightfieldSegments(hf);
739
+ const heights = resampleHeights(px.data, px.width, px.height, seg.render);
740
+ const material = new THREE.MeshStandardMaterial({ color: hf.color ?? '#ffffff' });
741
+ const mesh = new THREE.Mesh(heightfieldGeometry(heights, seg.render, hf.size), material);
742
+ // Terrain receives shadows and does not cast them. A surface this large
743
+ // casting into its own shadow map spends the whole map's resolution on
744
+ // one object and self-shadows into acne; the same reasoning already
745
+ // turns shadow casting off for flat ground tiles.
746
+ mesh.castShadow = false;
747
+ mesh.receiveShadow = true;
748
+ applyMaterialLibrary(material, hf.material, {
749
+ x: hf.size.x, y: hf.size.y, z: hf.size.z,
750
+ }, 'heightfield');
751
+ // The COLLIDER grid is resampled separately — same heightmap, its own
752
+ // resolution. Collision wants the coarsest grid a player cannot feel;
753
+ // rendering wants the finest one that is affordable. Sharing one grid
754
+ // would tie them together for no reason other than convenience.
755
+ const colliderHeights = seg.collider === seg.render
756
+ ? heights
757
+ : resampleHeights(px.data, px.width, px.height, seg.collider);
758
+ heightfieldGrids.set(e.id, { heights: colliderHeights, n: seg.collider, size: hf.size });
759
+ obj = mesh;
760
+ }
512
761
  else {
513
762
  if (e.attachments?.length) {
514
763
  throw new Error(`entity '${e.id}' has attachments but no model to hang them on`);
@@ -545,7 +794,12 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
545
794
  // explicitly authored (an editor-placed Block should be standable on
546
795
  // the moment it's dropped). An explicit collider always wins; this
547
796
  // only fills the gap for a primitive entity that has none.
548
- const collider = e.collider ?? (e.primitive ? defaultColliderForPrimitive(e.primitive) : undefined);
797
+ // ADR-050 — a heightfield is terrain: standing on it is the entire
798
+ // point, so it gets a collider with nothing authored, the same way
799
+ // ADR-043 gives an editor-placed Part one.
800
+ const collider = e.collider
801
+ ?? (e.primitive ? defaultColliderForPrimitive(e.primitive) : undefined)
802
+ ?? (e.heightfield ? { shape: { kind: 'heightfield' }, body: 'fixed' } : undefined);
549
803
  if (!collider)
550
804
  continue;
551
805
  const R = opts.rapier;
@@ -557,16 +811,58 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
557
811
  desc.setTranslation(p.x + off.x, p.y + off.y, p.z + off.z);
558
812
  const q = e.transform.rotation ?? IDENTITY_QUAT;
559
813
  desc.setRotation({ x: q[0], y: q[1], z: q[2], w: q[3] });
560
- const body = world.createRigidBody(desc);
561
814
  const s = collider.shape;
562
- const shape = s.kind === 'box' ? R.ColliderDesc.cuboid(s.halfExtents.x, s.halfExtents.y, s.halfExtents.z)
563
- : s.kind === 'sphere' ? R.ColliderDesc.ball(s.radius)
564
- : s.kind === 'capsule' ? R.ColliderDesc.capsule(s.halfHeight, s.radius)
565
- : s.kind === 'cylinder' ? R.ColliderDesc.cylinder(s.halfHeight, s.radius)
566
- : s.kind === 'convexHull' ? R.ColliderDesc.convexHull(flattenPoints(s.points))
567
- : null;
568
- if (!shape)
569
- throw new Error(`entity '${e.id}': trimesh colliders are not supported yet`);
815
+ // Built BEFORE the rigid body, so a collider that cannot be built
816
+ // leaves nothing behind. `trimesh` needs the entity's actual geometry,
817
+ // which every other shape does not — its numbers are authored.
818
+ let shape = null;
819
+ if (s.kind === 'box')
820
+ shape = R.ColliderDesc.cuboid(s.halfExtents.x, s.halfExtents.y, s.halfExtents.z);
821
+ else if (s.kind === 'sphere')
822
+ shape = R.ColliderDesc.ball(s.radius);
823
+ else if (s.kind === 'capsule')
824
+ shape = R.ColliderDesc.capsule(s.halfHeight, s.radius);
825
+ else if (s.kind === 'cylinder')
826
+ shape = R.ColliderDesc.cylinder(s.halfHeight, s.radius);
827
+ else if (s.kind === 'convexHull')
828
+ shape = R.ColliderDesc.convexHull(flattenPoints(s.points));
829
+ else if (s.kind === 'heightfield') {
830
+ const grid = heightfieldGrids.get(e.id);
831
+ if (grid) {
832
+ const a = heightfieldColliderArgs(grid.heights, grid.n, grid.size);
833
+ shape = R.ColliderDesc.heightfield(a.nrows, a.ncols, a.heights, a.scale);
834
+ }
835
+ else {
836
+ console.warn(`[umicat/scene3d] entity '${e.id}' asks for a heightfield collider but has no heightfield — skipping its collider.`);
837
+ }
838
+ }
839
+ else if (s.kind === 'trimesh') {
840
+ const obj = entities.get(e.id);
841
+ const data = obj ? trimeshData(obj, new Set(entities.values())) : null;
842
+ if (data) {
843
+ const triangles = data.indices.length / 3;
844
+ if (triangles > 50000) {
845
+ console.warn(`[umicat/scene3d] entity '${e.id}' builds a ${triangles.toLocaleString()}-triangle trimesh collider. `
846
+ + 'That is fine for static scenery but it is built once per load and never simplified — '
847
+ + 'consider a low-poly collision mesh if load time suffers.');
848
+ }
849
+ shape = R.ColliderDesc.trimesh(data.vertices, data.indices);
850
+ }
851
+ else {
852
+ console.warn(`[umicat/scene3d] entity '${e.id}' asks for a trimesh collider but renders no triangles — skipping its collider.`);
853
+ }
854
+ }
855
+ // One unbuildable collider must never take the whole scene down. That
856
+ // was the old behaviour for `trimesh` (a hard throw out of
857
+ // `loadScene3D`) even though `validateScene` explicitly ALLOWS a static
858
+ // trimesh and only rejects it on a dynamic body — so authored data the
859
+ // validator blessed produced a blank screen instead of one prop with no
860
+ // physics.
861
+ if (!shape) {
862
+ console.warn(`[umicat/scene3d] entity '${e.id}': collider kind '${s.kind}' could not be built — the entity renders, but nothing collides with it.`);
863
+ continue;
864
+ }
865
+ const body = world.createRigidBody(desc);
570
866
  world.createCollider(shape, body);
571
867
  bodies.set(e.id, body);
572
868
  }
package/dist/index.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  export { ThreeUmicat } from './ThreeUmicat.js';
2
2
  export type { UmicatInitOptions } from './ThreeUmicat.js';
3
3
  export * from './scene3d.js';
4
- export { loadScene3D, loadModelAsset } from './SceneLoader3D.js';
4
+ export { loadScene3D, loadModelAsset, heightfieldGeometry } from './SceneLoader3D.js';
5
5
  export { CharacterController3D } from './CharacterController3D.js';
6
6
  export type { CharacterOptions, CharacterState, CharacterInput } from './CharacterController3D.js';
7
7
  export { CharacterAnimator } from './CharacterAnimator.js';
package/dist/index.js CHANGED
@@ -5,7 +5,7 @@
5
5
  // that turns it into a three.js scene with physics, and the runtime glue.
6
6
  export { ThreeUmicat } from './ThreeUmicat.js';
7
7
  export * from './scene3d.js';
8
- export { loadScene3D, loadModelAsset } from './SceneLoader3D.js';
8
+ export { loadScene3D, loadModelAsset, heightfieldGeometry } from './SceneLoader3D.js';
9
9
  export { CharacterController3D } from './CharacterController3D.js';
10
10
  export { CharacterAnimator } from './CharacterAnimator.js';
11
11
  export { Input3D } from './Input3D.js';
package/dist/scene3d.d.ts CHANGED
@@ -62,6 +62,13 @@ export type ColliderShape = {
62
62
  /** Static geometry only. Never use this for a dynamic body. */
63
63
  | {
64
64
  kind: 'trimesh';
65
+ }
66
+ /** ADR-050 — the entity's own `heightfield`, as a Rapier heightfield: the
67
+ * cheapest collider any physics engine offers, and the reason terrain is a
68
+ * heightfield rather than a mesh. Only valid on an entity that HAS a
69
+ * heightfield, and static only, for the same reason `trimesh` is. */
70
+ | {
71
+ kind: 'heightfield';
65
72
  };
66
73
  export interface Collider3D {
67
74
  shape: ColliderShape;
@@ -91,6 +98,58 @@ export interface Attachment3D {
91
98
  /** Optional name, so game code can find this one again to swap or drop it. */
92
99
  id?: string;
93
100
  }
101
+ /**
102
+ * ADR-050 — a terrain surface driven by a heightmap image.
103
+ *
104
+ * Deliberately NOT Roblox's shape. Roblox's `Terrain` is a singleton at a fixed
105
+ * path in the scene graph that cannot be deleted or duplicated, which makes a
106
+ * whole class of scene inexpressible. This is an ordinary entity field: a scene
107
+ * may have zero, one or many, each with its own transform, exactly like Unity's
108
+ * Terrain component. Elevation is a property of 3D space, not a privileged
109
+ * global.
110
+ *
111
+ * The data model is a HEIGHTFIELD, not voxels — the same choice Unity and
112
+ * Unreal both make. Voxels buy authoring of three-dimensionally connected
113
+ * terrain (caves, overhangs), which this platform already covers differently:
114
+ * the public library's modular cliff kit places those as ordinary entities.
115
+ * What a heightfield buys in return is O(n^2) storage, trivial LOD, and the
116
+ * cheapest collider any physics engine offers.
117
+ */
118
+ export interface Heightfield3D {
119
+ /** Manifest id of a heightmap image — see `Manifest3D.heightmaps`. The
120
+ * image's brightness is the height: black is the base plane, white is
121
+ * `size.y` above it. Referenced by id and never by path, same rule every
122
+ * other asset here follows. */
123
+ assetId: string;
124
+ /**
125
+ * World footprint. `x`/`z` are the span on the ground; `y` is the height
126
+ * full white maps to. The surface sits with its BASE at the entity's own
127
+ * origin and rises from there — so dropping one at y=0 puts its lowest
128
+ * point on the ground, matching how every modular ground tile in the
129
+ * public library is authored (base at y=0, not centred).
130
+ */
131
+ size: Vec3;
132
+ /**
133
+ * Render grid resolution — the surface is built from `segments+1` squared
134
+ * vertices. Default 128 (16,641 vertices), a reasonable terrain-sized mesh.
135
+ * The heightmap's own pixel resolution is resampled to it rather than used
136
+ * directly: a 512px image taken literally would be a quarter-million
137
+ * vertices for a surface nobody looks at that closely.
138
+ */
139
+ segments?: number;
140
+ /**
141
+ * Physics grid resolution, defaulting to `segments`. Separate on purpose —
142
+ * every reference engine separates collision resolution from render
143
+ * resolution, because collision wants the coarsest grid a player cannot
144
+ * feel and rendering wants the finest one that is affordable.
145
+ */
146
+ colliderSegments?: number;
147
+ /** A name from the built-in material library (ADR-044), the same table
148
+ * Parts resolve against. `grass` and `rock` are the terrain-shaped ones. */
149
+ material?: string;
150
+ /** Flat colour, multiplied with the material the way a Part's is. */
151
+ color?: string;
152
+ }
94
153
  export interface Entity3D {
95
154
  /** Stable, authored, unique within the scene. */
96
155
  id: string;
@@ -149,6 +208,9 @@ export interface Entity3D {
149
208
  normals?: number[];
150
209
  };
151
210
  };
211
+ /** ADR-050 — a heightmap-driven terrain surface. Mutually exclusive with
212
+ * `primitive` and `modelAssetId`: an entity is one kind of thing. */
213
+ heightfield?: Heightfield3D;
152
214
  collider?: Collider3D;
153
215
  /**
154
216
  * ADR-047 — marks this Part for SUBTRACTION the next time it (or a
@@ -387,6 +449,14 @@ export interface Manifest3D {
387
449
  file: string;
388
450
  }[];
389
451
  models?: ModelAsset3D[];
452
+ /** ADR-050 — heightmap images, resolved by id from `Heightfield3D.assetId`.
453
+ * A separate registry from `models` because it is a different kind of
454
+ * thing entirely (an image, with no animations/skins/sockets), and reusing
455
+ * `models` would mean a model entry that is not a model. */
456
+ heightmaps?: {
457
+ id: string;
458
+ path: string;
459
+ }[];
390
460
  /** Registry of HUD resources — see `hud3d/types.ts`'s `Hud3DRef`. Named
391
461
  * `huds3d`, not `huds`, so it reads unambiguously next to the
392
462
  * already-dead `scenes` field above. */
@@ -396,6 +466,51 @@ export interface Manifest3D {
396
466
  file: string;
397
467
  }[];
398
468
  }
469
+ /**
470
+ * ADR-050 — resample a heightmap's pixels into the `(n+1) x (n+1)` grid a
471
+ * surface is built from, bilinearly.
472
+ *
473
+ * `src` is row-major, normalised 0..1, `srcW x srcH`. The result is row-major
474
+ * too, indexed `[iz * (n + 1) + ix]` — **row = z, column = x**, which is also
475
+ * how an image reads (its rows run along the ground away from the camera).
476
+ * Every consumer below shares that one convention; the Rapier hand-off is the
477
+ * only place it changes, and it changes there loudly.
478
+ *
479
+ * Bilinear rather than nearest because an 8-bit heightmap only has 256 levels
480
+ * to begin with: point-sampling a 64px image onto a 128-segment grid would
481
+ * turn a smooth slope into visible stairs twice over, once from the bit depth
482
+ * and once from the resampling.
483
+ */
484
+ export declare function resampleHeights(src: Float32Array, srcW: number, srcH: number, n: number): Float32Array;
485
+ /**
486
+ * ADR-050 — the arguments `Rapier.ColliderDesc.heightfield` wants, from the
487
+ * row-major grid everything else here uses.
488
+ *
489
+ * **This function exists because of one trap.** Rapier takes its heights as a
490
+ * `nrows x ncols` matrix in COLUMN-MAJOR order, with rows running along local
491
+ * x and columns along local z. Our grid is row-major with rows running along
492
+ * z. Handing ours over directly produces a terrain that is silently
493
+ * TRANSPOSED — still plausible-looking hills, in the wrong places, and only on
494
+ * the collision side, so the player walks into slopes that are not drawn and
495
+ * through ones that are. Keeping the swap in one named function with one test
496
+ * is the whole defence.
497
+ *
498
+ * `scale` carries the world size: Rapier multiplies the raw 0..1 heights by
499
+ * `scale.y`, and spans `scale.x` by `scale.z` CENTRED on the collider origin.
500
+ */
501
+ export declare function heightfieldColliderArgs(heights: Float32Array, n: number, size: Vec3): {
502
+ nrows: number;
503
+ ncols: number;
504
+ heights: Float32Array;
505
+ scale: Vec3;
506
+ };
507
+ /**
508
+ * ADR-050 — world-space height of the surface at a point, for a grid in the
509
+ * convention above. `x`/`z` are relative to the entity's origin. Returns null
510
+ * outside the footprint rather than clamping, so a caller can tell "off the
511
+ * edge" from "at ground level" — they are different answers.
512
+ */
513
+ export declare function sampleHeightfield(heights: Float32Array, n: number, size: Vec3, x: number, z: number): number | null;
399
514
  /** Identity quaternion, spelled out so callers don't have to remember the order. */
400
515
  export declare const IDENTITY_QUAT: Quat;
401
516
  export declare function vec3(x?: number, y?: number, z?: number): Vec3;
package/dist/scene3d.js CHANGED
@@ -161,6 +161,95 @@ export function cubeFacesFromNames(paths) {
161
161
  throw new Error(`cube map is missing ${missing.length} face(s): ${missing.join(', ')}`);
162
162
  return order.map((f) => found[f]);
163
163
  }
164
+ /**
165
+ * ADR-050 — resample a heightmap's pixels into the `(n+1) x (n+1)` grid a
166
+ * surface is built from, bilinearly.
167
+ *
168
+ * `src` is row-major, normalised 0..1, `srcW x srcH`. The result is row-major
169
+ * too, indexed `[iz * (n + 1) + ix]` — **row = z, column = x**, which is also
170
+ * how an image reads (its rows run along the ground away from the camera).
171
+ * Every consumer below shares that one convention; the Rapier hand-off is the
172
+ * only place it changes, and it changes there loudly.
173
+ *
174
+ * Bilinear rather than nearest because an 8-bit heightmap only has 256 levels
175
+ * to begin with: point-sampling a 64px image onto a 128-segment grid would
176
+ * turn a smooth slope into visible stairs twice over, once from the bit depth
177
+ * and once from the resampling.
178
+ */
179
+ export function resampleHeights(src, srcW, srcH, n) {
180
+ const out = new Float32Array((n + 1) * (n + 1));
181
+ const at = (x, z) => src[Math.min(srcH - 1, z) * srcW + Math.min(srcW - 1, x)];
182
+ for (let iz = 0; iz <= n; iz++) {
183
+ const fz = (iz / n) * (srcH - 1);
184
+ const z0 = Math.floor(fz), tz = fz - z0;
185
+ for (let ix = 0; ix <= n; ix++) {
186
+ const fx = (ix / n) * (srcW - 1);
187
+ const x0 = Math.floor(fx), tx = fx - x0;
188
+ const a = at(x0, z0), b = at(x0 + 1, z0), c = at(x0, z0 + 1), d = at(x0 + 1, z0 + 1);
189
+ out[iz * (n + 1) + ix] = (a * (1 - tx) + b * tx) * (1 - tz) + (c * (1 - tx) + d * tx) * tz;
190
+ }
191
+ }
192
+ return out;
193
+ }
194
+ /**
195
+ * ADR-050 — the arguments `Rapier.ColliderDesc.heightfield` wants, from the
196
+ * row-major grid everything else here uses.
197
+ *
198
+ * **This function exists because of one trap.** Rapier takes its heights as a
199
+ * `nrows x ncols` matrix in COLUMN-MAJOR order, with rows running along local
200
+ * x and columns along local z. Our grid is row-major with rows running along
201
+ * z. Handing ours over directly produces a terrain that is silently
202
+ * TRANSPOSED — still plausible-looking hills, in the wrong places, and only on
203
+ * the collision side, so the player walks into slopes that are not drawn and
204
+ * through ones that are. Keeping the swap in one named function with one test
205
+ * is the whole defence.
206
+ *
207
+ * `scale` carries the world size: Rapier multiplies the raw 0..1 heights by
208
+ * `scale.y`, and spans `scale.x` by `scale.z` CENTRED on the collider origin.
209
+ */
210
+ export function heightfieldColliderArgs(heights, n, size) {
211
+ const side = n + 1;
212
+ const columnMajor = new Float32Array(side * side);
213
+ for (let iz = 0; iz < side; iz++) {
214
+ for (let ix = 0; ix < side; ix++) {
215
+ // ours `[iz * side + ix]` (row = z) → Rapier's `[r + c * side]` where r
216
+ // indexes world Z and c indexes world X. So r = iz, c = ix.
217
+ //
218
+ // MEASURED, not derived. The obvious reading of "column-major, rows
219
+ // along x" produces `[ix + iz * side]`, which is byte-for-byte the SAME
220
+ // expression as ours — an identity mapping dressed up as a transpose —
221
+ // and a ray probe showed the terrain coming out rotated a quarter turn:
222
+ // collision slopes where nothing is drawn, flat ground where a hill is.
223
+ columnMajor[iz + ix * side] = heights[iz * side + ix];
224
+ }
225
+ }
226
+ // `nrows`/`ncols` are CELL counts, not sample counts — the binding builds a
227
+ // `(nrows + 1) x (ncols + 1)` matrix from the array. Passing sample counts
228
+ // makes Rapier panic inside wasm with an unreachable, which surfaces as a
229
+ // stack trace through four layers of minified glue and says nothing about
230
+ // the actual mistake. Found exactly that way.
231
+ return { nrows: n, ncols: n, heights: columnMajor, scale: { x: size.x, y: size.y, z: size.z } };
232
+ }
233
+ /**
234
+ * ADR-050 — world-space height of the surface at a point, for a grid in the
235
+ * convention above. `x`/`z` are relative to the entity's origin. Returns null
236
+ * outside the footprint rather than clamping, so a caller can tell "off the
237
+ * edge" from "at ground level" — they are different answers.
238
+ */
239
+ export function sampleHeightfield(heights, n, size, x, z) {
240
+ const u = x / size.x + 0.5;
241
+ const v = z / size.z + 0.5;
242
+ if (u < 0 || u > 1 || v < 0 || v > 1)
243
+ return null;
244
+ const side = n + 1;
245
+ const fx = u * n, fz = v * n;
246
+ const x0 = Math.min(n - 1, Math.floor(fx)), z0 = Math.min(n - 1, Math.floor(fz));
247
+ const tx = fx - x0, tz = fz - z0;
248
+ const h = (ix, iz) => heights[iz * side + ix];
249
+ const top = h(x0, z0) * (1 - tx) + h(x0 + 1, z0) * tx;
250
+ const bottom = h(x0, z0 + 1) * (1 - tx) + h(x0 + 1, z0 + 1) * tx;
251
+ return (top * (1 - tz) + bottom * tz) * size.y;
252
+ }
164
253
  /** Identity quaternion, spelled out so callers don't have to remember the order. */
165
254
  export const IDENTITY_QUAT = [0, 0, 0, 1];
166
255
  export function vec3(x = 0, y = 0, z = 0) { return { x, y, z }; }
@@ -189,12 +278,40 @@ export function validateScene(scene) {
189
278
  else if (ids.has(e.id))
190
279
  problems.push(`duplicate entity id '${e.id}'`);
191
280
  ids.add(e.id);
192
- if (!e.modelAssetId && !e.primitive) {
193
- problems.push(`entity '${e.id}' has neither a model nor a primitive — it would render nothing`);
281
+ if (!e.modelAssetId && !e.primitive && !e.heightfield) {
282
+ problems.push(`entity '${e.id}' has neither a model, a primitive nor a heightfield — it would render nothing`);
283
+ }
284
+ if (e.heightfield && (e.primitive || e.modelAssetId)) {
285
+ problems.push(`entity '${e.id}' is both a heightfield and a primitive/model — it can only be one`);
286
+ }
287
+ if (e.heightfield) {
288
+ const h = e.heightfield;
289
+ if (!h.assetId)
290
+ problems.push(`entity '${e.id}' has a heightfield with no assetId`);
291
+ if (!h.size || !(h.size.x > 0) || !(h.size.z > 0)) {
292
+ problems.push(`entity '${e.id}' has a heightfield with no positive x/z size — it would cover no ground`);
293
+ }
294
+ for (const field of ['segments', 'colliderSegments']) {
295
+ const n = h[field];
296
+ // The upper bound is not a style preference: 512 segments is 263k
297
+ // vertices for ONE entity, and the failure mode is a silently
298
+ // unplayable frame rate rather than an error anyone would see.
299
+ if (n !== undefined && (!Number.isInteger(n) || n < 1 || n > 512)) {
300
+ problems.push(`entity '${e.id}' heightfield ${field} must be a whole number between 1 and 512`);
301
+ }
302
+ }
194
303
  }
195
304
  if (e.collider?.body === 'dynamic' && e.collider.shape.kind === 'trimesh') {
196
305
  problems.push(`entity '${e.id}' uses a trimesh collider on a dynamic body; use a convex shape`);
197
306
  }
307
+ if (e.collider?.shape.kind === 'heightfield') {
308
+ if (!e.heightfield) {
309
+ problems.push(`entity '${e.id}' has a heightfield collider but no heightfield to build it from`);
310
+ }
311
+ if (e.collider.body !== 'fixed') {
312
+ problems.push(`entity '${e.id}' uses a heightfield collider on a non-fixed body; terrain does not move`);
313
+ }
314
+ }
198
315
  if (e.transform?.rotation && e.transform.rotation.length !== 4) {
199
316
  problems.push(`entity '${e.id}' rotation must be a quaternion [x,y,z,w]`);
200
317
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@umicat/three-sdk",
3
- "version": "1.17.1",
3
+ "version": "1.19.0",
4
4
  "description": "Three.js runtime for Umicat games: the scene3d design format, its loader with physics, a kinematic character controller, and the Umicat platform via @umicat/platform-sdk.",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",