@umicat/three-sdk 1.26.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/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/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",
|