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
@@ -17,7 +17,7 @@ import * as Steer from '../client/steer.js';
17
17
  import { connectSession } from '@imports/castle.real-time/code/client/connection.js';
18
18
  import { showSoloBadge, updateSoloBadge } from '@imports/castle.real-time/code/client/soloBadge.js';
19
19
  import { showJoinOverlay } from '@imports/castle.real-time/code/client/joinOverlay.js';
20
- import { GONE, STATE, WORLD } from '@imports/castle.real-time/code/client/messages.js';
20
+ import { GONE, SCENE, STATE, WORLD } from '@imports/castle.real-time/code/client/messages.js';
21
21
 
22
22
  // How long the joining overlay may hold the card before giving up.
23
23
  const JOIN_WAIT_MS = 10000;
@@ -41,6 +41,8 @@ const WRITTEN_SLACK = 0.005;
41
41
  // A moving object in the WORLD snapshot also gets a pose this far back along
42
42
  // its velocity, so interpolation has two poses to move it between at once.
43
43
  const JOIN_BACK_MS = 250;
44
+ // Castle refuses a player barred from the hub every hub join with this code.
45
+ const HUB_BANNED = 'CAULDRON_HUB_BANNED';
44
46
 
45
47
  // A deck may provide its own multiplayer system. The engine registry permits
46
48
  // duplicate systems, which would create duplicate session connections, so these
@@ -62,6 +64,10 @@ export function installSystem(runtime) {
62
64
  }
63
65
  const system = new MultiplayerSystem();
64
66
  runtime.registerSystem(system);
67
+
68
+ // Deck code that moves the player between sessions (a hub's doors) reaches
69
+ // the system here, for `switchSession`.
70
+ runtime.multiplayer = system;
65
71
  return system;
66
72
  }
67
73
 
