castle-web-cli 0.4.229 → 0.4.230

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 (232) hide show
  1. package/dist/agent-prompts.d.ts +2 -0
  2. package/dist/agent-prompts.js +16 -8
  3. package/dist/agent.d.ts +2 -0
  4. package/dist/agent.js +21 -21
  5. package/dist/api.d.ts +28 -2
  6. package/dist/api.js +74 -16
  7. package/dist/castle-host/host.d.ts +91 -0
  8. package/dist/castle-host/host.js +779 -3
  9. package/dist/castleJson.d.ts +44 -0
  10. package/dist/castleJson.js +131 -0
  11. package/dist/check.js +27 -1
  12. package/dist/contentPack.d.ts +49 -0
  13. package/dist/contentPack.js +273 -0
  14. package/dist/devExperiments.d.ts +21 -0
  15. package/dist/devExperiments.js +139 -0
  16. package/dist/devHub.d.ts +55 -0
  17. package/dist/devHub.js +187 -0
  18. package/dist/devSessionChild.js +3 -1
  19. package/dist/devSessionServer.d.ts +14 -1
  20. package/dist/devSessionServer.js +229 -44
  21. package/dist/experimentAssignment.d.ts +15 -0
  22. package/dist/experimentAssignment.js +41 -0
  23. package/dist/importCheckHook.d.ts +40 -0
  24. package/dist/importCheckHook.js +171 -0
  25. package/dist/importRegression.d.ts +15 -0
  26. package/dist/importRegression.js +100 -0
  27. package/dist/importTrust.d.ts +2 -0
  28. package/dist/importTrust.js +27 -0
  29. package/dist/importUpdateHook.d.ts +18 -0
  30. package/dist/importUpdateHook.js +31 -8
  31. package/dist/importUpdateHookRunner.js +19 -7
  32. package/dist/imports.d.ts +16 -0
  33. package/dist/imports.js +141 -31
  34. package/dist/index.js +3 -1
  35. package/dist/init.d.ts +3 -0
  36. package/dist/init.js +125 -8
  37. package/dist/install.js +4 -1
  38. package/dist/localPaths.js +4 -0
  39. package/dist/login.js +2 -2
  40. package/dist/platformDoc.js +3 -8
  41. package/dist/playPagePolicy.js +3 -1
  42. package/dist/remix.js +5 -0
  43. package/dist/routerTaskReport.d.ts +28 -0
  44. package/dist/routerTaskReport.js +56 -0
  45. package/dist/save-deck.d.ts +18 -0
  46. package/dist/save-deck.js +142 -6
  47. package/dist/serve.d.ts +8 -0
  48. package/dist/serve.js +94 -13
  49. package/dist/serverBundle.d.ts +1 -1
  50. package/dist/serverBundle.js +5 -1
  51. package/dist/webSourceSync.d.ts +2 -0
  52. package/dist/webSourceSync.js +2 -0
  53. package/kits/base/CLAUDE.md +2 -3
  54. package/kits/base/castle.json +1 -1
  55. package/kits/base/sdk/README.md +258 -52
  56. package/kits/base/sdk/agent.js +4 -4
  57. package/kits/base/sdk/avatar.d.ts +12 -0
  58. package/kits/base/sdk/avatar.js +23 -0
  59. package/kits/base/sdk/castle.d.ts +5 -0
  60. package/kits/base/sdk/castle.js +3 -0
  61. package/kits/base/sdk/commands.d.ts +208 -0
  62. package/kits/base/sdk/commands.js +16 -0
  63. package/kits/base/sdk/context.d.ts +6 -0
  64. package/kits/base/sdk/experiments.d.ts +15 -0
  65. package/kits/base/sdk/experiments.js +83 -0
  66. package/kits/base/sdk/hub.d.ts +85 -0
  67. package/kits/base/sdk/hub.js +107 -0
  68. package/kits/base/sdk/multiplayer.d.ts +45 -1
  69. package/kits/base/sdk/multiplayer.js +106 -4
  70. package/kits/base/sdk/server/hub.d.ts +169 -0
  71. package/kits/base/sdk/server/hub.js +125 -0
  72. package/kits/base/sdk/server/platformHandle.d.ts +42 -1
  73. package/kits/base/sdk/server/storage.d.ts +55 -2
  74. package/kits/base/sdk/server/wrapper.d.ts +32 -2
  75. package/kits/base/sdk/server/wrapper.js +90 -11
  76. package/kits/base/sdk/transport.d.ts +2 -1
  77. package/kits/base/sdk/transport.js +13 -1
  78. package/kits/hub-game/.prettierrc +5 -0
  79. package/kits/hub-game/CLAUDE.md +146 -0
  80. package/kits/hub-game/blueprints/avatar-0.scene +28 -0
  81. package/kits/hub-game/blueprints/avatar-1.scene +28 -0
  82. package/kits/hub-game/blueprints/avatar-2.scene +28 -0
  83. package/kits/hub-game/blueprints/avatar-3.scene +28 -0
  84. package/kits/hub-game/blueprints/bean/avatar-0.scene +28 -0
  85. package/kits/hub-game/blueprints/bean/avatar-1.scene +28 -0
  86. package/kits/hub-game/blueprints/bean/avatar-2.scene +28 -0
  87. package/kits/hub-game/blueprints/bean/avatar-3.scene +28 -0
  88. package/kits/hub-game/blueprints/blocky/avatar-0.scene +28 -0
  89. package/kits/hub-game/blueprints/blocky/avatar-1.scene +28 -0
  90. package/kits/hub-game/blueprints/blocky/avatar-2.scene +28 -0
  91. package/kits/hub-game/blueprints/blocky/avatar-3.scene +28 -0
  92. package/kits/hub-game/blueprints/pixel/avatar-0.scene +28 -0
  93. package/kits/hub-game/blueprints/pixel/avatar-1.scene +28 -0
  94. package/kits/hub-game/blueprints/pixel/avatar-2.scene +28 -0
  95. package/kits/hub-game/blueprints/pixel/avatar-3.scene +28 -0
  96. package/kits/hub-game/castle.json +96 -0
  97. package/kits/hub-game/code/client/attention.js +133 -0
  98. package/kits/hub-game/code/client/avatar.js +288 -0
  99. package/kits/hub-game/code/client/cabinets.js +90 -0
  100. package/kits/hub-game/code/client/chat.js +135 -0
  101. package/kits/hub-game/code/client/chrome.js +1001 -0
  102. package/kits/hub-game/code/client/doorFrame.js +15 -0
  103. package/kits/hub-game/code/client/firstJoin.js +14 -0
  104. package/kits/hub-game/code/client/grab.js +241 -0
  105. package/kits/hub-game/code/client/hookLayer.js +230 -0
  106. package/kits/hub-game/code/client/idle.js +326 -0
  107. package/kits/hub-game/code/client/keys.js +48 -0
  108. package/kits/hub-game/code/client/pack.js +232 -0
  109. package/kits/hub-game/code/client/packFormat.js +397 -0
  110. package/kits/hub-game/code/client/say.js +127 -0
  111. package/kits/hub-game/code/client/sha256.js +80 -0
  112. package/kits/hub-game/code/client/sound.js +147 -0
  113. package/kits/hub-game/code/client/state.js +131 -0
  114. package/kits/hub-game/code/client/talk.js +259 -0
  115. package/kits/hub-game/code/client/together.js +365 -0
  116. package/kits/hub-game/code/client/wear.js +149 -0
  117. package/kits/hub-game/code/server/actors.js +627 -0
  118. package/kits/hub-game/code/server/blocks.js +103 -0
  119. package/kits/hub-game/code/server/cabinets.js +309 -0
  120. package/kits/hub-game/code/server/game.js +137 -0
  121. package/kits/hub-game/code/server/grab.js +247 -0
  122. package/kits/hub-game/code/server/history.js +96 -0
  123. package/kits/hub-game/code/server/hub.js +1904 -0
  124. package/kits/hub-game/code/server/idle.js +412 -0
  125. package/kits/hub-game/code/server/index.js +64 -0
  126. package/kits/hub-game/code/server/labels.js +59 -0
  127. package/kits/hub-game/code/server/manifest.js +527 -0
  128. package/kits/hub-game/code/server/npcs.js +745 -0
  129. package/kits/hub-game/code/server/party.js +381 -0
  130. package/kits/hub-game/code/server/place.js +43 -0
  131. package/kits/hub-game/code/server/say.js +83 -0
  132. package/kits/hub-game/code/server/wear.js +142 -0
  133. package/kits/hub-game/code/systems/hub.js +2230 -0
  134. package/kits/hub-game/docs/content-pack.md +151 -0
  135. package/kits/hub-game/docs/contract.md +1139 -0
  136. package/kits/hub-game/docs/style.md +137 -0
  137. package/kits/hub-game/drawings/blocky/castle-eye.sprite +58 -0
  138. package/kits/hub-game/drawings/blocky/dash.sprite +59 -0
  139. package/kits/hub-game/drawings/blocky/pom.sprite +59 -0
  140. package/kits/hub-game/drawings/blocky/tabby.sprite +59 -0
  141. package/kits/hub-game/drawings/pixel/castle-arm.sprite +13 -0
  142. package/kits/hub-game/drawings/pixel/castle-body.sprite +23 -0
  143. package/kits/hub-game/drawings/pixel/castle-leg.sprite +12 -0
  144. package/kits/hub-game/drawings/pixel/kai-arm.sprite +14 -0
  145. package/kits/hub-game/drawings/pixel/kai-head.sprite +24 -0
  146. package/kits/hub-game/drawings/pixel/kai-leg.sprite +15 -0
  147. package/kits/hub-game/drawings/pixel/kai-torso.sprite +18 -0
  148. package/kits/hub-game/drawings/pixel/mimi-arm.sprite +13 -0
  149. package/kits/hub-game/drawings/pixel/mimi-head.sprite +23 -0
  150. package/kits/hub-game/drawings/pixel/mimi-leg.sprite +15 -0
  151. package/kits/hub-game/drawings/pixel/mimi-torso.sprite +18 -0
  152. package/kits/hub-game/drawings/pixel/nox-arm.sprite +13 -0
  153. package/kits/hub-game/drawings/pixel/nox-head.sprite +21 -0
  154. package/kits/hub-game/drawings/pixel/nox-leg.sprite +14 -0
  155. package/kits/hub-game/drawings/pixel/nox-torso.sprite +18 -0
  156. package/kits/hub-game/eslint.config.js +20 -0
  157. package/kits/hub-game/fonts.generated.js +9 -0
  158. package/kits/hub-game/index.html +22 -0
  159. package/kits/hub-game/main.jsx +6 -0
  160. package/kits/hub-game/models/avatar-0.pxmodel +21 -0
  161. package/kits/hub-game/models/avatar-1.pxmodel +24 -0
  162. package/kits/hub-game/models/avatar-2.pxmodel +27 -0
  163. package/kits/hub-game/models/avatar-3.pxmodel +22 -0
  164. package/kits/hub-game/models/bean/avatar-0.pxmodel +19 -0
  165. package/kits/hub-game/models/bean/avatar-1.pxmodel +24 -0
  166. package/kits/hub-game/models/bean/avatar-2.pxmodel +22 -0
  167. package/kits/hub-game/models/bean/avatar-3.pxmodel +24 -0
  168. package/kits/hub-game/models/blocky/avatar-0.pxmodel +21 -0
  169. package/kits/hub-game/models/blocky/avatar-1.pxmodel +30 -0
  170. package/kits/hub-game/models/blocky/avatar-2.pxmodel +28 -0
  171. package/kits/hub-game/models/blocky/avatar-3.pxmodel +27 -0
  172. package/kits/hub-game/models/pixel/avatar-0.pxmodel +24 -0
  173. package/kits/hub-game/models/pixel/avatar-1.pxmodel +16 -0
  174. package/kits/hub-game/models/pixel/avatar-2.pxmodel +19 -0
  175. package/kits/hub-game/models/pixel/avatar-3.pxmodel +23 -0
  176. package/kits/hub-game/package-lock.json +365 -0
  177. package/kits/hub-game/package.json +32 -0
  178. package/kits/hub-game/scenes/main.scene +318 -0
  179. package/kits/hub-game/scripts/check.mjs +339 -0
  180. package/kits/hub-game/scripts/fixtures/sdk-stub.mjs +3 -0
  181. package/kits/hub-game/scripts/gen-avatars-bean.mjs +748 -0
  182. package/kits/hub-game/scripts/gen-avatars-blocky.mjs +607 -0
  183. package/kits/hub-game/scripts/gen-avatars-pixel.mjs +771 -0
  184. package/kits/hub-game/scripts/gen-avatars.mjs +621 -0
  185. package/kits/hub-game/scripts/pack.mjs +192 -0
  186. package/kits/hub-game/scripts/test-actors.mjs +666 -0
  187. package/kits/hub-game/scripts/test-attention.mjs +103 -0
  188. package/kits/hub-game/scripts/test-avatar.mjs +472 -0
  189. package/kits/hub-game/scripts/test-ban-join.mjs +194 -0
  190. package/kits/hub-game/scripts/test-blocks.mjs +351 -0
  191. package/kits/hub-game/scripts/test-chat.mjs +98 -0
  192. package/kits/hub-game/scripts/test-classic.mjs +590 -0
  193. package/kits/hub-game/scripts/test-door-jump.mjs +131 -0
  194. package/kits/hub-game/scripts/test-door.mjs +56 -0
  195. package/kits/hub-game/scripts/test-grab.mjs +331 -0
  196. package/kits/hub-game/scripts/test-hub-ops.mjs +835 -0
  197. package/kits/hub-game/scripts/test-hub-trip.mjs +1310 -0
  198. package/kits/hub-game/scripts/test-idle.mjs +518 -0
  199. package/kits/hub-game/scripts/test-interest.mjs +413 -0
  200. package/kits/hub-game/scripts/test-keys.mjs +50 -0
  201. package/kits/hub-game/scripts/test-manifest.mjs +224 -0
  202. package/kits/hub-game/scripts/test-no-forms.mjs +16 -0
  203. package/kits/hub-game/scripts/test-npcs.mjs +714 -0
  204. package/kits/hub-game/scripts/test-pack.mjs +424 -0
  205. package/kits/hub-game/scripts/test-party.mjs +286 -0
  206. package/kits/hub-game/scripts/test-say.mjs +149 -0
  207. package/kits/hub-game/scripts/test-together.mjs +183 -0
  208. package/kits/hub-game/theme.style +3 -0
  209. package/kits/multiplayer-3d/castle.json +5 -5
  210. package/kits/multiplayer-3d/code/client/avatars.js +101 -1
  211. package/kits/multiplayer-3d/code/server/players.js +4 -1
  212. package/kits/multiplayer-3d/code/server/sceneBodies.js +27 -6
  213. package/kits/multiplayer-3d/code/server/world.js +20 -7
  214. package/kits/multiplayer-3d/code/systems/multiplayer.js +222 -11
  215. package/kits/physics-2d/castle.json +2 -2
  216. package/kits/physics-2d/engine/art.js +13 -0
  217. package/kits/physics-2d/engine/assets.js +4 -2
  218. package/kits/physics-2d/engine/scene.js +25 -5
  219. package/kits/physics-3d/CLAUDE.md +6 -1
  220. package/kits/physics-3d/castle.json +3 -3
  221. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +32 -4
  222. package/kits/physics-3d/engine3d/artobjects.js +2 -2
  223. package/kits/physics-3d/engine3d/materials.js +29 -1
  224. package/kits/physics-3d/engine3d/world3d.js +65 -1
  225. package/kits/physics-3d/systems/physics3d.js +5 -2
  226. package/kits/real-time/castle.json +2 -2
  227. package/kits/real-time/code/client/connection.js +77 -7
  228. package/kits/real-time/code/client/gameHooks.js +63 -3
  229. package/kits/real-time/code/client/messages.js +7 -0
  230. package/kits/real-time/code/server/gameHooks.js +24 -0
  231. package/kits/real-time/code/server/session.js +390 -22
  232. package/package.json +2 -2
