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
@@ -13,6 +13,13 @@ import { makeShapeMesh } from '@imports/castle.physics-3d/engine3d/materials.js'
13
13
  // until it makes one.
14
14
  const BLUEPRINT = 'blueprints/other-player.scene';
15
15
 
16
+ // How long a player the session starts or stops sending (a hub place's
17
+ // interest set) takes to grow in or shrink away, in seconds.
18
+ const FADE_SECONDS = 0.35;
19
+ // Where an entering actor waits for the frame its node is first drawn, so it
20
+ // is never drawn once at full size.
21
+ const SINK_Y = -1000;
22
+
16
23
  function defaultBlueprint(scene) {
17
24
  const files = scene.files ?? {};
18
25
  if (files[BLUEPRINT]) {
@@ -28,9 +35,89 @@ export function makeAvatars() {
28
35
  return {
29
36
  actors: new Map(), // playerId -> actor id
30
37
  tags: new Map(), // playerId, or 'self', -> name tag
38
+ // Players the session started or stopped sending (`enter`, `retire`):
39
+ // playerId -> how far grown, 0..1, and playerId -> { actorId, grown }
40
+ // for a shrinking actor no longer in `actors`.
41
+ entering: new Map(),
42
+ leaving: new Map(),
43
+ // Actor ids `animate` despawned after a `retire`: the client's own, not
44
+ // scene actors, so the frame that sees them gone does not report them.
45
+ retired: new Set(),
31
46
  };
32
47
  }
33
48
 
49
+ // The session started sending this player (a hub place's interest set): its
50
+ // actor grows in rather than appearing at full size. One still shrinking away
51
+ // turns around where it is.
52
+ export function enter(avatars, playerId) {
53
+ const leaving = avatars.leaving.get(playerId);
54
+ if (leaving) {
55
+ avatars.leaving.delete(playerId);
56
+ avatars.actors.set(playerId, leaving.actorId);
57
+ avatars.entering.set(playerId, leaving.grown);
58
+ return;
59
+ }
60
+ avatars.entering.set(playerId, 0);
61
+ }
62
+
63
+ // The session stopped sending this player: its label goes now and its actor
64
+ // shrinks away where it stands, then is despawned (`animate`).
65
+ export function retire(avatars, scene, playerId) {
66
+ const actorId = avatars.actors.get(playerId);
67
+ const earlier = avatars.leaving.get(playerId);
68
+ if (earlier && earlier.actorId !== actorId && scene.getActor(earlier.actorId)) {
69
+ avatars.retired.add(earlier.actorId);
70
+ scene.despawnActor(earlier.actorId);
71
+ }
72
+ dropTag(avatars, scene, playerId);
73
+ avatars.actors.delete(playerId);
74
+ const grown = avatars.entering.get(playerId) ?? 1;
75
+ avatars.entering.delete(playerId);
76
+ if (actorId && scene.getActor(actorId)) {
77
+ avatars.leaving.set(playerId, { actorId, grown });
78
+ }
79
+ }
80
+
81
+ // Grow entering actors and shrink leaving ones by one frame. A deck that never
82
+ // calls `enter` or `retire` has nothing here.
83
+ export function animate(avatars, scene, dt) {
84
+ const step = dt / FADE_SECONDS;
85
+ for (const [playerId, grown] of avatars.entering) {
86
+ const actorId = avatars.actors.get(playerId);
87
+ const actor = actorId && scene.getActor(actorId);
88
+ if (!actor) {
89
+ continue;
90
+ }
91
+ const node = scene.three?.nodes?.get(actorId)?.node;
92
+ if (!node) {
93
+ actor.components.Transform.y += SINK_Y;
94
+ continue;
95
+ }
96
+ const next = Math.min(1, grown + step);
97
+ node.scale.setScalar(Math.max(0.001, ease(next)));
98
+ if (next >= 1) {
99
+ avatars.entering.delete(playerId);
100
+ } else {
101
+ avatars.entering.set(playerId, next);
102
+ }
103
+ }
104
+ for (const [playerId, entry] of avatars.leaving) {
105
+ const node = scene.three?.nodes?.get(entry.actorId)?.node;
106
+ entry.grown -= step;
107
+ if (entry.grown <= 0 || !node || !scene.getActor(entry.actorId)) {
108
+ avatars.retired.add(entry.actorId);
109
+ scene.despawnActor(entry.actorId);
110
+ avatars.leaving.delete(playerId);
111
+ continue;
112
+ }
113
+ node.scale.setScalar(Math.max(0.001, ease(entry.grown)));
114
+ }
115
+ }
116
+
117
+ function ease(t) {
118
+ return t * t * (3 - 2 * t);
119
+ }
120
+
34
121
  // Create or update one other player and return its engine actor. A deck can
35
122
  // modify the returned actor after the kit applies the network pose.
36
123
  //
@@ -47,7 +134,8 @@ export function showPlayer(avatars, scene, playerId, username, pose, options = {
47
134
  // The engine Transform is the client-visible pose for the other player's actor.
48
135
  applyPose(actor.components.Transform, pose);
49
136
  const transform = actor.components.Transform;
50
- if (username === null) {
137
+ // A label appears once its actor has grown in.
138
+ if (username === null || avatars.entering.has(playerId)) {
51
139
  dropTag(avatars, scene, playerId);
52
140
  } else {
53
141
  showTag(avatars, scene, playerId, username, transform, options.tagHeight);
@@ -77,6 +165,7 @@ export function dropMissing(avatars, scene, present) {
77
165
  }
78
166
  scene.despawnActor(avatars.actors.get(playerId));
79
167
  avatars.actors.delete(playerId);
168
+ avatars.entering.delete(playerId);
80
169
  dropTag(avatars, scene, playerId);
81
170
  }
82
171
  }
@@ -86,6 +175,17 @@ export function dropMissing(avatars, scene, present) {
86
175
  // explicit disposal.
87
176
  export function clearAvatars(avatars, scene) {
88
177
  avatars.actors.clear();
178
+ avatars.entering.clear();
179
+ // A reset that is not a scene load (a closed connection, `switchSession`)
180
+ // leaves shrinking actors in the scene; nothing would despawn them later.
181
+ // The reset also forgets which actors were seen, so none is reported.
182
+ for (const { actorId } of avatars.leaving.values()) {
183
+ if (scene.getActor(actorId)) {
184
+ scene.despawnActor(actorId);
185
+ }
186
+ }
187
+ avatars.leaving.clear();
188
+ avatars.retired.clear();
89
189
  for (const key of [...avatars.tags.keys()]) {
90
190
  dropTag(avatars, scene, key);
91
191
  }
@@ -88,7 +88,10 @@ export function setPose(sim, playerId, message) {
88
88
  }
89
89
 
90
90
  // Combine elapsed-time movement allowance with fixed delivery slack.
91
- const reach = Limits.MAX_SPEED * earned(sim, player.movedAt) + Limits.MOVE_SLACK;
91
+ // A place may let one player move faster than the rest (the hub's
92
+ // `hub.tune`); everyone else keeps the deck's limit.
93
+ const maxSpeed = Number.isFinite(player.maxSpeed) ? player.maxSpeed : Limits.MAX_SPEED;
94
+ const reach = maxSpeed * earned(sim, player.movedAt) + Limits.MOVE_SLACK;
92
95
  player.movedAt = sim.timeMs;
93
96
  const step = {
94
97
  x: asked.x - player.at.x,
@@ -6,8 +6,11 @@ import { componentDefaults } from '@imports/castle.real-time/code/server/gameHoo
6
6
 
7
7
  // Root-anchored globs select files from the importing deck. Eager raw imports
8
8
  // embed the text in the server bundle, whose runtime has no deck filesystem.
9
- // Globbing also permits this kit's own package to omit a main scene.
10
- const sceneTexts = import.meta.glob('/scenes/main.scene', {
9
+ // Globbing also permits this kit's own package to omit a main scene. Every
10
+ // scene is embedded, not only the main one, because a deck whose server takes
11
+ // its scene from the client (`sceneFromClient`) runs a different one in each
12
+ // session.
13
+ const sceneTexts = import.meta.glob('/scenes/*.scene', {
11
14
  eager: true,
12
15
  query: '?raw',
13
16
  import: 'default',
@@ -40,10 +43,21 @@ const DEFAULTS = {
40
43
  ...componentDefaults,
41
44
  };
42
45
 
43
- // Parse the deck's main scene and return actor ids with resolved components.
44
- // `world.createSimulation` consumes this reduced representation at startup.
45
- export function readScene() {
46
- const text = sceneTexts['/scenes/main.scene'];
46
+ const MAIN_SCENE = 'scenes/main.scene';
47
+
48
+ // The deck scene a session should build: the one named, when the deck has it,
49
+ // else the main scene.
50
+ export function resolveScenePath(scenePath) {
51
+ return typeof scenePath === 'string' && sceneTexts[`/${scenePath}`] !== undefined
52
+ ? scenePath
53
+ : MAIN_SCENE;
54
+ }
55
+
56
+ // Parse one of the deck's scenes (the main one by default) and return actor ids
57
+ // with resolved components. `world.createSimulation` consumes this reduced
58
+ // representation at startup.
59
+ export function readScene(scenePath = MAIN_SCENE) {
60
+ const text = sceneTexts[`/${resolveScenePath(scenePath)}`];
47
61
 
48
62
  // An empty actor list lets this kit bundle independently without a deck scene.
49
63
  if (!text) {
@@ -59,6 +73,13 @@ export function readScene() {
59
73
  }));
60
74
  }
61
75
 
76
+ // The scene file's own `ground` setting (`{ none: true }` for a scene with no
77
+ // ground), or null.
78
+ export function sceneGround(scenePath = MAIN_SCENE) {
79
+ const text = sceneTexts[`/${resolveScenePath(scenePath)}`];
80
+ return text ? (JSON.parse(text).ground ?? null) : null;
81
+ }
82
+
62
83
  // Shallow-merge each component in engine precedence order: defaults, blueprint,
63
84
  // then scene instance values.
64
85
  function resolveComponents(actor) {
@@ -10,7 +10,7 @@ import {
10
10
  clamp,
11
11
  number,
12
12
  } from '@imports/castle.real-time/code/server/limits.js';
13
- import { readScene } from './sceneBodies.js';
13
+ import { readScene, resolveScenePath, sceneGround } from './sceneBodies.js';
14
14
  import * as Limits from './limits.js';
15
15
 
16
16
  const DEG = Math.PI / 180;
@@ -26,6 +26,7 @@ const DEG = Math.PI / 180;
26
26
  // staleReports how many owner reports were dropped for an old epoch
27
27
  // doors [{ body, props, baseY, openT }]
28
28
  // players playerId -> { body, at, facing, clamped, movedAt }
29
+ // scenePath the deck scene this session simulates
29
30
  // spawn where players come in
30
31
  // template the scene's own player actor, for its shape
31
32
  // acc seconds not yet turned into whole physics steps
@@ -49,24 +50,32 @@ function emptySim() {
49
50
 
50
51
  // Initialize Rapier and return the complete simulation consumed by server hooks.
51
52
  // Scene bodies and the server-added ground exist before the promise resolves.
52
- export async function createSimulation() {
53
+ //
54
+ // `scenePath` picks one of the deck's scenes; anything the deck does not have
55
+ // builds its main scene.
56
+ export async function createSimulation(scenePath) {
53
57
  await RAPIER.init();
54
58
  const sim = emptySim();
59
+ sim.scenePath = resolveScenePath(scenePath);
55
60
  buildGround(sim);
56
61
  buildScene(sim);
57
62
  return sim;
58
63
  }
59
64
 
60
- // Add the server's 200 m square ground slab below the authored scene.
65
+ // Add the server's 200 m square ground slab below the authored scene, unless
66
+ // the scene has none (`"ground": { "none": true }`, as the engine reads it).
61
67
  // `Limits.FELL_OUT_Y` handles dynamic bodies that fall beyond its edge.
62
68
  function buildGround(sim) {
69
+ if (sceneGround(sim.scenePath)?.none === true) {
70
+ return;
71
+ }
63
72
  const ground = sim.world.createRigidBody(RAPIER.RigidBodyDesc.fixed().setTranslation(0, -0.5, 0));
64
73
  sim.world.createCollider(RAPIER.ColliderDesc.cuboid(100, 0.5, 100), ground);
65
74
  }
66
75
 
67
76
  // Create Rapier bodies and indexes from the reduced scene representation.
68
77
  function buildScene(sim) {
69
- for (const actor of readScene()) {
78
+ for (const actor of readScene(sim.scenePath)) {
70
79
  const {
71
80
  Transform: t,
72
81
  Shape: shape,
@@ -258,11 +267,15 @@ function keepObjectsSane(sim) {
258
267
  }
259
268
 
260
269
  // Limit velocities imparted by server-side player capsules; the constant's
261
- // declaration documents why the cap remains below walking speed.
270
+ // declaration documents why the cap remains below walking speed. A game
271
+ // may give one object its own cap for a while (`speedCap`: the hub kit's
272
+ // thrown objects fly at the place's throw speed), still enforced after
273
+ // every step.
262
274
  const v = entry.body.linvel();
263
275
  const speed = Math.hypot(v.x, v.y, v.z);
264
- if (speed > Limits.MAX_PUSHED_SPEED) {
265
- const scale = Limits.MAX_PUSHED_SPEED / speed;
276
+ const cap = Number.isFinite(entry.speedCap) ? entry.speedCap : Limits.MAX_PUSHED_SPEED;
277
+ if (speed > cap) {
278
+ const scale = cap / speed;
266
279
  entry.body.setLinvel({ x: v.x * scale, y: v.y * scale, z: v.z * scale }, true);
267
280
  }
268
281
  }
@@ -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
 
@@ -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-03T04:25:18.207Z",
72
72
  "imports": {
73
73
  "castle.base": {
74
74
  "deckId": "yRcmH4_aYllE",
75
- "version": "2026-09-23T02:16:18.339Z"
75
+ "version": "2026-10-03T04:17:27.840Z"
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
  }