@umicat/three-sdk 1.21.0 → 1.23.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/CharacterController3D.d.ts +52 -1
- package/dist/CharacterController3D.js +100 -11
- package/dist/SceneLoader3D.d.ts +58 -0
- package/dist/SceneLoader3D.js +107 -20
- package/dist/index.d.ts +2 -2
- package/dist/index.js +1 -1
- package/dist/scene3d.d.ts +28 -0
- package/dist/scene3d.js +15 -4
- package/package.json +1 -1
|
@@ -24,6 +24,35 @@ export interface CharacterOptions {
|
|
|
24
24
|
y: number;
|
|
25
25
|
z: number;
|
|
26
26
|
};
|
|
27
|
+
/**
|
|
28
|
+
* ADR-050 — bodies of water as world-space AABBs, `max.y` being the surface.
|
|
29
|
+
* `LoadedScene3D.waters` is exactly this shape.
|
|
30
|
+
*
|
|
31
|
+
* **Everything water-related below is inert when this is empty**, which is
|
|
32
|
+
* the whole compatibility story: every 3D game already shipped keeps its
|
|
33
|
+
* current behaviour to the frame.
|
|
34
|
+
*/
|
|
35
|
+
waters?: {
|
|
36
|
+
min: {
|
|
37
|
+
x: number;
|
|
38
|
+
y: number;
|
|
39
|
+
z: number;
|
|
40
|
+
};
|
|
41
|
+
max: {
|
|
42
|
+
x: number;
|
|
43
|
+
y: number;
|
|
44
|
+
z: number;
|
|
45
|
+
};
|
|
46
|
+
}[];
|
|
47
|
+
/** How much of the character must be under before walking becomes swimming.
|
|
48
|
+
* Below it they are wading: still on the ground, just slower. */
|
|
49
|
+
swimAtSubmersion?: number;
|
|
50
|
+
/** Horizontal speed in water, as a fraction of `speed`. */
|
|
51
|
+
swimSpeedScale?: number;
|
|
52
|
+
/** Vertical speed when deliberately swimming up or down. */
|
|
53
|
+
swimVerticalSpeed?: number;
|
|
54
|
+
/** How hard the surface pulls a floating character back toward it. */
|
|
55
|
+
buoyancy?: number;
|
|
27
56
|
/** Upward speed at the moment of a jump. 0 disables jumping entirely. */
|
|
28
57
|
jumpSpeed?: number;
|
|
29
58
|
/**
|
|
@@ -45,11 +74,18 @@ export interface CharacterOptions {
|
|
|
45
74
|
jumpCut?: number;
|
|
46
75
|
}
|
|
47
76
|
/** What the character is doing, for animation. */
|
|
48
|
-
|
|
77
|
+
/** `swim` is ADR-050's addition. A game switching on this to choose an
|
|
78
|
+
* animation clip simply has no case for it and falls through to its default —
|
|
79
|
+
* additive, and unreachable in any scene with no water. */
|
|
80
|
+
export type CharacterState = 'idle' | 'walk' | 'jump' | 'fall' | 'swim';
|
|
49
81
|
/** Per-frame input. `jump` is the button's CURRENT state, not an event —
|
|
50
82
|
* edge detection, coyote time and buffering all live in the controller. */
|
|
51
83
|
export interface CharacterInput {
|
|
52
84
|
jump?: boolean;
|
|
85
|
+
/** ADR-050 — swim downward. Ignored out of water. `jump` doubles as swim-up,
|
|
86
|
+
* so one button covers the common case and this is only needed by a game
|
|
87
|
+
* that wants real diving. */
|
|
88
|
+
descend?: boolean;
|
|
53
89
|
}
|
|
54
90
|
/**
|
|
55
91
|
* A kinematic character: walks, collides with walls, climbs steps, falls.
|
|
@@ -79,6 +115,8 @@ export declare class CharacterController3D {
|
|
|
79
115
|
private jumping;
|
|
80
116
|
private jumpCutApplied;
|
|
81
117
|
private _state;
|
|
118
|
+
/** ADR-050 — recomputed every frame; false in every scene with no water. */
|
|
119
|
+
private swimming;
|
|
82
120
|
constructor(world: any, RAPIER: RapierRuntime, options?: CharacterOptions);
|
|
83
121
|
get grounded(): boolean;
|
|
84
122
|
/** What the character is doing — map this to a clip rather than deriving it
|
|
@@ -123,6 +161,19 @@ export declare class CharacterController3D {
|
|
|
123
161
|
x: number;
|
|
124
162
|
z: number;
|
|
125
163
|
}, input?: CharacterInput): void;
|
|
164
|
+
/** Capsule height, feet to crown. */
|
|
165
|
+
private height;
|
|
166
|
+
/**
|
|
167
|
+
* Surface of the water the character is in, or -Infinity when they are in
|
|
168
|
+
* none. The HIGHEST qualifying surface wins, so overlapping volumes behave
|
|
169
|
+
* like one body rather than like whichever was listed first.
|
|
170
|
+
*/
|
|
171
|
+
private surfaceY;
|
|
172
|
+
/** How much of the character is under water, 0..1. */
|
|
173
|
+
private submersion;
|
|
174
|
+
/** ADR-050 — 0 out of water, 1 fully under. What a game reads to drive a
|
|
175
|
+
* breath meter, a splash, or a camera tint. */
|
|
176
|
+
get waterDepth(): number;
|
|
126
177
|
/** Copy the simulated position onto the rendered object. */
|
|
127
178
|
syncTo(object: THREE.Object3D, yOffset?: number): void;
|
|
128
179
|
/** Face the direction of travel; ignores tiny inputs so idle doesn't spin. */
|
|
@@ -23,6 +23,8 @@ export class CharacterController3D {
|
|
|
23
23
|
this.jumping = false;
|
|
24
24
|
this.jumpCutApplied = false;
|
|
25
25
|
this._state = 'idle';
|
|
26
|
+
/** ADR-050 — recomputed every frame; false in every scene with no water. */
|
|
27
|
+
this.swimming = false;
|
|
26
28
|
this.opts = {
|
|
27
29
|
halfHeight: options.halfHeight ?? 0.5,
|
|
28
30
|
radius: options.radius ?? 0.35,
|
|
@@ -41,6 +43,13 @@ export class CharacterController3D {
|
|
|
41
43
|
coyoteTime: options.coyoteTime ?? 0.12,
|
|
42
44
|
jumpBuffer: options.jumpBuffer ?? 0.12,
|
|
43
45
|
jumpCut: options.jumpCut ?? 0.45,
|
|
46
|
+
waters: options.waters ?? [],
|
|
47
|
+
// 0.55 — a little past the waist. Below it you are wading and still
|
|
48
|
+
// walking; above it your feet no longer reach anything useful.
|
|
49
|
+
swimAtSubmersion: options.swimAtSubmersion ?? 0.55,
|
|
50
|
+
swimSpeedScale: options.swimSpeedScale ?? 0.55,
|
|
51
|
+
swimVerticalSpeed: options.swimVerticalSpeed ?? 2.0,
|
|
52
|
+
buoyancy: options.buoyancy ?? 6,
|
|
44
53
|
};
|
|
45
54
|
const p = options.position ?? { x: 0, y: 2, z: 0 };
|
|
46
55
|
this.body = world.createRigidBody(RAPIER.RigidBodyDesc.kinematicPositionBased().setTranslation(p.x, p.y, p.z));
|
|
@@ -103,10 +112,11 @@ export class CharacterController3D {
|
|
|
103
112
|
*/
|
|
104
113
|
update(dt, dir, input = {}) {
|
|
105
114
|
const len = Math.hypot(dir.x, dir.z);
|
|
106
|
-
|
|
107
|
-
|
|
115
|
+
let nx = len > 0 ? (dir.x / len) * this.opts.speed * dt : 0;
|
|
116
|
+
let nz = len > 0 ? (dir.z / len) * this.opts.speed * dt : 0;
|
|
108
117
|
const grounded = this.grounded;
|
|
109
118
|
const jumpHeld = input.jump === true;
|
|
119
|
+
const descendHeld = input.descend === true;
|
|
110
120
|
const jumpPressed = jumpHeld && !this.jumpWasHeld;
|
|
111
121
|
this.jumpWasHeld = jumpHeld;
|
|
112
122
|
// Both timers count DOWN in real time, so they behave the same at 30fps and
|
|
@@ -114,16 +124,58 @@ export class CharacterController3D {
|
|
|
114
124
|
// the machine.
|
|
115
125
|
this.coyoteLeft = grounded ? this.opts.coyoteTime : Math.max(0, this.coyoteLeft - dt);
|
|
116
126
|
this.bufferLeft = jumpPressed ? this.opts.jumpBuffer : Math.max(0, this.bufferLeft - dt);
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
127
|
+
// ── ADR-050: water ───────────────────────────────────────────────────
|
|
128
|
+
//
|
|
129
|
+
// Decided BEFORE gravity, and that order is load-bearing. The grounded
|
|
130
|
+
// branch resets `verticalVelocity` to `-gravity * dt` EVERY frame; with
|
|
131
|
+
// this running after it, the damped buoyancy could only close ~13% of the
|
|
132
|
+
// gap per frame and the two cancelled almost exactly. The character
|
|
133
|
+
// floated — stably, and 0.18 units below where it had been asked to float,
|
|
134
|
+
// with nothing in the numbers to say why. Swimming now owns vertical
|
|
135
|
+
// motion outright instead of negotiating with gravity for it.
|
|
136
|
+
//
|
|
137
|
+
// Submersion comes from the capsule's own extent rather than from a
|
|
138
|
+
// trigger volume: a sensor would require a dynamic body, and this
|
|
139
|
+
// character is kinematic on purpose.
|
|
140
|
+
const sub = this.submersion();
|
|
141
|
+
this.swimming = sub >= this.opts.swimAtSubmersion;
|
|
142
|
+
if (this.swimming) {
|
|
143
|
+
const feet = this.body.translation().y - (this.opts.halfHeight + this.opts.radius);
|
|
144
|
+
const head = feet + this.height();
|
|
145
|
+
// Aim for the waterline from just below, so a character with no input
|
|
146
|
+
// bobs under the surface rather than popping out of it.
|
|
147
|
+
const want = (this.surfaceY() - 0.15) - head;
|
|
148
|
+
const v = this.opts.swimVerticalSpeed;
|
|
149
|
+
const rise = jumpHeld ? v : descendHeld ? -v
|
|
150
|
+
: Math.max(-v, Math.min(v, want * this.opts.buoyancy));
|
|
151
|
+
// Damped rather than assigned, or every input change is a step in
|
|
152
|
+
// velocity and the character reads as weightless instead of buoyant.
|
|
153
|
+
this.verticalVelocity += (rise - this.verticalVelocity) * Math.min(1, 8 * dt);
|
|
121
154
|
this.jumping = false;
|
|
155
|
+
this.coyoteLeft = 0;
|
|
156
|
+
this.bufferLeft = 0;
|
|
157
|
+
nx *= this.opts.swimSpeedScale;
|
|
158
|
+
nz *= this.opts.swimSpeedScale;
|
|
122
159
|
}
|
|
123
160
|
else {
|
|
124
|
-
|
|
161
|
+
if (sub > 0) {
|
|
162
|
+
// Wading: still walking, just slowed in proportion to the depth.
|
|
163
|
+
const drag = 1 - 0.5 * (sub / this.opts.swimAtSubmersion);
|
|
164
|
+
nx *= drag;
|
|
165
|
+
nz *= drag;
|
|
166
|
+
}
|
|
167
|
+
if (grounded) {
|
|
168
|
+
// Small constant bias, not accumulated gravity: enough for
|
|
169
|
+
// snap-to-ground to hold contact over stairs and slopes without
|
|
170
|
+
// pinning the character.
|
|
171
|
+
this.verticalVelocity = -this.opts.gravity * dt;
|
|
172
|
+
this.jumping = false;
|
|
173
|
+
}
|
|
174
|
+
else {
|
|
175
|
+
this.verticalVelocity -= this.opts.gravity * dt;
|
|
176
|
+
}
|
|
125
177
|
}
|
|
126
|
-
if (this.opts.jumpSpeed > 0 && this.bufferLeft > 0 && this.coyoteLeft > 0 && !this.jumping) {
|
|
178
|
+
if (!this.swimming && this.opts.jumpSpeed > 0 && this.bufferLeft > 0 && this.coyoteLeft > 0 && !this.jumping) {
|
|
127
179
|
this.verticalVelocity = this.opts.jumpSpeed;
|
|
128
180
|
this.jumping = true;
|
|
129
181
|
this.jumpCutApplied = false;
|
|
@@ -148,10 +200,47 @@ export class CharacterController3D {
|
|
|
148
200
|
// State is read AFTER the move so a landing this frame reads as landed.
|
|
149
201
|
// Note `grounded` above is the PRE-move value — the two differ exactly on
|
|
150
202
|
// the frames that matter for animation.
|
|
151
|
-
this._state = this.
|
|
152
|
-
? (len > 0 ? 'walk' : 'idle')
|
|
153
|
-
|
|
203
|
+
this._state = this.swimming ? 'swim'
|
|
204
|
+
: this.grounded ? (len > 0 ? 'walk' : 'idle')
|
|
205
|
+
: (this.verticalVelocity > 0 ? 'jump' : 'fall');
|
|
206
|
+
}
|
|
207
|
+
/** Capsule height, feet to crown. */
|
|
208
|
+
height() { return (this.opts.halfHeight + this.opts.radius) * 2; }
|
|
209
|
+
/**
|
|
210
|
+
* Surface of the water the character is in, or -Infinity when they are in
|
|
211
|
+
* none. The HIGHEST qualifying surface wins, so overlapping volumes behave
|
|
212
|
+
* like one body rather than like whichever was listed first.
|
|
213
|
+
*/
|
|
214
|
+
surfaceY() {
|
|
215
|
+
const t = this.body.translation();
|
|
216
|
+
const feet = t.y - (this.opts.halfHeight + this.opts.radius);
|
|
217
|
+
let best = -Infinity;
|
|
218
|
+
for (const w of this.opts.waters) {
|
|
219
|
+
if (t.x < w.min.x || t.x > w.max.x || t.z < w.min.z || t.z > w.max.z)
|
|
220
|
+
continue;
|
|
221
|
+
// The feet have to be inside the volume vertically too: standing on a
|
|
222
|
+
// bridge over a river is not swimming, and neither is walking under an
|
|
223
|
+
// aqueduct.
|
|
224
|
+
if (feet > w.max.y || feet < w.min.y)
|
|
225
|
+
continue;
|
|
226
|
+
if (w.max.y > best)
|
|
227
|
+
best = w.max.y;
|
|
228
|
+
}
|
|
229
|
+
return best;
|
|
230
|
+
}
|
|
231
|
+
/** How much of the character is under water, 0..1. */
|
|
232
|
+
submersion() {
|
|
233
|
+
if (this.opts.waters.length === 0)
|
|
234
|
+
return 0; // the usual path, and free
|
|
235
|
+
const surface = this.surfaceY();
|
|
236
|
+
if (surface === -Infinity)
|
|
237
|
+
return 0;
|
|
238
|
+
const feet = this.body.translation().y - (this.opts.halfHeight + this.opts.radius);
|
|
239
|
+
return Math.max(0, Math.min(1, (surface - feet) / this.height()));
|
|
154
240
|
}
|
|
241
|
+
/** ADR-050 — 0 out of water, 1 fully under. What a game reads to drive a
|
|
242
|
+
* breath meter, a splash, or a camera tint. */
|
|
243
|
+
get waterDepth() { return this.submersion(); }
|
|
155
244
|
/** Copy the simulated position onto the rendered object. */
|
|
156
245
|
syncTo(object, yOffset = 0) {
|
|
157
246
|
const t = this.body.translation();
|
package/dist/SceneLoader3D.d.ts
CHANGED
|
@@ -40,6 +40,10 @@ export interface LoadedScene3D {
|
|
|
40
40
|
attachments: Map<string, WornMap>;
|
|
41
41
|
/** Entity id → rigid body, when physics was supplied. */
|
|
42
42
|
bodies: Map<string, any>;
|
|
43
|
+
/** ADR-050 — every body of water, world-space. Hand it to
|
|
44
|
+
* `CharacterController3D` to get buoyancy and swimming; ignore it and
|
|
45
|
+
* water is purely decorative. */
|
|
46
|
+
waters: WaterVolume3D[];
|
|
43
47
|
world?: any;
|
|
44
48
|
/** Where the follow camera is looking from, in radians. Feed it to
|
|
45
49
|
* `Input3D.direction(yaw)` — once the camera can turn, movement that ignores
|
|
@@ -55,6 +59,52 @@ export interface LoadedScene3D {
|
|
|
55
59
|
dispose(): void;
|
|
56
60
|
}
|
|
57
61
|
export declare function applyTransform(obj: THREE.Object3D, e: Entity3D): void;
|
|
62
|
+
/**
|
|
63
|
+
* ADR-044 — the built-in Parts material library. A NAME resolves to two
|
|
64
|
+
* CDN-hosted maps (Color + Roughness only — see the ADR's own "game-grade,
|
|
65
|
+
* not showcase-grade" scoping for why Normal/Displacement/AO aren't here),
|
|
66
|
+
* re-hosted (not linked to the source) under the platform-wide, already-
|
|
67
|
+
* public `platform/` S3 prefix (`cdn.umicat.ai/platform/...` — the same
|
|
68
|
+
* prefix `platform/canonical-rig/v1/...` already uses for the Model
|
|
69
|
+
* Editor's auto-rig skeleton; no bucket-policy change was needed). Sourced
|
|
70
|
+
* from ambientCG (CC0), reprocessed to 512×512 JPEG.
|
|
71
|
+
*/
|
|
72
|
+
/**
|
|
73
|
+
* ADR-050 — the built-in heightmap library: terrain shapes a creator can pick
|
|
74
|
+
* without having to author or import an image first.
|
|
75
|
+
*
|
|
76
|
+
* **Unlike `MATERIAL_LIBRARY`, this is a convenience layer, not a fence.**
|
|
77
|
+
* `Heightfield3D.assetId` resolves against the project's own
|
|
78
|
+
* `manifest.heightmaps`, so any image a project ships already works; these
|
|
79
|
+
* entries are simply pre-registered ones a UI can offer. Materials are the
|
|
80
|
+
* opposite — a closed table, with "use your own texture" explicitly out of
|
|
81
|
+
* scope in ADR-044. The difference is deliberate: a heightmap is a shape
|
|
82
|
+
* someone will want to author, a material is a surface we curate.
|
|
83
|
+
*
|
|
84
|
+
* Shape-first rather than noise-first, and deliberately NOT real elevation
|
|
85
|
+
* data. Real DEM tiles were sourced, licence-checked and tried (SRTM, public
|
|
86
|
+
* domain) and read badly: a casual scene is 20-60 units across, where a real
|
|
87
|
+
* landscape's hundreds of drainage channels become visual noise with no shape
|
|
88
|
+
* you can point at. These eight each have one readable idea.
|
|
89
|
+
*
|
|
90
|
+
* They differ in CHARACTER, not amplitude — amplitude is what `size.y`
|
|
91
|
+
* already controls, so three heightmaps differing only in height would be
|
|
92
|
+
* three copies of one preset.
|
|
93
|
+
*/
|
|
94
|
+
export declare const HEIGHTMAP_LIBRARY: Record<string, string>;
|
|
95
|
+
/**
|
|
96
|
+
* Where a `Heightfield3D.assetId` actually lives.
|
|
97
|
+
*
|
|
98
|
+
* A project's own `manifest.heightmaps` wins over a library name of the same
|
|
99
|
+
* id, so a creator can override `hills` by registering their own — the library
|
|
100
|
+
* is a default, never a reservation. Throws naming every id that WOULD have
|
|
101
|
+
* worked, because "no heightmap 'hils'" with no list is the single most
|
|
102
|
+
* annoying asset error there is.
|
|
103
|
+
*/
|
|
104
|
+
export declare function heightmapUrl(assetId: string, manifest: Manifest3D, assetBase?: string): string;
|
|
105
|
+
/** The size a preset is meant to be dropped at. One value for all eight,
|
|
106
|
+
* which only works because they differ in character rather than height. */
|
|
107
|
+
export declare const HEIGHTMAP_DEFAULT_SIZE: Vec3;
|
|
58
108
|
export declare const MATERIAL_LIBRARY: Record<string, {
|
|
59
109
|
color: string;
|
|
60
110
|
roughness: string;
|
|
@@ -70,6 +120,14 @@ export declare const MATERIAL_LIBRARY: Record<string, {
|
|
|
70
120
|
* when they drag one in.
|
|
71
121
|
*/
|
|
72
122
|
export declare function heightfieldGeometry(heights: Float32Array, n: number, size: Vec3): THREE.BufferGeometry;
|
|
123
|
+
/**
|
|
124
|
+
* ADR-050 — a water volume in WORLD space, as the character controller needs
|
|
125
|
+
* it: an axis-aligned box whose `max.y` is the surface.
|
|
126
|
+
*/
|
|
127
|
+
export interface WaterVolume3D {
|
|
128
|
+
min: Vec3;
|
|
129
|
+
max: Vec3;
|
|
130
|
+
}
|
|
73
131
|
/**
|
|
74
132
|
* ADR-050 — build one heightfield's surface and its collider grid.
|
|
75
133
|
*
|
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` },
|
|
@@ -307,6 +357,37 @@ export function heightfieldGeometry(heights, n, size) {
|
|
|
307
357
|
geom.computeVertexNormals();
|
|
308
358
|
return geom;
|
|
309
359
|
}
|
|
360
|
+
/**
|
|
361
|
+
* The visible surface of a body of water: one translucent quad at the top of
|
|
362
|
+
* the volume.
|
|
363
|
+
*
|
|
364
|
+
* `depthWrite` off and `DoubleSide` on, both load-bearing. Writing depth would
|
|
365
|
+
* make the water hide everything behind it that draws later — the riverbed,
|
|
366
|
+
* anything submerged — which reads as water that is somehow opaque from one
|
|
367
|
+
* angle only. Single-sided would make it vanish the moment the camera dips
|
|
368
|
+
* below the surface, exactly when a swimming player is looking at it.
|
|
369
|
+
*/
|
|
370
|
+
function makeWaterSurface(w) {
|
|
371
|
+
const geom = new THREE.PlaneGeometry(w.size.x, w.size.z);
|
|
372
|
+
geom.rotateX(-Math.PI / 2);
|
|
373
|
+
const mesh = new THREE.Mesh(geom, new THREE.MeshStandardMaterial({
|
|
374
|
+
color: w.color ?? '#2f7fb5',
|
|
375
|
+
transparent: true,
|
|
376
|
+
opacity: w.opacity ?? 0.72,
|
|
377
|
+
depthWrite: false,
|
|
378
|
+
side: THREE.DoubleSide,
|
|
379
|
+
roughness: 0.15,
|
|
380
|
+
metalness: 0.0,
|
|
381
|
+
}));
|
|
382
|
+
// Water neither casts nor receives: a translucent sheet in a shadow map
|
|
383
|
+
// darkens everything under it as if it were solid, which is the opposite of
|
|
384
|
+
// what water does to a riverbed.
|
|
385
|
+
mesh.castShadow = false;
|
|
386
|
+
mesh.receiveShadow = false;
|
|
387
|
+
// Drawn after opaque geometry so blending has something to blend with.
|
|
388
|
+
mesh.renderOrder = 1;
|
|
389
|
+
return mesh;
|
|
390
|
+
}
|
|
310
391
|
const heightmapPixelCache = new Map();
|
|
311
392
|
/**
|
|
312
393
|
* Decode a heightmap image to normalised 0..1 luminance, row-major.
|
|
@@ -357,12 +438,7 @@ function heightmapPixels(url) {
|
|
|
357
438
|
* same heightmap costs one fetch.
|
|
358
439
|
*/
|
|
359
440
|
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));
|
|
441
|
+
const px = await heightmapPixels(heightmapUrl(hf.assetId, manifest, opts.assetBase));
|
|
366
442
|
const seg = heightfieldSegments(hf);
|
|
367
443
|
const heights = resampleHeights(px.data, px.width, px.height, seg.render);
|
|
368
444
|
const material = new THREE.MeshStandardMaterial({ color: hf.color ?? '#ffffff' });
|
|
@@ -642,22 +718,19 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
|
|
|
642
718
|
// ADR-050 — heightmaps are fetched and decoded up front, same contract the
|
|
643
719
|
// models above follow: a caller that awaits `loadScene3D` gets a finished
|
|
644
720
|
// scene, not one whose terrain pops in flat and then rises a frame later.
|
|
645
|
-
|
|
646
|
-
|
|
721
|
+
// Nothing is stored from the prefetch — `heightmapPixels` caches per url, so
|
|
722
|
+
// this exists purely to run the decodes in PARALLEL and to make an unknown
|
|
723
|
+
// id fail at load. `makeHeightfield` then hits warm cache entries.
|
|
647
724
|
const heightmapJobs = [];
|
|
725
|
+
const prefetched = new Set();
|
|
648
726
|
for (const e of scene3d.entities) {
|
|
649
|
-
if (!e.heightfield)
|
|
727
|
+
if (!e.heightfield || prefetched.has(e.heightfield.assetId))
|
|
650
728
|
continue;
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
}
|
|
656
|
-
if (heightmapPixelsById.has(entry.id))
|
|
657
|
-
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); }));
|
|
729
|
+
prefetched.add(e.heightfield.assetId);
|
|
730
|
+
// Resolved through the SAME function `makeHeightfield` uses — which is
|
|
731
|
+
// also what makes an unknown id fail HERE, at load, naming every id that
|
|
732
|
+
// would have worked, rather than per-entity later.
|
|
733
|
+
heightmapJobs.push(heightmapPixels(heightmapUrl(e.heightfield.assetId, manifest, opts.assetBase)).then(() => { }));
|
|
661
734
|
}
|
|
662
735
|
if (heightmapJobs.length)
|
|
663
736
|
await Promise.all(heightmapJobs);
|
|
@@ -676,6 +749,10 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
|
|
|
676
749
|
/** ADR-050 — each heightfield's COLLIDER grid, kept for the physics pass
|
|
677
750
|
* below (which runs after every entity exists). */
|
|
678
751
|
const heightfieldGrids = new Map();
|
|
752
|
+
/** ADR-050 — every water volume in the scene, in world space, for the
|
|
753
|
+
* character controller. Collected here rather than derived later because
|
|
754
|
+
* only this pass knows each entity's authored transform. */
|
|
755
|
+
const waters = [];
|
|
679
756
|
const mixers = [];
|
|
680
757
|
const mixerFor = new Map();
|
|
681
758
|
const clips = new Map();
|
|
@@ -769,6 +846,16 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
|
|
|
769
846
|
.then((worn) => { attachments.set(e.id, worn); }));
|
|
770
847
|
}
|
|
771
848
|
}
|
|
849
|
+
else if (e.water) {
|
|
850
|
+
const w = e.water;
|
|
851
|
+
obj = makeWaterSurface(w);
|
|
852
|
+
const p = e.transform.position;
|
|
853
|
+
// The surface is AT the origin and the volume hangs below it.
|
|
854
|
+
waters.push({
|
|
855
|
+
min: { x: p.x - w.size.x / 2, y: p.y - w.size.y, z: p.z - w.size.z / 2 },
|
|
856
|
+
max: { x: p.x + w.size.x / 2, y: p.y, z: p.z + w.size.z / 2 },
|
|
857
|
+
});
|
|
858
|
+
}
|
|
772
859
|
else if (e.heightfield) {
|
|
773
860
|
if (e.attachments?.length) {
|
|
774
861
|
throw new Error(`entity '${e.id}' has attachments but no model to hang them on`);
|
|
@@ -969,7 +1056,7 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
|
|
|
969
1056
|
? entities.get(scene3d.camera.target) : undefined;
|
|
970
1057
|
const want = new THREE.Vector3();
|
|
971
1058
|
return {
|
|
972
|
-
scene, camera, entities, mixers, mixerFor, clips, attachments, bodies, world,
|
|
1059
|
+
scene, camera, entities, mixers, mixerFor, clips, attachments, bodies, world, waters,
|
|
973
1060
|
get cameraYaw() { return camYaw; },
|
|
974
1061
|
get cameraPitch() { return camPitch; },
|
|
975
1062
|
orbit(dYaw, dPitch) {
|
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';
|
|
@@ -26,7 +26,7 @@ export type { Hud3DRuntimeHandle } from './hud3d/HudRuntime3D.js';
|
|
|
26
26
|
export { resolveAnchor3D } from './hud3d/anchor3d.js';
|
|
27
27
|
export { setHudBinding3D, getHudBinding3D } from './hud3d/HudDynamicBinding3D.js';
|
|
28
28
|
export type { Attachment } from './Sockets.js';
|
|
29
|
-
export type { LoadedScene3D, LoadSceneOptions } from './SceneLoader3D.js';
|
|
29
|
+
export type { LoadedScene3D, LoadSceneOptions, WaterVolume3D } from './SceneLoader3D.js';
|
|
30
30
|
export { installDualScreen, viewportSize } from './DualScreen3D.js';
|
|
31
31
|
export type { FoldLayout, FoldRect } from '@umicat/platform-sdk/fold/FoldModule.js';
|
|
32
32
|
export { ORIENTATION_DIMENSIONS } from '@umicat/platform-sdk/orientation.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
|
@@ -150,6 +150,32 @@ export interface Heightfield3D {
|
|
|
150
150
|
/** Flat colour, multiplied with the material the way a Part's is. */
|
|
151
151
|
color?: string;
|
|
152
152
|
}
|
|
153
|
+
/**
|
|
154
|
+
* ADR-050 decision 3 — a body of water.
|
|
155
|
+
*
|
|
156
|
+
* **Deliberately decoupled from terrain**, which is the one thing Roblox gets
|
|
157
|
+
* structurally wrong here: there, water IS a terrain material, so a pool
|
|
158
|
+
* cannot exist without terrain and terrain cannot exist without carrying the
|
|
159
|
+
* water system with it. Here water is its own entity. A pool on flat ground
|
|
160
|
+
* works in a scene with no heightfield in it at all, and a heightfield works
|
|
161
|
+
* with no water.
|
|
162
|
+
*
|
|
163
|
+
* The SURFACE sits at the entity's own origin and the volume hangs BELOW it —
|
|
164
|
+
* the mirror of a heightfield, whose base sits at its origin and rises. Both
|
|
165
|
+
* choices are for the same reason: the number an author actually thinks about.
|
|
166
|
+
* For terrain that is "where the ground starts"; for water it is "what the
|
|
167
|
+
* water level is", and `y = 2` should mean a water level of 2 without having
|
|
168
|
+
* to add half the depth.
|
|
169
|
+
*/
|
|
170
|
+
export interface Water3D {
|
|
171
|
+
/** Extent of the volume: `x`/`z` across the surface, `y` downward from it. */
|
|
172
|
+
size: Vec3;
|
|
173
|
+
color?: string;
|
|
174
|
+
/** 0 is invisible, 1 is opaque. Defaults to 0.72 — enough to read as water
|
|
175
|
+
* while still showing what is under it, which is what makes a shoreline
|
|
176
|
+
* legible. */
|
|
177
|
+
opacity?: number;
|
|
178
|
+
}
|
|
153
179
|
export interface Entity3D {
|
|
154
180
|
/** Stable, authored, unique within the scene. */
|
|
155
181
|
id: string;
|
|
@@ -211,6 +237,8 @@ export interface Entity3D {
|
|
|
211
237
|
/** ADR-050 — a heightmap-driven terrain surface. Mutually exclusive with
|
|
212
238
|
* `primitive` and `modelAssetId`: an entity is one kind of thing. */
|
|
213
239
|
heightfield?: Heightfield3D;
|
|
240
|
+
/** ADR-050 — a body of water. Also mutually exclusive with the above. */
|
|
241
|
+
water?: Water3D;
|
|
214
242
|
collider?: Collider3D;
|
|
215
243
|
/**
|
|
216
244
|
* ADR-047 — marks this Part for SUBTRACTION the next time it (or a
|
package/dist/scene3d.js
CHANGED
|
@@ -304,11 +304,22 @@ export function validateScene(scene) {
|
|
|
304
304
|
else if (ids.has(e.id))
|
|
305
305
|
problems.push(`duplicate entity id '${e.id}'`);
|
|
306
306
|
ids.add(e.id);
|
|
307
|
-
|
|
308
|
-
|
|
307
|
+
const kinds = [e.modelAssetId && 'model', e.primitive && 'primitive',
|
|
308
|
+
e.heightfield && 'heightfield', e.water && 'water'].filter(Boolean);
|
|
309
|
+
if (kinds.length === 0) {
|
|
310
|
+
problems.push(`entity '${e.id}' is nothing — no model, primitive, heightfield or water, so it would render nothing`);
|
|
309
311
|
}
|
|
310
|
-
if (
|
|
311
|
-
problems.push(`entity '${e.id}' is
|
|
312
|
+
if (kinds.length > 1) {
|
|
313
|
+
problems.push(`entity '${e.id}' is ${kinds.join(' and ')} at once — an entity can only be one kind of thing`);
|
|
314
|
+
}
|
|
315
|
+
if (e.water) {
|
|
316
|
+
const w = e.water;
|
|
317
|
+
if (!w.size || !(w.size.x > 0) || !(w.size.y > 0) || !(w.size.z > 0)) {
|
|
318
|
+
problems.push(`entity '${e.id}' has water with a non-positive size — a volume needs all three`);
|
|
319
|
+
}
|
|
320
|
+
if (w.opacity !== undefined && (w.opacity < 0 || w.opacity > 1)) {
|
|
321
|
+
problems.push(`entity '${e.id}' water opacity must be between 0 and 1`);
|
|
322
|
+
}
|
|
312
323
|
}
|
|
313
324
|
if (e.heightfield) {
|
|
314
325
|
const h = e.heightfield;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@umicat/three-sdk",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.23.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",
|