@@ -8,9 +8,11 @@ import { initialMedia, isImageFile } from './files';
8
8
  // URLs, not text, so it comes straight from the bundler rather than through the
9
9
  // live file map). Shared by the editor App and the play-only entry point so both
10
10
  // hand the SceneRuntime the same map.
11
- export function collectAssets(files) {
11
+ // `media` is the path -> URL map images come from: this deck's bundled media
12
+ // unless the files are another deck's (a content pack brings its own).
13
+ export function collectAssets(files, media = initialMedia) {
12
14
  const sprites = {};
13
- for (const [path, url] of Object.entries(initialMedia)) {
15
+ for (const [path, url] of Object.entries(media)) {
14
16
  if (isImageFile(path)) sprites[path] = imageArt(path, url);
15
17
  }
16
18
  for (const [path, text] of Object.entries(files)) {
@@ -22,7 +22,7 @@ export const cardSize = { width: CARD_WIDTH, height: CARD_HEIGHT };
22
22
  // Resolve a scene-file name to its key in the loaded file map. Accepts
23
23
  // 'main.scene', 'scenes/main.scene', './scenes/main.scene', or 'main' -- the
24
24
  // `.scene` extension and a leading `scenes/` are both optional.
25
- function resolveSceneFileKey(name) {
25
+ function resolveSceneFileKey(name, files = initialFiles) {
26
26
  // `@imports/<alias>/scenes/x.scene` names an import's scene; anything else is
27
27
  // this deck's, with the `scenes/` folder and `.scene` suffix both optional.
28
28
  const key = resolveDeckFile(String(name));
@@ -31,7 +31,7 @@ function resolveSceneFileKey(name) {
31
31
  for (const candidate of [...candidates]) {
32
32
  if (!candidate.startsWith('scenes/')) candidates.push(`scenes/${candidate}`);
33
33
  }
34
- return candidates.find((candidate) => initialFiles[candidate] !== undefined) ?? key;
34
+ return candidates.find((candidate) => files[candidate] !== undefined) ?? key;
35
35
  }
36
36
 
37
37
  // `$enabled: false` turns a behavior off while keeping its props. Absent means
@@ -264,8 +264,9 @@ export class SceneRuntime {
264
264
  // instead of `import x from './scenes/foo.scene'` -- scene files are data, not
265
265
  // JS modules, so importing them is unsupported.
266
266
  readFromFile(name) {
267
- const key = resolveSceneFileKey(name);
268
- const text = initialFiles[key];
267
+ const files = this.content?.files ?? initialFiles;
268
+ const key = resolveSceneFileKey(name, files);
269
+ const text = files[key];
269
270
  if (text === undefined) {
270
271
  throw new Error(`scene file not found: ${name}`);
271
272
  }
@@ -277,10 +278,29 @@ export class SceneRuntime {
277
278
  // Transition the running scene to the scene stored in the named file (read it
278
279
  // fresh, then load it). The building block for "go to scene" / restart.
279
280
  loadFromFile(name) {
280
- this.scenePath = resolveSceneFileKey(name);
281
+ this.scenePath = resolveSceneFileKey(name, this.content?.files ?? initialFiles);
281
282
  this.load(this.readFromFile(name));
282
283
  }
283
284
 
285
+ // Swap whose content this runtime reads: another deck's, mounted as data (a
286
+ // hub content pack: `{ id, files, sprites }`), or null for this deck's own.
287
+ // Scene names, blueprints, models and art then resolve inside that content
288
+ // alone, so two decks' `scenes/main.scene` never meet. The swap takes effect
289
+ // at the next `loadFromFile`, which the caller makes in the same breath (the
290
+ // 3d player applies `requestedContent` with `requestedScene`).
291
+ setContent(content) {
292
+ this.ownContent ??= { files: this.files, sprites: this.sprites };
293
+ this.content = content ?? null;
294
+ this.files = content ? content.files : this.ownContent.files;
295
+ this.sprites = content ? content.sprites : this.ownContent.sprites;
296
+ }
297
+
298
+ // The scene's identity across contents: its path, qualified by the content
299
+ // it came from when that is not this deck's own.
300
+ get sceneKey() {
301
+ return this.content ? `${this.content.id}:${this.scenePath}` : this.scenePath;
302
+ }
303
+
284
304
  clone() {
285
305
  // Route through makeScene so the clone gets the same registered systems as a
286
306
  // freshly-made runtime.
@@ -49,9 +49,14 @@ bottom }`; any ref can pick a frame of a multi-frame sprite with
49
49
  load rebuilds the physics world and resets the scene to its authored state;
50
50
  `scene.persistent` survives loads -- the player's score, collected-pickup
51
51
  memory, and camera angle live there, so they cross scenes.
52
+ `scene.residentScenes` (a Set of scene paths) keeps those scenes' built
53
+ meshes parked while another scene plays, so coming back to one redraws it
54
+ without rebuilding them; anything not named is released on the load.
52
55
  - A scene can dress the ground: `"ground": { "art": "drawings/floor.sprite",
53
56
  "tile": 2, "color": "#..." }` at the scene file's top level (`tile` = meters
54
- per texture repeat). `Shape.artRepeat: [u, v]` tiles a texture across a
57
+ per texture repeat). `"ground": { "none": true }` has no ground at all, drawn
58
+ or stood on: whatever is not on an actor falls (pits, lava, sky islands).
59
+ `Shape.artRepeat: [u, v]` tiles a texture across a
55
60
  face so long walls don't stretch.
56
61
  - `.scene` files open in the kit's 3d scene editor (same chrome as the 2d
57
62
  kit's): blueprint hotbar (tap to inspect/edit the template, drag onto the
@@ -50,16 +50,16 @@
50
50
  "imports": {
51
51
  "castle.physics-2d": {
52
52
  "deckId": "ckRZGFW4iPrx",
53
- "version": "2026-09-23T02:16:34.231Z"
53
+ "version": "2026-10-03T04:25:18.207Z"
54
54
  },
55
55
  "castle.base": {
56
56
  "deckId": "yRcmH4_aYllE",
57
- "version": "2026-09-24T21:25:28.679Z"
57
+ "version": "2026-10-03T08:41:46.002Z"
58
58
  }
59
59
  },
60
60
  "main": "main.jsx",
61
61
  "autoUpdateWhenImported": true,
62
62
  "deckId": "JH0SclbPVP0y",
63
63
  "cardId": "eXfAaUdbSU5A",
64
- "publishedVersion": "2026-09-25T17:46:00.903Z"
64
+ "publishedVersion": "2026-10-03T09:17:32.572Z"
65
65
  }
@@ -39,6 +39,9 @@ export function Scene3DPlayer({
39
39
  // camera angle live here so they cross scene switches.
40
40
  runtime.persistent = {};
41
41
  runtime.currentScenePath = scenePath ?? 'scenes/main.scene';
42
+ // This loop applies `requestedContent` with `requestedScene` (another
43
+ // deck's content, mounted as data); a caller checks before asking.
44
+ runtime.mountsContent = true;
42
45
 
43
46
  const detachInput = attachInput(canvas, runtime, world);
44
47
  const stopResize = attachResize(canvas, world);
@@ -205,13 +208,11 @@ function startLoop(runtime, world, sprites, hudRefs, onFirstFrame, onError) {
205
208
  // registered systems -- the rapier world frees and lazily rebuilds --
206
209
  // while `runtime.persistent` carries the player's cross-scene state.
207
210
  if (runtime.requestedScene) {
208
- const next = runtime.requestedScene;
209
- runtime.requestedScene = null;
210
- runtime.loadFromFile(next);
211
+ const next = loadRequestedScene(runtime);
211
212
  runtime.currentScenePath = next;
212
213
  runtime.persistent.sceneChangeGraceUntil = runtime.time + 1;
213
214
  }
214
- syncActors(world, runtime, sprites, dt);
215
+ syncActors(world, runtime, runtime.sprites ?? sprites, dt);
215
216
  if (world.debugLines.visible) updatePhysicsDebug(world, runtime.physics3d?.debugRender());
216
217
  renderWorld(world);
217
218
  updateHud(runtime, hudRefs);
@@ -229,6 +230,33 @@ function startLoop(runtime, world, sprites, hudRefs, onFirstFrame, onError) {
229
230
  return () => cancelAnimationFrame(raf);
230
231
  }
231
232
 
233
+ // Load the scene a behavior asked for, with the content it comes from when
234
+ // that is another deck's (a hub content pack; `null` puts this deck's own
235
+ // back). Content that fails to load puts the scene that was running back and
236
+ // leaves the error on `runtime.mountError` for the asker. Returns the path now
237
+ // loaded.
238
+ function loadRequestedScene(runtime) {
239
+ const next = runtime.requestedScene;
240
+ runtime.requestedScene = null;
241
+ if (runtime.requestedContent === undefined) {
242
+ runtime.loadFromFile(next);
243
+ return next;
244
+ }
245
+ const before = { content: runtime.content ?? null, path: runtime.currentScenePath };
246
+ runtime.setContent(runtime.requestedContent);
247
+ runtime.requestedContent = undefined;
248
+ try {
249
+ runtime.loadFromFile(next);
250
+ return next;
251
+ } catch (err) {
252
+ console.error('[engine] content failed to load; staying where we were', err);
253
+ runtime.setContent(before.content);
254
+ runtime.loadFromFile(before.path);
255
+ runtime.mountError = err;
256
+ return before.path;
257
+ }
258
+ }
259
+
232
260
  // Behaviors write `scene.hud = { score, look }`; the loop pushes it into the
233
261
  // overlay divs imperatively (no react re-render at frame rate).
234
262
  function updateHud(runtime, hudRefs) {
@@ -7,7 +7,7 @@
7
7
  // change a part's materials after they are built.
8
8
 
9
9
  import * as THREE from 'three';
10
- import { makeMaterial, resolveArtTexture } from './materials';
10
+ import { makeMaterial, resolveArtTexture, trackDerivedTexture } from './materials';
11
11
  import { needsModelGeometry } from './partgeometry';
12
12
 
13
13
  const DEG = Math.PI / 180;
@@ -117,7 +117,7 @@ function specTexture(spec, part, sprites) {
117
117
  texture.center.set(0.5, 0.5);
118
118
  texture.rotation = rotation * DEG;
119
119
  texture.needsUpdate = true;
120
- variants.set(key, texture);
120
+ variants.set(key, trackDerivedTexture(base, texture));
121
121
  }
122
122
  return texture;
123
123
  }
@@ -13,6 +13,20 @@ import { renderArtFrame, artReady, artFrameCount } from '@imports/castle.physics
13
13
  // Baked textures cached per art object per frame (sprites are re-parsed only
14
14
  // when the file changes, so object identity is a good key).
15
15
  const textureCache = new WeakMap();
16
+ // Textures cloned from a cached one (tiling here, per-part variants in
17
+ // artobjects.js), by the texture they came from, so releasing an art's
18
+ // textures releases these too.
19
+ const derivedTextures = new WeakMap();
20
+
21
+ export function trackDerivedTexture(base, derived) {
22
+ let set = derivedTextures.get(base);
23
+ if (!set) {
24
+ set = new Set();
25
+ derivedTextures.set(base, set);
26
+ }
27
+ set.add(derived);
28
+ return derived;
29
+ }
16
30
 
17
31
  function albedoTexture(art, frame) {
18
32
  if (!art || !artReady(art)) return null;
@@ -35,6 +49,20 @@ function albedoTexture(art, frame) {
35
49
  return texture;
36
50
  }
37
51
 
52
+ // Dispose the textures baked for one art object, for art that is going away
53
+ // for good (a mounted content pack being dropped). A live mesh still using one
54
+ // would draw black, so callers release only art nothing draws any more.
55
+ export function releaseArtTextures(art) {
56
+ const byFrame = art ? textureCache.get(art) : null;
57
+ if (!byFrame) return;
58
+ for (const texture of byFrame.values()) {
59
+ for (const derived of derivedTextures.get(texture) ?? []) derived.dispose();
60
+ derivedTextures.delete(texture);
61
+ texture.dispose();
62
+ }
63
+ textureCache.delete(art);
64
+ }
65
+
38
66
  // 'drawings/door.sprite#1' -> { path, frame }
39
67
  function parseArtRef(ref) {
40
68
  const hash = ref.lastIndexOf('#');
@@ -56,7 +84,7 @@ export function resolveArtTexture(ref, sprites, repeat) {
56
84
  tiled.wrapT = THREE.RepeatWrapping;
57
85
  tiled.repeat.set(repeat[0] ?? 1, repeat[1] ?? 1);
58
86
  tiled.needsUpdate = true;
59
- return tiled;
87
+ return trackDerivedTexture(texture, tiled);
60
88
  }
61
89
 
62
90
  function artRefsOf(shape) {
@@ -78,6 +78,10 @@ export function makeWorld3D(canvas) {
78
78
  renderer,
79
79
  composer,
80
80
  nodes: new Map(),
81
+ // The scene path `nodes` were built for, and the nodes of scenes the
82
+ // runtime keeps resident while another one plays (`residentScenes`).
83
+ scenePath: undefined,
84
+ parked: new Map(),
81
85
  models: new Map(),
82
86
  instances: new Map(),
83
87
  instanceModels: false,
@@ -152,7 +156,11 @@ export function syncGround(world, setting, sprites) {
152
156
  });
153
157
  world.ground.material.dispose();
154
158
  world.ground.material = material;
155
- world.grid.visible = !texture;
159
+ // `"none": true`: no ground at all, drawn or stood on (the physics system
160
+ // leaves its collider out too).
161
+ const none = setting?.none === true;
162
+ world.ground.visible = !none;
163
+ world.grid.visible = !texture && !none;
156
164
  }
157
165
 
158
166
  // The signature suffix for an actor's Model component: the model file's text
@@ -250,6 +258,13 @@ const DEG = Math.PI / 180;
250
258
  // `actor.runtime.quat`; everything else rotates by the Transform's euler
251
259
  // degrees.
252
260
  export function syncActors(world, runtime, sprites, dt = 0) {
261
+ // A scene is keyed by its content as well as its path (`sceneKey`), so a
262
+ // town and a mounted game that both call theirs `scenes/main.scene` are
263
+ // different scenes here.
264
+ const key = runtime.sceneKey ?? runtime.scenePath;
265
+ if (key !== world.scenePath) {
266
+ swapSceneNodes(world, key, runtime.residentScenes);
267
+ }
253
268
  syncGround(world, runtime.data?.ground, sprites);
254
269
  const seen = new Set();
255
270
  for (const actor of runtime.getActors()) {
@@ -278,6 +293,51 @@ export function syncActors(world, runtime, sprites, dt = 0) {
278
293
  }
279
294
  }
280
295
 
296
+ // A scene load. The nodes built for the scene being left are parked when the
297
+ // runtime names that scene resident (`runtime.residentScenes`, a Set of scene
298
+ // keys -- `runtime.sceneKey`; the hub keeps the town it will walk back into), and released
299
+ // otherwise; the nodes parked for the scene arriving are put back, so a return
300
+ // redraws it without rebuilding a mesh. The sync that follows reuses a parked
301
+ // node only where its actor's signature still matches. A parked scene the
302
+ // runtime no longer names is released.
303
+ function swapSceneNodes(world, path, resident) {
304
+ const keep = resident instanceof Set ? resident : new Set();
305
+ if (world.scenePath !== undefined && keep.has(world.scenePath) && world.scenePath !== path) {
306
+ const parked = new Map();
307
+ for (const [id, entry] of world.nodes) {
308
+ if (entry.instancedRig) {
309
+ // An instanced rig is drawn by its model's shared instances wherever
310
+ // its node is; parking it would leave it drawn in the next scene.
311
+ releaseActorNode(world, entry);
312
+ continue;
313
+ }
314
+ world.scene.remove(entry.node);
315
+ parked.set(id, entry);
316
+ }
317
+ world.parked.set(world.scenePath, parked);
318
+ world.nodes = new Map();
319
+ }
320
+ // Nodes not parked stay where they are: the sync releases those whose actor
321
+ // is gone and reuses those an actor of the same id and look still has.
322
+ const back = world.parked.get(path);
323
+ if (back) {
324
+ world.parked.delete(path);
325
+ for (const [id, entry] of back) {
326
+ const current = world.nodes.get(id);
327
+ if (current) releaseActorNode(world, current);
328
+ world.scene.add(entry.node);
329
+ world.nodes.set(id, entry);
330
+ }
331
+ }
332
+ for (const [parkedPath, parked] of world.parked) {
333
+ if (!keep.has(parkedPath)) {
334
+ for (const entry of parked.values()) releaseActorNode(world, entry);
335
+ world.parked.delete(parkedPath);
336
+ }
337
+ }
338
+ world.scenePath = path;
339
+ }
340
+
281
341
  export function resizeWorld(world, width, height) {
282
342
  world.renderer.setSize(width, height, false);
283
343
  world.composer.setSize(width, height);
@@ -316,5 +376,9 @@ function fitShadowBias(world) {
316
376
  export function disposeWorld(world) {
317
377
  for (const entry of world.nodes.values()) releaseActorNode(world, entry);
318
378
  world.nodes.clear();
379
+ for (const parked of world.parked.values()) {
380
+ for (const entry of parked.values()) releaseActorNode(world, entry);
381
+ }
382
+ world.parked.clear();
319
383
  world.renderer.dispose();
320
384
  }
@@ -74,7 +74,7 @@ export class Physics3DSystem {
74
74
 
75
75
  afterBehaviors(scene, dt) {
76
76
  if (!rapierReady) return;
77
- this.ensureWorld();
77
+ this.ensureWorld(scene);
78
78
  this.reconcileBodies(scene);
79
79
  this.pushTransforms(scene);
80
80
  this.step(dt);
@@ -82,10 +82,13 @@ export class Physics3DSystem {
82
82
  this.dispatchCallbacks(scene);
83
83
  }
84
84
 
85
- ensureWorld() {
85
+ ensureWorld(scene) {
86
86
  if (this.world) return;
87
87
  this.world = new RAPIER.World({ x: 0, y: -9.81, z: 0 });
88
88
  this.eventQueue = new RAPIER.EventQueue(true);
89
+ // A scene whose top level says `"ground": { "none": true }` has no ground:
90
+ // what is not stood on something falls (a pit, lava, the sky).
91
+ if (scene?.data?.ground?.none === true) return;
89
92
  // The ground everything stands on, matching the visual ground plane.
90
93
  const groundBody = this.world.createRigidBody(
91
94
  RAPIER.RigidBodyDesc.fixed().setTranslation(0, -0.5, 0)
@@ -3,11 +3,11 @@
3
3
  "imports": {
4
4
  "castle.base": {
5
5
  "deckId": "yRcmH4_aYllE",
6
- "version": "2026-09-24T02:13:40.120Z"
6
+ "version": "2026-10-03T13:06:34.897Z"
7
7
  }
8
8
  },
9
9
  "autoUpdateWhenImported": true,
10
10
  "deckId": "xFVr-afOLuUQ",
11
11
  "cardId": "w6G45sy3_P_m",
12
- "publishedVersion": "2026-09-25T17:53:47.749Z"
12
+ "publishedVersion": "2026-10-03T15:40:59.728Z"
13
13
  }
@@ -1,5 +1,5 @@
1
- // Client transport over the Castle multiplayer SDK. This module joins the
2
- // public session, queues arriving messages, tracks the authenticated roster, and
1
+ // Client transport over the Castle multiplayer SDK. This module joins a
2
+ // session (the public one unless told otherwise), queues arriving messages, tracks the authenticated roster, and
3
3
  // rate-limits movement reports.
4
4
 
5
5
  import { Multiplayer } from 'castle-web-sdk';
@@ -31,16 +31,35 @@ function makeNet(connection) {
31
31
  };
32
32
  }
33
33
 
34
- // Join the deck's public session and return the interface its client system
35
- // uses. The SDK assigns the session and supplies authenticated roster names, so
34
+ // Join a session of the deck and return the interface its client system
35
+ // uses. `join` is what `Multiplayer.join` is asked for: the public session
36
+ // unless the caller names another (`{ mode: 'named', key }` for one instance
37
+ // of a game, say). The SDK assigns the session and supplies authenticated roster names, so
36
38
  // a deck message carries no sender-chosen username.
37
39
  //
40
+ // `{ destination: { routeId, slot }, fallback }` joins one of the deck's
41
+ // `server.destinations` routes instead (`Multiplayer.joinDestination`): a
42
+ // persistent world, the only kind that can carry shared characters. A host
43
+ // that cannot place it (`castle-web serve`, or an account the route is not
44
+ // open to) gets the `fallback` join, the public session unless it names
45
+ // another, and the returned `characters` is null unless that session's host
46
+ // brokers shared characters into it (see `characters` below).
47
+ //
38
48
  // `onArrival(msg)` sees each message the moment it arrives, before it is
39
49
  // queued, and returning true keeps it out of the queue. It runs whether or not
40
50
  // frames do: a hidden tab stops `requestAnimationFrame`, so a reply left in the
41
51
  // queue would wait until the tab is shown again.
42
- export async function connectSession({ onLog = () => {}, onArrival = () => false } = {}) {
43
- const connection = await Multiplayer.join({ mode: 'public' });
52
+ //
53
+ // `onConnected()` runs on each later transition back to connected: a
54
+ // reconnect, which can land on a replaced server process that has to be told
55
+ // again whatever the first connection told it.
56
+ export async function connectSession({
57
+ join = { mode: 'public' },
58
+ onLog = () => {},
59
+ onArrival = () => false,
60
+ onConnected = () => {},
61
+ } = {}) {
62
+ const { connection, world } = await joinTarget(join, onLog);
44
63
  const net = makeNet(connection);
45
64
 
46
65
  // Messages are queued with this page's clock at arrival. The client system
@@ -71,7 +90,17 @@ export async function connectSession({ onLog = () => {}, onArrival = () => false
71
90
 
72
91
  // Forward SDK connection transitions to the caller. The deck controls how
73
92
  // connection state appears in its status UI or logs.
74
- connection.onStateChange((state, meta) => onLog(`${state}${meta ? ` (${meta.type})` : ''}`));
93
+ connection.onStateChange((state, meta) => {
94
+ onLog(`${state}${meta ? ` (${meta.type})` : ''}`);
95
+ // Why a connection that closed on an error closed: the CastleError code of
96
+ // a failed recovery (a refused re-acquisition among them).
97
+ if (state === 'closed') {
98
+ net.closeCode = meta?.type === 'error' && typeof meta.error?.code === 'string' ? meta.error.code : null;
99
+ }
100
+ if (state === 'connected') {
101
+ onConnected();
102
+ }
103
+ });
75
104
  return {
76
105
  // The player id this connection was assigned.
77
106
  selfId: () => connection.playerId,
@@ -117,6 +146,10 @@ export async function connectSession({ onLog = () => {}, onArrival = () => false
117
146
  // on it again; the client system joins afresh.
118
147
  closed: () => connection.state === 'closed',
119
148
 
149
+ // The CastleError code it closed on, or null (closed for any other reason,
150
+ // or still open).
151
+ closeError: () => net.closeCode ?? null,
152
+
120
153
  // Connection and presence data for a deck status line.
121
154
  status: () => ({
122
155
  state: connection.state,
@@ -132,11 +165,48 @@ export async function connectSession({ onLog = () => {}, onArrival = () => false
132
165
  you: net.you?.username ?? net.roster.get(connection.playerId) ?? '',
133
166
  }),
134
167
 
168
+ // The shared-character calls (`requestCharacterTurn`,
169
+ // `getCharacterTurnStatus`, `readCharacters`) of a destination world, or
170
+ // of a session whose host said it brokers shared characters into it (a hub
171
+ // place's layer with place characters: the SDK's `sharedCharacters`, from
172
+ // the hello). Null on any other session. A getter, so it follows the
173
+ // hello of a reconnect.
174
+ get characters() {
175
+ return charactersOf(connection, world);
176
+ },
177
+
135
178
  // Leave the session when the engine runtime is disposed.
136
179
  close: () => connection.leave(),
137
180
  };
138
181
  }
139
182
 
183
+ // A world joined through its route has characters; any other session has them
184
+ // only when its host's hello said so (`connection.sharedCharacters`, absent on
185
+ // older SDKs).
186
+ export function charactersOf(connection, world) {
187
+ return world || connection?.sharedCharacters === true ? connection : null;
188
+ }
189
+
190
+ async function joinTarget(join, onLog) {
191
+ if (!join?.destination) {
192
+ return { connection: await Multiplayer.join(join), world: false };
193
+ }
194
+ const { routeId, slot } = join.destination;
195
+ let result = null;
196
+ try {
197
+ result = await Multiplayer.joinDestination({ routeId, slot });
198
+ } catch (err) {
199
+ onLog(`destination ${routeId} failed: ${err?.message ?? err}`);
200
+ }
201
+ if (result?.status === 'joined') {
202
+ return { connection: result.connection, world: true };
203
+ }
204
+ if (result) {
205
+ onLog(`destination ${routeId} is ${result.status}; joining the fallback session`);
206
+ }
207
+ return { connection: await Multiplayer.join(join.fallback ?? { mode: 'public' }), world: false };
208
+ }
209
+
140
210
  // Collect ownership requests from every frame and send at `MOVE_HZ`. `state` is
141
211
  // the player's own block, sent along when the caller has one to send. Returns
142
212
  // whether a packet went out.
@@ -12,8 +12,8 @@ const modules = {
12
12
  };
13
13
 
14
14
  // The selected hook object, or an empty object when the deck defines no client
15
- // hooks. Call sites invoke each hook optionally, so a deck writes only the ones
16
- // it needs:
15
+ // hooks, with any imported kit's layer under it (`compose`). Call sites invoke
16
+ // each hook optionally, so a deck writes only the ones it needs:
17
17
  //
18
18
  // The 2D and 3D multiplayer systems import this value and call the hooks at the
19
19
  // stages listed below.
@@ -45,10 +45,65 @@ const modules = {
45
45
  // soloBadge(status) the solo fallback badge (soloBadge.js):
46
46
  // false hides it, a string replaces its text.
47
47
  // Called every frame, so keep it a lookup
48
+ // firstJoin() what the first join asks for, read once when
49
+ // the multiplayer system is made: a
50
+ // `connectSession` join (a destination route,
51
+ // say). Default: the public session
48
52
  // reset(scene, system) a scene load, after spawned actors are gone
49
53
  // and while the connection is still open
50
54
  // dispose(scene, system) runtime disposal, before reset and close
51
- export const game = pick(modules)?.default ?? {};
55
+ // sceneFromClient a flag, not a hook: true names the scene this
56
+ // runtime plays to each session it joins, for
57
+ // a server that sets the same flag
58
+ // (exported at the end of this file, once the layers below are defined)
59
+
60
+ // Hooks an IMPORTED kit layers under the deck's own: a kit built on this one
61
+ // (castle.hub-game) whose decks ship no client code still needs its hooks
62
+ // called, and a deck's `code/client/game.js` is the deck's alone. A layer is
63
+ // `code/client/hookLayer.js` in any import, default-exporting the same hooks;
64
+ // the root one is that kit's own while it is served as itself.
65
+ const layerModules = {
66
+ ...import.meta.glob('/imports/*/code/client/hookLayer.js', { eager: true }),
67
+ ...import.meta.glob('/code/client/hookLayer.js', { eager: true }),
68
+ };
69
+
70
+ // One hook object from the layers and the deck's. A hook that only acts
71
+ // (`message`, `state`, `afterFrame`, `beforeReport`, `reset`, `dispose`) runs in
72
+ // every layer and then the deck's; `arrive` stops at the first that handles the
73
+ // message. A hook that answers (`avatar`, `claimable`, `report`, `presence`,
74
+ // `soloBadge`) is the deck's when it has one, else the last layer's. A hook no
75
+ // one defines stays undefined, which is what the call sites test for.
76
+ const ACTS = ['message', 'state', 'afterFrame', 'beforeReport', 'reset', 'dispose'];
77
+
78
+ function compose(layers, deck) {
79
+ if (!layers.length) {
80
+ return deck;
81
+ }
82
+ const all = [...layers, deck];
83
+ const out = {};
84
+ for (const name of ACTS) {
85
+ const fns = all.map((hooks) => hooks[name]).filter((fn) => typeof fn === 'function');
86
+ if (fns.length) {
87
+ out[name] = (...args) => {
88
+ for (const fn of fns) {
89
+ fn(...args);
90
+ }
91
+ };
92
+ }
93
+ }
94
+ const arrives = all.map((hooks) => hooks.arrive).filter((fn) => typeof fn === 'function');
95
+ if (arrives.length) {
96
+ out.arrive = (...args) => arrives.some((fn) => fn(...args) === true);
97
+ }
98
+ for (const hooks of all) {
99
+ for (const [name, value] of Object.entries(hooks)) {
100
+ if (!ACTS.includes(name) && name !== 'arrive' && value !== undefined) {
101
+ out[name] = value;
102
+ }
103
+ }
104
+ }
105
+ return out;
106
+ }
52
107
 
53
108
  // Selection uses the final glob entry, which gives the deck file precedence over
54
109
  // a module contributed by an import.
@@ -56,3 +111,8 @@ function pick(modules) {
56
111
  const keys = Object.keys(modules);
57
112
  return keys.length ? modules[keys[keys.length - 1]] : null;
58
113
  }
114
+
115
+ export const game = compose(
116
+ Object.values(layerModules).map((mod) => mod.default ?? {}),
117
+ pick(modules)?.default ?? {},
118
+ );
@@ -23,6 +23,13 @@ export const GONE = 'g';
23
23
  // `{ k: UNLOADED }`. The page has to be reloaded.
24
24
  export const UNLOADED = 'x';
25
25
 
26
+ // A client names the scene its session simulates: `{ k: SCENE, path }`, sent
27
+ // once after joining. Only a deck whose server hooks set `sceneFromClient`
28
+ // waits for it; one deck can then run a different scene in each session (a
29
+ // hub's town in the public session, a game in each named one). The first
30
+ // session's player to name a scene decides it; later ones change nothing.
31
+ export const SCENE = 'c';
32
+
26
33
  // Movement reports run below the render rate and below the platform's roughly
27
34
  // 30-message-per-second client cap. A second report inside one server tick would
28
35
  // be overwritten before the simulation read it.
@@ -37,6 +37,30 @@ const bodyModules = {
37
37
  // join(sim) fields merged into a joiner's WORLD snapshot
38
38
  // delta(sim) changed fields, or null when nothing changed;
39
39
  // a returned block is itself a reason to send
40
+ // interest(sim, known) which other players each client is sent:
41
+ // a Map of playerId -> Set of the other
42
+ // playerIds it sees, or null for everyone.
43
+ // `known` is what each client was last sent
44
+ // (playerId -> Set), for hysteresis. A deck
45
+ // without the hook broadcasts one delta to all
46
+ // poseEvery, poseIntervalMs with `interest`: a client's filtered sends
47
+ // carry other players' rows only every
48
+ // `poseEvery` ticks (`poseIntervalMs` apart,
49
+ // told to the client as `pi`), each row with a
50
+ // short number for its id (`idm` maps them)
51
+ // sceneFromClient not a hook but a flag: true builds the world
52
+ // from the scene the session's first client
53
+ // names (`scenes/*.scene`) instead of the main
54
+ // scene, so one deck runs a different scene in
55
+ // each session. `sim.scenePath` says which
56
+ // sceneFor(session) the scene this session builds, from the
57
+ // session itself (its id, or a place the host
58
+ // stamped), before the world exists; null or
59
+ // undefined builds the main scene. Unlike
60
+ // `sceneFromClient`, no client message is read
61
+ // persist a flag: false reads and writes no room or
62
+ // player rows, for sessions that are one visit
63
+ // long (a game instance behind a door)
40
64
  export const game = pick(modules)?.default ?? {};
41
65
 
42
66
  // Defaults for deck-defined scene components the server reads. The scene reader