@umicat/three-sdk 1.7.0 → 1.8.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.
@@ -54,6 +54,10 @@ export interface LoadedScene3D {
54
54
  update(dt: number): void;
55
55
  dispose(): void;
56
56
  }
57
+ export declare const MATERIAL_LIBRARY: Record<string, {
58
+ color: string;
59
+ roughness: string;
60
+ }>;
57
61
  export declare function makePrimitive(e: Entity3D): THREE.Mesh;
58
62
  /**
59
63
  * Turn scene3d design data into a running three.js scene.
@@ -37,12 +37,53 @@ function applyTransform(obj, e) {
37
37
  * `computeVertexNormals()` yields one flat normal per FACE rather than
38
38
  * blending across a shared vertex between two faces at different angles
39
39
  * (which would wrongly soften the wedge's sharp ridge edge into a curve).
40
+ *
41
+ * ADR-044 — also assigns a UV per vertex, dominant-axis PLANAR per face
42
+ * (box/sphere/cylinder/plane all already have usable UVs from three.js's
43
+ * own geometry constructors; these two hand-built shapes had none at all
44
+ * before this). Each face is flat by construction, so the face's own
45
+ * normal (computed directly from its 3 points — BEFORE
46
+ * `computeVertexNormals()` blends anything) picks which two of the three
47
+ * local axes to project onto: a face whose normal is mostly ±X reads its
48
+ * UV from (y,z), mostly ±Y from (x,z), mostly ±Z from (x,y). `size` scales
49
+ * the projection so UV spans ~0..1 per face — the SAME convention
50
+ * `BoxGeometry`'s own per-face UVs already use, which is what lets
51
+ * `makePrimitive`'s `texture.repeat` math treat every primitive kind
52
+ * uniformly regardless of which one actually has native UVs.
40
53
  */
41
- function triangleListGeometry(triangles) {
54
+ function triangleListGeometry(triangles, size) {
42
55
  const positions = new Float32Array(triangles.length * 3);
56
+ const uvs = new Float32Array(triangles.length * 2);
43
57
  triangles.forEach((v, i) => { positions[i * 3] = v.x; positions[i * 3 + 1] = v.y; positions[i * 3 + 2] = v.z; });
58
+ for (let i = 0; i < triangles.length; i += 3) {
59
+ const a = triangles[i], b = triangles[i + 1], c = triangles[i + 2];
60
+ const ab = new THREE.Vector3(b.x - a.x, b.y - a.y, b.z - a.z);
61
+ const ac = new THREE.Vector3(c.x - a.x, c.y - a.y, c.z - a.z);
62
+ const n = new THREE.Vector3().crossVectors(ab, ac);
63
+ const ax = Math.abs(n.x), ay = Math.abs(n.y), az = Math.abs(n.z);
64
+ for (let k = 0; k < 3; k++) {
65
+ const v = triangles[i + k];
66
+ let u, w;
67
+ if (ax >= ay && ax >= az) {
68
+ u = v.y / size.y;
69
+ w = v.z / size.z;
70
+ }
71
+ else if (ay >= ax && ay >= az) {
72
+ u = v.x / size.x;
73
+ w = v.z / size.z;
74
+ }
75
+ else {
76
+ u = v.x / size.x;
77
+ w = v.y / size.y;
78
+ }
79
+ const idx = i + k;
80
+ uvs[idx * 2] = u + 0.5;
81
+ uvs[idx * 2 + 1] = w + 0.5;
82
+ }
83
+ }
44
84
  const geom = new THREE.BufferGeometry();
45
85
  geom.setAttribute('position', new THREE.BufferAttribute(positions, 3));
86
+ geom.setAttribute('uv', new THREE.BufferAttribute(uvs, 2));
46
87
  geom.computeVertexNormals();
47
88
  return geom;
48
89
  }
@@ -56,7 +97,7 @@ function wedgeGeometry(size) {
56
97
  v0, v3, v4, // left end cap
57
98
  v1, v5, v2, // right end cap
58
99
  v3, v2, v4, v2, v5, v4, // slope (hypotenuse)
59
- ]);
100
+ ], size);
60
101
  }
61
102
  /** Winding verified by hand the same way as `wedgeGeometry` — see
62
103
  * `scene3d.ts`'s `cornerWedgeVertices` doc comment for the vertex layout. */
