castle-web-cli 0.4.229 → 0.4.231

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 (259) 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 +860 -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/devSaveStorage.d.ts +36 -0
  19. package/dist/devSaveStorage.js +469 -0
  20. package/dist/devSessionChild.js +25 -13
  21. package/dist/devSessionServer.d.ts +14 -1
  22. package/dist/devSessionServer.js +237 -46
  23. package/dist/devSessionStorage.d.ts +9 -0
  24. package/dist/devSessionStorage.js +66 -1
  25. package/dist/experimentAssignment.d.ts +15 -0
  26. package/dist/experimentAssignment.js +41 -0
  27. package/dist/importCheckHook.d.ts +40 -0
  28. package/dist/importCheckHook.js +171 -0
  29. package/dist/importRegression.d.ts +15 -0
  30. package/dist/importRegression.js +100 -0
  31. package/dist/importTrust.d.ts +2 -0
  32. package/dist/importTrust.js +27 -0
  33. package/dist/importUpdateHook.d.ts +18 -0
  34. package/dist/importUpdateHook.js +31 -8
  35. package/dist/importUpdateHookRunner.js +19 -7
  36. package/dist/imports.d.ts +16 -0
  37. package/dist/imports.js +141 -31
  38. package/dist/index.js +3 -1
  39. package/dist/init.d.ts +3 -0
  40. package/dist/init.js +126 -9
  41. package/dist/install.js +4 -1
  42. package/dist/localPaths.js +4 -0
  43. package/dist/login.js +2 -2
  44. package/dist/platformDoc.js +3 -8
  45. package/dist/playPagePolicy.js +3 -1
  46. package/dist/remix.js +5 -0
  47. package/dist/routerTaskReport.d.ts +28 -0
  48. package/dist/routerTaskReport.js +56 -0
  49. package/dist/save-deck.d.ts +18 -0
  50. package/dist/save-deck.js +142 -6
  51. package/dist/serve.d.ts +8 -0
  52. package/dist/serve.js +99 -14
  53. package/dist/serverBundle.d.ts +1 -1
  54. package/dist/serverBundle.js +5 -1
  55. package/dist/webSourceSync.d.ts +2 -0
  56. package/dist/webSourceSync.js +2 -0
  57. package/kits/base/CLAUDE.md +2 -3
  58. package/kits/base/castle.json +1 -1
  59. package/kits/base/sdk/README.md +406 -53
  60. package/kits/base/sdk/agent.js +4 -4
  61. package/kits/base/sdk/avatar.d.ts +12 -0
  62. package/kits/base/sdk/avatar.js +23 -0
  63. package/kits/base/sdk/castle.d.ts +9 -0
  64. package/kits/base/sdk/castle.js +5 -0
  65. package/kits/base/sdk/commands.d.ts +223 -0
  66. package/kits/base/sdk/commands.js +16 -0
  67. package/kits/base/sdk/context.d.ts +6 -0
  68. package/kits/base/sdk/experiments.d.ts +15 -0
  69. package/kits/base/sdk/experiments.js +83 -0
  70. package/kits/base/sdk/hub.d.ts +85 -0
  71. package/kits/base/sdk/hub.js +107 -0
  72. package/kits/base/sdk/multiplayer.d.ts +45 -1
  73. package/kits/base/sdk/multiplayer.js +158 -8
  74. package/kits/base/sdk/save.d.ts +197 -0
  75. package/kits/base/sdk/save.js +525 -0
  76. package/kits/base/sdk/saveCoordinator.d.ts +39 -0
  77. package/kits/base/sdk/saveCoordinator.js +252 -0
  78. package/kits/base/sdk/server/hub.d.ts +169 -0
  79. package/kits/base/sdk/server/hub.js +125 -0
  80. package/kits/base/sdk/server/platformHandle.d.ts +42 -1
  81. package/kits/base/sdk/server/storage.d.ts +58 -4
  82. package/kits/base/sdk/server/storage.js +25 -5
  83. package/kits/base/sdk/server/wrapper.d.ts +36 -2
  84. package/kits/base/sdk/server/wrapper.js +92 -11
  85. package/kits/base/sdk/store.d.ts +3 -2
  86. package/kits/base/sdk/store.js +5 -0
  87. package/kits/base/sdk/transport.d.ts +2 -1
  88. package/kits/base/sdk/transport.js +13 -1
  89. package/kits/hub-game/.prettierrc +5 -0
  90. package/kits/hub-game/CLAUDE.md +149 -0
  91. package/kits/hub-game/blueprints/avatar-0.scene +28 -0
  92. package/kits/hub-game/blueprints/avatar-1.scene +28 -0
  93. package/kits/hub-game/blueprints/avatar-2.scene +28 -0
  94. package/kits/hub-game/blueprints/avatar-3.scene +28 -0
  95. package/kits/hub-game/blueprints/bean/avatar-0.scene +28 -0
  96. package/kits/hub-game/blueprints/bean/avatar-1.scene +28 -0
  97. package/kits/hub-game/blueprints/bean/avatar-2.scene +28 -0
  98. package/kits/hub-game/blueprints/bean/avatar-3.scene +28 -0
  99. package/kits/hub-game/blueprints/blocky/avatar-0.scene +28 -0
  100. package/kits/hub-game/blueprints/blocky/avatar-1.scene +28 -0
  101. package/kits/hub-game/blueprints/blocky/avatar-2.scene +28 -0
  102. package/kits/hub-game/blueprints/blocky/avatar-3.scene +28 -0
  103. package/kits/hub-game/blueprints/pixel/avatar-0.scene +28 -0
  104. package/kits/hub-game/blueprints/pixel/avatar-1.scene +28 -0
  105. package/kits/hub-game/blueprints/pixel/avatar-2.scene +28 -0
  106. package/kits/hub-game/blueprints/pixel/avatar-3.scene +28 -0
  107. package/kits/hub-game/castle.json +96 -0
  108. package/kits/hub-game/code/client/attention.js +133 -0
  109. package/kits/hub-game/code/client/avatar.js +288 -0
  110. package/kits/hub-game/code/client/cabinets.js +90 -0
  111. package/kits/hub-game/code/client/chat.js +135 -0
  112. package/kits/hub-game/code/client/chrome.js +1035 -0
  113. package/kits/hub-game/code/client/doorFrame.js +15 -0
  114. package/kits/hub-game/code/client/firstJoin.js +14 -0
  115. package/kits/hub-game/code/client/grab.js +376 -0
  116. package/kits/hub-game/code/client/hookLayer.js +236 -0
  117. package/kits/hub-game/code/client/idle.js +326 -0
  118. package/kits/hub-game/code/client/keys.js +48 -0
  119. package/kits/hub-game/code/client/pack.js +232 -0
  120. package/kits/hub-game/code/client/packFormat.js +397 -0
  121. package/kits/hub-game/code/client/say.js +127 -0
  122. package/kits/hub-game/code/client/sha256.js +80 -0
  123. package/kits/hub-game/code/client/sound.js +147 -0
  124. package/kits/hub-game/code/client/state.js +143 -0
  125. package/kits/hub-game/code/client/talk.js +233 -0
  126. package/kits/hub-game/code/client/tiers.js +480 -0
  127. package/kits/hub-game/code/client/together.js +440 -0
  128. package/kits/hub-game/code/client/wear.js +149 -0
  129. package/kits/hub-game/code/server/actors.js +627 -0
  130. package/kits/hub-game/code/server/blocks.js +103 -0
  131. package/kits/hub-game/code/server/cabinets.js +309 -0
  132. package/kits/hub-game/code/server/game.js +137 -0
  133. package/kits/hub-game/code/server/grab.js +248 -0
  134. package/kits/hub-game/code/server/history.js +96 -0
  135. package/kits/hub-game/code/server/hub.js +1998 -0
  136. package/kits/hub-game/code/server/idle.js +412 -0
  137. package/kits/hub-game/code/server/index.js +64 -0
  138. package/kits/hub-game/code/server/labels.js +59 -0
  139. package/kits/hub-game/code/server/manifest.js +554 -0
  140. package/kits/hub-game/code/server/npcs.js +733 -0
  141. package/kits/hub-game/code/server/party.js +439 -0
  142. package/kits/hub-game/code/server/place.js +43 -0
  143. package/kits/hub-game/code/server/say.js +83 -0
  144. package/kits/hub-game/code/server/wear.js +142 -0
  145. package/kits/hub-game/code/systems/hub.js +2347 -0
  146. package/kits/hub-game/docs/content-pack.md +151 -0
  147. package/kits/hub-game/docs/contract.md +1209 -0
  148. package/kits/hub-game/docs/style.md +137 -0
  149. package/kits/hub-game/drawings/blocky/castle-eye.sprite +58 -0
  150. package/kits/hub-game/drawings/blocky/dash.sprite +59 -0
  151. package/kits/hub-game/drawings/blocky/pom.sprite +59 -0
  152. package/kits/hub-game/drawings/blocky/tabby.sprite +59 -0
  153. package/kits/hub-game/drawings/pixel/castle-arm.sprite +13 -0
  154. package/kits/hub-game/drawings/pixel/castle-body.sprite +23 -0
  155. package/kits/hub-game/drawings/pixel/castle-leg.sprite +12 -0
  156. package/kits/hub-game/drawings/pixel/kai-arm.sprite +14 -0
  157. package/kits/hub-game/drawings/pixel/kai-head.sprite +24 -0
  158. package/kits/hub-game/drawings/pixel/kai-leg.sprite +15 -0
  159. package/kits/hub-game/drawings/pixel/kai-torso.sprite +18 -0
  160. package/kits/hub-game/drawings/pixel/mimi-arm.sprite +13 -0
  161. package/kits/hub-game/drawings/pixel/mimi-head.sprite +23 -0
  162. package/kits/hub-game/drawings/pixel/mimi-leg.sprite +15 -0
  163. package/kits/hub-game/drawings/pixel/mimi-torso.sprite +18 -0
  164. package/kits/hub-game/drawings/pixel/nox-arm.sprite +13 -0
  165. package/kits/hub-game/drawings/pixel/nox-head.sprite +21 -0
  166. package/kits/hub-game/drawings/pixel/nox-leg.sprite +14 -0
  167. package/kits/hub-game/drawings/pixel/nox-torso.sprite +18 -0
  168. package/kits/hub-game/eslint.config.js +20 -0
  169. package/kits/hub-game/fonts.generated.js +9 -0
  170. package/kits/hub-game/index.html +22 -0
  171. package/kits/hub-game/main.jsx +6 -0
  172. package/kits/hub-game/models/avatar-0.pxmodel +21 -0
  173. package/kits/hub-game/models/avatar-1.pxmodel +24 -0
  174. package/kits/hub-game/models/avatar-2.pxmodel +27 -0
  175. package/kits/hub-game/models/avatar-3.pxmodel +22 -0
  176. package/kits/hub-game/models/bean/avatar-0.pxmodel +19 -0
  177. package/kits/hub-game/models/bean/avatar-1.pxmodel +24 -0
  178. package/kits/hub-game/models/bean/avatar-2.pxmodel +22 -0
  179. package/kits/hub-game/models/bean/avatar-3.pxmodel +24 -0
  180. package/kits/hub-game/models/blocky/avatar-0.pxmodel +21 -0
  181. package/kits/hub-game/models/blocky/avatar-1.pxmodel +30 -0
  182. package/kits/hub-game/models/blocky/avatar-2.pxmodel +28 -0
  183. package/kits/hub-game/models/blocky/avatar-3.pxmodel +27 -0
  184. package/kits/hub-game/models/pixel/avatar-0.pxmodel +24 -0
  185. package/kits/hub-game/models/pixel/avatar-1.pxmodel +16 -0
  186. package/kits/hub-game/models/pixel/avatar-2.pxmodel +19 -0
  187. package/kits/hub-game/models/pixel/avatar-3.pxmodel +23 -0
  188. package/kits/hub-game/package-lock.json +365 -0
  189. package/kits/hub-game/package.json +32 -0
  190. package/kits/hub-game/scenes/main.scene +318 -0
  191. package/kits/hub-game/scripts/check.mjs +339 -0
  192. package/kits/hub-game/scripts/fixtures/sdk-stub.mjs +3 -0
  193. package/kits/hub-game/scripts/gen-avatars-bean.mjs +748 -0
  194. package/kits/hub-game/scripts/gen-avatars-blocky.mjs +607 -0
  195. package/kits/hub-game/scripts/gen-avatars-pixel.mjs +771 -0
  196. package/kits/hub-game/scripts/gen-avatars.mjs +621 -0
  197. package/kits/hub-game/scripts/pack.mjs +192 -0
  198. package/kits/hub-game/scripts/test-actors.mjs +666 -0
  199. package/kits/hub-game/scripts/test-attention.mjs +103 -0
  200. package/kits/hub-game/scripts/test-avatar.mjs +472 -0
  201. package/kits/hub-game/scripts/test-ban-join.mjs +194 -0
  202. package/kits/hub-game/scripts/test-blocks.mjs +351 -0
  203. package/kits/hub-game/scripts/test-chat.mjs +98 -0
  204. package/kits/hub-game/scripts/test-classic.mjs +590 -0
  205. package/kits/hub-game/scripts/test-door-jump.mjs +131 -0
  206. package/kits/hub-game/scripts/test-door.mjs +56 -0
  207. package/kits/hub-game/scripts/test-grab-client.mjs +328 -0
  208. package/kits/hub-game/scripts/test-grab.mjs +331 -0
  209. package/kits/hub-game/scripts/test-hub-ops.mjs +835 -0
  210. package/kits/hub-game/scripts/test-hub-trip.mjs +1518 -0
  211. package/kits/hub-game/scripts/test-idle.mjs +518 -0
  212. package/kits/hub-game/scripts/test-interest.mjs +413 -0
  213. package/kits/hub-game/scripts/test-keys.mjs +50 -0
  214. package/kits/hub-game/scripts/test-manifest.mjs +270 -0
  215. package/kits/hub-game/scripts/test-no-forms.mjs +16 -0
  216. package/kits/hub-game/scripts/test-npcs.mjs +724 -0
  217. package/kits/hub-game/scripts/test-pack.mjs +424 -0
  218. package/kits/hub-game/scripts/test-party.mjs +369 -0
  219. package/kits/hub-game/scripts/test-say.mjs +149 -0
  220. package/kits/hub-game/scripts/test-tiers.mjs +666 -0
  221. package/kits/hub-game/scripts/test-together.mjs +215 -0
  222. package/kits/hub-game/theme.style +3 -0
  223. package/kits/multiplayer-3d/castle.json +5 -5
  224. package/kits/multiplayer-3d/code/client/avatars.js +101 -1
  225. package/kits/multiplayer-3d/code/server/players.js +4 -1
  226. package/kits/multiplayer-3d/code/server/sceneBodies.js +27 -6
  227. package/kits/multiplayer-3d/code/server/world.js +20 -7
  228. package/kits/multiplayer-3d/code/systems/multiplayer.js +222 -11
  229. package/kits/physics-2d/CLAUDE.md +2 -0
  230. package/kits/physics-2d/castle.json +2 -2
  231. package/kits/physics-2d/engine/art.js +13 -0
  232. package/kits/physics-2d/engine/assets.js +4 -2
  233. package/kits/physics-2d/engine/scene.js +117 -5
  234. package/kits/physics-2d/package.json +1 -1
  235. package/kits/physics-2d/scripts/test-skip-unchanged.mjs +254 -0
  236. package/kits/physics-3d/CLAUDE.md +285 -1
  237. package/kits/physics-3d/behaviors/Player.jsx +74 -1
  238. package/kits/physics-3d/castle.json +3 -3
  239. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +33 -5
  240. package/kits/physics-3d/engine3d/actornode.js +253 -0
  241. package/kits/physics-3d/engine3d/artobjects.js +2 -2
  242. package/kits/physics-3d/engine3d/materials.js +29 -1
  243. package/kits/physics-3d/engine3d/nearshadows.js +600 -0
  244. package/kits/physics-3d/engine3d/unchanged.js +153 -0
  245. package/kits/physics-3d/engine3d/world3d.js +527 -5
  246. package/kits/physics-3d/package.json +1 -1
  247. package/kits/physics-3d/scripts/test-camera-follow.mjs +533 -0
  248. package/kits/physics-3d/scripts/test-near-shadows.mjs +1073 -0
  249. package/kits/physics-3d/scripts/test-static-actors.mjs +662 -0
  250. package/kits/physics-3d/scripts/test-static-passes.mjs +459 -0
  251. package/kits/physics-3d/scripts/test-static-physics.mjs +128 -0
  252. package/kits/physics-3d/systems/physics3d.js +187 -5
  253. package/kits/real-time/castle.json +2 -2
  254. package/kits/real-time/code/client/connection.js +77 -7
  255. package/kits/real-time/code/client/gameHooks.js +63 -3
  256. package/kits/real-time/code/client/messages.js +7 -0
  257. package/kits/real-time/code/server/gameHooks.js +24 -0
  258. package/kits/real-time/code/server/session.js +390 -22
  259. package/package.json +2 -2
