castle-web-cli 0.4.157 → 0.4.158

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 (243) hide show
  1. package/dist/agent-failures.d.ts +1 -0
  2. package/dist/agent-failures.js +6 -4
  3. package/dist/agent-prompts.js +4 -0
  4. package/dist/agent.d.ts +11 -0
  5. package/dist/agent.js +175 -15
  6. package/dist/bundle.js +8 -2
  7. package/dist/castle-host/host.js +4 -2
  8. package/dist/castleJson.js +6 -1
  9. package/dist/check.d.ts +1 -0
  10. package/dist/check.js +25 -0
  11. package/dist/devSessionServer.js +31 -7
  12. package/dist/imports.js +1 -19
  13. package/dist/index.js +15 -1
  14. package/dist/init.d.ts +2 -2
  15. package/dist/init.js +78 -42
  16. package/dist/mcpPlaytest.d.ts +1 -0
  17. package/dist/mcpPlaytest.js +182 -0
  18. package/dist/metering.d.ts +24 -0
  19. package/dist/metering.js +87 -0
  20. package/dist/sdkResolve.d.ts +3 -0
  21. package/dist/sdkResolve.js +55 -0
  22. package/dist/serve.js +50 -4
  23. package/dist/serverBundle.js +8 -3
  24. package/dist/shell/assets/{index-DsDkYFvP.js → index-BuSYLy-C.js} +64 -64
  25. package/dist/shell/assets/{index-DwezawBs.css → index-DfZmu3XC.css} +1 -1
  26. package/dist/shell/index.html +2 -2
  27. package/dist/vitePlugins.d.ts +1 -0
  28. package/dist/vitePlugins.js +20 -0
  29. package/kits/base/CLAUDE.md +196 -0
  30. package/kits/{blank → base}/castle.json +5 -2
  31. package/kits/base/editorHost.js +172 -0
  32. package/kits/{blank → base}/node_modules/.package-lock.json +3 -2
  33. package/kits/{blank → base}/package-lock.json +7 -4
  34. package/kits/{blank → base}/package.json +4 -2
  35. package/kits/base/sdk/README.md +569 -0
  36. package/kits/base/sdk/castle.d.ts +27 -0
  37. package/kits/base/sdk/castle.js +16 -0
  38. package/kits/base/sdk/commands.d.ts +181 -0
  39. package/kits/base/sdk/commands.js +16 -0
  40. package/kits/base/sdk/context.d.ts +17 -0
  41. package/kits/base/sdk/context.js +15 -0
  42. package/kits/base/sdk/errors.d.ts +22 -0
  43. package/kits/base/sdk/errors.js +16 -0
  44. package/kits/base/sdk/files.d.ts +15 -0
  45. package/kits/base/sdk/files.js +52 -0
  46. package/kits/base/sdk/haptics.d.ts +6 -0
  47. package/kits/base/sdk/haptics.js +36 -0
  48. package/kits/base/sdk/leaderboard.d.ts +26 -0
  49. package/kits/base/sdk/leaderboard.js +296 -0
  50. package/kits/base/sdk/lifecycle.d.ts +4 -0
  51. package/kits/base/sdk/lifecycle.js +13 -0
  52. package/kits/base/sdk/multiplayer.d.ts +43 -0
  53. package/kits/base/sdk/multiplayer.js +464 -0
  54. package/kits/base/sdk/multiplayerProtocol.d.ts +51 -0
  55. package/kits/base/sdk/multiplayerProtocol.js +5 -0
  56. package/kits/base/sdk/passes.d.ts +7 -0
  57. package/kits/base/sdk/passes.js +84 -0
  58. package/kits/base/sdk/portal.d.ts +7 -0
  59. package/kits/base/sdk/portal.js +35 -0
  60. package/kits/base/sdk/runtime.d.ts +62 -0
  61. package/kits/base/sdk/runtime.js +970 -0
  62. package/kits/base/sdk/saveQueue.d.ts +27 -0
  63. package/kits/base/sdk/saveQueue.js +205 -0
  64. package/kits/base/sdk/server/platformHandle.d.ts +25 -0
  65. package/kits/base/sdk/server/platformHandle.js +1 -0
  66. package/kits/base/sdk/server/wrapper.d.ts +28 -0
  67. package/kits/base/sdk/server/wrapper.js +109 -0
  68. package/kits/base/sdk/storage.d.ts +16 -0
  69. package/kits/base/sdk/storage.js +323 -0
  70. package/kits/base/sdk/time.d.ts +17 -0
  71. package/kits/base/sdk/time.js +120 -0
  72. package/kits/base/sdk/transport.d.ts +17 -0
  73. package/kits/base/sdk/transport.js +141 -0
  74. package/kits/base/sdk/types.d.ts +3 -0
  75. package/kits/base/sdk/types.js +1 -0
  76. package/kits/base/sdk/user.d.ts +10 -0
  77. package/kits/base/sdk/user.js +45 -0
  78. package/kits/multiplayer-2d/.prettierrc +5 -0
  79. package/kits/multiplayer-2d/CLAUDE.md +129 -0
  80. package/kits/multiplayer-2d/behaviors/Box.jsx +92 -0
  81. package/kits/multiplayer-2d/behaviors/Player.jsx +86 -0
  82. package/kits/multiplayer-2d/blueprints/crate.scene +13 -0
  83. package/kits/multiplayer-2d/blueprints/other-player.scene +13 -0
  84. package/kits/multiplayer-2d/blueprints/player.scene +15 -0
  85. package/kits/multiplayer-2d/blueprints/wall.scene +12 -0
  86. package/kits/multiplayer-2d/castle.json +39 -0
  87. package/kits/multiplayer-2d/code/client/avatars.js +79 -0
  88. package/kits/multiplayer-2d/code/client/poses.js +168 -0
  89. package/kits/multiplayer-2d/code/server/index.js +26 -0
  90. package/kits/multiplayer-2d/code/server/limits.js +99 -0
  91. package/kits/multiplayer-2d/code/server/ownership.js +177 -0
  92. package/kits/multiplayer-2d/code/server/players.js +127 -0
  93. package/kits/multiplayer-2d/code/server/sceneBodies.js +98 -0
  94. package/kits/multiplayer-2d/code/server/world.js +337 -0
  95. package/kits/multiplayer-2d/code/systems/multiplayer.js +424 -0
  96. package/kits/multiplayer-2d/eslint.config.js +21 -0
  97. package/kits/multiplayer-2d/fonts.generated.js +9 -0
  98. package/kits/multiplayer-2d/index.html +25 -0
  99. package/kits/multiplayer-2d/main.jsx +10 -0
  100. package/kits/multiplayer-2d/package-lock.json +351 -0
  101. package/kits/multiplayer-2d/package.json +30 -0
  102. package/kits/multiplayer-2d/scenes/main.scene +20 -0
  103. package/kits/multiplayer-2d/test/two-client-test.mjs +341 -0
  104. package/kits/multiplayer-2d/theme.style +4 -0
  105. package/kits/multiplayer-3d/.prettierrc +5 -0
  106. package/kits/multiplayer-3d/CLAUDE.md +215 -0
  107. package/kits/multiplayer-3d/blueprints/ball.scene +21 -0
  108. package/kits/multiplayer-3d/blueprints/other-player.scene +21 -0
  109. package/kits/multiplayer-3d/castle.json +43 -0
  110. package/kits/multiplayer-3d/code/client/avatars.js +136 -0
  111. package/kits/multiplayer-3d/code/client/nameTags.js +101 -0
  112. package/kits/multiplayer-3d/code/client/poses.js +220 -0
  113. package/kits/multiplayer-3d/code/server/index.js +23 -0
  114. package/kits/multiplayer-3d/code/server/limits.js +107 -0
  115. package/kits/multiplayer-3d/code/server/ownership.js +157 -0
  116. package/kits/multiplayer-3d/code/server/players.js +114 -0
  117. package/kits/multiplayer-3d/code/server/sceneBodies.js +88 -0
  118. package/kits/multiplayer-3d/code/server/world.js +306 -0
  119. package/kits/multiplayer-3d/code/systems/multiplayer.js +427 -0
  120. package/kits/multiplayer-3d/eslint.config.js +20 -0
  121. package/kits/multiplayer-3d/fonts.generated.js +9 -0
  122. package/kits/multiplayer-3d/index.html +22 -0
  123. package/kits/multiplayer-3d/main.jsx +9 -0
  124. package/kits/multiplayer-3d/package-lock.json +368 -0
  125. package/kits/multiplayer-3d/package.json +32 -0
  126. package/kits/multiplayer-3d/scenes/main.scene +409 -0
  127. package/kits/multiplayer-3d/theme.style +3 -0
  128. package/kits/physics-2d/CLAUDE.md +6 -0
  129. package/kits/physics-2d/castle.json +7 -1
  130. package/kits/physics-2d/editors/behaviorRegistry.js +5 -0
  131. package/kits/physics-2d/editors/editorRegistry.jsx +3 -1
  132. package/kits/physics-2d/engine/files.js +9 -5
  133. package/kits/physics-2d/engine/systemRegistry.js +2 -0
  134. package/kits/physics-2d/engine/ui.module.css +11 -0
  135. package/kits/physics-2d/package-lock.json +8 -2
  136. package/kits/physics-2d/package.json +2 -2
  137. package/kits/physics-3d/CLAUDE.md +4 -4
  138. package/kits/physics-3d/behaviors/Shape.jsx +1 -1
  139. package/kits/physics-3d/blueprints/crate.scene +1 -1
  140. package/kits/physics-3d/blueprints/door.scene +4 -4
  141. package/kits/physics-3d/blueprints/pillar.scene +1 -1
  142. package/kits/physics-3d/blueprints/platform.scene +1 -1
  143. package/kits/physics-3d/blueprints/statue.scene +1 -1
  144. package/kits/physics-3d/blueprints/wall.scene +1 -1
  145. package/kits/physics-3d/castle.json +8 -11
  146. package/kits/physics-3d/docs/pxmodel-format.md +1 -1
  147. package/kits/physics-3d/engine3d/materials.js +3 -3
  148. package/kits/physics-3d/engine3d/modelFiles.js +4 -2
  149. package/kits/physics-3d/engine3d/world3d.js +1 -1
  150. package/kits/physics-3d/fonts.generated.js +9 -0
  151. package/kits/physics-3d/main.jsx +1 -1
  152. package/kits/physics-3d/package-lock.json +85 -2
  153. package/kits/physics-3d/package.json +6 -2
  154. package/kits/physics-3d/scenes/main.scene +1 -1
  155. package/kits/physics-3d/scenes/model-lab.scene +1 -1
  156. package/kits/real-time/.prettierrc +5 -0
  157. package/kits/real-time/CLAUDE.md +60 -0
  158. package/kits/real-time/castle.json +19 -0
  159. package/kits/real-time/code/client/clock.js +68 -0
  160. package/kits/real-time/code/client/connection.js +134 -0
  161. package/kits/real-time/code/client/gameHooks.js +50 -0
  162. package/kits/real-time/code/client/interpolate.js +82 -0
  163. package/kits/real-time/code/client/messages.js +55 -0
  164. package/kits/real-time/code/client/ownership.js +94 -0
  165. package/kits/real-time/code/client/smooth.js +54 -0
  166. package/kits/real-time/code/server/blockDelta.js +48 -0
  167. package/kits/real-time/code/server/gameHooks.js +47 -0
  168. package/kits/real-time/code/server/limits.js +35 -0
  169. package/kits/real-time/code/server/session.js +251 -0
  170. package/kits/real-time/eslint.config.js +22 -0
  171. package/kits/real-time/index.html +45 -0
  172. package/kits/real-time/package.json +14 -0
  173. package/kits/{tabletop → turn-based}/CLAUDE.md +42 -49
  174. package/kits/turn-based/blueprints/board.scene +15 -0
  175. package/kits/turn-based/blueprints/square.scene +25 -0
  176. package/kits/turn-based/castle.json +37 -0
  177. package/kits/turn-based/code/behaviors/Board.jsx +169 -0
  178. package/kits/turn-based/code/behaviors/Square.jsx +26 -0
  179. package/kits/turn-based/code/server/index.js +152 -0
  180. package/kits/turn-based/drawings/square.sprite +25 -0
  181. package/kits/turn-based/eslint.config.js +12 -0
  182. package/kits/turn-based/fonts.generated.js +9 -0
  183. package/kits/{tabletop → turn-based}/index.html +5 -3
  184. package/kits/{tabletop → turn-based}/main.jsx +2 -2
  185. package/kits/{tabletop → turn-based}/package-lock.json +17 -4
  186. package/kits/{tabletop → turn-based}/package.json +5 -2
  187. package/kits/turn-based/room.js +289 -0
  188. package/kits/turn-based/scenes/main.scene +227 -0
  189. package/kits/{tabletop → turn-based}/testing.js +131 -99
  190. package/kits/turn-based/theme.style +3 -0
  191. package/package.json +1 -1
  192. package/kits/blank/CLAUDE.md +0 -198
  193. package/kits/tabletop/castle.json +0 -34
  194. package/kits/tabletop/room.js +0 -269
  195. /package/kits/{blank → base}/index.html +0 -0
  196. /package/kits/{blank → base}/node_modules/castle-web-fonts/README.md +0 -0
  197. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/catalog.d.ts +0 -0
  198. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/catalog.js +0 -0
  199. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/face.d.ts +0 -0
  200. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/face.js +0 -0
  201. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/Bore.d.ts +0 -0
  202. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/Bore.js +0 -0
  203. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/CourierPrime.d.ts +0 -0
  204. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/CourierPrime.js +0 -0
  205. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/DMSans.d.ts +0 -0
  206. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/DMSans.js +0 -0
  207. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/Glacier.d.ts +0 -0
  208. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/Glacier.js +0 -0
  209. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/HelicoCentrica.d.ts +0 -0
  210. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/HelicoCentrica.js +0 -0
  211. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/Piazzolla.d.ts +0 -0
  212. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/Piazzolla.js +0 -0
  213. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/Synco.d.ts +0 -0
  214. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/Synco.js +0 -0
  215. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/Tektur.d.ts +0 -0
  216. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/Tektur.js +0 -0
  217. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/YatraOne.d.ts +0 -0
  218. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/YatraOne.js +0 -0
  219. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/index.d.ts +0 -0
  220. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/index.js +0 -0
  221. /package/kits/{blank → base}/node_modules/castle-web-fonts/licenses/CC-BY-ND-4.0.txt +0 -0
  222. /package/kits/{blank → base}/node_modules/castle-web-fonts/licenses/FONTS.md +0 -0
  223. /package/kits/{blank → base}/node_modules/castle-web-fonts/licenses/OFL-1.1.txt +0 -0
  224. /package/kits/{blank → base}/node_modules/castle-web-fonts/package.json +0 -0
  225. /package/kits/{blank → base}/node_modules/castle-web-fonts/woff2/Bore.woff2 +0 -0
  226. /package/kits/{blank → base}/node_modules/castle-web-fonts/woff2/CourierPrime.woff2 +0 -0
  227. /package/kits/{blank → base}/node_modules/castle-web-fonts/woff2/DMSans.woff2 +0 -0
  228. /package/kits/{blank → base}/node_modules/castle-web-fonts/woff2/Glacier.woff2 +0 -0
  229. /package/kits/{blank → base}/node_modules/castle-web-fonts/woff2/HelicoCentrica.woff2 +0 -0
  230. /package/kits/{blank → base}/node_modules/castle-web-fonts/woff2/Piazzolla.woff2 +0 -0
  231. /package/kits/{blank → base}/node_modules/castle-web-fonts/woff2/SOURCE.txt +0 -0
  232. /package/kits/{blank → base}/node_modules/castle-web-fonts/woff2/Synco.woff2 +0 -0
  233. /package/kits/{blank → base}/node_modules/castle-web-fonts/woff2/Tektur.woff2 +0 -0
  234. /package/kits/{blank → base}/node_modules/castle-web-fonts/woff2/YatraOne.woff2 +0 -0
  235. /package/kits/physics-3d/drawings/{crate.pxart → crate.sprite} +0 -0
  236. /package/kits/physics-3d/drawings/{door-edge.pxart → door-edge.sprite} +0 -0
  237. /package/kits/physics-3d/drawings/{door.pxart → door.sprite} +0 -0
  238. /package/kits/physics-3d/drawings/{face.pxart → face.sprite} +0 -0
  239. /package/kits/physics-3d/drawings/{floor.pxart → floor.sprite} +0 -0
  240. /package/kits/physics-3d/drawings/{platform.pxart → platform.sprite} +0 -0
  241. /package/kits/physics-3d/drawings/{statue.pxart → statue.sprite} +0 -0
  242. /package/kits/physics-3d/drawings/{wall.pxart → wall.sprite} +0 -0
  243. /package/kits/{tabletop → turn-based}/.prettierrc +0 -0
