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
@@ -0,0 +1,125 @@
1
+ import { CastleError } from "../errors";
2
+ const DOOR_ID = /^[A-Za-z0-9_.:-]{1,64}$/;
3
+ export function hubArrival(raw) {
4
+ if (!raw || typeof raw !== "object")
5
+ return null;
6
+ const { fromDeckId, doorId } = raw;
7
+ if (typeof fromDeckId !== "string" || fromDeckId.length === 0 || fromDeckId.length > 64) {
8
+ return null;
9
+ }
10
+ return Object.freeze({
11
+ fromDeckId,
12
+ doorId: typeof doorId === "string" && DOOR_ID.test(doorId) ? doorId : null,
13
+ });
14
+ }
15
+ // The co-present users a block hides from a joining hub player, as the host
16
+ // sends them on the join (`player.hiddenUserIds`): decimal user ids, or null
17
+ // when there are none or the list is malformed.
18
+ const HIDDEN_USER_ID = /^\d{1,20}$/;
19
+ const HIDDEN_USER_IDS_MAX = 1000;
20
+ export function recordHiddenUserIds(hidden, playerId, raw) {
21
+ const ids = hubHiddenUserIds(raw);
22
+ if (ids) {
23
+ hidden.set(playerId, ids);
24
+ }
25
+ else {
26
+ hidden.delete(playerId);
27
+ }
28
+ }
29
+ function hubHiddenUserIds(raw) {
30
+ if (!raw || typeof raw !== "object")
31
+ return null;
32
+ const list = raw.hiddenUserIds;
33
+ if (!Array.isArray(list) || list.length === 0)
34
+ return null;
35
+ const ids = new Set();
36
+ for (const id of list.slice(0, HIDDEN_USER_IDS_MAX)) {
37
+ if (typeof id === "string" && HIDDEN_USER_ID.test(id))
38
+ ids.add(id);
39
+ }
40
+ return ids.size > 0 ? ids : null;
41
+ }
42
+ export function createServerHub(platformHandle, arrivals, hiddenPair = () => false) {
43
+ const pinned = platformHandle.hub;
44
+ if (!pinned ||
45
+ typeof platformHandle.hubResult !== "function" ||
46
+ typeof platformHandle.hubPadUpdate !== "function" ||
47
+ typeof platformHandle.hubResultsRead !== "function") {
48
+ return null;
49
+ }
50
+ const call = async (op, args) => {
51
+ const raw = await platformHandle[op](JSON.stringify(args));
52
+ let parsed;
53
+ try {
54
+ parsed = JSON.parse(raw);
55
+ }
56
+ catch {
57
+ parsed = null;
58
+ }
59
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
60
+ throw new CastleError({
61
+ code: "CAULDRON_HUB_INVALID_RESPONSE",
62
+ message: `The platform returned an invalid ${op} response.`,
63
+ operation: `session.hub.${op}`,
64
+ });
65
+ }
66
+ return parsed;
67
+ };
68
+ return Object.freeze({
69
+ place: typeof pinned.place === "string" ? pinned.place : null,
70
+ title: typeof pinned.title === "string" ? pinned.title : null,
71
+ result: pinned.result ?? null,
72
+ arrival(playerId) {
73
+ return arrivals.get(playerId) ?? null;
74
+ },
75
+ hiddenPair(playerIdA, playerIdB) {
76
+ return hiddenPair(playerIdA, playerIdB);
77
+ },
78
+ async reportResult(playerId, result) {
79
+ const { place, outcome, score, stats } = result ?? {};
80
+ return (await call("hubResult", {
81
+ playerId,
82
+ ...(place === undefined ? {} : { place }),
83
+ outcome,
84
+ ...(score === undefined || score === null ? {} : { score }),
85
+ ...(stats === undefined ? {} : { stats }),
86
+ }));
87
+ },
88
+ async updatePad(input) {
89
+ return (await call("hubPadUpdate", {
90
+ doorId: input?.doorId,
91
+ padId: input?.padId,
92
+ memberUserIds: [...(input?.memberUserIds ?? [])],
93
+ ...(input?.fire === true ? { fire: true } : {}),
94
+ }));
95
+ },
96
+ async readResults(input = {}) {
97
+ const read = await call("hubResultsRead", {
98
+ ...(input.userIds ? { userIds: [...input.userIds] } : {}),
99
+ ...(input.doorIds ? { doorIds: [...input.doorIds] } : {}),
100
+ });
101
+ return {
102
+ players: (read.players ?? {}),
103
+ boards: (read.boards ?? {}),
104
+ };
105
+ },
106
+ async wear(playerId, wearable) {
107
+ if (typeof platformHandle.hubWear !== "function") {
108
+ throw new CastleError({
109
+ code: "CAULDRON_HUB_UNAVAILABLE",
110
+ message: "This host's runtime cannot change wearables.",
111
+ operation: "session.hub.hubWear",
112
+ });
113
+ }
114
+ const receipt = await call("hubWear", {
115
+ playerId,
116
+ wearable: wearable === null || wearable === undefined
117
+ ? null
118
+ : { kind: wearable.kind, color: wearable.color, rarity: wearable.rarity },
119
+ });
120
+ return {
121
+ wearable: (receipt.wearable ?? null),
122
+ };
123
+ },
124
+ });
125
+ }
@@ -1,4 +1,5 @@
1
1
  import type { Json } from "../types";
