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,50 @@
1
+ // Discovery of the optional deck hooks a client system calls. The module first
2
+ // searches the supported deck paths, then exports the selected hook object.
3
+ const modules = {
4
+ // Eager globs allow either deck module to be absent without a build error.
5
+ // Root paths select the served deck when this module lives inside an import.
6
+ // A relative path from that imported copy would resolve inside the kit.
7
+ // Decks that keep client hooks at the top-level client directory use this path.
8
+ ...import.meta.glob('/client/game.js', { eager: true }),
9
+
10
+ // The standard code/client location.
11
+ ...import.meta.glob('/code/client/game.js', { eager: true }),
12
+ };
13
+
14
+ // The selected hook object, or an empty object when the deck defines no client
15
+ // hooks. Call sites invoke each hook optionally, so a deck writes only the ones
16
+ // it needs:
17
+ //
18
+ // The 2D and 3D multiplayer systems import this value and call the hooks at the
19
+ // stages listed below.
20
+ //
21
+ // message(scene, msg, system) a message that is neither STATE nor WORLD,
22
+ // after the queue is drained
23
+ // state(scene, msg, system) a STATE or WORLD message, after the kit has
24
+ // filed its poses and handovers; for the fields
25
+ // the deck's own server added to it
26
+ // claimable(scene, system) which objects ownership is decided over, as
27
+ // [actorId, point]. Default: everything the
28
+ // server puts in object snapshots. The same list
29
+ // supplies owned-object reports
30
+ // avatar(playerId, name, sys) `{ blueprint, username }` for one other
31
+ // player, or null to leave it undrawn. The
32
+ // default uses the deck's other-player
33
+ // blueprint and the roster name
34
+ // beforeReport(scene, local, s) after local physics, before the local pose is
35
+ // collected
36
+ // report(scene, local, system) replaces claims, releases and pose reporting
37
+ // for one frame
38
+ // afterFrame(scene, dt, system) after reporting
39
+ // presence(status) the presence text a kit HUD shows
40
+ // reset(scene, system) a scene load, after spawned actors are gone
41
+ // and while the connection is still open
42
+ // dispose(scene, system) runtime disposal, before reset and close
43
+ export const game = pick(modules)?.default ?? {};
44
+
45
+ // Selection uses the final glob entry, which gives the deck file precedence over
46
+ // a module contributed by an import.
47
+ function pick(modules) {
48
+ const keys = Object.keys(modules);
49
+ return keys.length ? modules[keys[keys.length - 1]] : null;
50
+ }
@@ -0,0 +1,82 @@
1
+ // Timestamped pose histories. A track stores poses under the server simulation
2
+ // times they describe, and sampling blends the two poses either side of a
3
+ // requested time.
4
+ //
5
+ // A pose is an opaque array of numbers whose format belongs to the dimensional
6
+ // kit. The kit's `code/client/poses.js` supplies the `same` and `blend`
7
+ // arguments, so this module never reads a pose's components.
8
+
9
+ // A track is `{ samples: [{ simMs, pose }] }`, oldest first. Trimming keeps the
10
+ // recent window while retaining at least two samples.
11
+ const HISTORY_MS = 1000;
12
+
13
+ // Create an empty, time-ordered pose history for one player or scene object.
14
+ export function makeTrack() {
15
+ return { samples: [] };
16
+ }
17
+
18
+ // Add one pose under the simulation time it describes. The client system calls
19
+ // this once per pose in each drained state message, passing the message's `t`.
20
+ // Simulation time advances in whole physics steps, so adjacent timestamps
21
+ // record the exact interval between two poses without arrival jitter.
22
+ //
23
+ // This module stores each pose without reading or copying it. The caller supplies
24
+ // `same` for its pose format and must stop mutating a pose after this call.
25
+ export function pushSample(track, simMs, pose, same) {
26
+ const last = track.samples[track.samples.length - 1];
27
+
28
+ // Timestamps stay strictly increasing. A reordered or duplicate sample carries
29
+ // no usable interval after the newest one already accepted.
30
+ if (last && simMs <= last.simMs) {
31
+ return;
32
+ }
33
+
34
+ // A pose reported at 20 Hz and broadcast at 30 Hz repeats on about a third of
35
+ // broadcasts. Keeping the repeat would make a stationary span followed by a
36
+ // larger jump, so the first timestamp is the one retained.
37
+ if (last && same(last.pose, pose)) {
38
+ return;
39
+ }
40
+
41
+ track.samples.push({ simMs, pose });
42
+
43
+ // Two samples are always kept, however old, so something that stopped moving
44
+ // can still be placed.
45
+ while (track.samples.length > 2 && track.samples[0].simMs < simMs - HISTORY_MS) {
46
+ track.samples.shift();
47
+ }
48
+ }
49
+
50
+ // Return the pose at `simMs`, blending the samples immediately before and after
51
+ // it. `clock.js` supplies the delayed simulation time, and the caller supplies
52
+ // `blend` for the pose format stored in the track.
53
+ //
54
+ // Callers must treat the returned pose as read-only. Times outside the recorded
55
+ // interval return a pose array held directly by the track.
56
+ export function sampleAt(track, simMs, blend) {
57
+ const samples = track.samples;
58
+
59
+ // An empty track has no network pose for the caller to draw.
60
+ if (samples.length === 0) {
61
+ return null;
62
+ }
63
+
64
+ // Times before the history use the oldest sample. Sampling is bounded to the
65
+ // recorded range rather than extrapolating network motion.
66
+ if (simMs <= samples[0].simMs) {
67
+ return samples[0].pose;
68
+ }
69
+
70
+ // Newest first, since the moment being drawn is usually near the end.
71
+ for (let i = samples.length - 1; i > 0; i -= 1) {
72
+ const before = samples[i - 1];
73
+ const after = samples[i];
74
+ if (before.simMs <= simMs && simMs <= after.simMs) {
75
+ const span = after.simMs - before.simMs;
76
+ return blend(before.pose, after.pose, span > 0 ? (simMs - before.simMs) / span : 1);
77
+ }
78
+ }
79
+
80
+ // Times after the history use the newest sample.
81
+ return samples[samples.length - 1].pose;
82
+ }
@@ -0,0 +1,55 @@
1
+ // Wire constants and pose-independent helpers. Message kinds and the report
2
+ // rate come first, followed by change detection and numeric rounding.
3
+
4
+ // Message kinds. `i` carries one client's own pose and the poses of the objects
5
+ // it has been granted. The connection supplies sender identity, so the payload
6
+ // holds no player-chosen id.
7
+ //
8
+ // `w` is the whole world, sent once after a join. Later `s` messages carry only
9
+ // what changed during a server tick.
10
+ //
11
+ // Both `w` and `s` carry `t`, the simulation's own clock in milliseconds. It
12
+ // advances by whole physics steps, so `t` says exactly how far apart two samples
13
+ // are, whatever the network did to them on the way.
14
+ export const MOVE = 'i';
15
+ export const WORLD = 'w';
16
+ export const STATE = 's';
17
+
18
+ // Movement reports run below the render rate and below the platform's roughly
19
+ // 30-message-per-second client cap. A second report inside one server tick would
20
+ // be overwritten before the simulation read it.
21
+ export const MOVE_HZ = 20;
22
+
23
+ // The default difference that counts as movement, for a kit whose pose values
24
+ // are all the same unit.
25
+ const EPSILON = 0.002;
26
+
27
+ // Report whether a pose differs enough to belong in a state delta. The server
28
+ // session calls this against the last pose it broadcast for each id.
29
+ //
30
+ // Poses are flat numeric arrays whose indices are defined by the calling kit.
31
+ // `count` stops the comparison short of the end. A kit passes the number of
32
+ // leading geometry values, so a flag beside them is not itself a reason to send.
33
+ // `epsilonAt` returns the difference that counts as movement at one index, since a
34
+ // pose can contain units such as pixels and radians in the same array.
35
+ export function poseChanged(before, after, count = after.length, epsilonAt = () => EPSILON) {
36
+ // The first pose establishes the baseline and must be included in the delta.
37
+ if (!before) {
38
+ return true;
39
+ }
40
+ for (let i = 0; i < count; i += 1) {
41
+ if (Math.abs(before[i] - after[i]) > epsilonAt(i)) {
42
+ return true;
43
+ }
44
+ }
45
+ return false;
46
+ }
47
+
48
+ // Round a wire value to `places` decimals. Null and undefined inputs use zero.
49
+ // The kit pose codecs run every packed value through this; reduced precision
50
+ // removes engine floating-point noise before payload creation and change
51
+ // comparison.
52
+ export function rounded(value, places) {
53
+ const scale = 10 ** places;
54
+ return Math.round((value ?? 0) * scale) / scale;
55
+ }
@@ -0,0 +1,94 @@
1
+ // Client-side ownership of the loose objects in the world. This module applies
2
+ // the handovers the server grants and produces claim and release lists from how
3
+ // close the local character is.
4
+ //
5
+ // The point format and distance metric belong to the dimensional kit: its pose
6
+ // codec exports `REACH`, which the client system passes here as `reach`. The
7
+ // ids that `toClaim` and `toRelease` return go out in the next `sendMove`.
8
+
9
+ // A claim is one id in the next rate-limited movement message, and the grant
10
+ // takes a round trip. A repeat every 120 ms resends a pending request without
11
+ // adding the id on every render frame.
12
+ const ASK_EVERY_MS = 120;
13
+
14
+ // Create the ownership state one client system keeps. A scene load replaces it,
15
+ // because actor ids belong to the loaded scene.
16
+ export function makeOwnership() {
17
+ return {
18
+ mine: new Set(), // object ids the server has granted this player
19
+ asked: new Map(), // id -> when it was last asked for, to space the asks out
20
+ };
21
+ }
22
+
23
+ // Apply a server handover list. A grant adds the id to `mine`; any other owner
24
+ // removes it, so this client stops simulating that object on the same frame.
25
+ export function applyHandovers(own, handovers, selfId) {
26
+ for (const [id, playerId] of handovers ?? []) {
27
+ if (playerId === selfId) {
28
+ own.mine.add(id);
29
+ } else {
30
+ own.mine.delete(id);
31
+ }
32
+ }
33
+ }
34
+
35
+ // Claim requests for objects in reach whose nearest character is the local one.
36
+ // `objects` is `[id, point]` pairs; `me` and `others` are character points.
37
+ // `reach.radius` sets the maximum distance, and `reach.distanceBetween` defines
38
+ // the point representation and metric for the calling dimensional kit.
39
+ export function toClaim(own, objects, me, others, now, reach) {
40
+ const ids = [];
41
+
42
+ // Reach cannot be measured until the local character has a position.
43
+ if (!me) {
44
+ return ids;
45
+ }
46
+ for (const [id, at] of objects) {
47
+ if (own.mine.has(id)) {
48
+ continue;
49
+ }
50
+
51
+ // Space repeated requests while the previous claim completes its round trip.
52
+ if (now - (own.asked.get(id) ?? -Infinity) < ASK_EVERY_MS) {
53
+ continue;
54
+ }
55
+ const distance = reach.distanceBetween(me, at);
56
+ if (distance > reach.radius) {
57
+ continue;
58
+ }
59
+
60
+ // Asking only when this client is closest stops two players either side of
61
+ // an object from taking it from each other every tick.
62
+ if (others.some((other) => reach.distanceBetween(other, at) < distance)) {
63
+ continue;
64
+ }
65
+
66
+ // Store the time so the next render frame does not repeat this request.
67
+ own.asked.set(id, now);
68
+ ids.push(id);
69
+ }
70
+ return ids;
71
+ }
72
+
73
+ // Return owned objects that have moved out of reach and remove them from `mine`.
74
+ // The connection includes these ids in the next rate-limited movement report.
75
+ export function toRelease(own, objects, me, reach) {
76
+ const ids = [];
77
+ for (const [id, at] of objects) {
78
+ if (!own.mine.has(id)) {
79
+ continue;
80
+ }
81
+
82
+ // Ownership is kept while the object is still in reach, including while it
83
+ // is standing still. Releasing it there would hand placement back to the
84
+ // network until the next claim and break a push in the middle.
85
+ if (me && reach.distanceBetween(me, at) <= reach.radius) {
86
+ continue;
87
+ }
88
+
89
+ // Stop local simulation as soon as the release is queued for the server.
90
+ ids.push(id);
91
+ own.mine.delete(id);
92
+ }
93
+ return ids;
94
+ }
@@ -0,0 +1,54 @@
1
+ // Exponential smoothing between the interpolated network pose and the pose that
2
+ // is drawn. Each id keeps its last displayed pose; `smooth` advances it and
3
+ // `forget` drops it.
4
+ //
5
+ // The client system calls `smooth` on every sampled pose it is about to draw,
6
+ // passing its kit's pose codec (`code/client/poses.js`) as `poses` for the
7
+ // `far` and `advance` callbacks.
8
+
9
+ // About 37 percent of a gap remains after 55 ms at this rate. Small one-tick
10
+ // gaps converge over several frames with limited added delay.
11
+ const RATE = 18;
12
+
13
+ // Create the per-id store of displayed poses for one runtime.
14
+ export function makeSmoothing() {
15
+ return new Map(); // id -> the pose actually being drawn
16
+ }
17
+
18
+ // The pose to draw for `id` this frame, advanced from the previous displayed
19
+ // pose toward the interpolated target. The returned array is the store's own
20
+ // pose, or `target` itself on a snap; callers must not keep or mutate it.
21
+ //
22
+ // The pose remains opaque to this module. The caller supplies `poses.far` to
23
+ // identify corrections outside its smoothing range and `poses.advance` to
24
+ // update the displayed pose in its dimensional format.
25
+ export function smooth(store, id, target, dt, poses) {
26
+ const shown = store.get(id);
27
+
28
+ // Other players and their objects report at 20 Hz and broadcast at 30 Hz. Late
29
+ // delivery or a tick with no new pose can leave a small step after timestamp
30
+ // interpolation, which this second stage spreads over several frames.
31
+
32
+ // A new id, a changed pose format, or a correction that `poses.far` classifies
33
+ // outside the smoothing range starts directly at the target.
34
+ if (!shown || shown.length !== target.length || poses.far(shown, target)) {
35
+ // Store a copy because later calls mutate the displayed pose in place.
36
+ store.set(id, target.slice());
37
+ return target;
38
+ }
39
+
40
+ // The closed fraction comes from `dt`, so the follow rate is the same whether
41
+ // the engine is drawing 30 or 120 frames a second.
42
+ const f = 1 - Math.exp(-RATE * Math.max(0, dt));
43
+
44
+ // `poses.advance` must mutate `shown` in place; its return value is ignored.
45
+ poses.advance(shown, target, f);
46
+ return shown;
47
+ }
48
+
49
+ // Drop one displayed pose. The next `smooth` starts from its target. Called when
50
+ // a player leaves, or when this client claims an object it had been drawing from
51
+ // network samples.
52
+ export function forget(store, id) {
53
+ store.delete(id);
54
+ }
@@ -0,0 +1,48 @@
1
+ // Change latches for values returned by a deck's `game.delta(sim)` hook. Both
2
+ // helpers store the last accepted value on the deck's own simulation state and
3
+ // report whether the current value belongs in the next broadcast.
4
+ //
5
+ // Deck server hooks import these helpers directly; no kit module calls them.
6
+
7
+ // Return `block` when its JSON differs from the last returned block, or null for
8
+ // an unchanged block. The helper stores the JSON string in `holder.sent`.
9
+ //
10
+ // `holder` is normally the deck state created by `game.ready(sim)`. Replacing
11
+ // that state for a new round also resets this latch. A deck property already
12
+ // named `sent` will be overwritten by this helper.
13
+ //
14
+ // The original block is returned so the session can spread its fields directly
15
+ // into a STATE message. The latch updates only when that block changes.
16
+ export function blockDelta(holder, block) {
17
+ // Serialize the content because a hook may allocate a new object with the
18
+ // same serialized fields on every tick.
19
+ const key = JSON.stringify(block);
20
+ if (key === holder.sent) {
21
+ return null;
22
+ }
23
+
24
+ // Advance the baseline only when this block will be returned for broadcast.
25
+ holder.sent = key;
26
+ return block;
27
+ }
28
+
29
+ // Return whether one numeric value differs from its previous accepted value by
30
+ // more than `epsilon`. The first call for a field always returns true.
31
+ //
32
+ // Physics values often differ by a small amount every tick, which makes an exact
33
+ // JSON comparison broadcast continuously. This helper stores the accepted value
34
+ // in `holder[field]` and ignores smaller changes. A same-named deck property will
35
+ // be overwritten.
36
+ export function movedBy(holder, field, value, epsilon) {
37
+ const prior = holder[field];
38
+
39
+ // Compare with the last accepted value. Ignored movement therefore
40
+ // accumulates until its total difference exceeds `epsilon`.
41
+ if (prior !== undefined && Math.abs(value - prior) <= epsilon) {
42
+ return false;
43
+ }
44
+
45
+ // A missing baseline and a large enough difference both accept this value.
46
+ holder[field] = value;
47
+ return true;
48
+ }
@@ -0,0 +1,47 @@
1
+ // Discovery of optional deck server modules. Lifecycle hooks are selected first,
2
+ // followed by server-side component defaults for scene construction.
3
+ const modules = {
4
+ // Eager globs allow either hook path to be absent without a build error.
5
+ // Root paths select the served deck while this module lives under `imports/`.
6
+ // A relative path from that imported copy would resolve inside the kit.
7
+ ...import.meta.glob('/server/game.js', { eager: true }),
8
+ ...import.meta.glob('/code/server/game.js', { eager: true }),
9
+ };
10
+
11
+ // Deck component defaults support the same root and `code/` layouts as hooks.
12
+ // Their eager globs also allow both modules to be absent.
13
+ const bodyModules = {
14
+ ...import.meta.glob('/server/deckComponents.js', { eager: true }),
15
+ ...import.meta.glob('/code/server/deckComponents.js', { eager: true }),
16
+ };
17
+
18
+ // The selected hook object, or an empty object when the deck defines no server
19
+ // hooks. Call sites invoke each hook optionally:
20
+ //
21
+ // `session.js` receives this value from the dimensional kit's server entry and
22
+ // calls the hooks at the stages listed below.
23
+ //
24
+ // ready(sim) after the world and its scene bodies exist,
25
+ // before the first server tick
26
+ // message(session, player, d) client data that is not a pose report. It
27
+ // receives no handover list, so a world change
28
+ // is kept and applied later by `place` or `step`
29
+ // place(sim, handovers) before each physics step, where a write that
30
+ // only takes effect at the next step has to go
31
+ // step(sim, handovers) after each physics step, and may add state or
32
+ // ownership changes to this broadcast
33
+ // join(sim) fields merged into a joiner's WORLD snapshot
34
+ // delta(sim) changed fields, or null when nothing changed;
35
+ // a returned block is itself a reason to send
36
+ export const game = pick(modules)?.default ?? {};
37
+
38
+ // Defaults for deck-defined scene components the server reads. The scene reader
39
+ // merges these over its own defaults by component name.
40
+ export const componentDefaults = pick(bodyModules)?.componentDefaults ?? {};
41
+
42
+ // Selection uses the final glob entry, which gives the deck file precedence over
43
+ // a module contributed by an import.
44
+ function pick(modules) {
45
+ const keys = Object.keys(modules);
46
+ return keys.length ? modules[keys[keys.length - 1]] : null;
47
+ }
@@ -0,0 +1,35 @@
1
+ // Dimension-independent simulation limits and numeric helpers. Fixed-step and
2
+ // catch-up limits come first, followed by movement timing and input utilities.
3
+ // Dimensional kits define their distance and speed caps beside these limits.
4
+
5
+ // The physics engine steps at a fixed 60 Hz, whatever the session tick interval
6
+ // is. A constant delta is what both matter and rapier are tuned for.
7
+ export const STEP = 1 / 60;
8
+
9
+ // Catch-up physics after a stalled event loop is capped. `world.step` advances
10
+ // the simulation clock over the steps it skips without running their physics.
11
+ export const MAX_STEPS_PER_TICK = 4;
12
+
13
+ // Movement allowance uses at most half a second of reporting time. This covers
14
+ // an ordinary garbage-collection pause or low frame rate while preventing a
15
+ // multi-second reporting gap from increasing the permitted distance.
16
+ export const MAX_EARNED_S = 0.5;
17
+
18
+ // Return the movement interval since the last accepted report, capped by
19
+ // `MAX_EARNED_S`. The kit's `players.setPose` calls this with the player's last
20
+ // accepted report time and multiplies the result by its own speed limit.
21
+ export function earned(sim, since) {
22
+ // A future or reset timestamp contributes no movement allowance.
23
+ return Math.min(MAX_EARNED_S, Math.max(0, sim.timeMs - since) / 1000);
24
+ }
25
+
26
+ // Normalize an untrusted client value to a finite number, using zero as the
27
+ // wire fallback.
28
+ export function number(value) {
29
+ return Number.isFinite(value) ? value : 0;
30
+ }
31
+
32
+ // Bound a numeric value to the inclusive interval from `min` to `max`.
33
+ export function clamp(value, min, max) {
34
+ return Math.max(min, Math.min(max, value));
35
+ }