@@ -0,0 +1,251 @@
1
+ // Dimension-independent Castle multiplayer session process. It builds the
2
+ // supplied world, routes reports, reconciles players and ownership around each
3
+ // tick, then sends world snapshots and state deltas.
4
+ //
5
+ // The dimensional half arrives as the `parts` modules given to `makeSession`.
6
+ // Poses stay opaque arrays here; every read of a pose's contents happens in the
7
+ // kit modules or through the callbacks the kit's pose codec exports.
8
+
9
+ import * as Messages from '../client/messages.js';
10
+
11
+ // Maximum wall-clock duration passed to physics for one session tick.
12
+ const MAX_TICK_SECONDS = 0.25;
13
+
14
+ // The state one session process keeps, beside the modules it was built with:
15
+ //
16
+ // label prefix for this process in log messages
17
+ // poses the kit's pose codec, for `PLAYER_GEOMETRY` and the
18
+ // per-index `epsilonAt` the delta comparison reads
19
+ // world createSimulation, step, objectPoses
20
+ // players addPlayer, removePlayer, setPose, playerPoses
21
+ // ownership claim, release, setObjectPoses, sweepOwners, ownerships
22
+ // game the deck's hooks, from `gameHooks.js`
23
+ // sim the simulation, null until it is built
24
+ // lastTickAt wall clock at the previous tick
25
+ // sent the last pose broadcast for each id, so a later tick can
26
+ // send only what changed
27
+ // waitingForWorld players who have joined but have not been sent the world
28
+ // handovers ownership changes since the last broadcast, as
29
+ // [objectId, playerId|0]
30
+ function newServer(parts) {
31
+ return {
32
+ ...parts,
33
+ sim: null,
34
+ lastTickAt: 0,
35
+ sent: { players: new Map(), objects: new Map() },
36
+ waitingForWorld: new Set(),
37
+ handovers: [],
38
+ };
39
+ }
40
+
41
+ // Build the handler object Castle loads from `castle.json.server.main`. A
42
+ // dimensional kit's `code/server/index.js` supplies its pose codec plus world,
43
+ // player, ownership, and deck-hook modules, then exports the returned object.
44
+ // Those modules read and update physics bodies; this core passes opaque poses
45
+ // and messages between them.
46
+ export function makeSession(parts) {
47
+ const server = newServer(parts);
48
+ buildWorld(server);
49
+ return {
50
+ // Joins are logged here; the simulation's players are reconciled from the
51
+ // full session roster on the next tick.
52
+ onPlayerJoin(session, player) {
53
+ console.log(`[${server.label}] join ${player.username} (${player.playerId})`);
54
+ },
55
+
56
+ onPlayerLeave(session, player) {
57
+ // The next roster reconciliation removes the simulation player and body.
58
+ console.log(`[${server.label}] leave ${player.username}`);
59
+ },
60
+
61
+ onMessage(session, player, data) {
62
+ receive(server, session, player, data);
63
+ },
64
+
65
+ onTick(session) {
66
+ tick(server, session);
67
+ },
68
+
69
+ onReplaced(session) {
70
+ // Tell the connected clients when Castle replaces this session process.
71
+ session.broadcast({ k: 'replaced' });
72
+ },
73
+ };
74
+ }
75
+
76
+ // Start building the simulation when the handler object is created. Castle's
77
+ // handlers remain available while `createSimulation` is pending.
78
+ function buildWorld(server) {
79
+ server.world.createSimulation().then(
80
+ (created) => {
81
+ server.sim = created;
82
+
83
+ // Invoke the deck's ready hook with the built world before the first tick.
84
+ server.game.ready?.(created);
85
+ console.log(`[${server.label}] simulation ready`);
86
+ },
87
+ (err) => console.error(`[${server.label}] simulation failed: ${err?.message ?? err}`),
88
+ );
89
+ }
90
+
91
+ // Route one client message. Movement reports update the simulation, and other
92
+ // message kinds go to the deck hook.
93
+ function receive(server, session, player, data) {
94
+ // Deck control messages can run before simulation initialization completes.
95
+ if (data?.k !== Messages.MOVE) {
96
+ server.game.message?.(session, player, data);
97
+ return;
98
+ }
99
+ if (!server.sim) {
100
+ return;
101
+ }
102
+
103
+ // The supplied player module validates the dimensional pose and movement
104
+ // limit before updating the shared simulation.
105
+ server.players.setPose(server.sim, player.playerId, data);
106
+
107
+ // Claims come before owned poses, so a grant in this message authorizes the
108
+ // pose that arrived with it. Releases come last, so they cannot cancel a claim
109
+ // from the same message before its pose is applied.
110
+ server.ownership.claim(server.sim, player.playerId, data.c, server.handovers);
111
+ server.ownership.setObjectPoses(server.sim, player.playerId, data.o, server.handovers);
112
+ server.ownership.release(server.sim, player.playerId, data.r, server.handovers);
113
+ }
114
+
115
+ // One session tick: reconcile players, sweep ownership, run the deck's hooks
116
+ // around physics, and send the join snapshots and the delta.
117
+ function tick(server, session) {
118
+ if (!server.sim) {
119
+ return;
120
+ }
121
+ reconcilePlayers(server, session);
122
+
123
+ // Objects held by a player who left or stopped reporting are released before
124
+ // any new claim is granted this tick.
125
+ server.ownership.sweepOwners(server.sim, server.handovers);
126
+
127
+ // `game.place` runs before the step, which is where a write that only reaches
128
+ // a body at the next step has to happen.
129
+ server.game.place?.(server.sim, server.handovers);
130
+ server.world.step(server.sim, elapsedSeconds(server));
131
+
132
+ // `game.step` sees completed physics and may append fields or handovers for
133
+ // this tick's broadcast.
134
+ server.game.step?.(server.sim, server.handovers);
135
+
136
+ // The supplied player and world modules pack their dimensional poses. The
137
+ // session stores and transmits the arrays without interpreting components.
138
+ const snapshot = {
139
+ t: Math.round(server.sim.timeMs),
140
+ ps: server.players.playerPoses(server.sim),
141
+ os: server.world.objectPoses(server.sim),
142
+ };
143
+
144
+ // A new player gets the whole world and the current ownerships. Sending the
145
+ // ownerships with that first snapshot stops the client from simulating an
146
+ // object somebody else already holds.
147
+ for (const playerId of server.waitingForWorld) {
148
+ session.send(playerId, {
149
+ k: Messages.WORLD,
150
+ ...snapshot,
151
+ own: server.ownership.ownerships(server.sim),
152
+ ...server.game.join?.(server.sim),
153
+ });
154
+ }
155
+ server.waitingForWorld.clear();
156
+ broadcastDelta(server, session, snapshot);
157
+ }
158
+
159
+ // Make the simulation's player map match Castle's roster. The roster covers the
160
+ // connection changes that do not arrive as a join or a leave.
161
+ function reconcilePlayers(server, session) {
162
+ const present = new Set(session.players.map((player) => player.playerId));
163
+ for (const playerId of present) {
164
+ if (server.sim.players.has(playerId)) {
165
+ continue;
166
+ }
167
+
168
+ // A newly observed roster id gets a body and a full WORLD on this tick.
169
+ server.players.addPlayer(server.sim, playerId);
170
+ server.waitingForWorld.add(playerId);
171
+ }
172
+ for (const playerId of [...server.sim.players.keys()]) {
173
+ if (present.has(playerId)) {
174
+ continue;
175
+ }
176
+ server.players.removePlayer(server.sim, playerId);
177
+
178
+ // Remove the delta baseline so a later return sends an initial player pose.
179
+ server.sent.players.delete(playerId);
180
+ }
181
+ }
182
+
183
+ // Broadcast what changed since the previous tick. A tick where nothing changed
184
+ // sends nothing at all.
185
+ function broadcastDelta(server, session, snapshot) {
186
+ // `playerChanged` records each accepted player pose as its next baseline.
187
+ const ps = snapshot.ps.filter((pose) => playerChanged(server, pose));
188
+
189
+ // Forget the sent pose of an object that is gone. A respawned object can reuse
190
+ // an id and pose, and the old baseline would suppress its first pose.
191
+ const alive = new Set(snapshot.os.map(([id]) => id));
192
+ for (const id of server.sent.objects.keys()) {
193
+ if (!alive.has(id)) {
194
+ server.sent.objects.delete(id);
195
+ }
196
+ }
197
+
198
+ // `changed` applies the same baseline update to each object pose.
199
+ const os = snapshot.os.filter(([id, ...pose]) => changed(server, server.sent.objects, id, pose));
200
+
201
+ // This broadcast consumes the accumulated handovers. Later reports append to
202
+ // a new list for the next broadcast.
203
+ const own = server.handovers;
204
+ server.handovers = [];
205
+
206
+ // A changed deck block is its own reason to broadcast, including on a tick
207
+ // where no pose and no ownership moved.
208
+ const block = server.game.delta?.(server.sim) ?? null;
209
+ if (ps.length === 0 && os.length === 0 && own.length === 0 && !block) {
210
+ return;
211
+ }
212
+ session.broadcast({ k: Messages.STATE, t: snapshot.t, ps, os, own, ...block });
213
+ }
214
+
215
+ // Whether one player's pose belongs in this delta, recording it as the new
216
+ // baseline when it does.
217
+ function playerChanged(server, [id, ...pose]) {
218
+ const geometry = server.poses.PLAYER_GEOMETRY;
219
+ const prior = server.sent.players.get(id);
220
+
221
+ // Compare only the geometry values. A set `clamped` flag requires a delta
222
+ // because the reporting client needs the server position even when the
223
+ // correction is smaller than the movement threshold.
224
+ if (
225
+ prior &&
226
+ !pose[geometry] &&
227
+ !Messages.poseChanged(prior, pose, geometry, server.poses.epsilonAt)
228
+ ) {
229
+ return false;
230
+ }
231
+ server.sent.players.set(id, pose);
232
+ return true;
233
+ }
234
+
235
+ // Whether an object's pose changed, recording it as the new baseline when it did.
236
+ function changed(server, seen, id, pose) {
237
+ if (!Messages.poseChanged(seen.get(id), pose, pose.length, server.poses.epsilonAt)) {
238
+ return false;
239
+ }
240
+ seen.set(id, pose);
241
+ return true;
242
+ }
243
+
244
+ // Return wall-clock seconds since the previous tick, capped before the duration
245
+ // is passed to the physics module.
246
+ function elapsedSeconds(server) {
247
+ const now = Date.now();
248
+ const elapsed = server.lastTickAt ? (now - server.lastTickAt) / 1000 : 0;
249
+ server.lastTickAt = now;
250
+ return Math.min(elapsed, MAX_TICK_SECONDS);
251
+ }
@@ -0,0 +1,22 @@
1
+ // ESLint scope and kit-specific rules. The first block excludes dependency and
2
+ // build directories; the second applies JavaScript parsing and required braces
3
+ // to the hand-written code modules.
4
+ export default [
5
+ // Keep imported, installed, generated, and runtime files outside lint checks.
6
+ {
7
+ ignores: ['node_modules/**', 'dist/**', '.castle/**', 'imports/**'],
8
+ },
9
+ // The `curly` rule supplies braces that Prettier leaves unchanged.
10
+ {
11
+ files: ['code/**/*.{js,jsx}'],
12
+ // Parse the client and server modules as modern ECMAScript modules.
13
+ languageOptions: {
14
+ ecmaVersion: 'latest',
15
+ sourceType: 'module',
16
+ },
17
+ // Require explicit blocks around every control-flow body.
18
+ rules: {
19
+ curly: ['error', 'all'],
20
+ },
21
+ },
22
+ ];
@@ -0,0 +1,45 @@
1
+ <!doctype html>
2
+ <!-- Static landing card for the shared real-time kit. The kit runs through its
3
+ importers, so this page identifies the library and its two consumers. -->
4
+ <html>
5
+ <head>
6
+ <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no" />
7
+ <meta name="color-scheme" content="dark" />
8
+ <title>real-time kit</title>
9
+ <style>
10
+ html {
11
+ color-scheme: dark;
12
+ background: #0a0a0a;
13
+ }
14
+ body {
15
+ margin: 0;
16
+ height: 100vh;
17
+ display: flex;
18
+ flex-direction: column;
19
+ align-items: center;
20
+ justify-content: center;
21
+ gap: 12px;
22
+ font-family: system-ui, sans-serif;
23
+ color: #fff;
24
+ text-align: center;
25
+ padding: 24px;
26
+ box-sizing: border-box;
27
+ }
28
+ p {
29
+ margin: 0;
30
+ max-width: 24em;
31
+ color: #999;
32
+ font-size: 15px;
33
+ line-height: 1.5;
34
+ }
35
+ </style>
36
+ </head>
37
+ <body>
38
+ <h1>real-time</h1>
39
+ <p>
40
+ The wire, the clock, the interpolation and the session process shared by the
41
+ <code>multiplayer-2d</code> and <code>multiplayer-3d</code> kits. A library: there is no scene
42
+ and nothing to play here.
43
+ </p>
44
+ </body>
45
+ </html>
@@ -0,0 +1,14 @@
1
+ {
2
+ "name": "real-time",
3
+ "private": true,
4
+ "type": "module",
5
+ "scripts": {
6
+ "check": "eslint . && node --input-type=module -e \"const { bundleProject } = await import('../../cli/dist/bundle.js'); await bundleProject('.');\"",
7
+ "format": "prettier --write \"code/**/*.js\" castle.json package.json"
8
+ },
9
+ "devDependencies": {
10
+ "castle-web-sdk": "file:../../sdk",
11
+ "eslint": "^9.0.0",
12
+ "prettier": "^3.8.3"
13
+ }
14
+ }
@@ -1,4 +1,4 @@
1
- # tabletop kit
1
+ # turn-based kit
2
2
 
