@umicat/three-sdk 1.20.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.
@@ -1,6 +1,7 @@
1
1
  import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
2
2
  import { clone as cloneRigged } from 'three/examples/jsm/utils/SkeletonUtils.js';
3
3
  import { attachToSocket } from './Sockets.js';
4
+ import { resolveAssetUrl } from './scene3d.js';
4
5
  const cache = new Map();
5
6
  let loader = null;
6
7
  function fetchProp(url) {
@@ -57,7 +58,7 @@ export async function applyAttachments(wearer, wearerAsset, manifest, list, opts
57
58
  }
58
59
  resolved.push({ key: a.id ?? socketName, name: a.id ?? prop.id, prop, socket });
59
60
  }
60
- const gltfs = await Promise.all(resolved.map(({ prop }) => opts.preloaded?.get(prop.id) ?? fetchProp((opts.assetBase ?? '') + prop.path)));
61
+ const gltfs = await Promise.all(resolved.map(({ prop }) => opts.preloaded?.get(prop.id) ?? fetchProp(resolveAssetUrl(opts.assetBase, prop.path))));
61
62
  for (const object of opts.previous?.values() ?? [])
62
63
  detach(object);
63
64
  const worn = new Map();
@@ -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;
@@ -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, resampleHeights, heightfieldColliderArgs, } from './scene3d.js';
4
+ import { validateScene, IDENTITY_QUAT, wedgeVertices, cornerWedgeVertices, defaultColliderForPrimitive, resampleHeights, heightfieldColliderArgs, resolveAssetUrl, } from './scene3d.js';
5
5
  import { applySkin } from './Skin.js';
6
6
  import { applyAttachments } from './Attachments.js';
