castle-web-cli 0.4.199 → 0.4.200

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.
@@ -28,6 +28,7 @@ const COMMAND_NAMES = [
28
28
  "time.getServerTime",
29
29
  "pass.has",
30
30
  "pass.offer",
31
+ "snapshot.offer",
31
32
  "portal.open",
32
33
  "portal.prefetch",
33
34
  "haptics.play",
@@ -54,6 +55,7 @@ const COMMAND_NAMES = [
54
55
  // host's concern, never a deck-facing gate.
55
56
  const PLATFORM_COMMAND_NAMES = [
56
57
  "pass.offer",
58
+ "snapshot.offer",
57
59
  "portal.open",
58
60
  "portal.prefetch",
59
61
  "haptics.play",
@@ -163,6 +165,7 @@ function runCommand(ctx, command, params, caps) {
163
165
  // Platform commands are handled above; listed here to keep the switch
164
166
  // exhaustive over CommandName.
165
167
  case "pass.offer":
168
+ case "snapshot.offer":
166
169
  case "portal.open":
167
170
  case "portal.prefetch":
168
171
  case "haptics.play":
@@ -223,6 +226,8 @@ async function runPlatformCommand(ctx, command, params, caps) {
223
226
  switch (command) {
224
227
  case "pass.offer":
225
228
  return passesOffer(ctx, params, caps);
229
+ case "snapshot.offer":
230
+ return snapshotOffer(ctx, params, caps);
226
231
  case "portal.open":
227
232
  return portalOpen(ctx, params, caps);
228
233
  case "portal.prefetch":
@@ -275,6 +280,23 @@ function normalizePassOutcome(value) {
275
280
  }
276
281
  return { status: "cancelled" };
277
282
  }
283
+ async function snapshotOffer(ctx, params, caps) {
284
+ const title = typeof params.title === "string" ? params.title : "";
285
+ const description = typeof params.description === "string" ? params.description : "";
286
+ const bricksPrice = typeof params.bricksPrice === "number" ? params.bricksPrice : 0;
287
+ // Hosts with no collect card (the dev CLI) get a normalized unavailable.
288
+ if (!caps.platformHandler)
289
+ return { status: "unavailable" };
290
+ // The item belongs to a deck, so a trusted deckId is required before handing off.
291
+ const deckId = requireDeckId(ctx, "snapshot.offer");
292
+ const outcome = await caps.platformHandler("snapshot.offer", { deckId, title, description, bricksPrice }, ctx);
293
+ const status = outcome?.status;
294
+ const valid = ["collected", "cancelled", "unavailable"];
295
+ if (typeof status === "string" && valid.includes(status)) {
296
+ return { status: status };
297
+ }
298
+ return { status: "cancelled" };
299
+ }
278
300
  async function portalOpen(ctx, params, caps) {
279
301
  const targetDeckId = asString(params.targetDeckId, "targetDeckId", "portal.open");
280
302
  // Hosts that can't navigate the feed (dev CLI — no handler; editor) get a
package/dist/init.js CHANGED
@@ -56,7 +56,7 @@ if (!(await mountEditorRoute())) startGame(initCard());
56
56
  // Registry version of castle-web-sdk to inject when scaffolding from a
57
57
  // globally-installed castle-web (not from inside the workspace). Bumped
58
58
  // alongside cli/sdk version bumps.
59
- const PUBLISHED_SDK_VERSION = '0.4.30';
59
+ const PUBLISHED_SDK_VERSION = '0.4.31';
60
60
  // Range, not a pin: `castle-web-fonts` is its own package precisely so a tenth
61
61
  // face can ship without a cli release, and a caret range means an existing
62
62
  // deck's next install picks it up. Nothing here has to move when it does.
package/dist/serve.js CHANGED
@@ -654,6 +654,9 @@ window.__castleShellOrigin=(function(){
654
654
  return;
655
655
  }
656
656
  if (content) {
657
+ // The JS Self-Profiling API is gated on this document policy. A deck
658
+ // that samples itself on a local serve needs it on its own document.
659
+ res.setHeader('Document-Policy', 'js-profiling');
657
660
  if (reqPath === '/')
658
661
  req.url = `/index.html${req.url?.includes('?') ? req.url.slice(req.url.indexOf('?')) : ''}`;
659
662
  const allowedFilesRequest = isAllowedContentFilesRequest(contentRole, req.method, reqPath);
@@ -14,7 +14,7 @@ that framework provides. This one is true either way.
14
14
 
15
15
  <!-- Injected into Castle's create assistant every turn; keep this compact and factual. -->
16
16
 
17
- - `import { setup, initCard } from 'castle-web-sdk'`. Call `setup()` first, once; `initCard()` returns the element to render into (a React tree mounted at `#root` needs no `initCard`). Castle services — `Store`, `Leaderboard`, `Time`, `User`, `Haptics`, `Pass`, `Portal`, `Multiplayer`, `Lifecycle` — come from the same package. `Store` is how a deck saves anything; the older `Storage`/`SharedStorage` still work but should not be used in new decks; the full reference is `imports/castle.base/sdk/README.md`.
17
+ - `import { setup, initCard } from 'castle-web-sdk'`. Call `setup()` first, once; `initCard()` returns the element to render into (a React tree mounted at `#root` needs no `initCard`). Castle services — `Store`, `Leaderboard`, `Time`, `User`, `Haptics`, `Pass`, `Snapshot`, `Portal`, `Multiplayer`, `Lifecycle` — come from the same package. `Store` is how a deck saves anything; the older `Storage`/`SharedStorage` still work but should not be used in new decks; the full reference is `imports/castle.base/sdk/README.md`.
18
18
  - The SDK is a file of this import, not an npm package: `castle-web-sdk` resolves here. Nothing needs installing, and nothing in a deck's `package.json` names it.
19
19
  - Vite serves and bundles the deck: ES modules, JSX, JSON, CSS and npm packages all work with no build step of your own — don't add one.
20
20
  - Details: `## Files`, `## Editors` and `## The SDK` in this file (`imports/castle.base/CLAUDE.md`). The rules every deck plays by -- the card, touch, assets and formats, imports, reloading -- are the platform's: `.castle/docs/platform.md`, written by the serve.
@@ -82,7 +82,7 @@
82
82
  "title": "base",
83
83
  "deckId": "yRcmH4_aYllE",
84
84
  "cardId": "zkFdingmIm3m",
85
- "publishedVersion": "2026-09-22T19:37:37.345Z",
85
+ "publishedVersion": "2026-09-22T19:48:55.642Z",
86
86
  "provides": [
87
87
  "castle-web-sdk"
88
88
  ]
@@ -14,7 +14,7 @@
14
14
  },
15
15
  "../../sdk": {
16
16
  "name": "castle-web-sdk",
17
- "version": "0.4.30",
17
+ "version": "0.4.31",
18
18
  "dev": true,
19
19
  "devDependencies": {
20
20
  "eslint": "^9.0.0",
@@ -22,6 +22,7 @@ import { setup, initCard, Store, Leaderboard } from "castle-web-sdk";
22
22
  - [Time](#time)
23
23
  - [User](#user)
24
24
  - [Pass](#pass)
25
+ - [Snapshot](#snapshot)
25
26
  - [Portal](#portal)
26
27
  - [Haptics](#haptics)
27
28
  - [Lifecycle](#lifecycle)
@@ -499,6 +500,53 @@ if (status === "purchased" || status === "alreadyOwned") {
499
500
  }
500
501
  ```
501
502
 
503
+ ## Snapshot
504
+
505
+ A snapshot is a picture of the deck's current frame that a player collects
506
+ into their Castle inventory, free or for bricks. It is the same item a
507
+ classic deck makes with its "offer snapshot" rule. The player can also take
508
+ one any time with the camera button in the feed; the deck is not involved in
509
+ that one.
510
+
511
+ ### `Snapshot.offer(options?): Promise<SnapshotOfferResult>`
512
+
513
+ Captures the current frame and shows Castle's collect card over it; resolves
514
+ when the player collects or closes it. `options`:
515
+
516
+ - `title`, `description` — shown on the card. With no title the card reads
517
+ "A snapshot of @creator's deck".
518
+ - `price` — bricks. `0` or absent is free; otherwise a whole number from 5 to
519
+ 9995. Anything else throws `INVALID_ARGUMENT`.
520
+
521
+ Collecting works only in the Castle mobile app; the website shows "collect in
522
+ the app" and the dev server a short notice, and both resolve `unavailable`.
523
+ `SnapshotOfferResult` has a `status`:
524
+
525
+ - `'collected'` — the player collected it.
526
+ - `'cancelled'` — the player closed the card.
527
+ - `'unavailable'` — can't collect here, or another snapshot card is already
528
+ open (a second `offer` while one is open gets this and the first carries on).
529
+
530
+ ```js
531
+ const { status } = await Snapshot.offer({
532
+ title: "Level 3 cleared",
533
+ description: `${score} points`,
534
+ });
535
+ ```
536
+
537
+ ### `Snapshot.onTaken(handler): () => void`
538
+
539
+ Registers a function called just before an offer's capture, the twin of the
540
+ classic "snapshot taken" trigger. Change what's on screen in it — hide the
541
+ HUD, pose the character — and the capture shows the next painted frame.
542
+ Returns a function that unregisters it. The camera button never calls it.
543
+
544
+ ```js
545
+ Snapshot.onTaken(() => {
546
+ hud.hidden = true;
547
+ });
548
+ ```
549
+
502
550
  ## Portal
503
551
 
504
552
  A portal sends the player from this deck to another Castle deck,
@@ -18,6 +18,8 @@ export { registerParams } from "./paramsRegistry";
18
18
  export type { TunedParam, TunedParamValue } from "./paramsRegistry";
19
19
  export { Pass } from "./passes";
20
20
  export type { CastlePassApi, PassOfferResult, PassOfferStatus, } from "./passes";
21
+ export { Snapshot } from "./snapshots";
22
+ export type { CastleSnapshotApi, SnapshotOfferOptions, SnapshotOfferResult, SnapshotOfferStatus, } from "./snapshots";
21
23
  export { Portal } from "./portal";
22
24
  export type { CastlePortalApi, PortalOpenResult, PortalOpenStatus, PortalPrefetchResult, PortalPrefetchStatus, } from "./portal";
23
25
  export { CARD_RATIO, deleteFile, fileUrl, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, openFile, renameFile, requestReload, setup, takeReloadState, writeFileOnce, } from "./runtime";
@@ -10,6 +10,7 @@ export { Multiplayer } from "./multiplayer";
10
10
  export { MAX_CLIENT_FRAME_BYTES, MAX_PLAYERS_CAP } from "./multiplayerProtocol";
11
11
  export { registerParams } from "./paramsRegistry";
12
12
  export { Pass } from "./passes";
13
+ export { Snapshot } from "./snapshots";
13
14
  export { Portal } from "./portal";
14
15
  export { CARD_RATIO, deleteFile, fileUrl, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, openFile, renameFile, requestReload, setup, takeReloadState, writeFileOnce, } from "./runtime";
15
16
  export { flushSaves, hasPendingSave, onSaveState, writeFile, } from "./saveQueue";
@@ -48,6 +48,10 @@ export type PassOfferStatus = "purchased" | "alreadyOwned" | "cancelled" | "unav
48
48
  export interface PassOfferResult {
49
49
  status: PassOfferStatus;
50
50
  }
51
+ export type SnapshotOfferStatus = "collected" | "cancelled" | "unavailable";
52
+ export interface SnapshotOfferResult {
53
+ status: SnapshotOfferStatus;
54
+ }
51
55
  export type PortalOpenStatus = "navigating" | "unavailable";
52
56
  export interface PortalOpenResult {
53
57
  status: PortalOpenStatus;
@@ -171,6 +175,11 @@ export interface CommandParams {
171
175
  "pass.offer": {
172
176
  passId: string;
173
177
  };
178
+ "snapshot.offer": {
179
+ title: string;
180
+ description: string;
181
+ bricksPrice: number;
182
+ };
174
183
  "portal.open": {
175
184
  targetDeckId: string;
176
185
  };
@@ -294,6 +303,7 @@ export interface CommandResult {
294
303
  hasPass: boolean;
295
304
  };
296
305
  "pass.offer": PassOfferResult;
306
+ "snapshot.offer": SnapshotOfferResult;
297
307
  "portal.open": PortalOpenResult;
298
308
  "portal.prefetch": PortalPrefetchResult;
299
309
  "haptics.play": HapticsResult;
@@ -0,0 +1,12 @@
1
+ import type { SnapshotOfferResult } from "./commands";
2
+ export type { SnapshotOfferResult, SnapshotOfferStatus } from "./commands";
3
+ export interface SnapshotOfferOptions {
4
+ title?: string;
5
+ description?: string;
6
+ price?: number;
7
+ }
8
+ export interface CastleSnapshotApi {
9
+ offer(options?: SnapshotOfferOptions): Promise<SnapshotOfferResult>;
10
+ onTaken(handler: () => void): () => void;
11
+ }
12
+ export declare const Snapshot: CastleSnapshotApi;
@@ -0,0 +1,128 @@
1
+ // Snapshot: offer the player a collectible picture of the deck's current frame,
2
+ // the same item a classic deck makes with its "offer snapshot" rule.
3
+ //
4
+ // The host captures the frame and shows its own collect card; the deck gets one
5
+ // result back. `onTaken` is the twin of the classic "snapshot taken" trigger: it
6
+ // runs just before an offer's capture, so the deck can pose the frame. The
7
+ // camera button in the feed takes a snapshot without the deck, and never calls it.
8
+ //
9
+ // - mobile app : the collect card over the captured frame, then the confirm sheet
10
+ // - web player : "collect this snapshot in the app", returns `unavailable`
11
+ // - dev CLI : a small notice, returns `unavailable`
12
+ import { CastleError } from "./errors";
13
+ import { getCommandChannel, hostRequest } from "./transport";
14
+ export const Snapshot = {
15
+ offer,
16
+ onTaken,
17
+ };
18
+ const MIN_BRICKS_PRICE = 5;
19
+ const MAX_BRICKS_PRICE = 9995;
20
+ const takenHandlers = new Set();
21
+ // An offer is open until its result comes back. A second call meanwhile is
22
+ // ignored: it resolves `unavailable` and the open card goes on.
23
+ let offerOpen = false;
24
+ function onTaken(handler) {
25
+ takenHandlers.add(handler);
26
+ return () => {
27
+ takenHandlers.delete(handler);
28
+ };
29
+ }
30
+ async function offer(options = {}) {
31
+ const title = options.title ?? "";
32
+ const description = options.description ?? "";
33
+ const price = options.price ?? 0;
34
+ if (typeof title !== "string" || typeof description !== "string") {
35
+ throw new CastleError({
36
+ code: "INVALID_ARGUMENT",
37
+ message: "Snapshot.offer title and description must be strings.",
38
+ operation: "Snapshot.offer",
39
+ });
40
+ }
41
+ if (!Number.isInteger(price) ||
42
+ (price !== 0 && (price < MIN_BRICKS_PRICE || price > MAX_BRICKS_PRICE))) {
43
+ throw new CastleError({
44
+ code: "INVALID_ARGUMENT",
45
+ message: `Snapshot.offer price must be 0 or a whole number of bricks from ${MIN_BRICKS_PRICE} to ${MAX_BRICKS_PRICE}.`,
46
+ operation: "Snapshot.offer",
47
+ });
48
+ }
49
+ if (offerOpen) {
50
+ return { status: "unavailable" };
51
+ }
52
+ offerOpen = true;
53
+ try {
54
+ // Give the deck its "snapshot taken" moment, then let a frame paint so the
55
+ // capture shows whatever the handlers changed.
56
+ for (const handler of [...takenHandlers]) {
57
+ try {
58
+ handler();
59
+ }
60
+ catch (error) {
61
+ console.warn("Castle Snapshot.onTaken handler threw.", error);
62
+ }
63
+ }
64
+ await nextPaintedFrame();
65
+ const result = await hostRequest("snapshot.offer", {
66
+ title,
67
+ description,
68
+ bricksPrice: price,
69
+ });
70
+ // The dev server has no collect card, so say why nothing happened.
71
+ if (result.status === "unavailable" && getCommandChannel() === "local") {
72
+ showDevUnavailableNotice();
73
+ }
74
+ return result;
75
+ }
76
+ finally {
77
+ offerOpen = false;
78
+ }
79
+ }
80
+ // Two animation frames: the first runs after the handlers' changes are queued,
81
+ // the second after that frame has been painted.
82
+ function nextPaintedFrame() {
83
+ if (typeof requestAnimationFrame === "undefined") {
84
+ return Promise.resolve();
85
+ }
86
+ return new Promise((resolve) => {
87
+ requestAnimationFrame(() => {
88
+ requestAnimationFrame(() => resolve());
89
+ });
90
+ });
91
+ }
92
+ let devNoticeEl = null;
93
+ let devNoticeTimer = null;
94
+ function showDevUnavailableNotice() {
95
+ if (typeof document === "undefined") {
96
+ return;
97
+ }
98
+ if (!devNoticeEl) {
99
+ devNoticeEl = document.createElement("div");
100
+ devNoticeEl.textContent = "Snapshots can only be collected in the Castle app.";
101
+ devNoticeEl.style.cssText = [
102
+ "position:fixed",
103
+ "left:50%",
104
+ "bottom:24px",
105
+ "transform:translateX(-50%)",
106
+ "max-width:80vw",
107
+ "padding:10px 16px",
108
+ "border-radius:8px",
109
+ "background:rgba(0,0,0,0.82)",
110
+ "color:#fff",
111
+ "font:500 13px/1.4 system-ui,sans-serif",
112
+ "text-align:center",
113
+ "z-index:2147483647",
114
+ "pointer-events:none",
115
+ "transition:opacity 0.3s ease",
116
+ ].join(";");
117
+ document.body.appendChild(devNoticeEl);
118
+ }
119
+ devNoticeEl.style.opacity = "1";
120
+ if (devNoticeTimer) {
121
+ clearTimeout(devNoticeTimer);
122
+ }
123
+ devNoticeTimer = setTimeout(() => {
124
+ if (devNoticeEl) {
125
+ devNoticeEl.style.opacity = "0";
126
+ }
127
+ }, 3200);
128
+ }
@@ -17,6 +17,7 @@ const REQUEST_TIMEOUT_MS = 15000;
17
17
  // is wrong for them: they get NO timeout and resolve only when the host replies.
18
18
  const INTERACTIVE_COMMANDS = new Set([
19
19
  "pass.offer",
20
+ "snapshot.offer",
20
21
  "portal.open",
21
22
  ]);
22
23
  let nextRequestId = 1;
@@ -6,15 +6,15 @@
6
6
  "imports": {
7
7
  "castle.real-time": {
8
8
  "deckId": "xFVr-afOLuUQ",
9
- "version": "2026-09-16T21:18:06.448Z"
9
+ "version": "2026-09-22T19:48:58.226Z"
10
10
  },
11
11
  "castle.physics-2d": {
12
12
  "deckId": "ckRZGFW4iPrx",
13
- "version": "2026-09-16T21:17:53.144Z"
13
+ "version": "2026-09-22T19:49:07.246Z"
14
14
  },
15
15
  "castle.base": {
16
16
  "deckId": "yRcmH4_aYllE",
17
- "version": "2026-09-11T20:21:04.335Z"
17
+ "version": "2026-09-22T19:48:55.642Z"
18
18
  }
19
19
  },
20
20
  "autoUpdateWhenImported": true,
@@ -26,5 +26,5 @@
26
26
  },
27
27
  "deckId": "oiFu96LkwZ09",
28
28
  "cardId": "nkJgrvrCby3H",
29
- "publishedVersion": "2026-09-16T21:20:14.363Z"
29
+ "publishedVersion": "2026-09-22T19:49:27.017Z"
30
30
  }
@@ -82,6 +82,12 @@ class MultiplayerSystem {
82
82
 
83
83
  // The last position the server refused a move to, or null.
84
84
  this.clampedTo = null;
85
+
86
+ // Where the session placed this player, from the WORLD snapshot that starts
87
+ // it, until the local actor has been moved there. `settleFrames` then keeps
88
+ // the join overlay up for the frames it takes the camera to follow.
89
+ this.placedTo = null;
90
+ this.settleFrames = 0;
85
91
  }
86
92
 
87
93
  // The network frame, after behaviors and after local physics. Connect,
@@ -110,6 +116,9 @@ class MultiplayerSystem {
110
116
 
111
117
  // Player is a behavior component on the actor controlled by this browser.
112
118
  const local = scene.actorWith('Player');
119
+ if (this.settleFrames > 0) {
120
+ this.settleFrames -= 1;
121
+ }
113
122
 
114
123
  // Every queued message is drained before this frame picks its render time.
115
124
  this.receive(scene);
@@ -178,11 +187,13 @@ class MultiplayerSystem {
178
187
  for (const [id, x, y, facing, clamped] of msg.ps ?? []) {
179
188
  if (id !== selfId) {
180
189
  sample(this.players, msg, id, [x, y, facing]);
181
- } else if (clamped || msg.k === WORLD) {
190
+ } else if (msg.k === WORLD) {
191
+ // The WORLD snapshot that starts a session carries where this player
192
+ // left off. The actor is moved there in one step, behind the overlay.
193
+ this.placedTo = { x, y };
194
+ } else if (clamped) {
182
195
  // Store this client's returned pose when the server marks the report
183
- // clamped, and on the WORLD snapshot that starts a session: that one
184
- // carries where this player left off. Accepted movement remains
185
- // client-simulated.
196
+ // clamped. Accepted movement remains client-simulated.
186
197
  this.clampedTo = { x, y };
187
198
  }
188
199
  }
@@ -270,19 +281,33 @@ class MultiplayerSystem {
270
281
  // Correct the local actor after the server clamps a reported move. Accepted
271
282
  // snapshots do not move the locally simulated character.
272
283
  acceptClamp(scene, local) {
273
- if (!this.clampedTo) {
274
- return;
275
- }
276
- const to = this.clampedTo;
277
- this.clampedTo = null;
278
284
  const layout = local?.components.Layout;
279
- if (!layout) {
285
+
286
+ // The session's placement moves the actor in one step, however far it is:
287
+ // the character has been standing at the scene's spawn behind the join
288
+ // overlay, and easing from there would show a walk that never happened. The
289
+ // camera has not seen the new position yet, so the overlay stays up one more
290
+ // frame. Without a Layout yet, the placement waits for one.
291
+ let to = null;
292
+ let ease = CLAMP_EASE;
293
+ if (this.placedTo && layout) {
294
+ to = this.placedTo;
295
+ this.placedTo = null;
296
+ this.settleFrames = 1;
297
+ ease = 1;
298
+ } else if (this.clampedTo) {
299
+ to = this.clampedTo;
300
+ this.clampedTo = null;
301
+ }
302
+ if (!to || !layout) {
280
303
  return;
281
304
  }
282
305
  const off = { x: to.x - layout.x, y: to.y - layout.y };
283
306
 
284
307
  // Large corrections snap; short corrections converge over successive frames.
285
- const ease = Math.hypot(off.x, off.y) > CLAMP_SNAP ? 1 : CLAMP_EASE;
308
+ if (Math.hypot(off.x, off.y) > CLAMP_SNAP) {
309
+ ease = 1;
310
+ }
286
311
  layout.x += off.x * ease;
287
312
  layout.y += off.y * ease;
288
313
 
@@ -406,13 +431,24 @@ class MultiplayerSystem {
406
431
  this.own = Ownership.makeOwnership();
407
432
  this.shown = Smoothing.makeSmoothing();
408
433
  this.clampedTo = null;
434
+ this.placedTo = null;
435
+ this.settleFrames = 0;
409
436
  }
410
437
 
411
438
  // Whether the overlay should be up: joining or connected, not solo, and not
412
439
  // yet placed. A session that never answers releases it after JOIN_WAIT_MS so
413
440
  // the deck is not stuck behind it.
414
441
  joiningOverlayWanted() {
415
- if (this.joined || this.net?.status().solo) {
442
+ if (this.net?.status().solo) {
443
+ return false;
444
+ }
445
+
446
+ // Placed, but the actor has not been moved yet or the camera has not drawn
447
+ // it there: the frame under the overlay would still show the spawn.
448
+ if (this.joined && (this.placedTo || this.settleFrames > 0)) {
449
+ return true;
450
+ }
451
+ if (this.joined) {
416
452
  return false;
417
453
  }
418
454
  if (this.joinStartedAt && performance.now() - this.joinStartedAt > JOIN_WAIT_MS) {
@@ -29,7 +29,7 @@
29
29
  },
30
30
  "../../sdk": {
31
31
  "name": "castle-web-sdk",
32
- "version": "0.4.28",
32
+ "version": "0.4.31",
33
33
  "dev": true,
34
34
  "devDependencies": {
35
35
  "eslint": "^9.0.0",
@@ -6,26 +6,26 @@
6
6
  "imports": {
7
7
  "castle.real-time": {
8
8
  "deckId": "xFVr-afOLuUQ",
9
- "version": "2026-09-16T21:18:06.448Z"
9
+ "version": "2026-09-22T19:48:58.226Z"
10
10
  },
11
11
  "castle.physics-3d": {
12
12
  "deckId": "JH0SclbPVP0y",
13
- "version": "2026-09-14T02:38:17.286Z"
13
+ "version": "2026-09-22T19:49:18.182Z"
14
14
  },
15
15
  "castle.physics-2d": {
16
16
  "deckId": "ckRZGFW4iPrx",
17
- "version": "2026-09-16T21:17:53.144Z",
17
+ "version": "2026-09-22T19:49:07.246Z",
18
18
  "via": "castle.physics-3d"
19
19
  },
20
20
  "castle.base": {
21
21
  "deckId": "yRcmH4_aYllE",
22
- "version": "2026-09-11T20:21:04.335Z"
22
+ "version": "2026-09-22T19:48:55.642Z"
23
23
  }
24
24
  },
25
25
  "autoUpdateWhenImported": true,
26
26
  "deckId": "ZwA_P_-VO-Qh",
27
27
  "cardId": "bvRmCzyUpt_a",
28
- "publishedVersion": "2026-09-16T21:20:24.084Z",
28
+ "publishedVersion": "2026-09-22T19:49:32.861Z",
29
29
  "main": "main.jsx",
30
30
  "server": {
31
31
  "main": "code/server/index.js",
@@ -78,6 +78,12 @@ class MultiplayerSystem {
78
78
  // A clamp stores the last server position that rejected a local move.
79
79
  this.clampedTo = null;
80
80
 
81
+ // Where the session placed this player, from the WORLD snapshot that starts
82
+ // it, until the local body has been moved there. `settleFrames` then keeps
83
+ // the join overlay up for the frames it takes the camera to follow.
84
+ this.placedTo = null;
85
+ this.settleFrames = 0;
86
+
81
87
  // Scene actors the session has removed for good, and the actor ids present
82
88
  // at the end of the last frame. An id that was there and is not now was
83
89
  // despawned by a behavior this frame, and is reported.
@@ -112,6 +118,9 @@ class MultiplayerSystem {
112
118
  return;
113
119
  }
114
120
  const local = scene.actorWith('Player');
121
+ if (this.settleFrames > 0) {
122
+ this.settleFrames -= 1;
123
+ }
115
124
 
116
125
  // Drain all queued messages before choosing the render time for this frame.
117
126
  this.receive(scene);
@@ -206,11 +215,13 @@ class MultiplayerSystem {
206
215
  for (const [id, x, y, z, facing, clamped] of msg.ps ?? []) {
207
216
  if (id !== selfId) {
208
217
  sample(this.players, msg, id, [x, y, z, facing]);
209
- } else if (clamped || msg.k === WORLD) {
218
+ } else if (msg.k === WORLD) {
219
+ // The WORLD snapshot that starts a session carries where this player
220
+ // left off. The body is moved there in one step, behind the overlay.
221
+ this.placedTo = { x, y, z };
222
+ } else if (clamped) {
210
223
  // The local player's returned pose is used when the server marks it
211
- // clamped, and on the WORLD snapshot that starts a session: that one
212
- // carries where this player left off. Ordinary local movement remains
213
- // client-simulated.
224
+ // clamped. Ordinary local movement remains client-simulated.
214
225
  this.clampedTo = { x, y, z };
215
226
  }
216
227
  }
@@ -299,10 +310,22 @@ class MultiplayerSystem {
299
310
  // Apply a server position after it clamps an excessive local player move.
300
311
  // Ordinary server snapshots do not move the locally simulated player.
301
312
  acceptClamp(scene, local) {
313
+ const body = local && scene.physics3d?.bodyOf(local);
314
+
315
+ // The session's placement moves the body in one step, however far it is:
316
+ // the player has been standing at the scene's spawn behind the join overlay,
317
+ // and easing from there would show a walk that never happened. The camera
318
+ // has not seen the new position yet, so the overlay stays up one more frame.
319
+ // Without a body yet, the placement waits for one.
320
+ if (this.placedTo && body) {
321
+ body.setTranslation(this.placedTo, true);
322
+ body.setLinvel({ x: 0, y: 0, z: 0 }, true);
323
+ this.placedTo = null;
324
+ this.settleFrames = 1;
325
+ }
302
326
  if (!this.clampedTo) {
303
327
  return;
304
328
  }
305
- const body = local && scene.physics3d?.bodyOf(local);
306
329
  const to = this.clampedTo;
307
330
  this.clampedTo = null;
308
331
  if (!body) {
@@ -453,6 +476,8 @@ class MultiplayerSystem {
453
476
  this.own = Ownership.makeOwnership();
454
477
  this.shown = Smoothing.makeSmoothing();
455
478
  this.clampedTo = null;
479
+ this.placedTo = null;
480
+ this.settleFrames = 0;
456
481
  this.seen = null;
457
482
  }
458
483
 
@@ -492,7 +517,16 @@ class MultiplayerSystem {
492
517
  // yet placed. A session that never answers releases it after JOIN_WAIT_MS so
493
518
  // the deck is not stuck behind it.
494
519
  joiningOverlayWanted() {
495
- if (this.joined || this.net?.status().solo) {
520
+ if (this.net?.status().solo) {
521
+ return false;
522
+ }
523
+
524
+ // Placed, but the body has not been moved yet or the camera has not drawn
525
+ // it there: the frame under the overlay would still show the spawn.
526
+ if (this.joined && (this.placedTo || this.settleFrames > 0)) {
527
+ return true;
528
+ }
529
+ if (this.joined) {
496
530
  return false;
497
531
  }
498
532
  if (this.joinStartedAt && performance.now() - this.joinStartedAt > JOIN_WAIT_MS) {
@@ -31,7 +31,7 @@
31
31
  },
32
32
  "../../sdk": {
33
33
  "name": "castle-web-sdk",
34
- "version": "0.4.28",
34
+ "version": "0.4.31",
35
35
  "dev": true,
36
36
  "devDependencies": {
37
37
  "eslint": "^9.0.0",
@@ -21,7 +21,7 @@ Do you already know what you want to make, or do you want to figure it out toget
21
21
  - A behavior is a class with **one instance per actor**: creator-tuned settings in `static defaultProps` (read as `this.props`), per-actor state in `this.state` seeded from `static initialState` (not bare `this.foo` fields or `actor.runtime`). Anything another behavior triggers is a public method, called as `actor.behaviors.Name?.method()` — `this.actor.behaviors` for a sibling, `other.behaviors` for another actor.
22
22
  - Editable screens live in `scenes/*.scene` files (plain JSON). Use a separate scene file per distinct screen, and switch with `scene.loadFromFile('name.scene')`.
23
23
  - Every actor is an instance of a **blueprint** (`blueprints/*.scene`) — see `## Blueprints` below. Always author the blueprint file yourself and reference it via `"blueprint"`. Don't write inline actors (full `components`, no `blueprint` field): the editor auto-migrates each one into its own new blueprint file on open, one per actor with no dedup, which litters the deck with junk blueprints.
24
- - Real game objects and scenery should usually be editable sprites: generate `.sprite` with `npm run draw -- name`, then place it via a `Sprite` component pointing at `drawings/name.sprite`. Dynamic UI/effects stay procedural.
24
+ - Real game objects and scenery should usually be editable sprites: generate `.sprite` with `npm run draw -- name` on a canvas in the actor's proportions (see `## Creating pixel art`), then place it via a `Sprite` component pointing at `drawings/name.sprite`. Dynamic UI/effects stay procedural.
25
25
  - A deck can also hold uploaded media (the Files panel's Upload button): `Sprite` draws image files as well as `.sprite`, and `Video` plays video files. Point their `file` at the deck path (`assets/logo.png`). For audio see `## Sound` below -- sound effects need no component at all.
26
26
  - **Text** — place the kit preset `@imports/castle.physics-2d/blueprints/text.scene`, or add a `Text` component (optional `font`; chrome via sibling `Style`). Dynamic text is `actor.components.Text.text = …`. A sibling `onTap(actor, scene)` fires when that actor is tapped — no extra behavior.
27
27
  - The deck's body/UI font is picked in the Theme editor (`theme.style`): canvas text reads `scene.font`. A second display face is imported in the behavior that uses it. See `## Deck font` below.
@@ -455,7 +455,7 @@ The kit also ships a few presets under `blueprints/` (e.g. `text.scene`, `ball.s
455
455
  - **Layout** — `{ x, y, width, height, z?, rotation?, originX?, originY? }`. Every actor needs one. `z` orders draw (low first). `rotation` is degrees about the box center. `originX`/`originY` say WHICH point of the box `x`/`y` names, as fractions of the box from its own top-left: `0.5, 0.5` (the default, and what omitting them means) is the center, `0, 0` the top-left corner, `1, 1` the bottom-right; values outside `0..1` are allowed. So `{ x: 250, y: 350, width: 40, height: 40 }` centers a 40x40 box on the middle of the card. The origin anchors position only — rotation still pivots on the center, and collider shape fractions are still measured from the box's top-left. Blueprints the editor creates, and the kit's own presets (`ball`, `block`, `crate`, `goal`, `cauldron`, `text`), use center. A deck authored before the origin existed meant the top-left everywhere, and the kit update wrote that down as explicit `0`s rather than moving anything — so an old deck reads as top-left because it says so, not because of a default. Read the box back with `scene.layoutRect(actor)` instead of doing `x + width / 2` by hand, which is only right at a top-left origin.
456
456
  - **Sprite** — `{ file: "drawings/foo.sprite", tint?: "#rrggbbaa", playing?: true, tag?: "", mode?: 'cover'|'fit'|'stretch'|'tile', tileSize?: 50 }`. Renders the deck's 2D art into the Layout box. `file` is either a `.sprite` pixel-art sprite or an uploaded **image file** (`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.svg`) — every prop below works the same on both, except that an image is a single still (no frames or tags) and is drawn smoothed rather than nearest-neighbour, which is what you want for a photo and not for pixel art. Draw modes: scaled up preserving the art's aspect ratio to fill the whole box, cropping whatever overflows a mismatched box (`mode: 'cover'`, the default -- CSS object-fit: cover), scaled preserving the art's aspect ratio and centered so the whole sprite stays visible, letterboxing a mismatched box instead of cropping (`mode: 'fit'` -- CSS object-fit: contain), scaled to fill the box exactly and distorting the art when the aspect ratios don't match (`mode: 'stretch'`), or repeated (`mode: 'tile'`). `tint` multiplies; use white (`#ffffffff`) or omit for the original colors. Animated sprites play automatically; set `playing: false` to hold the first frame, or `tag` to play a named animation tag. Tile mode repeats the art at a fixed cell size (`tileSize` card units tall, width scaled by the art's aspect) instead of stretching it across the Layout box.
457
457
  - **Missing sprites fall back to a placeholder.** If `file` names a sprite that doesn't exist yet, it renders the fallback `drawings/cauldron.sprite` — so you can give an actor its REAL intended sprite name (`drawings/paddle.sprite`) right away and it shows the placeholder until that file is created. Reference real names from the start; don't wait for the art.
458
- - **Fill the box, don't distort.** The default `mode: 'cover'` fills the Layout box with the art undistorted, cropping whatever overflows when the box aspect doesn't match the art's — so treat the Layout box like an image frame in a design tool: size it to frame what matters and keep the sprite's important content toward the center, since the edges may be cropped. Keeping an actor's Layout aspect ratio close to its sprite's native aspect ratio minimizes how much gets cropped. When the whole sprite must stay visible (nothing is safe to crop), use `mode: 'fit'`, which preserves the art and letterboxes the mismatched box instead. Avoid `mode: 'stretch'` for pixel art — filling a long/tall box by distorting wrecks the pixels (a brick sprite stretched into a wall ruins the bricks). For long surfaces (walls, floors, platforms), use `mode: 'tile'` on one actor to repeat the art at a fixed cell size instead of stretching or cropping a single sprite.
458
+ - **Fill the box, don't distort.** The default `mode: 'cover'` fills the Layout box with the art undistorted, cropping whatever overflows when the box aspect doesn't match the art's — so treat the Layout box like an image frame in a design tool: size it to frame what matters and keep the sprite's important content toward the center, since the edges may be cropped. Keeping an actor's Layout aspect ratio close to its sprite's native aspect ratio minimizes how much gets cropped. When the whole sprite must stay visible (nothing is safe to crop), use `mode: 'fit'`, which preserves the art and letterboxes the mismatched box instead. `fit` shows the whole canvas, transparent margin included, so it only looks right when the canvas has the box's proportions. Avoid `mode: 'stretch'` for pixel art — filling a long/tall box by distorting wrecks the pixels (a brick sprite stretched into a wall ruins the bricks). For long surfaces (walls, floors, platforms), use `mode: 'tile'` on one actor to repeat the art at a fixed cell size instead of stretching or cropping a single sprite.
459
459
  - **Text** — `{ text, font?: '', size?: 24, color?: '#131313', align?: 'left'|'center'|'right', verticalAlign?: 'top'|'middle'|'bottom', lineHeight?: 1.25, space?: 'world'|'screen', outlineWidth?: 0, outlineColor?: '#ffffff' }`. Draws wrapped text into the Layout box (wrap width = box minus sibling `Style.padding`; lines may overflow vertically — no clipping, no auto-resize). `font: ''` (default) uses the deck font; pick any Castle face from the inspector and it is added to `fonts.generated.js`. `space: 'world'` scrolls with the camera; `space: 'screen'` is HUD via `drawUi`. `color` / `outlineColor` are deck-palette hexes (`''` = none — skip fill or stroke). Fill/border/shadow/opacity/padding live on sibling **Style**. Hide with `"$enabled": false`. Kit preset: `@imports/castle.physics-2d/blueprints/text.scene`. Change the string from deck code with `actor.components.Text.text = '…'`.
460
460
  - **Style** — `{ background?: '', border?: '', borderWidth?: 0, borderRadius?: 0, padding?: 0, shadowX?: 0, shadowY?: 0, shadowBlur?: 0, shadowColor?: '', opacity?: 1 }`. Shared chrome for **Text** and **Sprite**: background fill, border, corner radius, drop shadow (`shadowColor` + offsets + blur; empty color = no shadow), content padding, and opacity. Draws behind content. `background` / `border` are palette hexes (`''` = none). Add it beside Text or Sprite from the inspector.
461
461
  - **Collider** — `{ kind: 'solid'|'pickup', mode?: 'auto'|'manual', width, height, offsetX?, offsetY?, debug? }`. Just a rect; `offsetX`/`offsetY` nudge the collider from its default position (so `0,0` is the default). `mode: 'auto'` (the default) fits the rect to the actor's Sprite's opaque pixels, mapped through the Sprite's draw mode (`fit`'s letterboxed dest rect, `stretch`'s full Layout box, `cover`'s filled box clipped to the Layout box; `tile` mode and a missing/unresolved Sprite use the whole Layout box instead). `width`/`height` only apply in `mode: 'manual'` (a rect of that size, centered in the Layout box); they're ignored in `auto`. The framework does NOT auto-resolve collisions for you. Use it as data:
@@ -906,9 +906,10 @@ Physics is just this kit's use of it.
906
906
 
907
907
  ## Creating pixel art (`.sprite`)
908
908
 
909
- Don't hand-write pixel grids. Generate sprites with the `draw` command: **emit a terse svg-rect** — a tiny `<svg viewBox="0 0 16 16">` with **one `<rect>` per pixel** — and pipe it to `npm run draw`. It quantizes every fill to the agent palette and writes a single-frame `drawings/<name>.sprite`.
909
+ Don't hand-write pixel grids. Generate sprites with the `draw` command: **emit a terse svg-rect** — a tiny `<svg viewBox="0 0 W H">` in the actor's proportions with **one `<rect>` per pixel** — and pipe it to `npm run draw`. It quantizes every fill to the agent palette and writes a single-frame `drawings/<name>.sprite`.
910
910
 
911
- - **Resolution is 16×16.** Use `viewBox="0 0 16 16"` and **one 1×1 `<rect>` per filled pixel** (`width="1" height="1"` at integer `x`/`y`). Leave background pixels out (omitted = transparent). Keep every rect 1×1 — the decoder infers cell size from the smallest rect, so mixing in larger blocks shrinks the whole grid.
911
+ - **The canvas is the actor's shape.** The viewBox is the sprite's pixel grid, and the whole grid is the image, transparent cells included. Give it the same proportions as the actor's Layout box, with the short side at least 4 cells: a 100x20 paddle is `viewBox="0 0 40 8"`, a 60x24 brick `viewBox="0 0 20 8"`, a 20x20 ball `viewBox="0 0 16 16"`. Draw the piece edge to edge. A shape floating in the middle of a square canvas, shown with `mode: 'fit'` in a wide box, comes out as a sliver.
912
+ - **One 1×1 `<rect>` per filled pixel** (`width="1" height="1"` at integer `x`/`y`). Leave background pixels out (omitted = transparent). Keep every rect 1×1 — the decoder infers cell size from the smallest rect, so mixing in larger blocks shrinks the whole grid.
912
913
  - **Palette is the deck's generation palette.** The default (no `theme.style`, or Endesga-64) is this 16-color subset — every `fill` must be one of:
913
914
 
914
915
  `#e69c69` `#bf6f4a` `#8a4836` `#391f21` `#891e2b` `#ea323c` `#ffa214` `#ffeb57` `#5ac54f` `#1e6f50` `#134c4c` `#657392` `#c7cfdd` `#ffffff` `#0cf1ff` `#0098dc`
@@ -67,11 +67,11 @@
67
67
  "autoUpdateWhenImported": true,
68
68
  "onUpdate": "scripts/onUpdate.mjs",
69
69
  "title": "physics-2d",
70
- "publishedVersion": "2026-09-22T19:38:31.981Z",
70
+ "publishedVersion": "2026-09-22T19:49:07.246Z",
71
71
  "imports": {
72
72
  "castle.base": {
73
73
  "deckId": "yRcmH4_aYllE",
74
- "version": "2026-09-22T19:37:37.345Z"
74
+ "version": "2026-09-22T19:48:55.642Z"
75
75
  }
76
76
  }
77
77
  }
@@ -32,7 +32,7 @@
32
32
  },
33
33
  "../../sdk": {
34
34
  "name": "castle-web-sdk",
35
- "version": "0.4.30",
35
+ "version": "0.4.31",
36
36
  "dev": true,
37
37
  "devDependencies": {
38
38
  "eslint": "^9.0.0",
@@ -68,15 +68,24 @@ function applyMove(phys, actor, move, speed, grounded, dt) {
68
68
  }
69
69
  }
70
70
 
71
+ // A player moving faster than this between two frames was teleported: a scene
72
+ // switch, or the session placing them where they left off. Walking never covers
73
+ // it in one frame.
74
+ const TELEPORT_PER_FRAME = 3;
75
+
71
76
  function updateCamera(scene, t, rt, props, dt) {
72
77
  const cam = scene.three?.camera;
73
78
  if (!cam) return;
74
79
  const targetX = t.x - props.camDistance * Math.sin(rt.camAngle);
75
80
  const targetY = t.y + props.camHeight;
76
81
  const targetZ = t.z + props.camDistance * Math.cos(rt.camAngle);
77
- // A scene switch teleports the player; snap instead of swooshing the
78
- // camera across the whole map.
79
- if (Math.hypot(targetX - cam.position.x, targetZ - cam.position.z) > 20) {
82
+
83
+ // A teleport snaps the camera instead of swooshing it across the map. The
84
+ // player's position from the previous frame is what detects it.
85
+ const last = rt.camLastAt;
86
+ const jumped = last && Math.hypot(t.x - last.x, t.z - last.z) > TELEPORT_PER_FRAME;
87
+ rt.camLastAt = { x: t.x, z: t.z };
88
+ if (jumped || Math.hypot(targetX - cam.position.x, targetZ - cam.position.z) > 20) {
80
89
  cam.position.set(targetX, targetY, targetZ);
81
90
  } else {
82
91
  const lerp = 1 - Math.exp(-12 * dt);
@@ -49,16 +49,16 @@
49
49
  "imports": {
50
50
  "castle.physics-2d": {
51
51
  "deckId": "ckRZGFW4iPrx",
52
- "version": "2026-09-13T17:33:26.446Z"
52
+ "version": "2026-09-22T19:49:07.246Z"
53
53
  },
54
54
  "castle.base": {
55
55
  "deckId": "yRcmH4_aYllE",
56
- "version": "2026-09-11T20:21:04.335Z"
56
+ "version": "2026-09-22T19:48:55.642Z"
57
57
  }
58
58
  },
59
59
  "main": "main.jsx",
60
60
  "autoUpdateWhenImported": true,
61
61
  "deckId": "JH0SclbPVP0y",
62
62
  "cardId": "eXfAaUdbSU5A",
63
- "publishedVersion": "2026-09-14T02:38:17.286Z"
63
+ "publishedVersion": "2026-09-22T19:49:18.182Z"
64
64
  }
@@ -34,7 +34,7 @@
34
34
  },
35
35
  "../../sdk": {
36
36
  "name": "castle-web-sdk",
37
- "version": "0.4.28",
37
+ "version": "0.4.31",
38
38
  "dev": true,
39
39
  "devDependencies": {
40
40
  "eslint": "^9.0.0",
@@ -3,11 +3,11 @@
3
3
  "imports": {
4
4
  "castle.base": {
5
5
  "deckId": "yRcmH4_aYllE",
6
- "version": "2026-09-11T20:21:04.335Z"
6
+ "version": "2026-09-22T19:48:55.642Z"
7
7
  }
8
8
  },
9
9
  "autoUpdateWhenImported": true,
10
10
  "deckId": "xFVr-afOLuUQ",
11
11
  "cardId": "w6G45sy3_P_m",
12
- "publishedVersion": "2026-09-16T21:18:06.448Z"
12
+ "publishedVersion": "2026-09-22T19:48:58.226Z"
13
13
  }
@@ -16,7 +16,7 @@
16
16
  },
17
17
  "../../sdk": {
18
18
  "name": "castle-web-sdk",
19
- "version": "0.4.28",
19
+ "version": "0.4.31",
20
20
  "dev": true,
21
21
  "devDependencies": {
22
22
  "eslint": "^9.0.0",
@@ -6,18 +6,18 @@
6
6
  "imports": {
7
7
  "castle.physics-2d": {
8
8
  "deckId": "ckRZGFW4iPrx",
9
- "version": "2026-09-16T21:17:53.144Z"
9
+ "version": "2026-09-22T19:47:03.057Z"
10
10
  },
11
11
  "castle.base": {
12
12
  "deckId": "yRcmH4_aYllE",
13
- "version": "2026-09-11T20:21:04.335Z"
13
+ "version": "2026-09-22T19:48:55.642Z"
14
14
  }
15
15
  },
16
16
  "main": "main.jsx",
17
17
  "autoUpdateWhenImported": true,
18
18
  "deckId": "K6-Xs7dCoMVi",
19
19
  "cardId": "Kh_08IYATpC3",
20
- "publishedVersion": "2026-09-17T20:55:48.861Z",
20
+ "publishedVersion": "2026-09-22T19:49:03.070Z",
21
21
  "server": {
22
22
  "main": "code/server/index.js",
23
23
  "maxPlayers": 8,
@@ -28,7 +28,7 @@
28
28
  },
29
29
  "../../sdk": {
30
30
  "name": "castle-web-sdk",
31
- "version": "0.4.28",
31
+ "version": "0.4.31",
32
32
  "dev": true,
33
33
  "devDependencies": {
34
34
  "eslint": "^9.0.0",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "castle-web-cli",
3
- "version": "0.4.199",
3
+ "version": "0.4.200",
4
4
  "repository": {
5
5
  "type": "git",
6
6
  "url": "git+https://github.com/castle-xyz/castle-experimental-web.git"