@umicat/three-sdk 1.18.0 → 1.20.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, type Heightfield3D } 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,40 @@ 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;
73
+ /**
74
+ * ADR-050 — build one heightfield's surface and its collider grid.
75
+ *
76
+ * Exported because THREE callers need it and must not each reimplement it:
77
+ * `loadScene3D` below, the editor's live create, and the editor's live patch
78
+ * (a resize or a resolution change rebuilds the whole surface — there is no
79
+ * incremental edit of a heightmap-derived mesh). A second implementation is
80
+ * how the drawn surface and the walked surface drift apart, which is the one
81
+ * failure terrain cannot afford.
82
+ *
83
+ * The decoded pixels are cached per url, so calling this repeatedly for the
84
+ * same heightmap costs one fetch.
85
+ */
86
+ export declare function makeHeightfield(hf: Heightfield3D, manifest: Manifest3D, opts?: {
87
+ assetBase?: string;
88
+ }): Promise<{
89
+ mesh: THREE.Mesh;
90
+ grid: {
91
+ heights: Float32Array;
92
+ n: number;
93
+ size: Vec3;
94
+ };
95
+ }>;
62
96
  export declare function makePrimitive(e: Entity3D): THREE.Mesh;
63
97
  /**
64
98
  * Turn scene3d design data into a running three.js scene.
@@ -1,7 +1,7 @@
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) {
@@ -265,6 +265,129 @@ function materialRepeatFor(kind, size, tileUnit) {
265
265
  }
266
266
  return new THREE.Vector2(u(size.x), u(size.z));
267
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
+ /**
347
+ * ADR-050 — build one heightfield's surface and its collider grid.
348
+ *
349
+ * Exported because THREE callers need it and must not each reimplement it:
350
+ * `loadScene3D` below, the editor's live create, and the editor's live patch
351
+ * (a resize or a resolution change rebuilds the whole surface — there is no
352
+ * incremental edit of a heightmap-derived mesh). A second implementation is
353
+ * how the drawn surface and the walked surface drift apart, which is the one
354
+ * failure terrain cannot afford.
355
+ *
356
+ * The decoded pixels are cached per url, so calling this repeatedly for the
357
+ * same heightmap costs one fetch.
358
+ */
359
+ export async function makeHeightfield(hf, manifest, opts = {}) {
360
+ const entry = (manifest.heightmaps ?? []).find((h) => h.id === hf.assetId);
361
+ if (!entry) {
362
+ const have = (manifest.heightmaps ?? []).map((h) => h.id).join(', ');
363
+ throw new Error(`[umicat] manifest has no heightmap '${hf.assetId}'. It has: ${have || '(none)'}`);
364
+ }
365
+ const px = await heightmapPixels((opts.assetBase ?? '') + entry.path);
366
+ const seg = heightfieldSegments(hf);
367
+ const heights = resampleHeights(px.data, px.width, px.height, seg.render);
368
+ const material = new THREE.MeshStandardMaterial({ color: hf.color ?? '#ffffff' });
369
+ const mesh = new THREE.Mesh(heightfieldGeometry(heights, seg.render, hf.size), material);
370
+ // Terrain receives shadows and does not cast them. A surface this large
371
+ // casting into its own shadow map spends the map's whole resolution on one
372
+ // object and self-shadows into acne — the same reasoning that already turns
373
+ // shadow casting off for flat ground tiles.
374
+ mesh.castShadow = false;
375
+ mesh.receiveShadow = true;
376
+ applyMaterialLibrary(material, hf.material, hf.size, 'heightfield');
377
+ // The COLLIDER grid is resampled separately from the same heightmap.
378
+ // Collision wants the coarsest grid a player cannot feel; rendering wants
379
+ // the finest one that is affordable. Sharing one grid would tie them
380
+ // together for no reason beyond convenience.
381
+ const colliderHeights = seg.collider === seg.render
382
+ ? heights
383
+ : resampleHeights(px.data, px.width, px.height, seg.collider);
384
+ return { mesh, grid: { heights: colliderHeights, n: seg.collider, size: hf.size } };
385
+ }
386
+ /** Resolution actually used, with the documented defaults applied. */
387
+ function heightfieldSegments(h) {
388
+ const render = h.segments ?? 128;
389
+ return { render, collider: h.colliderSegments ?? render };
390
+ }
268
391
  /**
269
392
  * ADR-047 — rebuilds a `THREE.BufferGeometry` from a baked CSG result's
270
393
  * flat position/index arrays (`Entity3D.primitive.mesh`). `normals` is
@@ -322,34 +445,63 @@ export function makePrimitive(e) {
322
445
  // CDN-texture consumer in this SDK). A missing/renamed material name, or
323
446
  // a failed fetch, silently keeps the flat color rather than erroring —
324
447
  // this is cosmetic, not a thing worth surfacing as a broken scene.
325
- const libEntry = p.material ? MATERIAL_LIBRARY[p.material] : undefined;
326
- if (libEntry) {
327
- const repeat = materialRepeatFor(p.kind, s, MATERIAL_TILE_UNIT[p.material] ?? 1);
328
- void Promise.all([
329
- loadMaterialTexture(libEntry.color, THREE.SRGBColorSpace),
330
- loadMaterialTexture(libEntry.roughness, THREE.NoColorSpace),
331
- ]).then(([colorTex, roughTex]) => {
332
- // Cloned, not assigned directly — the cache shares ONE texture per
333
- // url across every Part using this material, and `.repeat` is
334
- // per-INSTANCE (a 1×1 block and a 10×10 platform using the same
335
- // "brick" material need different repeat counts). Assigning the
336
- // cached texture directly would make every Part sharing a material
337
- // fight over the last-set repeat value — the exact "clones share
338
- // materials" trap `Skin.ts` already documents, one level up (here
339
- // it's the TEXTURE being shared, not the material).
340
- const map = colorTex.clone();
341
- const roughnessMap = roughTex.clone();
342
- map.repeat.copy(repeat);
343
- roughnessMap.repeat.copy(repeat);
344
- map.needsUpdate = true;
345
- roughnessMap.needsUpdate = true;
346
- material.map = map;
347
- material.roughnessMap = roughnessMap;
348
- material.needsUpdate = true;
349
- }).catch(() => { });
350
- }
448
+ applyMaterialLibrary(material, p.material, s, p.kind);
351
449
  return mesh;
352
450
  }
451
+ /**
452
+ * ADR-044 — paint a library material onto an already-built material, async.
453
+ *
454
+ * Shared by Parts and (ADR-050) heightfields, which is the reuse boundary
455
+ * ADR-044 names: the library, the cache and this loading dance carry over
456
+ * between geometry kinds, while the FIELD does not — `material` lives on
457
+ * `primitive` and on `heightfield` separately, because an entity-level one
458
+ * would be meaningless on a model (models bring their own materials, and
459
+ * `skin` already covers retexturing them).
460
+ *
461
+ * Flat colour renders immediately; textures arrive and patch the material in
462
+ * place. A missing/renamed name or a failed fetch silently keeps the flat
463
+ * colour — this is cosmetic, not a thing worth surfacing as a broken scene.
464
+ */
465
+ function applyMaterialLibrary(material, name, size, kind) {
466
+ const libEntry = name ? MATERIAL_LIBRARY[name] : undefined;
467
+ if (!libEntry)
468
+ return;
469
+ const repeat = materialRepeatFor(kind, size, MATERIAL_TILE_UNIT[name] ?? 1);
470
+ void Promise.all([
471
+ loadMaterialTexture(libEntry.color, THREE.SRGBColorSpace),
472
+ loadMaterialTexture(libEntry.roughness, THREE.NoColorSpace),
473
+ ]).then(([colorTex, roughTex]) => {
474
+ // Cloned, not assigned directly — the cache shares ONE texture per url
475
+ // across every surface using this material, and `.repeat` is
476
+ // per-INSTANCE (a 1×1 block and a 200×200 terrain using the same
477
+ // "grass" need wildly different repeat counts). Assigning the cached
478
+ // texture directly would make every user of a material fight over the
479
+ // last-set repeat value — the "clones share materials" trap `Skin.ts`
480
+ // documents, one level up: here it is the TEXTURE being shared.
481
+ const map = colorTex.clone();
482
+ const roughnessMap = roughTex.clone();
483
+ map.repeat.copy(repeat);
484
+ roughnessMap.repeat.copy(repeat);
485
+ // Anisotropic filtering, which three.js leaves at 1 by default. Without
486
+ // it a surface with a high repeat count seen at a grazing angle — which
487
+ // is EVERY large surface: a terrain, a long platform, a floor — minifies
488
+ // to a flat average colour. Measured: a 60x60-unit heightfield with the
489
+ // `grass` material rendered as a single uniform green until this line
490
+ // existed, while reporting a perfectly healthy 512x512 texture with a
491
+ // repeat of 60. The symptom looks exactly like "the texture failed to
492
+ // load", which is the wrong thing to go and debug.
493
+ //
494
+ // 16 is a request, not an assumption: three clamps it to the device's
495
+ // own maximum at upload, so this needs no renderer handle to be correct.
496
+ map.anisotropy = 16;
497
+ roughnessMap.anisotropy = 16;
498
+ map.needsUpdate = true;
499
+ roughnessMap.needsUpdate = true;
500
+ material.map = map;
501
+ material.roughnessMap = roughnessMap;
502
+ material.needsUpdate = true;
503
+ }).catch(() => { });
504
+ }
353
505
  /**
354
506
  * Turn scene3d design data into a running three.js scene.
355
507
  *
@@ -487,6 +639,28 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
487
639
  needed.add(a.modelAssetId);
488
640
  }
489
641
  }
642
+ // ADR-050 — heightmaps are fetched and decoded up front, same contract the
643
+ // models above follow: a caller that awaits `loadScene3D` gets a finished
644
+ // scene, not one whose terrain pops in flat and then rises a frame later.
645
+ const heightmaps = new Map((manifest.heightmaps ?? []).map((h) => [h.id, h]));
646
+ const heightmapPixelsById = new Map();
647
+ const heightmapJobs = [];
648
+ for (const e of scene3d.entities) {
649
+ if (!e.heightfield)
650
+ continue;
651
+ const entry = heightmaps.get(e.heightfield.assetId);
652
+ if (!entry) {
653
+ throw new Error(`entity '${e.id}' uses heightmap '${e.heightfield.assetId}', which the manifest does not define. ` +
654
+ `It has: ${[...heightmaps.keys()].join(', ') || '(none)'}`);
655
+ }
656
+ if (heightmapPixelsById.has(entry.id))
657
+ continue;
658
+ heightmapPixelsById.set(entry.id, { data: new Float32Array(1), width: 1, height: 1 });
659
+ heightmapJobs.push(heightmapPixels((opts.assetBase ?? '') + entry.path)
660
+ .then((px) => { heightmapPixelsById.set(entry.id, px); }));
661
+ }
662
+ if (heightmapJobs.length)
663
+ await Promise.all(heightmapJobs);
490
664
  const loaded = new Map();
491
665
  if (needed.size) {
492
666
  const loader = new GLTFLoader();
@@ -499,6 +673,9 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
499
673
  }));
500
674
  }
501
675
  const entities = new Map();
676
+ /** ADR-050 — each heightfield's COLLIDER grid, kept for the physics pass
677
+ * below (which runs after every entity exists). */
678
+ const heightfieldGrids = new Map();
502
679
  const mixers = [];
