castle-web-cli 0.4.228 → 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 (236) hide show
  1. package/dist/agent-prompts.d.ts +11 -3
  2. package/dist/agent-prompts.js +153 -53
  3. package/dist/agent.d.ts +2 -0
  4. package/dist/agent.js +43 -33
  5. package/dist/api.d.ts +47 -2
  6. package/dist/api.js +85 -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 +59 -0
  10. package/dist/castleJson.js +267 -3
  11. package/dist/check.js +27 -1
  12. package/dist/cloudGit.d.ts +20 -1
  13. package/dist/cloudGit.js +267 -10
  14. package/dist/contentPack.d.ts +49 -0
  15. package/dist/contentPack.js +273 -0
  16. package/dist/devExperiments.d.ts +21 -0
  17. package/dist/devExperiments.js +139 -0
  18. package/dist/devHub.d.ts +55 -0
  19. package/dist/devHub.js +187 -0
  20. package/dist/devSessionChild.js +3 -1
  21. package/dist/devSessionServer.d.ts +14 -1
  22. package/dist/devSessionServer.js +229 -44
  23. package/dist/experimentAssignment.d.ts +15 -0
  24. package/dist/experimentAssignment.js +41 -0
  25. package/dist/importCheckHook.d.ts +40 -0
  26. package/dist/importCheckHook.js +171 -0
  27. package/dist/importRegression.d.ts +15 -0
  28. package/dist/importRegression.js +100 -0
  29. package/dist/importTrust.d.ts +2 -0
  30. package/dist/importTrust.js +27 -0
  31. package/dist/importUpdateHook.d.ts +18 -0
  32. package/dist/importUpdateHook.js +31 -8
  33. package/dist/importUpdateHookRunner.js +19 -7
  34. package/dist/imports.d.ts +16 -0
  35. package/dist/imports.js +145 -33
  36. package/dist/index.js +8 -1
  37. package/dist/init.d.ts +3 -0
  38. package/dist/init.js +125 -8
  39. package/dist/install.js +4 -1
  40. package/dist/localPaths.js +4 -0
  41. package/dist/login.js +2 -2
  42. package/dist/platformDoc.js +3 -8
  43. package/dist/playPagePolicy.js +3 -1
  44. package/dist/remix.js +5 -0
  45. package/dist/routerTaskReport.d.ts +28 -0
  46. package/dist/routerTaskReport.js +56 -0
  47. package/dist/save-deck.d.ts +18 -0
  48. package/dist/save-deck.js +145 -6
  49. package/dist/serve.d.ts +8 -0
  50. package/dist/serve.js +94 -13
  51. package/dist/serverBundle.d.ts +1 -1
  52. package/dist/serverBundle.js +5 -1
  53. package/dist/sourceLineage.d.ts +42 -0
  54. package/dist/sourceLineage.js +380 -0
  55. package/dist/webSourceSync.d.ts +11 -0
  56. package/dist/webSourceSync.js +26 -9
  57. package/kits/base/CLAUDE.md +2 -3
  58. package/kits/base/castle.json +1 -1
  59. package/kits/base/sdk/README.md +301 -52
  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 +6 -1
  64. package/kits/base/sdk/castle.js +3 -0
  65. package/kits/base/sdk/commands.d.ts +208 -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 +86 -6
  73. package/kits/base/sdk/multiplayer.js +157 -4
  74. package/kits/base/sdk/server/hub.d.ts +169 -0
  75. package/kits/base/sdk/server/hub.js +125 -0
  76. package/kits/base/sdk/server/platformHandle.d.ts +49 -2
  77. package/kits/base/sdk/server/storage.d.ts +55 -2
  78. package/kits/base/sdk/server/wrapper.d.ts +85 -6
  79. package/kits/base/sdk/server/wrapper.js +393 -30
  80. package/kits/base/sdk/transport.d.ts +2 -1
  81. package/kits/base/sdk/transport.js +13 -1
  82. package/kits/hub-game/.prettierrc +5 -0
  83. package/kits/hub-game/CLAUDE.md +146 -0
  84. package/kits/hub-game/blueprints/avatar-0.scene +28 -0
  85. package/kits/hub-game/blueprints/avatar-1.scene +28 -0
  86. package/kits/hub-game/blueprints/avatar-2.scene +28 -0
  87. package/kits/hub-game/blueprints/avatar-3.scene +28 -0
  88. package/kits/hub-game/blueprints/bean/avatar-0.scene +28 -0
  89. package/kits/hub-game/blueprints/bean/avatar-1.scene +28 -0
  90. package/kits/hub-game/blueprints/bean/avatar-2.scene +28 -0
  91. package/kits/hub-game/blueprints/bean/avatar-3.scene +28 -0
  92. package/kits/hub-game/blueprints/blocky/avatar-0.scene +28 -0
  93. package/kits/hub-game/blueprints/blocky/avatar-1.scene +28 -0
  94. package/kits/hub-game/blueprints/blocky/avatar-2.scene +28 -0
  95. package/kits/hub-game/blueprints/blocky/avatar-3.scene +28 -0
  96. package/kits/hub-game/blueprints/pixel/avatar-0.scene +28 -0
  97. package/kits/hub-game/blueprints/pixel/avatar-1.scene +28 -0
  98. package/kits/hub-game/blueprints/pixel/avatar-2.scene +28 -0
  99. package/kits/hub-game/blueprints/pixel/avatar-3.scene +28 -0
  100. package/kits/hub-game/castle.json +96 -0
  101. package/kits/hub-game/code/client/attention.js +133 -0
  102. package/kits/hub-game/code/client/avatar.js +288 -0
  103. package/kits/hub-game/code/client/cabinets.js +90 -0
  104. package/kits/hub-game/code/client/chat.js +135 -0
  105. package/kits/hub-game/code/client/chrome.js +1001 -0
  106. package/kits/hub-game/code/client/doorFrame.js +15 -0
  107. package/kits/hub-game/code/client/firstJoin.js +14 -0
  108. package/kits/hub-game/code/client/grab.js +241 -0
  109. package/kits/hub-game/code/client/hookLayer.js +230 -0
  110. package/kits/hub-game/code/client/idle.js +326 -0
  111. package/kits/hub-game/code/client/keys.js +48 -0
  112. package/kits/hub-game/code/client/pack.js +232 -0
  113. package/kits/hub-game/code/client/packFormat.js +397 -0
  114. package/kits/hub-game/code/client/say.js +127 -0
  115. package/kits/hub-game/code/client/sha256.js +80 -0
  116. package/kits/hub-game/code/client/sound.js +147 -0
  117. package/kits/hub-game/code/client/state.js +131 -0
  118. package/kits/hub-game/code/client/talk.js +259 -0
  119. package/kits/hub-game/code/client/together.js +365 -0
  120. package/kits/hub-game/code/client/wear.js +149 -0
  121. package/kits/hub-game/code/server/actors.js +627 -0
  122. package/kits/hub-game/code/server/blocks.js +103 -0
  123. package/kits/hub-game/code/server/cabinets.js +309 -0
  124. package/kits/hub-game/code/server/game.js +137 -0
  125. package/kits/hub-game/code/server/grab.js +247 -0
  126. package/kits/hub-game/code/server/history.js +96 -0
  127. package/kits/hub-game/code/server/hub.js +1904 -0
  128. package/kits/hub-game/code/server/idle.js +412 -0
  129. package/kits/hub-game/code/server/index.js +64 -0
  130. package/kits/hub-game/code/server/labels.js +59 -0
  131. package/kits/hub-game/code/server/manifest.js +527 -0
  132. package/kits/hub-game/code/server/npcs.js +745 -0
  133. package/kits/hub-game/code/server/party.js +381 -0
  134. package/kits/hub-game/code/server/place.js +43 -0
  135. package/kits/hub-game/code/server/say.js +83 -0
  136. package/kits/hub-game/code/server/wear.js +142 -0
  137. package/kits/hub-game/code/systems/hub.js +2230 -0
  138. package/kits/hub-game/docs/content-pack.md +151 -0
  139. package/kits/hub-game/docs/contract.md +1139 -0
  140. package/kits/hub-game/docs/style.md +137 -0
  141. package/kits/hub-game/drawings/blocky/castle-eye.sprite +58 -0
  142. package/kits/hub-game/drawings/blocky/dash.sprite +59 -0
  143. package/kits/hub-game/drawings/blocky/pom.sprite +59 -0
  144. package/kits/hub-game/drawings/blocky/tabby.sprite +59 -0
  145. package/kits/hub-game/drawings/pixel/castle-arm.sprite +13 -0
  146. package/kits/hub-game/drawings/pixel/castle-body.sprite +23 -0
  147. package/kits/hub-game/drawings/pixel/castle-leg.sprite +12 -0
  148. package/kits/hub-game/drawings/pixel/kai-arm.sprite +14 -0
  149. package/kits/hub-game/drawings/pixel/kai-head.sprite +24 -0
  150. package/kits/hub-game/drawings/pixel/kai-leg.sprite +15 -0
  151. package/kits/hub-game/drawings/pixel/kai-torso.sprite +18 -0
  152. package/kits/hub-game/drawings/pixel/mimi-arm.sprite +13 -0
  153. package/kits/hub-game/drawings/pixel/mimi-head.sprite +23 -0
  154. package/kits/hub-game/drawings/pixel/mimi-leg.sprite +15 -0
  155. package/kits/hub-game/drawings/pixel/mimi-torso.sprite +18 -0
  156. package/kits/hub-game/drawings/pixel/nox-arm.sprite +13 -0
  157. package/kits/hub-game/drawings/pixel/nox-head.sprite +21 -0
  158. package/kits/hub-game/drawings/pixel/nox-leg.sprite +14 -0
  159. package/kits/hub-game/drawings/pixel/nox-torso.sprite +18 -0
  160. package/kits/hub-game/eslint.config.js +20 -0
  161. package/kits/hub-game/fonts.generated.js +9 -0
  162. package/kits/hub-game/index.html +22 -0
  163. package/kits/hub-game/main.jsx +6 -0
  164. package/kits/hub-game/models/avatar-0.pxmodel +21 -0
  165. package/kits/hub-game/models/avatar-1.pxmodel +24 -0
  166. package/kits/hub-game/models/avatar-2.pxmodel +27 -0
  167. package/kits/hub-game/models/avatar-3.pxmodel +22 -0
  168. package/kits/hub-game/models/bean/avatar-0.pxmodel +19 -0
  169. package/kits/hub-game/models/bean/avatar-1.pxmodel +24 -0
  170. package/kits/hub-game/models/bean/avatar-2.pxmodel +22 -0
  171. package/kits/hub-game/models/bean/avatar-3.pxmodel +24 -0
  172. package/kits/hub-game/models/blocky/avatar-0.pxmodel +21 -0
  173. package/kits/hub-game/models/blocky/avatar-1.pxmodel +30 -0
  174. package/kits/hub-game/models/blocky/avatar-2.pxmodel +28 -0
  175. package/kits/hub-game/models/blocky/avatar-3.pxmodel +27 -0
  176. package/kits/hub-game/models/pixel/avatar-0.pxmodel +24 -0
  177. package/kits/hub-game/models/pixel/avatar-1.pxmodel +16 -0
  178. package/kits/hub-game/models/pixel/avatar-2.pxmodel +19 -0
  179. package/kits/hub-game/models/pixel/avatar-3.pxmodel +23 -0
  180. package/kits/hub-game/package-lock.json +365 -0
  181. package/kits/hub-game/package.json +32 -0
  182. package/kits/hub-game/scenes/main.scene +318 -0
  183. package/kits/hub-game/scripts/check.mjs +339 -0
  184. package/kits/hub-game/scripts/fixtures/sdk-stub.mjs +3 -0
  185. package/kits/hub-game/scripts/gen-avatars-bean.mjs +748 -0
  186. package/kits/hub-game/scripts/gen-avatars-blocky.mjs +607 -0
  187. package/kits/hub-game/scripts/gen-avatars-pixel.mjs +771 -0
  188. package/kits/hub-game/scripts/gen-avatars.mjs +621 -0
  189. package/kits/hub-game/scripts/pack.mjs +192 -0
  190. package/kits/hub-game/scripts/test-actors.mjs +666 -0
  191. package/kits/hub-game/scripts/test-attention.mjs +103 -0
  192. package/kits/hub-game/scripts/test-avatar.mjs +472 -0
  193. package/kits/hub-game/scripts/test-ban-join.mjs +194 -0
  194. package/kits/hub-game/scripts/test-blocks.mjs +351 -0
  195. package/kits/hub-game/scripts/test-chat.mjs +98 -0
  196. package/kits/hub-game/scripts/test-classic.mjs +590 -0
  197. package/kits/hub-game/scripts/test-door-jump.mjs +131 -0
  198. package/kits/hub-game/scripts/test-door.mjs +56 -0
  199. package/kits/hub-game/scripts/test-grab.mjs +331 -0
  200. package/kits/hub-game/scripts/test-hub-ops.mjs +835 -0
  201. package/kits/hub-game/scripts/test-hub-trip.mjs +1310 -0
  202. package/kits/hub-game/scripts/test-idle.mjs +518 -0
  203. package/kits/hub-game/scripts/test-interest.mjs +413 -0
  204. package/kits/hub-game/scripts/test-keys.mjs +50 -0
  205. package/kits/hub-game/scripts/test-manifest.mjs +224 -0
  206. package/kits/hub-game/scripts/test-no-forms.mjs +16 -0
  207. package/kits/hub-game/scripts/test-npcs.mjs +714 -0
  208. package/kits/hub-game/scripts/test-pack.mjs +424 -0
  209. package/kits/hub-game/scripts/test-party.mjs +286 -0
  210. package/kits/hub-game/scripts/test-say.mjs +149 -0
  211. package/kits/hub-game/scripts/test-together.mjs +183 -0
  212. package/kits/hub-game/theme.style +3 -0
  213. package/kits/multiplayer-3d/castle.json +5 -5
  214. package/kits/multiplayer-3d/code/client/avatars.js +101 -1
  215. package/kits/multiplayer-3d/code/server/players.js +4 -1
  216. package/kits/multiplayer-3d/code/server/sceneBodies.js +27 -6
  217. package/kits/multiplayer-3d/code/server/world.js +20 -7
  218. package/kits/multiplayer-3d/code/systems/multiplayer.js +222 -11
  219. package/kits/physics-2d/castle.json +2 -2
  220. package/kits/physics-2d/engine/art.js +13 -0
  221. package/kits/physics-2d/engine/assets.js +4 -2
  222. package/kits/physics-2d/engine/scene.js +25 -5
  223. package/kits/physics-3d/CLAUDE.md +6 -1
  224. package/kits/physics-3d/castle.json +3 -3
  225. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +32 -4
  226. package/kits/physics-3d/engine3d/artobjects.js +2 -2
  227. package/kits/physics-3d/engine3d/materials.js +29 -1
  228. package/kits/physics-3d/engine3d/world3d.js +65 -1
  229. package/kits/physics-3d/systems/physics3d.js +5 -2
  230. package/kits/real-time/castle.json +2 -2
  231. package/kits/real-time/code/client/connection.js +77 -7
  232. package/kits/real-time/code/client/gameHooks.js +63 -3
  233. package/kits/real-time/code/client/messages.js +7 -0
  234. package/kits/real-time/code/server/gameHooks.js +24 -0
  235. package/kits/real-time/code/server/session.js +390 -22
  236. package/package.json +2 -2
