castle-web-cli 0.4.229 → 0.4.230

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (232) hide show
  1. package/dist/agent-prompts.d.ts +2 -0
  2. package/dist/agent-prompts.js +16 -8
  3. package/dist/agent.d.ts +2 -0
  4. package/dist/agent.js +21 -21
  5. package/dist/api.d.ts +28 -2
  6. package/dist/api.js +74 -16
  7. package/dist/castle-host/host.d.ts +91 -0
  8. package/dist/castle-host/host.js +779 -3
  9. package/dist/castleJson.d.ts +44 -0
  10. package/dist/castleJson.js +131 -0
  11. package/dist/check.js +27 -1
  12. package/dist/contentPack.d.ts +49 -0
  13. package/dist/contentPack.js +273 -0
  14. package/dist/devExperiments.d.ts +21 -0
  15. package/dist/devExperiments.js +139 -0
  16. package/dist/devHub.d.ts +55 -0
  17. package/dist/devHub.js +187 -0
  18. package/dist/devSessionChild.js +3 -1
  19. package/dist/devSessionServer.d.ts +14 -1
  20. package/dist/devSessionServer.js +229 -44
  21. package/dist/experimentAssignment.d.ts +15 -0
  22. package/dist/experimentAssignment.js +41 -0
  23. package/dist/importCheckHook.d.ts +40 -0
  24. package/dist/importCheckHook.js +171 -0
  25. package/dist/importRegression.d.ts +15 -0
  26. package/dist/importRegression.js +100 -0
  27. package/dist/importTrust.d.ts +2 -0
  28. package/dist/importTrust.js +27 -0
  29. package/dist/importUpdateHook.d.ts +18 -0
  30. package/dist/importUpdateHook.js +31 -8
  31. package/dist/importUpdateHookRunner.js +19 -7
  32. package/dist/imports.d.ts +16 -0
  33. package/dist/imports.js +141 -31
  34. package/dist/index.js +3 -1
  35. package/dist/init.d.ts +3 -0
  36. package/dist/init.js +125 -8
  37. package/dist/install.js +4 -1
  38. package/dist/localPaths.js +4 -0
  39. package/dist/login.js +2 -2
  40. package/dist/platformDoc.js +3 -8
  41. package/dist/playPagePolicy.js +3 -1
  42. package/dist/remix.js +5 -0
  43. package/dist/routerTaskReport.d.ts +28 -0
  44. package/dist/routerTaskReport.js +56 -0
  45. package/dist/save-deck.d.ts +18 -0
  46. package/dist/save-deck.js +142 -6
  47. package/dist/serve.d.ts +8 -0
  48. package/dist/serve.js +94 -13
  49. package/dist/serverBundle.d.ts +1 -1
  50. package/dist/serverBundle.js +5 -1
  51. package/dist/webSourceSync.d.ts +2 -0
  52. package/dist/webSourceSync.js +2 -0
  53. package/kits/base/CLAUDE.md +2 -3
  54. package/kits/base/castle.json +1 -1
  55. package/kits/base/sdk/README.md +258 -52
  56. package/kits/base/sdk/agent.js +4 -4
  57. package/kits/base/sdk/avatar.d.ts +12 -0
  58. package/kits/base/sdk/avatar.js +23 -0
  59. package/kits/base/sdk/castle.d.ts +5 -0
  60. package/kits/base/sdk/castle.js +3 -0
  61. package/kits/base/sdk/commands.d.ts +208 -0
  62. package/kits/base/sdk/commands.js +16 -0
  63. package/kits/base/sdk/context.d.ts +6 -0
  64. package/kits/base/sdk/experiments.d.ts +15 -0
  65. package/kits/base/sdk/experiments.js +83 -0
  66. package/kits/base/sdk/hub.d.ts +85 -0
  67. package/kits/base/sdk/hub.js +107 -0
  68. package/kits/base/sdk/multiplayer.d.ts +45 -1
  69. package/kits/base/sdk/multiplayer.js +106 -4
  70. package/kits/base/sdk/server/hub.d.ts +169 -0
  71. package/kits/base/sdk/server/hub.js +125 -0
  72. package/kits/base/sdk/server/platformHandle.d.ts +42 -1
  73. package/kits/base/sdk/server/storage.d.ts +55 -2
  74. package/kits/base/sdk/server/wrapper.d.ts +32 -2
  75. package/kits/base/sdk/server/wrapper.js +90 -11
  76. package/kits/base/sdk/transport.d.ts +2 -1
  77. package/kits/base/sdk/transport.js +13 -1
  78. package/kits/hub-game/.prettierrc +5 -0
  79. package/kits/hub-game/CLAUDE.md +146 -0
  80. package/kits/hub-game/blueprints/avatar-0.scene +28 -0
  81. package/kits/hub-game/blueprints/avatar-1.scene +28 -0
  82. package/kits/hub-game/blueprints/avatar-2.scene +28 -0
  83. package/kits/hub-game/blueprints/avatar-3.scene +28 -0
  84. package/kits/hub-game/blueprints/bean/avatar-0.scene +28 -0
  85. package/kits/hub-game/blueprints/bean/avatar-1.scene +28 -0
  86. package/kits/hub-game/blueprints/bean/avatar-2.scene +28 -0
  87. package/kits/hub-game/blueprints/bean/avatar-3.scene +28 -0
  88. package/kits/hub-game/blueprints/blocky/avatar-0.scene +28 -0
  89. package/kits/hub-game/blueprints/blocky/avatar-1.scene +28 -0
  90. package/kits/hub-game/blueprints/blocky/avatar-2.scene +28 -0
  91. package/kits/hub-game/blueprints/blocky/avatar-3.scene +28 -0
  92. package/kits/hub-game/blueprints/pixel/avatar-0.scene +28 -0
  93. package/kits/hub-game/blueprints/pixel/avatar-1.scene +28 -0
  94. package/kits/hub-game/blueprints/pixel/avatar-2.scene +28 -0
  95. package/kits/hub-game/blueprints/pixel/avatar-3.scene +28 -0
  96. package/kits/hub-game/castle.json +96 -0
  97. package/kits/hub-game/code/client/attention.js +133 -0
  98. package/kits/hub-game/code/client/avatar.js +288 -0
  99. package/kits/hub-game/code/client/cabinets.js +90 -0
  100. package/kits/hub-game/code/client/chat.js +135 -0
  101. package/kits/hub-game/code/client/chrome.js +1001 -0
  102. package/kits/hub-game/code/client/doorFrame.js +15 -0
  103. package/kits/hub-game/code/client/firstJoin.js +14 -0
  104. package/kits/hub-game/code/client/grab.js +241 -0
  105. package/kits/hub-game/code/client/hookLayer.js +230 -0
  106. package/kits/hub-game/code/client/idle.js +326 -0
  107. package/kits/hub-game/code/client/keys.js +48 -0
  108. package/kits/hub-game/code/client/pack.js +232 -0
  109. package/kits/hub-game/code/client/packFormat.js +397 -0
  110. package/kits/hub-game/code/client/say.js +127 -0
  111. package/kits/hub-game/code/client/sha256.js +80 -0
  112. package/kits/hub-game/code/client/sound.js +147 -0
  113. package/kits/hub-game/code/client/state.js +131 -0
  114. package/kits/hub-game/code/client/talk.js +259 -0
  115. package/kits/hub-game/code/client/together.js +365 -0
  116. package/kits/hub-game/code/client/wear.js +149 -0
  117. package/kits/hub-game/code/server/actors.js +627 -0
  118. package/kits/hub-game/code/server/blocks.js +103 -0
  119. package/kits/hub-game/code/server/cabinets.js +309 -0
  120. package/kits/hub-game/code/server/game.js +137 -0
  121. package/kits/hub-game/code/server/grab.js +247 -0
  122. package/kits/hub-game/code/server/history.js +96 -0
  123. package/kits/hub-game/code/server/hub.js +1904 -0
  124. package/kits/hub-game/code/server/idle.js +412 -0
  125. package/kits/hub-game/code/server/index.js +64 -0
  126. package/kits/hub-game/code/server/labels.js +59 -0
  127. package/kits/hub-game/code/server/manifest.js +527 -0
  128. package/kits/hub-game/code/server/npcs.js +745 -0
  129. package/kits/hub-game/code/server/party.js +381 -0
  130. package/kits/hub-game/code/server/place.js +43 -0
  131. package/kits/hub-game/code/server/say.js +83 -0
  132. package/kits/hub-game/code/server/wear.js +142 -0
  133. package/kits/hub-game/code/systems/hub.js +2230 -0
  134. package/kits/hub-game/docs/content-pack.md +151 -0
  135. package/kits/hub-game/docs/contract.md +1139 -0
  136. package/kits/hub-game/docs/style.md +137 -0
  137. package/kits/hub-game/drawings/blocky/castle-eye.sprite +58 -0
  138. package/kits/hub-game/drawings/blocky/dash.sprite +59 -0
  139. package/kits/hub-game/drawings/blocky/pom.sprite +59 -0
  140. package/kits/hub-game/drawings/blocky/tabby.sprite +59 -0
  141. package/kits/hub-game/drawings/pixel/castle-arm.sprite +13 -0
  142. package/kits/hub-game/drawings/pixel/castle-body.sprite +23 -0
  143. package/kits/hub-game/drawings/pixel/castle-leg.sprite +12 -0
  144. package/kits/hub-game/drawings/pixel/kai-arm.sprite +14 -0
  145. package/kits/hub-game/drawings/pixel/kai-head.sprite +24 -0
  146. package/kits/hub-game/drawings/pixel/kai-leg.sprite +15 -0
  147. package/kits/hub-game/drawings/pixel/kai-torso.sprite +18 -0
  148. package/kits/hub-game/drawings/pixel/mimi-arm.sprite +13 -0
  149. package/kits/hub-game/drawings/pixel/mimi-head.sprite +23 -0
  150. package/kits/hub-game/drawings/pixel/mimi-leg.sprite +15 -0
  151. package/kits/hub-game/drawings/pixel/mimi-torso.sprite +18 -0
  152. package/kits/hub-game/drawings/pixel/nox-arm.sprite +13 -0
  153. package/kits/hub-game/drawings/pixel/nox-head.sprite +21 -0
  154. package/kits/hub-game/drawings/pixel/nox-leg.sprite +14 -0
  155. package/kits/hub-game/drawings/pixel/nox-torso.sprite +18 -0
  156. package/kits/hub-game/eslint.config.js +20 -0
  157. package/kits/hub-game/fonts.generated.js +9 -0
  158. package/kits/hub-game/index.html +22 -0
  159. package/kits/hub-game/main.jsx +6 -0
  160. package/kits/hub-game/models/avatar-0.pxmodel +21 -0
  161. package/kits/hub-game/models/avatar-1.pxmodel +24 -0
  162. package/kits/hub-game/models/avatar-2.pxmodel +27 -0
  163. package/kits/hub-game/models/avatar-3.pxmodel +22 -0
  164. package/kits/hub-game/models/bean/avatar-0.pxmodel +19 -0
  165. package/kits/hub-game/models/bean/avatar-1.pxmodel +24 -0
  166. package/kits/hub-game/models/bean/avatar-2.pxmodel +22 -0
  167. package/kits/hub-game/models/bean/avatar-3.pxmodel +24 -0
  168. package/kits/hub-game/models/blocky/avatar-0.pxmodel +21 -0
  169. package/kits/hub-game/models/blocky/avatar-1.pxmodel +30 -0
  170. package/kits/hub-game/models/blocky/avatar-2.pxmodel +28 -0
  171. package/kits/hub-game/models/blocky/avatar-3.pxmodel +27 -0
  172. package/kits/hub-game/models/pixel/avatar-0.pxmodel +24 -0
  173. package/kits/hub-game/models/pixel/avatar-1.pxmodel +16 -0
  174. package/kits/hub-game/models/pixel/avatar-2.pxmodel +19 -0
  175. package/kits/hub-game/models/pixel/avatar-3.pxmodel +23 -0
  176. package/kits/hub-game/package-lock.json +365 -0
  177. package/kits/hub-game/package.json +32 -0
  178. package/kits/hub-game/scenes/main.scene +318 -0
  179. package/kits/hub-game/scripts/check.mjs +339 -0
  180. package/kits/hub-game/scripts/fixtures/sdk-stub.mjs +3 -0
  181. package/kits/hub-game/scripts/gen-avatars-bean.mjs +748 -0
  182. package/kits/hub-game/scripts/gen-avatars-blocky.mjs +607 -0
  183. package/kits/hub-game/scripts/gen-avatars-pixel.mjs +771 -0
  184. package/kits/hub-game/scripts/gen-avatars.mjs +621 -0
  185. package/kits/hub-game/scripts/pack.mjs +192 -0
  186. package/kits/hub-game/scripts/test-actors.mjs +666 -0
  187. package/kits/hub-game/scripts/test-attention.mjs +103 -0
  188. package/kits/hub-game/scripts/test-avatar.mjs +472 -0
  189. package/kits/hub-game/scripts/test-ban-join.mjs +194 -0
  190. package/kits/hub-game/scripts/test-blocks.mjs +351 -0
  191. package/kits/hub-game/scripts/test-chat.mjs +98 -0
  192. package/kits/hub-game/scripts/test-classic.mjs +590 -0
  193. package/kits/hub-game/scripts/test-door-jump.mjs +131 -0
  194. package/kits/hub-game/scripts/test-door.mjs +56 -0
  195. package/kits/hub-game/scripts/test-grab.mjs +331 -0
  196. package/kits/hub-game/scripts/test-hub-ops.mjs +835 -0
  197. package/kits/hub-game/scripts/test-hub-trip.mjs +1310 -0
  198. package/kits/hub-game/scripts/test-idle.mjs +518 -0
  199. package/kits/hub-game/scripts/test-interest.mjs +413 -0
  200. package/kits/hub-game/scripts/test-keys.mjs +50 -0
  201. package/kits/hub-game/scripts/test-manifest.mjs +224 -0
  202. package/kits/hub-game/scripts/test-no-forms.mjs +16 -0
  203. package/kits/hub-game/scripts/test-npcs.mjs +714 -0
  204. package/kits/hub-game/scripts/test-pack.mjs +424 -0
  205. package/kits/hub-game/scripts/test-party.mjs +286 -0
  206. package/kits/hub-game/scripts/test-say.mjs +149 -0
  207. package/kits/hub-game/scripts/test-together.mjs +183 -0
  208. package/kits/hub-game/theme.style +3 -0
  209. package/kits/multiplayer-3d/castle.json +5 -5
  210. package/kits/multiplayer-3d/code/client/avatars.js +101 -1
  211. package/kits/multiplayer-3d/code/server/players.js +4 -1
  212. package/kits/multiplayer-3d/code/server/sceneBodies.js +27 -6
  213. package/kits/multiplayer-3d/code/server/world.js +20 -7
  214. package/kits/multiplayer-3d/code/systems/multiplayer.js +222 -11
  215. package/kits/physics-2d/castle.json +2 -2
  216. package/kits/physics-2d/engine/art.js +13 -0
  217. package/kits/physics-2d/engine/assets.js +4 -2
  218. package/kits/physics-2d/engine/scene.js +25 -5
  219. package/kits/physics-3d/CLAUDE.md +6 -1
  220. package/kits/physics-3d/castle.json +3 -3
  221. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +32 -4
  222. package/kits/physics-3d/engine3d/artobjects.js +2 -2
  223. package/kits/physics-3d/engine3d/materials.js +29 -1
  224. package/kits/physics-3d/engine3d/world3d.js +65 -1
  225. package/kits/physics-3d/systems/physics3d.js +5 -2
  226. package/kits/real-time/castle.json +2 -2
  227. package/kits/real-time/code/client/connection.js +77 -7
  228. package/kits/real-time/code/client/gameHooks.js +63 -3
  229. package/kits/real-time/code/client/messages.js +7 -0
  230. package/kits/real-time/code/server/gameHooks.js +24 -0
  231. package/kits/real-time/code/server/session.js +390 -22
  232. package/package.json +2 -2
