castle-web-cli 0.4.208 → 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.
- package/dist/api.d.ts +5 -0
- package/dist/castle-host/host.js +234 -0
- package/dist/castleJson.d.ts +4 -0
- package/dist/castleJson.js +3 -1
- package/dist/devSessionServer.js +1 -0
- package/dist/editorConfig.d.ts +12 -0
- package/dist/editorConfig.js +72 -6
- package/dist/init.js +1 -1
- package/dist/modulePreload.d.ts +14 -0
- package/dist/modulePreload.js +150 -0
- package/dist/native/loop.js +1 -1
- package/dist/native/playtest-executor.js +36 -4
- package/dist/native/playtest-remote.d.ts +1 -0
- package/dist/native/playtest-remote.js +61 -5
- package/dist/native/playtest.d.ts +35 -2
- package/dist/native/playtest.js +162 -18
- package/dist/platformDoc.d.ts +1 -0
- package/dist/platformDoc.js +24 -3
- package/dist/playUrl.d.ts +3 -0
- package/dist/playUrl.js +12 -0
- package/dist/save-deck.js +1 -0
- package/dist/serve.js +2 -0
- package/dist/shell/assets/{index-b_bebkRb.css → index-BCrgYh76.css} +1 -1
- package/dist/shell/assets/{index-C6SXXPwm.js → index-DzLbNBc7.js} +68 -68
- package/dist/shell/index.html +2 -2
- package/kits/base/CLAUDE.md +1 -0
- package/kits/base/castle.json +1 -1
- package/kits/base/sdk/README.md +70 -7
- package/kits/base/sdk/castle.d.ts +1 -0
- package/kits/base/sdk/commands.d.ts +78 -0
- package/kits/base/sdk/commands.js +25 -0
- package/kits/base/sdk/multiplayer.d.ts +3 -0
- package/kits/base/sdk/multiplayer.js +13 -0
- package/kits/base/sdk/multiplayerVoice.d.ts +91 -0
- package/kits/base/sdk/multiplayerVoice.js +424 -0
- package/kits/base/sdk/transport.d.ts +2 -1
- package/kits/base/sdk/transport.js +15 -1
- package/kits/multiplayer-2d/castle.json +2 -2
- package/kits/multiplayer-2d/code/systems/multiplayer.js +7 -1
- package/kits/multiplayer-3d/castle.json +2 -2
- package/kits/multiplayer-3d/code/systems/multiplayer.js +8 -4
- package/kits/physics-2d/castle.json +1 -1
- package/kits/physics-2d/editors/SceneEditor.jsx +18 -4
- package/kits/physics-2d/systems/media.js +3 -5
- package/kits/physics-3d/castle.json +2 -2
- package/kits/physics-3d/engine3d/PxModelEditor.jsx +2 -2
- package/kits/physics-3d/engine3d/pxmodel.js +7 -0
- package/kits/real-time/CLAUDE.md +3 -0
- package/kits/real-time/castle.json +1 -1
- package/kits/real-time/code/client/connection.js +17 -2
- package/kits/real-time/code/client/gameHooks.js +5 -0
- package/kits/real-time/code/client/joinOverlay.js +23 -5
- package/kits/real-time/code/client/messages.js +4 -0
- package/kits/real-time/code/server/persist.js +19 -10
- package/kits/real-time/code/server/session.js +19 -0
- package/package.json +2 -2
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
// The real (Playwright-backed) PlaytestExecutor: navigates a fresh
|
|
2
2
|
// browser context + page to the served deck, settles, replays a timeline of
|
|
3
|
-
// mouse/keyboard primitives and screenshot captures on one wall clock, and
|
|
3
|
+
// mouse/touch/keyboard primitives and screenshot captures on one wall clock, and
|
|
4
4
|
// reports console/pageerror output plus rAF-tick capture-health diagnostics.
|
|
5
5
|
// See native/playtest.ts for the browser-free types this implements and
|
|
6
6
|
// native/playtest-browser.ts for the warm-Chromium lifecycle this borrows a
|
|
@@ -65,7 +65,25 @@ function attachConsoleCapture(page, navStart, boundaries) {
|
|
|
65
65
|
page.on("pageerror", (err) => push("pageerror", err.message));
|
|
66
66
|
return log;
|
|
67
67
|
}
|
|
68
|
-
|
|
68
|
+
// Playwright's touchscreen only taps, so a touch drag goes through CDP --
|
|
69
|
+
// the same Input.dispatchTouchEvent that touchscreen.tap itself sends. A
|
|
70
|
+
// finger has no hover: Chromium rejects a touchMove or touchEnd with no touch
|
|
71
|
+
// in progress ("Must send a TouchStart first"), failing the whole call, so a
|
|
72
|
+
// move or up with no finger down is dropped rather than sent. One finger only:
|
|
73
|
+
// Chromium delivers a second down while the finger is down as a touchmove.
|
|
74
|
+
function touchDispatcher(cdp) {
|
|
75
|
+
let down = false;
|
|
76
|
+
return async (type, x, y) => {
|
|
77
|
+
if (type !== "touchStart" && !down)
|
|
78
|
+
return;
|
|
79
|
+
down = type !== "touchEnd";
|
|
80
|
+
await cdp.send("Input.dispatchTouchEvent", {
|
|
81
|
+
type,
|
|
82
|
+
touchPoints: type === "touchEnd" ? [] : [{ x, y }],
|
|
83
|
+
});
|
|
84
|
+
};
|
|
85
|
+
}
|
|
86
|
+
async function runTimeline(page, input, touch) {
|
|
69
87
|
const sessionStart = Date.now();
|
|
70
88
|
const frames = [];
|
|
71
89
|
let framesRequested = 0;
|
|
@@ -87,6 +105,15 @@ async function runTimeline(page, input) {
|
|
|
87
105
|
await page.mouse.move(event.x, event.y);
|
|
88
106
|
await page.mouse.up();
|
|
89
107
|
break;
|
|
108
|
+
case "touchstart":
|
|
109
|
+
await touch("touchStart", event.x, event.y);
|
|
110
|
+
break;
|
|
111
|
+
case "touchmove":
|
|
112
|
+
await touch("touchMove", event.x, event.y);
|
|
113
|
+
break;
|
|
114
|
+
case "touchend":
|
|
115
|
+
await touch("touchEnd", event.x, event.y);
|
|
116
|
+
break;
|
|
90
117
|
case "keydown":
|
|
91
118
|
await page.keyboard.down(event.key);
|
|
92
119
|
break;
|
|
@@ -114,7 +141,11 @@ async function measureDiagnostics(page, wallMs) {
|
|
|
114
141
|
async function runSessionOnBrowser(browser, input) {
|
|
115
142
|
const navStart = Date.now();
|
|
116
143
|
const boundaries = { settleStartRel: null, sessionStartRel: null };
|
|
117
|
-
const
|
|
144
|
+
const touchInput = input.input === "touch";
|
|
145
|
+
const context = await browser.newContext({
|
|
146
|
+
viewport: PLAYTEST_VIEWPORT,
|
|
147
|
+
...(touchInput ? { hasTouch: true, isMobile: true } : {}),
|
|
148
|
+
});
|
|
118
149
|
let consoleLog = [];
|
|
119
150
|
try {
|
|
120
151
|
const page = await context.newPage();
|
|
@@ -134,7 +165,8 @@ async function runSessionOnBrowser(browser, input) {
|
|
|
134
165
|
};
|
|
135
166
|
requestAnimationFrame(tick);
|
|
136
167
|
});
|
|
137
|
-
const
|
|
168
|
+
const touch = touchInput ? touchDispatcher(await context.newCDPSession(page)) : null;
|
|
169
|
+
const { frames, framesRequested, wallMs } = await runTimeline(page, input, touch);
|
|
138
170
|
const diagnostics = await measureDiagnostics(page, wallMs);
|
|
139
171
|
diagnostics.framesRequested = framesRequested;
|
|
140
172
|
diagnostics.framesCaptured = frames.length;
|
|
@@ -1,3 +1,4 @@
|
|
|
1
1
|
import { type PlaytestExecutor } from './playtest.js';
|
|
2
2
|
export declare function contentGrantFromBrowserUrl(value: string): string | null;
|
|
3
|
+
export declare const REMOTE_TOUCH_UNAVAILABLE = "touch input is not available in the cloud playtest browser yet, so nothing was run and this call was not counted -- use input \"mouse\", and say that touch was not checked";
|
|
3
4
|
export declare function createRemotePlaytestExecutor(browserContentUrl: () => string | null): PlaytestExecutor;
|
|
@@ -29,7 +29,26 @@ export function contentGrantFromBrowserUrl(value) {
|
|
|
29
29
|
return null;
|
|
30
30
|
}
|
|
31
31
|
}
|
|
32
|
-
|
|
32
|
+
// Ghost and the browser worker validate a playtest operation key by key, so
|
|
33
|
+
// `input`/`playFile` are sent only when a call needs them, and a refusal of
|
|
34
|
+
// those keys is remembered for the rest of the serve. Ghost answers every
|
|
35
|
+
// validation failure with BROWSER_INVALID_OPERATION; only its unknown-key
|
|
36
|
+
// message, "operation is invalid", is that refusal -- a bad coordinate or
|
|
37
|
+
// timestamp is the call's own mistake and must not switch the extension off.
|
|
38
|
+
// (A worker that refuses the keys after Ghost accepted them fails the job as a
|
|
39
|
+
// generic BROWSER_SERVICE_FAILED, which cannot be told apart, so the host
|
|
40
|
+
// rollout must reach the workers before Ghost.)
|
|
41
|
+
function refusedExtension(error) {
|
|
42
|
+
const { message, extensions } = (error ?? {});
|
|
43
|
+
return (extensions?.code === 'BROWSER_INVALID_OPERATION' &&
|
|
44
|
+
typeof message === 'string' &&
|
|
45
|
+
message.startsWith('operation is invalid ['));
|
|
46
|
+
}
|
|
47
|
+
export const REMOTE_TOUCH_UNAVAILABLE = "touch input is not available in the cloud playtest browser yet, so nothing was run and this call was not counted -- use input \"mouse\", and say that touch was not checked";
|
|
48
|
+
function wantsExtension(input) {
|
|
49
|
+
return input.input === 'touch' || Boolean(input.playFile);
|
|
50
|
+
}
|
|
51
|
+
function operationFromTimeline(input, extended) {
|
|
33
52
|
const actions = [];
|
|
34
53
|
const screenshots = [];
|
|
35
54
|
const keyDown = new Map();
|
|
@@ -59,9 +78,9 @@ function operationFromTimeline(input) {
|
|
|
59
78
|
continue;
|
|
60
79
|
actions.push({
|
|
61
80
|
t: event.t,
|
|
62
|
-
type: event.kind === 'mousedown'
|
|
81
|
+
type: event.kind === 'mousedown' || event.kind === 'touchstart'
|
|
63
82
|
? 'down'
|
|
64
|
-
: event.kind === 'mouseup'
|
|
83
|
+
: event.kind === 'mouseup' || event.kind === 'touchend'
|
|
65
84
|
? 'up'
|
|
66
85
|
: 'move',
|
|
67
86
|
x: event.x,
|
|
@@ -70,7 +89,14 @@ function operationFromTimeline(input) {
|
|
|
70
89
|
}
|
|
71
90
|
}
|
|
72
91
|
actions.sort((a, b) => a.t - b.t);
|
|
73
|
-
return {
|
|
92
|
+
return {
|
|
93
|
+
kind: 'playtest',
|
|
94
|
+
durationMs: input.durationMs,
|
|
95
|
+
actions,
|
|
96
|
+
screenshots,
|
|
97
|
+
...(extended && input.input === 'touch' ? { input: 'touch' } : {}),
|
|
98
|
+
...(extended && input.playFile ? { playFile: input.playFile } : {}),
|
|
99
|
+
};
|
|
74
100
|
}
|
|
75
101
|
function isRecord(value) {
|
|
76
102
|
return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
|
|
@@ -123,6 +149,24 @@ function validRemoteResult(result) {
|
|
|
123
149
|
Boolean(result.diagnostics));
|
|
124
150
|
}
|
|
125
151
|
export function createRemotePlaytestExecutor(browserContentUrl) {
|
|
152
|
+
let extensionRefused = false;
|
|
153
|
+
const submit = async (grant, input) => {
|
|
154
|
+
if (wantsExtension(input) && !extensionRefused) {
|
|
155
|
+
try {
|
|
156
|
+
const result = await api.runBrowserJob(grant, operationFromTimeline(input, true), input.signal);
|
|
157
|
+
return { result: result, degraded: false };
|
|
158
|
+
}
|
|
159
|
+
catch (error) {
|
|
160
|
+
if (!refusedExtension(error))
|
|
161
|
+
throw error;
|
|
162
|
+
extensionRefused = true;
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
if (input.input === 'touch')
|
|
166
|
+
return { refusedTouch: true };
|
|
167
|
+
const result = await api.runBrowserJob(grant, operationFromTimeline(input, false), input.signal);
|
|
168
|
+
return { result: result, degraded: Boolean(input.playFile) };
|
|
169
|
+
};
|
|
126
170
|
return {
|
|
127
171
|
async runSession(input) {
|
|
128
172
|
const contentUrl = browserContentUrl();
|
|
@@ -130,7 +174,10 @@ export function createRemotePlaytestExecutor(browserContentUrl) {
|
|
|
130
174
|
if (!grant)
|
|
131
175
|
return failed(input, 'the serve could not mint a browser content grant');
|
|
132
176
|
try {
|
|
133
|
-
const
|
|
177
|
+
const submitted = await submit(grant, input);
|
|
178
|
+
if ('refusedTouch' in submitted)
|
|
179
|
+
return { ...failed(input, REMOTE_TOUCH_UNAVAILABLE), unsupported: true };
|
|
180
|
+
const { result, degraded } = submitted;
|
|
134
181
|
if (!result.ok) {
|
|
135
182
|
if (!validFailureDiagnostics(result)) {
|
|
136
183
|
return failed(input, 'browser worker returned invalid failure diagnostics');
|
|
@@ -151,6 +198,15 @@ export function createRemotePlaytestExecutor(browserContentUrl) {
|
|
|
151
198
|
})),
|
|
152
199
|
console: result.console,
|
|
153
200
|
diagnostics: result.diagnostics,
|
|
201
|
+
...(degraded
|
|
202
|
+
? {
|
|
203
|
+
environment: {
|
|
204
|
+
playFile: null,
|
|
205
|
+
input: 'mouse',
|
|
206
|
+
note: `the cloud playtest browser cannot open a play file yet, so it loaded the entry point instead of ${input.playFile}. What the user's Play panel shows may differ.`,
|
|
207
|
+
},
|
|
208
|
+
}
|
|
209
|
+
: {}),
|
|
154
210
|
};
|
|
155
211
|
}
|
|
156
212
|
catch (error) {
|
|
@@ -12,6 +12,9 @@ export declare const PLAYTEST_MAX_CONSOLE_TEXT_BYTES: number;
|
|
|
12
12
|
export declare const PLAYTEST_FAILURE_CONSOLE_TEXT_MAX_BYTES = 1024;
|
|
13
13
|
export declare const PLAYTEST_FAILURE_OUTPUT_MAX_BYTES: number;
|
|
14
14
|
export type PlaytestActionType = "down" | "move" | "up" | "tap" | "key";
|
|
15
|
+
export type PlaytestInput = "mouse" | "touch";
|
|
16
|
+
export declare const PLAYTEST_INPUTS: readonly PlaytestInput[];
|
|
17
|
+
export declare const PLAYTEST_ENTRY_FILE = "index.html";
|
|
15
18
|
export interface PlaytestActionRaw {
|
|
16
19
|
t: number;
|
|
17
20
|
type: PlaytestActionType;
|
|
@@ -24,12 +27,19 @@ export interface PlaytestArgs {
|
|
|
24
27
|
durationMs: number;
|
|
25
28
|
actions: PlaytestActionRaw[];
|
|
26
29
|
screenshots: number[];
|
|
30
|
+
input?: PlaytestInput;
|
|
31
|
+
playFile?: string;
|
|
27
32
|
}
|
|
28
33
|
export type TimelineEvent = {
|
|
29
34
|
t: number;
|
|
30
35
|
kind: "mousemove" | "mousedown" | "mouseup";
|
|
31
36
|
x: number;
|
|
32
37
|
y: number;
|
|
38
|
+
} | {
|
|
39
|
+
t: number;
|
|
40
|
+
kind: "touchstart" | "touchmove" | "touchend";
|
|
41
|
+
x: number;
|
|
42
|
+
y: number;
|
|
33
43
|
} | {
|
|
34
44
|
t: number;
|
|
35
45
|
kind: "keydown" | "keyup";
|
|
@@ -47,7 +57,7 @@ export declare function validatePlaytestArgs(args: Record<string, unknown>): {
|
|
|
47
57
|
ok: false;
|
|
48
58
|
error: string;
|
|
49
59
|
};
|
|
50
|
-
export declare function buildTimeline(args: PlaytestArgs): TimelineEvent[];
|
|
60
|
+
export declare function buildTimeline(args: PlaytestArgs, input?: PlaytestInput): TimelineEvent[];
|
|
51
61
|
export interface PlaytestDiagnostics {
|
|
52
62
|
rafTicks: number;
|
|
53
63
|
wallMs: number;
|
|
@@ -70,7 +80,20 @@ export declare function captureReport(frames: PlaytestFrame[], d: PlaytestDiagno
|
|
|
70
80
|
expectedTicks: number;
|
|
71
81
|
lines: string[];
|
|
72
82
|
};
|
|
73
|
-
export declare function playtestDeckUrl(serveOrigin: string): string;
|
|
83
|
+
export declare function playtestDeckUrl(serveOrigin: string, playFile?: string | null): string;
|
|
84
|
+
export interface PlayTarget {
|
|
85
|
+
playFile: string | null;
|
|
86
|
+
source: "declared" | "requested" | "entry";
|
|
87
|
+
declared: string | null;
|
|
88
|
+
note?: string;
|
|
89
|
+
}
|
|
90
|
+
export declare function resolvePlayTarget(deckDir: string, requested: string | undefined): {
|
|
91
|
+
ok: true;
|
|
92
|
+
target: PlayTarget;
|
|
93
|
+
} | {
|
|
94
|
+
ok: false;
|
|
95
|
+
error: string;
|
|
96
|
+
};
|
|
74
97
|
export interface PlaytestConsoleEntry {
|
|
75
98
|
t: number;
|
|
76
99
|
phase: "load" | "settle" | "session";
|
|
@@ -95,6 +118,8 @@ export type PlaytestInstallEvent = {
|
|
|
95
118
|
};
|
|
96
119
|
export interface PlaytestSessionInput {
|
|
97
120
|
url: string;
|
|
121
|
+
playFile: string | null;
|
|
122
|
+
input: PlaytestInput;
|
|
98
123
|
durationMs: number;
|
|
99
124
|
timeline: TimelineEvent[];
|
|
100
125
|
signal?: AbortSignal;
|
|
@@ -113,6 +138,12 @@ export interface PlaytestSessionResult {
|
|
|
113
138
|
truncation?: PlaytestTruncation;
|
|
114
139
|
diagnostics: PlaytestDiagnostics;
|
|
115
140
|
browserInstallMs?: number;
|
|
141
|
+
environment?: {
|
|
142
|
+
playFile: string | null;
|
|
143
|
+
input: PlaytestInput;
|
|
144
|
+
note: string;
|
|
145
|
+
};
|
|
146
|
+
unsupported?: boolean;
|
|
116
147
|
}
|
|
117
148
|
export interface PlaytestExecutor {
|
|
118
149
|
runSession(input: PlaytestSessionInput): Promise<PlaytestSessionResult>;
|
|
@@ -126,6 +157,7 @@ export interface PlaytestToolContext {
|
|
|
126
157
|
};
|
|
127
158
|
onProgress?: (label: string) => void;
|
|
128
159
|
onInstallEvent?: (evt: PlaytestInstallEvent) => void;
|
|
160
|
+
defaultInput?: PlaytestInput;
|
|
129
161
|
}
|
|
130
162
|
export interface PlaytestToolResult {
|
|
131
163
|
ok: boolean;
|
|
@@ -137,6 +169,7 @@ export interface PlaytestToolResult {
|
|
|
137
169
|
playtestFrames?: string[];
|
|
138
170
|
activitySummary?: string;
|
|
139
171
|
}
|
|
172
|
+
export declare function environmentLines(target: PlayTarget, input: PlaytestInput, session: Pick<PlaytestSessionResult, "viewport" | "environment">): string[];
|
|
140
173
|
export declare function runPlaytest(args: Record<string, unknown>, deckDir: string, ctx: PlaytestToolContext | undefined, signal: AbortSignal | undefined): Promise<PlaytestToolResult>;
|
|
141
174
|
export declare const PLAYTEST_TOOL_DESCRIPTION: string;
|
|
142
175
|
export declare const PLAYTEST_TOOL_PARAMETERS: Record<string, unknown>;
|
package/dist/native/playtest.js
CHANGED
|
@@ -17,6 +17,8 @@
|
|
|
17
17
|
// iframe posts back to one a Playwright page reports directly.
|
|
18
18
|
import * as fs from "fs";
|
|
19
19
|
import * as path from "path";
|
|
20
|
+
import { normalizePlayFile, readEditorConfig } from "../editorConfig.js";
|
|
21
|
+
import { playPagePath } from "../playUrl.js";
|
|
20
22
|
// -- caps + fixed geometry ------------------------------------------------------
|
|
21
23
|
// Ratified constants. The viewport is FIXED (not per-deck): every digest and
|
|
22
24
|
// the schema description both state it, so the model never has to guess
|
|
@@ -36,6 +38,8 @@ export const PLAYTEST_MAX_CONSOLE_ENTRIES = 100;
|
|
|
36
38
|
export const PLAYTEST_MAX_CONSOLE_TEXT_BYTES = 8 * 1024;
|
|
37
39
|
export const PLAYTEST_FAILURE_CONSOLE_TEXT_MAX_BYTES = 1_024;
|
|
38
40
|
export const PLAYTEST_FAILURE_OUTPUT_MAX_BYTES = 40 * 1024;
|
|
41
|
+
export const PLAYTEST_INPUTS = ["mouse", "touch"];
|
|
42
|
+
export const PLAYTEST_ENTRY_FILE = "index.html";
|
|
39
43
|
function isFiniteNumber(v) {
|
|
40
44
|
return typeof v === "number" && Number.isFinite(v);
|
|
41
45
|
}
|
|
@@ -160,17 +164,45 @@ export function validatePlaytestArgs(args) {
|
|
|
160
164
|
screenshots.push(v);
|
|
161
165
|
}
|
|
162
166
|
}
|
|
163
|
-
|
|
167
|
+
let input;
|
|
168
|
+
if (args.input !== undefined) {
|
|
169
|
+
if (!PLAYTEST_INPUTS.includes(args.input)) {
|
|
170
|
+
return { ok: false, error: `input must be one of ${PLAYTEST_INPUTS.join("/")}, got ${JSON.stringify(args.input)}` };
|
|
171
|
+
}
|
|
172
|
+
input = args.input;
|
|
173
|
+
}
|
|
174
|
+
let playFile;
|
|
175
|
+
if (args.playFile !== undefined) {
|
|
176
|
+
if (typeof args.playFile !== "string" || !args.playFile.trim()) {
|
|
177
|
+
return { ok: false, error: "playFile must be a non-empty deck-relative path when given" };
|
|
178
|
+
}
|
|
179
|
+
playFile = args.playFile.trim();
|
|
180
|
+
}
|
|
181
|
+
return {
|
|
182
|
+
ok: true,
|
|
183
|
+
value: {
|
|
184
|
+
durationMs,
|
|
185
|
+
actions,
|
|
186
|
+
screenshots,
|
|
187
|
+
...(input ? { input } : {}),
|
|
188
|
+
...(playFile ? { playFile } : {}),
|
|
189
|
+
},
|
|
190
|
+
};
|
|
164
191
|
}
|
|
165
192
|
// Expands tap/key sugar into raw primitives and merges in screenshot
|
|
166
193
|
// requests, stable-sorted by t (ties: actions before screenshots, so a shot
|
|
167
194
|
// requested at the same timestamp as an action captures its effect).
|
|
168
|
-
|
|
195
|
+
const POINTER_KINDS = {
|
|
196
|
+
mouse: { down: "mousedown", move: "mousemove", up: "mouseup" },
|
|
197
|
+
touch: { down: "touchstart", move: "touchmove", up: "touchend" },
|
|
198
|
+
};
|
|
199
|
+
export function buildTimeline(args, input = "mouse") {
|
|
200
|
+
const kinds = POINTER_KINDS[input];
|
|
169
201
|
const events = [];
|
|
170
202
|
for (const a of args.actions) {
|
|
171
203
|
if (a.type === "tap") {
|
|
172
|
-
events.push({ t: a.t, kind:
|
|
173
|
-
events.push({ t: a.t, kind:
|
|
204
|
+
events.push({ t: a.t, kind: kinds.down, x: a.x, y: a.y });
|
|
205
|
+
events.push({ t: a.t, kind: kinds.up, x: a.x, y: a.y });
|
|
174
206
|
}
|
|
175
207
|
else if (a.type === "key") {
|
|
176
208
|
const holdMs = a.durationMs ?? PLAYTEST_DEFAULT_KEY_DURATION_MS;
|
|
@@ -178,8 +210,7 @@ export function buildTimeline(args) {
|
|
|
178
210
|
events.push({ t: a.t + holdMs, kind: "keyup", key: a.key });
|
|
179
211
|
}
|
|
180
212
|
else {
|
|
181
|
-
|
|
182
|
-
events.push({ t: a.t, kind, x: a.x, y: a.y });
|
|
213
|
+
events.push({ t: a.t, kind: kinds[a.type], x: a.x, y: a.y });
|
|
183
214
|
}
|
|
184
215
|
}
|
|
185
216
|
for (const t of args.screenshots)
|
|
@@ -228,8 +259,55 @@ export function captureReport(frames, d) {
|
|
|
228
259
|
// (`logs=1`, the postMessage console forwarder for the shell's logs drawer)
|
|
229
260
|
// is deliberately NOT mirrored: its inject bails on a top-level page, and
|
|
230
261
|
// Playwright captures console output natively.
|
|
231
|
-
export function playtestDeckUrl(serveOrigin) {
|
|
232
|
-
return `${serveOrigin.replace(/\/+$/, "")}
|
|
262
|
+
export function playtestDeckUrl(serveOrigin, playFile = null) {
|
|
263
|
+
return `${serveOrigin.replace(/\/+$/, "")}${playPagePath(playFile)}`;
|
|
264
|
+
}
|
|
265
|
+
function declaredTarget(deckDir) {
|
|
266
|
+
const config = readEditorConfig(deckDir);
|
|
267
|
+
const declared = config.defaultPlayFile ?? null;
|
|
268
|
+
if (declared) {
|
|
269
|
+
const abs = path.join(path.resolve(deckDir), declared);
|
|
270
|
+
const missing = !fs.existsSync(abs) || !fs.statSync(abs).isFile();
|
|
271
|
+
return {
|
|
272
|
+
playFile: declared,
|
|
273
|
+
source: "declared",
|
|
274
|
+
declared,
|
|
275
|
+
...(missing
|
|
276
|
+
? { note: `the deck's defaultPlayFile ${declared} is not a file in this deck. The page was asked for it anyway, as the Play panel asks; what it shows then is up to the deck.` }
|
|
277
|
+
: {}),
|
|
278
|
+
};
|
|
279
|
+
}
|
|
280
|
+
const refused = config.defaultPlayFileRefused;
|
|
281
|
+
return {
|
|
282
|
+
playFile: null,
|
|
283
|
+
source: "entry",
|
|
284
|
+
declared: null,
|
|
285
|
+
...(refused
|
|
286
|
+
? { note: `the deck's defaultPlayFile ${JSON.stringify(refused.value)} was not used because ${refused.reason}, so this opened the entry point -- as the Play panel does.` }
|
|
287
|
+
: {}),
|
|
288
|
+
};
|
|
289
|
+
}
|
|
290
|
+
export function resolvePlayTarget(deckDir, requested) {
|
|
291
|
+
const fromDeck = declaredTarget(deckDir);
|
|
292
|
+
const declared = fromDeck.declared;
|
|
293
|
+
if (requested === undefined)
|
|
294
|
+
return { ok: true, target: fromDeck };
|
|
295
|
+
const normalized = normalizePlayFile(deckDir, requested);
|
|
296
|
+
if (!normalized.ok) {
|
|
297
|
+
return { ok: false, error: `playFile ${JSON.stringify(requested)} cannot be opened: ${normalized.reason}` };
|
|
298
|
+
}
|
|
299
|
+
if (normalized.path === PLAYTEST_ENTRY_FILE) {
|
|
300
|
+
return { ok: true, target: { playFile: null, source: "entry", declared } };
|
|
301
|
+
}
|
|
302
|
+
const inside = normalized.path;
|
|
303
|
+
const abs = path.join(path.resolve(deckDir), inside);
|
|
304
|
+
if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) {
|
|
305
|
+
return {
|
|
306
|
+
ok: false,
|
|
307
|
+
error: `playFile ${JSON.stringify(requested)} is not a file in this deck. Omit playFile to open what the Play panel opens (${declared ?? `${PLAYTEST_ENTRY_FILE}, the entry point`}), or pass "${PLAYTEST_ENTRY_FILE}" for the entry point with no play file.`,
|
|
308
|
+
};
|
|
309
|
+
}
|
|
310
|
+
return { ok: true, target: { playFile: inside, source: "requested", declared } };
|
|
233
311
|
}
|
|
234
312
|
const CONSOLE_LOG_CAP = 20;
|
|
235
313
|
function truncateUtf8(value, maxBytes) {
|
|
@@ -271,10 +349,38 @@ function buildFailureOutput(session) {
|
|
|
271
349
|
}
|
|
272
350
|
return truncateUtf8(lines.join("\n"), PLAYTEST_FAILURE_OUTPUT_MAX_BYTES);
|
|
273
351
|
}
|
|
352
|
+
function openedLine(playFile, target) {
|
|
353
|
+
const panel = target.declared ?? `${PLAYTEST_ENTRY_FILE}, the entry point`;
|
|
354
|
+
if (playFile === null) {
|
|
355
|
+
return `Opened: ${PLAYTEST_ENTRY_FILE}, the deck's entry point with no play file -- how a published deck starts. ${target.declared ? `The user's Play panel opens ${target.declared} instead.` : "The user's Play panel opens the same."}`;
|
|
356
|
+
}
|
|
357
|
+
if (playFile === target.declared) {
|
|
358
|
+
return `Opened: ${playFile}, the deck's defaultPlayFile -- what the user's Play panel opens unless they picked another file in it. A published deck starts at ${PLAYTEST_ENTRY_FILE} with no play file (playFile "${PLAYTEST_ENTRY_FILE}" opens that).`;
|
|
359
|
+
}
|
|
360
|
+
return `Opened: ${playFile}, as requested. The user's Play panel opens ${panel}.`;
|
|
361
|
+
}
|
|
362
|
+
// Says where the frames came from, so a report can name it: a headless
|
|
363
|
+
// preview is evidence about the preview, not about the user's phone.
|
|
364
|
+
export function environmentLines(target, input, session) {
|
|
365
|
+
const actual = session.environment;
|
|
366
|
+
const drove = (actual?.input ?? input) === "touch"
|
|
367
|
+
? "touch emulated (touchscreen, mobile viewport, pixel ratio 1)"
|
|
368
|
+
: "mouse and keyboard";
|
|
369
|
+
const lines = [
|
|
370
|
+
`Environment: headless Chromium, ${session.viewport.width}x${session.viewport.height} viewport, ${drove}. Not the user's device, browser, or app -- report what this shows as seen in the headless preview.`,
|
|
371
|
+
openedLine(actual ? actual.playFile : target.playFile, target),
|
|
372
|
+
];
|
|
373
|
+
if (target.note)
|
|
374
|
+
lines.push(`Note: ${target.note}`);
|
|
375
|
+
if (actual)
|
|
376
|
+
lines.push(`Note: ${actual.note}`);
|
|
377
|
+
return lines;
|
|
378
|
+
}
|
|
274
379
|
function buildDigest(opts) {
|
|
275
|
-
const { callIndex, args, session, report, persisted } = opts;
|
|
380
|
+
const { callIndex, args, target, input, session, report, persisted } = opts;
|
|
276
381
|
const lines = [
|
|
277
|
-
`Playtest call ${callIndex}/${PLAYTEST_MAX_CALLS_PER_RUN} -- ${
|
|
382
|
+
`Playtest call ${callIndex}/${PLAYTEST_MAX_CALLS_PER_RUN} -- ${args.durationMs}ms session (${args.actions.length} action(s), ${args.screenshots.length} screenshot(s) requested).`,
|
|
383
|
+
...environmentLines(target, input, session),
|
|
278
384
|
];
|
|
279
385
|
lines.push("Frames:");
|
|
280
386
|
for (const p of persisted)
|
|
@@ -296,11 +402,27 @@ function buildDigest(opts) {
|
|
|
296
402
|
lines.push(` ${fmtConsolePhase(entry)}`);
|
|
297
403
|
}
|
|
298
404
|
const distinctNote = persisted.length > 1 ? `${report.distinct} distinct` : `${report.distinct}`;
|
|
299
|
-
const
|
|
405
|
+
const actualInput = session.environment?.input ?? input;
|
|
406
|
+
const actualFile = session.environment ? session.environment.playFile : target.playFile;
|
|
407
|
+
const activitySummary = `Playtested ${args.durationMs}ms (${actualInput}, ${actualFile ?? PLAYTEST_ENTRY_FILE}): ${persisted.length} frame(s), ${distinctNote}` +
|
|
300
408
|
(errorCount > 0 ? `, ${errorCount} console error(s)` : "") +
|
|
301
409
|
(report.starved ? " [CAPTURE STARVED -- retry]" : "");
|
|
302
410
|
return { text: lines.join("\n"), activitySummary };
|
|
303
411
|
}
|
|
412
|
+
// The prefix a call's frames are saved under: one past the highest already in
|
|
413
|
+
// the dir, not the budget count. The budget count can repeat -- a refused call
|
|
414
|
+
// is given back, and a retried run starts a fresh budget in the same dir -- and
|
|
415
|
+
// a repeat would overwrite frames a task card already links. Read and written
|
|
416
|
+
// in one synchronous stretch, so concurrent calls cannot pick the same prefix.
|
|
417
|
+
function nextFrameSet(framesDir) {
|
|
418
|
+
let highest = 0;
|
|
419
|
+
for (const name of fs.readdirSync(framesDir)) {
|
|
420
|
+
const match = /^(\d+)-\d+(?:\.\d+)?\.png$/.exec(name);
|
|
421
|
+
if (match)
|
|
422
|
+
highest = Math.max(highest, Number(match[1]));
|
|
423
|
+
}
|
|
424
|
+
return highest + 1;
|
|
425
|
+
}
|
|
304
426
|
export async function runPlaytest(args, deckDir, ctx, signal) {
|
|
305
427
|
if (!ctx) {
|
|
306
428
|
return {
|
|
@@ -311,6 +433,11 @@ export async function runPlaytest(args, deckDir, ctx, signal) {
|
|
|
311
433
|
const parsed = validatePlaytestArgs(args);
|
|
312
434
|
if (!parsed.ok)
|
|
313
435
|
return { ok: false, output: `Error: ${parsed.error}` };
|
|
436
|
+
const resolved = resolvePlayTarget(deckDir, parsed.value.playFile);
|
|
437
|
+
if (!resolved.ok)
|
|
438
|
+
return { ok: false, output: `Error: ${resolved.error}` };
|
|
439
|
+
const target = resolved.target;
|
|
440
|
+
const input = parsed.value.input ?? ctx.defaultInput ?? "mouse";
|
|
314
441
|
if (ctx.callCount.value >= PLAYTEST_MAX_CALLS_PER_RUN) {
|
|
315
442
|
return {
|
|
316
443
|
ok: false,
|
|
@@ -319,15 +446,21 @@ export async function runPlaytest(args, deckDir, ctx, signal) {
|
|
|
319
446
|
}
|
|
320
447
|
ctx.callCount.value += 1;
|
|
321
448
|
const callIndex = ctx.callCount.value;
|
|
322
|
-
const timeline = buildTimeline(parsed.value);
|
|
449
|
+
const timeline = buildTimeline(parsed.value, input);
|
|
323
450
|
const session = await ctx.executor.runSession({
|
|
324
|
-
url: playtestDeckUrl(ctx.serveUrl),
|
|
451
|
+
url: playtestDeckUrl(ctx.serveUrl, target.playFile),
|
|
452
|
+
playFile: target.playFile,
|
|
453
|
+
input,
|
|
325
454
|
durationMs: parsed.value.durationMs,
|
|
326
455
|
timeline,
|
|
327
456
|
signal,
|
|
328
457
|
onProgress: ctx.onProgress,
|
|
329
458
|
onInstallEvent: ctx.onInstallEvent,
|
|
330
459
|
});
|
|
460
|
+
if (!session.ok && session.unsupported) {
|
|
461
|
+
ctx.callCount.value -= 1;
|
|
462
|
+
return { ok: false, output: `Error: ${session.error}` };
|
|
463
|
+
}
|
|
331
464
|
if (!session.ok) {
|
|
332
465
|
return {
|
|
333
466
|
ok: false,
|
|
@@ -335,20 +468,21 @@ export async function runPlaytest(args, deckDir, ctx, signal) {
|
|
|
335
468
|
};
|
|
336
469
|
}
|
|
337
470
|
fs.mkdirSync(ctx.framesDir, { recursive: true });
|
|
471
|
+
const frameSet = nextFrameSet(ctx.framesDir);
|
|
338
472
|
const persisted = [];
|
|
339
473
|
for (const frame of session.frames) {
|
|
340
|
-
const filename = `${
|
|
474
|
+
const filename = `${frameSet}-${frame.t}.png`;
|
|
341
475
|
const absPath = path.join(ctx.framesDir, filename);
|
|
342
476
|
fs.writeFileSync(absPath, frame.png);
|
|
343
477
|
persisted.push({ t: frame.t, relPath: path.relative(deckDir, absPath).split(path.sep).join("/") });
|
|
344
478
|
}
|
|
345
479
|
const report = captureReport(session.frames, session.diagnostics);
|
|
346
|
-
const digest = buildDigest({ callIndex, args: parsed.value, session, report, persisted });
|
|
480
|
+
const digest = buildDigest({ callIndex, args: parsed.value, target, input, session, report, persisted });
|
|
347
481
|
return {
|
|
348
482
|
ok: true,
|
|
349
483
|
output: digest.text,
|
|
350
484
|
images: session.frames.map((f) => ({
|
|
351
|
-
label: `playtest call ${callIndex} frame t=${f.t}ms`,
|
|
485
|
+
label: `playtest call ${callIndex} frame t=${f.t}ms (${frameSet}-${f.t}.png)`,
|
|
352
486
|
dataUrl: `data:image/png;base64,${f.png.toString("base64")}`,
|
|
353
487
|
})),
|
|
354
488
|
playtestFrames: persisted.map((p) => p.relPath),
|
|
@@ -357,9 +491,10 @@ export async function runPlaytest(args, deckDir, ctx, signal) {
|
|
|
357
491
|
}
|
|
358
492
|
// -- tool schema (model-facing) ------------------------------------------------
|
|
359
493
|
export const PLAYTEST_TOOL_DESCRIPTION = [
|
|
360
|
-
`Load the served deck in a real headless browser, optionally drive timed mouse
|
|
494
|
+
`Load the served deck in a real headless browser (Chromium, not the user's device), optionally drive timed mouse, touch, or keyboard input, and capture screenshots + console/error output. Use this after changing behavior or visuals to actually SEE what you built, not just read the code back.`,
|
|
495
|
+
`It opens what the user's Play panel opens (the deck's declared play file, else its entry point); playFile opens another deck file instead, and "${PLAYTEST_ENTRY_FILE}" opens the entry point with no play file, as a published deck starts. input "touch" emulates a phone touchscreen: down/move/up/tap arrive as touch events, which touch-only controls need.`,
|
|
361
496
|
`Coordinates (x/y) are CSS pixels in a FIXED ${PLAYTEST_VIEWPORT.width}x${PLAYTEST_VIEWPORT.height} viewport, regardless of the deck's own canvas size.`,
|
|
362
|
-
`durationMs is the session length (ms, up to ${PLAYTEST_MAX_DURATION_MS}). actions (up to ${PLAYTEST_MAX_ACTIONS}) are timed inputs: {t,type:"down"|"move"|"up",x,y} raw mouse
|
|
497
|
+
`durationMs is the session length (ms, up to ${PLAYTEST_MAX_DURATION_MS}). actions (up to ${PLAYTEST_MAX_ACTIONS}) are timed inputs: {t,type:"down"|"move"|"up",x,y} raw pointer primitives (mouse or touch, per input), {t,type:"tap",x,y} (down+up sugar), or {t,type:"key",key,durationMs?} (keydown at t, keyup at t+durationMs, default ${PLAYTEST_DEFAULT_KEY_DURATION_MS}ms -- overlapping holds are fine). screenshots (up to ${PLAYTEST_MAX_SHOTS} timestamps in ms) default to [0, durationMs].`,
|
|
363
498
|
`The result is a text digest (frame list, console/error log, capture-health) plus the actual frame images delivered right after. A "capture starved" warning means the CAPTURE wasn't rendering (throttled/dead browser) -- that is not proof the game is broken; retry before concluding anything. This tool is capped at ${PLAYTEST_MAX_CALLS_PER_RUN} calls per run.`,
|
|
364
499
|
].join(" ");
|
|
365
500
|
export const PLAYTEST_TOOL_PARAMETERS = {
|
|
@@ -395,6 +530,15 @@ export const PLAYTEST_TOOL_PARAMETERS = {
|
|
|
395
530
|
items: { type: "integer" },
|
|
396
531
|
description: `Up to ${PLAYTEST_MAX_SHOTS} timestamps (ms) to screenshot at. Defaults to [0, durationMs].`,
|
|
397
532
|
},
|
|
533
|
+
input: {
|
|
534
|
+
type: "string",
|
|
535
|
+
enum: [...PLAYTEST_INPUTS],
|
|
536
|
+
description: `"mouse" (default) or "touch" (emulated touchscreen; down/move/up/tap become touch events).`,
|
|
537
|
+
},
|
|
538
|
+
playFile: {
|
|
539
|
+
type: "string",
|
|
540
|
+
description: `Deck-relative file to open instead of what the Play panel opens. "${PLAYTEST_ENTRY_FILE}" = the entry point with no play file.`,
|
|
541
|
+
},
|
|
398
542
|
},
|
|
399
543
|
required: ["durationMs"],
|
|
400
544
|
};
|
package/dist/platformDoc.d.ts
CHANGED
|
@@ -2,6 +2,7 @@ export declare const PLATFORM_DOCS_DIR: string;
|
|
|
2
2
|
export declare const PLATFORM_DOC_REL: string;
|
|
3
3
|
export declare const MULTIPLAYER_DOC_REL: string;
|
|
4
4
|
export declare function everyDeckBullets(deckDir: string): string[];
|
|
5
|
+
export declare const HOST_LIMIT_BULLETS: string[];
|
|
5
6
|
export type AgentRole = 'router' | 'task';
|
|
6
7
|
export declare function roleLoadsClaudeMd(role: AgentRole): boolean;
|
|
7
8
|
export declare function claudeContextEnv(role: AgentRole): NodeJS.ProcessEnv;
|
package/dist/platformDoc.js
CHANGED
|
@@ -68,6 +68,20 @@ export function everyDeckBullets(deckDir) {
|
|
|
68
68
|
MODE_BULLET,
|
|
69
69
|
];
|
|
70
70
|
}
|
|
71
|
+
// Routers are told never to call something impossible without checking their
|
|
72
|
+
// context, so a host limit missing from it gets "fixed" task after task
|
|
73
|
+
// (frustration survey B1). Only facts about the hosts themselves live here;
|
|
74
|
+
// what depends on the SDK (storage caps, which command needs which app build)
|
|
75
|
+
// ships in sdk/README.md, so it cannot go stale when the SDK changes. Each
|
|
76
|
+
// bullet is a claim about castle-client, castle-www or ghost-server code, with
|
|
77
|
+
// pointers in memo 26-09-24-16-30-host-limits-verified-from-code: re-verify
|
|
78
|
+
// one when its host changes.
|
|
79
|
+
export const HOST_LIMIT_BULLETS = [
|
|
80
|
+
"- **Where a deck runs decides what it can do.** The Play panel runs it from this serve; players run the published deck in the Castle app (iOS, Android) or castle.xyz's web player. When something works in one and fails in another, check it against the limits below before another fix: if one covers it, name that limit instead of retrying, and ask where they run it if you do not know. If none does, it is an ordinary deck bug (a runtime `fetch` of a loose file, a control that only answers a mouse) and gets fixed.",
|
|
81
|
+
"- **Microphone and camera are blocked in the Play panel and on castle.xyz**: neither frame is granted them, so `getUserMedia` rejects with `NotAllowedError` whatever the person allows, and no deck change helps. The Android app's published deck can use them; the iOS app is untested.",
|
|
82
|
+
"- **A published deck loads almost nothing from the network.** Its CSP allows images, audio and video only from the deck itself, `data:` or `blob:`, `fetch` only to esm.sh, cdnjs.cloudflare.com and Castle's multiplayer hosts, and no iframes. The Play panel sets no CSP, so a remote URL that works there fails once published. Bundle the file, or let the player pick one with `<input type=\"file\">`.",
|
|
83
|
+
"- **An older Castle app build rejects SDK commands newer than the build**, with a `CastleError` whose `code` is `UNKNOWN_COMMAND`; only an app update fixes that, so the deck should catch it and keep working. Which commands need which app build, and every other limit of a Castle service, is in the SDK reference, `imports/castle.base/sdk/README.md`.",
|
|
84
|
+
];
|
|
71
85
|
// The line has to stand on its own to count: this repo's CLAUDE.md names the
|
|
72
86
|
// path inside a sentence, and prose about the import must not read as a deck
|
|
73
87
|
// carrying one.
|
|
@@ -100,12 +114,14 @@ function deckLoadsGuide(deckDir) {
|
|
|
100
114
|
const RESTATEMENT_MARKER = '**Supported media formats are exactly**';
|
|
101
115
|
// The every-deck bullets after a quick reference that lacks them. Skipped when
|
|
102
116
|
// the deck's kit is pinned to a version that still restates them, which would
|
|
103
|
-
// otherwise say all of it twice.
|
|
117
|
+
// otherwise say all of it twice. No kit ever restated the host limits, so they
|
|
118
|
+
// come either way.
|
|
104
119
|
function withEveryDeckBullets(deckDir, quickReference) {
|
|
105
120
|
const own = quickReference.trim();
|
|
121
|
+
const hostLimits = HOST_LIMIT_BULLETS.join('\n');
|
|
106
122
|
if (own.includes(RESTATEMENT_MARKER))
|
|
107
|
-
return
|
|
108
|
-
const bullets = everyDeckBullets(deckDir).join('\n');
|
|
123
|
+
return `${own}\n\n${hostLimits}`;
|
|
124
|
+
const bullets = [...everyDeckBullets(deckDir), ...HOST_LIMIT_BULLETS].join('\n');
|
|
109
125
|
return own ? `${own}\n\n${bullets}` : bullets;
|
|
110
126
|
}
|
|
111
127
|
// Whether a role's claude process auto-loads the deck's CLAUDE.md, and with it
|
|
@@ -213,6 +229,7 @@ const COMMON_SECTIONS = `## Imports are read-only
|
|
|
213
229
|
|
|
214
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.
|
|
215
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 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\`.
|
|
216
233
|
- **The server module default-exports lifecycle callbacks**, each taking the session first:
|
|
217
234
|
|
|
218
235
|
\`\`\`js
|
|
@@ -270,6 +287,10 @@ ${everyDeckBullets(deckDir).filter((b) => !b.includes('PARAMS')).join('\n')}
|
|
|
270
287
|
## Tunable values and the Parameters panel
|
|
271
288
|
|
|
272
289
|
${everyDeckBullets(deckDir).filter((b) => b.includes('PARAMS')).join('\n')}
|
|
290
|
+
|
|
291
|
+
## Host limits
|
|
292
|
+
|
|
293
|
+
${HOST_LIMIT_BULLETS.join('\n')}
|
|
273
294
|
`;
|
|
274
295
|
}
|
|
275
296
|
function platformDoc(deckDir) {
|