castle-web-cli 0.4.229 → 0.4.231

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 (259) 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 +860 -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/devSaveStorage.d.ts +36 -0
  19. package/dist/devSaveStorage.js +469 -0
  20. package/dist/devSessionChild.js +25 -13
  21. package/dist/devSessionServer.d.ts +14 -1
  22. package/dist/devSessionServer.js +237 -46
  23. package/dist/devSessionStorage.d.ts +9 -0
  24. package/dist/devSessionStorage.js +66 -1
  25. package/dist/experimentAssignment.d.ts +15 -0
  26. package/dist/experimentAssignment.js +41 -0
  27. package/dist/importCheckHook.d.ts +40 -0
  28. package/dist/importCheckHook.js +171 -0
  29. package/dist/importRegression.d.ts +15 -0
  30. package/dist/importRegression.js +100 -0
  31. package/dist/importTrust.d.ts +2 -0
  32. package/dist/importTrust.js +27 -0
  33. package/dist/importUpdateHook.d.ts +18 -0
  34. package/dist/importUpdateHook.js +31 -8
  35. package/dist/importUpdateHookRunner.js +19 -7
  36. package/dist/imports.d.ts +16 -0
  37. package/dist/imports.js +141 -31
  38. package/dist/index.js +3 -1
  39. package/dist/init.d.ts +3 -0
  40. package/dist/init.js +126 -9
  41. package/dist/install.js +4 -1
  42. package/dist/localPaths.js +4 -0
  43. package/dist/login.js +2 -2
  44. package/dist/platformDoc.js +3 -8
  45. package/dist/playPagePolicy.js +3 -1
  46. package/dist/remix.js +5 -0
  47. package/dist/routerTaskReport.d.ts +28 -0
  48. package/dist/routerTaskReport.js +56 -0
  49. package/dist/save-deck.d.ts +18 -0
  50. package/dist/save-deck.js +142 -6
  51. package/dist/serve.d.ts +8 -0
  52. package/dist/serve.js +99 -14
  53. package/dist/serverBundle.d.ts +1 -1
  54. package/dist/serverBundle.js +5 -1
  55. package/dist/webSourceSync.d.ts +2 -0
  56. package/dist/webSourceSync.js +2 -0
  57. package/kits/base/CLAUDE.md +2 -3
  58. package/kits/base/castle.json +1 -1
  59. package/kits/base/sdk/README.md +406 -53
  60. package/kits/base/sdk/agent.js +4 -4
  61. package/kits/base/sdk/avatar.d.ts +12 -0
  62. package/kits/base/sdk/avatar.js +23 -0
  63. package/kits/base/sdk/castle.d.ts +9 -0
  64. package/kits/base/sdk/castle.js +5 -0
  65. package/kits/base/sdk/commands.d.ts +223 -0
  66. package/kits/base/sdk/commands.js +16 -0
  67. package/kits/base/sdk/context.d.ts +6 -0
  68. package/kits/base/sdk/experiments.d.ts +15 -0
  69. package/kits/base/sdk/experiments.js +83 -0
  70. package/kits/base/sdk/hub.d.ts +85 -0
  71. package/kits/base/sdk/hub.js +107 -0
  72. package/kits/base/sdk/multiplayer.d.ts +45 -1
  73. package/kits/base/sdk/multiplayer.js +158 -8
  74. package/kits/base/sdk/save.d.ts +197 -0
  75. package/kits/base/sdk/save.js +525 -0
  76. package/kits/base/sdk/saveCoordinator.d.ts +39 -0
  77. package/kits/base/sdk/saveCoordinator.js +252 -0
  78. package/kits/base/sdk/server/hub.d.ts +169 -0
  79. package/kits/base/sdk/server/hub.js +125 -0
  80. package/kits/base/sdk/server/platformHandle.d.ts +42 -1
  81. package/kits/base/sdk/server/storage.d.ts +58 -4
  82. package/kits/base/sdk/server/storage.js +25 -5
  83. package/kits/base/sdk/server/wrapper.d.ts +36 -2
  84. package/kits/base/sdk/server/wrapper.js +92 -11
  85. package/kits/base/sdk/store.d.ts +3 -2
  86. package/kits/base/sdk/store.js +5 -0
  87. package/kits/base/sdk/transport.d.ts +2 -1
  88. package/kits/base/sdk/transport.js +13 -1
  89. package/kits/hub-game/.prettierrc +5 -0
  90. package/kits/hub-game/CLAUDE.md +149 -0
  91. package/kits/hub-game/blueprints/avatar-0.scene +28 -0
  92. package/kits/hub-game/blueprints/avatar-1.scene +28 -0
  93. package/kits/hub-game/blueprints/avatar-2.scene +28 -0
  94. package/kits/hub-game/blueprints/avatar-3.scene +28 -0
  95. package/kits/hub-game/blueprints/bean/avatar-0.scene +28 -0
  96. package/kits/hub-game/blueprints/bean/avatar-1.scene +28 -0
  97. package/kits/hub-game/blueprints/bean/avatar-2.scene +28 -0
  98. package/kits/hub-game/blueprints/bean/avatar-3.scene +28 -0
  99. package/kits/hub-game/blueprints/blocky/avatar-0.scene +28 -0
  100. package/kits/hub-game/blueprints/blocky/avatar-1.scene +28 -0
  101. package/kits/hub-game/blueprints/blocky/avatar-2.scene +28 -0
  102. package/kits/hub-game/blueprints/blocky/avatar-3.scene +28 -0
  103. package/kits/hub-game/blueprints/pixel/avatar-0.scene +28 -0
  104. package/kits/hub-game/blueprints/pixel/avatar-1.scene +28 -0
  105. package/kits/hub-game/blueprints/pixel/avatar-2.scene +28 -0
  106. package/kits/hub-game/blueprints/pixel/avatar-3.scene +28 -0
  107. package/kits/hub-game/castle.json +96 -0
  108. package/kits/hub-game/code/client/attention.js +133 -0
  109. package/kits/hub-game/code/client/avatar.js +288 -0
  110. package/kits/hub-game/code/client/cabinets.js +90 -0
  111. package/kits/hub-game/code/client/chat.js +135 -0
  112. package/kits/hub-game/code/client/chrome.js +1035 -0
  113. package/kits/hub-game/code/client/doorFrame.js +15 -0
  114. package/kits/hub-game/code/client/firstJoin.js +14 -0
  115. package/kits/hub-game/code/client/grab.js +376 -0
  116. package/kits/hub-game/code/client/hookLayer.js +236 -0
  117. package/kits/hub-game/code/client/idle.js +326 -0
  118. package/kits/hub-game/code/client/keys.js +48 -0
  119. package/kits/hub-game/code/client/pack.js +232 -0
  120. package/kits/hub-game/code/client/packFormat.js +397 -0
  121. package/kits/hub-game/code/client/say.js +127 -0
  122. package/kits/hub-game/code/client/sha256.js +80 -0
  123. package/kits/hub-game/code/client/sound.js +147 -0
  124. package/kits/hub-game/code/client/state.js +143 -0
  125. package/kits/hub-game/code/client/talk.js +233 -0
  126. package/kits/hub-game/code/client/tiers.js +480 -0
  127. package/kits/hub-game/code/client/together.js +440 -0
  128. package/kits/hub-game/code/client/wear.js +149 -0
  129. package/kits/hub-game/code/server/actors.js +627 -0
  130. package/kits/hub-game/code/server/blocks.js +103 -0
  131. package/kits/hub-game/code/server/cabinets.js +309 -0
  132. package/kits/hub-game/code/server/game.js +137 -0
  133. package/kits/hub-game/code/server/grab.js +248 -0
  134. package/kits/hub-game/code/server/history.js +96 -0
  135. package/kits/hub-game/code/server/hub.js +1998 -0
  136. package/kits/hub-game/code/server/idle.js +412 -0
  137. package/kits/hub-game/code/server/index.js +64 -0
  138. package/kits/hub-game/code/server/labels.js +59 -0
  139. package/kits/hub-game/code/server/manifest.js +554 -0
  140. package/kits/hub-game/code/server/npcs.js +733 -0
  141. package/kits/hub-game/code/server/party.js +439 -0
  142. package/kits/hub-game/code/server/place.js +43 -0
  143. package/kits/hub-game/code/server/say.js +83 -0
  144. package/kits/hub-game/code/server/wear.js +142 -0
  145. package/kits/hub-game/code/systems/hub.js +2347 -0
  146. package/kits/hub-game/docs/content-pack.md +151 -0
  147. package/kits/hub-game/docs/contract.md +1209 -0
  148. package/kits/hub-game/docs/style.md +137 -0
  149. package/kits/hub-game/drawings/blocky/castle-eye.sprite +58 -0
  150. package/kits/hub-game/drawings/blocky/dash.sprite +59 -0
  151. package/kits/hub-game/drawings/blocky/pom.sprite +59 -0
  152. package/kits/hub-game/drawings/blocky/tabby.sprite +59 -0
  153. package/kits/hub-game/drawings/pixel/castle-arm.sprite +13 -0
  154. package/kits/hub-game/drawings/pixel/castle-body.sprite +23 -0
  155. package/kits/hub-game/drawings/pixel/castle-leg.sprite +12 -0
  156. package/kits/hub-game/drawings/pixel/kai-arm.sprite +14 -0
  157. package/kits/hub-game/drawings/pixel/kai-head.sprite +24 -0
  158. package/kits/hub-game/drawings/pixel/kai-leg.sprite +15 -0
  159. package/kits/hub-game/drawings/pixel/kai-torso.sprite +18 -0
  160. package/kits/hub-game/drawings/pixel/mimi-arm.sprite +13 -0
  161. package/kits/hub-game/drawings/pixel/mimi-head.sprite +23 -0
  162. package/kits/hub-game/drawings/pixel/mimi-leg.sprite +15 -0
  163. package/kits/hub-game/drawings/pixel/mimi-torso.sprite +18 -0
  164. package/kits/hub-game/drawings/pixel/nox-arm.sprite +13 -0
  165. package/kits/hub-game/drawings/pixel/nox-head.sprite +21 -0
  166. package/kits/hub-game/drawings/pixel/nox-leg.sprite +14 -0
  167. package/kits/hub-game/drawings/pixel/nox-torso.sprite +18 -0
  168. package/kits/hub-game/eslint.config.js +20 -0
  169. package/kits/hub-game/fonts.generated.js +9 -0
  170. package/kits/hub-game/index.html +22 -0
  171. package/kits/hub-game/main.jsx +6 -0
  172. package/kits/hub-game/models/avatar-0.pxmodel +21 -0
  173. package/kits/hub-game/models/avatar-1.pxmodel +24 -0
  174. package/kits/hub-game/models/avatar-2.pxmodel +27 -0
  175. package/kits/hub-game/models/avatar-3.pxmodel +22 -0
  176. package/kits/hub-game/models/bean/avatar-0.pxmodel +19 -0
  177. package/kits/hub-game/models/bean/avatar-1.pxmodel +24 -0
  178. package/kits/hub-game/models/bean/avatar-2.pxmodel +22 -0
  179. package/kits/hub-game/models/bean/avatar-3.pxmodel +24 -0
  180. package/kits/hub-game/models/blocky/avatar-0.pxmodel +21 -0
  181. package/kits/hub-game/models/blocky/avatar-1.pxmodel +30 -0
  182. package/kits/hub-game/models/blocky/avatar-2.pxmodel +28 -0
  183. package/kits/hub-game/models/blocky/avatar-3.pxmodel +27 -0
  184. package/kits/hub-game/models/pixel/avatar-0.pxmodel +24 -0
  185. package/kits/hub-game/models/pixel/avatar-1.pxmodel +16 -0
  186. package/kits/hub-game/models/pixel/avatar-2.pxmodel +19 -0
  187. package/kits/hub-game/models/pixel/avatar-3.pxmodel +23 -0
  188. package/kits/hub-game/package-lock.json +365 -0
  189. package/kits/hub-game/package.json +32 -0
  190. package/kits/hub-game/scenes/main.scene +318 -0
  191. package/kits/hub-game/scripts/check.mjs +339 -0
  192. package/kits/hub-game/scripts/fixtures/sdk-stub.mjs +3 -0
  193. package/kits/hub-game/scripts/gen-avatars-bean.mjs +748 -0
  194. package/kits/hub-game/scripts/gen-avatars-blocky.mjs +607 -0
  195. package/kits/hub-game/scripts/gen-avatars-pixel.mjs +771 -0
  196. package/kits/hub-game/scripts/gen-avatars.mjs +621 -0
  197. package/kits/hub-game/scripts/pack.mjs +192 -0
  198. package/kits/hub-game/scripts/test-actors.mjs +666 -0
  199. package/kits/hub-game/scripts/test-attention.mjs +103 -0
  200. package/kits/hub-game/scripts/test-avatar.mjs +472 -0
  201. package/kits/hub-game/scripts/test-ban-join.mjs +194 -0
  202. package/kits/hub-game/scripts/test-blocks.mjs +351 -0
  203. package/kits/hub-game/scripts/test-chat.mjs +98 -0
  204. package/kits/hub-game/scripts/test-classic.mjs +590 -0
  205. package/kits/hub-game/scripts/test-door-jump.mjs +131 -0
  206. package/kits/hub-game/scripts/test-door.mjs +56 -0
  207. package/kits/hub-game/scripts/test-grab-client.mjs +328 -0
  208. package/kits/hub-game/scripts/test-grab.mjs +331 -0
  209. package/kits/hub-game/scripts/test-hub-ops.mjs +835 -0
  210. package/kits/hub-game/scripts/test-hub-trip.mjs +1518 -0
  211. package/kits/hub-game/scripts/test-idle.mjs +518 -0
  212. package/kits/hub-game/scripts/test-interest.mjs +413 -0
  213. package/kits/hub-game/scripts/test-keys.mjs +50 -0
  214. package/kits/hub-game/scripts/test-manifest.mjs +270 -0
  215. package/kits/hub-game/scripts/test-no-forms.mjs +16 -0
  216. package/kits/hub-game/scripts/test-npcs.mjs +724 -0
  217. package/kits/hub-game/scripts/test-pack.mjs +424 -0
  218. package/kits/hub-game/scripts/test-party.mjs +369 -0
  219. package/kits/hub-game/scripts/test-say.mjs +149 -0
  220. package/kits/hub-game/scripts/test-tiers.mjs +666 -0
  221. package/kits/hub-game/scripts/test-together.mjs +215 -0
  222. package/kits/hub-game/theme.style +3 -0
  223. package/kits/multiplayer-3d/castle.json +5 -5
  224. package/kits/multiplayer-3d/code/client/avatars.js +101 -1
  225. package/kits/multiplayer-3d/code/server/players.js +4 -1
  226. package/kits/multiplayer-3d/code/server/sceneBodies.js +27 -6
  227. package/kits/multiplayer-3d/code/server/world.js +20 -7
  228. package/kits/multiplayer-3d/code/systems/multiplayer.js +222 -11
  229. package/kits/physics-2d/CLAUDE.md +2 -0
  230. package/kits/physics-2d/castle.json +2 -2
  231. package/kits/physics-2d/engine/art.js +13 -0
  232. package/kits/physics-2d/engine/assets.js +4 -2
  233. package/kits/physics-2d/engine/scene.js +117 -5
  234. package/kits/physics-2d/package.json +1 -1
  235. package/kits/physics-2d/scripts/test-skip-unchanged.mjs +254 -0
  236. package/kits/physics-3d/CLAUDE.md +285 -1
  237. package/kits/physics-3d/behaviors/Player.jsx +74 -1
  238. package/kits/physics-3d/castle.json +3 -3
  239. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +33 -5
  240. package/kits/physics-3d/engine3d/actornode.js +253 -0
  241. package/kits/physics-3d/engine3d/artobjects.js +2 -2
  242. package/kits/physics-3d/engine3d/materials.js +29 -1
  243. package/kits/physics-3d/engine3d/nearshadows.js +600 -0
  244. package/kits/physics-3d/engine3d/unchanged.js +153 -0
  245. package/kits/physics-3d/engine3d/world3d.js +527 -5
  246. package/kits/physics-3d/package.json +1 -1
  247. package/kits/physics-3d/scripts/test-camera-follow.mjs +533 -0
  248. package/kits/physics-3d/scripts/test-near-shadows.mjs +1073 -0
  249. package/kits/physics-3d/scripts/test-static-actors.mjs +662 -0
  250. package/kits/physics-3d/scripts/test-static-passes.mjs +459 -0
  251. package/kits/physics-3d/scripts/test-static-physics.mjs +128 -0
  252. package/kits/physics-3d/systems/physics3d.js +187 -5
  253. package/kits/real-time/castle.json +2 -2
  254. package/kits/real-time/code/client/connection.js +77 -7
  255. package/kits/real-time/code/client/gameHooks.js +63 -3
  256. package/kits/real-time/code/client/messages.js +7 -0
  257. package/kits/real-time/code/server/gameHooks.js +24 -0
  258. package/kits/real-time/code/server/session.js +390 -22
  259. package/package.json +2 -2