@@ -21,9 +21,12 @@ import { setup, initCard, Store, Leaderboard } from "castle-web-sdk";
21
21
  - [Leaderboard](#leaderboard)
22
22
  - [Time](#time)
23
23
  - [User](#user)
24
+ - [Experiments](#experiments)
25
+ - [Avatar](#avatar)
24
26
  - [Pass](#pass)
25
27
  - [Snapshot](#snapshot)
26
28
  - [Portal](#portal)
29
+ - [Hub](#hub)
27
30
  - [Decks](#decks)
28
31
  - [Clipboard](#clipboard)
29
32
  - [Haptics](#haptics)
@@ -112,6 +115,11 @@ TypeScript server entries can import callback, session, player, and platform
112
115
  handle types from `castle-web-sdk/server`. Server transport has no runtime
113
116
  dependency on a WebSocket package.
114
117
 
118
+ `session.sessionId`, `session.deckId` and `session.mode` say which session this
119
+ is. `session.place` is the hub place the host started the session for (see
120
+ [`session.hub`](#sessionhub)), and `null` otherwise. It is never taken from a
121
+ client.
122
+
115
123
  ### `session.storage`
116
124
 
117
125
  A session ends when its last player leaves, and its memory goes with it.
@@ -151,6 +159,73 @@ Two differences follow from a session server not being a player:
151
159
  stop. An out-of-memory kill or a host failing sends no shutdown at all, so
152
160
  save as things change and treat `onShutdown` as the last chance, not the plan.
153
161
 
162
+ ### `session.hub`
163
+
164
+ A deck whose `castle.json` declares a `hub` block is a hub place (the hub-game
165
+ kit's contract). `save-deck` publishes the block's titles and result shapes with
166
+ the server bundle, and Castle pins them to every session of the place. Those
167
+ sessions have `session.hub`; every other session has `session.hub === null`.
168
+
169
+ - `session.hub.place`, `.title` and `.result` are the place and the result shape
170
+ as published (`result` is `null` for a place that reports none, such as a town).
171
+ - `session.hub.arrival(playerId)` is how a player came in when Castle placed them
172
+ through a hub door: `{ fromDeckId, doorId }` (`doorId` is `null` when the door
173
+ names none), else `null`. It is Castle's word, never a client's, and it is also
174
+ the third argument of `onPlayerJoin`.
175
+ - `session.hub.reportResult(playerId, { outcome?, score?, stats? })` records a
176
+ signed-in player's result for this visit, once. The host checks it against the
177
+ published shape and Castle keeps it only for a place behind a curated door;
178
+ resolves `{ recorded, record }` (`recorded: false, reason: "duplicate"` for a
179
+ visit that already has one).
180
+ - `session.hub.updatePad({ doorId, padId, memberUserIds, fire? })` names who is
181
+ standing on a pad of one of this place's doors (only players connected to this
182
+ session count); `fire: true` sends them through together. Resolves
183
+ `{ status: "gathering" | "fired", members }`. A fired pad's group is fixed, so
184
+ the next gathering uses a new `padId`.
185
+ - `session.hub.readResults({ userIds?, doorIds? })` reads players' recent results,
186
+ records, platform avatars and wearables (`players[userId]`) and the best scores behind this
187
+ place's doors (`boards[doorId]`). A board also carries the door's title,
188
+ whether it is featured, and its group: `minPlayers`, `maxPlayers` and
189
+ `lateJoin` (null where the door does not say).
190
+ - `session.hub.wear(playerId, { kind, color, rarity } | null)` puts one wearable
191
+ on a signed-in player's platform avatar in every hub place (`kind` a lowercase
192
+ id the kit draws, `color` `'#rrggbb'`, `rarity` 0-9), or clears it with `null`;
193
+ the latest wins. Castle takes it only from a curated hub place. Resolves
194
+ `{ wearable }`; `readResults` returns it as `players[userId].wearable`.
195
+ - `session.hub.hiddenPair(playerIdA, playerIdB)` is true when a block hides these
196
+ two players from each other (either one blocked the other). Never send either
197
+ one the other's pose, avatar or name. The block lists themselves never reach
198
+ the deck, and player objects never carry them.
199
+
200
+ Refusals reject with a `CAULDRON_HUB_*` code, such as
201
+ `CAULDRON_HUB_RESULT_ACCOUNT_REQUIRED` for a guest, `CAULDRON_HUB_RESULT_DUPLICATE`
202
+ or `CAULDRON_HUB_PAD_NOT_READY`.
203
+
204
+ ### `session.experiment`
205
+
206
+ A deck with [experiments](#experiments) reads a player's variants on the server
207
+ too. Castle resolves them and delivers them with the join, so they are the same
208
+ arms the player's page reads and nothing a client can claim.
209
+
210
+ - `session.experiment(player, name)` is the variant a connected player (the
211
+ player object or its `playerId`) has in `name`, or `null` when they are in no
212
+ such experiment.
213
+ - `session.experiments(player)` is all of them, `{ name: variant }`.
214
+
215
+ Both answer from `onPlayerJoin` until the player leaves, and `null` / `{}`
216
+ after. The variants are never on the player object, so a roster or state built
217
+ from `session.players` does not show one player's arm to another; send a variant
218
+ to other clients only when the game means to.
219
+
220
+ ```js
221
+ export default {
222
+ onPlayerJoin(session, player) {
223
+ const lives = session.experiment(player, "starting_lives") === "five" ? 5 : 3;
224
+ state.players[player.playerId] = { lives };
225
+ },
226
+ };
227
+ ```
228
+
154
229
  ### Persistent worlds
155
230
 
156
231
  An opted-in persistent-world route has `session.world`; other sessions have
@@ -607,6 +682,92 @@ if (them?.photoUrl) {
607
682
  }
608
683
  ```
609
684
 
685
+ ## Experiments
686
+
687
+ A/B tests. A deck declares its experiments in `castle.json`; Castle gives each
688
+ player one variant of each, the same one every time they play, and the deck
689
+ reads it. The guide, with the caveats worth knowing before reading results, is
690
+ [docs/ab-tests.md](../docs/ab-tests.md).
691
+
692
+ ```json
693
+ "experiments": {
694
+ "tutorial_length": { "variants": ["short", "long"] },
695
+ "shop_price": { "variants": ["low", "mid", "high"], "weights": [50, 25, 25] }
696
+ }
697
+ ```
698
+
699
+ - An experiment's name and its variants' names are 1 to 32 characters of `a-z`,
700
+ `0-9` and `_`. A deck declares at most 8 experiments, each with 2 to 8
701
+ variants.
702
+ - `weights` are whole percentages, one per variant, summing to 100. Leave them
703
+ out for an equal split.
704
+ - `winner` (one of the variants) ends the test: every player gets that variant.
705
+ - `save-deck` sends the block to Castle, and `castle-web check` and `save-deck`
706
+ both refuse one that breaks a rule. Removing the block ends every experiment
707
+ at the next save.
708
+
709
+ ```js
710
+ import { experiment, experimentsReady } from "castle-web-sdk";
711
+
712
+ await experimentsReady();
713
+ const tutorial = experiment("tutorial_length") === "long" ? longTutorial : shortTutorial;
714
+ ```
715
+
716
+ ### `experiment(name): string | null`
717
+
718
+ The variant this player has in `name`. Synchronous. `null` means the player is
719
+ in no such experiment: the deck does not declare it, it was removed, or the host
720
+ is an older one that knows nothing of experiments. Always give `null` a
721
+ behavior, normally the one the deck had before the test.
722
+
723
+ ### `experiments(): Record<string, string>`
724
+
725
+ Every experiment this player is in on this deck, as `{ name: variant }`.
726
+
727
+ ### `experimentsReady(): Promise<Record<string, string>>`
728
+
729
+ Resolves with that same map once the host has answered, and never rejects.
730
+ Await it once at boot, before the first read: some hosts hand the answer over
731
+ with the page, where it is already resolved, and the rest answer one request. A
732
+ read made before then returns `null` and logs a warning.
733
+
734
+ A multiplayer deck's server reads the same answer with
735
+ [`session.experiment(player, name)`](#sessionexperiment).
736
+
737
+ On `castle-web serve` the experiments come from the folder's `castle.json`,
738
+ assigned to you exactly as they will be once the deck is saved. Add
739
+ `?experiment.<name>=<variant>` to the serve's URL to force an arm (a declared
740
+ experiment and one of its variants); it holds for the whole serve, client and
741
+ local server alike, until `?experiment.<name>=` clears it or the serve stops.
742
+ An open deck page keeps the arm it loaded with until it is reloaded.
743
+ Nothing published reads that parameter. `devExperiments` in `castle.json`, a
744
+ `{ "name": "variant" }` map, answers for experiments the deck does not declare
745
+ itself (ones Castle runs across decks), on the serve only.
746
+
747
+ ## Avatar
748
+
749
+ The player's platform avatar: one per account, worn in every hub place
750
+ (cauldron-game-server `docs/HUB.md`, decision 4). In v1 it is an index into the
751
+ hub-game kit's character templates; there is no editor and no cosmetics. The
752
+ hub-game kit is the caller: it dresses the player and offers the choice in its
753
+ picker. Other players' avatars are not read here; a place's server learns them
754
+ from ghost.
755
+
756
+ ### `Avatar.get(): Promise<AvatarResult>`
757
+
758
+ `{ status: "ok", avatar, chosen }` with the player's choice, or the default
759
+ every account has (`chosen: false`). Anonymous accounts have one too.
760
+ `{ status: "unavailable", avatar: null }` for a signed-out visitor; a host from
761
+ before avatars rejects with `UNKNOWN_COMMAND`. Either way the deck picks its own.
762
+
763
+ ### `Avatar.set(avatar): Promise<AvatarResult>`
764
+
765
+ Makes `avatar` the account's from now on, everywhere. Only a curated hub place
766
+ (a deck an enabled hub door leads into or out of) may: anywhere else, and for a
767
+ signed-out visitor, the answer is `unavailable` and nothing changes. Ghost
768
+ refuses an index outside its template set (`INVALID_ARGUMENT`) and more than 30
769
+ choices a minute (`RATE_LIMIT_EXCEEDED`).
770
+
610
771
  ## Pass
611
772
 
612
773
  A pass is something a creator sells to players for Castle bricks (the
@@ -700,6 +861,98 @@ Snapshot.onTaken(() => {
700
861
  });
701
862
  ```
702
863
 
864
+ ## Hub
865
+
866
+ `Hub` moves a player between hub places: every deck built on the hub-game kit is
867
+ a place, and a door is a row in Castle's curated door table. A deck names only a
868
+ door; the host supplies the current place, the session it joined there and the
869
+ party, and calls Castle with the player's own account. Hosts without hub support
870
+ answer `unavailable`; older hosts reject with `CastleError` code `UNKNOWN_COMMAND`.
871
+
872
+ - `Hub.doors()` reads the current place's doors and who is inside them:
873
+ `{ status: "ok", doors }` or `{ status: "unavailable", doors: null }`. A row has
874
+ `doorId`, `launcherKind` (`door`, `table`, `cabinet`, `gate`), `placementKind`
875
+ (`layer`, `pad`, `exact`), `placement`, `padSize`, `enabled`, `featured` and
876
+ `status: { playersInside, friendsInside }`. Where a door leads stays with the host.
877
+ - `Hub.go(doorId)` acquires the destination behind a door of the current place.
878
+ A door used within seconds of arriving can take up to 15 seconds to answer
879
+ while Castle catches up with the arrival.
880
+ - `Hub.back()` acquires the way back through the door the player came in by: the
881
+ layer they left if it has room, else their party's, else the usual pick. The
882
+ deck cannot choose where it leads; `not_found` when there is no way back.
883
+ - `Hub.friends()` reads the mutual friends in a layer of the current place right
884
+ now, as far as their now-playing privacy lets this player see them (at most
885
+ 20): `{ status: "ok", friends: [{ userId, username, here, door }] }` or
886
+ `{ status: "unavailable", friends: null }`. `here` is true for a friend in the
887
+ player's own layer; `door` is set instead for a friend inside the place behind
888
+ one of this place's doors (that door's id), and null otherwise.
889
+ - `Hub.jump(userId)` acquires the layer of the current place that friend is in:
890
+ the same place in another session, joined exactly like a door's. The way back
891
+ does not change. `not_found` when the friend is not in another layer of it.
892
+ - `Hub.report(userId, reason?)` reports another player in this hub session to
893
+ Castle's moderators, with an optional short reason (at most 500 characters).
894
+ The host names the place and session. `{ status: "ok" }`, or `unavailable`
895
+ outside a hub session or on hosts without hub support. Hub chrome only.
896
+ - `Hub.chat(after?)` reads this hub session's chat:
897
+ `{ status: "ok", canChat, peers, messages: [{ id, fromUserId, fromUsername, text, at }], cursor }`.
898
+ Who may chat is Castle's rule, not the deck's: players who follow each other
899
+ and are both over 13. Each player is returned only the messages they may
900
+ read (at most 50), and `peers` are the user ids here who would be sent what
901
+ they say. Poll it, passing the last `cursor` as `after` for only what is newer.
902
+ `unavailable` outside a hub session or on hosts without hub support.
903
+ - `Hub.say(text)` says something in that chat (at most 200 characters). A deck
904
+ cannot choose recipients: Castle sends it to the players here who may chat
905
+ with this one. `{ status, id }`, where `status` is `sent`, `none` (nobody to
906
+ send it to), `refused`, `limited` (said too fast) or `unavailable`.
907
+ - `Hub.reportChat(messageId)` reports a chat message the player was returned to
908
+ Castle's moderators. The host names the place and session. `{ status: "ok" }`
909
+ or `unavailable`. Hub chrome only.
910
+ - `Hub.cancel()` gives back an acquisition the deck will not join. Optional: one
911
+ that is never joined expires within two minutes.
912
+ - `Hub.onBack(listener)` hears the host's Back control, which a game cannot hide.
913
+ Answer it with `Hub.back()` behind the door animation; a host that hears
914
+ nothing takes the player home itself. Returns an unsubscribe function.
915
+
916
+ A player Castle has barred from the hub is refused at every hub door and at the
917
+ town itself with `CastleError` code `CAULDRON_HUB_BANNED` (from `Hub.go`,
918
+ `Hub.back`, `Hub.jump` and the place's `Multiplayer.join`). Do not retry it.
919
+
920
+ `go`, `back` and `jump` return a `HubHandoffResult`: `status: "ok"` with `url`, `nonce`
921
+ (single use, valid for 60 seconds), `sessionId`, `bundleHash` (the
922
+ destination session's content pack hash) and `contentUrl` (that pack's immutable
923
+ URL, or null when the destination has none), or `cancelled`, `full`,
924
+ `unavailable`, `not_found`, `forbidden` or `party_required` with those fields null.
925
+
926
+ A door can also lead to a cabinet: a classic Castle deck the host plays itself.
927
+ `Hub.go` then answers `status: "ok"` with `kind: "classic"` and null `url`, `nonce`
928
+ and `sessionId`: there is no session to join, and the trip is already committed.
929
+ Do not pass that handoff to `Multiplayer.join`; cover the place and wait for the
930
+ host's Back control, which `Hub.back()` answers like any other way back. `kind` is
931
+ absent on every other handoff.
932
+
933
+ Success is an acquisition; nothing has moved yet. Load the destination's content,
934
+ then join it:
935
+
936
+ ```js
937
+ import { Hub, Multiplayer } from "castle-web-sdk";
938
+
939
+ const handoff = await Hub.go("race");
940
+ if (handoff.status === "ok") {
941
+ // ...the door opens; load the destination's scene behind it...
942
+ const connection = await Multiplayer.join({ mode: "hub", handoff });
943
+ }
944
+ ```
945
+
946
+ When that socket first says hello the SDK tells the host, which commits the trip:
947
+ the player's presence moves and the way back is recorded, and from then on
948
+ every SDK call speaks for the destination. `join` resolves once that is done,
949
+ and rejects when the trip could not be completed (the player is still where they
950
+ were). A join that fails
951
+ before then cancels it, and the player is still where they were. A hub
952
+ connection reconnects with its session's own token like any other, but cannot be
953
+ acquired again: when one closes for good, go back. The engine stays in the same
954
+ page throughout; the previous place is left, not held.
955
+
703
956
  ## Portal
704
957
 
705
958
  A portal sends the player from this deck to another Castle deck,
@@ -851,8 +1104,9 @@ be coalesced, so it's safe to call on frequent events.
851
1104
  through Castle's deck-agent service, so the deck holds no key. Castle pays
852
1105
  for each player's calls out of a daily play allowance, which Castle
853
1106
  characters draw from too; once a player has used it up, calls resolve
854
- `'allowance_exhausted'` until it resets at midnight UTC. Agent.chat is
855
- limited to Castle admins for now; every other player gets `'refused'`.
1107
+ `'allowance_exhausted'` until it resets at midnight UTC. Agent.chat answers
1108
+ Castle admins and the players Castle has given access; every other player
1109
+ gets `'refused'`.
856
1110
 
857
1111
  ### `Agent.chat(params): Promise<AgentChatResult>`
858
1112
 
@@ -943,7 +1197,8 @@ for (let round = 0; round < 8; round++) {
943
1197
  display; it is not part of `message`. `finishReason` is `'stop'`,
944
1198
  `'tool_calls'` or `'length'`. `usage` carries `prompt_tokens`,
945
1199
  `completion_tokens` and `total_tokens`.
946
- - `'refused'` — the player is not a Castle admin. The model was not called.
1200
+ - `'refused'` — the player has no access to the agent. The model was not
1201
+ called.
947
1202
  - `'allowance_exhausted'` — the player's play allowance for the day is used
948
1203
  up. The model was not called. It resets at midnight UTC.
949
1204
  - `'unavailable'` — this host has no route to the deck-agent service, or
@@ -1089,55 +1344,6 @@ Host-specific layout flags such as `CastleEmbed.feed` are deprecated.
1089
1344
  New code should let Castle hosts provide the frame and let the SDK infer
1090
1345
  whether it is running standalone or embedded.
1091
1346
 
1092
- ### Filling the screen: `<meta name="castle-display">`
1093
-
1094
- By default a deck is a 5:7 portrait card. A deck that can lay itself out at
1095
- other shapes opts out of the card in its own `index.html`:
1096
-
1097
- ```html
1098
- <meta name="castle-display" content="layout=fill">
1099
- <!-- or narrow the shapes it accepts (width / height, as 16/9, 16:9 or 1.78) -->
1100
- <meta name="castle-display" content="layout=fill, min-aspect=9/16, max-aspect=16/9">
1101
- ```
1102
-
1103
- A `fill` deck gets the host's whole frame, edge to edge with no rounded
1104
- corners, whenever that frame's aspect is inside its range (default 9/21 to
1105
- 21/9); outside it, the deck gets the largest in-range box, centered. Castle's
1106
- web player gives a fill deck a bigger stage and a fullscreen button. Hosts
1107
- that don't know the tag still give it a 5:7 frame, so a fill deck should look
1108
- right at 5:7 as well.
1109
-
1110
- Lay out against the stage: the element `initCard()` returns, or
1111
- `--castle-card-w`/`--castle-card-h` in CSS, with a resize listener. Not the
1112
- window: the stage is smaller than the window when the host frame is outside
1113
- the deck's range, and inside `castle-web serve`'s own page. `getDisplay()` returns the parsed declaration and `fitStage(w, h,
1114
- display)` the box the SDK would pick.
1115
-
1116
- Size HUD, buttons and text in the card unit, not in `vw` or `cqw`:
1117
-
1118
- ```css
1119
- .score { font-size: calc(5 * var(--castle-unit)); top: calc(3 * var(--castle-unit)); }
1120
- ```
1121
-
1122
- `--castle-unit` is 1% of the width of the largest 5:7 card that fits in the
1123
- stage. On a card, or a stage taller than a card, it is 1% of the stage width
1124
- (the same as `1vw`); on a wide stage it stops growing, so a HUD keeps its card
1125
- size while the playfield gets the extra room. Anything sized in `vw` grows with
1126
- the stage instead, and a 16:9 monitor makes it huge. Canvas code gets the same
1127
- number from `cardUnit(width, height)` (px). The SDK sets the exact value for
1128
- its own stage; in edit mode, and in a kit's scene editor that draws the stage
1129
- smaller than the window, it falls back to the window's.
1130
-
1131
- A 3D camera tuned for the card keeps its framing with `fovForAspect(fov,
1132
- aspect)`: it returns `fov` at 5:7 and wider (a wide stage shows more to the
1133
- sides) and widens it on a stage narrower than 5:7, so a tall phone still sees
1134
- the card's full width.
1135
-
1136
- ```js
1137
- camera.fov = fovForAspect(50, width / height);
1138
- camera.updateProjectionMatrix();
1139
- ```
1140
-
1141
1347
  ### `CARD_RATIO`
1142
1348
 
1143
1349
  The card aspect ratio (`5 / 7`). Use this if you need to size something
@@ -6,10 +6,10 @@
6
6
  // promise resolves with the whole message. A deck runs any tool calls itself
7
7
  // and calls Agent.chat again with the results.
8
8
  //
9
- // Agent.chat is limited to Castle admins for now: every other player gets
10
- // `refused`. A player whose allowance for the day is spent gets
11
- // `allowance_exhausted`. A host with no route to the service answers
12
- // `unavailable`.
9
+ // Agent.chat answers Castle admins and the players Castle has given access;
10
+ // every other player gets `refused`. A player whose allowance for the day is
11
+ // spent gets `allowance_exhausted`. A host with no route to the service
12
+ // answers `unavailable`.
13
13
  import { CastleError } from "./errors";
14
14
  import { hostRequest } from "./transport";
15
15
  async function chat(params) {
@@ -0,0 +1,12 @@
1
+ import type { AvatarResult } from "./commands";
2
+ export type { AvatarResult } from "./commands";
3
+ export interface CastleAvatarApi {
4
+ /**
5
+ * The player's avatar: their choice, or the default every account has.
6
+ * `unavailable` for a signed-out visitor, or on a host without avatars.
7
+ */
8
+ get(): Promise<AvatarResult>;
9
+ /** Choose the avatar this player wears everywhere from now on. */
10
+ set(avatar: number): Promise<AvatarResult>;
11
+ }
12
+ export declare const Avatar: CastleAvatarApi;
@@ -0,0 +1,23 @@
1
+ // Avatar — the player's platform avatar (cauldron-game-server docs/HUB.md,
2
+ // decision 4): one per account, worn in every hub place. v1 is an index into the
3
+ // hub-game kit's character templates; there is no editor and no cosmetics.
4
+ //
5
+ // The hub-game kit is the one caller: it reads the avatar to dress the player
6
+ // and offers the choice in its picker. Other players' avatars are not read
7
+ // here; a place's server learns them from ghost.
8
+ import { CastleError } from "./errors";
9
+ import { hostRequest } from "./transport";
10
+ export const Avatar = { get, set };
11
+ async function get() {
12
+ return hostRequest("avatar.get", {});
13
+ }
14
+ async function set(avatar) {
15
+ if (typeof avatar !== "number" || !Number.isInteger(avatar) || avatar < 0) {
16
+ throw new CastleError({
17
+ code: "INVALID_ARGUMENT",
18
+ message: "Avatar.set requires a template index.",
19
+ operation: "Avatar.set",
20
+ });
21
+ }
22
+ return hostRequest("avatar.set", { avatar });
23
+ }
@@ -1,14 +1,19 @@
1
1
  export { isEdit } from "./context";
2
2
  export { Agent } from "./agent";
3
3
  export type { AgentChatDelta, AgentChatParams, AgentChatResult, AgentMessage, AgentReasoning, AgentTool, AgentToolCall, AgentToolChoice, AgentUsage, CastleAgentApi, } from "./agent";
4
+ export { Avatar } from "./avatar";
5
+ export type { AvatarResult, CastleAvatarApi } from "./avatar";
4
6
  export { Characters } from "./characters";
5
7
  export type { CastleCharactersApi, CharacterHandle, CharacterHistoryOptions, CharacterSendInput, } from "./characters";
6
8
  export { Decks } from "./decks";
7
9
  export type { CastleDecksApi, DeckSummary, DecksListParams, DecksListResult } from "./decks";
8
10
  export { CastleError } from "./errors";
11
+ export { experiment, experiments, experimentsReady } from "./experiments";
9
12
  export { deckPrefixOf, IMPORTS_DIR, IMPORTS_PREFIX, isImportedFile, resolveDeckFile, } from "./files";
10
13
  export { Haptics } from "./haptics";
11
14
  export type { CastleHapticsApi, HapticsResult, HapticsStatus, HapticStyle } from "./haptics";
15
+ export { Hub } from "./hub";
16
+ export type { CastleHubApi, HubBackResult, HubCancelResult, HubCancelStatus, HubChatMessage, HubChatResult, HubDoor, HubDoorsResult, HubFriend, HubFriendsResult, HubGoParams, HubGoResult, HubHandoffResult, HubHandoffStatus, HubJumpResult, HubPlacementKind, HubReportResult, HubSayResult, } from "./hub";
12
17
  export { Leaderboard } from "./leaderboard";
13
18
  export type { LeaderboardData, LeaderboardEntry, LeaderboardOptions, LeaderboardScope, LeaderboardShowOptions, LeaderboardShowResult, LeaderboardShowStatus, LeaderboardSort, } from "./leaderboard";
14
19
  export { Lifecycle } from "./lifecycle";
@@ -1,11 +1,14 @@
1
1
  // Castle Web SDK
2
2
  export { isEdit } from "./context";
3
3
  export { Agent } from "./agent";
4
+ export { Avatar } from "./avatar";
4
5
  export { Characters } from "./characters";
5
6
  export { Decks } from "./decks";
6
7
  export { CastleError } from "./errors";
8
+ export { experiment, experiments, experimentsReady } from "./experiments";
7
9
  export { deckPrefixOf, IMPORTS_DIR, IMPORTS_PREFIX, isImportedFile, resolveDeckFile, } from "./files";
8
10
  export { Haptics } from "./haptics";
11
+ export { Hub } from "./hub";
9
12
  export { Leaderboard } from "./leaderboard";
10
13
  export { Lifecycle } from "./lifecycle";
11
14
  export { Multiplayer } from "./multiplayer";