@umicat/three-sdk 1.22.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.
@@ -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
- export type CharacterState = 'idle' | 'walk' | 'jump' | 'fall';
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
- const nx = len > 0 ? (dir.x / len) * this.opts.speed * dt : 0;
107
- const nz = len > 0 ? (dir.z / len) * this.opts.speed * dt : 0;
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
- if (grounded) {
118
- // Small constant bias, not accumulated gravity: enough for snap-to-ground
119
- // to hold contact over stairs and slopes without pinning the character.
120
- this.verticalVelocity = -this.opts.gravity * dt;
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
- this.verticalVelocity -= this.opts.gravity * dt;
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.grounded
152
- ? (len > 0 ? 'walk' : 'idle')
153
- : (this.verticalVelocity > 0 ? 'jump' : 'fall');
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();
@@ -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,14 @@ 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
+ }
119
131
  /**
120
132
  * ADR-050 — build one heightfield's surface and its collider grid.
121
133
  *
@@ -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
+ 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) {
package/dist/index.d.ts CHANGED
@@ -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/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
- if (!e.modelAssetId && !e.primitive && !e.heightfield) {
308
- problems.push(`entity '${e.id}' has neither a model, a primitive nor a heightfield — it would render nothing`);
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 (e.heightfield && (e.primitive || e.modelAssetId)) {
311
- problems.push(`entity '${e.id}' is both a heightfield and a primitive/model — it can only be one`);
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.22.0",
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",