@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.
@@ -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;
@@ -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 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(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
- const heightmaps = new Map((manifest.heightmaps ?? []).map((h) => [h.id, h]));
646
- const heightmapPixelsById = new Map();
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
- heightmapPixelsById.set(entry.id, { data: new Float32Array(1), width: 1, height: 1 });
659
- heightmapJobs.push(heightmapPixels(resolveAssetUrl(opts.assetBase, entry.path))
660
- .then((px) => { heightmapPixelsById.set(entry.id, px); }));
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.21.0",
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",