3
3
  The **room** a board game is played in, for decks whose server is authoritative:
4
4
  seats, spectators, reconnect, and when state left in a session stops belonging to
@@ -21,19 +21,20 @@ code:
21
21
 
22
22
  - Server-side room bookkeeping for board games, over the physics-2d kit. The
23
23
  deck's `server/index.js` builds one room and delegates arrivals and departures
24
- to it: `createRoom({ seats, createState, idleMs, graceMs })` from
25
- `@imports/castle.tabletop/room.js`.
26
- - `room.join(session, player)` -> `{ table, seat, returning, cleared }`, and
27
- `room.leave(session, player)` -> `{ table, seat, promoted }`. One table per
28
- `session.sessionId`, made on demand.
29
- - The table holds the deck's own game at `table.game` (whatever `createState`
30
- returned) plus `seatOf(playerId)`, `holder(seat)`, `names()`, `occupied()`,
31
- `watching(session)`, `touch()`, `newRound()`, `rotate()`.
32
- - `table.touch()` stamps the idle clock and must be called ONLY past every
24
+ to it: `createRoom({ seats, idleMs, graceMs })` from
25
+ `@imports/castle.turn-based/room.js`.
26
+ - `room.join(session, player)` and `room.leave(session, player)` both return
27
+ `{ table }`. One table per `session.sessionId`, made on demand.
28
+ - **The deck owns its game.** `table.game` starts null and a clear puts it back
29
+ to null, so the deck's join handler is `if (!table.game) { table.game = ... }`.
30
+ The kit never builds or reads it.
31
+ - The table also carries `seatOf(playerId)`, `playerAt(seat)`, `seatNames()`,
32
+ `spectatorCount(session)` and `keepAlive()`.
33
+ - `table.keepAlive()` stamps the idle clock and must be called ONLY past every
33
34
  rejection -- a refused message is not a sign of life.
