castle-web-cli 0.4.229 → 0.4.230

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (232) hide show
  1. package/dist/agent-prompts.d.ts +2 -0
  2. package/dist/agent-prompts.js +16 -8
  3. package/dist/agent.d.ts +2 -0
  4. package/dist/agent.js +21 -21
  5. package/dist/api.d.ts +28 -2
  6. package/dist/api.js +74 -16
  7. package/dist/castle-host/host.d.ts +91 -0
  8. package/dist/castle-host/host.js +779 -3
  9. package/dist/castleJson.d.ts +44 -0
  10. package/dist/castleJson.js +131 -0
  11. package/dist/check.js +27 -1
  12. package/dist/contentPack.d.ts +49 -0
  13. package/dist/contentPack.js +273 -0
  14. package/dist/devExperiments.d.ts +21 -0
  15. package/dist/devExperiments.js +139 -0
  16. package/dist/devHub.d.ts +55 -0
  17. package/dist/devHub.js +187 -0
  18. package/dist/devSessionChild.js +3 -1
  19. package/dist/devSessionServer.d.ts +14 -1
  20. package/dist/devSessionServer.js +229 -44
  21. package/dist/experimentAssignment.d.ts +15 -0
  22. package/dist/experimentAssignment.js +41 -0
  23. package/dist/importCheckHook.d.ts +40 -0
  24. package/dist/importCheckHook.js +171 -0
  25. package/dist/importRegression.d.ts +15 -0
  26. package/dist/importRegression.js +100 -0
  27. package/dist/importTrust.d.ts +2 -0
  28. package/dist/importTrust.js +27 -0
  29. package/dist/importUpdateHook.d.ts +18 -0
  30. package/dist/importUpdateHook.js +31 -8
  31. package/dist/importUpdateHookRunner.js +19 -7
  32. package/dist/imports.d.ts +16 -0
  33. package/dist/imports.js +141 -31
  34. package/dist/index.js +3 -1
  35. package/dist/init.d.ts +3 -0
  36. package/dist/init.js +125 -8
  37. package/dist/install.js +4 -1
  38. package/dist/localPaths.js +4 -0
  39. package/dist/login.js +2 -2
  40. package/dist/platformDoc.js +3 -8
  41. package/dist/playPagePolicy.js +3 -1
  42. package/dist/remix.js +5 -0
  43. package/dist/routerTaskReport.d.ts +28 -0
  44. package/dist/routerTaskReport.js +56 -0
  45. package/dist/save-deck.d.ts +18 -0
  46. package/dist/save-deck.js +142 -6
  47. package/dist/serve.d.ts +8 -0
  48. package/dist/serve.js +94 -13
  49. package/dist/serverBundle.d.ts +1 -1
  50. package/dist/serverBundle.js +5 -1
  51. package/dist/webSourceSync.d.ts +2 -0
  52. package/dist/webSourceSync.js +2 -0
  53. package/kits/base/CLAUDE.md +2 -3
  54. package/kits/base/castle.json +1 -1
  55. package/kits/base/sdk/README.md +258 -52
  56. package/kits/base/sdk/agent.js +4 -4
  57. package/kits/base/sdk/avatar.d.ts +12 -0
  58. package/kits/base/sdk/avatar.js +23 -0
  59. package/kits/base/sdk/castle.d.ts +5 -0
  60. package/kits/base/sdk/castle.js +3 -0
  61. package/kits/base/sdk/commands.d.ts +208 -0
  62. package/kits/base/sdk/commands.js +16 -0
  63. package/kits/base/sdk/context.d.ts +6 -0
  64. package/kits/base/sdk/experiments.d.ts +15 -0
  65. package/kits/base/sdk/experiments.js +83 -0
  66. package/kits/base/sdk/hub.d.ts +85 -0
  67. package/kits/base/sdk/hub.js +107 -0
  68. package/kits/base/sdk/multiplayer.d.ts +45 -1
  69. package/kits/base/sdk/multiplayer.js +106 -4
  70. package/kits/base/sdk/server/hub.d.ts +169 -0
  71. package/kits/base/sdk/server/hub.js +125 -0
  72. package/kits/base/sdk/server/platformHandle.d.ts +42 -1
  73. package/kits/base/sdk/server/storage.d.ts +55 -2
  74. package/kits/base/sdk/server/wrapper.d.ts +32 -2
  75. package/kits/base/sdk/server/wrapper.js +90 -11
  76. package/kits/base/sdk/transport.d.ts +2 -1
  77. package/kits/base/sdk/transport.js +13 -1
  78. package/kits/hub-game/.prettierrc +5 -0
  79. package/kits/hub-game/CLAUDE.md +146 -0
  80. package/kits/hub-game/blueprints/avatar-0.scene +28 -0
  81. package/kits/hub-game/blueprints/avatar-1.scene +28 -0
  82. package/kits/hub-game/blueprints/avatar-2.scene +28 -0
  83. package/kits/hub-game/blueprints/avatar-3.scene +28 -0
  84. package/kits/hub-game/blueprints/bean/avatar-0.scene +28 -0
  85. package/kits/hub-game/blueprints/bean/avatar-1.scene +28 -0
  86. package/kits/hub-game/blueprints/bean/avatar-2.scene +28 -0
  87. package/kits/hub-game/blueprints/bean/avatar-3.scene +28 -0
  88. package/kits/hub-game/blueprints/blocky/avatar-0.scene +28 -0
  89. package/kits/hub-game/blueprints/blocky/avatar-1.scene +28 -0
  90. package/kits/hub-game/blueprints/blocky/avatar-2.scene +28 -0
  91. package/kits/hub-game/blueprints/blocky/avatar-3.scene +28 -0
  92. package/kits/hub-game/blueprints/pixel/avatar-0.scene +28 -0
  93. package/kits/hub-game/blueprints/pixel/avatar-1.scene +28 -0
  94. package/kits/hub-game/blueprints/pixel/avatar-2.scene +28 -0
  95. package/kits/hub-game/blueprints/pixel/avatar-3.scene +28 -0
  96. package/kits/hub-game/castle.json +96 -0
  97. package/kits/hub-game/code/client/attention.js +133 -0
  98. package/kits/hub-game/code/client/avatar.js +288 -0
  99. package/kits/hub-game/code/client/cabinets.js +90 -0
  100. package/kits/hub-game/code/client/chat.js +135 -0
  101. package/kits/hub-game/code/client/chrome.js +1001 -0
  102. package/kits/hub-game/code/client/doorFrame.js +15 -0
  103. package/kits/hub-game/code/client/firstJoin.js +14 -0
  104. package/kits/hub-game/code/client/grab.js +241 -0
  105. package/kits/hub-game/code/client/hookLayer.js +230 -0
  106. package/kits/hub-game/code/client/idle.js +326 -0
  107. package/kits/hub-game/code/client/keys.js +48 -0
  108. package/kits/hub-game/code/client/pack.js +232 -0
  109. package/kits/hub-game/code/client/packFormat.js +397 -0
  110. package/kits/hub-game/code/client/say.js +127 -0
  111. package/kits/hub-game/code/client/sha256.js +80 -0
  112. package/kits/hub-game/code/client/sound.js +147 -0
  113. package/kits/hub-game/code/client/state.js +131 -0
  114. package/kits/hub-game/code/client/talk.js +259 -0
  115. package/kits/hub-game/code/client/together.js +365 -0
  116. package/kits/hub-game/code/client/wear.js +149 -0
  117. package/kits/hub-game/code/server/actors.js +627 -0
  118. package/kits/hub-game/code/server/blocks.js +103 -0
  119. package/kits/hub-game/code/server/cabinets.js +309 -0
  120. package/kits/hub-game/code/server/game.js +137 -0
  121. package/kits/hub-game/code/server/grab.js +247 -0
  122. package/kits/hub-game/code/server/history.js +96 -0
  123. package/kits/hub-game/code/server/hub.js +1904 -0
  124. package/kits/hub-game/code/server/idle.js +412 -0
  125. package/kits/hub-game/code/server/index.js +64 -0
  126. package/kits/hub-game/code/server/labels.js +59 -0
  127. package/kits/hub-game/code/server/manifest.js +527 -0
  128. package/kits/hub-game/code/server/npcs.js +745 -0
  129. package/kits/hub-game/code/server/party.js +381 -0
  130. package/kits/hub-game/code/server/place.js +43 -0
  131. package/kits/hub-game/code/server/say.js +83 -0
  132. package/kits/hub-game/code/server/wear.js +142 -0
  133. package/kits/hub-game/code/systems/hub.js +2230 -0
  134. package/kits/hub-game/docs/content-pack.md +151 -0
  135. package/kits/hub-game/docs/contract.md +1139 -0
  136. package/kits/hub-game/docs/style.md +137 -0
  137. package/kits/hub-game/drawings/blocky/castle-eye.sprite +58 -0
  138. package/kits/hub-game/drawings/blocky/dash.sprite +59 -0
  139. package/kits/hub-game/drawings/blocky/pom.sprite +59 -0
  140. package/kits/hub-game/drawings/blocky/tabby.sprite +59 -0
  141. package/kits/hub-game/drawings/pixel/castle-arm.sprite +13 -0
  142. package/kits/hub-game/drawings/pixel/castle-body.sprite +23 -0
  143. package/kits/hub-game/drawings/pixel/castle-leg.sprite +12 -0
  144. package/kits/hub-game/drawings/pixel/kai-arm.sprite +14 -0
  145. package/kits/hub-game/drawings/pixel/kai-head.sprite +24 -0
  146. package/kits/hub-game/drawings/pixel/kai-leg.sprite +15 -0
  147. package/kits/hub-game/drawings/pixel/kai-torso.sprite +18 -0
  148. package/kits/hub-game/drawings/pixel/mimi-arm.sprite +13 -0
  149. package/kits/hub-game/drawings/pixel/mimi-head.sprite +23 -0
  150. package/kits/hub-game/drawings/pixel/mimi-leg.sprite +15 -0
  151. package/kits/hub-game/drawings/pixel/mimi-torso.sprite +18 -0
  152. package/kits/hub-game/drawings/pixel/nox-arm.sprite +13 -0
  153. package/kits/hub-game/drawings/pixel/nox-head.sprite +21 -0
  154. package/kits/hub-game/drawings/pixel/nox-leg.sprite +14 -0
  155. package/kits/hub-game/drawings/pixel/nox-torso.sprite +18 -0
  156. package/kits/hub-game/eslint.config.js +20 -0
  157. package/kits/hub-game/fonts.generated.js +9 -0
  158. package/kits/hub-game/index.html +22 -0
  159. package/kits/hub-game/main.jsx +6 -0
  160. package/kits/hub-game/models/avatar-0.pxmodel +21 -0
  161. package/kits/hub-game/models/avatar-1.pxmodel +24 -0
  162. package/kits/hub-game/models/avatar-2.pxmodel +27 -0
  163. package/kits/hub-game/models/avatar-3.pxmodel +22 -0
  164. package/kits/hub-game/models/bean/avatar-0.pxmodel +19 -0
  165. package/kits/hub-game/models/bean/avatar-1.pxmodel +24 -0
  166. package/kits/hub-game/models/bean/avatar-2.pxmodel +22 -0
  167. package/kits/hub-game/models/bean/avatar-3.pxmodel +24 -0
  168. package/kits/hub-game/models/blocky/avatar-0.pxmodel +21 -0
  169. package/kits/hub-game/models/blocky/avatar-1.pxmodel +30 -0
  170. package/kits/hub-game/models/blocky/avatar-2.pxmodel +28 -0
  171. package/kits/hub-game/models/blocky/avatar-3.pxmodel +27 -0
  172. package/kits/hub-game/models/pixel/avatar-0.pxmodel +24 -0
  173. package/kits/hub-game/models/pixel/avatar-1.pxmodel +16 -0
  174. package/kits/hub-game/models/pixel/avatar-2.pxmodel +19 -0
  175. package/kits/hub-game/models/pixel/avatar-3.pxmodel +23 -0
  176. package/kits/hub-game/package-lock.json +365 -0
  177. package/kits/hub-game/package.json +32 -0
  178. package/kits/hub-game/scenes/main.scene +318 -0
  179. package/kits/hub-game/scripts/check.mjs +339 -0
  180. package/kits/hub-game/scripts/fixtures/sdk-stub.mjs +3 -0
  181. package/kits/hub-game/scripts/gen-avatars-bean.mjs +748 -0
  182. package/kits/hub-game/scripts/gen-avatars-blocky.mjs +607 -0
  183. package/kits/hub-game/scripts/gen-avatars-pixel.mjs +771 -0
  184. package/kits/hub-game/scripts/gen-avatars.mjs +621 -0
  185. package/kits/hub-game/scripts/pack.mjs +192 -0
  186. package/kits/hub-game/scripts/test-actors.mjs +666 -0
  187. package/kits/hub-game/scripts/test-attention.mjs +103 -0
  188. package/kits/hub-game/scripts/test-avatar.mjs +472 -0
  189. package/kits/hub-game/scripts/test-ban-join.mjs +194 -0
  190. package/kits/hub-game/scripts/test-blocks.mjs +351 -0
  191. package/kits/hub-game/scripts/test-chat.mjs +98 -0
  192. package/kits/hub-game/scripts/test-classic.mjs +590 -0
  193. package/kits/hub-game/scripts/test-door-jump.mjs +131 -0
  194. package/kits/hub-game/scripts/test-door.mjs +56 -0
  195. package/kits/hub-game/scripts/test-grab.mjs +331 -0
  196. package/kits/hub-game/scripts/test-hub-ops.mjs +835 -0
  197. package/kits/hub-game/scripts/test-hub-trip.mjs +1310 -0
  198. package/kits/hub-game/scripts/test-idle.mjs +518 -0
  199. package/kits/hub-game/scripts/test-interest.mjs +413 -0
  200. package/kits/hub-game/scripts/test-keys.mjs +50 -0
  201. package/kits/hub-game/scripts/test-manifest.mjs +224 -0
  202. package/kits/hub-game/scripts/test-no-forms.mjs +16 -0
  203. package/kits/hub-game/scripts/test-npcs.mjs +714 -0
  204. package/kits/hub-game/scripts/test-pack.mjs +424 -0
  205. package/kits/hub-game/scripts/test-party.mjs +286 -0
  206. package/kits/hub-game/scripts/test-say.mjs +149 -0
  207. package/kits/hub-game/scripts/test-together.mjs +183 -0
  208. package/kits/hub-game/theme.style +3 -0
  209. package/kits/multiplayer-3d/castle.json +5 -5
  210. package/kits/multiplayer-3d/code/client/avatars.js +101 -1
  211. package/kits/multiplayer-3d/code/server/players.js +4 -1
  212. package/kits/multiplayer-3d/code/server/sceneBodies.js +27 -6
  213. package/kits/multiplayer-3d/code/server/world.js +20 -7
  214. package/kits/multiplayer-3d/code/systems/multiplayer.js +222 -11
  215. package/kits/physics-2d/castle.json +2 -2
  216. package/kits/physics-2d/engine/art.js +13 -0
  217. package/kits/physics-2d/engine/assets.js +4 -2
  218. package/kits/physics-2d/engine/scene.js +25 -5
  219. package/kits/physics-3d/CLAUDE.md +6 -1
  220. package/kits/physics-3d/castle.json +3 -3
  221. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +32 -4
  222. package/kits/physics-3d/engine3d/artobjects.js +2 -2
  223. package/kits/physics-3d/engine3d/materials.js +29 -1
  224. package/kits/physics-3d/engine3d/world3d.js +65 -1
  225. package/kits/physics-3d/systems/physics3d.js +5 -2
  226. package/kits/real-time/castle.json +2 -2
  227. package/kits/real-time/code/client/connection.js +77 -7
  228. package/kits/real-time/code/client/gameHooks.js +63 -3
  229. package/kits/real-time/code/client/messages.js +7 -0
  230. package/kits/real-time/code/server/gameHooks.js +24 -0
  231. package/kits/real-time/code/server/session.js +390 -22
  232. package/package.json +2 -2
