@umicat/three-sdk 1.25.0 → 1.27.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/GameAudio.d.ts +24 -0
- package/dist/GameAudio.js +50 -4
- package/dist/SceneLoader3D.js +6 -0
- package/dist/editor/EditorDesignPlayer3D.js +44 -2
- package/dist/scene3d.d.ts +21 -0
- package/package.json +1 -1
package/dist/GameAudio.d.ts
CHANGED
|
@@ -76,6 +76,9 @@ export declare class GameAudio {
|
|
|
76
76
|
private readonly clips;
|
|
77
77
|
private readonly base;
|
|
78
78
|
private readonly ext;
|
|
79
|
+
/** When the current duck is allowed to start climbing back, on the context's
|
|
80
|
+
* clock. Zero when nothing is ducking. */
|
|
81
|
+
private duckedUntil;
|
|
79
82
|
/** Not readonly any more: it is the top of the music's range and the level
|
|
80
83
|
* `duck()` returns to, and both move when the player moves the slider. */
|
|
81
84
|
private musicVolume;
|
|
@@ -137,6 +140,27 @@ export declare class GameAudio {
|
|
|
137
140
|
play(name: string): void;
|
|
138
141
|
/** Duck the music for a moment — for an ending that should be heard over it. */
|
|
139
142
|
duck(seconds?: number): void;
|
|
143
|
+
/**
|
|
144
|
+
* Hold the music down while something else plays OVER it — a voice message, a
|
|
145
|
+
* line of narration, anything with words in it.
|
|
146
|
+
*
|
|
147
|
+
* **`duck()` is the wrong shape for this and it is not obvious why.** It dips
|
|
148
|
+
* and then climbs back across the whole time it is given, which is right for
|
|
149
|
+
* a sting: the music swells again as the moment lands. Give it the length of
|
|
150
|
+
* a three-second voice clip and the music is already back to two thirds by
|
|
151
|
+
* the middle of the sentence, which is exactly where the words are. This one
|
|
152
|
+
* stays down for the whole of `seconds` and only then comes back.
|
|
153
|
+
*
|
|
154
|
+
* **Overlapping callers compose.** The return is never scheduled earlier than
|
|
155
|
+
* one already promised, so a second clip starting over the first extends the
|
|
156
|
+
* quiet instead of ending it — the alternative is music that swells back up
|
|
157
|
+
* between two people talking, which is worse than not ducking at all.
|
|
158
|
+
*/
|
|
159
|
+
duckFor(seconds: number): void;
|
|
160
|
+
/** Down over `DUCK_FALL`, flat for `hold`, back over `rise`. The one place
|
|
161
|
+
* that touches the music gain for this, so the two public shapes above
|
|
162
|
+
* cannot drift apart. */
|
|
163
|
+
private dip;
|
|
140
164
|
/**
|
|
141
165
|
* How loud the music is, 0 to 1, as a fraction of the mix it was given.
|
|
142
166
|
*
|
package/dist/GameAudio.js
CHANGED
|
@@ -33,6 +33,13 @@
|
|
|
33
33
|
*
|
|
34
34
|
* The game brings its own clips; nothing here knows what a game sounds like.
|
|
35
35
|
*/
|
|
36
|
+
/** How long the music takes to get out of the way. Short enough that the first
|
|
37
|
+
* syllable is not lost under it, long enough not to read as a cut. */
|
|
38
|
+
const DUCK_FALL = 0.2;
|
|
39
|
+
/** And how long it takes to come back when whatever it made room for is over.
|
|
40
|
+
* Slower than the fall on purpose: a sudden return draws attention to the
|
|
41
|
+
* music, which is the opposite of what ducking is for. */
|
|
42
|
+
const DUCK_RISE = 0.6;
|
|
36
43
|
export class GameAudio {
|
|
37
44
|
constructor(opts) {
|
|
38
45
|
this.loading = null;
|
|
@@ -51,6 +58,9 @@ export class GameAudio {
|
|
|
51
58
|
this.musicName = null;
|
|
52
59
|
this.buffers = new Map();
|
|
53
60
|
this.lastPlayed = new Map();
|
|
61
|
+
/** When the current duck is allowed to start climbing back, on the context's
|
|
62
|
+
* clock. Zero when nothing is ducking. */
|
|
63
|
+
this.duckedUntil = 0;
|
|
54
64
|
this.sfxVolume = 1;
|
|
55
65
|
this.muted = false;
|
|
56
66
|
this.cleanups = [];
|
|
@@ -274,13 +284,49 @@ export class GameAudio {
|
|
|
274
284
|
}
|
|
275
285
|
/** Duck the music for a moment — for an ending that should be heard over it. */
|
|
276
286
|
duck(seconds = 3) {
|
|
287
|
+
this.dip(0, Math.max(0, seconds - DUCK_FALL));
|
|
288
|
+
}
|
|
289
|
+
/**
|
|
290
|
+
* Hold the music down while something else plays OVER it — a voice message, a
|
|
291
|
+
* line of narration, anything with words in it.
|
|
292
|
+
*
|
|
293
|
+
* **`duck()` is the wrong shape for this and it is not obvious why.** It dips
|
|
294
|
+
* and then climbs back across the whole time it is given, which is right for
|
|
295
|
+
* a sting: the music swells again as the moment lands. Give it the length of
|
|
296
|
+
* a three-second voice clip and the music is already back to two thirds by
|
|
297
|
+
* the middle of the sentence, which is exactly where the words are. This one
|
|
298
|
+
* stays down for the whole of `seconds` and only then comes back.
|
|
299
|
+
*
|
|
300
|
+
* **Overlapping callers compose.** The return is never scheduled earlier than
|
|
301
|
+
* one already promised, so a second clip starting over the first extends the
|
|
302
|
+
* quiet instead of ending it — the alternative is music that swells back up
|
|
303
|
+
* between two people talking, which is worse than not ducking at all.
|
|
304
|
+
*/
|
|
305
|
+
duckFor(seconds) {
|
|
306
|
+
this.dip(Math.max(0, seconds), DUCK_RISE);
|
|
307
|
+
}
|
|
308
|
+
/** Down over `DUCK_FALL`, flat for `hold`, back over `rise`. The one place
|
|
309
|
+
* that touches the music gain for this, so the two public shapes above
|
|
310
|
+
* cannot drift apart. */
|
|
311
|
+
dip(hold, rise) {
|
|
277
312
|
if (!this.ctx || !this.musicGain)
|
|
278
313
|
return;
|
|
279
314
|
const t = this.ctx.currentTime;
|
|
280
|
-
this.
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
315
|
+
const floor = this.musicVolume * 0.25;
|
|
316
|
+
// Never sooner than something already asked for. Measured from the
|
|
317
|
+
// context's own clock, so it survives a caller that does its own counting.
|
|
318
|
+
const until = Math.max(t + DUCK_FALL + hold, this.duckedUntil);
|
|
319
|
+
this.duckedUntil = until;
|
|
320
|
+
const gain = this.musicGain.gain;
|
|
321
|
+
gain.cancelScheduledValues(t);
|
|
322
|
+
// From wherever it is NOW, not from the top: cancelling mid-ramp leaves the
|
|
323
|
+
// gain wherever the ramp had got to, and re-ramping from a value it is not
|
|
324
|
+
// at is an audible step.
|
|
325
|
+
gain.setValueAtTime(gain.value, t);
|
|
326
|
+
gain.linearRampToValueAtTime(floor, t + DUCK_FALL);
|
|
327
|
+
if (until > t + DUCK_FALL)
|
|
328
|
+
gain.setValueAtTime(floor, until);
|
|
329
|
+
gain.linearRampToValueAtTime(this.musicVolume, until + rise);
|
|
284
330
|
}
|
|
285
331
|
/**
|
|
286
332
|
* How loud the music is, 0 to 1, as a fraction of the mix it was given.
|
package/dist/SceneLoader3D.js
CHANGED
|
@@ -876,6 +876,12 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
|
|
|
876
876
|
obj.userData.properties = e.properties;
|
|
877
877
|
if (e.visible === false)
|
|
878
878
|
obj.visible = false;
|
|
879
|
+
// `editorHidden` is authoring state, not game state — it hides the entity
|
|
880
|
+
// in the DESIGN VIEW and nowhere else. A scene loaded by the running game
|
|
881
|
+
// ignores it entirely, which is what separates it from `visible` and is
|
|
882
|
+
// why it can be toggled freely without changing what players see.
|
|
883
|
+
if (opts.designMode && e.editorHidden)
|
|
884
|
+
obj.visible = false;
|
|
879
885
|
applyTransform(obj, e);
|
|
880
886
|
entities.set(e.id, obj);
|
|
881
887
|
}
|
|
@@ -654,9 +654,24 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
654
654
|
// separately-placed visible ground models — without this filter, a click
|
|
655
655
|
// that visibly lands on the rendered ground can silently return the
|
|
656
656
|
// collider's coordinates instead.
|
|
657
|
+
/**
|
|
658
|
+
* Hidden or locked — either way the canvas ignores it. Hidden entities are
|
|
659
|
+
* not drawn; locked ones stay visible but inert, which is the whole point:
|
|
660
|
+
* a ground plane you can see, build on, and never accidentally grab.
|
|
661
|
+
*
|
|
662
|
+
* Mirrors 2D's `editorHidden`/`editorLocked` semantics exactly, down to
|
|
663
|
+
* sharing one hit-test skip.
|
|
664
|
+
*/
|
|
665
|
+
const isInert = (entityId) => {
|
|
666
|
+
if (!entityId)
|
|
667
|
+
return false;
|
|
668
|
+
const a = sceneData?.entities.find((en) => en.id === entityId);
|
|
669
|
+
return a?.editorHidden === true || a?.editorLocked === true;
|
|
670
|
+
};
|
|
657
671
|
const pickEntityAt = (e) => {
|
|
658
672
|
raycaster.setFromCamera(ndcFromEvent(e), camera);
|
|
659
|
-
const targets = Array.from(entityByObject.keys())
|
|
673
|
+
const targets = Array.from(entityByObject.keys())
|
|
674
|
+
.filter((o) => o.visible !== false && !isInert(entityByObject.get(o)));
|
|
660
675
|
const hits = raycaster.intersectObjects(targets, true);
|
|
661
676
|
if (hits.length === 0)
|
|
662
677
|
return null;
|
|
@@ -881,7 +896,13 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
881
896
|
const worldPos = new THREE.Vector3();
|
|
882
897
|
const camSpace = new THREE.Vector3();
|
|
883
898
|
const hits = [];
|
|
884
|
-
for (const obj of objectByEntity
|
|
899
|
+
for (const [entityId, obj] of objectByEntity) {
|
|
900
|
+
// A marquee must skip hidden and locked entities for the same reason a
|
|
901
|
+
// click does — otherwise locking the ground would stop you grabbing it
|
|
902
|
+
// but still let a box-select scoop it up, which is a lock that does not
|
|
903
|
+
// lock.
|
|
904
|
+
if (isInert(entityId))
|
|
905
|
+
continue;
|
|
885
906
|
obj.getWorldPosition(worldPos);
|
|
886
907
|
camSpace.copy(worldPos).applyMatrix4(camera.matrixWorldInverse);
|
|
887
908
|
if (camSpace.z > -camera.near)
|
|
@@ -1808,6 +1829,27 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
1808
1829
|
disposeMeshInPlace(object);
|
|
1809
1830
|
object = swapEntityObject(object, fresh, m.entityId);
|
|
1810
1831
|
}
|
|
1832
|
+
if (m.patch?.editorHidden !== undefined || m.patch?.editorLocked !== undefined) {
|
|
1833
|
+
const authored = sceneData?.entities.find((e) => e.id === m.entityId);
|
|
1834
|
+
if (!authored)
|
|
1835
|
+
return done(`no entity '${m.entityId}' in the scene being shown`);
|
|
1836
|
+
if (m.patch.editorHidden !== undefined)
|
|
1837
|
+
authored.editorHidden = m.patch.editorHidden;
|
|
1838
|
+
if (m.patch.editorLocked !== undefined)
|
|
1839
|
+
authored.editorLocked = m.patch.editorLocked;
|
|
1840
|
+
// Hidden affects the DESIGN VIEW only; the running game never reads
|
|
1841
|
+
// these. `visible` is the game's own field and is left alone — an
|
|
1842
|
+
// entity authored invisible stays invisible when it is unhidden here.
|
|
1843
|
+
object.visible = authored.visible !== false && authored.editorHidden !== true;
|
|
1844
|
+
// Dropping out of the selection on the way out: a hidden or locked
|
|
1845
|
+
// entity that stayed selected would keep its gizmo on screen, grabbable,
|
|
1846
|
+
// which is precisely what both flags exist to prevent.
|
|
1847
|
+
if ((authored.editorHidden || authored.editorLocked) && multiSelected.has(object)) {
|
|
1848
|
+
const next = new Set(multiSelected);
|
|
1849
|
+
next.delete(object);
|
|
1850
|
+
applySelection([...next]);
|
|
1851
|
+
}
|
|
1852
|
+
}
|
|
1811
1853
|
if (m.patch?.water !== undefined) {
|
|
1812
1854
|
// Colour and opacity could be patched in place, size cannot — one
|
|
1813
1855
|
// rebuild path rather than two, same call this scene's load and the
|
package/dist/scene3d.d.ts
CHANGED
|
@@ -239,6 +239,27 @@ export interface Entity3D {
|
|
|
239
239
|
heightfield?: Heightfield3D;
|
|
240
240
|
/** ADR-050 — a body of water. Also mutually exclusive with the above. */
|
|
241
241
|
water?: Water3D;
|
|
242
|
+
/**
|
|
243
|
+
* Editor-only authoring state, mirroring 2D's `editorHidden`/`editorLocked`
|
|
244
|
+
* exactly (Figma's eye and padlock).
|
|
245
|
+
*
|
|
246
|
+
* `editorHidden` hides the entity in the DESIGN VIEW only — the running game
|
|
247
|
+
* is unaffected, which is what separates it from `visible`. `editorLocked`
|
|
248
|
+
* leaves it visible but inert: it cannot be clicked, dragged or caught by a
|
|
249
|
+
* marquee.
|
|
250
|
+
*
|
|
251
|
+
* Lock earns its place here for a specific reason. Drag-to-move now needs a
|
|
252
|
+
* selection so that a full-viewport ground cannot swallow every marquee; the
|
|
253
|
+
* complementary fix is being able to take the ground out of the running
|
|
254
|
+
* entirely, which is what Roblox Studio's Lock is for and why it exists
|
|
255
|
+
* there.
|
|
256
|
+
*
|
|
257
|
+
* **A locked entity cannot be right-clicked either**, so there has to be
|
|
258
|
+
* another way back — 2D has a Hierarchy panel, 3D does not, so the
|
|
259
|
+
* empty-space context menu carries "Unlock all".
|
|
260
|
+
*/
|
|
261
|
+
editorHidden?: boolean;
|
|
262
|
+
editorLocked?: boolean;
|
|
242
263
|
collider?: Collider3D;
|
|
243
264
|
/**
|
|
244
265
|
* ADR-047 — marks this Part for SUBTRACTION the next time it (or a
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@umicat/three-sdk",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.27.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",
|