34
35
  - **A leave never clears the game.** The kit releases the seat, remembers the
35
36
  departure for `graceMs`, and promotes a watcher. Clearing only ever happens on
36
- a join. There is no path from `leave` to `createState`.
37
+ a join. There is no path from `leave` to a cleared table.
37
38
  - Clearing rules, all inside `room.join`: never in a `party` session; never for a
38
39
  player returning inside the grace window; always for someone arriving alone;
39
40
  never while `minPlayers` seats are held by people who are present; otherwise
@@ -43,8 +44,8 @@ code:
43
44
  hand of cards, a hidden role -- must be keyed by the `playerId` it was dealt
44
45
  to, never by the seat id.
45
46
  - Test it with `checkRoom({...})` and `createSessionHarness(server)` from
46
- `@imports/castle.tabletop/testing.js`, run from the deck dir as
47
- `node --import ./imports/castle.tabletop/testing.js tools/check.mjs` -- that
47
+ `@imports/castle.turn-based/testing.js`, run from the deck dir as
48
+ `node --import ./imports/castle.turn-based/testing.js tools/check.mjs` -- that
48
49
  `--import` is what makes `@imports/` resolve under plain node.
49
50
  - Deliberately NOT here: the solo fallback, the message envelope, any HUD, fonts
50
51
  and other assets, and every game rule.