@@ -78,8 +84,44 @@ class MultiplayerSystem {
78
84
  // `starting` prevents concurrent join attempts while the promise is pending.
79
85
  this.starting = false;
80
86
 
87
+ // What `Multiplayer.join` is asked for, and whether the kit's join overlay
88
+ // stays down while it happens (the caller covers the join itself, as a
89
+ // hub's door animation does). `generation` counts `switchSession` calls, so
90
+ // a join still pending from before one is dropped when it lands.
91
+ // A client hook may name the first join instead (`firstJoin`, a hub place
92
+ // that joins its world through a destination route).
93
+ this.target = game.firstJoin?.() ?? { mode: 'public' };
94
+ this.quiet = false;
95
+ this.generation = 0;
96
+ // A hub join (`{ mode: 'hub', handoff }`) spends its handoff: once it is
97
+ // refused, or its connection closes for good, it is not tried again. The
98
+ // caller that switched to it reads `joinState()` and decides where to go.
99
+ this.joinFailed = false;
100
+ // The CastleError code of a join refused for good (`HUB_BANNED`), else null.
101
+ this.joinError = null;
102
+ // Whether the join `switchSession` asked for has resolved (for a hub join,
103
+ // the host committed the trip), kept apart from whether its connection is
104
+ // still open. `holding` keeps a new connection's messages queued, nothing
105
+ // received or reported, until the caller `release()`s it.
106
+ this.joinCommitted = false;
107
+ this.holding = false;
108
+ // A hub join the host committed whose connection then closed before the
109
+ // session placed this player (a full layer refusing the socket after its
110
+ // hello): the player is in no session, and the spent handoff is not
111
+ // joined again. Only a hub target is ever lost; `joinState()` says 'lost'.
112
+ this.joinLost = false;
113
+
81
114
  // Network histories are indexed separately for players and scene actors.
82
115
  this.players = new Map();
116
+ // A session that sends other players' rows only every few ticks (a hub
117
+ // town) numbers them: number -> playerId, from `idm`, kept for the whole
118
+ // session; and says how far apart the rows are (`pi`, ms), which others
119
+ // are drawn about that much further behind so there is a later row to
120
+ // move toward. `rowLagShown` eases toward that, so the moment drawn never
121
+ // jumps.
122
+ this.shortIds = new Map();
123
+ this.rowInterval = 0;
124
+ this.rowLagShown = 0;
83
125
  this.objects = new Map();
84
126
 
85
127
  // The clock maps page time to delayed server simulation time.
@@ -142,14 +184,25 @@ class MultiplayerSystem {
142
184
  // multiplayer sessions because the scene editor constructs but never steps them.
143
185
  if (!this.net) {
144
186
  showJoinOverlay(this.joiningOverlayWanted());
145
- return void this.start();
187
+ return void this.start(scene);
146
188
  }
147
189
 
148
190
  // The session ended under this connection (the server was replaced, or the
149
191
  // platform closed it). Everything drawn from it goes, and the next frame
150
192
  // joins afresh behind the overlay.
151
193
  if (this.net.closed()) {
194
+ // A recovery the platform refused because the player is barred from the
195
+ // hub is as final as a first join refused that way.
196
+ this.joinError = this.net.closeError?.() === HUB_BANNED ? HUB_BANNED : null;
197
+ if (this.target?.mode === 'hub' && this.joinCommitted && !this.joined) {
198
+ this.joinLost = true;
199
+ }
152
200
  this.reset(scene);
201
+ this.shortIds.clear();
202
+ this.rowInterval = 0;
203
+ this.rowLagShown = 0;
204
+ this.joinFailed = this.target?.mode === 'hub' || this.joinError !== null;
205
+ this.holding = false;
153
206
  this.net = null;
154
207
  this.joined = false;
155
208
  this.joinStartedAt = 0;
@@ -157,6 +210,9 @@ class MultiplayerSystem {
157
210
  this.sentState = '';
158
211
  return;
159
212
  }
213
+ if (this.holding) {
214
+ return;
215
+ }
160
216
  const local = scene.actorWith('Player');
161
217
  if (this.settleFrames > 0) {
162
218
  this.settleFrames -= 1;
@@ -172,8 +228,9 @@ class MultiplayerSystem {
172
228
  // timestamp establishes a clock offset.
173
229
  const at = Clock.ready(this.clock) ? Clock.renderTime(this.clock, performance.now()) : null;
174
230
  if (at !== null) {
231
+ this.easeRowLag(dt);
175
232
  this.applyObjectPoses(scene, at, dt, local);
176
- this.applyPlayerPoses(scene, at, dt);
233
+ this.applyPlayerPoses(scene, at - this.rowLag(), dt);
177
234
  }
178
235
 
179
236
  // Apply a server clamp before collecting this frame's outgoing local pose.
@@ -206,27 +263,118 @@ class MultiplayerSystem {
206
263
  showJoinOverlay(this.joiningOverlayWanted());
207
264
  }
208
265
 
209
- // Join the Castle public session once and retain the transport across scene loads.
210
- async start() {
211
- if (this.starting) {
266
+ // Join the session `target` names (the public one unless `switchSession`
267
+ // said otherwise) and retain the transport across scene loads.
268
+ async start(scene) {
269
+ if (this.starting || this.joinFailed) {
212
270
  return;
213
271
  }
214
272
  this.starting = true;
215
273
  this.joinStartedAt ||= performance.now();
274
+ const generation = this.generation;
216
275
  try {
217
- this.net = await connectSession({
276
+ const net = await connectSession({
277
+ join: this.target,
218
278
  onLog: (text) => console.log(`[multiplayer] ${text}`),
219
279
 
220
280
  // A deck message can be handled on arrival through the `arrive` hook,
221
281
  // which still runs in a hidden tab. State messages always wait for a frame.
222
282
  onArrival: (msg) => msg.k !== STATE && msg.k !== WORLD && game.arrive?.(msg, this) === true,
283
+
284
+ // A reconnect may reach a restarted server process, which builds its
285
+ // world from scratch: it is named the scene again.
286
+ onConnected: () => {
287
+ if (generation === this.generation) {
288
+ this.nameScene(scene);
289
+ }
290
+ },
223
291
  });
292
+ if (generation !== this.generation) {
293
+ // `switchSession` ran while this join was pending: it is not wanted.
294
+ net.close();
295
+ return;
296
+ }
297
+ this.net = net;
298
+ this.joinCommitted = true;
299
+
300
+ this.nameScene(scene);
224
301
  } catch (err) {
225
302
  console.log(`[multiplayer] could not join: ${err?.message ?? err}`);
226
- this.starting = false;
303
+ if (generation === this.generation) {
304
+ this.starting = false;
305
+ // A player Castle has barred from the hub is refused every hub join,
306
+ // the town's own included: asking again changes nothing.
307
+ this.joinError = err?.code === HUB_BANNED ? HUB_BANNED : null;
308
+ this.joinFailed = this.target?.mode === 'hub' || this.joinError !== null;
309
+ }
310
+ }
311
+ }
312
+
313
+ // A deck whose server takes its scene from the client names the scene this
314
+ // runtime is playing, before anything else is sent. A server that already
315
+ // has one ignores it.
316
+ nameScene(scene) {
317
+ if (game.sceneFromClient && this.net) {
318
+ this.net.send({ k: SCENE, path: scene?.currentScenePath ?? scene?.scenePath ?? 'scenes/main.scene' });
227
319
  }
228
320
  }
229
321
 
322
+ // Leave the current session and join another on the next frame: `join` is
323
+ // what `Multiplayer.join` is asked for (`{ mode: 'named', key }`, or
324
+ // `{ mode: 'public' }` to go back). Everything drawn from the old session goes
325
+ // now. `quiet` keeps the kit's join overlay down because the caller covers
326
+ // the join; `placed()` says when the new session has placed this player.
327
+ // A scene swap requested in the same frame is applied before the next one,
328
+ // so the new session is named the new scene.
329
+ switchSession(scene, join, { quiet = false, hold = false } = {}) {
330
+ this.generation += 1;
331
+ this.reset(scene);
332
+ this.net?.close();
333
+ this.net = null;
334
+ this.joined = false;
335
+ this.joinStartedAt = 0;
336
+ this.joinWarned = false;
337
+ this.starting = false;
338
+ this.joinFailed = false;
339
+ this.joinError = null;
340
+ this.joinCommitted = false;
341
+ this.joinLost = false;
342
+ this.holding = hold;
343
+ this.sentState = '';
344
+ this.gone.clear();
345
+ // The new session numbers its rows afresh.
346
+ this.shortIds.clear();
347
+ this.rowInterval = 0;
348
+ this.rowLagShown = 0;
349
+ // The new session's simulation clock starts from its own zero.
350
+ this.clock = Clock.makeClock();
351
+ this.target = join;
352
+ this.quiet = quiet;
353
+ showJoinOverlay(this.joiningOverlayWanted());
354
+ }
355
+
356
+ // Where the join `switchSession` asked for stands: 'joining', 'joined' (it
357
+ // resolved -- for a hub join, the host committed the trip -- even if the
358
+ // connection has closed since), 'lost' (a hub join the host committed whose
359
+ // connection closed before the session placed this player; it is not
360
+ // retried) or 'failed' (a hub join refused before the commit; not retried).
361
+ // Only a hub join is ever 'lost'.
362
+ joinState() {
363
+ return this.joinLost ? 'lost' : this.joinCommitted ? 'joined' : this.joinFailed ? 'failed' : 'joining';
364
+ }
365
+
366
+ // Lets a held connection's queued messages through (`switchSession` `hold`),
367
+ // once the caller has the scene they belong to.
368
+ release() {
369
+ this.holding = false;
370
+ }
371
+
372
+ // Whether the session has placed this player and the body and camera have
373
+ // caught up with it, which is when a caller covering the join can uncover.
374
+ placed() {
375
+ return Boolean(this.net) && this.joined && !this.placedTo && this.settleFrames === 0;
376
+ }
377
+
230
378
  // Drain queued transport messages. State messages update clock, ownership, pose
231
379
  // histories, and deck state in that order; other message kinds go to the deck.
232
380
  receive(scene) {
@@ -237,6 +385,21 @@ class MultiplayerSystem {
237
385
  continue;
238
386
  }
239
387
 
388
+ // Short-numbered rows get their ids back before anything reads them.
389
+ for (const [n, id] of msg.idm ?? []) {
390
+ this.shortIds.set(n, id);
391
+ }
392
+ if (msg.ps?.some((row) => typeof row[0] === 'number')) {
393
+ msg.ps = msg.ps
394
+ .map(([n, ...rest]) => [typeof n === 'number' ? this.shortIds.get(n) : n, ...rest])
395
+ .filter(([id]) => id !== undefined);
396
+ }
397
+ // Rows that say how far apart they come (`pi`) set how far behind
398
+ // others are drawn; rows that do not (a broadcast) say every tick.
399
+ if (msg.ps?.length) {
400
+ this.rowInterval = typeof msg.pi === 'number' ? msg.pi : 0;
401
+ }
402
+
240
403
  // Pair simulation time with the page arrival time before filing samples.
241
404
  Clock.noteArrival(this.clock, msg.t, msg.localMs);
242
405
  if (!this.joined && (msg.k === WORLD || (msg.ps ?? []).some((pose) => pose[0] === selfId))) {
@@ -260,6 +423,24 @@ class MultiplayerSystem {
260
423
  Ownership.applyHandovers(this.own, msg.own, selfId, performance.now());
261
424
  noteGrants(this.granted, msg.own, selfId);
262
425
  this.noteHandovers(msg);
426
+
427
+ // A session that sends each client only the players near it (a hub
428
+ // place) says who it stopped sending, and who it started sending again,
429
+ // whose row here starts a fresh history.
430
+ for (const id of msg.out ?? []) {
431
+ this.dropPlayer(id);
432
+ Avatars.retire(this.avatars, scene, id);
433
+ }
434
+ for (const id of msg.in ?? []) {
435
+ this.dropPlayer(id);
436
+ Avatars.enter(this.avatars, id);
437
+ }
438
+ // A row for a player still shrinking away turns it around, `in` or not.
439
+ for (const [id] of msg.ps ?? []) {
440
+ if (this.avatars.leaving.has(id)) {
441
+ Avatars.enter(this.avatars, id);
442
+ }
443
+ }
263
444
  for (const [id, x, y, z, facing, clamped] of msg.ps ?? []) {
264
445
  if (id !== selfId) {
265
446
  sample(this.players, msg, id, [x, y, z, facing]);
@@ -512,6 +693,7 @@ class MultiplayerSystem {
512
693
  });
513
694
  }
514
695
  Avatars.dropMissing(this.avatars, scene, others);
696
+ Avatars.animate(this.avatars, scene, dt);
515
697
  for (const playerId of [...this.players.keys()]) {
516
698
  if (!others.has(playerId)) {
517
699
  this.dropPlayer(playerId);
@@ -519,6 +701,22 @@ class MultiplayerSystem {
519
701
  }
520
702
  }
521
703
 
704
+ // How much further behind other players are drawn than objects: enough that
705
+ // rows sent every `rowInterval` ms always have a later one to move toward.
706
+ // Nothing for a session that sends them every tick.
707
+ rowLag() {
708
+ return this.rowLagShown;
709
+ }
710
+
711
+ // Move the lag toward its target by at most a tenth of the frame's time, so
712
+ // other players play a little slower or faster for a moment rather than
713
+ // jumping back or ahead when the session starts or stops spacing its rows.
714
+ easeRowLag(dt) {
715
+ const target = this.rowInterval > 0 ? Math.max(0, this.rowInterval + 20 - this.clock.delay) : 0;
716
+ const step = Math.max(0, dt) * 1000 * 0.1;
717
+ this.rowLagShown += Math.max(-step, Math.min(step, target - this.rowLagShown));
718
+ }
719
+
522
720
  // Remove history and smoothing state after a player leaves the SDK roster.
523
721
  dropPlayer(playerId) {
524
722
  this.players.delete(playerId);
@@ -665,7 +863,7 @@ class MultiplayerSystem {
665
863
  // Sample other player positions at the current delayed render time. Ownership
666
864
  // claims use these points to require the local player to be closest.
667
865
  otherPlaces(now) {
668
- const at = Clock.ready(this.clock) ? Clock.renderTime(this.clock, now) : null;
866
+ const at = Clock.ready(this.clock) ? Clock.renderTime(this.clock, now) - this.rowLag() : null;
669
867
  if (at === null) {
670
868
  return [];
671
869
  }
@@ -750,6 +948,19 @@ class MultiplayerSystem {
750
948
  // Actors removed for good
751
949
  //
752
950
 
951
+ // Forget everything kept about a scene object the caller removed for good
952
+ // without its being gone (a copy a place despawned, say): its pose history,
953
+ // steering, smoothing and handover. A pose the session sends for it later
954
+ // starts afresh.
955
+ forgetObject(id) {
956
+ this.objects.delete(id);
957
+ this.live.delete(id);
958
+ this.written.delete(id);
959
+ this.handed.delete(id);
960
+ this.acks.delete(id);
961
+ Smoothing.forget(this.shown, id);
962
+ }
963
+
753
964
  // Despawn every actor the session says is gone. Runs each frame, so a scene
754
965
  // load that brings an actor back from the file loses it again at once.
755
966
  applyGone(scene) {
@@ -768,7 +979,7 @@ class MultiplayerSystem {
768
979
  if (this.seen && this.joined) {
769
980
  const avatars = new Set(this.avatars.actors.values());
770
981
  for (const id of this.seen) {
771
- if (ids.has(id) || this.gone.has(id) || avatars.has(id)) {
982
+ if (ids.has(id) || this.gone.has(id) || avatars.has(id) || this.avatars.retired.delete(id)) {
772
983
  continue;
773
984
  }
774
985
  this.gone.add(id);
@@ -782,7 +993,7 @@ class MultiplayerSystem {
782
993
  // yet placed. A session that never answers releases it after JOIN_WAIT_MS so
783
994
  // the deck is not stuck behind it.
784
995
  joiningOverlayWanted() {
785
- if (this.net?.status().solo) {
996
+ if (this.quiet || this.net?.status().solo || this.joinError) {
786
997
  return false;
787
998
  }
788
999
 
@@ -384,6 +384,8 @@ A scene is a background plus a list of actors. Every actor is an **instance of a
384
384
  }
385
385
  ```
386
386
 
387
+ A scene can set `"engine": { "skipUnchangedActors": true }` at its top level, beside `background`; the terms are in the 3d kit's `CLAUDE.md`. In this kit it does one thing: the actor list is not sorted again while every `Layout.z` is a stored number already in order. The update loop and every behavior hook are the same with and without it, so a 2d scene gains little.
388
+
387
389
  ### Switching a behavior off without losing its settings
388
390
 
389
391
  Any component may carry `"$enabled": false` to stop the behavior running while
@@ -68,11 +68,11 @@
68
68
  "onUpdate": "scripts/onUpdate.mjs",
69
69
  "title": "physics-2d",
70
70
  "description": "Scene Editor. Works like classic Castle: actors, blueprints, behaviors and drawing tools, with physics built in.",
71
- "publishedVersion": "2026-09-25T17:51:55.024Z",
71
+ "publishedVersion": "2026-10-04T22:43:17.146Z",
72
72
  "imports": {
73
73
  "castle.base": {
74
74
  "deckId": "yRcmH4_aYllE",
75
- "version": "2026-09-23T02:16:18.339Z"
75
+ "version": "2026-10-04T22:42:38.248Z"
76
76
  }
77
77
  }
78
78
  }
@@ -72,6 +72,19 @@ export function imageArt(path, url) {
72
72
  return art;
73
73
  }
74
74
 
75
+ // Forget an image art for good (a mounted content pack being dropped): the
76
+ // next `imageArt` of this url builds a fresh one. Returns the art it dropped,
77
+ // so a renderer can release what it baked from it.
78
+ export function releaseImageArt(url) {
79
+ const art = imageArts.get(url);
80
+ if (!art) return null;
81
+ imageArts.delete(url);
82
+ art.image.onload = null;
83
+ art.image.onerror = null;
84
+ art.image.src = '';
85
+ return art;
86
+ }
87
+
75
88
  export function isImageArt(art) {
76
89
  return Boolean(art) && art.kind === 'image';
77
90
  }
@@ -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
@@ -101,6 +101,61 @@ function makeBehaviorsProxy(scene, actor) {
101
101
  });
102
102
  }
103
103
 
104
+ // `"engine": { "skipUnchangedActors": true }` at a scene file's top level: the
105
+ // scene asks the engine not to redo, every frame, work whose answer cannot
106
+ // have changed (the 3d kit's CLAUDE.md has the terms). It is off unless a scene
107
+ // says so. In this file it does one thing: `getActors` does not sort a list
108
+ // that is already in order. The update loop is the same loop either way.
109
+ function sceneSkipsUnchangedActors(data) {
110
+ return data?.engine?.skipUnchangedActors === true;
111
+ }
112
+
113
+ // `"engine": { "shadows": { "distance": <metres> } }` at a scene file's top
114
+ // level: the scene asks the 3d kit to draw the sun's shadows in a box that
115
+ // follows the view, complete out to that far from the camera (its CLAUDE.md
116
+ // has the terms). 0 unless a scene says so with a finite number above 0.
117
+ // Nothing in this kit reads it.
118
+ function sceneNearShadowDistance(data) {
119
+ const distance = data?.engine?.shadows?.distance;
120
+ return typeof distance === 'number' && Number.isFinite(distance) && distance > 0 ? distance : 0;
121
+ }
122
+
123
+ // `"engine": { "camera": { "follow": "rigid" } }` at a scene file's top level:
124
+ // the scene asks the 3d kit's Player for a follow camera that moves with the
125
+ // player rather than easing after it (its CLAUDE.md has the terms). Off unless
126
+ // a scene says so with exactly "rigid". Nothing in this kit reads it.
127
+ function sceneCameraFollowsRigidly(data) {
128
+ return data?.engine?.camera?.follow === 'rigid';
129
+ }
130
+
131
+ // Whether a Layout's z is plain data: its own stored value, or absent
132
+ // altogether. One that is computed when read (an accessor, or carried by a
133
+ // prototype) is left to the sort, which reads it in the sort's own order.
134
+ function hasPlainZ(layout) {
135
+ if (typeof layout !== 'object') return false;
136
+ const own = Object.getOwnPropertyDescriptor(layout, 'z');
137
+ return own ? 'value' in own : !('z' in layout);
138
+ }
139
+
140
+ // Whether the actors are already in the order `getActors` sorts them into:
141
+ // every Layout z plain data and a finite number (or absent, which is 0), none
142
+ // below the one before it. Sorting is stable, so sorting such a list would
143
+ // change nothing.
144
+ function alreadyInLayoutOrder(actors) {
145
+ let last = -Infinity;
146
+ for (let i = 0; i < actors.length; i++) {
147
+ const layout = getLayout(actors[i]);
148
+ let z = 0;
149
+ if (layout !== undefined && layout !== null) {
150
+ if (!hasPlainZ(layout)) return false;
151
+ z = layout.z ?? 0;
152
+ }
153
+ if (typeof z !== 'number' || !Number.isFinite(z) || z < last) return false;
154
+ last = z;
155
+ }
156
+ return true;
157
+ }
158
+
104
159
  // Shared by the constructor and `setBehaviors` -- both build the same
105
160
  // behaviorName -> class Map from a list of classes.
106
161
  function behaviorMapFrom(classes) {
@@ -108,6 +163,31 @@ function behaviorMapFrom(classes) {
108
163
  }
109
164
 
110
165
  export class SceneRuntime {
166
+ // Whether the loaded scene asked for `skipUnchangedActors`. Set by `load`
167
+ // from the scene's data and by nothing else, so one scene runs one way from
168
+ // its load to the next.
169
+ #skipUnchanged = false;
170
+
171
+ get skipsUnchangedActors() {
172
+ return this.#skipUnchanged;
173
+ }
174
+
175
+ // The distance the loaded scene asked for with `engine.shadows.distance`,
176
+ // or 0. Set by `load`, as `skipsUnchangedActors` is.
177
+ #nearShadowDistance = 0;
178
+
179
+ get nearShadowDistance() {
180
+ return this.#nearShadowDistance;
181
+ }
182
+
183
+ // Whether the loaded scene asked for `engine.camera.follow: "rigid"`. Set
184
+ // by `load`, as `skipsUnchangedActors` is.
185
+ #cameraFollowsRigidly = false;
186
+
187
+ get cameraFollowsRigidly() {
188
+ return this.#cameraFollowsRigidly;
189
+ }
190
+
111
191
  // `files` is the live deck files map (path -> text), used to resolve every
112
192
  // actor's `blueprint` ref against the CURRENT blueprint file content -- not
113
193
  // a load-time snapshot -- so a blueprint edit propagates to every scene that
@@ -240,6 +320,9 @@ export class SceneRuntime {
240
320
  // No-op on the constructor's first load, before any system is registered.
241
321
  for (const system of this.systems) system.reset?.(this);
242
322
  this.data = structuredClone(sceneData);
323
+ this.#skipUnchanged = sceneSkipsUnchangedActors(this.data);
324
+ this.#nearShadowDistance = sceneNearShadowDistance(this.data);
325
+ this.#cameraFollowsRigidly = sceneCameraFollowsRigidly(this.data);
243
326
  this.actors = new Map();
244
327
  for (const actor of this.data.actors ?? []) {
245
328
  this.#initActor(actor);
@@ -264,8 +347,9 @@ export class SceneRuntime {
264
347
  // instead of `import x from './scenes/foo.scene'` -- scene files are data, not
265
348
  // JS modules, so importing them is unsupported.
266
349
  readFromFile(name) {
267
- const key = resolveSceneFileKey(name);
268
- const text = initialFiles[key];
350
+ const files = this.content?.files ?? initialFiles;
351
+ const key = resolveSceneFileKey(name, files);
352
+ const text = files[key];
269
353
  if (text === undefined) {
270
354
  throw new Error(`scene file not found: ${name}`);
271
355
  }
@@ -277,10 +361,29 @@ export class SceneRuntime {
277
361
  // Transition the running scene to the scene stored in the named file (read it
278
362
  // fresh, then load it). The building block for "go to scene" / restart.
279
363
  loadFromFile(name) {
280
- this.scenePath = resolveSceneFileKey(name);
364
+ this.scenePath = resolveSceneFileKey(name, this.content?.files ?? initialFiles);
281
365
  this.load(this.readFromFile(name));
282
366
  }
283
367
 
368
+ // Swap whose content this runtime reads: another deck's, mounted as data (a
369
+ // hub content pack: `{ id, files, sprites }`), or null for this deck's own.
370
+ // Scene names, blueprints, models and art then resolve inside that content
371
+ // alone, so two decks' `scenes/main.scene` never meet. The swap takes effect
372
+ // at the next `loadFromFile`, which the caller makes in the same breath (the
373
+ // 3d player applies `requestedContent` with `requestedScene`).
374
+ setContent(content) {
375
+ this.ownContent ??= { files: this.files, sprites: this.sprites };
376
+ this.content = content ?? null;
377
+ this.files = content ? content.files : this.ownContent.files;
378
+ this.sprites = content ? content.sprites : this.ownContent.sprites;
379
+ }
380
+
381
+ // The scene's identity across contents: its path, qualified by the content
382
+ // it came from when that is not this deck's own.
383
+ get sceneKey() {
384
+ return this.content ? `${this.content.id}:${this.scenePath}` : this.scenePath;
385
+ }
386
+
284
387
  clone() {
285
388
  // Route through makeScene so the clone gets the same registered systems as a
286
389
  // freshly-made runtime.
@@ -309,6 +412,7 @@ export class SceneRuntime {
309
412
  }
310
413
 
311
414
  getActors() {
415
+ if (this.#skipUnchanged) return this.#actorsSkippingSort();
312
416
  return [...this.actors.values()].sort((a, b) => {
313
417
  const az = getLayout(a)?.z ?? 0;
314
418
  const bz = getLayout(b)?.z ?? 0;
@@ -316,6 +420,14 @@ export class SceneRuntime {
316
420
  });
317
421
  }
318
422
 
423
+ // `getActors` for a scene that set `skipUnchangedActors`: the same list,
424
+ // sorted only when it is not already in order.
425
+ #actorsSkippingSort() {
426
+ const actors = [...this.actors.values()];
427
+ if (alreadyInLayoutOrder(actors)) return actors;
428
+ return actors.sort((a, b) => (getLayout(a)?.z ?? 0) - (getLayout(b)?.z ?? 0));
429
+ }
430
+
319
431
  getComponent(actor, behaviorName) {
320
432
  return actor?.components?.[behaviorName] ?? null;
321
433
  }
@@ -7,7 +7,7 @@
7
7
  "palette": "node scripts/palette.mjs",
8
8
  "restart": "node ../../cli/dist/index.js restart .",
9
9
  "screenshot": "node ../../cli/dist/index.js screenshot .",
10
- "check": "node ../../scripts/sync-shared.mjs --check && eslint . && jscpd && node --input-type=module -e \"const { bundleProject } = await import('../../cli/dist/bundle.js'); await bundleProject('.');\""
10
+ "check": "node ../../scripts/sync-shared.mjs --check && eslint . && jscpd && node scripts/test-skip-unchanged.mjs && node --input-type=module -e \"const { bundleProject } = await import('../../cli/dist/bundle.js'); await bundleProject('.');\""
11
11
  },
12
12
  "jscpd": {
13
13
  "path": [