castle-web-cli 0.4.236 → 0.4.237

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 CHANGED
@@ -166,6 +166,8 @@ export interface CauldronServerConfig {
166
166
  voice: {
167
167
  enabled: boolean;
168
168
  };
169
+ /** castle.json `server.placeMaxPlayers`; sent only when declared. */
170
+ placeMaxPlayers?: number;
169
171
  destinations?: Array<{
170
172
  routeId: string;
171
173
  access: 'player' | 'party' | 'public';
@@ -26,6 +26,7 @@ export interface CastleJson {
26
26
  main?: string;
27
27
  tickRate?: number;
28
28
  maxPlayers?: number;
29
+ placeMaxPlayers?: number;
29
30
  destinations?: ServerDestinationConfig[];
30
31
  worldNotifications?: ServerWorldNotificationsConfig;
31
32
  };
@@ -81,6 +82,7 @@ export declare const DEFAULT_SERVER_MAX_PLAYERS = 8;
81
82
  export declare const SERVER_TICK_RATE_CAP = 30;
82
83
  export declare const SERVER_MAX_PLAYERS_CAP = 24;
83
84
  export declare const SERVER_DESTINATIONS_CAP = 16;
85
+ export declare const SERVER_PLACE_MAX_PLAYERS_CAP = 100;
84
86
  export interface ServerDestinationConfig {
85
87
  routeId: string;
86
88
  access: 'player' | 'party' | 'public';
@@ -107,6 +109,7 @@ export interface ResolvedServerConfig {
107
109
  tickRate: number;
108
110
  maxPlayers: number;
109
111
  voiceEnabled: boolean;
112
+ placeMaxPlayers?: number;
110
113
  destinations?: ServerDestinationConfig[];
111
114
  worldNotifications?: ServerWorldNotificationsConfig;
112
115
  hub?: ServerHubConfig;
@@ -137,6 +140,21 @@ export interface ServerHubConfig extends ServerHubPlaceConfig {
137
140
  unlocks?: unknown;
138
141
  }
139
142
  export declare function resolveServerConfig(dir: string): ResolvedServerConfig | null;
143
+ /**
144
+ * The config `save-deck` sends with the server bundle. Optional keys go only when
145
+ * declared, so a deck that declares none sends exactly what it always has.
146
+ */
147
+ export declare function serverBundleConfig(serverConfig: ResolvedServerConfig): {
148
+ placeMaxPlayers?: number | undefined;
149
+ hub?: ServerHubConfig | undefined;
150
+ worldNotifications?: ServerWorldNotificationsConfig | undefined;
151
+ destinations?: ServerDestinationConfig[] | undefined;
152
+ tickRate: number;
153
+ maxPlayers: number;
154
+ voice: {
155
+ enabled: boolean;
156
+ };
157
+ };
140
158
  export declare function deckStarterScene(dir: string): string;
141
159
  export declare const DEFAULT_MAIN = "main.jsx";
142
160
  export declare function deckMainFile(dir: string): string;
@@ -157,6 +157,8 @@ export const DEFAULT_SERVER_MAX_PLAYERS = 8;
157
157
  export const SERVER_TICK_RATE_CAP = 30;
158
158
  export const SERVER_MAX_PLAYERS_CAP = 24;
159
159
  export const SERVER_DESTINATIONS_CAP = 16;
160
+ // Ghost's town size class cap (ghost-server CAULDRON_SESSION_SIZE_CLASSES.town).
161
+ export const SERVER_PLACE_MAX_PLAYERS_CAP = 100;
160
162
  // A deck may keep its source under `code/`, so both roots are candidates.
161
163
  const DEFAULT_SERVER_ENTRIES = [
162
164
  'server/index.js',
@@ -180,16 +182,53 @@ export function resolveServerConfig(dir) {
180
182
  const worldNotifications = server?.worldNotifications === undefined
181
183
  ? undefined
182
184
  : validateServerWorldNotifications(server.worldNotifications, destinations);
185
+ const placeMaxPlayers = server?.placeMaxPlayers === undefined
186
+ ? undefined
187
+ : validatePlaceMaxPlayers(server.placeMaxPlayers);
183
188
  return {
184
189
  entry,
185
190
  tickRate: clampNumber(server?.tickRate, DEFAULT_SERVER_TICK_RATE, 0, SERVER_TICK_RATE_CAP),
186
191
  maxPlayers: Math.floor(clampNumber(server?.maxPlayers, DEFAULT_SERVER_MAX_PLAYERS, 1, SERVER_MAX_PLAYERS_CAP)),
187
192
  voiceEnabled: castleJson?.voice?.enabled !== false,
193
+ ...(placeMaxPlayers === undefined ? {} : { placeMaxPlayers }),
188
194
  ...(destinations === undefined ? {} : { destinations }),
189
195
  ...(worldNotifications === undefined ? {} : { worldNotifications }),
190
196
  ...(castleJson?.hub === undefined ? {} : { hub: serverHubConfig(castleJson.hub) }),
191
197
  };
192
198
  }
199
+ function validatePlaceMaxPlayers(value) {
200
+ if (typeof value !== 'number' ||
201
+ !Number.isInteger(value) ||
202
+ value < 1 ||
203
+ value > SERVER_PLACE_MAX_PLAYERS_CAP) {
204
+ throw new Error(`castle.json server.placeMaxPlayers must be an integer from 1 through ` +
205
+ `${SERVER_PLACE_MAX_PLAYERS_CAP} (got ${JSON.stringify(value)}).`);
206
+ }
207
+ return value;
208
+ }
209
+ /**
210
+ * The config `save-deck` sends with the server bundle. Optional keys go only when
211
+ * declared, so a deck that declares none sends exactly what it always has.
212
+ */
213
+ export function serverBundleConfig(serverConfig) {
214
+ return {
215
+ tickRate: serverConfig.tickRate,
216
+ maxPlayers: serverConfig.maxPlayers,
217
+ voice: { enabled: serverConfig.voiceEnabled },
218
+ ...(serverConfig.destinations ? { destinations: serverConfig.destinations } : {}),
219
+ ...(serverConfig.worldNotifications
220
+ ? { worldNotifications: serverConfig.worldNotifications }
221
+ : {}),
222
+ // Sent only for a deck whose castle.json declares a hub place, so every
223
+ // other deck's config is exactly what it was.
224
+ ...(serverConfig.hub ? { hub: serverConfig.hub } : {}),
225
+ // A Ghost without placeMaxPlayers support drops the key (its config
226
+ // normalizer keeps only the keys it knows), so the save still succeeds there.
227
+ ...(serverConfig.placeMaxPlayers === undefined
228
+ ? {}
229
+ : { placeMaxPlayers: serverConfig.placeMaxPlayers }),
230
+ };
231
+ }
193
232
  // `serve` and `check` resolve this too, and the hub block is
194
233
  // checked by the kit at publish and by ghost when it is saved. Invalid push capability
195
234
  // keys are refused here; other blocks that are
package/dist/save-deck.js CHANGED
@@ -6,7 +6,7 @@ import { nanoid } from 'nanoid';
6
6
  import * as api from './api.js';
7
7
  import * as config from './config.js';
8
8
  import { bundleProject, bundleProjectChunked } from './bundle.js';
9
- import { resolveBundleChunks, resolveServerConfig, validateExperiments, } from './castleJson.js';
9
+ import { resolveBundleChunks, resolveServerConfig, serverBundleConfig, validateExperiments, } from './castleJson.js';
10
10
  import { importChecksFailedMessage, runImportChecks } from './importCheckHook.js';
11
11
  import { selectSaveCover } from './saveCover.js';
12
12
  import { COVER_FILE } from './localPaths.js';
@@ -276,18 +276,7 @@ async function publishServerBundle(projectDir, deckId, pack) {
276
276
  const uploadConfig = await api.createCauldronServerBundleUploadConfig(deckId);
277
277
  await uploadPresignedFile(uploadConfig, new Blob([bundle.code], { type: 'application/javascript' }), 'application/javascript', 60_000, 'Server bundle upload');
278
278
  const packUploadId = pack ? await uploadContentPack(deckId, pack) : null;
279
- const saved = await api.saveCauldronServerBundle(deckId, uploadConfig.uploadId, {
280
- tickRate: serverConfig.tickRate,
281
- maxPlayers: serverConfig.maxPlayers,
282
- voice: { enabled: serverConfig.voiceEnabled },
283
- ...(serverConfig.destinations ? { destinations: serverConfig.destinations } : {}),
284
- ...(serverConfig.worldNotifications
285
- ? { worldNotifications: serverConfig.worldNotifications }
286
- : {}),
287
- // Sent only for a deck whose castle.json declares a hub place, so every
288
- // other deck's config is exactly what it was.
289
- ...(serverConfig.hub ? { hub: serverConfig.hub } : {}),
290
- }, packUploadId ?? undefined);
279
+ const saved = await api.saveCauldronServerBundle(deckId, uploadConfig.uploadId, serverBundleConfig(serverConfig), packUploadId ?? undefined);
291
280
  // The server hashes what it actually stored. A mismatch means the bytes that
292
281
  // will run in sessions are not the bytes we bundled.
293
282
  if (saved && saved.sha256 !== bundle.sha256) {
@@ -313,6 +302,17 @@ function checkedExperiments(castleJson) {
313
302
  throw new Error(`castle.json ${e instanceof Error ? e.message : String(e)} Nothing was saved.`);
314
303
  }
315
304
  }
305
+ // The server block is read again when the bundle is published, after the deck is
306
+ // live; a value it refuses (server.placeMaxPlayers, server.destinations) stops
307
+ // the save here instead.
308
+ function checkedServerConfig(projectDir) {
309
+ try {
310
+ resolveServerConfig(projectDir);
311
+ }
312
+ catch (e) {
313
+ throw new Error(`${e instanceof Error ? e.message : String(e)} Nothing was saved.`);
314
+ }
315
+ }
316
316
  // castle.json `experiments` goes to Castle on every save, with or without a
317
317
  // server bundle. A declared block is awaited and fails the save loudly when it
318
318
  // cannot be stored. Exported for the tests.
@@ -625,6 +625,7 @@ async function saveDeckAfterValidation(dir, opts, projectDir, visibility) {
625
625
  const castleJson = readCastleJson(projectDir);
626
626
  const existingDeckId = typeof castleJson?.deckId === 'string' && castleJson.deckId ? castleJson.deckId : null;
627
627
  const experiments = checkedExperiments(castleJson);
628
+ checkedServerConfig(projectDir);
628
629
  const chunked = checkedBundleChunks(castleJson, opts);
629
630
  if (chunked && !existingDeckId) {
630
631
  // Ghost grants chunk uploads for a deck that exists; a new one is created
@@ -92,6 +92,11 @@ const OPEN_MS = 650;
92
92
  const REVEAL_MS = 700;
93
93
  const LEAVING_MS = 2800;
94
94
  const LOADING_LIMIT_MS = 15000;
95
+ // Ghost's roster can lag a player's arrival in a session by up to 15 s, and
96
+ // the SDK asks a door again through the `forbidden` it answers meanwhile, for
97
+ // 16 s after the arrival (v1.154). A door asked inside that window has its
98
+ // LOADING_LIMIT_MS counted from the window's end: at most this much later.
99
+ const ROSTER_LAG_MS = 16000;
95
100
  // How long the cover waits for the place to say where it put this player
96
101
  // after the session has placed them, before it lifts anyway.
97
102
  const ARRIVAL_WAIT_MS = 4000;
@@ -745,6 +750,7 @@ class HubSystem {
745
750
  this.act ??= makeAct(this.chrome, this.grab, this.talk);
746
751
  this.act.frame(scene, mp, local, !this.trip && this.pendingEnd === null && !this.talk.talking() && !decorating && !this.actionInput && !this.askInput && !this.menuInput && !this.carded);
747
752
  }
753
+ this.noteArrival(mp, now);
748
754
  if (this.trip) {
749
755
  this.stepTrip(scene, mp, local, now);
750
756
  } else if (!Hub.hub.faced) {
@@ -2839,6 +2845,27 @@ class HubSystem {
2839
2845
  }
2840
2846
  }
2841
2847
 
2848
+ // This player's latest arrival in a session (a join, a trip's, a
2849
+ // reconnect's), for a door's roster window (`contentDeadline`). Each frame,
2850
+ // before the trip steps.
2851
+ noteArrival(mp, now) {
2852
+ const placed = mp.placed?.() ?? null;
2853
+ if (placed === true && this.placedLast !== true) {
2854
+ this.arrivedAt = now;
2855
+ }
2856
+ this.placedLast = placed;
2857
+ }
2858
+
2859
+ // When a door still being asked gives up: LOADING_LIMIT_MS after it was
2860
+ // asked, or after the roster window of this player's latest arrival when
2861
+ // that ends later (v1.154). A player not placed right now is arriving now.
2862
+ contentDeadline(trip, now) {
2863
+ const from = trip.target.pendingFrom ?? trip.startedAt;
2864
+ const arrived = this.placedLast === false ? now : this.arrivedAt;
2865
+ const grace = arrived === undefined ? 0 : Math.min(ROSTER_LAG_MS, Math.max(0, arrived + ROSTER_LAG_MS - from));
2866
+ return from + LOADING_LIMIT_MS + grace;
2867
+ }
2868
+
2842
2869
  // Whether a door to another deck has its content, once the cover is down.
2843
2870
  // Until then the cover holds; a pack that failed, or never came, keeps the
2844
2871
  // door shut: the trip turns back without leaving this place (HUB.md, Doors:
@@ -2851,7 +2878,7 @@ class HubSystem {
2851
2878
  trip.marks.covered ??= now;
2852
2879
  this.setTripCover(1, trip);
2853
2880
  // A retried way back has its own deadline, from when it was asked again.
2854
- if (!pending.done && now - (trip.target.pendingFrom ?? trip.startedAt) < LOADING_LIMIT_MS) {
2881
+ if (!pending.done && now < this.contentDeadline(trip, now)) {
2855
2882
  return false;
2856
2883
  }
2857
2884
  // A player barred from the hub is told so, and not asked for again. A way
@@ -4281,6 +4281,7 @@ a deck written before them remains valid.
4281
4281
 
4282
4282
  | date | change |
4283
4283
  | --- | --- |
4284
+ | 2026-10-18 (v1.154) | §5 a door asked within 16 s of this player's arrival in a session (a join, a trip's, a reconnect; ghost's roster lags it by up to 15 s, during which the SDK asks again through `forbidden`) keeps its cover up for the 15 s loading limit counted from that window's end, not the trip's start: a door that answers ok after 14 s of `forbidden` goes through instead of "it took too long". A door that never answers still shuts, by 31 s at most; one asked later keeps 15 s. Every deck, no key. Within `hub.contract: 1`. |
4284
4285
  | 2026-10-17 (v1.147) | §5 a joining player's body without a readable saved pose starts on the scene's spawn itself (its x and z, at the v1.48 standing height), not on the multiplayer spawn ring 1.1 m around it. The client starts its own body at the spawn; on the live Town the first WORLD snapped it to its ring slot, and the kit's arrival row back at the spawn then reached it as a correction under the client's 4 m snap distance, eased a quarter of the way a frame: a 1.1 m glide just after the cover lifted (3 of 5 captures, web and TECNO). Players waiting together share the spot until the arrival row spreads them; the row, the v1.40 settle and every later placement are unchanged. Saved and resumed poses are unchanged. A default in every hub place; no key, nothing new sent. |
4285
4286
  | 2026-10-18 (v1.150) | §12 and §13 authored mind taps also apply in `under13Choices` places: an under-13 speaker receives the place's authored asks ahead of both bundle `childAsks` and the three legacy choices. A matching trimmed `hub-npc-say` is answered through `npcLine` `why: 'authored'`; legacy strings outside those taps are ignored, and mind turns remain refused with `HUB_NPC_CHOICE_REQUIRED`. Mind-less NPCs, minds without authored asks, adults and unknown ages are unchanged. Within `hub.contract: 1`. |
4286
4287
  | 2026-10-17 (v1.148) | §12 and §13 authored taps: `npcOpening` may return `authored: true`, meaning the place answers its asks through `npcLine` `why: 'authored'`. A mind's open for a speaker with trusted `under13 === true` then carries those asks as `choices: string[]` with `authoredChoices: true`, ahead of bundle `childAsks`; a tap goes by `hub-npc-say` to the place's authored line, never a mind turn or ghost, and the kit refuses that speaker's mind turns on that open. Chips clear after the place answers. Over 13s and opens without `authored` are unchanged. Within `hub.contract: 1`. |
@@ -514,6 +514,91 @@ await test('an acquisition that lands after the trip gave up is given back', asy
514
514
  }
515
515
  });
516
516
 
517
+ // v1.154: ghost's roster lags an arrival by up to 15 s, and the SDK asks a door
518
+ // again through its `forbidden` for 16 s after the arrival. The kit's limit
519
+ // counts from the end of that window, not from the trip's start.
520
+ async function rosterTrip({ arrivedAt, placed = true, startedAt = 1000 }) {
521
+ const { system, scene } = setup();
522
+ let release;
523
+ const go = globalThis.__tripHub.go;
524
+ globalThis.__tripHub.go = (doorId) => {
525
+ calls.push(['go', doorId]);
526
+ return new Promise((resolve) => (release = resolve));
527
+ };
528
+ try {
529
+ system.arrivedAt = arrivedAt;
530
+ system.placedLast = placed;
531
+ system.goHub(scene, { door: 'race', key: null, title: 'Foot Race' });
532
+ await flush();
533
+ } finally {
534
+ globalThis.__tripHub.go = go;
535
+ }
536
+ system.trip.startedAt = startedAt;
537
+ return { system, scene, trip: system.trip, release: (v) => release(v) };
538
+ }
539
+
540
+ await test('v1.154: a door used 1 s after arriving, forbidden for 14 s and then ok, goes through', async () => {
541
+ const { system, scene, trip, release } = await rosterTrip({ arrivedAt: 0 });
542
+ // 15.5 s after the trip began: the old limit's "it took too long".
543
+ assert.equal(system.contentReady(scene, trip, 16_500), false);
544
+ assert.equal(trip.shut, undefined);
545
+ // The SDK's retry gets its ok (14 s of `forbidden`), and the pack loads.
546
+ release(handoff());
547
+ await flush();
548
+ assert.equal(system.contentReady(scene, trip, 17_000), true);
549
+ assert.equal(trip.shut, undefined);
550
+ assert.deepEqual(calls, [['go', 'race'], ['loadPack', 'abc', 'https://cdn/abc.json']]);
551
+ });
552
+
553
+ await test('v1.154: a door that never answers after an arrival still shuts, by 31 s', async () => {
554
+ const { system, scene, trip, release } = await rosterTrip({ arrivedAt: 0 });
555
+ // Asked at 1 s: the window ends at 16 s, the limit 15 s after that.
556
+ assert.equal(system.contentReady(scene, trip, 30_999), false);
557
+ assert.equal(trip.shut, undefined);
558
+ assert.equal(system.contentReady(scene, trip, 31_001), false);
559
+ assert.equal(trip.shut, 'it took too long');
560
+ release(handoff());
561
+ await flush();
562
+ await flush();
563
+ assert.deepEqual(calls.at(-1), ['cancel']);
564
+ });
565
+
566
+ await test('v1.154: a player not placed (reconnecting) gets the window, capped at 16 s', async () => {
567
+ const { system, scene, trip } = await rosterTrip({ arrivedAt: 0, placed: false });
568
+ assert.equal(system.contentReady(scene, trip, 1000 + 30_999), false);
569
+ assert.equal(trip.shut, undefined);
570
+ assert.equal(system.contentReady(scene, trip, 1000 + 31_001), false);
571
+ assert.equal(trip.shut, 'it took too long');
572
+ });
573
+
574
+ await test('v1.154: a door used long after the arrival keeps the 15 s limit', async () => {
575
+ const { system, scene, trip } = await rosterTrip({ arrivedAt: -60_000 });
576
+ assert.equal(system.contentReady(scene, trip, 1000 + 14_999), false);
577
+ assert.equal(trip.shut, undefined);
578
+ assert.equal(system.contentReady(scene, trip, 1000 + 15_001), false);
579
+ assert.equal(trip.shut, 'it took too long');
580
+ });
581
+
582
+ await test('v1.154: an arrival is placed() rising; unplaced reads as arriving now', async () => {
583
+ const { system } = setup();
584
+ let placed = false;
585
+ const mp = { placed: () => placed };
586
+ system.noteArrival(mp, 0);
587
+ assert.equal(system.arrivedAt, undefined);
588
+ placed = true;
589
+ system.noteArrival(mp, 500);
590
+ system.noteArrival(mp, 900);
591
+ assert.equal(system.arrivedAt, 500);
592
+ assert.equal(system.contentDeadline({ target: {}, startedAt: 2000 }, 2000), 2000 + 15_000 + 14_500);
593
+ placed = false;
594
+ system.noteArrival(mp, 40_000);
595
+ assert.equal(system.contentDeadline({ target: {}, startedAt: 40_000 }, 40_000), 40_000 + 15_000 + 16_000);
596
+ // A runtime without placed() never extends the limit.
597
+ const bare = setup().system;
598
+ bare.noteArrival({}, 0);
599
+ assert.equal(bare.contentDeadline({ target: {}, startedAt: 0 }, 0), 15_000);
600
+ });
601
+
517
602
  await test('the way back from a hub trip is Hub.back', async () => {
518
603
  const { system, scene } = setup();
519
604
  const ticket = { hub: true, scene: 'scenes/main.scene', content: null, join: { mode: 'public' }, door: 'race', title: 'Town' };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "castle-web-cli",
3
- "version": "0.4.236",
3
+ "version": "0.4.237",
4
4
  "repository": {
5
5
  "type": "git",
6
6
  "url": "git+https://github.com/castle-xyz/castle-experimental-web.git"