@umicat/three-sdk 1.22.0 → 1.24.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 +23 -0
- package/dist/SceneLoader3D.js +46 -1
- package/dist/editor/EditorDesignPlayer3D.js +19 -1
- 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
|
|
@@ -116,6 +120,25 @@ export declare const MATERIAL_LIBRARY: Record<string, {
|
|
|
116
120
|
* when they drag one in.
|
|
117
121
|
*/
|
|
118
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
|
+
}
|
|
131
|
+
/**
|
|
132
|
+
* The visible surface of a body of water: one translucent quad at the top of
|
|
133
|
+
* the volume.
|
|
134
|
+
*
|
|
135
|
+
* `depthWrite` off and `DoubleSide` on, both load-bearing. Writing depth would
|
|
136
|
+
* make the water hide everything behind it that draws later — the riverbed,
|
|
137
|
+
* anything submerged — which reads as water that is somehow opaque from one
|
|
138
|
+
* angle only. Single-sided would make it vanish the moment the camera dips
|
|
139
|
+
* below the surface, exactly when a swimming player is looking at it.
|
|
140
|
+
*/
|
|
141
|
+
export declare function makeWaterSurface(w: NonNullable<Entity3D['water']>): THREE.Mesh;
|
|
119
142
|
/**
|
|
120
143
|
* ADR-050 — build one heightfield's surface and its collider grid.
|
|
121
144
|
*
|
package/dist/SceneLoader3D.js
CHANGED
|
@@ -357,6 +357,37 @@ export function heightfieldGeometry(heights, n, size) {
|
|
|
357
357
|
geom.computeVertexNormals();
|
|
358
358
|
return geom;
|
|
359
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
|
+
export 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
|
+
}
|
|
360
391
|
const heightmapPixelCache = new Map();
|
|
361
392
|
/**
|
|
362
393
|
* Decode a heightmap image to normalised 0..1 luminance, row-major.
|
|
@@ -718,6 +749,10 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
|
|
|
718
749
|
/** ADR-050 — each heightfield's COLLIDER grid, kept for the physics pass
|
|
719
750
|
* below (which runs after every entity exists). */
|
|
720
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 = [];
|
|
721
756
|
const mixers = [];
|
|
722
757
|
const mixerFor = new Map();
|
|
723
758
|
const clips = new Map();
|
|
@@ -811,6 +846,16 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
|
|
|
811
846
|
.then((worn) => { attachments.set(e.id, worn); }));
|
|
812
847
|
}
|
|
813
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
|
+
}
|
|
814
859
|
else if (e.heightfield) {
|
|
815
860
|
if (e.attachments?.length) {
|
|
816
861
|
throw new Error(`entity '${e.id}' has attachments but no model to hang them on`);
|
|
@@ -1011,7 +1056,7 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
|
|
|
1011
1056
|
? entities.get(scene3d.camera.target) : undefined;
|
|
1012
1057
|
const want = new THREE.Vector3();
|
|
1013
1058
|
return {
|
|
1014
|
-
scene, camera, entities, mixers, mixerFor, clips, attachments, bodies, world,
|
|
1059
|
+
scene, camera, entities, mixers, mixerFor, clips, attachments, bodies, world, waters,
|
|
1015
1060
|
get cameraYaw() { return camYaw; },
|
|
1016
1061
|
get cameraPitch() { return camPitch; },
|
|
1017
1062
|
orbit(dYaw, dPitch) {
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import * as THREE from 'three';
|
|
2
2
|
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
|
|
3
|
-
import { loadScene3D, loadModelAsset, makePrimitive, makeHeightfield, applyTransform } from '../SceneLoader3D.js';
|
|
3
|
+
import { loadScene3D, loadModelAsset, makePrimitive, makeHeightfield, makeWaterSurface, applyTransform } from '../SceneLoader3D.js';
|
|
4
4
|
import { applySkin } from '../Skin.js';
|
|
5
5
|
import { applyAttachments } from '../Attachments.js';
|
|
6
6
|
import { singleModelManifest, defaultColliderForPrimitive, groundRestOffset } from '../scene3d.js';
|
|
@@ -1756,6 +1756,21 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
1756
1756
|
disposeMeshInPlace(object);
|
|
1757
1757
|
object = swapEntityObject(object, fresh, m.entityId);
|
|
1758
1758
|
}
|
|
1759
|
+
if (m.patch?.water !== undefined) {
|
|
1760
|
+
// Colour and opacity could be patched in place, size cannot — one
|
|
1761
|
+
// rebuild path rather than two, same call this scene's load and the
|
|
1762
|
+
// live create both go through.
|
|
1763
|
+
const authored = sceneData?.entities.find((e) => e.id === m.entityId);
|
|
1764
|
+
if (!authored?.water)
|
|
1765
|
+
return done(`entity '${m.entityId}' is not water`);
|
|
1766
|
+
authored.water = { ...authored.water, ...m.patch.water };
|
|
1767
|
+
const fresh = makeWaterSurface(authored.water);
|
|
1768
|
+
fresh.position.copy(object.position);
|
|
1769
|
+
fresh.quaternion.copy(object.quaternion);
|
|
1770
|
+
fresh.scale.copy(object.scale);
|
|
1771
|
+
disposeMeshInPlace(object);
|
|
1772
|
+
object = swapEntityObject(object, fresh, m.entityId);
|
|
1773
|
+
}
|
|
1759
1774
|
if (m.patch?.heightfield !== undefined) {
|
|
1760
1775
|
// ADR-050 — a heightfield has no incremental edit: every patchable
|
|
1761
1776
|
// field (size, either resolution, material, colour) changes the vertex
|
|
@@ -1959,6 +1974,9 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
1959
1974
|
object.castShadow = e.primitive.kind !== 'plane';
|
|
1960
1975
|
object.receiveShadow = true;
|
|
1961
1976
|
}
|
|
1977
|
+
else if (e.water) {
|
|
1978
|
+
object = makeWaterSurface(e.water);
|
|
1979
|
+
}
|
|
1962
1980
|
else if (e.heightfield) {
|
|
1963
1981
|
try {
|
|
1964
1982
|
object = (await makeHeightfield(e.heightfield, manifest, { assetBase: '' })).mesh;
|
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, HEIGHTMAP_LIBRARY, HEIGHTMAP_DEFAULT_SIZE } from './SceneLoader3D.js';
|
|
4
|
+
export { loadScene3D, loadModelAsset, heightfieldGeometry, makeHeightfield, makeWaterSurface, 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, HEIGHTMAP_LIBRARY, HEIGHTMAP_DEFAULT_SIZE } from './SceneLoader3D.js';
|
|
8
|
+
export { loadScene3D, loadModelAsset, heightfieldGeometry, makeHeightfield, makeWaterSurface, 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.24.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",
|