@@ -1,6 +1,7 @@
1
1
  import type { Json } from "../types";
2
2
  import type { CharacterHistory, CharacterOperation } from "../commands";
3
3
  import type { PlatformHandle } from "./platformHandle";
4
+ import { type SaveApi, type SaveBucketApi } from "../save";
4
5
  export interface ServerStorageListOptions {
5
6
  prefix?: string;
6
7
  limit?: number;
@@ -15,7 +16,7 @@ export interface ServerStorageListPage<T extends Json = Json> {
15
16
  /** Null means there is nothing left. A short page alone does not mean that. */
16
17
  cursor: string | null;
17
18
  }
18
- export interface ServerStorageScope {
19
+ export interface ServerStorageScope extends SaveBucketApi {
19
20
  get<T extends Json = Json>(keys: string[]): Promise<Record<string, T>>;
20
21
  set(values: Record<string, Json>): Promise<void>;
21
22
  remove(keys: string[]): Promise<void>;
@@ -95,6 +96,59 @@ export interface DeliverCharacterKnowledgeInput {
95
96
  claimIds: string[];
96
97
  source: CharacterKnowledgeSource;
97
98
  }
99
+ /**
100
+ * A character acting on its own after a command woke it (autonomous character
101
+ * actions, bundles with `characterActions`). `declined` covers choosing
102
+ * nothing, too little confidence for its temperament, and an action no longer
103
+ * eligible when it committed; `failed` is a decision-model error.
104
+ */
105
+ export type CharacterActionNotice = {
106
+ characterId: string;
107
+ /** `id` is the event occurrence, routine, or promise id. */
108
+ trigger: {
109
+ type: "witnessed" | "routine" | "promise_due";
110
+ id: string;
111
+ };
112
+ outcome: "acted" | "declined" | "failed";
113
+ /** When acted. */
114
+ actionId?: string;
115
+ /** When acted with a parameterized action's variant. */
116
+ variantId?: string;
117
+ /** The action's world event, when it has one. */
118
+ eventOccurrenceId?: string;
119
+ /** The decision model's probability for its choice. */
120
+ probability?: number;
121
+ };
122
+ export type CharacterGameStateResult = {
123
+ revision: number;
124
+ state: {
125
+ [key: string]: string | number | boolean;
126
+ };
127
+ promiseOutcomes: Array<{
128
+ id: string;
129
+ status: "fulfilled" | "broken";
130
+ due: number;
131
+ resolvedAtGameTime: number;
132
+ }>;
133
+ /** At most 8, omitted when no character acted, declined, or failed. */
134
+ characterActions?: CharacterActionNotice[];
135
+ };
136
+ export type CharacterGameStateOperation = Omit<CharacterOperation, "result"> & {
137
+ result: CharacterGameStateResult | null;
138
+ };
139
+ export type CharacterKnowledgeDeliveryResult = {
140
+ deliveryId: string;
141
+ recipientCharacterId: string;
142
+ eventOccurrenceId: string;
143
+ claimIds: string[];
144
+ source: CharacterKnowledgeSource;
145
+ deliveredAt: string;
146
+ /** At most 8, omitted when no character acted, declined, or failed. */
147
+ characterActions?: CharacterActionNotice[];
148
+ };
149
+ export type CharacterKnowledgeDeliveryOperation = Omit<CharacterOperation, "result"> & {
150
+ result: CharacterKnowledgeDeliveryResult | null;
151
+ };
98
152
  export interface CompleteCharacterBeatInput {
99
153
  operationId: string;
100
154
  characterId: string;
@@ -189,10 +243,10 @@ export interface ServerPlaythroughCharacters {
189
243
  /** Queues a funded turn whose admitted listeners are fixed at enqueue time. */
190
244
  send(input: SendCharacterInput): Promise<CharacterOperation>;
191
245
  recordEvent(input: RecordCharacterEventInput): Promise<CharacterOperation>;
192
- setGameState(input: SetCharacterGameStateInput): Promise<CharacterOperation>;
246
+ setGameState(input: SetCharacterGameStateInput): Promise<CharacterGameStateOperation>;
193
247
  shareClaim(input: ShareCharacterClaimInput): Promise<CharacterOperation>;
194
248
  inspect(): Promise<Json>;
195
- deliverKnowledge(input: DeliverCharacterKnowledgeInput): Promise<CharacterOperation>;
249
+ deliverKnowledge(input: DeliverCharacterKnowledgeInput): Promise<CharacterKnowledgeDeliveryOperation>;
196
250
  completeBeat(input: CompleteCharacterBeatInput): Promise<CharacterOperation>;
197
251
  evaluateInformation(input: EvaluateCharacterInformationInput): Promise<CharacterInformationEvaluationOperation>;
198
252
  evaluateBeats(input: EvaluateCharacterBeatsInput): Promise<CharacterBeatEvaluationOperation>;
@@ -204,7 +258,7 @@ export interface ServerCharacterHistoryOptions {
204
258
  limit?: number;
205
259
  cursor?: string | null;
206
260
  }
207
- export interface ServerStorage {
261
+ export interface ServerStorage extends SaveApi {
208
262
  /** Shared by everyone playing the deck, and owned by this server. */
209
263
  readonly deck: ServerStorageScope;
210
264
  /** One player's public data. Readable by anyone; writable by them or by this server. */
@@ -1,5 +1,6 @@
1
1
  import { chunked } from "../chunk";
2
2
  import { decodeStorageValue, encodeStorageValue, storageError, } from "../storageJson";
3
+ import { createSaveApi, createSaveBucket, preflightSaveRequest, SaveError, } from "../save";
3
4
  // Deck storage for an author's session server.
4
5
  //
5
6
  // The same store the deck's clients use, reached over the platform channel instead of
@@ -56,8 +57,26 @@ export function createServerStorage(platformHandle) {
56
57
  const result = await platformHandle.storage(op, JSON.stringify(args));
57
58
  return JSON.parse(result);
58
59
  };
60
+ // The host forwards these args to the platform's storage route unchanged,
61
+ // which takes a save's request as `input` and a lookup as `operationId`.
62
+ const saveApi = createSaveApi(async (verb, input) => {
63
+ if (typeof platformHandle.storage !== "function" ||
64
+ platformHandle.storageEnabled === false) {
65
+ throw new SaveError({
66
+ code: "CAULDRON_STORAGE_UNAVAILABLE",
67
+ message: "Storage is not available to this session.",
68
+ operationId: input.operationId,
69
+ retryable: false,
70
+ committed: false,
71
+ });
72
+ }
73
+ const args = verb === "operation" ? input : { input };
74
+ preflightSaveRequest(verb, args, MAX_REQUEST_BYTES);
75
+ return call(verb, args);
76
+ }, true);
59
77
  return {
60
- deck: createScope(call, "DECK", null),
78
+ ...saveApi,
79
+ deck: createScope(call, "DECK", null, saveApi),
61
80
  user(userId) {
62
81
  // A bad id poisons the scope rather than throwing here, so the failure arrives
63
82
  // the same way every other failure does -- as a rejection the author can await.
@@ -65,12 +84,12 @@ export function createServerStorage(platformHandle) {
65
84
  // resolved by the platform to the deck's creator, quietly writing the wrong
66
85
  // player's bucket, so nothing is sent either.
67
86
  if (typeof userId !== "string" || userId.length === 0) {
68
- return createScope(rejectMissingSubject, "USER", null);
87
+ return createScope(rejectMissingSubject, "USER", null, saveApi);
69
88
  }
70
89
  if (utf8Length(userId) > MAX_SUBJECT_BYTES) {
71
- return createScope(rejectOversizeSubject, "USER", null);
90
+ return createScope(rejectOversizeSubject, "USER", userId, saveApi);
72
91
  }
73
- return createScope(call, "USER", userId);
92
+ return createScope(call, "USER", userId, saveApi);
74
93
  },
75
94
  board(name) {
76
95
  return createBoard(call, name);
@@ -224,8 +243,9 @@ function createPlaythrough(call, subject, generation) {
224
243
  },
225
244
  });
226
245
  }
227
- function createScope(call, scope, subject) {
246
+ function createScope(call, scope, subject, saveApi) {
228
247
  return {
248
+ ...createSaveBucket(saveApi, scope === "DECK" ? "deck" : "user", subject ?? undefined),
229
249
  async get(keys) {
230
250
  // A bare array, not a wrapper: the platform hands back exactly what the
231
251
  // storage verb returns, and `get` returns its entries directly.
@@ -2,8 +2,14 @@ import type { MultiplayerSessionMode, PlatformHandle, PlayerIdentity } from "./p
2
2
  import type { Json } from "../types";
3
3
  import type { MultiplayerWorldCharacterCommand, MultiplayerWorldCharacterCommandResult, MultiplayerWorldCharacterCommandResultValue } from "../multiplayer";
4
4
  import { type ServerStorage } from "./storage";
5
+ import { type MultiplayerHubArrival, type MultiplayerServerHub } from "./hub";
5
6
  export type { MultiplayerSessionMode, PlatformHandle, PlatformSessionConfig, PlatformWorldCheckpoint, PlatformWorldSnapshot, PlatformWorldTimeConfig, PlayerIdentity, } from "./platformHandle";
6
- export type { CharacterKnowledgeSource, CompleteCharacterBeatInput, DeliverCharacterKnowledgeInput, RecordCharacterEventInput, SetCharacterGameStateInput, ShareCharacterClaimInput, ServerStorage, ServerStorageBoard, ServerStorageBoardScore, ServerStorageListEntry, ServerStorageListOptions, ServerStorageListPage, ServerPlaythrough, ServerPlaythroughCharacters, ServerCharacterHistoryOptions, ServerStorageScope, } from "./storage";
7
+ export { createSaveCoordinator } from "../saveCoordinator";
8
+ export type { CoordinatedChange, CoordinatedSave, SaveCoordinator, SaveStatus, } from "../saveCoordinator";
9
+ export { SaveError } from "../save";
10
+ export type { SaveApi, SaveBucketApi, SaveBucketRead, SaveChange, SaveCheck, SaveClaimed, SaveClaimInput, SaveErrorEnvelope, SaveInitial, SaveInitializeInput, SaveOpened, SaveOperation, SaveReadTarget, SaveReceipt, SaveRevision, SaveRows, SaveScope, SaveSelection, SaveSnapshot, SaveTarget, SaveTransactionInput, SaveWriter, } from "../save";
11
+ export type { MultiplayerHubArrival, MultiplayerHubBoard, MultiplayerHubOutcome, MultiplayerHubPadUpdateInput, MultiplayerHubPadUpdateResult, MultiplayerHubPlayerResults, MultiplayerHubRecord, MultiplayerHubReportReceipt, MultiplayerHubResultInput, MultiplayerHubResultRow, MultiplayerHubResultShape, MultiplayerHubResultsRead, MultiplayerHubResultsReadInput, MultiplayerHubWearable, MultiplayerHubWearReceipt, MultiplayerServerHub, } from "./hub";
12
+ export type { CharacterActionNotice, CharacterGameStateOperation, CharacterGameStateResult, CharacterKnowledgeDeliveryOperation, CharacterKnowledgeDeliveryResult, CharacterKnowledgeSource, CompleteCharacterBeatInput, DeliverCharacterKnowledgeInput, RecordCharacterEventInput, SetCharacterGameStateInput, ShareCharacterClaimInput, ServerStorage, ServerStorageBoard, ServerStorageBoardScore, ServerStorageListEntry, ServerStorageListOptions, ServerStorageListPage, ServerPlaythrough, ServerPlaythroughCharacters, ServerCharacterHistoryOptions, ServerStorageScope, } from "./storage";
7
13
  export interface MultiplayerServerPlayer extends PlayerIdentity {
8
14
  playerId: string;
9
15
  readonly participantId: string;
@@ -16,6 +22,12 @@ export interface MultiplayerServerSession {
16
22
  readonly sessionId: string;
17
23
  readonly deckId: string;
18
24
  readonly mode: MultiplayerSessionMode;
25
+ /**
26
+ * The place the host started this session for (a hub door's destination, or
27
+ * the hub place ghost pinned the session to), or null when the host stamped
28
+ * none. Never set from a client.
29
+ */
30
+ readonly place: string | null;
19
31
  /**
20
32
  * Deck storage that outlives the session. Nothing else here does: a session ends
21
33
  * when its last player leaves and its memory goes with it.
@@ -23,6 +35,27 @@ export interface MultiplayerServerSession {
23
35
  readonly storage: ServerStorage;
24
36
  /** A durable checkpoint for an opted-in persistent destination. */
25
37
  readonly world: MultiplayerServerWorld | null;
38
+ /**
39
+ * The shared characters this session can address: `session.world.characters`
40
+ * in a shared-character world (the same object), or a hub place's characters
41
+ * on one of its layers, where `session.world` stays null. Null everywhere else.
42
+ */
43
+ readonly characters: MultiplayerServerWorldCharacters | null;
44
+ /**
45
+ * The hub place this session runs (castle.json `hub`, as ghost pinned it):
46
+ * results, pads and arrivals. Null for a deck without a hub block and on hosts
47
+ * without hub support.
48
+ */
49
+ readonly hub: MultiplayerServerHub | null;
50
+ /**
51
+ * The variant a connected player has in the A/B experiment `name`, or null
52
+ * when they are in no such experiment (or have left). Castle's server
53
+ * resolved it and the host delivered it with the join, so it is the same arm
54
+ * the player's page reads and nothing a client sent.
55
+ */
56
+ experiment(player: MultiplayerServerPlayer | string, name: string): string | null;
57
+ /** Every experiment a connected player is in, `{ name: variant }`. */
58
+ experiments(player: MultiplayerServerPlayer | string): Record<string, string>;
26
59
  /** Sends bytes as a binary message and all other payloads as JSON. */
27
60
  send(playerId: string, data: unknown): void;
28
61
  /** Broadcasts bytes as a binary message and all other payloads as JSON. */
@@ -243,7 +276,8 @@ export interface MultiplayerWorldCharacterTurn {
243
276
  type CallbackResult = unknown;
244
277
  export interface MultiplayerServerCallbacks {
245
278
  onStart?: (session: MultiplayerServerSession) => CallbackResult;
246
- onPlayerJoin?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer) => CallbackResult;
279
+ /** `arrival` is set when ghost placed the player through a hub door. */
280
+ onPlayerJoin?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer, arrival: MultiplayerHubArrival | null) => CallbackResult;
247
281
  onPlayerLeave?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer) => CallbackResult;
248
282
  /** Receives binary messages as Uint8Array values and JSON messages otherwise. */
249
283
  onMessage?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer, data: unknown) => CallbackResult;
@@ -1,6 +1,9 @@
1
1
  import { isBinaryPayload, toUint8Array, } from "../multiplayerProtocol";
2
2
  import { encodeStorageValue, storageError } from "../storageJson";
3
3
  import { createServerStorage } from "./storage";
4
+ import { createServerHub, hubArrival, recordHiddenUserIds, } from "./hub";
5
+ export { createSaveCoordinator } from "../saveCoordinator";
6
+ export { SaveError } from "../save";
4
7
  // The publish bundler binds the author's default callbacks export once and
5
8
  // exports the returned one-argument function as `__castleBootSession`.
6
9
  export function createCastleSessionBoot(callbacks) {
@@ -10,19 +13,23 @@ export function createCastleSessionBoot(callbacks) {
10
13
  }
11
14
  async function bootSession(platformHandle, callbacks) {
12
15
  const players = new Map();
13
- const session = createAuthorSession(platformHandle, players);
16
+ const arrivals = new Map();
17
+ // playerId -> users a block hides from them; never on the player object.
18
+ const hidden = new Map();
19
+ // playerId -> their A/B arms while connected; never on the player object.
20
+ const variants = new Map();
21
+ const session = createAuthorSession(platformHandle, players, arrivals, hidden, variants);
14
22
  let tickTimer = null;
15
- platformHandle.on("join", async (connId, identity) => {
16
- // The compatibility branch accepts the current Node shim's legacy
17
- // single-argument SessionPlayer event while the public handle contract uses
18
- // the runtime-agnostic (connId, trusted identity) pair.
19
- const player = joinedPlayer(connId, identity);
20
- players.set(player.playerId, player);
21
- await callbacks.onPlayerJoin?.(session, player);
23
+ platformHandle.on("join", async (connId, identity, handleArrival, handleVariants) => {
24
+ const { player, arrival } = admitPlayer({ players, arrivals, hidden, variants }, connId, identity, handleArrival, handleVariants);
25
+ await callbacks.onPlayerJoin?.(session, player, arrival);
22
26
  });
23
27
  platformHandle.on("leave", async (connId) => {
24
28
  const player = players.get(connId);
25
29
  players.delete(connId);
30
+ arrivals.delete(connId);
31
+ hidden.delete(connId);
32
+ variants.delete(connId);
26
33
  if (player) {
27
34
  await callbacks.onPlayerLeave?.(session, player);
28
35
  }
@@ -203,7 +210,22 @@ async function bootSession(platformHandle, callbacks) {
203
210
  }, 1_000 / platformHandle.config.tickRate);
204
211
  }
205
212
  }
206
- function createAuthorSession(platformHandle, players) {
213
+ function createAuthorSession(platformHandle, players, arrivals, hidden, variants) {
214
+ // Lenient about what it is handed: an unknown player is in no experiment.
215
+ const variantsOf = (player) => variants.get(typeof player === "string"
216
+ ? player
217
+ : (player?.playerId ?? ""));
218
+ // The pinned place counts only where the host services the hub ops.
219
+ const hub = createServerHub(platformHandle, arrivals, (a, b) => {
220
+ if (hidden.size === 0 || a === b)
221
+ return false;
222
+ const userA = players.get(a)?.userId;
223
+ const userB = players.get(b)?.userId;
224
+ if (!userA || !userB)
225
+ return false;
226
+ return Boolean(hidden.get(a)?.has(userB) || hidden.get(b)?.has(userA));
227
+ });
228
+ const world = createServerWorld(platformHandle);
207
229
  return {
208
230
  get players() {
209
231
  return Array.from(players.values());
@@ -211,8 +233,20 @@ function createAuthorSession(platformHandle, players) {
211
233
  sessionId: platformHandle.config.sessionId,
212
234
  deckId: platformHandle.config.deckId,
213
235
  mode: platformHandle.config.mode,
236
+ place: typeof platformHandle.config.place === "string"
237
+ ? platformHandle.config.place
238
+ : hub?.place ?? null,
214
239
  storage: createServerStorage(platformHandle),
215
- world: createServerWorld(platformHandle),
240
+ world,
241
+ characters: world?.characters ?? createPlaceCharacters(platformHandle),
242
+ hub,
243
+ experiment(player, name) {
244
+ const known = variantsOf(player);
245
+ return known && Object.hasOwn(known, name) ? known[name] : null;
246
+ },
247
+ experiments(player) {
248
+ return { ...variantsOf(player) };
249
+ },
216
250
  send(playerId, data) {
217
251
  if (isBinaryPayload(data)) {
218
252
  requireSendBinary(platformHandle);
@@ -274,6 +308,15 @@ const WORLD_CATCH_UP_DEFAULT_MAX_ELAPSED_MS = 7 * 24 * 60 * 60 * 1_000;
274
308
  const SAFE_WORLD_NOTIFICATION_KEY = /^[A-Za-z0-9_-]+$/;
275
309
  const CANONICAL_WORLD_NOTIFICATION_TIME = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.(\d{1,3}))?Z$/;
276
310
  const URL_IN_WORLD_NOTIFICATION_TEXT = /(?:https?:\/\/|www\.|\b[a-z0-9-]+\.(?:app|com|dev|gg|io|net|org|xyz)\b)/i;
311
+ // A hub place's layer has no world of its own, but the host may still broker
312
+ // the place's shared characters into it (`placeCharacters` in the runtime
313
+ // init). The character API is the world one; only the binding differs, and the
314
+ // host stamps that.
315
+ function createPlaceCharacters(platformHandle) {
316
+ if (platformHandle.config.placeCharacters !== true)
317
+ return null;
318
+ return createServerWorldCharacters(platformHandle);
319
+ }
277
320
  function createServerWorld(platformHandle) {
278
321
  if (!platformHandle.config.world)
279
322
  return null;
@@ -1257,13 +1300,51 @@ function requireBroadcastBinary(platformHandle) {
1257
1300
  function unsupportedBinaryRuntime() {
1258
1301
  throw new TypeError("This Castle runtime does not support binary multiplayer messages yet.");
1259
1302
  }
1303
+ // The compatibility branch accepts the current Node shim's legacy
1304
+ // single-argument SessionPlayer event while the public handle contract uses the
1305
+ // runtime-agnostic (connId, trusted identity) pair. Either form may carry the hub
1306
+ // arrival after the player and the player's A/B arms after that, and a hub
1307
+ // player's block list on the player itself.
1308
+ function admitPlayer(state, connId, identity, handleArrival, handleVariants) {
1309
+ const player = joinedPlayer(connId, identity);
1310
+ const arrival = hubArrival(typeof connId === "string" ? handleArrival : identity);
1311
+ const known = experimentVariants(typeof connId === "string" ? handleVariants : handleArrival);
1312
+ state.players.set(player.playerId, player);
1313
+ if (known) {
1314
+ state.variants.set(player.playerId, known);
1315
+ }
1316
+ else {
1317
+ state.variants.delete(player.playerId);
1318
+ }
1319
+ recordHiddenUserIds(state.hidden, player.playerId, typeof connId === "string" ? identity : connId);
1320
+ if (arrival) {
1321
+ state.arrivals.set(player.playerId, arrival);
1322
+ }
1323
+ else {
1324
+ state.arrivals.delete(player.playerId);
1325
+ }
1326
+ return { player, arrival };
1327
+ }
1328
+ // Absent on a host that predates experiments, and for a player who is in none.
1329
+ function experimentVariants(value) {
1330
+ if (!value || typeof value !== "object" || Array.isArray(value))
1331
+ return null;
1332
+ const entries = Object.entries(value).filter((entry) => typeof entry[1] === "string");
1333
+ return entries.length > 0 ? Object.freeze(Object.fromEntries(entries)) : null;
1334
+ }
1260
1335
  function joinedPlayer(connId, identity) {
1261
1336
  if (typeof connId === "string") {
1262
- return {
1337
+ const player = {
1263
1338
  ...identity,
1264
1339
  playerId: connId,
1265
1340
  participantId: identity.scopedUserId ?? identity.userId,
1266
1341
  };
1342
+ // A hub player's block list stays in the wrapper (`session.hub.hiddenPair`):
1343
+ // decks broadcast player objects.
1344
+ delete player.hiddenUserIds;
1345
+ // A/B arms arrive beside the player; one a host put on it stays off it too.
1346
+ delete player.experimentVariants;
1347
+ return player;
1267
1348
  }
1268
1349
  const legacy = connId;
1269
1350
  return {
@@ -1,5 +1,6 @@
1
1
  import type { StoreAllowance } from "./commands";
2
2
  import type { Json } from "./types";
3
+ import { type SaveApi, type SaveBucketApi } from "./save";
3
4
  export interface StoreListOptions {
4
5
  /** Only keys beginning with this. Omit for every key in the scope. */
5
6
  prefix?: string;
@@ -21,7 +22,7 @@ export interface StoreListPage<T extends Json = Json> {
21
22
  */
22
23
  cursor: string | null;
23
24
  }
24
- export interface StoreScopeApi {
25
+ export interface StoreScopeApi extends SaveBucketApi {
25
26
  /** Reads keys. Keys with no value are absent from the result. */
26
27
  get<T extends Json = Json>(keys: string[]): Promise<Record<string, T>>;
27
28
  /**
@@ -63,7 +64,7 @@ export interface StoreUsage {
63
64
  /** `Store.deck`: one allowance shared by every player of the deck. */
64
65
  shared: StoreAllowance;
65
66
  }
66
- export interface CastleStoreApi {
67
+ export interface CastleStoreApi extends SaveApi {
67
68
  /** Shared by everyone playing the deck. */
68
69
  readonly deck: StoreScopeApi;
69
70
  /** The current player's data, which other players can read. */
@@ -2,6 +2,7 @@ import { chunked } from "./chunk";
2
2
  import { decodeStorageValue, encodeStorageValue, storageError } from "./storageJson";
3
3
  import { hostRequest } from "./transport";
4
4
  import { onUnloadFlush } from "./unloadFlush";
5
+ import { createSaveApi, createSaveBucket, } from "./save";
5
6
  // Per-key deck storage for Cauldron decks.
6
7
  //
7
8
  // The older Storage/SharedStorage keep one document per bucket and rewrite the
@@ -212,6 +213,7 @@ function assertKeys(keys, operation) {
212
213
  }
213
214
  function createScope(scope, subject) {
214
215
  return {
216
+ ...createSaveBucket(saveApi, scope, subject ?? undefined),
215
217
  async get(keys) {
216
218
  const { entries } = await hostRequest("cauldronStorage.get", {
217
219
  scope,
@@ -309,7 +311,10 @@ async function usage() {
309
311
  const { usage: allowances } = await hostRequest("cauldronStorage.usage", {});
310
312
  return { player: allowances.player, shared: allowances.shared };
311
313
  }
314
+ // Saves skip the write coalescing above: each is one request, sent at once.
315
+ const saveApi = createSaveApi((verb, input) => hostRequest(`cauldronStorage.${verb}`, input));
312
316
  export const Store = {
317
+ ...saveApi,
313
318
  deck: createScope("deck", null),
314
319
  me: createScope("user", null),
315
320
  user(userId) {
@@ -1,4 +1,4 @@
1
- import { type CommandName, type CommandParams, type CommandResult, type LifecycleEvent, type VoiceEvent } from "./commands";
1
+ import { type CommandName, type CommandParams, type CommandResult, type HubEvent, type LifecycleEvent, type VoiceEvent } from "./commands";
2
2
  type PostChannel = "mobile" | "web";
3
3
  export interface HostStreamOptions {
4
4
  onStream?: (event: unknown) => void;
@@ -21,5 +21,6 @@ export declare function hostNotify(event: LifecycleEvent): void;
21
21
  export declare function postUnloadDone(unloadId: string, state?: string): void;
22
22
  export declare function setUnloadHandler(handler: (unloadId: string) => void): void;
23
23
  export declare function setVoiceEventHandler(handler: ((event: VoiceEvent) => void) | null): void;
24
+ export declare function setHubEventHandler(handler: ((event: HubEvent) => void) | null): void;
24
25
  export declare function installHostListener(): void;
25
26
  export {};
@@ -11,7 +11,7 @@
11
11
  // A streaming command (agent.chat) gets stream envelopes on its requestId before
12
12
  // its response. Each one goes to the caller's onStream and restarts the wait,
13
13
  // and the caller's AbortSignal sends the host a cancel envelope.
14
- import { CASTLE_SDK_PROTOCOL, COMMAND_TIMEOUTS_MS, STREAM_IDLE_TIMEOUT_MS, isResponseEnvelope, isStreamEnvelope, unloadRequestId, voiceEventFrom, } from "./commands";
14
+ import { CASTLE_SDK_PROTOCOL, COMMAND_TIMEOUTS_MS, STREAM_IDLE_TIMEOUT_MS, isResponseEnvelope, isStreamEnvelope, hubEventFrom, unloadRequestId, voiceEventFrom, } from "./commands";
15
15
  import { getCastleEmbed } from "./context";
16
16
  import { CastleError } from "./errors";
17
17
  import { cancelLocalCommand, releaseLocalCommand, sendLocalCommand } from "./runtime";
@@ -35,6 +35,7 @@ const pending = new Map();
35
35
  let listenersInstalled = false;
36
36
  let unloadHandler = null;
37
37
  let voiceEventHandler = null;
38
+ let hubEventHandler = null;
38
39
  export async function hostRequest(command, params, stream = {}) {
39
40
  try {
40
41
  const env = await sendCommand(resolveChannel(), command, params, stream);
@@ -103,6 +104,12 @@ export function setVoiceEventHandler(handler) {
103
104
  if (handler)
104
105
  installHostListener();
105
106
  }
107
+ // Registered by hub.ts while the deck listens for the host's Back control.
108
+ export function setHubEventHandler(handler) {
109
+ hubEventHandler = handler;
110
+ if (handler)
111
+ installHostListener();
112
+ }
106
113
  function resolveChannel() {
107
114
  if (typeof window === "undefined")
108
115
  return "local";
@@ -233,6 +240,11 @@ function receive(message) {
233
240
  voiceEventHandler?.(voiceEvent);
234
241
  return;
235
242
  }
243
+ const hubEvent = hubEventFrom(message);
244
+ if (hubEvent) {
245
+ hubEventHandler?.(hubEvent);
246
+ return;
247
+ }
236
248
  const unloadId = unloadRequestId(message);
237
249
  if (unloadId !== null)
238
250
  unloadHandler?.(unloadId);
@@ -0,0 +1,5 @@
1
+ {
2
+ "printWidth": 100,
3
+ "tabWidth": 2,
4
+ "singleQuote": true
5
+ }
@@ -0,0 +1,149 @@
1
+ # hub-game
2
+
3
+ A game behind a door in the Cauldron hub town. A hub game is a
4
+ `castle.multiplayer-3d` deck that meets the **hub contract**
5
+ (`docs/contract.md`, version 1): the kit draws every player as their platform
6
+ avatar, brings them in at the arrival together and sends them back out
7
+ through the door they came in by, and draws the HUD, labels and Back control
8
+ the game declares. The game itself is scene data plus server hooks -- **no
9
+ client code** (Tier 0).
10
+
11
+ Read `docs/contract.md` before changing the `hub` block or the server hooks;
12
+ it is what every published hub game depends on.
13
+
14
+ ## Quick reference
15
+
16
+ <!-- Injected into Castle's create assistant every turn; keep this compact and factual. -->
17
+
18
+ - Scenes, blueprints, models and behaviors are `castle.physics-3d`'s, the
19
+ network is `castle.multiplayer-3d`'s; this kit adds the hub. Everything those
20
+ kits' guides say about scenes and the server holds, except where it says
21
+ otherwise below.
22
+ - **No client code.** A hub game ships nothing under `code/client/`,
23
+ `code/systems/`, `behaviors/`, and no `.js` outside `code/server/`. The
24
+ check refuses it: a hub game's content runs inside the town's iframe.
25
+ - **The game is `code/server/game.js`**, a default export of hooks that each
26
+ get `hub`, the place's context: `ready(hub)`, `arrive(hub, group)`,
27
+ `step(hub, dt)`, `leave(hub, playerId, { userId, username })` (a result may be
28
+ reported there), `shutdown(hub)` (finish writing), `message(hub, player, data)`,
29
+ `fall(hub, playerId)` (below the place's `fallY`; a scene with
30
+ `"ground": { "none": true }` has no ground and catches at -20 by default).
31
+ `server.main` stays `imports/castle.hub-game/code/server/index.js`.
32
+ - **A player's progress between visits** goes in `hub.session.storage.deck`
33
+ under `'<name>:<userId>'`, never user scope, which their own client can
34
+ write (contract §14).
35
+ - What `hub` does: `players()`, `actorsWith(component)` (each with its `t`,
36
+ `props`, `shape` and `body`), `now`, `placeAt`,
37
+ `hold` / `release` (keep a player still), `setHud(spec, playerId?)`,
38
+ `hide` / `show` (an actor, for everyone), `move(actorId, { x, y, z,
39
+ rotationY }, { overMs })` (a `Body` `"kinematic"` actor: platforms, sweepers,
40
+ gates), `tint(actorId, '#rrggbb' | null)` (a Shape actor's colour),
41
+ `mark(playerId, { text, color } | null)` (a coloured tag over a player's
42
+ avatar: a team, who is it), `wear(playerId, { kind, color, rarity } | null)`
43
+ (v1.4: `halo`, `aura` or `orbit` in `#rrggbb`, rarity 0-9, worn on the
44
+ player's avatar in every hub place once ghost keeps it), `spawn(fromActorId, at)` / `despawn(id)` (a
45
+ copy of a scene actor, often a hidden prototype), `pose(actorId)` /
46
+ `reset(actorId, at?)` (read a body; put a loose object back, at rest),
47
+ `tune(playerId, { speed,
48
+ jump } | null)` (one player's own walk, as multipliers of the preset),
49
+ `label(actorId, text)`, `drop(playerId?)` / `holding(playerId)` (grab, below),
50
+ `result(playerId, { outcome, score, stats })`, `results(playerId)` (ghost's
51
+ recent results and records of a player), `end(playerIds?)`,
52
+ `go(door, playerIds)`, `send`, `broadcast`, `session`, `sim`, `place`.
53
+ - **The HUD** is `{ title, big, text, timer: { since | until } }` in simulation
54
+ ms (`hub.now`), drawn by the hub. It is the only way the game puts words on
55
+ screen.
56
+ - **Results** are server-only, once per player per visit, checked against
57
+ `hub.result` in `castle.json`. No free text: the town writes the words. The
58
+ `outcome` may be left out when a `score` says it all (a time trial).
59
+ - **Players arrive at `hub.arrival.actor`**, in a row, facing
60
+ `hub.arrival.face`, already placed when `arrive` runs. Never move the Player
61
+ actor in the scene to change that -- change the arrival.
62
+ - **Exit is always the hub's**: the Back control, `hub.end`, or
63
+ `hub.maxDurationSec`. A game has no lobby and no leave button.
64
+ - Never ship `blueprints/other-player.scene` or restyle the Player: every
65
+ player is drawn as their avatar (`blueprints/avatar-<n>.scene` here).
66
+ - Controller: `"walk"` (the engine's `Player`) is the only preset; `hub.tune`
67
+ scales one player's speed and jump within it. No
68
+ player shove: other players are kinematic.
69
+ - **Grab and throw** (contract v1.3): `"grab": true` in the `hub` block (or
70
+ `{ throwSpeed, holdDistance, holdHeight }`) gives players a Grab / Throw
71
+ button for the place's `Body` `"dynamic"` actors (crates, barrels). The
72
+ optional hook `grab(hub, playerId, actorId, op)` hears each `'grab'` and
73
+ `'throw'` and refuses a grab by returning `false`; `hub.drop(playerId?)`
74
+ makes holders let go (a goal, a whistle), `hub.holding(playerId)` says what
75
+ someone holds. Never a player, one object at a time. `reach` (1.6-3 m) and
76
+ `steady: true` (contract v1.22) offer objects from farther away and keep
77
+ the button up through a moment at the reach, the cone or a shared owner --
78
+ for places played on phones.
79
+ - **Idle play** (contract v1.6): `"idle": true` in the `hub` block (or
80
+ `{ emotes, seats, sounds: ["sounds/x.mp3"] }`) gives players an emote picker
81
+ (wave, dance, cheer, bow, spin, drawn on their avatar) and Sit on scene
82
+ actors carrying `HubSeat` (`{ face, height }`); a seat is a hold, so the
83
+ place's `hub.release` stands a sitter. Hooks `emote(hub, playerId, id)` and
84
+ `sit(hub, playerId, seatId)` may refuse with `false`; `hub.emote(playerId,
85
+ id)`, `hub.seat(playerId)`, and `hub.sound(actorId, file, { loop, volume,
86
+ radius })` / `hub.sound(actorId, null)` for a listed sound file of the deck
87
+ (carried in its content pack's `audio`, so a game behind a door sounds too;
88
+ silent only on a town whose engine predates that).
89
+ - **Cabinets** (contract v1.7): a `HubDoor` with `"kind": "cabinet"` whose
90
+ board from ghost carries `classic` is a door to a classic Castle deck the
91
+ host plays itself. `hub.doors()` says `classic: true` once the board is
92
+ read; `hub.go(doorId, [playerId])` sends that player through alone (away
93
+ under the hub's cover until Back). The kit sends and draws the cabinet's
94
+ card: by the cabinet a small chip (the best score and whose it is), and on a
95
+ tap the board (cover, title, top scores with photos and frames). Inert on the dev
96
+ serve, where there is no board.
97
+ - Run it like any multiplayer deck: `castle-web serve`, two tabs on the play
98
+ URL. Played on its own, Back and the game's end start a fresh instance.
99
+ - `npm run check` bundles the deck and runs this kit's contract check; it must
100
+ pass before `save-deck`, which runs the same check and refuses to publish.
101
+
102
+ ## What is where
103
+
104
+ | file | what it is |
105
+ | --- | --- |
106
+ | `docs/contract.md` | the contract, versioned |
107
+ | `code/server/index.js` | the session entry: multiplayer-3d's, with the hub layer around the deck's hooks |
108
+ | `code/server/hub.js` | the hub layer: place, avatars, arrival, holds, HUD, visibility, labels, results, exit, doors |
109
+ | `code/server/actors.js` | `hub.move` and `hub.tint`: kinematic actors driven by the server, painted actors under a budget |
110
+ | `code/server/grab.js`, `code/client/grab.js` | grabbing and throwing (v1.3): the server's checks, hook and `hub.drop`; the client's button, hold and throw |
111
+ | `code/server/idle.js`, `code/client/idle.js`, `code/client/sound.js` | idle play (v1.6): emotes, seats and sounds; the server's checks, hooks and `hub.emote` / `hub.seat` / `hub.sound`; the client's picker, Sit / Stand, avatar motion and audio |
112
+ | `code/server/cabinets.js`, `code/client/cabinets.js` | cabinets (v1.7): the server's cards (bounded, sent per player in range inside a send budget) and the dev fixture; the client's kept cards and which one to draw |
113
+ | `code/server/say.js`, `code/client/say.js` | quick reactions and canned phrases (v1.11): ids only, never text; the server's checks and fan-out, the client's words, bubbles and feed |
114
+ | `code/client/chat.js` | free-text chat (v1.12): polls the host for what this player may read and whom they reach, sends through it; who may chat is ghost's rule, never the kit's |
115
+ | `code/server/party.js` | parties in a town (v1.10): invitations, a door proposed to the party, members put on its pad, `hub.coming`; a member away through a door is kept |
116
+ | `code/client/together.js` | finding a friend in a town (v1.9): who here is one, the People list's rows, the pointers; the server's half (`hub-where`, `hub-goto`, the `where` hook) is in `code/server/hub.js` |
117
+ | `code/server/manifest.js` | reads and checks the `hub` block and results (plain JS, shared with the check) |
118
+ | `code/server/place.js` | which place a session runs, from the session alone |
119
+ | `code/server/game.js` | the starter game (Flag Dash), copied into a new deck |
120
+ | `code/client/hookLayer.js` | the client hooks, layered under the deck's by `castle.real-time` |
121
+ | `code/systems/hub.js` | the door trip, Back, joining a friend's layer, the HUD, labels, hidden actors, holds, the ribbon |
122
+ | `code/client/chrome.js`, `state.js`, `avatar.js`, `firstJoin.js` | the DOM chrome, what the place declared, the avatar seam, the main place's first join (§13) |
123
+ | `blueprints/avatar-<n>.scene`, `models/avatar-<n>.pxmodel`, `scripts/gen-avatars.mjs` | the four avatars (the Castle mascot, Petal, Beat, Star) and the script that writes their models; each avatar's height is in `avatar.js`, for what is worn over it |
124
+ | `scripts/gen-avatars-blocky.mjs`, `gen-avatars-bean.mjs`, `gen-avatars-pixel.mjs` | the scripts that write the other three sets' models (and blocky's and pixel's drawings); each set is the Castle mascot and three characters of its own |
125
+ | `blueprints/<style>/avatar-<n>.scene`, `models/<style>/`, `drawings/<style>/` | the other avatar sets (`blocky`, `bean`, `pixel`): the same four avatar ids drawn another way, picked per viewer by `Avatar.style()` (the `hub_avatar_style` experiment, or `?hubStyle=` on localhost); toon unless one is assigned (contract §11) |
126
+ | `scripts/check.mjs` | the publish check (`onCheck`) |
127
+ | `scripts/pack.mjs` | the content pack exporter (`onPack`): the deck's client half as data, for another deck's engine (`docs/content-pack.md`) |
128
+ | `code/client/pack.js`, `packFormat.js`, `sha256.js` | mounting a pack: fetch, verify, validate, build content |
129
+ | `scripts/test-manifest.mjs`, `test-pack.mjs`, `test-actors.mjs`, `test-idle.mjs`, `test-classic.mjs` | tests over the manifest, results, place resolution, the pack, moved and painted actors, idle play, and cabinets |
130
+
131
+ ## Rules for editing this kit
132
+
133
+ - A change to anything `docs/contract.md` describes is a contract change: an
134
+ optional new field is fine within v1; anything that changes what a field
135
+ means, or removes one, is v2 and must keep v1 decks working.
136
+ - The place a session runs comes from the session (`place.js`), never from a
137
+ client message.
138
+ - Hub chrome is drawn by this kit, never by game content.
139
+ - Root-anchor anything that reaches the deck (`/castle.json`,
140
+ `/code/server/game.js`), as the multiplayer kits do.
141
+
142
+ ## Not offered yet
143
+
144
+ This kit's `castle.json` carries no `description` on purpose: the CLI's kit
145
+ catalog (`cli/src/kitCatalog.ts`) offers the create assistant only kits that
146
+ describe themselves, and hub games are Castle-authored only until the door
147
+ table and curation exist (HUB.md decision 10). `castle-web init --kit
148
+ hub-game` works regardless. Adding the description is the switch that offers
149
+ it.