castle-web-cli 0.4.209 → 0.4.210

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.
@@ -44,6 +44,7 @@ const COMMAND_NAMES = [
44
44
  "voice.requestJoin",
45
45
  "voice.leave",
46
46
  "voice.setMix",
47
+ "voice.setSpatial",
47
48
  "characters.open",
48
49
  "characters.send",
49
50
  "characters.status",
@@ -184,6 +185,8 @@ function runCommand(ctx, command, params, caps, options) {
184
185
  return voiceRequestJoin(ctx, params, caps, options.signal);
185
186
  case "voice.leave":
186
187
  return voiceLeave(ctx, params, caps);
188
+ case "voice.setSpatial":
189
+ return Promise.resolve(voiceSetSpatial(ctx, params, caps));
187
190
  case "voice.setMix":
188
191
  return Promise.resolve(voiceSetMix(ctx, params, caps));
189
192
  case "characters.open":
@@ -411,6 +414,86 @@ function voiceSetMix(ctx, params, caps) {
411
414
  caps.voice.setMix(sessionId, mix, ctx);
412
415
  return { ok: true };
413
416
  }
417
+ // World coordinates past this are a confused deck, not a big world.
418
+ const VOICE_COORDINATE_LIMIT = 1_000_000;
419
+ const VOICE_DISTANCE_MODELS = ["linear", "inverse", "exponential"];
420
+ function voiceVector(value) {
421
+ if (!Array.isArray(value) || value.length !== 3)
422
+ return null;
423
+ const vector = value.map((component) => typeof component === "number" && Number.isFinite(component)
424
+ ? Math.min(VOICE_COORDINATE_LIMIT, Math.max(-VOICE_COORDINATE_LIMIT, component))
425
+ : NaN);
426
+ return vector.every((component) => !Number.isNaN(component))
427
+ ? vector
428
+ : null;
429
+ }
430
+ function isZero(vector) {
431
+ return vector[0] === 0 && vector[1] === 0 && vector[2] === 0;
432
+ }
433
+ // A camera looking straight down (a top-down deck) with the default y-up has forward
434
+ // parallel to up, which leaves no left or right: every voice would play centered.
435
+ // Swap in an up that is perpendicular, so the top of the screen (-z) stays "ahead".
436
+ function perpendicularUp(forward, up) {
437
+ const cross = [
438
+ forward[1] * up[2] - forward[2] * up[1],
439
+ forward[2] * up[0] - forward[0] * up[2],
440
+ forward[0] * up[1] - forward[1] * up[0],
441
+ ];
442
+ const crossLength = Math.hypot(cross[0], cross[1], cross[2]);
443
+ const scale = Math.hypot(...forward) * Math.hypot(...up);
444
+ if (crossLength > 1e-6 * scale)
445
+ return up;
446
+ return Math.abs(forward[2]) < 0.9 * Math.hypot(...forward) ? [0, 0, -1] : [0, 1, 0];
447
+ }
448
+ function voiceSetSpatial(ctx, params, caps) {
449
+ const sessionId = voiceSessionId(params, "voice.setSpatial");
450
+ const update = {};
451
+ const listener = params.listener;
452
+ if (listener && typeof listener === "object") {
453
+ const position = voiceVector(listener.position);
454
+ const forward = voiceVector(listener.forward);
455
+ const up = listener.up === undefined ? [0, 1, 0] : voiceVector(listener.up);
456
+ // A zero forward or up has no direction to face.
457
+ if (position && forward && up && !isZero(forward) && !isZero(up)) {
458
+ update.listener = { position, forward, up: perpendicularUp(forward, up) };
459
+ }
460
+ }
461
+ const rawPositions = params.positions;
462
+ if (rawPositions && typeof rawPositions === "object" && !Array.isArray(rawPositions)) {
463
+ const positions = Object.create(null);
464
+ const entries = Object.entries(rawPositions).slice(0, VOICE_MIX_MAX_ENTRIES);
465
+ for (const [userId, value] of entries) {
466
+ if (!userId || userId.length > 64 || RESERVED_MIX_KEYS.has(userId))
467
+ continue;
468
+ if (value === null) {
469
+ positions[userId] = null;
470
+ continue;
471
+ }
472
+ const position = voiceVector(value);
473
+ if (position)
474
+ positions[userId] = position;
475
+ }
476
+ if (Object.keys(positions).length > 0)
477
+ update.positions = positions;
478
+ }
479
+ const options = params.options;
480
+ if (options && typeof options === "object") {
481
+ const model = VOICE_DISTANCE_MODELS.includes(options.distanceModel)
482
+ ? options.distanceModel
483
+ : "inverse";
484
+ const refDistance = finiteOr(options.refDistance, 1, 0.01, VOICE_COORDINATE_LIMIT);
485
+ update.options = {
486
+ distanceModel: model,
487
+ refDistance,
488
+ maxDistance: Math.max(refDistance, finiteOr(options.maxDistance, 100, 0.01, VOICE_COORDINATE_LIMIT)),
489
+ rolloff: finiteOr(options.rolloff, 1, 0, 100),
490
+ };
491
+ }
492
+ if (caps.voice?.setSpatial && (update.listener || update.positions || update.options)) {
493
+ caps.voice.setSpatial(sessionId, update, ctx);
494
+ }
495
+ return { ok: true };
496
+ }
414
497
  function finiteOr(value, fallback, min, max) {
415
498
  return typeof value === "number" && Number.isFinite(value)
416
499
  ? Math.min(max, Math.max(min, value))
@@ -0,0 +1,14 @@
1
+ import type { EnvironmentModuleNode, Plugin } from 'vite';
2
+ export declare function isPreloadableModuleUrl(url: string): boolean;
3
+ export declare function moduleEntrySrcs(html: string): string[];
4
+ type PreloadGraph = {
5
+ transformRequest(url: string): Promise<unknown>;
6
+ getModuleByUrl(url: string): Promise<EnvironmentModuleNode | undefined>;
7
+ };
8
+ export declare function isStaticImportIn(code: string, url: string): boolean;
9
+ export declare function collectModulePreloads(graph: PreloadGraph, entries: string[], budgetMs?: number): Promise<string[]>;
10
+ export declare function modulePreloadPlugin(options: {
11
+ enabled: boolean;
12
+ budgetMs?: number;
13
+ }): Plugin;
14
+ export {};
@@ -0,0 +1,150 @@
1
+ // The dev server hands a deck's modules to the browser one file at a time, and
2
+ // the browser only learns a module's imports once that module has arrived. A
3
+ // kit deck is 150-300 modules deep in that chain, so on a phone every level
4
+ // costs a network round trip: physics-2d measured 1.5 s on localhost and 6.5 s
5
+ // at 150 ms RTT. Listing the whole static graph up front as modulepreload links
6
+ // lets the browser fetch it in parallel instead, while each module is still
7
+ // served, cached and executed exactly as before.
8
+ //
9
+ // Off unless CASTLE_MODULE_PRELOAD=1, so the sandbox image decides.
10
+ const DEFAULT_BUDGET_MS = 1500;
11
+ // Listed links, not walked modules: the walk itself is bounded by the budget.
12
+ const MAX_MODULES = 1000;
13
+ // Only plain script modules. Anything Vite serves under an `?import`, `?raw`,
14
+ // `?url` or `?worker` style query, and every non-script file (scenes, json,
15
+ // styles, assets), is left for the page to ask for itself: preloading a URL
16
+ // the page never imports would fetch twice, and preloading a non-module one
17
+ // would log a load error into the deck's console.
18
+ const SCRIPT_URL = /^\/(?!\/)[^?#]*\.(?:m?[jt]sx?)(?:\?v=[\w.-]+)?$/;
19
+ export function isPreloadableModuleUrl(url) {
20
+ return SCRIPT_URL.test(url);
21
+ }
22
+ // `<script type="module" src="/...">` entries of the page as Vite will serve it.
23
+ export function moduleEntrySrcs(html) {
24
+ const srcs = [];
25
+ for (const tag of html.match(/<script\b[^>]*>/gi) ?? []) {
26
+ if (!/\btype\s*=\s*["']?module\b/i.test(tag))
27
+ continue;
28
+ const src = /\bsrc\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/i.exec(tag);
29
+ const value = src?.[1] ?? src?.[2] ?? src?.[3];
30
+ if (value && value.startsWith('/') && !value.startsWith('//'))
31
+ srcs.push(value);
32
+ }
33
+ return srcs;
34
+ }
35
+ // Vite rewrites each import to a URL and records it, minus any HMR timestamp,
36
+ // in `staticImportedUrls`; that recorded string is what the browser asks for,
37
+ // so it is what gets preloaded. It can differ from the child node's own url: a
38
+ // shared chunk inside an optimized dep is imported with its importer's `?v=`.
39
+ function childNode(byUrl, importUrl) {
40
+ return byUrl.get(importUrl) ?? byUrl.get(importUrl.replace(/[?&]v=[\w.-]+$/, ''));
41
+ }
42
+ // Vite's `staticImportedUrls` holds every literal import specifier, dynamic ones
43
+ // included (`import('./x.js')`, a lazy `import.meta.glob`). Those load on demand,
44
+ // so only a URL the transformed code imports statically -- `import "u"`,
45
+ // `from "u"` -- is preloaded and walked.
46
+ function escapeRegExp(value) {
47
+ return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
48
+ }
49
+ export function isStaticImportIn(code, url) {
50
+ const u = escapeRegExp(url);
51
+ return new RegExp(`(?:\\bfrom|\\bimport)\\s*(["'])${u}(?:[?&]t=\\d+)?\\1`).test(code);
52
+ }
53
+ // Walk the static import graph below `entries`, transforming modules the
54
+ // server has not seen yet (work the browser's requests would otherwise wait
55
+ // on one by one). A module is listed only once its own transform succeeded.
56
+ // The walk is raced against the budget, so a slow transform (a dependency
57
+ // re-optimization, a plugin that never settles) cannot hold the page: when
58
+ // the timer fires the list so far is returned and the rest load the ordinary way.
59
+ export async function collectModulePreloads(graph, entries, budgetMs = DEFAULT_BUDGET_MS) {
60
+ const out = [];
61
+ let stopped = false;
62
+ const walk = async () => {
63
+ const seen = new Set(entries);
64
+ let level = entries.map((url) => ({ url, href: null }));
65
+ while (level.length && !stopped) {
66
+ const next = [];
67
+ await Promise.all(level.map(async ({ url, href }) => {
68
+ let mod = await graph.getModuleByUrl(url);
69
+ if (!mod?.transformResult) {
70
+ try {
71
+ await graph.transformRequest(url);
72
+ }
73
+ catch {
74
+ return; // The page will hit the same error and report it itself.
75
+ }
76
+ mod = await graph.getModuleByUrl(url);
77
+ }
78
+ if (!mod?.transformResult || stopped)
79
+ return;
80
+ if (href && out.length < MAX_MODULES)
81
+ out.push(href);
82
+ const staticUrls = mod.staticImportedUrls;
83
+ const code = mod.transformResult.code;
84
+ if (!staticUrls || typeof code !== 'string')
85
+ return;
86
+ const byUrl = new Map([...mod.importedModules].map((child) => [child.url, child]));
87
+ for (const importUrl of staticUrls) {
88
+ if (!isStaticImportIn(code, importUrl))
89
+ continue;
90
+ const child = childNode(byUrl, importUrl);
91
+ if (!child || seen.has(child.url))
92
+ continue;
93
+ seen.add(child.url);
94
+ // A timestamped import carries `t=` at a position that depends on its
95
+ // other queries; skip rather than risk a second fetch. HMR is off, so
96
+ // this is rare (Vite still stamps pruned modules).
97
+ if (child.type !== 'js' || child.lastHMRTimestamp > 0)
98
+ continue;
99
+ if (!isPreloadableModuleUrl(importUrl))
100
+ continue;
101
+ next.push({ url: child.url, href: importUrl });
102
+ }
103
+ }));
104
+ level = next;
105
+ }
106
+ };
107
+ let timer;
108
+ const timeout = new Promise((resolve) => {
109
+ timer = setTimeout(resolve, budgetMs);
110
+ });
111
+ await Promise.race([walk().catch(() => { }), timeout]);
112
+ stopped = true;
113
+ clearTimeout(timer);
114
+ return out.slice();
115
+ }
116
+ export function modulePreloadPlugin(options) {
117
+ let server = null;
118
+ return {
119
+ name: 'castle-module-preload',
120
+ apply: 'serve',
121
+ configureServer(s) {
122
+ server = s;
123
+ },
124
+ transformIndexHtml: {
125
+ order: 'post',
126
+ async handler(html) {
127
+ const client = server?.environments?.client;
128
+ if (!options.enabled || !client)
129
+ return html;
130
+ const graph = {
131
+ transformRequest: (url) => client.transformRequest(url),
132
+ getModuleByUrl: (url) => client.moduleGraph.getModuleByUrl(url),
133
+ };
134
+ let urls;
135
+ try {
136
+ urls = await collectModulePreloads(graph, moduleEntrySrcs(html), options.budgetMs);
137
+ }
138
+ catch {
139
+ return html; // An optimisation only: never cost the page itself.
140
+ }
141
+ const tags = urls.map((href) => ({
142
+ tag: 'link',
143
+ attrs: { rel: 'modulepreload', href },
144
+ injectTo: 'head',
145
+ }));
146
+ return { html, tags };
147
+ },
148
+ },
149
+ };
150
+ }
@@ -229,7 +229,7 @@ const COMMON_SECTIONS = `## Imports are read-only
229
229
 
230
230
  - **Read \`${MULTIPLAYER_DOC_REL}\` before writing or changing a server entry or client netcode by hand.** It carries what this section leaves out: the outbound frame budget in practice, the snapshot pattern, self-healing events, and the reconnect and disconnect handling a hand-rolled session gets wrong. A deck built on the \`castle.multiplayer-2d\` / \`castle.multiplayer-3d\` (or \`castle.turn-based\`) kits already does all of that and normally writes nothing against the raw session API.
231
231
  - **A deck becomes multiplayer by having a server entry** — no flag, no dashboard. The entry is \`castle.json\`'s \`server.main\` when set (a kit deck points it under \`imports/\`), otherwise the first of \`server/index.{js,ts,mjs}\` or \`code/server/index.{js,ts,mjs}\` that exists; removing the entry turns multiplayer off on the next \`save-deck\`. Castle runs that module as a real server process, one per session, shared by the players in it. Other options under \`server\`: \`maxPlayers\` (max 24), and \`tickRate\` (defaults to 20, max 30; 0 turns ticks off).
232
- - **Voice chat comes with multiplayer; the deck doesn't build it.** Castle runs the call, the microphone prompt and the mute/push-to-talk controls outside the card, so a deck never touches audio or the mic. \`connection.voice\` lets a deck ask the player to join (\`requestJoin()\` shows Castle's prompt), follow \`state\` and \`onSpeaking(playerIds => ...)\` for talking indicators, and \`setMix({ [playerId]: { gain, pan } })\` for proximity chat (gain 0-1, pan -1 to 1). \`state\` is \`"unavailable"\` in solo, in local dev, and wherever voice isn't offered, so draw voice UI only when it isn't. Call \`requestJoin()\` from a player action (a "Join voice" button): if they decline, asking again within 10 seconds answers \`"declined"\` without a prompt. Turn voice off for a deck with \`"voice": { "enabled": false }\` in \`castle.json\`.
232
+ - **Voice chat comes with multiplayer; the deck doesn't build it.** Castle runs the call, the microphone prompt and the mute/push-to-talk controls outside the card, so a deck never touches audio or the mic. \`connection.voice\` lets a deck ask the player to join (\`requestJoin()\` shows Castle's prompt), follow \`state\` and \`onSpeaking(playerIds => ...)\` for talking indicators, and \`setMix({ [playerId]: { gain, pan } })\` for simple proximity chat (gain 0-1, pan -1 to 1). For 3D voice, \`setListener({ position: [x, y, z], forward: [x, y, z] })\` (usually the local player's camera, y up) and \`setPositions({ [playerId]: [x, y, z] })\` place each voice in the world, with distance falloff and direction (best on headphones); \`setSpatialOptions({ refDistance, maxDistance, rolloff, distanceModel })\` tunes the falloff. Update them as things move; they are sent ten times a second. \`state\` is \`"unavailable"\` in solo, in local dev, and wherever voice isn't offered, so draw voice UI only when it isn't. Call \`requestJoin()\` from a player action (a "Join voice" button): if they decline, asking again within 10 seconds answers \`"declined"\` without a prompt. Turn voice off for a deck with \`"voice": { "enabled": false }\` in \`castle.json\`.
233
233
  - **The server module default-exports lifecycle callbacks**, each taking the session first:
234
234
 
235
235
  \`\`\`js
package/dist/serve.js CHANGED
@@ -11,6 +11,7 @@ import { createAgentServer } from './agent.js';
11
11
  import { sceneFilesPlugin, importsAliasPlugin, forksOverlayPlugin, sdkAliasPlugin, } from './vitePlugins.js';
12
12
  import { viteClientStubPlugin } from './viteClientStub.js';
13
13
  import { paramsRegisterPlugin } from './paramsRegisterPlugin.js';
14
+ import { modulePreloadPlugin } from './modulePreload.js';
14
15
  import { createScriptErrors, scriptErrorsPlugin } from './scriptErrors.js';
15
16
  import { installFilesChangedWatcher } from './filesChanged.js';
16
17
  import { applyDeckWrite, createTuneLedger } from './paramsTunes.js';
@@ -1226,6 +1227,7 @@ export async function serve(dir, options = {}) {
1226
1227
  paramsRegisterPlugin(projectDir, tuneLedger),
1227
1228
  sceneFilesPlugin(),
1228
1229
  scriptErrorsPlugin(scriptErrors),
1230
+ modulePreloadPlugin({ enabled: process.env.CASTLE_MODULE_PRELOAD === '1' }),
1229
1231
  ],
1230
1232
  server: {
1231
1233
  port,
@@ -82,7 +82,7 @@
82
82
  "title": "base",
83
83
  "deckId": "yRcmH4_aYllE",
84
84
  "cardId": "zkFdingmIm3m",
85
- "publishedVersion": "2026-09-25T17:53:46.911Z",
85
+ "publishedVersion": "2026-09-25T19:32:53.241Z",
86
86
  "provides": [
87
87
  "castle-web-sdk"
88
88
  ]
@@ -15,7 +15,7 @@ export { Lifecycle } from "./lifecycle";
15
15
  export type { CastleLifecycleApi } from "./lifecycle";
16
16
  export { Multiplayer } from "./multiplayer";
17
17
  export type { CastleMultiplayerApi, MultiplayerConnection, MultiplayerConnectionState, MultiplayerJoinOptions, MultiplayerRoster, MultiplayerStateMetadata, } from "./multiplayer";
18
- export type { MultiplayerVoice, VoiceJoinStatus, VoiceMixEntry, VoiceState, } from "./multiplayerVoice";
18
+ export type { MultiplayerVoice, VoiceJoinStatus, VoiceListener, VoiceMixEntry, VoiceSpatialOptions, VoiceState, VoiceVector, } from "./multiplayerVoice";
19
19
  export type { MultiplayerSoloReason } from "./commands";
20
20
  export { MAX_CLIENT_FRAME_BYTES, MAX_PLAYERS_CAP } from "./multiplayerProtocol";
21
21
  export type { ClientByeFrame, ClientHelloFrame, ClientMessageFrame, ClientPingFrame, ClientPongFrame, ClientReplacedFrame, ClientRosterFrame, ClientToPlatformFrame, ClientToPlatformMessageFrame, MultiplayerPlayer, PlayerIdentity, PlatformToClientFrame, SessionPlayer, SessionType, } from "./multiplayerProtocol";
@@ -108,9 +108,33 @@ export type VoiceJoinStatus = "joined" | "declined" | "unavailable";
108
108
  export interface VoiceMixEntry {
109
109
  /** 0 (silent) to 1 (full). */
110
110
  gain?: number;
111
- /** -1 (left) to 1 (right). */
111
+ /** -1 (left) to 1 (right). Ignored for a player with a 3D position. */
112
112
  pan?: number;
113
113
  }
114
+ export type VoiceVector = [number, number, number];
115
+ export interface VoiceListener {
116
+ position: VoiceVector;
117
+ /** The direction the listener faces; need not be normalized. */
118
+ forward: VoiceVector;
119
+ /** Defaults to [0, 1, 0]. */
120
+ up?: VoiceVector;
121
+ }
122
+ export interface VoiceSpatialOptions {
123
+ /** How volume falls off with distance; default "inverse". */
124
+ distanceModel?: "linear" | "inverse" | "exponential";
125
+ /** Distance at which a voice is at full volume; default 1. */
126
+ refDistance?: number;
127
+ /** Beyond this, a voice gets no quieter ("linear": silent); default 100. */
128
+ maxDistance?: number;
129
+ /** How fast volume falls off; default 1. */
130
+ rolloff?: number;
131
+ }
132
+ export interface VoiceSpatialUpdate {
133
+ listener?: VoiceListener;
134
+ /** Keyed by userId. `null` returns a player to plain gain and pan. */
135
+ positions?: Record<string, VoiceVector | null>;
136
+ options?: VoiceSpatialOptions;
137
+ }
114
138
  export interface CharacterSummary {
115
139
  id: string;
116
140
  version: string;
@@ -316,6 +340,9 @@ export interface CommandParams {
316
340
  sessionId: string;
317
341
  mix: Record<string, VoiceMixEntry>;
318
342
  };
343
+ "voice.setSpatial": {
344
+ sessionId: string;
345
+ } & VoiceSpatialUpdate;
319
346
  "characters.open": {
320
347
  characterId: string;
321
348
  };
@@ -450,6 +477,9 @@ export interface CommandResult {
450
477
  "voice.setMix": {
451
478
  ok: true;
452
479
  };
480
+ "voice.setSpatial": {
481
+ ok: true;
482
+ };
453
483
  "characters.open": CharacterAdmission;
454
484
  "characters.send": CharacterOperation;
455
485
  "characters.status": CharacterOperation;
@@ -1,7 +1,7 @@
1
- import type { VoiceEvent, VoiceJoinStatus, VoiceMixEntry, VoiceState } from "./commands";
1
+ import type { VoiceEvent, VoiceJoinStatus, VoiceListener, VoiceMixEntry, VoiceSpatialOptions, VoiceState, VoiceVector } from "./commands";
2
2
  import type { MultiplayerPlayer } from "./multiplayerProtocol";
3
3
  export declare const VOICE_MIX_INTERVAL_MS = 100;
4
- export type { VoiceJoinStatus, VoiceMixEntry, VoiceState };
4
+ export type { VoiceJoinStatus, VoiceListener, VoiceMixEntry, VoiceSpatialOptions, VoiceState, VoiceVector, };
5
5
  export interface MultiplayerVoice {
6
6
  /** "unavailable" when this host, deck, session or player can't have voice. */
7
7
  readonly state: VoiceState;
@@ -18,6 +18,19 @@ export interface MultiplayerVoice {
18
18
  * full volume, centered). Sent at most ten times a second; the latest values win.
19
19
  */
20
20
  setMix(mix: Record<string, VoiceMixEntry>): void;
21
+ /**
22
+ * 3D voice: where the listener (usually the local player's camera) is and faces, in
23
+ * the deck's world units, y up. With positions set, voices come from their place in
24
+ * the world (distance, left/right, front/behind, above/below; best on headphones).
25
+ */
26
+ setListener(listener: VoiceListener): void;
27
+ /**
28
+ * Where each player's voice comes from, keyed by playerId. `null` returns a player
29
+ * to plain gain and pan. Their `setMix` gain still applies; their pan does not.
30
+ */
31
+ setPositions(positions: Record<string, VoiceVector | null>): void;
32
+ /** How voices fade with distance. Defaults: inverse, refDistance 1, maxDistance 100, rolloff 1. */
33
+ setSpatialOptions(options: VoiceSpatialOptions): void;
21
34
  onState(callback: (state: VoiceState) => void): () => void;
22
35
  /** The playerIds speaking right now; called whenever that set changes. */
23
36
  onSpeaking(callback: (playerIds: string[]) => void): () => void;
@@ -39,6 +52,12 @@ export declare class MultiplayerVoiceImpl implements MultiplayerVoice {
39
52
  private speaking;
40
53
  private pendingMix;
41
54
  private sentMix;
55
+ private pendingListener;
56
+ private pendingPositions;
57
+ private pendingOptions;
58
+ private sentListener;
59
+ private sentPositions;
60
+ private sentOptions;
42
61
  private mixTimer;
43
62
  private lastMixSentAt;
44
63
  private disposed;
@@ -51,6 +70,9 @@ export declare class MultiplayerVoiceImpl implements MultiplayerVoice {
51
70
  private askToJoin;
52
71
  leave(): void;
53
72
  setMix(mix: Record<string, VoiceMixEntry>): void;
73
+ setListener(listener: VoiceListener): void;
74
+ setPositions(positions: Record<string, VoiceVector | null>): void;
75
+ setSpatialOptions(options: VoiceSpatialOptions): void;
54
76
  onState(callback: (state: VoiceState) => void): () => void;
55
77
  onSpeaking(callback: (playerIds: string[]) => void): () => void;
56
78
  receive(event: VoiceEvent): void;
@@ -62,6 +84,8 @@ export declare class MultiplayerVoiceImpl implements MultiplayerVoice {
62
84
  private sendLeave;
63
85
  private setState;
64
86
  private emitSpeaking;
87
+ private hasPending;
65
88
  private scheduleMix;
66
89
  private flushMix;
90
+ private takeSpatial;
67
91
  }
@@ -31,6 +31,13 @@ export class MultiplayerVoiceImpl {
31
31
  speaking = [];
32
32
  pendingMix = {};
33
33
  sentMix = {};
34
+ // Spatial state: pending (not yet sent) and sent (re-sent when a call restarts).
35
+ pendingListener = null;
36
+ pendingPositions = {};
37
+ pendingOptions = null;
38
+ sentListener = null;
39
+ sentPositions = {};
40
+ sentOptions = null;
34
41
  mixTimer = null;
35
42
  lastMixSentAt = 0;
36
43
  disposed = false;
@@ -163,6 +170,45 @@ export class MultiplayerVoiceImpl {
163
170
  }
164
171
  this.scheduleMix();
165
172
  }
173
+ setListener(listener) {
174
+ if (this.disposed || !listener || typeof listener !== "object")
175
+ return;
176
+ const position = vector(listener.position);
177
+ const forward = vector(listener.forward);
178
+ const up = listener.up === undefined ? undefined : vector(listener.up);
179
+ // A zero direction faces nowhere (a player standing still, say): keep the last
180
+ // listener rather than send one the host would drop.
181
+ if (!position || !forward || up === null || isZero(forward) || (up && isZero(up)))
182
+ return;
183
+ this.pendingListener = up ? { position, forward, up } : { position, forward };
184
+ this.scheduleMix();
185
+ }
186
+ setPositions(positions) {
187
+ if (this.disposed || !positions || typeof positions !== "object")
188
+ return;
189
+ const players = this.access.players();
190
+ for (const [playerId, value] of Object.entries(positions)) {
191
+ const player = players.find((candidate) => candidate.playerId === playerId);
192
+ if (!player)
193
+ continue;
194
+ if (value === null) {
195
+ this.pendingPositions[player.userId] = null;
196
+ continue;
197
+ }
198
+ const position = vector(value);
199
+ if (position)
200
+ this.pendingPositions[player.userId] = position;
201
+ }
202
+ this.scheduleMix();
203
+ }
204
+ setSpatialOptions(options) {
205
+ if (this.disposed || !options || typeof options !== "object")
206
+ return;
207
+ // Cumulative: the host fills every missing field with its default, so each send
208
+ // carries everything the deck has set so far.
209
+ this.pendingOptions = { ...this.sentOptions, ...this.pendingOptions, ...options };
210
+ this.scheduleMix();
211
+ }
166
212
  onState(callback) {
167
213
  this.states.add(callback);
168
214
  callListener(callback, this.currentState);
@@ -198,6 +244,14 @@ export class MultiplayerVoiceImpl {
198
244
  if (!userIds.has(userId))
199
245
  delete this.sentMix[userId];
200
246
  }
247
+ for (const userId of Object.keys(this.pendingPositions)) {
248
+ if (!userIds.has(userId))
249
+ delete this.pendingPositions[userId];
250
+ }
251
+ for (const userId of Object.keys(this.sentPositions)) {
252
+ if (!userIds.has(userId))
253
+ delete this.sentPositions[userId];
254
+ }
201
255
  this.emitSpeaking();
202
256
  }
203
257
  // The game connection ended: voice for its session goes with it.
@@ -230,6 +284,12 @@ export class MultiplayerVoiceImpl {
230
284
  this.speakingUserIds = [];
231
285
  this.pendingMix = {};
232
286
  this.sentMix = {};
287
+ this.pendingListener = null;
288
+ this.pendingPositions = {};
289
+ this.pendingOptions = null;
290
+ this.sentListener = null;
291
+ this.sentPositions = {};
292
+ this.sentOptions = null;
233
293
  this.emitSpeaking();
234
294
  }
235
295
  sendLeave(sessionId) {
@@ -249,6 +309,12 @@ export class MultiplayerVoiceImpl {
249
309
  for (const userId of Object.keys(this.sentMix)) {
250
310
  this.pendingMix[userId] ??= {};
251
311
  }
312
+ this.pendingListener ??= this.sentListener;
313
+ this.pendingOptions ??= this.sentOptions;
314
+ for (const [userId, position] of Object.entries(this.sentPositions)) {
315
+ if (!(userId in this.pendingPositions))
316
+ this.pendingPositions[userId] = position;
317
+ }
252
318
  this.scheduleMix();
253
319
  }
254
320
  }
@@ -265,8 +331,14 @@ export class MultiplayerVoiceImpl {
265
331
  for (const callback of this.speakers)
266
332
  callListener(callback, playerIds.slice());
267
333
  }
334
+ hasPending() {
335
+ return (Object.keys(this.pendingMix).length > 0 ||
336
+ Object.keys(this.pendingPositions).length > 0 ||
337
+ this.pendingListener !== null ||
338
+ this.pendingOptions !== null);
339
+ }
268
340
  scheduleMix() {
269
- if (this.mixTimer !== null || Object.keys(this.pendingMix).length === 0)
341
+ if (this.mixTimer !== null || !this.hasPending())
270
342
  return;
271
343
  const wait = Math.max(0, this.lastMixSentAt + VOICE_MIX_INTERVAL_MS - Date.now());
272
344
  this.mixTimer = setTimeout(() => {
@@ -290,11 +362,54 @@ export class MultiplayerVoiceImpl {
290
362
  mix[userId] = full;
291
363
  }
292
364
  this.pendingMix = {};
293
- if (Object.keys(mix).length === 0)
365
+ const spatial = this.takeSpatial(userIds);
366
+ if (Object.keys(mix).length === 0 && !spatial)
294
367
  return;
295
368
  this.lastMixSentAt = Date.now();
296
- void hostRequest("voice.setMix", { sessionId: this.voiceSessionId, mix }).catch(() => { });
369
+ if (Object.keys(mix).length > 0) {
370
+ void hostRequest("voice.setMix", { sessionId: this.voiceSessionId, mix }).catch(() => { });
371
+ }
372
+ if (spatial) {
373
+ void hostRequest("voice.setSpatial", { sessionId: this.voiceSessionId, ...spatial }).catch(() => { });
374
+ }
297
375
  }
376
+ takeSpatial(userIds) {
377
+ const update = {};
378
+ if (this.pendingListener) {
379
+ update.listener = this.pendingListener;
380
+ this.sentListener = this.pendingListener;
381
+ }
382
+ if (this.pendingOptions) {
383
+ update.options = this.pendingOptions;
384
+ this.sentOptions = this.pendingOptions;
385
+ }
386
+ const positions = {};
387
+ for (const [userId, position] of Object.entries(this.pendingPositions)) {
388
+ if (!userIds.has(userId))
389
+ continue;
390
+ positions[userId] = position;
391
+ if (position)
392
+ this.sentPositions[userId] = position;
393
+ else
394
+ delete this.sentPositions[userId];
395
+ }
396
+ if (Object.keys(positions).length > 0)
397
+ update.positions = positions;
398
+ this.pendingListener = null;
399
+ this.pendingOptions = null;
400
+ this.pendingPositions = {};
401
+ return update.listener || update.options || update.positions ? update : null;
402
+ }
403
+ }
404
+ function vector(value) {
405
+ return Array.isArray(value) &&
406
+ value.length === 3 &&
407
+ value.every((component) => typeof component === "number" && Number.isFinite(component))
408
+ ? [value[0], value[1], value[2]]
409
+ : null;
410
+ }
411
+ function isZero(value) {
412
+ return value[0] === 0 && value[1] === 0 && value[2] === 0;
298
413
  }
299
414
  function clamp(value, min, max) {
300
415
  return Math.min(max, Math.max(min, value));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "castle-web-cli",
3
- "version": "0.4.209",
3
+ "version": "0.4.210",
4
4
  "repository": {
5
5
  "type": "git",
6
6
  "url": "git+https://github.com/castle-xyz/castle-experimental-web.git"