@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.
@@ -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.musicGain.gain.cancelScheduledValues(t);
281
- this.musicGain.gain.setValueAtTime(this.musicGain.gain.value, t);
282
- this.musicGain.gain.linearRampToValueAtTime(this.musicVolume * 0.25, t + 0.2);
283
- this.musicGain.gain.linearRampToValueAtTime(this.musicVolume, t + seconds);
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.26.0",
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",