@@ -68,7 +109,78 @@ function cornerWedgeGeometry(size) {
68
109
  v1, v4, v2, // right side
69
110
  v2, v4, v3, // front side
70
111
  v3, v4, v0, // left side
71
- ]);
112
+ ], size);
113
+ }
114
+ /**
115
+ * ADR-044 — the built-in Parts material library. A NAME resolves to two
116
+ * CDN-hosted maps (Color + Roughness only — see the ADR's own "game-grade,
117
+ * not showcase-grade" scoping for why Normal/Displacement/AO aren't here),
118
+ * re-hosted (not linked to the source) under the platform-wide, already-
119
+ * public `platform/` S3 prefix (`cdn.umicat.ai/platform/...` — the same
120
+ * prefix `platform/canonical-rig/v1/...` already uses for the Model
121
+ * Editor's auto-rig skeleton; no bucket-policy change was needed). Sourced
122
+ * from ambientCG (CC0), reprocessed to 512×512 JPEG.
123
+ */
124
+ const MATERIAL_BASE = 'https://cdn.umicat.ai/platform/three-sdk-materials';
125
+ export const MATERIAL_LIBRARY = Object.fromEntries(['concrete', 'brick', 'wood', 'metal', 'cardboard', 'rock', 'grass', 'tile'].map((name) => [
126
+ name, { color: `${MATERIAL_BASE}/${name}/color.jpg`, roughness: `${MATERIAL_BASE}/${name}/roughness.jpg` },
127
+ ]));
128
+ /** How many world units one tile of a material's source photo covers —
129
+ * matched loosely to each photo's own real-world scale so e.g. brick
130
+ * courses read as actual brick-sized, not a wall-sized or postage-stamp-
131
+ * sized repeat. Same role `groundRestOffset` plays for placement: a
132
+ * small per-kind constant rather than a universal formula, because there
133
+ * isn't one — these are real photos at real physical scales. */
134
+ const MATERIAL_TILE_UNIT = {
135
+ concrete: 1, brick: 0.5, wood: 1, metal: 1, cardboard: 0.6, rock: 1, grass: 1, tile: 0.5,
136
+ };
137
+ const materialTextures = new Map();
138
+ let materialLoader = null;
139
+ /** Load (and cache) one material-library texture. `colorSpace` distinguishes
140
+ * the Color map (sRGB — it's a photographed colour) from Roughness (a data
141
+ * map — tagging it sRGB would wrongly remap its own numeric values, the
142
+ * same class of mistake `Skin.ts`'s texture loader already guards against
143
+ * for the opposite reason). Unlike `Skin.ts`'s `loadSkinTexture`, `flipY`
144
+ * is left at the `TextureLoader` DEFAULT (`true`) — these primitives use
145
+ * three.js's own standard UV convention (both the native box/sphere/
146
+ * cylinder/plane geometries AND `triangleListGeometry`'s hand-rolled UVs
147
+ * above), not GLTFLoader's inverted one; copying Skin.ts's `flipY=false`
148
+ * here would flip every Parts material upside down. */
149
+ function loadMaterialTexture(url, colorSpace) {
150
+ const key = `${url}|${colorSpace}`;
151
+ const hit = materialTextures.get(key);
152
+ if (hit)
153
+ return hit;
154
+ materialLoader ?? (materialLoader = new THREE.TextureLoader());
155
+ const p = materialLoader.loadAsync(url).then((t) => {
156
+ t.colorSpace = colorSpace;
157
+ t.wrapS = t.wrapT = THREE.RepeatWrapping;
158
+ return t;
159
+ });
160
+ materialTextures.set(key, p);
161
+ // A failed fetch must not be remembered as the answer — same reasoning
162
+ // Skin.ts's cache already documents.
163
+ p.catch(() => materialTextures.delete(key));
164
+ return p;
165
+ }
166
+ /**
167
+ * ADR-044 — how many times a material's texture repeats across a Part,
168
+ * per axis. box/plane/wedge/corner-wedge all use width×depth (the closest
169
+ * single approximation to "looks right" across a shape with several
170
+ * differently-sized faces — a perfect per-face repeat would need a scale
171
+ * baked in per face, not worth it for a blockout tool); cylinder uses
172
+ * diameter×height; sphere uses diameter on both axes (no clean width-vs-
173
+ * depth distinction on a sphere for tiling purposes).
174
+ */
175
+ function materialRepeatFor(kind, size, tileUnit) {
176
+ const u = (n) => Math.max(0.1, n / tileUnit);
177
+ if (kind === 'cylinder')
178
+ return new THREE.Vector2(u(size.x), u(size.y));
179
+ if (kind === 'sphere') {
180
+ const d = u(size.x);
181
+ return new THREE.Vector2(d, d);
182
+ }
183
+ return new THREE.Vector2(u(size.x), u(size.z));
72
184
  }