2
+ import type { MultiplayerWorldCharacterCommand } from "../multiplayer";
2
3
  export type MultiplayerSessionMode = "named" | "party" | "public";
3
4
  export interface PlayerIdentity {
4
5
  userId: string;
@@ -13,6 +14,16 @@ export interface PlatformSessionConfig {
13
14
  readonly tickRate: number;
14
15
  readonly maxPlayers: number;
15
16
  readonly world?: PlatformWorldSnapshot;
17
+ /**
18
+ * True when the host brokers a hub place's shared characters into this
19
+ * session without a world (a layer of the place). Absent on hosts that do not.
20
+ */
21
+ readonly placeCharacters?: boolean;
22
+ /**
23
+ * The place this session was started for, stamped by a host that placed it
24
+ * through a door (the hub's door table). Absent on hosts that do not.
25
+ */
26
+ readonly place?: string;
16
27
  }
17
28
  export interface PlatformWorldCheckpoint {
18
29
  version: number;
@@ -21,6 +32,11 @@ export interface PlatformWorldCheckpoint {
21
32
  export interface PlatformWorldSnapshot {
22
33
  revision: string;
23
34
  checkpoint: PlatformWorldCheckpoint | null;
35
+ /** Selected destination timing policy, stamped by hosts that support catch-up. */
36
+ worldTime?: PlatformWorldTimeConfig;
37
+ }
38
+ export interface PlatformWorldTimeConfig {
39
+ advance: "wallClock";
24
40
  }
25
41
  export interface PlatformHandle {
26
42
  send(connId: string, text: string): void;
@@ -28,7 +44,7 @@ export interface PlatformHandle {
28
44
  sendBinary?(connId: string, bytes: Uint8Array | ArrayBuffer): void;
29
45
  broadcastBinary?(bytes: Uint8Array | ArrayBuffer): void;
30
46
  disconnect(connId: string, code: string | number): void;
31
- on(event: "join", callback: (connId: string, player: PlayerIdentity) => unknown): void;
47
+ on(event: "join", callback: (connId: string, player: PlayerIdentity, arrival?: PlatformHubArrival, experimentVariants?: Record<string, string>) => unknown): void;
32
48
  on(event: "leave", callback: (connId: string) => unknown): void;
33
49
  on(event: "message", callback: (connId: string, text: string) => unknown): void;
34
50
  on(event: "binaryMessage", callback: (connId: string, bytes: Uint8Array) => unknown): void;
@@ -58,8 +74,39 @@ export interface PlatformHandle {
58
74
  worldCharacterRuntimeCreate?(argsJson: string): Promise<string>;
59
75
  worldCharacterRuntimeList?(): Promise<string>;
60
76
  worldCharacterReject?(grantId: string, code?: string): void;
77
+ /**
78
+ * The hub place this session runs, as ghost pinned it from the published
79
+ * castle.json `hub` block. Present only when the host services the hub ops
80
+ * below, so a deck without a hub block never sees any of them.
81
+ */
82
+ readonly hub?: Readonly<PlatformHubPlace>;
83
+ hubResult?(argsJson: string): Promise<string>;
84
+ hubPadUpdate?(argsJson: string): Promise<string>;
85
+ hubResultsRead?(argsJson: string): Promise<string>;
86
+ /** Absent on a runtime older than wearables (contract v1.4). */
87
+ hubWear?(argsJson: string): Promise<string>;
61
88
  readonly config: PlatformSessionConfig;
62
89
  }
90
+ export interface PlatformHubResultShape {
91
+ outcomes: ("win" | "lose" | "draw")[];
92
+ score: {
93
+ unit: "ms" | "s" | "points";
94
+ better: "higher" | "lower";
95
+ min: number;
96
+ max: number;
97
+ } | null;
98
+ stats: Record<string, "number" | "string">;
99
+ }
100
+ export interface PlatformHubPlace {
101
+ place?: string;
102
+ title?: string | null;
103
+ result?: PlatformHubResultShape | null;
104
+ }
105
+ /** Where a player came in, when ghost placed them through a hub door. Ghost's word, not a client's. */
106
+ export interface PlatformHubArrival {
107
+ fromDeckId: string;
108
+ doorId?: string;
109
+ }
63
110
  export interface PlatformWorldCharacterCommand {
64
111
  grantId: string;
65
112
  requestId: string;
@@ -67,7 +114,7 @@ export interface PlatformWorldCharacterCommand {
67
114
  speaker: PlayerIdentity & {
68
115
  playerId: string;
69
116
  };
70
- command: unknown;
117
+ command: MultiplayerWorldCharacterCommand;
71
118
  }
72
119
  export interface PlatformWorldCharacterRead {
73
120
  grantId: string;
@@ -95,6 +95,59 @@ export interface DeliverCharacterKnowledgeInput {
95
95
  claimIds: string[];
96
96
  source: CharacterKnowledgeSource;
97
97
  }
98
+ /**
99
+ * A character acting on its own after a command woke it (autonomous character
100
+ * actions, bundles with `characterActions`). `declined` covers choosing
101
+ * nothing, too little confidence for its temperament, and an action no longer
102
+ * eligible when it committed; `failed` is a decision-model error.
103
+ */
104
+ export type CharacterActionNotice = {
105
+ characterId: string;
106
+ /** `id` is the event occurrence, routine, or promise id. */
107
+ trigger: {
108
+ type: "witnessed" | "routine" | "promise_due";
109
+ id: string;
110
+ };
111
+ outcome: "acted" | "declined" | "failed";
112
+ /** When acted. */
113
+ actionId?: string;
114
+ /** When acted with a parameterized action's variant. */
115
+ variantId?: string;
116
+ /** The action's world event, when it has one. */
117
+ eventOccurrenceId?: string;
118
+ /** The decision model's probability for its choice. */
119
+ probability?: number;
120
+ };
121
+ export type CharacterGameStateResult = {
122
+ revision: number;
123
+ state: {
124
+ [key: string]: string | number | boolean;
125
+ };
126
+ promiseOutcomes: Array<{
127
+ id: string;
128
+ status: "fulfilled" | "broken";
129
+ due: number;
130
+ resolvedAtGameTime: number;
131
+ }>;
132
+ /** At most 8, omitted when no character acted, declined, or failed. */
133
+ characterActions?: CharacterActionNotice[];
134
+ };
135
+ export type CharacterGameStateOperation = Omit<CharacterOperation, "result"> & {
136
+ result: CharacterGameStateResult | null;
137
+ };
138
+ export type CharacterKnowledgeDeliveryResult = {
139
+ deliveryId: string;
140
+ recipientCharacterId: string;
141
+ eventOccurrenceId: string;
142
+ claimIds: string[];
143
+ source: CharacterKnowledgeSource;
144
+ deliveredAt: string;
145
+ /** At most 8, omitted when no character acted, declined, or failed. */
146
+ characterActions?: CharacterActionNotice[];
147
+ };
148
+ export type CharacterKnowledgeDeliveryOperation = Omit<CharacterOperation, "result"> & {
149
+ result: CharacterKnowledgeDeliveryResult | null;
150
+ };
98
151
  export interface CompleteCharacterBeatInput {
99
152
  operationId: string;
100
153
  characterId: string;
@@ -189,10 +242,10 @@ export interface ServerPlaythroughCharacters {
189
242
  /** Queues a funded turn whose admitted listeners are fixed at enqueue time. */
190
243
  send(input: SendCharacterInput): Promise<CharacterOperation>;
191
244
  recordEvent(input: RecordCharacterEventInput): Promise<CharacterOperation>;
192
- setGameState(input: SetCharacterGameStateInput): Promise<CharacterOperation>;
245
+ setGameState(input: SetCharacterGameStateInput): Promise<CharacterGameStateOperation>;
193
246
  shareClaim(input: ShareCharacterClaimInput): Promise<CharacterOperation>;
194
247
  inspect(): Promise<Json>;
195
- deliverKnowledge(input: DeliverCharacterKnowledgeInput): Promise<CharacterOperation>;
248
+ deliverKnowledge(input: DeliverCharacterKnowledgeInput): Promise<CharacterKnowledgeDeliveryOperation>;
196
249
  completeBeat(input: CompleteCharacterBeatInput): Promise<CharacterOperation>;
197
250
  evaluateInformation(input: EvaluateCharacterInformationInput): Promise<CharacterInformationEvaluationOperation>;
198
251
  evaluateBeats(input: EvaluateCharacterBeatsInput): Promise<CharacterBeatEvaluationOperation>;
@@ -1,8 +1,11 @@
1
1
  import type { MultiplayerSessionMode, PlatformHandle, PlayerIdentity } from "./platformHandle";
2
2
  import type { Json } from "../types";
3
+ import type { MultiplayerWorldCharacterCommand, MultiplayerWorldCharacterCommandResult, MultiplayerWorldCharacterCommandResultValue } from "../multiplayer";
3
4
  import { type ServerStorage } from "./storage";
4
- export type { MultiplayerSessionMode, PlatformHandle, PlatformSessionConfig, PlatformWorldCheckpoint, PlatformWorldSnapshot, PlayerIdentity, } from "./platformHandle";
5
- export type { CharacterKnowledgeSource, CompleteCharacterBeatInput, DeliverCharacterKnowledgeInput, RecordCharacterEventInput, SetCharacterGameStateInput, ShareCharacterClaimInput, ServerStorage, ServerStorageBoard, ServerStorageBoardScore, ServerStorageListEntry, ServerStorageListOptions, ServerStorageListPage, ServerPlaythrough, ServerPlaythroughCharacters, ServerCharacterHistoryOptions, ServerStorageScope, } from "./storage";
5
+ import { type MultiplayerHubArrival, type MultiplayerServerHub } from "./hub";
6
+ export type { MultiplayerSessionMode, PlatformHandle, PlatformSessionConfig, PlatformWorldCheckpoint, PlatformWorldSnapshot, PlatformWorldTimeConfig, PlayerIdentity, } from "./platformHandle";
7
+ export type { MultiplayerHubArrival, MultiplayerHubBoard, MultiplayerHubOutcome, MultiplayerHubPadUpdateInput, MultiplayerHubPadUpdateResult, MultiplayerHubPlayerResults, MultiplayerHubRecord, MultiplayerHubReportReceipt, MultiplayerHubResultInput, MultiplayerHubResultRow, MultiplayerHubResultShape, MultiplayerHubResultsRead, MultiplayerHubResultsReadInput, MultiplayerHubWearable, MultiplayerHubWearReceipt, MultiplayerServerHub, } from "./hub";
8
+ 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";
6
9
  export interface MultiplayerServerPlayer extends PlayerIdentity {
7
10
  playerId: string;
8
11
  readonly participantId: string;
@@ -15,6 +18,12 @@ export interface MultiplayerServerSession {
15
18
  readonly sessionId: string;
16
19
  readonly deckId: string;
17
20
  readonly mode: MultiplayerSessionMode;
21
+ /**
22
+ * The place the host started this session for (a hub door's destination, or
23
+ * the hub place ghost pinned the session to), or null when the host stamped
24
+ * none. Never set from a client.
25
+ */
26
+ readonly place: string | null;
18
27
  /**
19
28
  * Deck storage that outlives the session. Nothing else here does: a session ends
20
29
  * when its last player leaves and its memory goes with it.
@@ -22,6 +31,27 @@ export interface MultiplayerServerSession {
22
31
  readonly storage: ServerStorage;
23
32
  /** A durable checkpoint for an opted-in persistent destination. */
24
33
  readonly world: MultiplayerServerWorld | null;
34
+ /**
35
+ * The shared characters this session can address: `session.world.characters`
36
+ * in a shared-character world (the same object), or a hub place's characters
37
+ * on one of its layers, where `session.world` stays null. Null everywhere else.
38
+ */
39
+ readonly characters: MultiplayerServerWorldCharacters | null;
40
+ /**
41
+ * The hub place this session runs (castle.json `hub`, as ghost pinned it):
42
+ * results, pads and arrivals. Null for a deck without a hub block and on hosts
43
+ * without hub support.
44
+ */
45
+ readonly hub: MultiplayerServerHub | null;
46
+ /**
47
+ * The variant a connected player has in the A/B experiment `name`, or null
48
+ * when they are in no such experiment (or have left). Castle's server
49
+ * resolved it and the host delivered it with the join, so it is the same arm
50
+ * the player's page reads and nothing a client sent.
51
+ */
52
+ experiment(player: MultiplayerServerPlayer | string, name: string): string | null;
53
+ /** Every experiment a connected player is in, `{ name: variant }`. */
54
+ experiments(player: MultiplayerServerPlayer | string): Record<string, string>;
25
55
  /** Sends bytes as a binary message and all other payloads as JSON. */
26
56
  send(playerId: string, data: unknown): void;
27
57
  /** Broadcasts bytes as a binary message and all other payloads as JSON. */
@@ -53,10 +83,26 @@ export interface MultiplayerServerWorld {
53
83
  read(): Promise<MultiplayerWorldSnapshot>;
54
84
  /** Commits exactly against expectedRevision; conflicts never partially write. */
55
85
  commit(input: MultiplayerWorldCommitInput): Promise<MultiplayerWorldCommitReceipt>;
86
+ catchUp(options: MultiplayerWorldCatchUpOptions): Promise<MultiplayerWorldCatchUpResult>;
56
87
  readonly journal: MultiplayerServerWorldJournal;
57
88
  readonly participants: MultiplayerServerWorldParticipants;
89
+ readonly notifications: MultiplayerServerWorldNotifications;
58
90
  readonly characters: MultiplayerServerWorldCharacters;
59
91
  }
92
+ export interface MultiplayerWorldCatchUpOptions {
93
+ key?: string;
94
+ maxElapsedMs?: number;
95
+ apply(input: {
96
+ elapsedMs: number;
97
+ now: number;
98
+ checkpoint: MultiplayerWorldCheckpoint | null;
99
+ }): MultiplayerWorldCheckpoint | Promise<MultiplayerWorldCheckpoint>;
100
+ }
101
+ export interface MultiplayerWorldCatchUpResult {
102
+ applied: boolean;
103
+ elapsedMs: number;
104
+ revision: string;
105
+ }
60
106
  export interface MultiplayerWorldJournalAppendInput {
61
107
  operationId: string;
62
108
  entries: readonly MultiplayerWorldJournalAppendEntry[];
@@ -112,6 +158,31 @@ export interface MultiplayerWorldParticipantsReadResult {
112
158
  export interface MultiplayerServerWorldParticipants {
113
159
  read(options?: MultiplayerWorldParticipantsReadOptions): Promise<MultiplayerWorldParticipantsReadResult>;
114
160
  }
161
+ export interface MultiplayerWorldNotificationNotifyInput {
162
+ key: string;
163
+ participantIds: readonly string[];
164
+ templateId: string;
165
+ slots?: Readonly<Record<string, string>>;
166
+ at?: string;
167
+ expiresAt?: string;
168
+ }
169
+ export interface MultiplayerWorldNotificationNotifyResult {
170
+ key: string;
171
+ accepted: number;
172
+ skipped: number;
173
+ limited: number;
174
+ }
175
+ export interface MultiplayerWorldNotificationCancelInput {
176
+ key: string;
177
+ participantIds?: readonly string[];
178
+ }
179
+ export interface MultiplayerWorldNotificationCancelResult {
180
+ cancelled: number;
181
+ }
182
+ export interface MultiplayerServerWorldNotifications {
183
+ notify(input: MultiplayerWorldNotificationNotifyInput): Promise<MultiplayerWorldNotificationNotifyResult>;
184
+ cancel(input: MultiplayerWorldNotificationCancelInput): Promise<MultiplayerWorldNotificationCancelResult>;
185
+ }
115
186
  export interface MultiplayerServerWorldCharacters {
116
187
  create(input: MultiplayerWorldRuntimeCharacterCreateInput): Promise<MultiplayerWorldRuntimeCharacterCreateReceipt>;
117
188
  list(): Promise<MultiplayerWorldCharacterList>;
@@ -155,14 +226,21 @@ export interface MultiplayerWorldRuntimeCharacterCreateReceipt {
155
226
  export interface MultiplayerWorldCharacterList {
156
227
  characters: readonly MultiplayerWorldCharacterSummary[];
157
228
  }
158
- export interface MultiplayerWorldCharacterCommandRequest {
229
+ interface MultiplayerWorldCharacterCommandRequestFor<Command extends MultiplayerWorldCharacterCommand> {
230
+ /** Command discriminator mirrored at the request level for TypeScript narrowing. */
231
+ readonly type: Command["type"];
159
232
  readonly requestId: string;
160
233
  readonly operationId: string;
161
234
  readonly speaker: MultiplayerServerPlayer;
162
- readonly command: Readonly<Record<string, unknown>>;
163
- apply(): Promise<unknown>;
235
+ readonly command: Readonly<Command>;
236
+ apply(): Promise<MultiplayerWorldCharacterCommandResult<MultiplayerWorldCharacterCommandResultValue<Command>>>;
164
237
  reject(code?: string): void;
165
238
  }
239
+ export type MultiplayerWorldCharacterCommandRequest = {
240
+ [Type in MultiplayerWorldCharacterCommand["type"]]: MultiplayerWorldCharacterCommandRequestFor<Extract<MultiplayerWorldCharacterCommand, {
241
+ type: Type;
242
+ }>>;
243
+ }[MultiplayerWorldCharacterCommand["type"]];
166
244
  export interface MultiplayerWorldCharacterReadRequest {
167
245
  readonly requestId: string;
168
246
  readonly speaker: MultiplayerServerPlayer;
@@ -194,7 +272,8 @@ export interface MultiplayerWorldCharacterTurn {
194
272
  type CallbackResult = unknown;
195
273
  export interface MultiplayerServerCallbacks {
196
274
  onStart?: (session: MultiplayerServerSession) => CallbackResult;
197
- onPlayerJoin?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer) => CallbackResult;
275
+ /** `arrival` is set when ghost placed the player through a hub door. */
276
+ onPlayerJoin?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer, arrival: MultiplayerHubArrival | null) => CallbackResult;
198
277
  onPlayerLeave?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer) => CallbackResult;
199
278
  /** Receives binary messages as Uint8Array values and JSON messages otherwise. */
200
279
  onMessage?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer, data: unknown) => CallbackResult;