@@ -0,0 +1,139 @@
1
+ // A/B experiments on the dev serve. Published, Castle's server resolves a
2
+ // player's variants once per deck load; here the serve does, from the folder's
3
+ // castle.json, with the same assignment function (experimentAssignment.ts):
4
+ //
5
+ // "experiments": { "tutorial_length": { "variants": ["short", "long"] } }
6
+ // "devExperiments": { "hub_avatar_style": "blocky" }
7
+ //
8
+ // `experiments` are the deck's own, assigned to the dev user as they would be
9
+ // once published. `devExperiments` stands in for experiments Castle runs across
10
+ // decks, which no local folder declares: each name simply answers its variant.
11
+ //
12
+ // `?experiment.<name>=<variant>` on any page of the serve forces an arm, for a
13
+ // declared experiment and one of its variants or for a `devExperiments` name.
14
+ // It holds for every page and local multiplayer session of this serve until
15
+ // `?experiment.<name>=` clears it or the serve stops; nothing published reads it.
16
+ // A page load keeps the arms it first read (`variantsForPage`), so a page and
17
+ // the session it joins never disagree; an override shows on the next load.
18
+ import { isPlatformExperimentName, readCastleJson, readDevExperiments, validateExperiments, } from './castleJson.js';
19
+ import { assignExperimentVariant } from './experimentAssignment.js';
20
+ const OVERRIDE_PREFIX = 'experiment.';
21
+ // The deck id a deck is assigned under before its first save gives it one.
22
+ const UNSAVED_DECK_ID = 'dev';
23
+ // Page loads whose arms are remembered; past this the one idle longest is forgotten.
24
+ const PAGE_LOADS_CAP = 1024;
25
+ export class DevExperiments {
26
+ projectDir;
27
+ log;
28
+ overrides = new Map();
29
+ pages = new Map();
30
+ lastWarning = null;
31
+ constructor(projectDir, log = () => { }) {
32
+ this.projectDir = projectDir;
33
+ this.log = log;
34
+ }
35
+ /** Takes the `experiment.<name>` overrides out of a requested URL. */
36
+ noteUrl(url) {
37
+ if (!url || !url.includes(OVERRIDE_PREFIX))
38
+ return;
39
+ let params;
40
+ try {
41
+ params = new URL(url, 'http://localhost').searchParams;
42
+ }
43
+ catch {
44
+ return;
45
+ }
46
+ const { declared, platform } = this.read();
47
+ for (const [key, variant] of params) {
48
+ if (!key.startsWith(OVERRIDE_PREFIX))
49
+ continue;
50
+ const name = key.slice(OVERRIDE_PREFIX.length);
51
+ if (variant === '') {
52
+ if (this.overrides.delete(name))
53
+ this.log(`${name} is no longer forced`);
54
+ continue;
55
+ }
56
+ const refusal = overrideRefusal(name, variant, declared, platform);
57
+ if (refusal) {
58
+ this.log(`?${key}=${variant} ignored: ${refusal}`);
59
+ continue;
60
+ }
61
+ if (this.overrides.get(name) !== variant) {
62
+ this.overrides.set(name, variant);
63
+ this.log(`${name} forced to "${variant}" until ?${key}= clears it or the serve stops`);
64
+ }
65
+ }
66
+ }
67
+ /** `{ name: variant }` for one player: what a host hands the deck and its server. */
68
+ variantsFor(userId, deckId) {
69
+ const { declared, platform } = this.read();
70
+ const variants = new Map();
71
+ for (const [name, config] of Object.entries(declared)) {
72
+ variants.set(name, assignExperimentVariant(userId, deckId ?? UNSAVED_DECK_ID, name, config));
73
+ }
74
+ // As on Castle's server: a name an experiment of Castle's holds is Castle's alone.
75
+ for (const [name, variant] of Object.entries(platform))
76
+ variants.set(name, variant);
77
+ for (const [name, variant] of this.overrides) {
78
+ // castle.json may have changed since the override was taken.
79
+ if (!overrideRefusal(name, variant, declared, platform))
80
+ variants.set(name, variant);
81
+ }
82
+ return Object.fromEntries(variants);
83
+ }
84
+ /**
85
+ * The arms of one page load, resolved the first time the page asks anything
86
+ * and the same from then on: the deck's SDK keeps its first answer, so the
87
+ * map handed to the deck's server at a later join has to be that one too. An
88
+ * override taken afterwards shows on the next page load. `page` is null for
89
+ * a caller that names none, which is resolved afresh.
90
+ */
91
+ variantsForPage(page, userId, deckId) {
92
+ if (page === null)
93
+ return this.variantsFor(userId, deckId);
94
+ let variants = this.pages.get(page);
95
+ if (variants) {
96
+ // Moved to the newest end: the cap drops the page that has gone longest
97
+ // without sending a command, never one still in use.
98
+ this.pages.delete(page);
99
+ }
100
+ else {
101
+ variants = this.variantsFor(userId, deckId);
102
+ }
103
+ this.pages.set(page, variants);
104
+ if (this.pages.size > PAGE_LOADS_CAP) {
105
+ this.pages.delete(this.pages.keys().next().value);
106
+ }
107
+ return variants;
108
+ }
109
+ read() {
110
+ const castleJson = readCastleJson(this.projectDir);
111
+ const warnings = [];
112
+ let declared = {};
113
+ try {
114
+ declared = validateExperiments(castleJson?.experiments) ?? {};
115
+ }
116
+ catch (error) {
117
+ warnings.push(`castle.json ${error instanceof Error ? error.message : String(error)} No experiment is assigned until it is fixed.`);
118
+ }
119
+ const platform = readDevExperiments(castleJson?.devExperiments, (text) => warnings.push(text));
120
+ // Read on every command, so a standing problem is reported once, not per call.
121
+ const warning = warnings.join('\n');
122
+ if (warning && warning !== this.lastWarning)
123
+ this.log(warning);
124
+ this.lastWarning = warning || null;
125
+ return { declared, platform };
126
+ }
127
+ }
128
+ function overrideRefusal(name, variant, declared, platform) {
129
+ if (Object.hasOwn(platform, name)) {
130
+ return isPlatformExperimentName(variant) ? null : `"${variant}" is not a variant name`;
131
+ }
132
+ const config = Object.hasOwn(declared, name) ? declared[name] : undefined;
133
+ if (config) {
134
+ return config.variants.includes(variant)
135
+ ? null
136
+ : `"${variant}" is not a variant of ${name} (${config.variants.join(', ')})`;
137
+ }
138
+ return `castle.json declares no experiment named "${name}" (experiments or devExperiments)`;
139
+ }
@@ -0,0 +1,55 @@
1
+ import type { HostContext, HostHub, HubCancelResult, HubCommitResult, HubDoorsResult, HubHandoffResult } from './castle-host/host.js';
2
+ export interface DevHubDoorRow {
3
+ from: string;
4
+ doorId: string;
5
+ to: string;
6
+ placementKind: 'layer' | 'pad' | 'exact';
7
+ placement: {
8
+ key?: string;
9
+ };
10
+ launcherKind: string;
11
+ padSize: number | null;
12
+ enabled: boolean;
13
+ featured: boolean;
14
+ }
15
+ export interface DevHubSessions {
16
+ /** The local WebSocket URL, or null when multiplayer is not running. */
17
+ url(): string | null;
18
+ mintNonce(ctx: HostContext, key: string | null): string;
19
+ sessionIdFor(key: string | null): string;
20
+ }
21
+ export declare function readDevHubDoors(projectDir: string, log?: (text: string) => void): DevHubDoorRow[];
22
+ /** The place a session key is: `hub.<place>.<n>`, else the deck's main place. */
23
+ export declare function devPlaceOf(key: string | null): string;
24
+ export interface DevPadGroups {
25
+ get(id: string): {
26
+ key: string;
27
+ openedAt: number;
28
+ members: number;
29
+ } | undefined;
30
+ set(id: string, group: {
31
+ key: string;
32
+ openedAt: number;
33
+ members: number;
34
+ }): void;
35
+ }
36
+ export declare class DevHubVisit implements HostHub {
37
+ private readonly rows;
38
+ private readonly sessions;
39
+ private readonly pads;
40
+ private readonly now;
41
+ private readonly random;
42
+ private key;
43
+ private joined;
44
+ private pending;
45
+ private readonly trail;
46
+ constructor(rows: () => DevHubDoorRow[], sessions: DevHubSessions, pads: DevPadGroups, now?: () => number, random?: () => string);
47
+ sessionAcquired(sessionId: string): void;
48
+ doors(): Promise<HubDoorsResult>;
49
+ go(doorId: string, ctx: HostContext): Promise<HubHandoffResult>;
50
+ back(ctx: HostContext): Promise<HubHandoffResult>;
51
+ commit(nonce: string): Promise<HubCommitResult>;
52
+ cancel(nonce: string | null): Promise<HubCancelResult>;
53
+ private acquire;
54
+ private destinationKey;
55
+ }
package/dist/devHub.js ADDED
@@ -0,0 +1,187 @@
1
+ // Hub doors on the dev serve. Production doors are rows in ghost's door table
2
+ // and lead between decks; a deck being developed locally runs every place it
3
+ // has as a named session of itself, so its door rows are a fixture in
4
+ // castle.json and each one leads to a session whose named key names the place,
5
+ // `hub.<place>.<instance>` (the key a hub kit reads its place from on
6
+ // `castle-web serve`). The public session is the deck's main place.
7
+ //
8
+ // "devHubDoors": [
9
+ // { "from": "main", "doorId": "race", "to": "race", "placementKind": "pad", "padSize": 4 },
10
+ // { "from": "main", "doorId": "inn", "to": "inn", "placementKind": "exact", "placement": { "key": "inn" } },
11
+ // { "from": "race", "doorId": "to-arena", "to": "arena", "placementKind": "layer" }
12
+ // ]
13
+ //
14
+ // One DevHubVisit per page playing the deck (each Play panel, each browser
15
+ // tab): the place it is in, its pending trip and its way back, the same state a
16
+ // web or app host keeps with ghost. A pad's players arrive together because the
17
+ // door is used by all of them within moments of the pad firing; the first one
18
+ // opens an instance and the rest of the window joins it.
19
+ import * as fs from 'node:fs';
20
+ import * as path from 'node:path';
21
+ const MAIN_PLACE = 'main';
22
+ const PLACE_ID = /^[a-z][a-z0-9-]{0,23}$/;
23
+ const DOOR_ID = /^[A-Za-z0-9_.:-]{1,64}$/;
24
+ const DEV_KEY = /^hub\.([a-z][a-z0-9-]{0,23})\.[A-Za-z0-9-]{1,40}$/;
25
+ // How long after a pad's first player the rest of it still lands in the same
26
+ // instance.
27
+ const PAD_GATHER_MS = 5000;
28
+ const TRAIL_MAX = 4;
29
+ export function readDevHubDoors(projectDir, log) {
30
+ let raw;
31
+ try {
32
+ raw = JSON.parse(fs.readFileSync(path.join(projectDir, 'castle.json'), 'utf8'))
33
+ .devHubDoors;
34
+ }
35
+ catch {
36
+ return [];
37
+ }
38
+ if (raw === undefined)
39
+ return [];
40
+ if (!Array.isArray(raw)) {
41
+ log?.('castle.json devHubDoors must be an array of door rows');
42
+ return [];
43
+ }
44
+ return raw.flatMap((entry, index) => {
45
+ const row = devHubDoorRow(entry);
46
+ if (!row)
47
+ log?.(`castle.json devHubDoors[${index}] is not a door row; it is ignored`);
48
+ return row ? [row] : [];
49
+ });
50
+ }
51
+ function devHubDoorRow(entry) {
52
+ if (!entry || typeof entry !== 'object')
53
+ return null;
54
+ const e = entry;
55
+ const kind = e.placementKind ?? 'layer';
56
+ const placement = (e.placement && typeof e.placement === 'object' ? e.placement : {});
57
+ if (typeof e.from !== 'string' ||
58
+ !PLACE_ID.test(e.from) ||
59
+ typeof e.to !== 'string' ||
60
+ !PLACE_ID.test(e.to) ||
61
+ typeof e.doorId !== 'string' ||
62
+ !DOOR_ID.test(e.doorId) ||
63
+ (kind !== 'layer' && kind !== 'pad' && kind !== 'exact') ||
64
+ (kind === 'exact' && (typeof placement.key !== 'string' || !/^[A-Za-z0-9-]{1,40}$/.test(placement.key)))) {
65
+ return null;
66
+ }
67
+ return {
68
+ from: e.from,
69
+ doorId: e.doorId,
70
+ to: e.to,
71
+ placementKind: kind,
72
+ placement: kind === 'exact' ? { key: placement.key } : {},
73
+ launcherKind: typeof e.launcherKind === 'string' ? e.launcherKind : 'door',
74
+ padSize: kind === 'pad' && Number.isInteger(e.padSize) && e.padSize > 0 ? e.padSize : kind === 'pad' ? 4 : null,
75
+ enabled: e.enabled !== false,
76
+ featured: e.featured === true,
77
+ };
78
+ }
79
+ /** The place a session key is: `hub.<place>.<n>`, else the deck's main place. */
80
+ export function devPlaceOf(key) {
81
+ return (key && DEV_KEY.exec(key)?.[1]) ?? MAIN_PLACE;
82
+ }
83
+ export class DevHubVisit {
84
+ rows;
85
+ sessions;
86
+ pads;
87
+ now;
88
+ random;
89
+ key = null;
90
+ joined = false;
91
+ pending = null;
92
+ trail = [];
93
+ constructor(rows, sessions, pads, now = () => Date.now(), random = () => Math.random().toString(36).slice(2, 10)) {
94
+ this.rows = rows;
95
+ this.sessions = sessions;
96
+ this.pads = pads;
97
+ this.now = now;
98
+ this.random = random;
99
+ }
100
+ sessionAcquired(sessionId) {
101
+ const local = this.sessions.sessionIdFor(null);
102
+ this.key = sessionId === local ? null : sessionId.startsWith(`${local}:`) ? sessionId.slice(local.length + 1) : this.key;
103
+ this.joined = true;
104
+ }
105
+ doors() {
106
+ const place = devPlaceOf(this.key);
107
+ return Promise.resolve({
108
+ status: 'ok',
109
+ doors: this.rows()
110
+ .filter((row) => row.from === place)
111
+ .map((row) => ({
112
+ doorId: row.doorId,
113
+ launcherKind: row.launcherKind,
114
+ placementKind: row.placementKind,
115
+ placement: row.placement,
116
+ padSize: row.padSize,
117
+ enabled: row.enabled,
118
+ featured: row.featured,
119
+ status: { playersInside: 0, friendsInside: 0 },
120
+ })),
121
+ });
122
+ }
123
+ go(doorId, ctx) {
124
+ if (!this.joined)
125
+ return Promise.resolve(failure('forbidden'));
126
+ const place = devPlaceOf(this.key);
127
+ const row = this.rows().find((r) => r.from === place && r.doorId === doorId);
128
+ if (!row || !row.enabled)
129
+ return Promise.resolve(failure(row ? 'unavailable' : 'not_found'));
130
+ return Promise.resolve(this.acquire('go', this.destinationKey(row), ctx));
131
+ }
132
+ back(ctx) {
133
+ if (this.trail.length === 0)
134
+ return Promise.resolve(failure('not_found'));
135
+ return Promise.resolve(this.acquire('back', this.trail[this.trail.length - 1], ctx));
136
+ }
137
+ commit(nonce) {
138
+ const trip = this.pending;
139
+ if (!trip || trip.nonce !== nonce)
140
+ return Promise.resolve({ status: 'none' });
141
+ this.pending = null;
142
+ if (trip.kind === 'go') {
143
+ this.trail.push(this.key);
144
+ if (this.trail.length > TRAIL_MAX)
145
+ this.trail.shift();
146
+ }
147
+ else {
148
+ this.trail.pop();
149
+ }
150
+ this.key = trip.key;
151
+ return Promise.resolve({ status: 'committed' });
152
+ }
153
+ cancel(nonce) {
154
+ const trip = this.pending;
155
+ if (!trip || (nonce !== null && trip.nonce !== nonce))
156
+ return Promise.resolve({ status: 'none' });
157
+ this.pending = null;
158
+ return Promise.resolve({ status: 'cancelled' });
159
+ }
160
+ acquire(kind, key, ctx) {
161
+ const url = this.sessions.url();
162
+ if (!url)
163
+ return failure('unavailable');
164
+ const nonce = this.sessions.mintNonce(ctx, key);
165
+ this.pending = { kind, key, nonce };
166
+ return { status: 'ok', url, nonce, sessionId: this.sessions.sessionIdFor(key), bundleHash: 'dev', contentUrl: null };
167
+ }
168
+ destinationKey(row) {
169
+ if (row.placementKind === 'exact')
170
+ return `hub.${row.to}.${row.placement.key}`;
171
+ if (row.placementKind === 'layer')
172
+ return row.to === MAIN_PLACE ? null : `hub.${row.to}.layer`;
173
+ const id = `${this.key ?? ''}|${row.doorId}`;
174
+ const group = this.pads.get(id);
175
+ const now = this.now();
176
+ if (group && now - group.openedAt < PAD_GATHER_MS && group.members < (row.padSize ?? 1)) {
177
+ group.members += 1;
178
+ return group.key;
179
+ }
180
+ const key = `hub.${row.to}.${this.random()}`;
181
+ this.pads.set(id, { key, openedAt: now, members: 1 });
182
+ return key;
183
+ }
184
+ }
185
+ function failure(status) {
186
+ return { status, url: null, nonce: null, sessionId: null, bundleHash: null, contentUrl: null };
187
+ }
@@ -154,7 +154,9 @@ async function dispatch(platformEvents, frame) {
154
154
  throw new Error('received duplicate init frame');
155
155
  case 'playerJoined': {
156
156
  const player = asRecord(frame.player);
157
- await platformEvents.emit('join', player.playerId, player);
157
+ // (connId, identity, arrival, experimentVariants): local sessions have no
158
+ // hub arrival, and the A/B arms stay off the player object.
159
+ await platformEvents.emit('join', player.playerId, player, undefined, frame.experimentVariants);
158
160
  return;
159
161
  }
160
162
  case 'playerLeft':
@@ -7,15 +7,28 @@ export interface DevPlayerIdentity {
7
7
  }
8
8
  export interface DevSessionServer {
9
9
  readonly port: number;
10
+ /** The default session's id: every public and party join lands there. */
10
11
  readonly sessionId: 'dev';
11
- mintNonce(author: DevPlayerIdentity): string;
12
+ /**
13
+ * Mints a one-use join nonce. `key` is a named join's key (`Multiplayer.join({
14
+ * mode: 'named', key })`): each key runs its own session, started on its first
15
+ * join. `null` (public, party) is the default session. `experimentVariants` is
16
+ * the A/B arms the joining page was given, handed to the deck's server with the
17
+ * join the way a production host hands it ghost's.
18
+ */
19
+ mintNonce(author: DevPlayerIdentity, key?: string | null, experimentVariants?: Record<string, string>): string;
20
+ /** The session id a join with this key is reported, and stored, under. */
21
+ sessionIdFor(key: string | null): string;
12
22
  handleFilesChanged(message: FilesChangedMessage): void;
13
23
  shutdown(): Promise<void>;
14
24
  shutdownNow(): void;
15
25
  }
26
+ export declare function devSessionIdFor(key: string | null): string;
16
27
  export declare function startDevSessionServer(opts: {
17
28
  projectDir: string;
18
29
  log: (level: 'log' | 'error', text: string) => void;
30
+ /** Tests shorten the empty named-session teardown. */
31
+ namedSessionIdleMs?: number;
19
32
  }): Promise<DevSessionServer>;
20
33
  export declare function serverRestartNeeded(changes: ReadonlyArray<{
21
34
  path: string;