castle-web-cli 0.4.198 → 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.
Files changed (46) hide show
  1. package/dist/castle-host/host.js +22 -0
  2. package/dist/init.js +1 -1
  3. package/dist/serve.js +3 -0
  4. package/dist/shell/assets/{index-B9lbHsWz.js → index-DJSLmPmw.js} +3 -3
  5. package/dist/shell/assets/index-uXcYGwQC.css +1 -0
  6. package/dist/shell/index.html +2 -2
  7. package/kits/base/CLAUDE.md +1 -1
  8. package/kits/base/castle.json +1 -1
  9. package/kits/base/package-lock.json +1 -1
  10. package/kits/base/sdk/README.md +48 -18
  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 +10 -0
  14. package/kits/base/sdk/paramsRegistry.d.ts +6 -4
  15. package/kits/base/sdk/paramsRegistry.js +28 -11
  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/behaviors/Collider.jsx +3 -3
  27. package/kits/physics-2d/behaviors/Joints.jsx +2 -2
  28. package/kits/physics-2d/castle.json +2 -2
  29. package/kits/physics-2d/editors/SceneEditor.jsx +5 -5
  30. package/kits/physics-2d/editors/pxArtTimeline.jsx +1 -1
  31. package/kits/physics-2d/editors/pxArtTimeline.module.css +73 -73
  32. package/kits/physics-2d/editors/themeEditor.module.css +17 -17
  33. package/kits/physics-2d/engine/castle-tokens.css +64 -0
  34. package/kits/physics-2d/engine/fields/fields.module.css +43 -37
  35. package/kits/physics-2d/engine/ui.jsx +1 -0
  36. package/kits/physics-2d/engine/ui.module.css +262 -288
  37. package/kits/physics-2d/package-lock.json +6 -1
  38. package/kits/physics-3d/behaviors/Player.jsx +12 -3
  39. package/kits/physics-3d/castle.json +3 -3
  40. package/kits/physics-3d/package-lock.json +1 -1
  41. package/kits/real-time/castle.json +2 -2
  42. package/kits/real-time/package-lock.json +1 -1
  43. package/kits/turn-based/castle.json +3 -3
  44. package/kits/turn-based/package-lock.json +1 -1
  45. package/package.json +1 -1
  46. package/dist/shell/assets/index-p8e-uehb.css +0 -1
