castle-web-cli 0.4.199 → 0.4.201

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.
Files changed (43) hide show
  1. package/dist/castle-host/host.js +80 -0
  2. package/dist/init.js +1 -1
  3. package/dist/platformDoc.js +1 -0
  4. package/dist/serve.js +3 -0
  5. package/dist/shell/assets/index-CHMcsJrW.css +1 -0
  6. package/dist/shell/index.html +2 -2
  7. package/kits/base/CLAUDE.md +2 -2
  8. package/kits/base/castle.json +1 -1
  9. package/kits/base/package-lock.json +1 -1
  10. package/kits/base/sdk/README.md +73 -0
  11. package/kits/base/sdk/castle.d.ts +2 -0
  12. package/kits/base/sdk/castle.js +1 -0
  13. package/kits/base/sdk/commands.d.ts +26 -0
  14. package/kits/base/sdk/portal.d.ts +3 -2
  15. package/kits/base/sdk/portal.js +22 -0
  16. package/kits/base/sdk/snapshots.d.ts +12 -0
  17. package/kits/base/sdk/snapshots.js +128 -0
  18. package/kits/base/sdk/transport.js +1 -0
  19. package/kits/multiplayer-2d/castle.json +4 -4
  20. package/kits/multiplayer-2d/code/systems/multiplayer.js +48 -12
  21. package/kits/multiplayer-2d/package-lock.json +1 -1
  22. package/kits/multiplayer-3d/castle.json +5 -5
  23. package/kits/multiplayer-3d/code/systems/multiplayer.js +40 -6
  24. package/kits/multiplayer-3d/package-lock.json +1 -1
  25. package/kits/physics-2d/CLAUDE.md +5 -4
  26. package/kits/physics-2d/castle.json +2 -2
  27. package/kits/physics-2d/engine/castle-patterns.css +1206 -0
  28. package/kits/physics-2d/engine/castle-tokens.css +32 -0
  29. package/kits/physics-2d/engine/ui.jsx +1 -0
  30. package/kits/physics-2d/engine/ui.module.css +0 -7
  31. package/kits/physics-2d/package-lock.json +1 -1
  32. package/kits/physics-3d/behaviors/Player.jsx +12 -3
  33. package/kits/physics-3d/castle.json +3 -3
  34. package/kits/physics-3d/package-lock.json +1 -1
  35. package/kits/real-time/castle.json +2 -2
  36. package/kits/real-time/package-lock.json +1 -1
  37. package/kits/turn-based/castle.json +3 -3
  38. package/kits/turn-based/package-lock.json +1 -1
  39. package/package.json +1 -1
  40. package/dist/shell/assets/Basteleur-Bold-CK8LF7Pt.woff +0 -0
  41. package/dist/shell/assets/Basteleur-Bold-DKFKedNb.woff2 +0 -0
  42. package/dist/shell/assets/index-uXcYGwQC.css +0 -1
  43. /package/dist/shell/assets/{index-DJSLmPmw.js → index-CxrtbzHf.js} +0 -0
@@ -48,11 +48,27 @@ 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;
54
58
  }
55
59
  export type PortalPrefetchStatus = "prefetching" | "rejected" | "unavailable";
60
+ export type PortalInfoResult = {
61
+ status: "ok";
62
+ deckId: string;
63
+ title: string;
64
+ creator: {
65
+ userId: string;
66
+ username: string;
67
+ } | null;
68
+ coverUrl: string | null;
69
+ } | {
70
+ status: "broken" | "unavailable";
71
+ };
56
72
  export interface PortalPrefetchResult {
57
73
  status: PortalPrefetchStatus;
58
74
  }
@@ -171,12 +187,20 @@ export interface CommandParams {
171
187
  "pass.offer": {
172
188
  passId: string;
173
189
  };
190
+ "snapshot.offer": {
191
+ title: string;
192
+ description: string;
193
+ bricksPrice: number;
194
+ };
174
195
  "portal.open": {
175
196
  targetDeckId: string;
176
197
  };
177
198
  "portal.prefetch": {
178
199
  targetDeckId: string;
179
200
  };
201
+ "portal.info": {
202
+ targetDeckId: string;
203
+ };
180
204
  "haptics.play": {
181
205
  style: HapticStyle;
182
206
  };
@@ -294,8 +318,10 @@ export interface CommandResult {
294
318
  hasPass: boolean;
295
319
  };
296
320
  "pass.offer": PassOfferResult;
321
+ "snapshot.offer": SnapshotOfferResult;
297
322
  "portal.open": PortalOpenResult;
298
323
  "portal.prefetch": PortalPrefetchResult;
324
+ "portal.info": PortalInfoResult;
299
325
  "haptics.play": HapticsResult;
300
326
  "multiplayer.getSession": MultiplayerGetSessionResult;
301
327
  "characters.open": CharacterAdmission;
@@ -1,7 +1,8 @@
1
- import type { PortalOpenResult, PortalPrefetchResult } from "./commands";
2
- export type { PortalOpenResult, PortalOpenStatus, PortalPrefetchResult, PortalPrefetchStatus, } from "./commands";
1
+ import type { PortalInfoResult, PortalOpenResult, PortalPrefetchResult } from "./commands";
2
+ export type { PortalInfoResult, PortalOpenResult, PortalOpenStatus, PortalPrefetchResult, PortalPrefetchStatus, } from "./commands";
3
3
  export interface CastlePortalApi {
4
4
  open(deckId: string): Promise<PortalOpenResult>;
5
5
  prefetch(deckId: string): Promise<PortalPrefetchResult>;
6
+ info(deckId: string): Promise<PortalInfoResult>;
6
7
  }
7
8
  export declare const Portal: CastlePortalApi;
@@ -7,11 +7,16 @@
7
7
  // Navigation is effectively fire-and-forget: once the host accepts it, the
8
8
  // source deck is torn down as the feed moves to the target, so a deck should
9
9
  // not rely on code running after a successful `open`.
10
+ //
11
+ // `info` is a plain read of where a portal leads: the target's title, creator
12
+ // and cover, for a sign on the portal. It works on every host that has a
13
+ // Castle login.
10
14
  import { CastleError } from "./errors";
11
15
  import { hostRequest } from "./transport";
12
16
  export const Portal = {
13
17
  open,
14
18
  prefetch,
19
+ info,
15
20
  };
16
21
  async function open(deckId) {
17
22
  if (typeof deckId !== "string" || deckId.length === 0) {
@@ -33,3 +38,20 @@ async function prefetch(deckId) {
33
38
  }
34
39
  return hostRequest("portal.prefetch", { targetDeckId: deckId });
35
40
  }
41
+ async function info(deckId) {
42
+ if (typeof deckId !== "string" || deckId.length === 0) {
43
+ throw new CastleError({
44
+ code: "INVALID_ARGUMENT",
45
+ message: "Portal.info requires a deckId.",
46
+ operation: "Portal.info",
47
+ });
48
+ }
49
+ try {
50
+ return await hostRequest("portal.info", { targetDeckId: deckId });
51
+ }
52
+ catch {
53
+ // No login, an old host, or a failed lookup all read the same to a deck:
54
+ // there is nothing to show, so it keeps whatever label it had.
55
+ return { status: "unavailable" };
56
+ }
57
+ }
@@ -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-23T02:16:34.231Z",
71
71
  "imports": {
72
72
  "castle.base": {
73
73
  "deckId": "yRcmH4_aYllE",
74
- "version": "2026-09-22T19:37:37.345Z"
74
+ "version": "2026-09-23T02:16:18.339Z"
75
75
  }
76
76
  }
77
77
  }