@umicat/three-sdk 1.26.0 → 1.28.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.
@@ -668,10 +668,10 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
668
668
  const a = sceneData?.entities.find((en) => en.id === entityId);
669
669
  return a?.editorHidden === true || a?.editorLocked === true;
670
670
  };
671
- const pickEntityAt = (e) => {
671
+ const pickEntityAt = (e, includeInert = false) => {
672
672
  raycaster.setFromCamera(ndcFromEvent(e), camera);
673
673
  const targets = Array.from(entityByObject.keys())
674
- .filter((o) => o.visible !== false && !isInert(entityByObject.get(o)));
674
+ .filter((o) => o.visible !== false && (includeInert || !isInert(entityByObject.get(o))));
675
675
  const hits = raycaster.intersectObjects(targets, true);
676
676
  if (hits.length === 0)
677
677
  return null;
@@ -1375,7 +1375,16 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1375
1375
  // decides whether an empty-space menu is worth showing (e.g. Paste).
1376
1376
  if (!scene || rightMoved)
1377
1377
  return;
1378
- const hit = pickEntityAt(e);
1378
+ // Right-click reaches a HIDDEN or LOCKED entity even though every other
1379
+ // gesture ignores it. Lock blocks MANIPULATION — click-select, drag,
1380
+ // marquee — and blocking the context menu as well would leave the only
1381
+ // way out behind a menu you have to already know exists. Reported from a
1382
+ // real session: "I locked it and now there is no way to unlock it."
1383
+ //
1384
+ // It is still not SELECTED: selecting would attach the gizmo and make it
1385
+ // draggable again, which is the one thing the lock is for. The menu acts
1386
+ // on the entity it was opened on, not on the selection.
1387
+ const hit = pickEntityAt(e, true);
1379
1388
  if (!hit) {
1380
1389
  clearWorldSelection();
1381
1390
  if (hudSelectedId)
@@ -1383,6 +1392,10 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1383
1392
  window.parent.postMessage({ type: 'umicat:editor:contextMenu3d', entityId: null, clientX: e.clientX, clientY: e.clientY }, '*');
1384
1393
  return;
1385
1394
  }
1395
+ if (isInert(hit.entityId)) {
1396
+ window.parent.postMessage({ type: 'umicat:editor:contextMenu3d', entityId: hit.entityId, inert: true, clientX: e.clientX, clientY: e.clientY }, '*');
1397
+ return;
1398
+ }
1386
1399
  if (hudSelectedId)
1387
1400
  selectHudEntity(null);
1388
1401
  // ADR-046 — right-clicking an entity that's ALREADY part of a
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@umicat/three-sdk",
3
- "version": "1.26.0",
3
+ "version": "1.28.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",