castle-web-cli 0.4.208 → 0.4.209
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 +151 -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/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/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 +48 -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 +67 -0
- package/kits/base/sdk/multiplayerVoice.js +309 -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
|
@@ -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 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\`.
|
|
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) {
|
package/dist/playUrl.js
ADDED
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
// The deck page a play surface loads: the shell's Play panel iframes it, and the
|
|
2
|
+
// playtest tool opens it headless. Both build it here so a task's playtest opens
|
|
3
|
+
// exactly what the user's Play panel opens. `scene` is the query name kits read
|
|
4
|
+
// the play file from; the platform only passes the declared file through.
|
|
5
|
+
export function playPagePath(playFile, opts = {}) {
|
|
6
|
+
const query = ['edit=0'];
|
|
7
|
+
if (opts.logs)
|
|
8
|
+
query.push('logs=1');
|
|
9
|
+
if (playFile)
|
|
10
|
+
query.push(`scene=${encodeURIComponent(playFile)}`);
|
|
11
|
+
return `/index.html?${query.join('&')}`;
|
|
12
|
+
}
|
package/dist/save-deck.js
CHANGED
|
@@ -173,6 +173,7 @@ async function publishServerBundle(projectDir, deckId) {
|
|
|
173
173
|
const saved = await api.saveCauldronServerBundle(deckId, uploadConfig.uploadId, {
|
|
174
174
|
tickRate: serverConfig.tickRate,
|
|
175
175
|
maxPlayers: serverConfig.maxPlayers,
|
|
176
|
+
voice: { enabled: serverConfig.voiceEnabled },
|
|
176
177
|
});
|
|
177
178
|
// The server hashes what it actually stored. A mismatch means the bytes that
|
|
178
179
|
// will run in sessions are not the bytes we bundled.
|