castle-web-cli 0.4.156 → 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 +114 -8
  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,129 @@
1
+ # multiplayer-2d
2
+
3
+ The wire, the clock, the interpolation, the ownership rule, and a server that
4
+ builds a matter world from the deck's own scene -- plus a room to play in. A deck
5
+ imports this beside `castle.physics-2d`, which is the engine and the editors.
6
+
7
+ Ported from `castle.multiplayer-3d`, and the two now share
8
+ `castle.real-time`: the core that treats a pose as an opaque array of numbers.
9
+ This kit supplies what that means here.
10
+
11
+ **Two products, two words.** "The kit" is always THIS --
12
+ `castle.multiplayer-2d`. "The engine" is always `castle.physics-2d`: the
13
+ renderer, the editors, and the behaviors (`Layout`, `Collider`, `RigidBody`,
14
+ `AnalogStick`) a scene is built from.
15
+
16
+ **Namespace imports take an uppercase name**, so a call reads as a proper noun at
17
+ the site: `import * as Smoothing from '@imports/castle.real-time/code/client/smooth.js'`,
18
+ then `Smoothing.smooth(…)`. File names stay lowercase.
19
+
20
+ ## Layout
21
+
22
+ ```
23
+ code/client/ the pose format, and the browser half of it
24
+ code/server/ what runs in the session process
25
+ code/systems/ the engine binding -- the only file that knows about physics-2d
26
+ behaviors/ Box (all the drawing) and Player (the local character)
27
+ blueprints/ crate, wall, player, other-player
28
+ scenes/main.scene the starter room
29
+ ```
30
+
31
+ Poses are card pixels and radians: `[x, y, angle]` for a crate and
32
+ `[x, y, facing, clamped]` for a character, both measured from the Layout box's
33
+ top-left corner. `client/poses.js` is where that is written down, and it is the
34
+ only client file the shared core calls back into.
35
+
36
+ ## What comes from `castle.real-time`
37
+
38
+ The clock, the transport, the pose tracks, the smoothing, the ownership rule, the
39
+ wire kinds, the deck hooks, the block latches and the session process. Nothing
40
+ here forwards to them; a caller imports
41
+ `@imports/castle.real-time/code/...` directly, and passes `client/poses.js` to
42
+ every call that has to read inside a pose:
43
+
44
+ ```js
45
+ Interpolate.pushSample(track, msg.t, pose, Poses.same);
46
+ Interpolate.sampleAt(track, at, Poses.blend);
47
+ Smoothing.smooth(this.shown, id, sampled, dt, Poses);
48
+ Ownership.toClaim(this.own, objects, me, others, now, Poses.REACH);
49
+ net.sendMove(Poses.packMove(layout, facing), owned, claims, releases);
50
+ ```
51
+
52
+ What is left here is what knows about pixels or matter: `client/poses.js`,
53
+ `client/avatars.js`, `systems/multiplayer.js`, `server/limits.js`, and
54
+ `server/world.js`, `players.js`, `ownership.js` and `sceneBodies.js`.
55
+
56
+ ## How one frame goes
57
+
58
+ In `code/systems/multiplayer.js`:
59
+
60
+ 1. **Drain.** Every queued message: note the arrival against the server's own
61
+ simulation clock, apply ownership handovers, then file one pose sample per
62
+ player and object under `msg.t`. Never under arrival time.
63
+ 2. **Draw**, at `renderTime()` -- a delay behind the server clock, so
64
+ interpolation has a sample either side. Sample, smooth, write Layout, and
65
+ write the matter body too, because matter copies a dynamic body's pose back
66
+ over Layout every frame. Objects this client owns are skipped.
67
+ 3. **Take back a refused move.** The server clamps a report that moved too far
68
+ and marks the returned pose `clamped`; that is the only snapshot that moves
69
+ the local character.
70
+ 4. **Report** at `MOVE_HZ`: this character's pose, the poses of the crates this
71
+ client owns, and the claims and releases proximity asks for.
72
+
73
+ Crates belong to one client at a time. A client near a crate claims it, the
74
+ server grants it and makes the body static there, and that client simulates and
75
+ reports it while everyone else interpolates. The grant is what makes a push feel
76
+ immediate to the person doing the pushing.
77
+
78
+ A deck that keeps its own `code/systems/multiplayer.js` gets it instead of this
79
+ one: `installSystem` globs for the deck's file and stands aside when it finds it.
80
+ A glob never returns the module it is written in, so the kit served as its own
81
+ deck still installs.
82
+
83
+ ## How a deck uses it
84
+
85
+ ```jsonc
86
+ // castle.json
87
+ "server": { "main": "imports/castle.multiplayer-2d/code/server/index.js" }
88
+ ```
89
+
90
+ and then, all optional, all found by root-anchored glob in
91
+ `castle.real-time`'s `gameHooks.js`:
92
+
93
+ | deck file | what it is |
94
+ | ------------------------------- | --------------------------------------------------- |
95
+ | `code/client/game.js` | the client hooks |
96
+ | `code/server/game.js` | the game, as six hooks on a default export |
97
+ | `code/server/deckComponents.js` | `export const componentDefaults = { Cargo: {...} }` |
98
+
99
+ The six server hooks: `ready(sim)`, `message(session, player, data)`,
100
+ `place(sim, handovers)`, `step(sim, handovers)`, `join(sim)`, `delta(sim)`.
101
+ `place` runs BEFORE the physics step, which is where a write that only reaches a
102
+ body at the next step has to happen. `delta` is also a reason to send -- a tick
103
+ where nothing moved but a round ended is broadcast rather than swallowed.
104
+
105
+ ## Working on it
106
+
107
+ ```sh
108
+ node ../../cli/dist/index.js serve . --port 5762 --detach
109
+ node test/two-client-test.mjs
110
+ ```
111
+
112
+ The session process holds the room's state, so crates stay where the last run
113
+ pushed them. Restart the serve for a fresh room. Each client publishes what it
114
+ believes about the room on `globalThis.__multiplayer`, which is what the test
115
+ reads.
116
+
117
+ ## Rules for editing this kit
118
+
119
+ **Root-anchor anything that reaches out of the kit.** Once imported, these files
120
+ live at `imports/<alias>/code/...`, so `../../scenes/main.scene` is the KIT's
121
+ scene, not the deck's. `sceneBodies.js` reads `/scenes/main.scene?raw` for
122
+ exactly this reason, and the deck-hook globs in `castle.real-time` do the same.
123
+
124
+ **`server/index.js` is meant never to be forked.** Every hook a deck needs goes
125
+ through `gameHooks.js`. If a deck has to fork it, a seam is missing -- add the
126
+ seam.
127
+
128
+ **Anything that is not about pixels or matter belongs in `castle.real-time`,**
129
+ where the 3d kit gets it too.
@@ -0,0 +1,92 @@
1
+ // The Box behavior draws an actor as a filled rectangle with an optional facing
2
+ // marker and label. The class declares editable properties first, then provides
3
+ // the engine drawing methods and local canvas helpers.
4
+
5
+ export class Box {
6
+ // The engine registers behavior classes by this stable scene component name.
7
+ static behaviorName = 'Box';
8
+
9
+ static defaultProps = {
10
+ color: '#6272a4',
11
+ edge: '#44475a',
12
+ radius: 4,
13
+
14
+ // Player writes the local facing and the avatar helper writes other players' facings.
15
+ // The value is the movement direction in radians.
16
+ facing: 0,
17
+ showFacing: false,
18
+
19
+ // The multiplayer system writes the local name and the avatar helper writes
20
+ // other players' names. An empty string suppresses the label.
21
+ label: '',
22
+ };
23
+
24
+ // The inspector uses this text to identify Box instances in compact lists.
25
+ static summary(props) {
26
+ return props.color ?? '';
27
+ }
28
+
29
+ constructor(props) {
30
+ this.props = props;
31
+ }
32
+
33
+ // Draw the component during the engine's actor render pass. The runtime has
34
+ // already rotated the context around the Layout center, so the rectangle uses
35
+ // Layout coordinates directly and a crate rotates with its actor.
36
+ draw(actor, scene, ctx) {
37
+ const { x, y, width, height } = actor.components.Layout;
38
+ ctx.save();
39
+ ctx.fillStyle = this.props.color;
40
+ ctx.strokeStyle = this.props.edge;
41
+ ctx.lineWidth = 2;
42
+ roundRect(ctx, x, y, width, height, this.props.radius);
43
+ ctx.fill();
44
+ ctx.stroke();
45
+
46
+ if (this.props.showFacing) {
47
+ this.drawFacing(ctx, x + width / 2, y + height / 2, Math.min(width, height) / 2);
48
+ }
49
+ if (this.props.label) {
50
+ this.drawLabel(ctx, scene, x + width / 2, y);
51
+ }
52
+ ctx.restore();
53
+ }
54
+
55
+ // Draw a marker toward the edge in the movement direction. The square body
56
+ // has no other directional feature.
57
+ drawFacing(ctx, cx, cy, reach) {
58
+ const angle = this.props.facing ?? 0;
59
+ ctx.fillStyle = '#f8f8f2';
60
+ ctx.beginPath();
61
+ ctx.arc(
62
+ cx + Math.cos(angle) * reach * 0.55,
63
+ cy + Math.sin(angle) * reach * 0.55,
64
+ 3.5,
65
+ 0,
66
+ Math.PI * 2,
67
+ );
68
+ ctx.fill();
69
+ }
70
+
71
+ drawLabel(ctx, scene, cx, top) {
72
+ // Use the scene font so runtime labels match text drawn by the engine.
73
+ ctx.font = `12px ${scene.font}`;
74
+ ctx.textAlign = 'center';
75
+ ctx.textBaseline = 'bottom';
76
+ ctx.fillStyle = '#f8f8f2';
77
+ ctx.fillText(this.props.label, cx, top - 4);
78
+ }
79
+ }
80
+
81
+ // Add a rounded rectangle path to the current canvas context.
82
+ function roundRect(ctx, x, y, width, height, radius) {
83
+ // Clamp the radius so narrow Layout boxes still produce valid corners.
84
+ const r = Math.min(radius, width / 2, height / 2);
85
+ ctx.beginPath();
86
+ ctx.moveTo(x + r, y);
87
+ ctx.arcTo(x + width, y, x + width, y + height, r);
88
+ ctx.arcTo(x + width, y + height, x, y + height, r);
89
+ ctx.arcTo(x, y + height, x, y, r);
90
+ ctx.arcTo(x, y, x + width, y, r);
91
+ ctx.closePath();
92
+ }
@@ -0,0 +1,86 @@
1
+ // The Player behavior drives this browser's character from keyboard input.
2
+ // It writes physics velocity and the facing used by Box; the multiplayer system
3
+ // later reads the same actor to report its client-simulated pose.
4
+
5
+ // Below this speed the body is drifting to a stop and its direction is noise, so
6
+ // the character keeps the facing it already had. Same unit as `speed`.
7
+ const FACING_MIN_SPEED = 0.2;
8
+
9
+ // KeyboardEvent.code values provide arrow keys and the physical WASD cluster.
10
+ // Each direction accepts either control scheme through the same movement path.
11
+ const LEFT = ['ArrowLeft', 'KeyA'];
12
+ const RIGHT = ['ArrowRight', 'KeyD'];
13
+ const UP = ['ArrowUp', 'KeyW'];
14
+ const DOWN = ['ArrowDown', 'KeyS'];
15
+
16
+ export class Player {
17
+ // scene.actorWith('Player') uses this component name to find the local actor.
18
+ static behaviorName = 'Player';
19
+
20
+ // The editor warns when a Player lacks the body components movement requires.
21
+ static expectedSiblings = ['Collider', 'RigidBody'];
22
+
23
+ static defaultProps = {
24
+ // Pixels per fixed physics step at full tilt, the same unit AnalogStick uses.
25
+ speed: 4,
26
+ };
27
+
28
+ static propertyMeta = {
29
+ // The inspector uses this range metadata for its numeric speed control.
30
+ speed: { min: 0, step: 0.5 },
31
+ };
32
+
33
+ constructor(props) {
34
+ this.props = props;
35
+ }
36
+
37
+ // Run once per behavior frame before the multiplayer system reports the pose.
38
+ update(actor, scene) {
39
+ const direction = readKeys(scene.keys);
40
+ if (direction.x !== 0 || direction.y !== 0) {
41
+ // A held keyboard direction takes control by setting the dynamic body's
42
+ // velocity. With no held key, AnalogStick may set the velocity for touch.
43
+ const speed = this.props.speed ?? 4;
44
+ scene.physics.setVelocity(actor, { x: direction.x * speed, y: direction.y * speed });
45
+ }
46
+
47
+ // Box draws this facing marker, and the client includes the value in move
48
+ // reports for other players' avatars. Reading body velocity includes movement from
49
+ // both the keyboard and AnalogStick.
50
+ const box = actor.components.Box;
51
+ if (!box) {
52
+ // Movement remains valid for a custom player blueprint without Box art.
53
+ return;
54
+ }
55
+ const velocity = scene.physics.getVelocity(actor);
56
+ if (Math.hypot(velocity.x, velocity.y) > FACING_MIN_SPEED) {
57
+ box.facing = Math.atan2(velocity.y, velocity.x);
58
+ }
59
+ }
60
+ }
61
+
62
+ // Return the held movement keys as a unit vector. Opposite keys cancel, and
63
+ // normalizing keeps diagonal movement at the configured straight-line speed.
64
+ function readKeys(keys) {
65
+ let x = 0;
66
+ let y = 0;
67
+ if (LEFT.some((key) => keys.has(key))) {
68
+ x -= 1;
69
+ }
70
+ if (RIGHT.some((key) => keys.has(key))) {
71
+ x += 1;
72
+ }
73
+ if (UP.some((key) => keys.has(key))) {
74
+ y -= 1;
75
+ }
76
+ if (DOWN.some((key) => keys.has(key))) {
77
+ y += 1;
78
+ }
79
+ const length = Math.hypot(x, y);
80
+ if (length === 0) {
81
+ return { x: 0, y: 0 };
82
+ }
83
+
84
+ // The behavior multiplies this unit direction by the configured speed.
85
+ return { x: x / length, y: y / length };
86
+ }
@@ -0,0 +1,13 @@
1
+ {
2
+ "name": "Crate",
3
+ "actors": [
4
+ {
5
+ "components": {
6
+ "Layout": { "width": 44, "height": 44, "z": 2 },
7
+ "Box": { "color": "#bd9354", "edge": "#7a5c31", "radius": 3 },
8
+ "Collider": { "shapes": [{ "type": "box", "x": 0.5, "y": 0.5, "w": 1, "h": 1 }], "friction": 0.3, "frictionStatic": 0.4, "bounciness": 0 },
9
+ "RigidBody": { "bodyType": "dynamic", "gravityScale": 0, "drag": 0.09, "angularDrag": 2 }
10
+ }
11
+ }
12
+ ]
13
+ }
@@ -0,0 +1,13 @@
1
+ {
2
+ "name": "Other player",
3
+ "actors": [
4
+ {
5
+ "components": {
6
+ "Layout": { "width": 34, "height": 34, "z": 3 },
7
+ "Box": { "color": "#ff79c6", "edge": "#8c3f6b", "radius": 17, "showFacing": true },
8
+ "Collider": { "shapes": [{ "type": "circle", "x": 0.5, "y": 0.5, "r": 0.5 }], "friction": 0.05, "bounciness": 0 },
9
+ "RigidBody": { "bodyType": "kinematic", "gravityScale": 0, "drag": 0, "freezeRotation": true }
10
+ }
11
+ }
12
+ ]
13
+ }
@@ -0,0 +1,15 @@
1
+ {
2
+ "name": "Player",
3
+ "actors": [
4
+ {
5
+ "components": {
6
+ "Layout": { "width": 34, "height": 34, "z": 3 },
7
+ "Box": { "color": "#8be9fd", "edge": "#3f7f8c", "radius": 17, "showFacing": true },
8
+ "Collider": { "shapes": [{ "type": "circle", "x": 0.5, "y": 0.5, "r": 0.5 }], "friction": 0.05, "bounciness": 0 },
9
+ "RigidBody": { "bodyType": "dynamic", "gravityScale": 0, "drag": 0.3, "freezeRotation": true },
10
+ "Player": { "speed": 4 },
11
+ "AnalogStick": { "speed": 4, "maxRadius": 70 }
12
+ }
13
+ }
14
+ ]
15
+ }
@@ -0,0 +1,12 @@
1
+ {
2
+ "name": "Wall",
3
+ "actors": [
4
+ {
5
+ "components": {
6
+ "Layout": { "width": 100, "height": 24, "z": 1 },
7
+ "Box": { "color": "#2b2d3d", "edge": "#3d4159", "radius": 2 },
8
+ "Collider": { "shapes": [{ "type": "box", "x": 0.5, "y": 0.5, "w": 1, "h": 1 }], "friction": 0.1, "bounciness": 0 }
9
+ }
10
+ }
11
+ ]
12
+ }
@@ -0,0 +1,39 @@
1
+ {
2
+ "title": "multiplayer-2d",
3
+ "editor": {
4
+ "hiddenPaths": [],
5
+ "visiblePaths": [
6
+ "code/**",
7
+ "behaviors/**",
8
+ "scenes/**",
9
+ "blueprints/**",
10
+ "theme.style",
11
+ "fonts.generated.js"
12
+ ],
13
+ "defaultPlayFile": "scenes/main.scene"
14
+ },
15
+ "imports": {
16
+ "castle.real-time": {
17
+ "deckId": "xFVr-afOLuUQ",
18
+ "version": "2026-09-01T20:54:44.750Z"
19
+ },
20
+ "castle.physics-2d": {
21
+ "deckId": "ckRZGFW4iPrx",
22
+ "version": "2026-09-01T01:02:46.041Z"
23
+ },
24
+ "castle.base": {
25
+ "deckId": "yRcmH4_aYllE",
26
+ "version": "2026-09-01T01:02:34.326Z"
27
+ }
28
+ },
29
+ "autoUpdateWhenImported": true,
30
+ "main": "main.jsx",
31
+ "server": {
32
+ "main": "code/server/index.js",
33
+ "tickRate": 30,
34
+ "maxPlayers": 8
35
+ },
36
+ "deckId": "oiFu96LkwZ09",
37
+ "cardId": "nkJgrvrCby3H",
38
+ "publishedVersion": "2026-09-02T03:33:41.146Z"
39
+ }
@@ -0,0 +1,79 @@
1
+ // This module manages the scene actors used for other players. `showPlayer`
2
+ // creates or updates one other player's actor, with its spawn and label helpers beside
3
+ // it; `dropMissing` and `clearAvatars` remove actors that no longer have a
4
+ // player behind them.
5
+
6
+ import { applyCharacterPose } from './poses.js';
7
+
8
+ // The blueprint spawned when the caller names none.
9
+ const BLUEPRINT = 'blueprints/other-player.scene';
10
+
11
+ // Create the player-to-actor index held by one multiplayer system instance.
12
+ export function makeAvatars() {
13
+ // Actor ids remain valid across frames and can be resolved through the scene.
14
+ return { actors: new Map() }; // playerId -> actor id
15
+ }
16
+
17
+ // Create or update one other player and return its actor. The multiplayer
18
+ // system calls this once per other player per frame with the smoothed network
19
+ // pose. A `username` of null draws no label.
20
+ export function showPlayer(avatars, scene, playerId, username, pose, options = {}) {
21
+ const actor = ensureActor(avatars, scene, playerId, pose, options.blueprint ?? BLUEPRINT);
22
+
23
+ // Network character poses update Layout and Box facing on the spawned actor.
24
+ applyCharacterPose(actor, pose);
25
+ if (actor.components.Box) {
26
+ // A blueprint may omit Box; such an avatar still receives its Layout pose.
27
+ actor.components.Box.label = username === null ? '' : shortName(username);
28
+ }
29
+ return actor;
30
+ }
31
+
32
+ // Return the existing actor for a player or spawn one from the selected
33
+ // blueprint. Other player counts are unknown when the scene is authored, so
34
+ // this helper creates every other player's actor at runtime.
35
+ function ensureActor(avatars, scene, playerId, pose, blueprint) {
36
+ const known = avatars.actors.get(playerId);
37
+ const existing = known && scene.getActor(known);
38
+ if (existing) {
39
+ return existing;
40
+ }
41
+
42
+ // The other-player blueprint supplies a kinematic body. Network poses place
43
+ // it while its collider continues to block the local dynamic character.
44
+ const spawned = scene.spawnFromBlueprint(blueprint, {
45
+ // Set the initial Layout position before the first engine physics step.
46
+ components: { Layout: { x: pose[0], y: pose[1] } },
47
+ });
48
+ avatars.actors.set(playerId, spawned.id);
49
+ return spawned;
50
+ }
51
+
52
+ // Return a label that fits above the default 34-pixel avatar. The multiplayer
53
+ // system also uses this for the local player's own label. Signed-out player
54
+ // names use `anonymous-user-<uuid>`, so the shortened form keeps a useful prefix.
55
+ export function shortName(username) {
56
+ const name = String(username ?? '');
57
+ if (name.startsWith('anonymous-user-')) {
58
+ return `anon-${name.slice(15, 21)}`;
59
+ }
60
+ return name.length > 10 ? `${name.slice(0, 9)}…` : name;
61
+ }
62
+
63
+ // Despawn the actor of every player absent from `present`.
64
+ export function dropMissing(avatars, scene, present) {
65
+ // Iterate over a copy because each missing player is removed from the map.
66
+ for (const playerId of [...avatars.actors.keys()]) {
67
+ if (present.has(playerId)) {
68
+ continue;
69
+ }
70
+ scene.despawnActor(avatars.actors.get(playerId));
71
+ avatars.actors.delete(playerId);
72
+ }
73
+ }
74
+
75
+ // Clear the index after a scene load. The engine has already despawned the old
76
+ // actors, so callers must not ask the old scene to remove them again.
77
+ export function clearAvatars(avatars) {
78
+ avatars.actors.clear();
79
+ }
@@ -0,0 +1,168 @@
1
+ // This module defines the multiplayer-2d pose format for the shared real-time
2
+ // core, which otherwise treats poses as opaque number arrays. It provides wire
3
+ // packing first, engine writes second, and numeric callbacks last.
4
+ //
5
+ // Object poses are `[x, y, angle]`; character poses are `[x, y, facing]` plus a
6
+ // server-only `clamped` flag. Positions use card pixels from the Layout box's
7
+ // top-left corner, and angle values use radians.
8
+ // `multiplayer-3d/code/client/poses.js` is this file's 3D counterpart.
9
+
10
+ import { rounded } from '@imports/castle.real-time/code/client/messages.js';
11
+
12
+ const RAD_TO_DEG = 180 / Math.PI;
13
+ const DEG_TO_RAD = Math.PI / 180;
14
+
15
+ // A correction over this many pixels takes the target at once. Smoothing a jump
16
+ // of half the room would draw it as motion through positions nobody reported.
17
+ const SNAP = 120;
18
+
19
+ // How close a character has to be to claim an object. It matches the server
20
+ // reach test in `server/limits.js` and is wider than the body itself, so the
21
+ // request completes before contact.
22
+ const CLAIM_RADIUS = 90;
23
+
24
+ // How many of a character pose's values are geometry: the count stops before
25
+ // the `clamped` flag. The session delta filter compares only geometry, so a
26
+ // flag change alone does not cause a state broadcast.
27
+ export const PLAYER_GEOMETRY = 3;
28
+
29
+ // The shared ownership helper reads this radius and calls distanceBetween for
30
+ // each candidate object and competing player position.
31
+ export const REACH = { radius: CLAIM_RADIUS, distanceBetween };
32
+
33
+ //
34
+ // Packing for the wire
35
+ //
36
+
37
+ // Round a wire position to two decimals. On a 500x700 card the discarded
38
+ // fraction is not visible, and repeated physics noise does not enlarge deltas.
39
+ export function position(value) {
40
+ return rounded(value, 2);
41
+ }
42
+
43
+ // Round a wire angle to four decimals. Two decimals in radians would discard
44
+ // about half a degree and make slow rotation visibly step.
45
+ export function radians(value) {
46
+ return rounded(value, 4);
47
+ }
48
+
49
+ // Pack a server-simulated object as `[x, y, angle]`: the Layout box's top-left
50
+ // corner in card pixels, and the body's rotation in radians.
51
+ export function packPose(x, y, angle) {
52
+ return [position(x), position(y), radians(angle)];
53
+ }
54
+
55
+ // Pack a character as `[x, y, facing, clamped]`. `facing` is the direction it is
56
+ // moving and affects only the drawing.
57
+ //
58
+ // `clamped` is 1 only on the tick a player's own move was refused for being
59
+ // faster than the limit. The reporting client uses that flag to take the server
60
+ // position for the body it is simulating itself.
61
+ export function packPlayer(x, y, facing, clamped) {
62
+ return [position(x), position(y), radians(facing), clamped ? 1 : 0];
63
+ }
64
+
65
+ // Pack the local character as the pose a move report carries. `facing` is the
66
+ // direction it is moving, which the Box draws and the other clients redraw.
67
+ export function packMove(layout, facing) {
68
+ return [position(layout.x), position(layout.y), radians(facing)];
69
+ }
70
+
71
+ // The wire form of a locally simulated Layout box: the same `[x, y, angle]` the
72
+ // server sends back for everything it simulates.
73
+ export function poseOf(layout) {
74
+ // Layout rotation is optional and expressed in degrees by the engine.
75
+ return [position(layout.x), position(layout.y), radians((layout.rotation ?? 0) * DEG_TO_RAD)];
76
+ }
77
+
78
+ //
79
+ // Writing onto the engine
80
+ //
81
+
82
+ // Write an object's wire pose onto its Layout box. The engine keeps rotation in
83
+ // degrees; the wire carries radians.
84
+ export function applyPose(layout, pose) {
85
+ // Layout stores rotation in degrees even though Matter and the wire use radians.
86
+ layout.x = pose[0];
87
+ layout.y = pose[1];
88
+ layout.rotation = pose[2] * RAD_TO_DEG;
89
+ }
90
+
91
+ // Write a character's wire pose onto an actor. The third value is the direction
92
+ // it is moving, which the Box draws as a pip; the body itself stays upright.
93
+ export function applyCharacterPose(actor, pose) {
94
+ const layout = actor.components.Layout;
95
+
96
+ // Character positions use the same top-left Layout coordinates as objects.
97
+ layout.x = pose[0];
98
+ layout.y = pose[1];
99
+ if (actor.components.Box) {
100
+ actor.components.Box.facing = pose[2];
101
+ }
102
+ }
103
+
104
+ //
105
+ // Callbacks for the shared core
106
+ //
107
+
108
+ // The difference that counts as movement at one index of a pose. The server
109
+ // session passes this to `messages.poseChanged` when it filters its delta. A
110
+ // pose mixes units, so the test does too: a twentieth of a pixel for the two
111
+ // positions, and 0.002 radians (about a tenth of a degree) for an angle.
112
+ export function epsilonAt(index) {
113
+ return index < 2 ? 0.05 : 0.002;
114
+ }
115
+
116
+ // Whether two poses are the same on the wire. `interpolate.pushSample` uses
117
+ // this to drop a repeated broadcast of an unchanged pose. The comparison is
118
+ // tighter than the wire's own rounding, so two poses that differ only by
119
+ // rounding count as equal.
120
+ export function same(a, b) {
121
+ // Tracks compare arrays of the same pose kind and therefore the same length.
122
+ for (let i = 0; i < a.length; i += 1) {
123
+ if (Math.abs(a[i] - b[i]) > 0.005) {
124
+ return false;
125
+ }
126
+ }
127
+ return true;
128
+ }
129
+
130
+ // Blend two poses at fraction `f`, where zero selects `a` and one selects `b`.
131
+ // `interpolate.sampleAt` calls this with the samples either side of the render
132
+ // time. Position interpolates straight; the angle takes the shorter way around.
133
+ export function blend(a, b, f) {
134
+ return [a[0] + (b[0] - a[0]) * f, a[1] + (b[1] - a[1]) * f, a[2] + shortestTurn(a[2], b[2]) * f];
135
+ }
136
+
137
+ // Whether the positional correction is past the smoothing range. `smooth`
138
+ // starts over at the target when this reports true.
139
+ export function far(a, b) {
140
+ return Math.hypot(a[0] - b[0], a[1] - b[1]) > SNAP;
141
+ }
142
+
143
+ // Move the displayed pose a fraction of the way toward the target, in place.
144
+ // `smooth` calls this each frame with the fraction its rate closes over `dt`.
145
+ export function advance(shown, target, f) {
146
+ shown[0] += (target[0] - shown[0]) * f;
147
+ shown[1] += (target[1] - shown[1]) * f;
148
+ shown[2] += shortestTurn(shown[2], target[2]) * f;
149
+ }
150
+
151
+ // Distance between two points on the card, for the ownership reach test.
152
+ export function distanceBetween(a, b) {
153
+ return Math.hypot(a.x - b.x, a.y - b.y);
154
+ }
155
+
156
+ // The signed angular difference in the interval [-pi, pi].
157
+ export function shortestTurn(from, to) {
158
+ let turn = (to - from) % (2 * Math.PI);
159
+
160
+ // Fold either long direction around the circle into the shorter signed turn.
161
+ if (turn > Math.PI) {
162
+ turn -= 2 * Math.PI;
163
+ }
164
+ if (turn < -Math.PI) {
165
+ turn += 2 * Math.PI;
166
+ }
167
+ return turn;
168
+ }
@@ -0,0 +1,26 @@
1
+ // This is the entry point for one Castle multiplayer session process. It binds
2
+ // the shared real-time session loop to the 2D pose, Matter world, player, and
3
+ // ownership modules declared below. multiplayer-3d has the same entry shape
4
+ // with Rapier modules in place of the Matter ones.
5
+
6
+ import { makeSession } from '@imports/castle.real-time/code/server/session.js';
7
+ import { game } from '@imports/castle.real-time/code/server/gameHooks.js';
8
+ import * as Poses from '../client/poses.js';
9
+ import * as Ownership from './ownership.js';
10
+ import * as Players from './players.js';
11
+ import * as World from './world.js';
12
+
13
+ // Castle loads this object from `castle.json.server.main`. makeSession supplies
14
+ // message routing, fixed ticks, delta broadcasts, and the connection handlers.
15
+ //
16
+ // Deck-specific server behavior belongs in `code/server/game.js`; gameHooks
17
+ // discovers that root-anchored module and exposes its optional hooks here.
18
+ export default makeSession({
19
+ // The shared core calls these adapters without inspecting their 2D values.
20
+ label: 'multiplayer',
21
+ poses: Poses,
22
+ world: World,
23
+ players: Players,
24
+ ownership: Ownership,
25
+ game,
26
+ });