7
7
  function toVec(v, d = 0) {
@@ -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((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' });
@@ -526,7 +571,7 @@ export async function loadModelAsset(manifest, modelAssetId, opts = {}) {
526
571
  const have = (manifest.models ?? []).map((m) => m.id).join(', ');
527
572
  throw new Error(`[umicat] manifest has no model '${modelAssetId}'. It has: ${have || '(none)'}`);
528
573
  }
529
- const gltf = await new GLTFLoader().loadAsync((opts.assetBase ?? '') + asset.path);
574
+ const gltf = await new GLTFLoader().loadAsync(resolveAssetUrl(opts.assetBase, asset.path));
530
575
  const object = gltf.scene;
531
576
  if (opts.skin) {
532
577
  const path = asset.skins?.[opts.skin];
@@ -565,10 +610,10 @@ export async function applySky(scene, sky, opts = {}) {
565
610
  if (sky.paths?.length !== 6) {
566
611
  throw new Error(`cubemap sky needs exactly 6 faces, got ${sky.paths?.length ?? 0} — use cubeFacesFromNames to order them`);
567
612
  }
568
- texture = await new THREE.CubeTextureLoader().loadAsync(sky.paths.map((p) => base + p));
613
+ texture = await new THREE.CubeTextureLoader().loadAsync(sky.paths.map((p) => resolveAssetUrl(base, p)));
569
614
  }
570
615
  else {
571
- texture = await new THREE.TextureLoader().loadAsync(base + sky.path);
616
+ texture = await new THREE.TextureLoader().loadAsync(resolveAssetUrl(base, sky.path));
572
617
  texture.mapping = THREE.EquirectangularReflectionMapping;
573
618
  }
574
619
  texture.colorSpace = THREE.SRGBColorSpace;
@@ -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((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);
@@ -668,7 +710,7 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
668
710
  const asset = models.get(id);
669
711
  if (!asset)
670
712
  throw new Error(`scene3d references model '${id}', which the manifest does not define`);
671
- const url = (opts.assetBase ?? '') + asset.path;
713
+ const url = resolveAssetUrl(opts.assetBase, asset.path);
672
714
  loaded.set(id, await loader.loadAsync(url));
673
715
  }));
674
716
  }
package/dist/Skin.js CHANGED
@@ -1,4 +1,5 @@
1
1
  import * as THREE from 'three';
2
+ import { resolveAssetUrl } from './scene3d.js';
2
3
  /** Objects whose materials have already been given their own copies. */
3
4
  const isolated = new WeakSet();
4
5
  const textures = new Map();
@@ -100,7 +101,7 @@ export function applySkinTexture(object, texture, opts = {}) {
100
101
  * did nothing", and there is no other signal.
101
102
  */
102
103
  export async function applySkin(object, url, opts = {}) {
103
- const full = (opts.assetBase ?? '') + url;
104
+ const full = resolveAssetUrl(opts.assetBase, url);
104
105
  const texture = await loadSkinTexture(full, opts.cache !== false);
105
106
  return applySkinTexture(object, texture, opts);
106
107
  }
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/dist/scene3d.d.ts CHANGED
@@ -511,6 +511,26 @@ export declare function heightfieldColliderArgs(heights: Float32Array, n: number
511
511
  * edge" from "at ground level" — they are different answers.
512
512
  */
513
513
  export declare function sampleHeightfield(heights: Float32Array, n: number, size: Vec3, x: number, z: number): number | null;
514
+ /**
515
+ * Join a project's asset base to an asset's own path — **unless the path is
516
+ * already complete**, in which case it is returned untouched.
517
+ *
518
+ * Every asset path in this SDK used to be a bare `base + path` concatenation,
519
+ * which quietly made one whole category of asset unreferenceable: anything
520
+ * hosted somewhere else. A manifest entry pointing at
521
+ * `https://cdn.umicat.ai/platform/...` became
522
+ * `<base>https://cdn.umicat.ai/platform/...` and 404'd, in every project whose
523
+ * base is non-empty — which is every real project. This blocked platform-hosted
524
+ * assets of ANY kind (ADR-050's preset heightmaps are what surfaced it) and it
525
+ * applied equally to models, skins, props and skies.
526
+ *
527
+ * Left deliberately alone: a ROOT-RELATIVE `/foo.png`. It reads as "from the
528
+ * site root", but `base + '/foo.png'` against a CDN base is the established
529
+ * behaviour and almost certainly what the author of such a path meant.
530
+ * Changing it would be a silent behaviour change for existing projects, which
531
+ * is not worth it to make one more spelling work.
532
+ */
533
+ export declare function resolveAssetUrl(base: string | undefined, path: string): string;
514
534
  /** Identity quaternion, spelled out so callers don't have to remember the order. */
515
535
  export declare const IDENTITY_QUAT: Quat;
516
536
  export declare function vec3(x?: number, y?: number, z?: number): Vec3;
package/dist/scene3d.js CHANGED
@@ -250,6 +250,32 @@ export function sampleHeightfield(heights, n, size, x, z) {
250
250
  const bottom = h(x0, z0 + 1) * (1 - tx) + h(x0 + 1, z0 + 1) * tx;
251
251
  return (top * (1 - tz) + bottom * tz) * size.y;
252
252
  }
253
+ /**
254
+ * Join a project's asset base to an asset's own path — **unless the path is
255
+ * already complete**, in which case it is returned untouched.
256
+ *
257
+ * Every asset path in this SDK used to be a bare `base + path` concatenation,
258
+ * which quietly made one whole category of asset unreferenceable: anything
259
+ * hosted somewhere else. A manifest entry pointing at
260
+ * `https://cdn.umicat.ai/platform/...` became
261
+ * `<base>https://cdn.umicat.ai/platform/...` and 404'd, in every project whose
262
+ * base is non-empty — which is every real project. This blocked platform-hosted
263
+ * assets of ANY kind (ADR-050's preset heightmaps are what surfaced it) and it
264
+ * applied equally to models, skins, props and skies.
265
+ *
266
+ * Left deliberately alone: a ROOT-RELATIVE `/foo.png`. It reads as "from the
267
+ * site root", but `base + '/foo.png'` against a CDN base is the established
268
+ * behaviour and almost certainly what the author of such a path meant.
269
+ * Changing it would be a silent behaviour change for existing projects, which
270
+ * is not worth it to make one more spelling work.
271
+ */
272
+ export function resolveAssetUrl(base, path) {
273
+ // Any scheme (`https:`, `data:`, `blob:`) or protocol-relative `//host/...`
274
+ // is already a complete reference.
275
+ if (/^[a-z][a-z0-9+.-]*:/i.test(path) || path.startsWith('//'))
276
+ return path;
277
+ return (base ?? '') + path;
278
+ }
253
279
  /** Identity quaternion, spelled out so callers don't have to remember the order. */
254
280
  export const IDENTITY_QUAT = [0, 0, 0, 1];
255
281
  export function vec3(x = 0, y = 0, z = 0) { return { x, y, z }; }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@umicat/three-sdk",
3
- "version": "1.20.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",