@@ -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`
@@ -9,9 +9,9 @@ const rowGap = { display: 'flex', flexWrap: 'wrap', alignItems: 'center', gap: 6
9
9
  const chip = (active) => ({
10
10
  padding: '3px 9px',
11
11
  borderRadius: 6,
12
- border: `1px solid ${active ? '#4aa3ff' : 'var(--castle-inspector-divider)'}`,
12
+ border: `1px solid ${active ? '#4aa3ff' : 'var(--castle-border-1)'}`,
13
13
  background: active ? 'rgba(74,163,255,0.15)' : 'transparent',
14
- color: 'var(--castle-inspector-text)',
14
+ color: 'var(--castle-text-primary)',
15
15
  fontFamily: 'inherit',
16
16
  fontSize: 12,
17
17
  cursor: 'pointer',
@@ -29,7 +29,7 @@ const linkBtn = {
29
29
  };
30
30
  const deleteBtn = { ...linkBtn, color: '#ff7a7a' };
31
31
  const actionRow = { display: 'flex', justifyContent: 'space-between', alignItems: 'center', margin: '4px 0 12px' };
32
- const noteStyle = { fontSize: 12, color: 'var(--castle-inspector-muted, #888)', margin: '2px 0 10px' };
32
+ const noteStyle = { fontSize: 12, color: 'var(--castle-text-muted)', margin: '2px 0 10px' };
33
33
  const resetRow = { display: 'flex', justifyContent: 'space-between', alignItems: 'center', margin: '2px 0 10px' };
34
34
  const overrideNote = { fontSize: 12, color: '#b58dff' };
35
35
  const resetLink = { ...linkBtn, color: '#b58dff' };
@@ -235,7 +235,7 @@ function AnchorFields({ joint, isPivot, onPatch }) {
235
235
  );
236
236
  }
237
237
 
238
- const entryBox = { borderTop: '1px solid var(--castle-inspector-divider)', paddingTop: 8, marginBottom: 6 };
238
+ const entryBox = { borderTop: '1px solid var(--castle-border-1)', paddingTop: 8, marginBottom: 6 };
239
239
  const anchorToggle = {
240
240
  background: 'none',
241
241
  border: 'none',
@@ -249,7 +249,7 @@ const entryHead = { display: 'flex', justifyContent: 'space-between', alignItems
249
249
  const entryTitle = { color: '#c9a9ff', fontSize: 13 };
250
250
  const removeLink = { background: 'none', border: 'none', padding: 0, color: '#ff7a7a', fontSize: 12, cursor: 'pointer' };
251
251
  const targetRow = { display: 'flex', flexDirection: 'column', gap: 6, margin: '4px 0 10px' };
252
- const targetText = { fontSize: 13, color: 'var(--castle-inspector-text)' };
252
+ const targetText = { fontSize: 13, color: 'var(--castle-text-primary)' };
253
253
 
254
254
  // Draw the link between two world points, styled by joint type: spring coils,
255
255
  // rope dashes, weld doubles the line, rod is a plain line.
@@ -67,11 +67,11 @@
67
67
  "autoUpdateWhenImported": true,
68
68
  "onUpdate": "scripts/onUpdate.mjs",
69
69
  "title": "physics-2d",
70
- "publishedVersion": "2026-09-18T20:10:58.457Z",
70
+ "publishedVersion": "2026-09-22T19:49:07.246Z",
71
71
  "imports": {
72
72
  "castle.base": {
73
73
  "deckId": "yRcmH4_aYllE",
74
- "version": "2026-09-18T20:02:20.225Z"
74
+ "version": "2026-09-22T19:48:55.642Z"
75
75
  }
76
76
  }
77
77
  }
@@ -1092,7 +1092,7 @@ function setSceneEditorSettings(sceneData, nextEditor) {
1092
1092
  }
1093
1093
  function darkenSceneBackground(background) {
1094
1094
  const parsed = parseHexColor(background ?? '#121213');
1095
- if (!parsed) return 'var(--castle-stage-workspace-bg)';
1095
+ if (!parsed) return 'var(--kit-stage-workspace-bg)';
1096
1096
  const amount = 0.42;
1097
1097
  const darken = (channel) => Math.max(0, Math.round(channel * (1 - amount)));
1098
1098
  return `rgb(${darken(parsed.r)}, ${darken(parsed.g)}, ${darken(parsed.b)})`;
@@ -1914,7 +1914,7 @@ function inspectorActionStyle(disabled) {
1914
1914
  padding: '6px 10px',
1915
1915
  background: 'transparent',
1916
1916
  color: 'inherit',
1917
- border: '1px solid var(--castle-inspector-divider)',
1917
+ border: '1px solid var(--castle-border-1)',
1918
1918
  borderRadius: 6,
1919
1919
  cursor: disabled ? 'default' : 'pointer',
1920
1920
  opacity: disabled ? 0.5 : 1,
@@ -2397,7 +2397,7 @@ function BehaviorRow({
2397
2397
  className={cx(styles.behaviorRow, isDragging && styles.behaviorRowDragging)}
2398
2398
  style={{
2399
2399
  ...rowProps.style,
2400
- borderBottom: isLast ? undefined : '1px solid var(--castle-inspector-divider)',
2400
+ borderBottom: isLast ? undefined : '1px solid var(--castle-border-1)',
2401
2401
  }}>
2402
2402
  <BehaviorPanel
2403
2403
  summary={behaviorSummary(Behavior, component)}
@@ -2434,11 +2434,11 @@ function AddBehaviorPicker({ available, onAdd }) {
2434
2434
  return (
2435
2435
  <div
2436
2436
  style={{
2437
- height: 'var(--castle-hotbar-row-full)',
2437
+ height: 'var(--kit-hotbar-row-full)',
2438
2438
  padding: '0 16px',
2439
2439
  display: 'flex',
2440
2440
  alignItems: 'center',
2441
- borderBottom: '1px solid var(--castle-inspector-divider)',
2441
+ borderBottom: '1px solid var(--castle-border-1)',
2442
2442
  }}>
2443
2443
  <select
2444
2444
  className={cx(fieldStyles.input, fieldStyles.select)}
@@ -735,7 +735,7 @@ const kindBadgeStyle = {
735
735
  display: 'inline-flex',
736
736
  alignItems: 'center',
737
737
  justifyContent: 'center',
738
- color: 'var(--castle-muted, #888)',
738
+ color: 'var(--castle-text-muted)',
739
739
  fontSize: 11,
740
740
  opacity: 0.85,
741
741
  };