73
185
  export function makePrimitive(e) {
74
186
  const p = e.primitive;
@@ -87,7 +199,7 @@ export function makePrimitive(e) {
87
199
  // measurement still says the character is dead centre, because it is —
88
200
  // behind a 40x40 wall.
89
201
  : new THREE.PlaneGeometry(s.x, s.z).rotateX(-Math.PI / 2);
90
- const mesh = new THREE.Mesh(geom, new THREE.MeshStandardMaterial({
202
+ const material = new THREE.MeshStandardMaterial({
91
203
  color: new THREE.Color(p.color ?? '#c8c8c8'), roughness: 0.85,
92
204
  // The wedge/corner-wedge faces' winding was verified by hand (no
93
205
  // browser available to render and visually confirm it in this pass) —
@@ -95,9 +207,42 @@ export function makePrimitive(e) {
95
207
  // making a face invisible from its intended viewing side; it costs a
96
208
  // little backface-culling perf on two low-poly shapes, not correctness.
97
209
  side: (p.kind === 'wedge' || p.kind === 'corner-wedge') ? THREE.DoubleSide : THREE.FrontSide,
98
- }));
210
+ });
211
+ const mesh = new THREE.Mesh(geom, material);
99
212
  mesh.castShadow = p.kind !== 'plane';
100
213
  mesh.receiveShadow = true;
214
+ // ADR-044 — flat color renders IMMEDIATELY above; a material's textures
215
+ // arrive async and patch the material in place once loaded (same "good
216
+ // default now, real thing when it's ready" shape as every other
217
+ // CDN-texture consumer in this SDK). A missing/renamed material name, or
218
+ // a failed fetch, silently keeps the flat color rather than erroring —
219
+ // this is cosmetic, not a thing worth surfacing as a broken scene.
220
+ const libEntry = p.material ? MATERIAL_LIBRARY[p.material] : undefined;
221
+ if (libEntry) {
222
+ const repeat = materialRepeatFor(p.kind, s, MATERIAL_TILE_UNIT[p.material] ?? 1);
223
+ void Promise.all([
224
+ loadMaterialTexture(libEntry.color, THREE.SRGBColorSpace),
225
+ loadMaterialTexture(libEntry.roughness, THREE.NoColorSpace),
226
+ ]).then(([colorTex, roughTex]) => {
227
+ // Cloned, not assigned directly — the cache shares ONE texture per
228
+ // url across every Part using this material, and `.repeat` is
229
+ // per-INSTANCE (a 1×1 block and a 10×10 platform using the same
230
+ // "brick" material need different repeat counts). Assigning the
231
+ // cached texture directly would make every Part sharing a material
232
+ // fight over the last-set repeat value — the exact "clones share
233
+ // materials" trap `Skin.ts` already documents, one level up (here
234
+ // it's the TEXTURE being shared, not the material).
235
+ const map = colorTex.clone();
236
+ const roughnessMap = roughTex.clone();
237
+ map.repeat.copy(repeat);
238
+ roughnessMap.repeat.copy(repeat);
239
+ map.needsUpdate = true;
240
+ roughnessMap.needsUpdate = true;
241
+ material.map = map;
242
+ material.roughnessMap = roughnessMap;
243
+ material.needsUpdate = true;
244
+ }).catch(() => { });
245
+ }
101
246
  return mesh;
102
247
  }
103
248
  /**
@@ -393,6 +393,35 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
393
393
  scale: { x: o.scale.x, y: o.scale.y, z: o.scale.z },
394
394
  };
395
395
  };
396
+ // ADR-044 — test-only readback of a Part's live material state: whether
397
+ // its async-loaded textures actually landed (`hasMap`/`hasRoughnessMap`),
398
+ // what repeat they resolved to (proves `materialRepeatFor`'s size-based
399
+ // math reached the live object, not just that SOME texture loaded), and
400
+ // the map's own source url (proves the right material NAME resolved to
401
+ // the right CDN file). No pixel-level visual check is possible without a
402
+ // real screenshot; this is what a test CAN assert without one.
403
+ globalThis.__umicatPrimitiveMaterial =
404
+ (entityId) => {
405
+ const o = objectByEntity.get(entityId);
406
+ if (!o || !(o instanceof THREE.Mesh))
407
+ return null;
408
+ const mat = o.material;
409
+ const geom = o.geometry;
410
+ const posAttr = geom.getAttribute('position');
411
+ const uvAttr = geom.getAttribute('uv');
412
+ return {
413
+ hasMap: !!mat.map,
414
+ hasRoughnessMap: !!mat.roughnessMap,
415
+ mapRepeat: mat.map ? { x: mat.map.repeat.x, y: mat.map.repeat.y } : null,
416
+ mapUrl: mat.map?.source?.data?.currentSrc
417
+ ?? mat.map?.source?.data?.src ?? null,
418
+ vertexCount: posAttr ? posAttr.count : 0,
419
+ // 0 (no uv attribute at all — the pre-ADR-044 state for wedge/
420
+ // corner-wedge) vs a real count, matching position's, is exactly
421
+ // the distinction this exists to prove.
422
+ uvCount: uvAttr ? uvAttr.count : 0,
423
+ };
424
+ };
396
425
  // Test-only — the MAIN camera's current pose, for the desktop camera
397
426
  // controls test suite (left-select/right-look/WASD/QE) to assert against
398
427
  // without hand-deriving projection math — same posture as every other
@@ -950,16 +979,36 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
950
979
  const authored = sceneData?.entities.find((e) => e.id === m.entityId);
951
980
  if (!authored?.primitive)
952
981
  return done(`entity '${m.entityId}' is not a primitive Part`);
953
- authored.primitive = { ...authored.primitive, ...m.patch.primitive };
982
+ // `material: null` (explicit clear) and `material: undefined` (key
983
+ // omitted, don't touch) both arrive through the same patch bag, but
984
+ // the STORED entity only ever has `material` present-with-a-string
985
+ // or absent — `null` is a wire-only sentinel, never written to disk.
986
+ const { material: materialPatch, ...restPatch } = m.patch.primitive;
987
+ const merged = { ...authored.primitive, ...restPatch };
988
+ if (materialPatch === null)
989
+ delete merged.material;
990
+ else if (materialPatch !== undefined)
991
+ merged.material = materialPatch;
992
+ authored.primitive = merged;
954
993
  const fresh = makePrimitive(authored);
955
994
  fresh.position.copy(object.position);
956
995
  fresh.quaternion.copy(object.quaternion);
957
996
  fresh.scale.copy(object.scale);
958
- fresh.castShadow = authored.primitive.kind !== 'plane';
997
+ fresh.castShadow = merged.kind !== 'plane';
959
998
  fresh.receiveShadow = true;
960
999
  if (object instanceof THREE.Mesh) {
961
1000
  object.geometry.dispose();
962
- (Array.isArray(object.material) ? object.material : [object.material]).forEach((mat) => mat.dispose());
1001
+ (Array.isArray(object.material) ? object.material : [object.material]).forEach((mat) => {
1002
+ // ADR-044 — `map`/`roughnessMap` on a Parts material are PER-
1003
+ // INSTANCE clones (`makePrimitive`'s own doc comment), never the
1004
+ // shared cached texture — `Material.dispose()` does not reach
1005
+ // into its own maps, so leaving this out would leak one texture
1006
+ // per rebuild (every resize/recolor of a materialed Part).
1007
+ const std = mat;
1008
+ std.map?.dispose();
1009
+ std.roughnessMap?.dispose();
1010
+ mat.dispose();
1011
+ });
963
1012
  }
964
1013
  scene?.remove(object);
965
1014
  scene?.add(fresh);
package/dist/scene3d.d.ts CHANGED
@@ -114,6 +114,17 @@ export interface Entity3D {
114
114
  kind: 'box' | 'sphere' | 'plane' | 'cylinder' | 'wedge' | 'corner-wedge';
115
115
  size?: Vec3;
116
116
  color?: string;
117
+ /**
118
+ * ADR-044 — a NAME from the built-in material library
119
+ * (`MATERIAL_LIBRARY` in `SceneLoader3D.ts`), not a URL: same
120
+ * convention as a model's `skin` (the SDK resolves it, nothing is
121
+ * authored per-scene). Omitted = flat `color` only, today's behavior
122
+ * — every Part authored before this field existed keeps rendering
123
+ * identically. `color` still applies when `material` is set (it
124
+ * tints the material's own color map, same as `MeshStandardMaterial`
125
+ * already does when both `color` and `map` are present).
126
+ */
127
+ material?: string;
117
128
  };
118
129
  collider?: Collider3D;
119
130
  /** Which clip to play on spawn, by SEMANTIC name — see `AnimationMap`. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@umicat/three-sdk",
3
- "version": "1.7.0",
3
+ "version": "1.8.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",