@umicat/three-sdk 1.18.0 → 1.19.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/SceneLoader3D.d.ts +12 -1
- package/dist/SceneLoader3D.js +209 -28
- 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 } from './scene3d.js';
|
|
3
3
|
import { type WornMap } from './Attachments.js';
|
|
4
4
|
export interface LoadSceneOptions {
|
|
5
5
|
/** Base url assets resolve against (the project's asset host). */
|
|
@@ -59,6 +59,17 @@ export declare const MATERIAL_LIBRARY: Record<string, {
|
|
|
59
59
|
color: string;
|
|
60
60
|
roughness: string;
|
|
61
61
|
}>;
|
|
62
|
+
/**
|
|
63
|
+
* ADR-050 — the surface mesh for a heightfield, from the row-major
|
|
64
|
+
* `[iz * (n+1) + ix]` grid `resampleHeights` produces.
|
|
65
|
+
*
|
|
66
|
+
* Centred on the entity's origin in x/z and rising from it in y — the base
|
|
67
|
+
* sits AT the origin rather than straddling it, so a terrain dropped at y=0
|
|
68
|
+
* has its lowest point on the ground. That matches how every modular ground
|
|
69
|
+
* tile in the public library is authored and is the thing a person expects
|
|
70
|
+
* when they drag one in.
|
|
71
|
+
*/
|
|
72
|
+
export declare function heightfieldGeometry(heights: Float32Array, n: number, size: Vec3): THREE.BufferGeometry;
|
|
62
73
|
export declare function makePrimitive(e: Entity3D): THREE.Mesh;
|
|
63
74
|
/**
|
|
64
75
|
* Turn scene3d design data into a running three.js scene.
|
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,89 @@ 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
|
+
/** Resolution actually used, with the documented defaults applied. */
|
|
347
|
+
function heightfieldSegments(h) {
|
|
348
|
+
const render = h.segments ?? 128;
|
|
349
|
+
return { render, collider: h.colliderSegments ?? render };
|
|
350
|
+
}
|
|
268
351
|
/**
|
|
269
352
|
* ADR-047 — rebuilds a `THREE.BufferGeometry` from a baked CSG result's
|
|
270
353
|
* flat position/index arrays (`Entity3D.primitive.mesh`). `normals` is
|
|
@@ -322,34 +405,63 @@ export function makePrimitive(e) {
|
|
|
322
405
|
// CDN-texture consumer in this SDK). A missing/renamed material name, or
|
|
323
406
|
// a failed fetch, silently keeps the flat color rather than erroring —
|
|
324
407
|
// 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
|
-
}
|
|
408
|
+
applyMaterialLibrary(material, p.material, s, p.kind);
|
|
351
409
|
return mesh;
|
|
352
410
|
}
|
|
411
|
+
/**
|
|
412
|
+
* ADR-044 — paint a library material onto an already-built material, async.
|
|
413
|
+
*
|
|
414
|
+
* Shared by Parts and (ADR-050) heightfields, which is the reuse boundary
|
|
415
|
+
* ADR-044 names: the library, the cache and this loading dance carry over
|
|
416
|
+
* between geometry kinds, while the FIELD does not — `material` lives on
|
|
417
|
+
* `primitive` and on `heightfield` separately, because an entity-level one
|
|
418
|
+
* would be meaningless on a model (models bring their own materials, and
|
|
419
|
+
* `skin` already covers retexturing them).
|
|
420
|
+
*
|
|
421
|
+
* Flat colour renders immediately; textures arrive and patch the material in
|
|
422
|
+
* place. A missing/renamed name or a failed fetch silently keeps the flat
|
|
423
|
+
* colour — this is cosmetic, not a thing worth surfacing as a broken scene.
|
|
424
|
+
*/
|
|
425
|
+
function applyMaterialLibrary(material, name, size, kind) {
|
|
426
|
+
const libEntry = name ? MATERIAL_LIBRARY[name] : undefined;
|
|
427
|
+
if (!libEntry)
|
|
428
|
+
return;
|
|
429
|
+
const repeat = materialRepeatFor(kind, size, MATERIAL_TILE_UNIT[name] ?? 1);
|
|
430
|
+
void Promise.all([
|
|
431
|
+
loadMaterialTexture(libEntry.color, THREE.SRGBColorSpace),
|
|
432
|
+
loadMaterialTexture(libEntry.roughness, THREE.NoColorSpace),
|
|
433
|
+
]).then(([colorTex, roughTex]) => {
|
|
434
|
+
// Cloned, not assigned directly — the cache shares ONE texture per url
|
|
435
|
+
// across every surface using this material, and `.repeat` is
|
|
436
|
+
// per-INSTANCE (a 1×1 block and a 200×200 terrain using the same
|
|
437
|
+
// "grass" need wildly different repeat counts). Assigning the cached
|
|
438
|
+
// texture directly would make every user of a material fight over the
|
|
439
|
+
// last-set repeat value — the "clones share materials" trap `Skin.ts`
|
|
440
|
+
// documents, one level up: here it is the TEXTURE being shared.
|
|
441
|
+
const map = colorTex.clone();
|
|
442
|
+
const roughnessMap = roughTex.clone();
|
|
443
|
+
map.repeat.copy(repeat);
|
|
444
|
+
roughnessMap.repeat.copy(repeat);
|
|
445
|
+
// Anisotropic filtering, which three.js leaves at 1 by default. Without
|
|
446
|
+
// it a surface with a high repeat count seen at a grazing angle — which
|
|
447
|
+
// is EVERY large surface: a terrain, a long platform, a floor — minifies
|
|
448
|
+
// to a flat average colour. Measured: a 60x60-unit heightfield with the
|
|
449
|
+
// `grass` material rendered as a single uniform green until this line
|
|
450
|
+
// existed, while reporting a perfectly healthy 512x512 texture with a
|
|
451
|
+
// repeat of 60. The symptom looks exactly like "the texture failed to
|
|
452
|
+
// load", which is the wrong thing to go and debug.
|
|
453
|
+
//
|
|
454
|
+
// 16 is a request, not an assumption: three clamps it to the device's
|
|
455
|
+
// own maximum at upload, so this needs no renderer handle to be correct.
|
|
456
|
+
map.anisotropy = 16;
|
|
457
|
+
roughnessMap.anisotropy = 16;
|
|
458
|
+
map.needsUpdate = true;
|
|
459
|
+
roughnessMap.needsUpdate = true;
|
|
460
|
+
material.map = map;
|
|
461
|
+
material.roughnessMap = roughnessMap;
|
|
462
|
+
material.needsUpdate = true;
|
|
463
|
+
}).catch(() => { });
|
|
464
|
+
}
|
|
353
465
|
/**
|
|
354
466
|
* Turn scene3d design data into a running three.js scene.
|
|
355
467
|
*
|
|
@@ -487,6 +599,28 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
|
|
|
487
599
|
needed.add(a.modelAssetId);
|
|
488
600
|
}
|
|
489
601
|
}
|
|
602
|
+
// ADR-050 — heightmaps are fetched and decoded up front, same contract the
|
|
603
|
+
// models above follow: a caller that awaits `loadScene3D` gets a finished
|
|
604
|
+
// scene, not one whose terrain pops in flat and then rises a frame later.
|
|
605
|
+
const heightmaps = new Map((manifest.heightmaps ?? []).map((h) => [h.id, h]));
|
|
606
|
+
const heightmapPixelsById = new Map();
|
|
607
|
+
const heightmapJobs = [];
|
|
608
|
+
for (const e of scene3d.entities) {
|
|
609
|
+
if (!e.heightfield)
|
|
610
|
+
continue;
|
|
611
|
+
const entry = heightmaps.get(e.heightfield.assetId);
|
|
612
|
+
if (!entry) {
|
|
613
|
+
throw new Error(`entity '${e.id}' uses heightmap '${e.heightfield.assetId}', which the manifest does not define. ` +
|
|
614
|
+
`It has: ${[...heightmaps.keys()].join(', ') || '(none)'}`);
|
|
615
|
+
}
|
|
616
|
+
if (heightmapPixelsById.has(entry.id))
|
|
617
|
+
continue;
|
|
618
|
+
heightmapPixelsById.set(entry.id, { data: new Float32Array(1), width: 1, height: 1 });
|
|
619
|
+
heightmapJobs.push(heightmapPixels((opts.assetBase ?? '') + entry.path)
|
|
620
|
+
.then((px) => { heightmapPixelsById.set(entry.id, px); }));
|
|
621
|
+
}
|
|
622
|
+
if (heightmapJobs.length)
|
|
623
|
+
await Promise.all(heightmapJobs);
|
|
490
624
|
const loaded = new Map();
|
|
491
625
|
if (needed.size) {
|
|
492
626
|
const loader = new GLTFLoader();
|
|
@@ -499,6 +633,9 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
|
|
|
499
633
|
}));
|
|
500
634
|
}
|
|
501
635
|
const entities = new Map();
|
|
636
|
+
/** ADR-050 — each heightfield's COLLIDER grid, kept for the physics pass
|
|
637
|
+
* below (which runs after every entity exists). */
|
|
638
|
+
const heightfieldGrids = new Map();
|
|
502
639
|
const mixers = [];
|
|
503
640
|
const mixerFor = new Map();
|
|
504
641
|
const clips = new Map();
|
|
@@ -592,6 +729,35 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
|
|
|
592
729
|
.then((worn) => { attachments.set(e.id, worn); }));
|
|
593
730
|
}
|
|
594
731
|
}
|
|
732
|
+
else if (e.heightfield) {
|
|
733
|
+
if (e.attachments?.length) {
|
|
734
|
+
throw new Error(`entity '${e.id}' has attachments but no model to hang them on`);
|
|
735
|
+
}
|
|
736
|
+
const hf = e.heightfield;
|
|
737
|
+
const px = heightmapPixelsById.get(hf.assetId);
|
|
738
|
+
const seg = heightfieldSegments(hf);
|
|
739
|
+
const heights = resampleHeights(px.data, px.width, px.height, seg.render);
|
|
740
|
+
const material = new THREE.MeshStandardMaterial({ color: hf.color ?? '#ffffff' });
|
|
741
|
+
const mesh = new THREE.Mesh(heightfieldGeometry(heights, seg.render, hf.size), material);
|
|
742
|
+
// Terrain receives shadows and does not cast them. A surface this large
|
|
743
|
+
// casting into its own shadow map spends the whole map's resolution on
|
|
744
|
+
// one object and self-shadows into acne; the same reasoning already
|
|
745
|
+
// turns shadow casting off for flat ground tiles.
|
|
746
|
+
mesh.castShadow = false;
|
|
747
|
+
mesh.receiveShadow = true;
|
|
748
|
+
applyMaterialLibrary(material, hf.material, {
|
|
749
|
+
x: hf.size.x, y: hf.size.y, z: hf.size.z,
|
|
750
|
+
}, 'heightfield');
|
|
751
|
+
// The COLLIDER grid is resampled separately — same heightmap, its own
|
|
752
|
+
// resolution. Collision wants the coarsest grid a player cannot feel;
|
|
753
|
+
// rendering wants the finest one that is affordable. Sharing one grid
|
|
754
|
+
// would tie them together for no reason other than convenience.
|
|
755
|
+
const colliderHeights = seg.collider === seg.render
|
|
756
|
+
? heights
|
|
757
|
+
: resampleHeights(px.data, px.width, px.height, seg.collider);
|
|
758
|
+
heightfieldGrids.set(e.id, { heights: colliderHeights, n: seg.collider, size: hf.size });
|
|
759
|
+
obj = mesh;
|
|
760
|
+
}
|
|
595
761
|
else {
|
|
596
762
|
if (e.attachments?.length) {
|
|
597
763
|
throw new Error(`entity '${e.id}' has attachments but no model to hang them on`);
|
|
@@ -628,7 +794,12 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
|
|
|
628
794
|
// explicitly authored (an editor-placed Block should be standable on
|
|
629
795
|
// the moment it's dropped). An explicit collider always wins; this
|
|
630
796
|
// only fills the gap for a primitive entity that has none.
|
|
631
|
-
|
|
797
|
+
// ADR-050 — a heightfield is terrain: standing on it is the entire
|
|
798
|
+
// point, so it gets a collider with nothing authored, the same way
|
|
799
|
+
// ADR-043 gives an editor-placed Part one.
|
|
800
|
+
const collider = e.collider
|
|
801
|
+
?? (e.primitive ? defaultColliderForPrimitive(e.primitive) : undefined)
|
|
802
|
+
?? (e.heightfield ? { shape: { kind: 'heightfield' }, body: 'fixed' } : undefined);
|
|
632
803
|
if (!collider)
|
|
633
804
|
continue;
|
|
634
805
|
const R = opts.rapier;
|
|
@@ -655,6 +826,16 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
|
|
|
655
826
|
shape = R.ColliderDesc.cylinder(s.halfHeight, s.radius);
|
|
656
827
|
else if (s.kind === 'convexHull')
|
|
657
828
|
shape = R.ColliderDesc.convexHull(flattenPoints(s.points));
|
|
829
|
+
else if (s.kind === 'heightfield') {
|
|
830
|
+
const grid = heightfieldGrids.get(e.id);
|
|
831
|
+
if (grid) {
|
|
832
|
+
const a = heightfieldColliderArgs(grid.heights, grid.n, grid.size);
|
|
833
|
+
shape = R.ColliderDesc.heightfield(a.nrows, a.ncols, a.heights, a.scale);
|
|
834
|
+
}
|
|
835
|
+
else {
|
|
836
|
+
console.warn(`[umicat/scene3d] entity '${e.id}' asks for a heightfield collider but has no heightfield — skipping its collider.`);
|
|
837
|
+
}
|
|
838
|
+
}
|
|
658
839
|
else if (s.kind === 'trimesh') {
|
|
659
840
|
const obj = entities.get(e.id);
|
|
660
841
|
const data = obj ? trimeshData(obj, new Set(entities.values())) : null;
|
package/dist/index.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
export { ThreeUmicat } from './ThreeUmicat.js';
|
|
2
2
|
export type { UmicatInitOptions } from './ThreeUmicat.js';
|
|
3
3
|
export * from './scene3d.js';
|
|
4
|
-
export { loadScene3D, loadModelAsset } from './SceneLoader3D.js';
|
|
4
|
+
export { loadScene3D, loadModelAsset, heightfieldGeometry } from './SceneLoader3D.js';
|
|
5
5
|
export { CharacterController3D } from './CharacterController3D.js';
|
|
6
6
|
export type { CharacterOptions, CharacterState, CharacterInput } from './CharacterController3D.js';
|
|
7
7
|
export { CharacterAnimator } from './CharacterAnimator.js';
|
package/dist/index.js
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
// that turns it into a three.js scene with physics, and the runtime glue.
|
|
6
6
|
export { ThreeUmicat } from './ThreeUmicat.js';
|
|
7
7
|
export * from './scene3d.js';
|
|
8
|
-
export { loadScene3D, loadModelAsset } from './SceneLoader3D.js';
|
|
8
|
+
export { loadScene3D, loadModelAsset, heightfieldGeometry } from './SceneLoader3D.js';
|
|
9
9
|
export { CharacterController3D } from './CharacterController3D.js';
|
|
10
10
|
export { CharacterAnimator } from './CharacterAnimator.js';
|
|
11
11
|
export { Input3D } from './Input3D.js';
|
package/dist/scene3d.d.ts
CHANGED
|
@@ -62,6 +62,13 @@ export type ColliderShape = {
|
|
|
62
62
|
/** Static geometry only. Never use this for a dynamic body. */
|
|
63
63
|
| {
|
|
64
64
|
kind: 'trimesh';
|
|
65
|
+
}
|
|
66
|
+
/** ADR-050 — the entity's own `heightfield`, as a Rapier heightfield: the
|
|
67
|
+
* cheapest collider any physics engine offers, and the reason terrain is a
|
|
68
|
+
* heightfield rather than a mesh. Only valid on an entity that HAS a
|
|
69
|
+
* heightfield, and static only, for the same reason `trimesh` is. */
|
|
70
|
+
| {
|
|
71
|
+
kind: 'heightfield';
|
|
65
72
|
};
|
|
66
73
|
export interface Collider3D {
|
|
67
74
|
shape: ColliderShape;
|
|
@@ -91,6 +98,58 @@ export interface Attachment3D {
|
|
|
91
98
|
/** Optional name, so game code can find this one again to swap or drop it. */
|
|
92
99
|
id?: string;
|
|
93
100
|
}
|
|
101
|
+
/**
|
|
102
|
+
* ADR-050 — a terrain surface driven by a heightmap image.
|
|
103
|
+
*
|
|
104
|
+
* Deliberately NOT Roblox's shape. Roblox's `Terrain` is a singleton at a fixed
|
|
105
|
+
* path in the scene graph that cannot be deleted or duplicated, which makes a
|
|
106
|
+
* whole class of scene inexpressible. This is an ordinary entity field: a scene
|
|
107
|
+
* may have zero, one or many, each with its own transform, exactly like Unity's
|
|
108
|
+
* Terrain component. Elevation is a property of 3D space, not a privileged
|
|
109
|
+
* global.
|
|
110
|
+
*
|
|
111
|
+
* The data model is a HEIGHTFIELD, not voxels — the same choice Unity and
|
|
112
|
+
* Unreal both make. Voxels buy authoring of three-dimensionally connected
|
|
113
|
+
* terrain (caves, overhangs), which this platform already covers differently:
|
|
114
|
+
* the public library's modular cliff kit places those as ordinary entities.
|
|
115
|
+
* What a heightfield buys in return is O(n^2) storage, trivial LOD, and the
|
|
116
|
+
* cheapest collider any physics engine offers.
|
|
117
|
+
*/
|
|
118
|
+
export interface Heightfield3D {
|
|
119
|
+
/** Manifest id of a heightmap image — see `Manifest3D.heightmaps`. The
|
|
120
|
+
* image's brightness is the height: black is the base plane, white is
|
|
121
|
+
* `size.y` above it. Referenced by id and never by path, same rule every
|
|
122
|
+
* other asset here follows. */
|
|
123
|
+
assetId: string;
|
|
124
|
+
/**
|
|
125
|
+
* World footprint. `x`/`z` are the span on the ground; `y` is the height
|
|
126
|
+
* full white maps to. The surface sits with its BASE at the entity's own
|
|
127
|
+
* origin and rises from there — so dropping one at y=0 puts its lowest
|
|
128
|
+
* point on the ground, matching how every modular ground tile in the
|
|
129
|
+
* public library is authored (base at y=0, not centred).
|
|
130
|
+
*/
|
|
131
|
+
size: Vec3;
|
|
132
|
+
/**
|
|
133
|
+
* Render grid resolution — the surface is built from `segments+1` squared
|
|
134
|
+
* vertices. Default 128 (16,641 vertices), a reasonable terrain-sized mesh.
|
|
135
|
+
* The heightmap's own pixel resolution is resampled to it rather than used
|
|
136
|
+
* directly: a 512px image taken literally would be a quarter-million
|
|
137
|
+
* vertices for a surface nobody looks at that closely.
|
|
138
|
+
*/
|
|
139
|
+
segments?: number;
|
|
140
|
+
/**
|
|
141
|
+
* Physics grid resolution, defaulting to `segments`. Separate on purpose —
|
|
142
|
+
* every reference engine separates collision resolution from render
|
|
143
|
+
* resolution, because collision wants the coarsest grid a player cannot
|
|
144
|
+
* feel and rendering wants the finest one that is affordable.
|
|
145
|
+
*/
|
|
146
|
+
colliderSegments?: number;
|
|
147
|
+
/** A name from the built-in material library (ADR-044), the same table
|
|
148
|
+
* Parts resolve against. `grass` and `rock` are the terrain-shaped ones. */
|
|
149
|
+
material?: string;
|
|
150
|
+
/** Flat colour, multiplied with the material the way a Part's is. */
|
|
151
|
+
color?: string;
|
|
152
|
+
}
|
|
94
153
|
export interface Entity3D {
|
|
95
154
|
/** Stable, authored, unique within the scene. */
|
|
96
155
|
id: string;
|
|
@@ -149,6 +208,9 @@ export interface Entity3D {
|
|
|
149
208
|
normals?: number[];
|
|
150
209
|
};
|
|
151
210
|
};
|
|
211
|
+
/** ADR-050 — a heightmap-driven terrain surface. Mutually exclusive with
|
|
212
|
+
* `primitive` and `modelAssetId`: an entity is one kind of thing. */
|
|
213
|
+
heightfield?: Heightfield3D;
|
|
152
214
|
collider?: Collider3D;
|
|
153
215
|
/**
|
|
154
216
|
* ADR-047 — marks this Part for SUBTRACTION the next time it (or a
|
|
@@ -387,6 +449,14 @@ export interface Manifest3D {
|
|
|
387
449
|
file: string;
|
|
388
450
|
}[];
|
|
389
451
|
models?: ModelAsset3D[];
|
|
452
|
+
/** ADR-050 — heightmap images, resolved by id from `Heightfield3D.assetId`.
|
|
453
|
+
* A separate registry from `models` because it is a different kind of
|
|
454
|
+
* thing entirely (an image, with no animations/skins/sockets), and reusing
|
|
455
|
+
* `models` would mean a model entry that is not a model. */
|
|
456
|
+
heightmaps?: {
|
|
457
|
+
id: string;
|
|
458
|
+
path: string;
|
|
459
|
+
}[];
|
|
390
460
|
/** Registry of HUD resources — see `hud3d/types.ts`'s `Hud3DRef`. Named
|
|
391
461
|
* `huds3d`, not `huds`, so it reads unambiguously next to the
|
|
392
462
|
* already-dead `scenes` field above. */
|
|
@@ -396,6 +466,51 @@ export interface Manifest3D {
|
|
|
396
466
|
file: string;
|
|
397
467
|
}[];
|
|
398
468
|
}
|
|
469
|
+
/**
|
|
470
|
+
* ADR-050 — resample a heightmap's pixels into the `(n+1) x (n+1)` grid a
|
|
471
|
+
* surface is built from, bilinearly.
|
|
472
|
+
*
|
|
473
|
+
* `src` is row-major, normalised 0..1, `srcW x srcH`. The result is row-major
|
|
474
|
+
* too, indexed `[iz * (n + 1) + ix]` — **row = z, column = x**, which is also
|
|
475
|
+
* how an image reads (its rows run along the ground away from the camera).
|
|
476
|
+
* Every consumer below shares that one convention; the Rapier hand-off is the
|
|
477
|
+
* only place it changes, and it changes there loudly.
|
|
478
|
+
*
|
|
479
|
+
* Bilinear rather than nearest because an 8-bit heightmap only has 256 levels
|
|
480
|
+
* to begin with: point-sampling a 64px image onto a 128-segment grid would
|
|
481
|
+
* turn a smooth slope into visible stairs twice over, once from the bit depth
|
|
482
|
+
* and once from the resampling.
|
|
483
|
+
*/
|
|
484
|
+
export declare function resampleHeights(src: Float32Array, srcW: number, srcH: number, n: number): Float32Array;
|
|
485
|
+
/**
|
|
486
|
+
* ADR-050 — the arguments `Rapier.ColliderDesc.heightfield` wants, from the
|
|
487
|
+
* row-major grid everything else here uses.
|
|
488
|
+
*
|
|
489
|
+
* **This function exists because of one trap.** Rapier takes its heights as a
|
|
490
|
+
* `nrows x ncols` matrix in COLUMN-MAJOR order, with rows running along local
|
|
491
|
+
* x and columns along local z. Our grid is row-major with rows running along
|
|
492
|
+
* z. Handing ours over directly produces a terrain that is silently
|
|
493
|
+
* TRANSPOSED — still plausible-looking hills, in the wrong places, and only on
|
|
494
|
+
* the collision side, so the player walks into slopes that are not drawn and
|
|
495
|
+
* through ones that are. Keeping the swap in one named function with one test
|
|
496
|
+
* is the whole defence.
|
|
497
|
+
*
|
|
498
|
+
* `scale` carries the world size: Rapier multiplies the raw 0..1 heights by
|
|
499
|
+
* `scale.y`, and spans `scale.x` by `scale.z` CENTRED on the collider origin.
|
|
500
|
+
*/
|
|
501
|
+
export declare function heightfieldColliderArgs(heights: Float32Array, n: number, size: Vec3): {
|
|
502
|
+
nrows: number;
|
|
503
|
+
ncols: number;
|
|
504
|
+
heights: Float32Array;
|
|
505
|
+
scale: Vec3;
|
|
506
|
+
};
|
|
507
|
+
/**
|
|
508
|
+
* ADR-050 — world-space height of the surface at a point, for a grid in the
|
|
509
|
+
* convention above. `x`/`z` are relative to the entity's origin. Returns null
|
|
510
|
+
* outside the footprint rather than clamping, so a caller can tell "off the
|
|
511
|
+
* edge" from "at ground level" — they are different answers.
|
|
512
|
+
*/
|
|
513
|
+
export declare function sampleHeightfield(heights: Float32Array, n: number, size: Vec3, x: number, z: number): number | null;
|
|
399
514
|
/** Identity quaternion, spelled out so callers don't have to remember the order. */
|
|
400
515
|
export declare const IDENTITY_QUAT: Quat;
|
|
401
516
|
export declare function vec3(x?: number, y?: number, z?: number): Vec3;
|
package/dist/scene3d.js
CHANGED
|
@@ -161,6 +161,95 @@ export function cubeFacesFromNames(paths) {
|
|
|
161
161
|
throw new Error(`cube map is missing ${missing.length} face(s): ${missing.join(', ')}`);
|
|
162
162
|
return order.map((f) => found[f]);
|
|
163
163
|
}
|
|
164
|
+
/**
|
|
165
|
+
* ADR-050 — resample a heightmap's pixels into the `(n+1) x (n+1)` grid a
|
|
166
|
+
* surface is built from, bilinearly.
|
|
167
|
+
*
|
|
168
|
+
* `src` is row-major, normalised 0..1, `srcW x srcH`. The result is row-major
|
|
169
|
+
* too, indexed `[iz * (n + 1) + ix]` — **row = z, column = x**, which is also
|
|
170
|
+
* how an image reads (its rows run along the ground away from the camera).
|
|
171
|
+
* Every consumer below shares that one convention; the Rapier hand-off is the
|
|
172
|
+
* only place it changes, and it changes there loudly.
|
|
173
|
+
*
|
|
174
|
+
* Bilinear rather than nearest because an 8-bit heightmap only has 256 levels
|
|
175
|
+
* to begin with: point-sampling a 64px image onto a 128-segment grid would
|
|
176
|
+
* turn a smooth slope into visible stairs twice over, once from the bit depth
|
|
177
|
+
* and once from the resampling.
|
|
178
|
+
*/
|
|
179
|
+
export function resampleHeights(src, srcW, srcH, n) {
|
|
180
|
+
const out = new Float32Array((n + 1) * (n + 1));
|
|
181
|
+
const at = (x, z) => src[Math.min(srcH - 1, z) * srcW + Math.min(srcW - 1, x)];
|
|
182
|
+
for (let iz = 0; iz <= n; iz++) {
|
|
183
|
+
const fz = (iz / n) * (srcH - 1);
|
|
184
|
+
const z0 = Math.floor(fz), tz = fz - z0;
|
|
185
|
+
for (let ix = 0; ix <= n; ix++) {
|
|
186
|
+
const fx = (ix / n) * (srcW - 1);
|
|
187
|
+
const x0 = Math.floor(fx), tx = fx - x0;
|
|
188
|
+
const a = at(x0, z0), b = at(x0 + 1, z0), c = at(x0, z0 + 1), d = at(x0 + 1, z0 + 1);
|
|
189
|
+
out[iz * (n + 1) + ix] = (a * (1 - tx) + b * tx) * (1 - tz) + (c * (1 - tx) + d * tx) * tz;
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
return out;
|
|
193
|
+
}
|
|
194
|
+
/**
|
|
195
|
+
* ADR-050 — the arguments `Rapier.ColliderDesc.heightfield` wants, from the
|
|
196
|
+
* row-major grid everything else here uses.
|
|
197
|
+
*
|
|
198
|
+
* **This function exists because of one trap.** Rapier takes its heights as a
|
|
199
|
+
* `nrows x ncols` matrix in COLUMN-MAJOR order, with rows running along local
|
|
200
|
+
* x and columns along local z. Our grid is row-major with rows running along
|
|
201
|
+
* z. Handing ours over directly produces a terrain that is silently
|
|
202
|
+
* TRANSPOSED — still plausible-looking hills, in the wrong places, and only on
|
|
203
|
+
* the collision side, so the player walks into slopes that are not drawn and
|
|
204
|
+
* through ones that are. Keeping the swap in one named function with one test
|
|
205
|
+
* is the whole defence.
|
|
206
|
+
*
|
|
207
|
+
* `scale` carries the world size: Rapier multiplies the raw 0..1 heights by
|
|
208
|
+
* `scale.y`, and spans `scale.x` by `scale.z` CENTRED on the collider origin.
|
|
209
|
+
*/
|
|
210
|
+
export function heightfieldColliderArgs(heights, n, size) {
|
|
211
|
+
const side = n + 1;
|
|
212
|
+
const columnMajor = new Float32Array(side * side);
|
|
213
|
+
for (let iz = 0; iz < side; iz++) {
|
|
214
|
+
for (let ix = 0; ix < side; ix++) {
|
|
215
|
+
// ours `[iz * side + ix]` (row = z) → Rapier's `[r + c * side]` where r
|
|
216
|
+
// indexes world Z and c indexes world X. So r = iz, c = ix.
|
|
217
|
+
//
|
|
218
|
+
// MEASURED, not derived. The obvious reading of "column-major, rows
|
|
219
|
+
// along x" produces `[ix + iz * side]`, which is byte-for-byte the SAME
|
|
220
|
+
// expression as ours — an identity mapping dressed up as a transpose —
|
|
221
|
+
// and a ray probe showed the terrain coming out rotated a quarter turn:
|
|
222
|
+
// collision slopes where nothing is drawn, flat ground where a hill is.
|
|
223
|
+
columnMajor[iz + ix * side] = heights[iz * side + ix];
|
|
224
|
+
}
|
|
225
|
+
}
|
|
226
|
+
// `nrows`/`ncols` are CELL counts, not sample counts — the binding builds a
|
|
227
|
+
// `(nrows + 1) x (ncols + 1)` matrix from the array. Passing sample counts
|
|
228
|
+
// makes Rapier panic inside wasm with an unreachable, which surfaces as a
|
|
229
|
+
// stack trace through four layers of minified glue and says nothing about
|
|
230
|
+
// the actual mistake. Found exactly that way.
|
|
231
|
+
return { nrows: n, ncols: n, heights: columnMajor, scale: { x: size.x, y: size.y, z: size.z } };
|
|
232
|
+
}
|
|
233
|
+
/**
|
|
234
|
+
* ADR-050 — world-space height of the surface at a point, for a grid in the
|
|
235
|
+
* convention above. `x`/`z` are relative to the entity's origin. Returns null
|
|
236
|
+
* outside the footprint rather than clamping, so a caller can tell "off the
|
|
237
|
+
* edge" from "at ground level" — they are different answers.
|
|
238
|
+
*/
|
|
239
|
+
export function sampleHeightfield(heights, n, size, x, z) {
|
|
240
|
+
const u = x / size.x + 0.5;
|
|
241
|
+
const v = z / size.z + 0.5;
|
|
242
|
+
if (u < 0 || u > 1 || v < 0 || v > 1)
|
|
243
|
+
return null;
|
|
244
|
+
const side = n + 1;
|
|
245
|
+
const fx = u * n, fz = v * n;
|
|
246
|
+
const x0 = Math.min(n - 1, Math.floor(fx)), z0 = Math.min(n - 1, Math.floor(fz));
|
|
247
|
+
const tx = fx - x0, tz = fz - z0;
|
|
248
|
+
const h = (ix, iz) => heights[iz * side + ix];
|
|
249
|
+
const top = h(x0, z0) * (1 - tx) + h(x0 + 1, z0) * tx;
|
|
250
|
+
const bottom = h(x0, z0 + 1) * (1 - tx) + h(x0 + 1, z0 + 1) * tx;
|
|
251
|
+
return (top * (1 - tz) + bottom * tz) * size.y;
|
|
252
|
+
}
|
|
164
253
|
/** Identity quaternion, spelled out so callers don't have to remember the order. */
|
|
165
254
|
export const IDENTITY_QUAT = [0, 0, 0, 1];
|
|
166
255
|
export function vec3(x = 0, y = 0, z = 0) { return { x, y, z }; }
|
|
@@ -189,12 +278,40 @@ export function validateScene(scene) {
|
|
|
189
278
|
else if (ids.has(e.id))
|
|
190
279
|
problems.push(`duplicate entity id '${e.id}'`);
|
|
191
280
|
ids.add(e.id);
|
|
192
|
-
if (!e.modelAssetId && !e.primitive) {
|
|
193
|
-
problems.push(`entity '${e.id}' has neither a model nor a
|
|
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.19.0",
|
|
4
4
|
"description": "Three.js runtime for Umicat games: the scene3d design format, its loader with physics, a kinematic character controller, and the Umicat platform via @umicat/platform-sdk.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|