@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.
- package/dist/SceneLoader3D.d.ts +35 -1
- package/dist/SceneLoader3D.js +228 -28
- package/dist/editor/EditorDesignPlayer3D.js +112 -47
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/scene3d.d.ts +115 -0
- package/dist/scene3d.js +119 -2
- package/package.json +1 -1
package/dist/SceneLoader3D.d.ts
CHANGED
|
@@ -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.
|
package/dist/SceneLoader3D.js
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
1739
|
-
|
|
1740
|
-
|
|
1741
|
-
|
|
1742
|
-
|
|
1743
|
-
|
|
1744
|
-
|
|
1745
|
-
|
|
1746
|
-
|
|
1747
|
-
|
|
1748
|
-
|
|
1749
|
-
|
|
1750
|
-
|
|
1751
|
-
|
|
1752
|
-
|
|
1753
|
-
|
|
1754
|
-
|
|
1755
|
-
|
|
1756
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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.
|
|
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",
|