@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.
- package/dist/SceneLoader3D.d.ts +4 -0
- package/dist/SceneLoader3D.js +150 -5
- package/dist/editor/EditorDesignPlayer3D.js +52 -3
- package/dist/scene3d.d.ts +11 -0
- package/package.json +1 -1
package/dist/SceneLoader3D.d.ts
CHANGED
|
@@ -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.
|
package/dist/SceneLoader3D.js
CHANGED
|
@@ -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
|
|
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
|
-
|
|
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 =
|
|
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) =>
|
|
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.
|
|
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",
|