503
680
  const mixerFor = new Map();
504
681
  const clips = new Map();
@@ -592,6 +769,14 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
592
769
  .then((worn) => { attachments.set(e.id, worn); }));
593
770
  }
594
771
  }
772
+ else if (e.heightfield) {
773
+ if (e.attachments?.length) {
774
+ throw new Error(`entity '${e.id}' has attachments but no model to hang them on`);
775
+ }
776
+ const built = await makeHeightfield(e.heightfield, manifest, { assetBase: opts.assetBase });
777
+ heightfieldGrids.set(e.id, built.grid);
778
+ obj = built.mesh;
779
+ }
595
780
  else {
596
781
  if (e.attachments?.length) {
597
782
  throw new Error(`entity '${e.id}' has attachments but no model to hang them on`);
@@ -628,7 +813,12 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
628
813
  // explicitly authored (an editor-placed Block should be standable on
629
814
  // the moment it's dropped). An explicit collider always wins; this
630
815
  // only fills the gap for a primitive entity that has none.
631
- const collider = e.collider ?? (e.primitive ? defaultColliderForPrimitive(e.primitive) : undefined);
816
+ // ADR-050 — a heightfield is terrain: standing on it is the entire
817
+ // point, so it gets a collider with nothing authored, the same way
818
+ // ADR-043 gives an editor-placed Part one.
819
+ const collider = e.collider
820
+ ?? (e.primitive ? defaultColliderForPrimitive(e.primitive) : undefined)
821
+ ?? (e.heightfield ? { shape: { kind: 'heightfield' }, body: 'fixed' } : undefined);
632
822
  if (!collider)
633
823
  continue;
634
824
  const R = opts.rapier;
@@ -655,6 +845,16 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
655
845
  shape = R.ColliderDesc.cylinder(s.halfHeight, s.radius);
656
846
  else if (s.kind === 'convexHull')
657
847
  shape = R.ColliderDesc.convexHull(flattenPoints(s.points));
848
+ else if (s.kind === 'heightfield') {
849
+ const grid = heightfieldGrids.get(e.id);
850
+ if (grid) {
851
+ const a = heightfieldColliderArgs(grid.heights, grid.n, grid.size);
852
+ shape = R.ColliderDesc.heightfield(a.nrows, a.ncols, a.heights, a.scale);
853
+ }
854
+ else {
855
+ console.warn(`[umicat/scene3d] entity '${e.id}' asks for a heightfield collider but has no heightfield — skipping its collider.`);
856
+ }
857
+ }
658
858
  else if (s.kind === 'trimesh') {
659
859
  const obj = entities.get(e.id);
660
860
  const data = obj ? trimeshData(obj, new Set(entities.values())) : null;
@@ -1,6 +1,6 @@
1
1
  import * as THREE from 'three';
2
2
  import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
3
- import { loadScene3D, loadModelAsset, makePrimitive, applyTransform } from '../SceneLoader3D.js';
3
+ import { loadScene3D, loadModelAsset, makePrimitive, makeHeightfield, applyTransform } from '../SceneLoader3D.js';
4
4
  import { applySkin } from '../Skin.js';
5
5
  import { applyAttachments } from '../Attachments.js';
6
6
  import { singleModelManifest, defaultColliderForPrimitive, groundRestOffset } from '../scene3d.js';
@@ -531,6 +531,24 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
531
531
  // grid frames 100 units around a 20-unit scene, which reads as "the
532
532
  // editor opens zoomed out" rather than as a bug, and no assertion about
533
533
  // snapping itself would ever catch it.
534
+ // ADR-050 — test-only readback of a heightfield's live state. `gizmoAttached`
535
+ // is here because the thing most likely to break on a rebuild is not the
536
+ // geometry (visibly wrong) but the instance SWAP: a gizmo still pointing at
537
+ // the disposed mesh renders its handles and moves nothing.
538
+ globalThis.__umicatEntityMesh =
539
+ (entityId) => {
540
+ const o = objectByEntity.get(entityId);
541
+ if (!o)
542
+ return null;
543
+ const mesh = o;
544
+ const pos = mesh.geometry?.getAttribute?.('position');
545
+ const mat = mesh.material;
546
+ return {
547
+ vertexCount: pos ? pos.count : 0,
548
+ hasMaterialMap: !!(mat && !Array.isArray(mat) && mat.map),
549
+ gizmoAttached: gizmo.attached === o,
550
+ };
551
+ };
534
552
  globalThis.__umicatSnapState =
535
553
  () => ({
536
554
  enabled: snapEnabled,
@@ -1735,54 +1753,34 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1735
1753
  fresh.scale.copy(object.scale);
1736
1754
  fresh.castShadow = merged.kind !== 'plane';
1737
1755
  fresh.receiveShadow = true;
1738
- if (object instanceof THREE.Mesh) {
1739
- object.geometry.dispose();
1740
- (Array.isArray(object.material) ? object.material : [object.material]).forEach((mat) => {
1741
- // ADR-044 — `map`/`roughnessMap` on a Parts material are PER-
1742
- // INSTANCE clones (`makePrimitive`'s own doc comment), never the
1743
- // shared cached texture — `Material.dispose()` does not reach
1744
- // into its own maps, so leaving this out would leak one texture
1745
- // per rebuild (every resize/recolor of a materialed Part).
1746
- const std = mat;
1747
- std.map?.dispose();
1748
- std.roughnessMap?.dispose();
1749
- mat.dispose();
1750
- });
1751
- }
1752
- scene?.remove(object);
1753
- scene?.add(fresh);
1754
- entityByObject.delete(object);
1755
- entityByObject.set(fresh, m.entityId);
1756
- objectByEntity.set(m.entityId, fresh);
1757
- // Same object-instance swap the position/rotation/scale branch
1758
- // above already handles for the single-select visuals — `object`
1759
- // itself is being replaced, so anything keyed by the OLD instance
1760
- // (gizmo attachment, AND now `multiSelected`/`multiBoxes` — ADR-046)
1761
- // has to move to `fresh` or it silently points at a disposed object.
1762
- if (gizmo.attached === object) {
1763
- gizmo.detach();
1764
- gizmo.attach(fresh, camera);
1765
- selectionBox.setFromObject(fresh);
1766
- }
1767
- if (multiSelected.has(object)) {
1768
- multiSelected.delete(object);
1769
- multiSelected.add(fresh);
1770
- const box = multiBoxes.get(object);
1771
- if (box) {
1772
- multiBoxes.delete(object);
1773
- multiBoxes.set(fresh, box);
1774
- box.setFromObject(fresh);
1775
- }
1756
+ disposeMeshInPlace(object);
1757
+ object = swapEntityObject(object, fresh, m.entityId);
1758
+ }
1759
+ if (m.patch?.heightfield !== undefined) {
1760
+ // ADR-050 — a heightfield has no incremental edit: every patchable
1761
+ // field (size, either resolution, material, colour) changes the vertex
1762
+ // buffer or the material wholesale, so the surface is rebuilt through
1763
+ // the SAME `makeHeightfield` the scene load and the live create both
1764
+ // use. A second build path here is exactly how the drawn surface and
1765
+ // the walked surface drift apart, which is the one thing terrain cannot
1766
+ // afford to get wrong.
1767
+ const authored = sceneData?.entities.find((e) => e.id === m.entityId);
1768
+ if (!authored?.heightfield)
1769
+ return done(`entity '${m.entityId}' is not a heightfield`);
1770
+ const merged = { ...authored.heightfield, ...m.patch.heightfield };
1771
+ authored.heightfield = merged;
1772
+ let fresh;
1773
+ try {
1774
+ fresh = (await makeHeightfield(merged, manifest, { assetBase: '' })).mesh;
1776
1775
  }
1777
- {
1778
- const box = negatedBoxes.get(object);
1779
- if (box) {
1780
- negatedBoxes.delete(object);
1781
- negatedBoxes.set(fresh, box);
1782
- box.setFromObject(fresh);
1783
- }
1776
+ catch (err) {
1777
+ return done(err instanceof Error ? err.message : String(err));
1784
1778
  }
1785
- object = fresh;
1779
+ fresh.position.copy(object.position);
1780
+ fresh.quaternion.copy(object.quaternion);
1781
+ fresh.scale.copy(object.scale);
1782
+ disposeMeshInPlace(object);
1783
+ object = swapEntityObject(object, fresh, m.entityId);
1786
1784
  }
1787
1785
  done();
1788
1786
  }
@@ -1961,6 +1959,14 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1961
1959
  object.castShadow = e.primitive.kind !== 'plane';
1962
1960
  object.receiveShadow = true;
1963
1961
  }
1962
+ else if (e.heightfield) {
1963
+ try {
1964
+ object = (await makeHeightfield(e.heightfield, manifest, { assetBase: '' })).mesh;
1965
+ }
1966
+ catch (err) {
1967
+ return err instanceof Error ? err.message : String(err);
1968
+ }
1969
+ }
1964
1970
  else {
1965
1971
  // Neither model nor primitive — an empty transform/pivot node.
1966
1972
  // ADR-045 Phase 2's "Group as Model" container is exactly this.
@@ -1989,6 +1995,65 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1989
1995
  setNegatedVisual(object, true);
1990
1996
  return undefined;
1991
1997
  }
1998
+ /**
1999
+ * Free a rebuilt mesh's own GPU resources.
2000
+ *
2001
+ * `map`/`roughnessMap` on a library material are PER-INSTANCE clones (see
2002
+ * `applyMaterialLibrary`), never the shared cached texture, and
2003
+ * `Material.dispose()` does not reach into its own maps — so leaving these
2004
+ * out leaks one texture per rebuild, i.e. per resize or recolour.
2005
+ */
2006
+ function disposeMeshInPlace(object) {
2007
+ if (!(object instanceof THREE.Mesh))
2008
+ return;
2009
+ object.geometry.dispose();
2010
+ (Array.isArray(object.material) ? object.material : [object.material]).forEach((mat) => {
2011
+ const std = mat;
2012
+ std.map?.dispose();
2013
+ std.roughnessMap?.dispose();
2014
+ mat.dispose();
2015
+ });
2016
+ }
2017
+ /**
2018
+ * Put `fresh` in `old`'s place everywhere the editor keys things by object
2019
+ * INSTANCE — the scene graph, both id maps, the gizmo attachment, the
2020
+ * multi-select set and its boxes (ADR-046), and the negated-Part box
2021
+ * (ADR-047). A rebuild that misses one of these leaves that map pointing at
2022
+ * a disposed object: no error, just a gizmo that moves nothing or a
2023
+ * selection box frozen where the old mesh used to be.
2024
+ *
2025
+ * Shared by every rebuild-in-place path rather than written per path, which
2026
+ * is the only way the list stays complete as more get added.
2027
+ */
2028
+ function swapEntityObject(old, fresh, entityId) {
2029
+ scene?.remove(old);
2030
+ scene?.add(fresh);
2031
+ entityByObject.delete(old);
2032
+ entityByObject.set(fresh, entityId);
2033
+ objectByEntity.set(entityId, fresh);
2034
+ if (gizmo.attached === old) {
2035
+ gizmo.detach();
2036
+ gizmo.attach(fresh, camera);
2037
+ selectionBox.setFromObject(fresh);
2038
+ }
2039
+ if (multiSelected.has(old)) {
2040
+ multiSelected.delete(old);
2041
+ multiSelected.add(fresh);
2042
+ const box = multiBoxes.get(old);
2043
+ if (box) {
2044
+ multiBoxes.delete(old);
2045
+ multiBoxes.set(fresh, box);
2046
+ box.setFromObject(fresh);
2047
+ }
2048
+ }
2049
+ const negated = negatedBoxes.get(old);
2050
+ if (negated) {
2051
+ negatedBoxes.delete(old);
2052
+ negatedBoxes.set(fresh, negated);
2053
+ negated.setFromObject(fresh);
2054
+ }
2055
+ return fresh;
2056
+ }
1992
2057
  async function onCreateEntity3d(m) {
1993
2058
  const error = await createEntityLive(m.entity);
1994
2059
  if (error)
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, makeHeightfield } 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, makeHeightfield } 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.18.0",
3
+ "version": "1.20.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",