@@ -1,4 +1,4 @@
1
- import type { MultiplayerDestinationAudience, MultiplayerJoinHint, MultiplayerSoloReason } from "./commands";
1
+ import type { HubHandoffResult, MultiplayerDestinationAudience, MultiplayerJoinHint, MultiplayerSoloReason } from "./commands";
2
2
  import { CastleError } from "./errors";
3
3
  import type { Json } from "./types";
4
4
  import { type MultiplayerPlayer, type MultiplayerCharacterDisclosure, type MultiplayerCharacterTurnStatus } from "./multiplayerProtocol";
@@ -11,6 +11,9 @@ export type MultiplayerJoinOptions = {
11
11
  mode: "party";
12
12
  } | {
13
13
  mode: "public";
14
+ } | {
15
+ mode: "hub";
16
+ handoff: HubHandoffResult;
14
17
  };
15
18
  export interface MultiplayerDestinationOptions {
16
19
  routeId: string;
@@ -79,7 +82,45 @@ export type MultiplayerWorldCharacterCommand = {
79
82
  type: "record_event";
80
83
  eventTypeId: string;
81
84
  data?: Json;
85
+ /** Characters that saw it (at most 4); each may act on its own about the recorder. */
86
+ witnesses?: string[];
87
+ } | MultiplayerEvaluateBeatsCommand | MultiplayerCompleteScheduledBeatCommand;
88
+ export type MultiplayerStoryOpportunity = {
89
+ type: "approach" | "room_entry" | "world_action";
90
+ id: string;
82
91
  };
92
+ export interface MultiplayerEvaluateBeatsCommand {
93
+ type: "evaluate_beats";
94
+ opportunityId: string;
95
+ opportunity: MultiplayerStoryOpportunity;
96
+ presentCharacterIds: string[];
97
+ }
98
+ export interface MultiplayerCompleteScheduledBeatCommand {
99
+ type: "complete_scheduled_beat";
100
+ deliveryId: string;
101
+ outcomeId: string;
102
+ }
103
+ export interface MultiplayerScheduledBeatSelection {
104
+ deliveryId: string;
105
+ beatId: string;
106
+ characterId: string;
107
+ openingText: string;
108
+ }
109
+ export interface MultiplayerScheduledBeatReason {
110
+ beatId: string;
111
+ status: "selected" | "expired" | "eligible" | "blocked";
112
+ reasonCodes: string[];
113
+ }
114
+ export interface MultiplayerEvaluateBeatsResult {
115
+ selection: MultiplayerScheduledBeatSelection | null;
116
+ reasons?: MultiplayerScheduledBeatReason[];
117
+ }
118
+ export interface MultiplayerCompleteScheduledBeatResult {
119
+ deliveryId: string;
120
+ outcomeId: string;
121
+ completed: true;
122
+ }
123
+ export type MultiplayerWorldCharacterCommandResultValue<Command extends MultiplayerWorldCharacterCommand> = Command extends MultiplayerEvaluateBeatsCommand ? MultiplayerEvaluateBeatsResult : Command extends MultiplayerCompleteScheduledBeatCommand ? MultiplayerCompleteScheduledBeatResult : Json;
83
124
  export type MultiplayerWorldCharacterQuery = {
84
125
  type: "inspect";
85
126
  } | {
@@ -90,7 +131,33 @@ export type MultiplayerWorldCharacterQuery = {
90
131
  characterId?: string;
91
132
  limit?: number;
92
133
  cursor?: string;
134
+ }
135
+ /** Autonomous-action notices after a cursor (world-visible). */
136
+ | {
137
+ type: "actions";
138
+ after?: string;
93
139
  };
140
+ /** One autonomous character decision in a shared world. */
141
+ export interface MultiplayerCharacterActionNotice {
142
+ characterId: string;
143
+ /** The participant the character acted about: the one whose deed it witnessed. */
144
+ participantId: string;
145
+ trigger: {
146
+ type: "witnessed";
147
+ id: string;
148
+ };
149
+ outcome: "acted" | "declined" | "failed";
150
+ actionId?: string;
151
+ variantId?: string;
152
+ eventOccurrenceId?: string;
153
+ probability?: number;
154
+ /** Feed cursor; pass the last one as `after` to read only newer notices. */
155
+ sequence: string;
156
+ }
157
+ export interface MultiplayerWorldCharacterActionsResult {
158
+ notices: MultiplayerCharacterActionNotice[];
159
+ after: string;
160
+ }
94
161
  /** Authenticated, participant-scoped projection of a shared character world. */
95
162
  export interface MultiplayerWorldCharacterInspectResult<Gameplay = unknown, SharedState = unknown, PrivateState = unknown, Source = unknown> {
96
163
  /** Durable identity used by gameplay holders and promise debtors. */
@@ -106,11 +173,11 @@ export interface MultiplayerWorldCharacterInspectResult<Gameplay = unknown, Shar
106
173
  }>;
107
174
  sources: Source[];
108
175
  }
109
- export interface MultiplayerWorldCharacterCommandResult {
176
+ export interface MultiplayerWorldCharacterCommandResult<Result = unknown> {
110
177
  operationId: string;
111
178
  status: "applied" | "ineligible";
112
179
  replayed: boolean;
113
- result: unknown;
180
+ result: Result;
114
181
  worldRevision: string;
115
182
  }
116
183
  export interface MultiplayerConnection {
@@ -123,17 +190,24 @@ export interface MultiplayerConnection {
123
190
  * `private_deck` and `no_server_bundle` are the creator's to fix.
124
191
  */
125
192
  readonly soloReason: MultiplayerSoloReason | null;
193
+ /**
194
+ * Whether the host brokers shared characters into this session (its hello
195
+ * advertised them): a shared-character world, or a hub place's layer with
196
+ * place characters. The character calls below refuse while this is false.
197
+ * Read it when needed: a reconnect can land on a host that says otherwise.
198
+ */
199
+ readonly sharedCharacters: boolean;
126
200
  /** Sends byte payloads as binary frames and all other payloads as JSON. */
127
201
  send(data: unknown): void;
128
202
  /** Requests one billed character turn through this authenticated world socket. */
129
203
  requestCharacterTurn(request: MultiplayerCharacterTurnRequest): Promise<MultiplayerCharacterTurnAdmission>;
130
204
  /** Recovers the durable status of a prior operation after reconnecting. */
131
205
  getCharacterTurnStatus(operationId: string): Promise<MultiplayerCharacterTurnStatusResult>;
132
- requestCharacterCommand(request: {
206
+ requestCharacterCommand<Command extends MultiplayerWorldCharacterCommand>(request: {
133
207
  requestId: string;
134
208
  operationId: string;
135
- command: MultiplayerWorldCharacterCommand;
136
- }): Promise<MultiplayerWorldCharacterCommandResult>;
209
+ command: Command;
210
+ }): Promise<MultiplayerWorldCharacterCommandResult<MultiplayerWorldCharacterCommandResultValue<Command>>>;
137
211
  readCharacters(request: {
138
212
  requestId: string;
139
213
  query: {
@@ -153,6 +227,12 @@ export interface MultiplayerConnection {
153
227
  leave(): void;
154
228
  }
155
229
  export interface CastleMultiplayerApi {
230
+ /**
231
+ * True on an SDK whose session server can address a hub place's shared
232
+ * characters from a layer (`session.characters` without `session.world`).
233
+ * Absent on older SDKs, so a kit can tell before joining.
234
+ */
235
+ readonly placeCharacters: true;
156
236
  join(options: MultiplayerJoinOptions): Promise<MultiplayerConnection>;
157
237
  joinHint(): Promise<MultiplayerJoinHint | null>;
158
238
  joinDestination(options: MultiplayerDestinationOptions): Promise<MultiplayerDestinationJoinResult>;
@@ -18,7 +18,12 @@ let nextCharacterStatusRequestId = 1;
18
18
  let activeConnection = null;
19
19
  let latestJoinAttempt = 0;
20
20
  let pendingDestinationJoin = null;
21
- export const Multiplayer = { join, joinHint, joinDestination };
21
+ export const Multiplayer = {
22
+ placeCharacters: true,
23
+ join,
24
+ joinHint,
25
+ joinDestination,
26
+ };
22
27
  async function joinHint() {
23
28
  try {
24
29
  return await hostRequest("multiplayer.getJoinHint", {});
@@ -30,18 +35,70 @@ async function joinHint() {
30
35
  }
31
36
  }
32
37
  async function join(options) {
33
- const params = joinParams(options);
38
+ const hub = hubJoin(options);
39
+ const request = hub
40
+ ? { command: "hub", nonce: hub.nonce }
41
+ : { command: "multiplayer.getSession", params: joinParams(options) };
34
42
  latestJoinAttempt += 1;
35
43
  cancelPendingDestinationJoin();
36
44
  activeConnection?.leave();
37
- const connection = new MultiplayerConnectionImpl({ command: "multiplayer.getSession", params }, () => {
45
+ const connection = new MultiplayerConnectionImpl(request, () => {
38
46
  if (activeConnection === connection)
39
47
  activeConnection = null;
40
48
  });
41
49
  activeConnection = connection;
42
- await connection.start();
50
+ await connection.start(hub ?? undefined);
51
+ // The host moves its place (and every place-scoped command with it) when the
52
+ // trip commits; the deck gets the connection once it has. A trip that did not
53
+ // commit leaves the player where they were, so its connection is closed.
54
+ if (!(await connection.hubCommitted())) {
55
+ connection.leave();
56
+ throw multiplayerError("MULTIPLAYER_UNAVAILABLE", "The hub trip could not be completed; the player is still where they were.", "Multiplayer.join");
57
+ }
43
58
  return connection;
44
59
  }
60
+ // A hub handoff is joined as it was acquired; it cannot be acquired again.
61
+ // The host answers `unavailable` while ghost is busy with this player; the
62
+ // trip stays pending there, so asking again is safe.
63
+ const HUB_COMMIT_RETRY_MS = [1_000, 2_000, 4_000, 8_000];
64
+ async function commitHubTrip(nonce, sessionId) {
65
+ for (let attempt = 0;; attempt++) {
66
+ let status;
67
+ try {
68
+ status = (await hostRequest("hub.commit", { nonce })).status;
69
+ }
70
+ catch (error) {
71
+ status = error instanceof CastleError ? error.code : "unavailable";
72
+ }
73
+ if (status === "committed")
74
+ return true;
75
+ const delay = HUB_COMMIT_RETRY_MS[attempt];
76
+ if ((status !== "unavailable" && status !== "CASTLE_HOST_UNAVAILABLE") || delay === undefined) {
77
+ console.warn(`Castle hub trip to ${sessionId} was not committed: ${status}`);
78
+ return false;
79
+ }
80
+ await pause(delay);
81
+ }
82
+ }
83
+ function hubJoin(options) {
84
+ if (!options || typeof options !== "object" || options.mode !== "hub")
85
+ return null;
86
+ const handoff = options.handoff;
87
+ if (!handoff ||
88
+ handoff.status !== "ok" ||
89
+ typeof handoff.url !== "string" ||
90
+ typeof handoff.nonce !== "string" ||
91
+ typeof handoff.sessionId !== "string") {
92
+ throw multiplayerError("INVALID_ARGUMENT", "Multiplayer.join({ mode: \"hub\" }) requires an ok result from Hub.go or Hub.back.", "Multiplayer.join");
93
+ }
94
+ return {
95
+ status: "ok",
96
+ url: handoff.url,
97
+ nonce: handoff.nonce,
98
+ sessionId: handoff.sessionId,
99
+ soloReason: null,
100
+ };
101
+ }
45
102
  async function joinDestination(options) {
46
103
  const params = destinationParams(options);
47
104
  const attempt = ++latestJoinAttempt;
@@ -129,6 +186,8 @@ class MultiplayerConnectionImpl {
129
186
  keepalive = null;
130
187
  reAcquisitionUsed = false;
131
188
  recovering = false;
189
+ hubSettled = false;
190
+ hubCommit = Promise.resolve(true);
132
191
  roster = null;
133
192
  sharedCharactersSupported = false;
134
193
  pendingCharacterRequests = new Map();
@@ -160,6 +219,9 @@ class MultiplayerConnectionImpl {
160
219
  get soloReason() {
161
220
  return this.currentSoloReason;
162
221
  }
222
+ get sharedCharacters() {
223
+ return this.sharedCharactersSupported;
224
+ }
163
225
  get voice() {
164
226
  return this.voiceImpl;
165
227
  }
@@ -168,6 +230,7 @@ class MultiplayerConnectionImpl {
168
230
  await this.acquire(initial);
169
231
  }
170
232
  catch (error) {
233
+ this.settleHub("cancel");
171
234
  const castleError = asCastleError(error);
172
235
  if (this.currentState !== "closed") {
173
236
  this.finish({ type: "error", error: castleError });
@@ -265,8 +328,26 @@ class MultiplayerConnectionImpl {
265
328
  leave() {
266
329
  if (this.currentState === "closed")
267
330
  return;
331
+ this.settleHub("cancel");
268
332
  this.finish({ type: "left" });
269
333
  }
334
+ // A hub trip is the host's to commit or cancel, once: committed when the
335
+ // destination first says hello, cancelled if the join ends before that. The
336
+ // acquisition is named by its nonce, which no other acquisition shares.
337
+ settleHub(outcome) {
338
+ if (this.request.command !== "hub" || this.hubSettled)
339
+ return;
340
+ this.hubSettled = true;
341
+ const nonce = this.request.nonce;
342
+ if (outcome === "cancel") {
343
+ hostRequest("hub.cancel", { nonce }).catch(() => { });
344
+ return;
345
+ }
346
+ this.hubCommit = commitHubTrip(nonce, this.currentSessionId);
347
+ }
348
+ hubCommitted() {
349
+ return this.hubCommit;
350
+ }
270
351
  matchesDestination(params) {
271
352
  return (this.currentState !== "closed" &&
272
353
  this.request.command === "multiplayer.joinDestination" &&
@@ -329,6 +410,8 @@ class MultiplayerConnectionImpl {
329
410
  }
330
411
  connectSolo(result) {
331
412
  this.solo = true;
413
+ // A solo session has no host, so no characters, whatever the last socket's hello offered.
414
+ this.sharedCharactersSupported = false;
332
415
  this.currentSoloReason = result.soloReason ?? "unavailable";
333
416
  this.currentPlayerId = "solo";
334
417
  this.currentSessionId = result.sessionId ?? "solo";
@@ -422,6 +505,7 @@ class MultiplayerConnectionImpl {
422
505
  // is backgrounded many times in a play, and each of those is its own outage;
423
506
  // without this the second one finds the budget spent and closes for good.
424
507
  this.reAcquisitionUsed = false;
508
+ this.settleHub("commit");
425
509
  this.transition("connected");
426
510
  this.startKeepalive();
427
511
  void this.voiceImpl.attach();
@@ -685,6 +769,11 @@ function cancelPendingDestinationJoin() {
685
769
  pending?.connection?.leave();
686
770
  }
687
771
  async function requestAcquisition(request) {
772
+ if (request.command === "hub") {
773
+ // The nonce was single-use and the trip is the host's; a hub session that
774
+ // cannot be reconnected to is left by going back through the door.
775
+ throw multiplayerError("MULTIPLAYER_CONNECTION_LOST", "A hub session cannot be acquired again. Go back through the door.");
776
+ }
688
777
  if (request.command === "multiplayer.getSession") {
689
778
  return hostRequest(request.command, request.params);
690
779
  }
@@ -778,6 +867,42 @@ function normalizeWorldCharacterCommandRequest(request) {
778
867
  type: "record_event",
779
868
  eventTypeId: boundedCharacterText(command.eventTypeId, 128, "command.eventTypeId", WORLD_CHARACTER_ID_MAX_CHARACTERS),
780
869
  ...(command.data === undefined ? {} : { data: normalizeJson(command.data, "command.data") }),
870
+ ...(command.witnesses === undefined ? {} : { witnesses: normalizeWitnesses(command.witnesses) }),
871
+ },
872
+ };
873
+ }
874
+ if (command.type === "evaluate_beats") {
875
+ const opportunity = command.opportunity;
876
+ if (!opportunity || typeof opportunity !== "object") {
877
+ throw characterError("INVALID_ARGUMENT", "command.opportunity must be an opportunity object.");
878
+ }
879
+ if (opportunity.type !== "approach" &&
880
+ opportunity.type !== "room_entry" &&
881
+ opportunity.type !== "world_action") {
882
+ throw characterError("INVALID_ARGUMENT", "command.opportunity.type is invalid.");
883
+ }
884
+ return {
885
+ requestId,
886
+ operationId,
887
+ command: {
888
+ type: "evaluate_beats",
889
+ opportunityId: boundedCharacterSafeKey(command.opportunityId, "command.opportunityId"),
890
+ opportunity: {
891
+ type: opportunity.type,
892
+ id: boundedCharacterSafeKey(opportunity.id, "command.opportunity.id"),
893
+ },
894
+ presentCharacterIds: boundedCharacterSafeKeys(command.presentCharacterIds, 16, "command.presentCharacterIds"),
895
+ },
896
+ };
897
+ }
898
+ if (command.type === "complete_scheduled_beat") {
899
+ return {
900
+ requestId,
901
+ operationId,
902
+ command: {
903
+ type: "complete_scheduled_beat",
904
+ deliveryId: boundedCharacterSafeKey(command.deliveryId, "command.deliveryId"),
905
+ outcomeId: boundedCharacterSafeKey(command.outcomeId, "command.outcomeId"),
781
906
  },
782
907
  };
783
908
  }
@@ -808,8 +933,20 @@ function normalizeWorldCharacterReadRequest(request) {
808
933
  },
809
934
  };
810
935
  }
936
+ if (query.type === "actions") {
937
+ if (query.after !== undefined && (typeof query.after !== "string" || !/^\d{1,18}$/.test(query.after))) {
938
+ throw characterError("INVALID_ARGUMENT", "Character actions cursor must be a sequence string.");
939
+ }
940
+ return { requestId, query: { type: "actions", ...(query.after === undefined ? {} : { after: query.after }) } };
941
+ }
811
942
  throw characterError("INVALID_ARGUMENT", "Unknown shared character query type.");
812
943
  }
944
+ function normalizeWitnesses(value) {
945
+ if (!Array.isArray(value) || value.length > 4) {
946
+ throw characterError("INVALID_ARGUMENT", "command.witnesses must be at most 4 character ids.");
947
+ }
948
+ return value.map((item, index) => boundedCharacterText(item, 128, `command.witnesses[${index}]`, WORLD_CHARACTER_ID_MAX_CHARACTERS));
949
+ }
813
950
  function normalizeJson(value, field) {
814
951
  try {
815
952
  const text = JSON.stringify(value);
@@ -831,6 +968,22 @@ function boundedCharacterIds(value, maxItems, field, maxCharacters = 128) {
831
968
  }
832
969
  return ids;
833
970
  }
971
+ function boundedCharacterSafeKeys(value, maxItems, field) {
972
+ if (!Array.isArray(value) || value.length > maxItems) {
973
+ throw characterError("INVALID_ARGUMENT", `${field} may contain at most ${maxItems} ids.`);
974
+ }
975
+ const ids = value.map((item) => boundedCharacterSafeKey(item, field));
976
+ if (new Set(ids).size !== ids.length) {
977
+ throw characterError("INVALID_ARGUMENT", `${field} may not contain duplicate ids.`);
978
+ }
979
+ return ids;
980
+ }
981
+ function boundedCharacterSafeKey(value, field) {
982
+ if (typeof value !== "string" || !/^[A-Za-z0-9_-]{1,64}$/.test(value)) {
983
+ throw characterError("INVALID_ARGUMENT", `${field} must be a safe key of at most 64 characters.`);
984
+ }
985
+ return value;
986
+ }
834
987
  function boundedCharacterText(value, maxBytes, field, maxCharacters = maxBytes) {
835
988
  if (typeof value !== "string" ||
836
989
  value.length === 0 ||
@@ -0,0 +1,169 @@
1
+ import type { PlatformHandle, PlatformHubResultShape } from "./platformHandle";
2
+ export type MultiplayerHubOutcome = "win" | "lose" | "draw";
3
+ export type MultiplayerHubResultShape = PlatformHubResultShape;
4
+ /** Where a player came in through a hub door: ghost's word, never a client's. */
5
+ export interface MultiplayerHubArrival {
6
+ /** The deck of the place the player came from. */
7
+ readonly fromDeckId: string;
8
+ /** The door of this place the player arrived by, when the door row names one. */
9
+ readonly doorId: string | null;
10
+ }
11
+ export interface MultiplayerHubResultInput {
12
+ /** This session's place; refused when it names another. */
13
+ place?: string;
14
+ outcome: MultiplayerHubOutcome;
15
+ score?: number;
16
+ stats?: Record<string, number | string>;
17
+ }
18
+ export interface MultiplayerHubRecord {
19
+ deckId: string;
20
+ place: string;
21
+ title: string | null;
22
+ plays: number;
23
+ outcomes: {
24
+ win: number;
25
+ lose: number;
26
+ draw: number;
27
+ };
28
+ bestScore: number | null;
29
+ unit: string | null;
30
+ better: "higher" | "lower" | null;
31
+ winStreak: number;
32
+ lastOutcome: MultiplayerHubOutcome | null;
33
+ lastScore: number | null;
34
+ lastAt: string;
35
+ }
36
+ export interface MultiplayerHubResultRow {
37
+ deckId: string;
38
+ place: string;
39
+ title: string | null;
40
+ outcome: MultiplayerHubOutcome;
41
+ score: number | null;
42
+ unit: string | null;
43
+ better: "higher" | "lower" | null;
44
+ stats: Record<string, number | string>;
45
+ at: string;
46
+ }
47
+ export interface MultiplayerHubReportReceipt {
48
+ recorded: boolean;
49
+ /** Why nothing was recorded: ghost already holds this visit's result. */
50
+ reason?: "duplicate";
51
+ record?: MultiplayerHubRecord;
52
+ }
53
+ /**
54
+ * A wearable on the player's platform avatar, drawn by the hub kit in every hub
55
+ * place: `kind` matches /^[a-z][a-z0-9-]{0,23}$/ (the kit draws the kinds it
56
+ * knows), `color` is '#rrggbb', `rarity` an integer 0-9.
57
+ */
58
+ export interface MultiplayerHubWearable {
59
+ kind: string;
60
+ color: string;
61
+ rarity: number;
62
+ }
63
+ export interface MultiplayerHubWearReceipt {
64
+ /** What the player now wears; null when cleared. */
65
+ wearable: MultiplayerHubWearable | null;
66
+ }
67
+ export interface MultiplayerHubPadUpdateInput {
68
+ /** A pad door of this place, from ghost's door table. */
69
+ doorId: string;
70
+ /** This gathering's id; a fired pad's group is fixed, so the next one needs a new id. */
71
+ padId: string;
72
+ /** Who stands on the pad. The host keeps only players connected to this session. */
73
+ memberUserIds: readonly string[];
74
+ /** Send the pad's players through the door now. */
75
+ fire?: boolean;
76
+ }
77
+ export interface MultiplayerHubPadUpdateResult {
78
+ status: "gathering" | "fired";
79
+ members: string[];
80
+ }
81
+ export interface MultiplayerHubResultsReadInput {
82
+ /** Players of this session to read; anyone not connected is dropped by the host. */
83
+ userIds?: readonly string[];
84
+ /** Doors of this place whose best scores to read, at most 16. */
85
+ doorIds?: readonly string[];
86
+ }
87
+ export interface MultiplayerHubPlayerResults {
88
+ /** Newest five results from the last hour. */
89
+ recent: MultiplayerHubResultRow[];
90
+ /** Newest twenty per-place records. */
91
+ records: MultiplayerHubRecord[];
92
+ /** The player's platform avatar, chosen or default; null when ghost has none to say. */
93
+ avatar: number | null;
94
+ /** The player's wearable; null when none. Absent from a ghost older than wearables. */
95
+ wearable?: MultiplayerHubWearable | null;
96
+ }
97
+ export interface MultiplayerHubBoard {
98
+ toDeckId: string;
99
+ title: string | null;
100
+ unit: string | null;
101
+ better: "higher" | "lower" | null;
102
+ top: {
103
+ userId: string;
104
+ username: string;
105
+ score: number;
106
+ at: string;
107
+ }[];
108
+ /** Featured today (the daily rotation, or set by hand). */
109
+ featured?: boolean;
110
+ /**
111
+ * The door row's group: the pad's minimum, the most that go through, and whether
112
+ * later arrivals join a running instance. Null where the row does not say; absent
113
+ * from a ghost older than these fields.
114
+ */
115
+ minPlayers?: number | null;
116
+ maxPlayers?: number | null;
117
+ lateJoin?: boolean;
118
+ /**
119
+ * Live presence behind the door, counts only and never who: players in the
120
+ * destination's public sessions from every town layer and entry, and how many of
121
+ * those sessions are open. Zero when nobody is inside; for an event gate, the
122
+ * current event's game. Absent from a ghost older than these fields.
123
+ */
124
+ playersInside?: number;
125
+ instancesOpen?: number;
126
+ }
127
+ export interface MultiplayerHubResultsRead {
128
+ players: Record<string, MultiplayerHubPlayerResults>;
129
+ boards: Record<string, MultiplayerHubBoard>;
130
+ }
131
+ /**
132
+ * The hub place this session runs, as ghost pinned it from the deck's published
133
+ * castle.json `hub` block. `session.hub` is null on a host without hub support
134
+ * and for a deck that declares no hub block.
135
+ */
136
+ export interface MultiplayerServerHub {
137
+ readonly place: string | null;
138
+ readonly title: string | null;
139
+ readonly result: MultiplayerHubResultShape | null;
140
+ /** How this player came in, when ghost placed them through a door; null otherwise. */
141
+ arrival(playerId: string): MultiplayerHubArrival | null;
142
+ /**
143
+ * Records a signed-in player's result for this visit, once. The host checks it
144
+ * against the published shape; ghost keeps it only for a place behind a curated
145
+ * door. Rejects with the platform's `CAULDRON_HUB_*` code.
146
+ */
147
+ reportResult(playerId: string, result: MultiplayerHubResultInput): Promise<MultiplayerHubReportReceipt>;
148
+ /** Names who stands on a pad, and fires it. */
149
+ updatePad(input: MultiplayerHubPadUpdateInput): Promise<MultiplayerHubPadUpdateResult>;
150
+ /** Results, avatars and wearables of players here, and the boards of this place's doors. */
151
+ readResults(input?: MultiplayerHubResultsReadInput): Promise<MultiplayerHubResultsRead>;
152
+ /**
153
+ * Puts a wearable on a signed-in player's platform avatar in every hub place, or
154
+ * clears it with null; latest wins. Castle takes it only from a curated hub place.
155
+ * Rejects with a `CAULDRON_HUB_*` code (`CAULDRON_HUB_UNAVAILABLE` on a runtime
156
+ * without it).
157
+ */
158
+ wear(playerId: string, wearable: MultiplayerHubWearable | null): Promise<MultiplayerHubWearReceipt>;
159
+ /**
160
+ * Whether a block hides these two players from each other: either one blocked
161
+ * the other, in either direction. Symmetric. The block lists themselves stay
162
+ * with the host and this wrapper; a place server learns only the pair, and
163
+ * only for players who are both here. False on hosts that send none.
164
+ */
165
+ hiddenPair(playerIdA: string, playerIdB: string): boolean;
166
+ }
167
+ export declare function hubArrival(raw: unknown): MultiplayerHubArrival | null;
168
+ export declare function recordHiddenUserIds(hidden: Map<string, ReadonlySet<string>>, playerId: string, raw: unknown): void;
169
+ export declare function createServerHub(platformHandle: PlatformHandle, arrivals: ReadonlyMap<string, MultiplayerHubArrival>, hiddenPair?: (playerIdA: string, playerIdB: string) => boolean): MultiplayerServerHub | null;