@umicat/three-sdk 1.21.0 → 1.22.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 +46 -0
- package/dist/SceneLoader3D.js +61 -19
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/package.json +1 -1
package/dist/SceneLoader3D.d.ts
CHANGED
|
@@ -55,6 +55,52 @@ export interface LoadedScene3D {
|
|
|
55
55
|
dispose(): void;
|
|
56
56
|
}
|
|
57
57
|
export declare function applyTransform(obj: THREE.Object3D, e: Entity3D): void;
|
|
58
|
+
/**
|
|
59
|
+
* ADR-044 — the built-in Parts material library. A NAME resolves to two
|
|
60
|
+
* CDN-hosted maps (Color + Roughness only — see the ADR's own "game-grade,
|
|
61
|
+
* not showcase-grade" scoping for why Normal/Displacement/AO aren't here),
|
|
62
|
+
* re-hosted (not linked to the source) under the platform-wide, already-
|
|
63
|
+
* public `platform/` S3 prefix (`cdn.umicat.ai/platform/...` — the same
|
|
64
|
+
* prefix `platform/canonical-rig/v1/...` already uses for the Model
|
|
65
|
+
* Editor's auto-rig skeleton; no bucket-policy change was needed). Sourced
|
|
66
|
+
* from ambientCG (CC0), reprocessed to 512×512 JPEG.
|
|
67
|
+
*/
|
|
68
|
+
/**
|
|
69
|
+
* ADR-050 — the built-in heightmap library: terrain shapes a creator can pick
|
|
70
|
+
* without having to author or import an image first.
|
|
71
|
+
*
|
|
72
|
+
* **Unlike `MATERIAL_LIBRARY`, this is a convenience layer, not a fence.**
|
|
73
|
+
* `Heightfield3D.assetId` resolves against the project's own
|
|
74
|
+
* `manifest.heightmaps`, so any image a project ships already works; these
|
|
75
|
+
* entries are simply pre-registered ones a UI can offer. Materials are the
|
|
76
|
+
* opposite — a closed table, with "use your own texture" explicitly out of
|
|
77
|
+
* scope in ADR-044. The difference is deliberate: a heightmap is a shape
|
|
78
|
+
* someone will want to author, a material is a surface we curate.
|
|
79
|
+
*
|
|
80
|
+
* Shape-first rather than noise-first, and deliberately NOT real elevation
|
|
81
|
+
* data. Real DEM tiles were sourced, licence-checked and tried (SRTM, public
|
|
82
|
+
* domain) and read badly: a casual scene is 20-60 units across, where a real
|
|
83
|
+
* landscape's hundreds of drainage channels become visual noise with no shape
|
|
84
|
+
* you can point at. These eight each have one readable idea.
|
|
85
|
+
*
|
|
86
|
+
* They differ in CHARACTER, not amplitude — amplitude is what `size.y`
|
|
87
|
+
* already controls, so three heightmaps differing only in height would be
|
|
88
|
+
* three copies of one preset.
|
|
89
|
+
*/
|
|
90
|
+
export declare const HEIGHTMAP_LIBRARY: Record<string, string>;
|
|
91
|
+
/**
|
|
92
|
+
* Where a `Heightfield3D.assetId` actually lives.
|
|
93
|
+
*
|
|
94
|
+
* A project's own `manifest.heightmaps` wins over a library name of the same
|
|
95
|
+
* id, so a creator can override `hills` by registering their own — the library
|
|
96
|
+
* is a default, never a reservation. Throws naming every id that WOULD have
|
|
97
|
+
* worked, because "no heightmap 'hils'" with no list is the single most
|
|
98
|
+
* annoying asset error there is.
|
|
99
|
+
*/
|
|
100
|
+
export declare function heightmapUrl(assetId: string, manifest: Manifest3D, assetBase?: string): string;
|
|
101
|
+
/** The size a preset is meant to be dropped at. One value for all eight,
|
|
102
|
+
* which only works because they differ in character rather than height. */
|
|
103
|
+
export declare const HEIGHTMAP_DEFAULT_SIZE: Vec3;
|
|
58
104
|
export declare const MATERIAL_LIBRARY: Record<string, {
|
|
59
105
|
color: string;
|
|
60
106
|
roughness: string;
|
package/dist/SceneLoader3D.js
CHANGED
|
@@ -204,6 +204,56 @@ function cornerWedgeGeometry(size) {
|
|
|
204
204
|
* Editor's auto-rig skeleton; no bucket-policy change was needed). Sourced
|
|
205
205
|
* from ambientCG (CC0), reprocessed to 512×512 JPEG.
|
|
206
206
|
*/
|
|
207
|
+
/**
|
|
208
|
+
* ADR-050 — the built-in heightmap library: terrain shapes a creator can pick
|
|
209
|
+
* without having to author or import an image first.
|
|
210
|
+
*
|
|
211
|
+
* **Unlike `MATERIAL_LIBRARY`, this is a convenience layer, not a fence.**
|
|
212
|
+
* `Heightfield3D.assetId` resolves against the project's own
|
|
213
|
+
* `manifest.heightmaps`, so any image a project ships already works; these
|
|
214
|
+
* entries are simply pre-registered ones a UI can offer. Materials are the
|
|
215
|
+
* opposite — a closed table, with "use your own texture" explicitly out of
|
|
216
|
+
* scope in ADR-044. The difference is deliberate: a heightmap is a shape
|
|
217
|
+
* someone will want to author, a material is a surface we curate.
|
|
218
|
+
*
|
|
219
|
+
* Shape-first rather than noise-first, and deliberately NOT real elevation
|
|
220
|
+
* data. Real DEM tiles were sourced, licence-checked and tried (SRTM, public
|
|
221
|
+
* domain) and read badly: a casual scene is 20-60 units across, where a real
|
|
222
|
+
* landscape's hundreds of drainage channels become visual noise with no shape
|
|
223
|
+
* you can point at. These eight each have one readable idea.
|
|
224
|
+
*
|
|
225
|
+
* They differ in CHARACTER, not amplitude — amplitude is what `size.y`
|
|
226
|
+
* already controls, so three heightmaps differing only in height would be
|
|
227
|
+
* three copies of one preset.
|
|
228
|
+
*/
|
|
229
|
+
export const HEIGHTMAP_LIBRARY = Object.fromEntries(
|
|
230
|
+
// `island` is honest about needing water: its geometry is a mound with a
|
|
231
|
+
// margin of zero all round, which becomes a shoreline the moment ADR-050's
|
|
232
|
+
// water lands and is indistinguishable from `hills` until then.
|
|
233
|
+
['hills', 'plains', 'mountains', 'valley', 'island', 'plateau', 'basin', 'dunes']
|
|
234
|
+
.map((name) => [name, `https://cdn.umicat.ai/platform/three-sdk-heightmaps/${name}.png`]));
|
|
235
|
+
/**
|
|
236
|
+
* Where a `Heightfield3D.assetId` actually lives.
|
|
237
|
+
*
|
|
238
|
+
* A project's own `manifest.heightmaps` wins over a library name of the same
|
|
239
|
+
* id, so a creator can override `hills` by registering their own — the library
|
|
240
|
+
* is a default, never a reservation. Throws naming every id that WOULD have
|
|
241
|
+
* worked, because "no heightmap 'hils'" with no list is the single most
|
|
242
|
+
* annoying asset error there is.
|
|
243
|
+
*/
|
|
244
|
+
export function heightmapUrl(assetId, manifest, assetBase) {
|
|
245
|
+
const entry = (manifest.heightmaps ?? []).find((h) => h.id === assetId);
|
|
246
|
+
if (entry)
|
|
247
|
+
return resolveAssetUrl(assetBase, entry.path);
|
|
248
|
+
const built = HEIGHTMAP_LIBRARY[assetId];
|
|
249
|
+
if (built)
|
|
250
|
+
return built;
|
|
251
|
+
const have = [...(manifest.heightmaps ?? []).map((h) => h.id), ...Object.keys(HEIGHTMAP_LIBRARY)].join(', ');
|
|
252
|
+
throw new Error(`[umicat] no heightmap '${assetId}' in the manifest or the built-in library. Available: ${have || '(none)'}`);
|
|
253
|
+
}
|
|
254
|
+
/** The size a preset is meant to be dropped at. One value for all eight,
|
|
255
|
+
* which only works because they differ in character rather than height. */
|
|
256
|
+
export const HEIGHTMAP_DEFAULT_SIZE = { x: 40, y: 6, z: 40 };
|
|
207
257
|
const MATERIAL_BASE = 'https://cdn.umicat.ai/platform/three-sdk-materials';
|
|
208
258
|
export const MATERIAL_LIBRARY = Object.fromEntries(['concrete', 'brick', 'wood', 'metal', 'cardboard', 'rock', 'grass', 'tile'].map((name) => [
|
|
209
259
|
name, { color: `${MATERIAL_BASE}/${name}/color.jpg`, roughness: `${MATERIAL_BASE}/${name}/roughness.jpg` },
|
|
@@ -357,12 +407,7 @@ function heightmapPixels(url) {
|
|
|
357
407
|
* same heightmap costs one fetch.
|
|
358
408
|
*/
|
|
359
409
|
export async function makeHeightfield(hf, manifest, opts = {}) {
|
|
360
|
-
const
|
|
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(resolveAssetUrl(opts.assetBase, entry.path));
|
|
410
|
+
const px = await heightmapPixels(heightmapUrl(hf.assetId, manifest, opts.assetBase));
|
|
366
411
|
const seg = heightfieldSegments(hf);
|
|
367
412
|
const heights = resampleHeights(px.data, px.width, px.height, seg.render);
|
|
368
413
|
const material = new THREE.MeshStandardMaterial({ color: hf.color ?? '#ffffff' });
|
|
@@ -642,22 +687,19 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
|
|
|
642
687
|
// ADR-050 — heightmaps are fetched and decoded up front, same contract the
|
|
643
688
|
// models above follow: a caller that awaits `loadScene3D` gets a finished
|
|
644
689
|
// scene, not one whose terrain pops in flat and then rises a frame later.
|
|
645
|
-
|
|
646
|
-
|
|
690
|
+
// Nothing is stored from the prefetch — `heightmapPixels` caches per url, so
|
|
691
|
+
// this exists purely to run the decodes in PARALLEL and to make an unknown
|
|
692
|
+
// id fail at load. `makeHeightfield` then hits warm cache entries.
|
|
647
693
|
const heightmapJobs = [];
|
|
694
|
+
const prefetched = new Set();
|
|
648
695
|
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))
|
|
696
|
+
if (!e.heightfield || prefetched.has(e.heightfield.assetId))
|
|
657
697
|
continue;
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
698
|
+
prefetched.add(e.heightfield.assetId);
|
|
699
|
+
// Resolved through the SAME function `makeHeightfield` uses — which is
|
|
700
|
+
// also what makes an unknown id fail HERE, at load, naming every id that
|
|
701
|
+
// would have worked, rather than per-entity later.
|
|
702
|
+
heightmapJobs.push(heightmapPixels(heightmapUrl(e.heightfield.assetId, manifest, opts.assetBase)).then(() => { }));
|
|
661
703
|
}
|
|
662
704
|
if (heightmapJobs.length)
|
|
663
705
|
await Promise.all(heightmapJobs);
|
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, heightfieldGeometry, makeHeightfield } from './SceneLoader3D.js';
|
|
4
|
+
export { loadScene3D, loadModelAsset, heightfieldGeometry, makeHeightfield, HEIGHTMAP_LIBRARY, HEIGHTMAP_DEFAULT_SIZE } 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, heightfieldGeometry, makeHeightfield } from './SceneLoader3D.js';
|
|
8
|
+
export { loadScene3D, loadModelAsset, heightfieldGeometry, makeHeightfield, HEIGHTMAP_LIBRARY, HEIGHTMAP_DEFAULT_SIZE } 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/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@umicat/three-sdk",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.22.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",
|