@@ -57,18 +58,25 @@ therefore decides only bookkeeping -- seats, spectators, departures, session
57
58
  freshness. Every number, every rule and every message is the deck's.
58
59
 
59
60
  ```js
60
- import { createRoom } from '@imports/castle.tabletop/room.js';
61
+ import * as Room from '@imports/castle.turn-based/room.js';
61
62
 
62
- const room = createRoom({
63
+ const room = Room.createRoom({
63
64
  seats: ['X', 'O'],
64
- createState: () => ({ board: Array(9).fill(null), turn: 'X', winner: null }),
65
65
  idleMs: 3 * 60 * 1000,
66
66
  graceMs: 45 * 1000,
67
67
  });
68
68
 
69
+ function freshGame() {
70
+ return { board: Array(9).fill(null), turn: 'X', winner: null };
71
+ }
72
+
69
73
  export default {
70
74
  onPlayerJoin(session, player) {
71
- push(session, room.join(session, player).table);
75
+ const { table } = room.join(session, player);
76
+ if (!table.game) {
77
+ table.game = freshGame();
78
+ }
79
+ push(session, table);
72
80
  },
73
81
  onPlayerLeave(session, player) {
74
82
  push(session, room.leave(session, player).table);
@@ -76,7 +84,7 @@ export default {
76
84
  onMessage(session, player, data) {
77
85
  const table = room.table(session);
78
86
  // ... validate against table.seatOf(player.playerId) and table.game,
79
- // then table.touch() only once the move is accepted.
87
+ // then table.keepAlive() only once the move is accepted.
80
88
  },
81
89
  };
82
90
  ```