@@ -11,6 +11,7 @@
11
11
  // simulating on the first frame after init resolves.
12
12
  import * as THREE from 'three';
13
13
  import * as RAPIER from '@dimforge/rapier3d-compat';
14
+ import { remember, sameAs } from '../engine3d/unchanged.js';
14
15
 
15
16
  const FIXED_STEP = 1 / 60;
16
17
  const MAX_STEPS_PER_FRAME = 4;
@@ -28,6 +29,24 @@ function ensureRapierInit() {
28
29
  return rapierInitPromise;
29
30
  }
30
31
 
32
+ // A scene that set `"engine": { "camera": { "follow": "rigid" } }`: the
33
+ // Player behavior asks for its camera (`scene.followCamera`: the player's id,
34
+ // the scene data it was asked for, and the function that places it) and it is
35
+ // placed here, last in the frame, once this frame's positions are written back
36
+ // and after the collision callbacks, so on the position the frame is drawn
37
+ // with (behaviors run before physics, and see last frame's). It is placed on a
38
+ // frame physics could not step too (rapier still loading). A request is used
39
+ // once, and only while the scene it was made for is loaded; a load and a
40
+ // dispose drop it (`reset`). Without the key nothing is asked for, and this
41
+ // reads one property and returns.
42
+ export function placeFollowCamera(scene) {
43
+ const request = scene.followCamera;
44
+ if (!request) return;
45
+ scene.followCamera = null;
46
+ if (scene.cameraFollowsRigidly !== true || request.data !== scene.data) return;
47
+ request.place(scene, request.id, request.dt);
48
+ }
49
+
31
50
  export function installSystem(runtime) {
32
51
  const system = new Physics3DSystem();
33
52
  runtime.registerSystem(system);
@@ -52,7 +71,7 @@ export class Physics3DSystem {
52
71
  void ensureRapierInit();
53
72
  }
54
73
 
55
- reset() {
74
+ reset(runtime) {
56
75
  // Rapier objects live in wasm -- dropping the JS reference leaks them, so
57
76
  // both the world and its event queue are freed explicitly. Runs on every
58
77
  // scene load (the runtime resets registered systems) and on dispose.
@@ -66,15 +85,34 @@ export class Physics3DSystem {
66
85
  this.enter.length = 0;
67
86
  this.exit.length = 0;
68
87
  this.acc = 0;
88
+ // What a skipping pass wrote down goes with the world it was written for.
89
+ this.remembered = null;
90
+ this.rememberedIn = null;
91
+ // A follow camera asked for before the load goes with the scene it was
92
+ // asked for.
93
+ if (runtime?.followCamera) runtime.followCamera = null;
69
94
  }
70
95
 
71
- dispose() {
72
- this.reset();
96
+ dispose(runtime) {
97
+ this.reset(runtime);
73
98
  }
74
99
 
75
100
  afterBehaviors(scene, dt) {
101
+ this.simulate(scene, dt);
102
+ placeFollowCamera(scene);
103
+ }
104
+
105
+ simulate(scene, dt) {
76
106
  if (!rapierReady) return;
77
- this.ensureWorld();
107
+ this.ensureWorld(scene);
108
+ if (scene.skipsUnchangedActors === true) {
109
+ this.afterBehaviorsSkipping(scene, dt);
110
+ return;
111
+ }
112
+ if (this.remembered) {
113
+ this.remembered = null;
114
+ this.rememberedIn = null;
115
+ }
78
116
  this.reconcileBodies(scene);
79
117
  this.pushTransforms(scene);
80
118
  this.step(dt);
@@ -82,10 +120,13 @@ export class Physics3DSystem {
82
120
  this.dispatchCallbacks(scene);
83
121
  }
84
122
 
85
- ensureWorld() {
123
+ ensureWorld(scene) {
86
124
  if (this.world) return;
87
125
  this.world = new RAPIER.World({ x: 0, y: -9.81, z: 0 });
88
126
  this.eventQueue = new RAPIER.EventQueue(true);
127
+ // A scene whose top level says `"ground": { "none": true }` has no ground:
128
+ // what is not stood on something falls (a pit, lava, the sky).
129
+ if (scene?.data?.ground?.none === true) return;
89
130
  // The ground everything stands on, matching the visual ground plane.
90
131
  const groundBody = this.world.createRigidBody(
91
132
  RAPIER.RigidBodyDesc.fixed().setTranslation(0, -0.5, 0)
@@ -128,6 +169,7 @@ export class Physics3DSystem {
128
169
  if (entry.collider) this.byCollider.delete(entry.collider.handle);
129
170
  this.world.removeRigidBody(entry.body);
130
171
  this.bodies.delete(actorId);
172
+ if (this.remembered) this.remembered.delete(entry);
131
173
  for (const key of [...this.touching]) {
132
174
  if (key.startsWith(`${actorId}|`) || key.endsWith(`|${actorId}`)) this.touching.delete(key);
133
175
  }
@@ -230,6 +272,102 @@ export class Physics3DSystem {
230
272
  }
231
273
  }
232
274
 
275
+ // `afterBehaviors` for a scene that set `"engine": { "skipUnchangedActors":
276
+ // true }`: the same bodies, pushes, steps and write-back, without building a
277
+ // body's signature or a fixed body's Transform key while what they are built
278
+ // from reads the same, and with the scene's actors listed once (nothing
279
+ // between here and the write-back runs deck code, so the list is the same
280
+ // for each pass). A body's type is still read from the body every frame.
281
+ //
282
+ // By the rule world3d.js states for its passes: nothing this method relies
283
+ // on from one statement to the next is trusted across code outside the
284
+ // engine. Between listing the actors and the write-back it calls only
285
+ // rapier (wasm; no hooks are handed to `step`), `scene.getActors`, and
286
+ // `JSON.stringify` on plain components. The one place it leaves the engine
287
+ // is `dispatchCallbacks`, last, after which nothing here is used again; a
288
+ // behavior that updates the scene from a collision callback starts a pass of
289
+ // its own from the top. What is kept between frames is read against the
290
+ // live components on every use. It is kept in `this.remembered`, a WeakMap
291
+ // from a body's entry to what the body was made from and where it was last
292
+ // pushed, started afresh with each rapier world and dropped on `reset`, on
293
+ // a frame without the key and, for one body, when the body is removed;
294
+ // nothing is kept on the entries, so an entry that is removed, or held by
295
+ // someone else, holds none of it.
296
+ afterBehaviorsSkipping(scene, dt) {
297
+ if (!this.remembered || this.rememberedIn !== this.world) {
298
+ this.remembered = new WeakMap();
299
+ this.rememberedIn = this.world;
300
+ }
301
+ const actors = scene.getActors();
302
+ this.reconcileUnchanged(actors);
303
+ const dynamic = this.pushUnchanged(actors);
304
+ this.step(dt);
305
+ // `writeBack` asks its scene for the actors; it is handed the dynamic
306
+ // ones, in the scene's order, which are the only ones it writes.
307
+ this.writeBack({ getActors: () => dynamic });
308
+ this.dispatchCallbacks(scene);
309
+ }
310
+
311
+ reconcileUnchanged(actors) {
312
+ // Each body whose actor is still here is marked with this pass's count; a
313
+ // body without the mark afterwards has lost its actor.
314
+ this.pass = (this.pass ?? 0) + 1;
315
+ const pass = this.pass;
316
+ let marked = 0;
317
+ for (const actor of actors) {
318
+ if (!actor.components.Transform) continue;
319
+ const entry = this.bodyFor(actor);
320
+ if (entry.pass !== pass) {
321
+ entry.pass = pass;
322
+ marked += 1;
323
+ }
324
+ }
325
+ if (marked === this.bodies.size) return;
326
+ for (const [id, entry] of [...this.bodies]) {
327
+ if (entry.pass !== pass) this.removeBody(id);
328
+ }
329
+ }
330
+
331
+ // The actor's body, made again when its signature differs. The signature is
332
+ // built and compared, as it is every frame elsewhere, only when something
333
+ // the body is made from reads differently; what it was made from is written
334
+ // down after the body is made.
335
+ bodyFor(actor) {
336
+ let entry = this.bodies.get(actor.id);
337
+ const made = entry && this.remembered.get(entry);
338
+ if (made && madeTheSame(made.madeFrom, actor)) return entry;
339
+ const sig = bodySignature(actor);
340
+ if (!entry || entry.sig !== sig) {
341
+ if (entry) this.removeBody(actor.id);
342
+ this.createBody(actor, sig);
343
+ entry = this.bodies.get(actor.id);
344
+ }
345
+ this.remembered.set(entry, { madeFrom: rememberMaking(actor), pushedAt: null });
346
+ return entry;
347
+ }
348
+
349
+ // `pushTransforms`, returning the actors whose body is dynamic.
350
+ pushUnchanged(actors) {
351
+ const dynamic = [];
352
+ for (const actor of actors) {
353
+ const entry = this.bodies.get(actor.id);
354
+ const t = actor.components.Transform;
355
+ if (!entry || !t) continue;
356
+ const { body } = entry;
357
+ const type = body.bodyType();
358
+ if (type === RAPIER.RigidBodyType.Dynamic) {
359
+ dynamic.push(actor);
360
+ } else if (type === RAPIER.RigidBodyType.KinematicPositionBased) {
361
+ body.setNextKinematicTranslation(placeOf(t));
362
+ body.setNextKinematicRotation(quatFromEuler(t));
363
+ } else if (type === RAPIER.RigidBodyType.Fixed && !alreadyPushed(entry, this.remembered.get(entry), t)) {
364
+ body.setTranslation(placeOf(t), false);
365
+ body.setRotation(quatFromEuler(t), false);
366
+ }
367
+ }
368
+ return dynamic;
369
+ }
370
+
233
371
  dispatchCallbacks(scene) {
234
372
  for (const [a, b] of this.enter) emitPair(scene, a, b, 'onCollisionEnter');
235
373
  for (const [a, b] of this.exit) emitPair(scene, a, b, 'onCollisionExit');
@@ -260,6 +398,50 @@ function transformKey(t) {
260
398
  return `${t.x},${t.y},${t.z},${t.rotationX},${t.rotationY},${t.rotationZ}`;
261
399
  }
262
400
 
401
+ function placeOf(t) {
402
+ return { x: t.x, y: t.y, z: t.z };
403
+ }
404
+
405
+ // What a body is made from, kept so the next frame can tell without building
406
+ // the signature whether it would come out the same (`unchanged.js`).
407
+ function rememberMaking(actor) {
408
+ const components = actor.components;
409
+ return { body: remember(components.Body), shape: remember(components.Shape), solid: isSolid(actor) };
410
+ }
411
+
412
+ function madeTheSame(madeFrom, actor) {
413
+ const components = actor.components;
414
+ return (
415
+ sameAs(components.Body, madeFrom.body) &&
416
+ sameAs(components.Shape, madeFrom.shape) &&
417
+ isSolid(actor) === madeFrom.solid
418
+ );
419
+ }
420
+
421
+ // Whether a fixed body is already where its Transform says. The six numbers it
422
+ // was last compared at are kept and compared as they are; anything that is not
423
+ // plainly the same six is settled by the key `pushTransforms` compares, and
424
+ // the entry's `pushedKey` is moved on when that differs.
425
+ function alreadyPushed(entry, made, t) {
426
+ const at = made.pushedAt;
427
+ if (
428
+ at &&
429
+ at.x === t.x &&
430
+ at.y === t.y &&
431
+ at.z === t.z &&
432
+ at.rotationX === t.rotationX &&
433
+ at.rotationY === t.rotationY &&
434
+ at.rotationZ === t.rotationZ
435
+ ) {
436
+ return true;
437
+ }
438
+ const key = transformKey(t);
439
+ const same = key === entry.pushedKey;
440
+ entry.pushedKey = key;
441
+ made.pushedAt = { x: t.x, y: t.y, z: t.z, rotationX: t.rotationX, rotationY: t.rotationY, rotationZ: t.rotationZ };
442
+ return same;
443
+ }
444
+
263
445
  function bodyDescFor(actor, t) {
264
446
  const opts = actor.components.Body;
265
447
  let desc;
@@ -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