@@ -86,8 +94,6 @@ export default {
86
94
  ### `createRoom(config)`
87
95
 
88
96
  - `seats` -- seat ids, in the order they are handed out. Required.
89
- - `createState` -- `() => any`, a fresh game. Required. The kit stores what it
90
- returns at `table.game` and otherwise never reads or writes it.
91
97
  - `idleMs` -- how long an untended table may sit before an arriving player is
92
98
  handed a clean one instead. Required. The three decks this came from chose
93
99
  3, 3 and 10 minutes: configuration, not disagreement.
@@ -96,42 +102,29 @@ export default {
96
102
  - `minPlayers` -- how many seats held by PRESENT players protect the table from a
97
103
  join-side clear. Default: every seat. A game that runs short-handed (a card
98
104
  game with a minimum of 2 at a 6-seat table) sets it.
99
- - `displayName` -- `(player) => string`. Default: `username`, else `'guest'` for
100
- an anonymous player, else `'player'`.
101
- - `now` -- `() => ms`, if the deck wants its own clock. Leave it alone unless you
102
- have a reason; the kit's clock is the one `testing.js` can move.
103
105
 
104
106
  ### `room`
105
107
 
106
108
  - `room.table(session)` -- the table for this session, made if new.
107
- - `room.join(session, player)` -> `{ table, seat, returning, cleared }`. `seat`
108
- is `null` for a spectator: everyone past the last seat watches.
109
- - `room.leave(session, player)` -> `{ table, seat, promoted }` -- the seat freed
110
- (null if the leaver was watching) and the playerIds moved up into seats.
111
- - `room.forget(session)` -- drop a session's table. Only for a host that reuses a
112
- `sessionId`.
109
+ - `room.join(session, player)` -> `{ table }`. Everyone past the last seat
110
+ watches.
111
+ - `room.leave(session, player)` -> `{ table }`.
113
112
 
114
113
  ### `table`
115
114
 
116
- - `table.game` -- the deck's game. Mutate it freely; the kit replaces it
117
- wholesale on a clear or a `newRound()`.
115
+ - `table.game` -- the deck's game, and the deck's to build. Null until the deck
116
+ makes one, and null again after a clear.
118
117
  - `table.seatOf(playerId)` -- seat id, or `null`. The ONLY thing that should
119
118
  decide whether a message may move anything. Identity comes from
120
119
  `player.playerId` / `player.userId`, never from a message body.
121
- - `table.holder(seat)` -> `{ playerId, userId, name } | null`. Null the moment
120
+ - `table.playerAt(seat)` -> `{ playerId, userId, name } | null`. Null the moment
122
121
  the holder drops. The departure record behind it is pruned at `graceMs`, so a
123
122
  deck that has to keep showing a departed player's name for the length of a hand
124
123
  copies the name into its own state when it deals.
125
- - `table.names()` -> `{ [seat]: name | null }`, ready to send.
126
- - `table.occupied()` -- seats with a holder.
127
- - `table.watching(session)` -- people in the session holding no seat.
128
- - `table.touch()` -- stamp the idle clock. **Past every rejection, never before
129
- one.**
130
- - `table.newRound()` -- fresh game, same seats, clock restarted.
131
- - `table.rotate()` -- shift every holder one seat BACKWARDS along the declared
132
- order, so a series alternates who plays what. Chess swaps colours with this; a
133
- card game moves the dealer. It turns the whole ring rather than compacting it:
134
- an empty seat rotates along with the held ones.
124
+ - `table.seatNames()` -> `{ [seat]: name | null }`, ready to send.
125
+ - `table.spectatorCount(session)` -- people in the session holding no seat.
126
+ - `table.keepAlive()` -- stamp the idle clock. **Past every rejection, never
127
+ before one.** A rematch is the deck's own `table.game = fresh()` plus this.
135
128
  - `table.lastActivityAt`, `table.sessionId`, `table.seats`, `table.departed` are
136
129
  readable for a status line or a test.
137
130
 
@@ -199,7 +192,7 @@ is no runner. Run it from the deck directory, with the kit's `testing.js` as the
199
192
  `--import`, so `@imports/` means the same thing in a test as it does in the deck:
200
193
 
201
194
  ```sh
202
- node --import ./imports/castle.tabletop/testing.js tools/check.mjs
195
+ node --import ./imports/castle.turn-based/testing.js tools/check.mjs
203
196
  ```
204
197
 
205
198
  Put that in the deck's `package.json` as a `check` script. Without it `node` has
@@ -208,7 +201,7 @@ exist to check.
208
201
 
209
202
  ```js
210
203
  import server from '../server/index.js';
211
- import { checkRoom, printRoomChecks } from '@imports/castle.tabletop/testing.js';
204
+ import { checkRoom, printRoomChecks } from '@imports/castle.turn-based/testing.js';
212
205
 
213
206
  process.exit(
214
207
  printRoomChecks(
@@ -268,7 +261,7 @@ message(player, data), sent(playerId), last(playerId, match?), outbox }`. It
268
261
  uninstall() }`. `install()` points the kit's clock at it.
269
262
 
270
263
  It is not a transport. A two-client game over a real `castle-web serve` is still
271
- the thing that proves a deck -- `tic-tac-toe-tabletop/tools/live.mjs` is a
264
+ the thing that proves a deck -- `tic-tac-toe/tools/live.mjs` is a
272
265
  dependency-free one to copy. It needs the serve on **loopback** and to itself: a
273
266
  socket with no browser Origin is admitted from nowhere else, and a browser tab
274
267
  already on that serve holds a seat the suite expects to be free.
@@ -288,15 +281,15 @@ already on that serve holds a seat the suite expects to be free.
288
281
 
289
282
  ```sh
290
283
  castle-web init <dir> --kit physics-2d
291
- castle-web add-import <tabletop deckId> <dir> --as castle.tabletop
284
+ castle-web add-import <turn-based deckId> <dir> --as castle.turn-based
292
285
  ```
293
286
 
294
- `--as castle.tabletop` matters: the alias is the path every `@imports/...`
287
+ `--as castle.turn-based` matters: the alias is the path every `@imports/...`
295
288
  specifier is written against, and it is never re-derived from the upstream deck
296
289
  name. `castle.physics-2d` comes along with it -- transitive imports are flattened
297
290
  into one `imports/` at the deck root.
298
291
 
299
- Then point `index.html` at `/imports/castle.tabletop/main.jsx` (physics-2d's
292
+ Then point `index.html` at `/imports/castle.turn-based/main.jsx` (physics-2d's
300
293
  entry, re-exported so a deck imports one kit and not two), and set `server.main`
301
294
  in `castle.json`.
302
295
 
@@ -0,0 +1,15 @@
1
+ {
2
+ "name": "Board",
3
+ "actors": [
4
+ {
5
+ "components": {
6
+ "Layout": {
7
+ "width": 500,
8
+ "height": 700,
9
+ "z": 10
10
+ },
11
+ "Board": {}
12
+ }
13
+ }
14
+ ]
15
+ }
@@ -0,0 +1,25 @@
1
+ {
2
+ "name": "Square",
3
+ "actors": [
4
+ {
5
+ "components": {
6
+ "Layout": {
7
+ "width": 96,
8
+ "height": 96
9
+ },
10
+ "Sprite": {
11
+ "file": "drawings/square.sprite"
12
+ },
13
+ "Collider": {
14
+ "kind": "solid",
15
+ "mode": "manual",
16
+ "width": 96,
17
+ "height": 96
18
+ },
19
+ "Square": {
20
+ "index": 0
21
+ }
22
+ }
23
+ }
24
+ ]
25
+ }
@@ -0,0 +1,37 @@
1
+ {
2
+ "title": "turn-based",
3
+ "editor": {
4
+ "hiddenPaths": [],
5
+ "visiblePaths": [
6
+ "code/**",
7
+ "room.js",
8
+ "testing.js",
9
+ "scenes/**",
10
+ "blueprints/**",
11
+ "drawings/**",
12
+ "theme.style",
13
+ "fonts.generated.js"
14
+ ],
15
+ "defaultPlayFile": "scenes/main.scene"
16
+ },
17
+ "imports": {
18
+ "castle.physics-2d": {
19
+ "deckId": "ckRZGFW4iPrx",
20
+ "version": "2026-08-31T02:59:16.016Z"
21
+ },
22
+ "castle.base": {
23
+ "deckId": "yRcmH4_aYllE",
24
+ "version": "2026-09-01T01:02:34.326Z"
25
+ }
26
+ },
27
+ "main": "main.jsx",
28
+ "autoUpdateWhenImported": true,
29
+ "deckId": "K6-Xs7dCoMVi",
30
+ "cardId": "Kh_08IYATpC3",
31
+ "publishedVersion": "2026-09-02T03:33:55.506Z",
32
+ "server": {
33
+ "main": "code/server/index.js",
34
+ "maxPlayers": 8,
35
+ "tickRate": 0
36
+ }
37
+ }