castle-web-cli 0.4.229 → 0.4.231

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (259) hide show
  1. package/dist/agent-prompts.d.ts +2 -0
  2. package/dist/agent-prompts.js +16 -8
  3. package/dist/agent.d.ts +2 -0
  4. package/dist/agent.js +21 -21
  5. package/dist/api.d.ts +28 -2
  6. package/dist/api.js +74 -16
  7. package/dist/castle-host/host.d.ts +91 -0
  8. package/dist/castle-host/host.js +860 -3
  9. package/dist/castleJson.d.ts +44 -0
  10. package/dist/castleJson.js +131 -0
  11. package/dist/check.js +27 -1
  12. package/dist/contentPack.d.ts +49 -0
  13. package/dist/contentPack.js +273 -0
  14. package/dist/devExperiments.d.ts +21 -0
  15. package/dist/devExperiments.js +139 -0
  16. package/dist/devHub.d.ts +55 -0
  17. package/dist/devHub.js +187 -0
  18. package/dist/devSaveStorage.d.ts +36 -0
  19. package/dist/devSaveStorage.js +469 -0
  20. package/dist/devSessionChild.js +25 -13
  21. package/dist/devSessionServer.d.ts +14 -1
  22. package/dist/devSessionServer.js +237 -46
  23. package/dist/devSessionStorage.d.ts +9 -0
  24. package/dist/devSessionStorage.js +66 -1
  25. package/dist/experimentAssignment.d.ts +15 -0
  26. package/dist/experimentAssignment.js +41 -0
  27. package/dist/importCheckHook.d.ts +40 -0
  28. package/dist/importCheckHook.js +171 -0
  29. package/dist/importRegression.d.ts +15 -0
  30. package/dist/importRegression.js +100 -0
  31. package/dist/importTrust.d.ts +2 -0
  32. package/dist/importTrust.js +27 -0
  33. package/dist/importUpdateHook.d.ts +18 -0
  34. package/dist/importUpdateHook.js +31 -8
  35. package/dist/importUpdateHookRunner.js +19 -7
  36. package/dist/imports.d.ts +16 -0
  37. package/dist/imports.js +141 -31
  38. package/dist/index.js +3 -1
  39. package/dist/init.d.ts +3 -0
  40. package/dist/init.js +126 -9
  41. package/dist/install.js +4 -1
  42. package/dist/localPaths.js +4 -0
  43. package/dist/login.js +2 -2
  44. package/dist/platformDoc.js +3 -8
  45. package/dist/playPagePolicy.js +3 -1
  46. package/dist/remix.js +5 -0
  47. package/dist/routerTaskReport.d.ts +28 -0
  48. package/dist/routerTaskReport.js +56 -0
  49. package/dist/save-deck.d.ts +18 -0
  50. package/dist/save-deck.js +142 -6
  51. package/dist/serve.d.ts +8 -0
  52. package/dist/serve.js +99 -14
  53. package/dist/serverBundle.d.ts +1 -1
  54. package/dist/serverBundle.js +5 -1
  55. package/dist/webSourceSync.d.ts +2 -0
  56. package/dist/webSourceSync.js +2 -0
  57. package/kits/base/CLAUDE.md +2 -3
  58. package/kits/base/castle.json +1 -1
  59. package/kits/base/sdk/README.md +406 -53
  60. package/kits/base/sdk/agent.js +4 -4
  61. package/kits/base/sdk/avatar.d.ts +12 -0
  62. package/kits/base/sdk/avatar.js +23 -0
  63. package/kits/base/sdk/castle.d.ts +9 -0
  64. package/kits/base/sdk/castle.js +5 -0
  65. package/kits/base/sdk/commands.d.ts +223 -0
  66. package/kits/base/sdk/commands.js +16 -0
  67. package/kits/base/sdk/context.d.ts +6 -0
  68. package/kits/base/sdk/experiments.d.ts +15 -0
  69. package/kits/base/sdk/experiments.js +83 -0
  70. package/kits/base/sdk/hub.d.ts +85 -0
  71. package/kits/base/sdk/hub.js +107 -0
  72. package/kits/base/sdk/multiplayer.d.ts +45 -1
  73. package/kits/base/sdk/multiplayer.js +158 -8
  74. package/kits/base/sdk/save.d.ts +197 -0
  75. package/kits/base/sdk/save.js +525 -0
  76. package/kits/base/sdk/saveCoordinator.d.ts +39 -0
  77. package/kits/base/sdk/saveCoordinator.js +252 -0
  78. package/kits/base/sdk/server/hub.d.ts +169 -0
  79. package/kits/base/sdk/server/hub.js +125 -0
  80. package/kits/base/sdk/server/platformHandle.d.ts +42 -1
  81. package/kits/base/sdk/server/storage.d.ts +58 -4
  82. package/kits/base/sdk/server/storage.js +25 -5
  83. package/kits/base/sdk/server/wrapper.d.ts +36 -2
  84. package/kits/base/sdk/server/wrapper.js +92 -11
  85. package/kits/base/sdk/store.d.ts +3 -2
  86. package/kits/base/sdk/store.js +5 -0
  87. package/kits/base/sdk/transport.d.ts +2 -1
  88. package/kits/base/sdk/transport.js +13 -1
  89. package/kits/hub-game/.prettierrc +5 -0
  90. package/kits/hub-game/CLAUDE.md +149 -0
  91. package/kits/hub-game/blueprints/avatar-0.scene +28 -0
  92. package/kits/hub-game/blueprints/avatar-1.scene +28 -0
  93. package/kits/hub-game/blueprints/avatar-2.scene +28 -0
  94. package/kits/hub-game/blueprints/avatar-3.scene +28 -0
  95. package/kits/hub-game/blueprints/bean/avatar-0.scene +28 -0
  96. package/kits/hub-game/blueprints/bean/avatar-1.scene +28 -0
  97. package/kits/hub-game/blueprints/bean/avatar-2.scene +28 -0
  98. package/kits/hub-game/blueprints/bean/avatar-3.scene +28 -0
  99. package/kits/hub-game/blueprints/blocky/avatar-0.scene +28 -0
  100. package/kits/hub-game/blueprints/blocky/avatar-1.scene +28 -0
  101. package/kits/hub-game/blueprints/blocky/avatar-2.scene +28 -0
  102. package/kits/hub-game/blueprints/blocky/avatar-3.scene +28 -0
  103. package/kits/hub-game/blueprints/pixel/avatar-0.scene +28 -0
  104. package/kits/hub-game/blueprints/pixel/avatar-1.scene +28 -0
  105. package/kits/hub-game/blueprints/pixel/avatar-2.scene +28 -0
  106. package/kits/hub-game/blueprints/pixel/avatar-3.scene +28 -0
  107. package/kits/hub-game/castle.json +96 -0
  108. package/kits/hub-game/code/client/attention.js +133 -0
  109. package/kits/hub-game/code/client/avatar.js +288 -0
  110. package/kits/hub-game/code/client/cabinets.js +90 -0
  111. package/kits/hub-game/code/client/chat.js +135 -0
  112. package/kits/hub-game/code/client/chrome.js +1035 -0
  113. package/kits/hub-game/code/client/doorFrame.js +15 -0
  114. package/kits/hub-game/code/client/firstJoin.js +14 -0
  115. package/kits/hub-game/code/client/grab.js +376 -0
  116. package/kits/hub-game/code/client/hookLayer.js +236 -0
  117. package/kits/hub-game/code/client/idle.js +326 -0
  118. package/kits/hub-game/code/client/keys.js +48 -0
  119. package/kits/hub-game/code/client/pack.js +232 -0
  120. package/kits/hub-game/code/client/packFormat.js +397 -0
  121. package/kits/hub-game/code/client/say.js +127 -0
  122. package/kits/hub-game/code/client/sha256.js +80 -0
  123. package/kits/hub-game/code/client/sound.js +147 -0
  124. package/kits/hub-game/code/client/state.js +143 -0
  125. package/kits/hub-game/code/client/talk.js +233 -0
  126. package/kits/hub-game/code/client/tiers.js +480 -0
  127. package/kits/hub-game/code/client/together.js +440 -0
  128. package/kits/hub-game/code/client/wear.js +149 -0
  129. package/kits/hub-game/code/server/actors.js +627 -0
  130. package/kits/hub-game/code/server/blocks.js +103 -0
  131. package/kits/hub-game/code/server/cabinets.js +309 -0
  132. package/kits/hub-game/code/server/game.js +137 -0
  133. package/kits/hub-game/code/server/grab.js +248 -0
  134. package/kits/hub-game/code/server/history.js +96 -0
  135. package/kits/hub-game/code/server/hub.js +1998 -0
  136. package/kits/hub-game/code/server/idle.js +412 -0
  137. package/kits/hub-game/code/server/index.js +64 -0
  138. package/kits/hub-game/code/server/labels.js +59 -0
  139. package/kits/hub-game/code/server/manifest.js +554 -0
  140. package/kits/hub-game/code/server/npcs.js +733 -0
  141. package/kits/hub-game/code/server/party.js +439 -0
  142. package/kits/hub-game/code/server/place.js +43 -0
  143. package/kits/hub-game/code/server/say.js +83 -0
  144. package/kits/hub-game/code/server/wear.js +142 -0
  145. package/kits/hub-game/code/systems/hub.js +2347 -0
  146. package/kits/hub-game/docs/content-pack.md +151 -0
  147. package/kits/hub-game/docs/contract.md +1209 -0
  148. package/kits/hub-game/docs/style.md +137 -0
  149. package/kits/hub-game/drawings/blocky/castle-eye.sprite +58 -0
  150. package/kits/hub-game/drawings/blocky/dash.sprite +59 -0
  151. package/kits/hub-game/drawings/blocky/pom.sprite +59 -0
  152. package/kits/hub-game/drawings/blocky/tabby.sprite +59 -0
  153. package/kits/hub-game/drawings/pixel/castle-arm.sprite +13 -0
  154. package/kits/hub-game/drawings/pixel/castle-body.sprite +23 -0
  155. package/kits/hub-game/drawings/pixel/castle-leg.sprite +12 -0
  156. package/kits/hub-game/drawings/pixel/kai-arm.sprite +14 -0
  157. package/kits/hub-game/drawings/pixel/kai-head.sprite +24 -0
  158. package/kits/hub-game/drawings/pixel/kai-leg.sprite +15 -0
  159. package/kits/hub-game/drawings/pixel/kai-torso.sprite +18 -0
  160. package/kits/hub-game/drawings/pixel/mimi-arm.sprite +13 -0
  161. package/kits/hub-game/drawings/pixel/mimi-head.sprite +23 -0
  162. package/kits/hub-game/drawings/pixel/mimi-leg.sprite +15 -0
  163. package/kits/hub-game/drawings/pixel/mimi-torso.sprite +18 -0
  164. package/kits/hub-game/drawings/pixel/nox-arm.sprite +13 -0
  165. package/kits/hub-game/drawings/pixel/nox-head.sprite +21 -0
  166. package/kits/hub-game/drawings/pixel/nox-leg.sprite +14 -0
  167. package/kits/hub-game/drawings/pixel/nox-torso.sprite +18 -0
  168. package/kits/hub-game/eslint.config.js +20 -0
  169. package/kits/hub-game/fonts.generated.js +9 -0
  170. package/kits/hub-game/index.html +22 -0
  171. package/kits/hub-game/main.jsx +6 -0
  172. package/kits/hub-game/models/avatar-0.pxmodel +21 -0
  173. package/kits/hub-game/models/avatar-1.pxmodel +24 -0
  174. package/kits/hub-game/models/avatar-2.pxmodel +27 -0
  175. package/kits/hub-game/models/avatar-3.pxmodel +22 -0
  176. package/kits/hub-game/models/bean/avatar-0.pxmodel +19 -0
  177. package/kits/hub-game/models/bean/avatar-1.pxmodel +24 -0
  178. package/kits/hub-game/models/bean/avatar-2.pxmodel +22 -0
  179. package/kits/hub-game/models/bean/avatar-3.pxmodel +24 -0
  180. package/kits/hub-game/models/blocky/avatar-0.pxmodel +21 -0
  181. package/kits/hub-game/models/blocky/avatar-1.pxmodel +30 -0
  182. package/kits/hub-game/models/blocky/avatar-2.pxmodel +28 -0
  183. package/kits/hub-game/models/blocky/avatar-3.pxmodel +27 -0
  184. package/kits/hub-game/models/pixel/avatar-0.pxmodel +24 -0
  185. package/kits/hub-game/models/pixel/avatar-1.pxmodel +16 -0
  186. package/kits/hub-game/models/pixel/avatar-2.pxmodel +19 -0
  187. package/kits/hub-game/models/pixel/avatar-3.pxmodel +23 -0
  188. package/kits/hub-game/package-lock.json +365 -0
  189. package/kits/hub-game/package.json +32 -0
  190. package/kits/hub-game/scenes/main.scene +318 -0
  191. package/kits/hub-game/scripts/check.mjs +339 -0
  192. package/kits/hub-game/scripts/fixtures/sdk-stub.mjs +3 -0
  193. package/kits/hub-game/scripts/gen-avatars-bean.mjs +748 -0
  194. package/kits/hub-game/scripts/gen-avatars-blocky.mjs +607 -0
  195. package/kits/hub-game/scripts/gen-avatars-pixel.mjs +771 -0
  196. package/kits/hub-game/scripts/gen-avatars.mjs +621 -0
  197. package/kits/hub-game/scripts/pack.mjs +192 -0
  198. package/kits/hub-game/scripts/test-actors.mjs +666 -0
  199. package/kits/hub-game/scripts/test-attention.mjs +103 -0
  200. package/kits/hub-game/scripts/test-avatar.mjs +472 -0
  201. package/kits/hub-game/scripts/test-ban-join.mjs +194 -0
  202. package/kits/hub-game/scripts/test-blocks.mjs +351 -0
  203. package/kits/hub-game/scripts/test-chat.mjs +98 -0
  204. package/kits/hub-game/scripts/test-classic.mjs +590 -0
  205. package/kits/hub-game/scripts/test-door-jump.mjs +131 -0
  206. package/kits/hub-game/scripts/test-door.mjs +56 -0
  207. package/kits/hub-game/scripts/test-grab-client.mjs +328 -0
  208. package/kits/hub-game/scripts/test-grab.mjs +331 -0
  209. package/kits/hub-game/scripts/test-hub-ops.mjs +835 -0
  210. package/kits/hub-game/scripts/test-hub-trip.mjs +1518 -0
  211. package/kits/hub-game/scripts/test-idle.mjs +518 -0
  212. package/kits/hub-game/scripts/test-interest.mjs +413 -0
  213. package/kits/hub-game/scripts/test-keys.mjs +50 -0
  214. package/kits/hub-game/scripts/test-manifest.mjs +270 -0
  215. package/kits/hub-game/scripts/test-no-forms.mjs +16 -0
  216. package/kits/hub-game/scripts/test-npcs.mjs +724 -0
  217. package/kits/hub-game/scripts/test-pack.mjs +424 -0
  218. package/kits/hub-game/scripts/test-party.mjs +369 -0
  219. package/kits/hub-game/scripts/test-say.mjs +149 -0
  220. package/kits/hub-game/scripts/test-tiers.mjs +666 -0
  221. package/kits/hub-game/scripts/test-together.mjs +215 -0
  222. package/kits/hub-game/theme.style +3 -0
  223. package/kits/multiplayer-3d/castle.json +5 -5
  224. package/kits/multiplayer-3d/code/client/avatars.js +101 -1
  225. package/kits/multiplayer-3d/code/server/players.js +4 -1
  226. package/kits/multiplayer-3d/code/server/sceneBodies.js +27 -6
  227. package/kits/multiplayer-3d/code/server/world.js +20 -7
  228. package/kits/multiplayer-3d/code/systems/multiplayer.js +222 -11
  229. package/kits/physics-2d/CLAUDE.md +2 -0
  230. package/kits/physics-2d/castle.json +2 -2
  231. package/kits/physics-2d/engine/art.js +13 -0
  232. package/kits/physics-2d/engine/assets.js +4 -2
  233. package/kits/physics-2d/engine/scene.js +117 -5
  234. package/kits/physics-2d/package.json +1 -1
  235. package/kits/physics-2d/scripts/test-skip-unchanged.mjs +254 -0
  236. package/kits/physics-3d/CLAUDE.md +285 -1
  237. package/kits/physics-3d/behaviors/Player.jsx +74 -1
  238. package/kits/physics-3d/castle.json +3 -3
  239. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +33 -5
  240. package/kits/physics-3d/engine3d/actornode.js +253 -0
  241. package/kits/physics-3d/engine3d/artobjects.js +2 -2
  242. package/kits/physics-3d/engine3d/materials.js +29 -1
  243. package/kits/physics-3d/engine3d/nearshadows.js +600 -0
  244. package/kits/physics-3d/engine3d/unchanged.js +153 -0
  245. package/kits/physics-3d/engine3d/world3d.js +527 -5
  246. package/kits/physics-3d/package.json +1 -1
  247. package/kits/physics-3d/scripts/test-camera-follow.mjs +533 -0
  248. package/kits/physics-3d/scripts/test-near-shadows.mjs +1073 -0
  249. package/kits/physics-3d/scripts/test-static-actors.mjs +662 -0
  250. package/kits/physics-3d/scripts/test-static-passes.mjs +459 -0
  251. package/kits/physics-3d/scripts/test-static-physics.mjs +128 -0
  252. package/kits/physics-3d/systems/physics3d.js +187 -5
  253. package/kits/real-time/castle.json +2 -2
  254. package/kits/real-time/code/client/connection.js +77 -7
  255. package/kits/real-time/code/client/gameHooks.js +63 -3
  256. package/kits/real-time/code/client/messages.js +7 -0
  257. package/kits/real-time/code/server/gameHooks.js +24 -0
  258. package/kits/real-time/code/server/session.js +390 -22
  259. package/package.json +2 -2
@@ -0,0 +1,554 @@
1
+ // The hub manifest: `castle.json` -> `hub`, read and checked against the
2
+ // contract (`docs/contract.md`). Plain JavaScript with no bundler features, so
3
+ // the server, the publish check (`scripts/check.mjs`) and tests read it the
4
+ // same way.
5
+ //
6
+ // `readManifest(castleJson, sceneExists)` returns `{ errors, manifest }`. The
7
+ // manifest is null when there are errors; otherwise every place has every
8
+ // field filled with its default.
9
+
10
+ export const CONTRACT_VERSION = 1;
11
+
12
+ export const CONTROLLERS = ['walk'];
13
+ // Names kept for presets the kit does not have yet, so a deck that asks for
14
+ // one is told it is coming rather than that it is a typo.
15
+ export const RESERVED_CONTROLLERS = ['vehicle', 'fixed-camera'];
16
+
17
+ export const OUTCOMES = ['win', 'lose', 'draw'];
18
+ export const SCORE_UNITS = ['ms', 's', 'points'];
19
+ export const MAX_PLAYERS_CAP = 24;
20
+ export const MAX_STATS = 8;
21
+ export const PLACE_ID = /^[a-z][a-z0-9-]{0,23}$/;
22
+ export const MAIN_PLACE = 'main';
23
+ // How many other players each client of a place is sent (`nearestPlayers`).
24
+ export const NEAREST_PLAYERS = 30;
25
+ export const NEAREST_PLAYERS_CAP = 100;
26
+ // Grabbing and throwing (v1.3, §6): what `grab: true` means, and the bounds of
27
+ // each field. The fastest throw stays well under multiplayer-3d's limit on an
28
+ // owned object's reported speed (40 m/s), so a throw is never cut short by it.
29
+ export const GRAB_DEFAULTS = { throwSpeed: 10, holdDistance: 1.4, holdHeight: 1.2 };
30
+ const GRAB_LIMITS = { throwSpeed: [1, 14, 'm/s'], holdDistance: [0.8, 3, 'metres'], holdHeight: [0, 2.5, 'metres'] };
31
+ // v1.22: a place may lengthen the reach at which an object is offered (from
32
+ // the object's near side, flat metres; 1.6 is the reach without it) and ask
33
+ // for a steady offer (`code/client/grab.js`). Neither has a default written
34
+ // into the place: a place that sets neither is sent what it always was. The
35
+ // top stays inside the server's GRAB_REACH (4 m, centre to centre), and the
36
+ // client also never offers an object whose centre is past 3 m.
37
+ export const GRAB_REACH_LIMITS = [1.6, 3, 'metres'];
38
+ const GRAB_KEYS = [...Object.keys(GRAB_DEFAULTS), 'reach', 'steady'];
39
+ // Idle play (v1.6, §6): emotes, seats and the place's own sounds. Sounds are
40
+ // files of the deck, listed so the server can refuse any other name.
41
+ export const IDLE_KEYS = ['emotes', 'seats', 'sounds'];
42
+ export const SOUND_EXTS = ['.mp3', '.wav', '.m4a'];
43
+ export const MAX_SOUND_FILES = 16;
44
+ const SOUND_PATH = /^[A-Za-z0-9_@-][A-Za-z0-9_./@-]{0,199}$/;
45
+
46
+ const PLACE_KEYS = [
47
+ 'title',
48
+ 'scene',
49
+ 'minPlayers',
50
+ 'maxPlayers',
51
+ 'lateJoin',
52
+ 'maxDurationSec',
53
+ 'controller',
54
+ 'arrival',
55
+ 'result',
56
+ 'sign',
57
+ 'npcs',
58
+ 'nearestPlayers',
59
+ 'fallY',
60
+ 'grab',
61
+ 'idle',
62
+ ];
63
+ // `tiers` is the deck's, not a place's: the client's picture on a slow device
64
+ // (v1.21, `code/client/tiers.js`). The server reads nothing of it.
65
+ const TOP_KEYS = ['contract', 'places', 'tiers', ...PLACE_KEYS];
66
+
67
+ const DEFAULT_SCENE = 'scenes/main.scene';
68
+
69
+ export function readManifest(castleJson, sceneExists = () => true) {
70
+ const errors = [];
71
+ const hub = castleJson?.hub;
72
+ if (!isObject(hub)) {
73
+ return { errors: ['castle.json has no `hub` block: a hub-game deck declares one.'], manifest: null };
74
+ }
75
+ if (hub.contract !== CONTRACT_VERSION) {
76
+ errors.push(
77
+ Number.isInteger(hub.contract) && hub.contract > CONTRACT_VERSION
78
+ ? `hub.contract is ${hub.contract}, newer than this kit's ${CONTRACT_VERSION}: update the castle.hub-game import.`
79
+ : `hub.contract must be ${CONTRACT_VERSION}.`,
80
+ );
81
+ }
82
+ unknownKeys(hub, TOP_KEYS, 'hub', errors);
83
+ if (hub.tiers !== undefined && typeof hub.tiers !== 'boolean') {
84
+ errors.push('hub.tiers must be true or false.');
85
+ }
86
+ const defaultScene =
87
+ typeof castleJson?.editor?.defaultPlayFile === 'string' ? castleJson.editor.defaultPlayFile : DEFAULT_SCENE;
88
+ const serverMax = Number.isInteger(castleJson?.server?.maxPlayers) ? castleJson.server.maxPlayers : MAX_PLAYERS_CAP;
89
+ const destinations = Array.isArray(castleJson?.server?.destinations) ? castleJson.server.destinations : [];
90
+ const bundle = castleJson?.characterBundle ?? null;
91
+
92
+ const places = {};
93
+ places[MAIN_PLACE] = readPlace(hub, 'hub', defaultScene, serverMax, sceneExists, errors, destinations, bundle);
94
+ if (hub.places !== undefined) {
95
+ if (!isObject(hub.places)) {
96
+ errors.push('hub.places must be an object of place id -> place.');
97
+ } else {
98
+ for (const [id, block] of Object.entries(hub.places)) {
99
+ const where = `hub.places.${id}`;
100
+ if (!PLACE_ID.test(id) || id === MAIN_PLACE) {
101
+ errors.push(`${where}: a place id is [a-z][a-z0-9-]{0,23} and not "${MAIN_PLACE}".`);
102
+ continue;
103
+ }
104
+ if (!isObject(block)) {
105
+ errors.push(`${where} must be an object.`);
106
+ continue;
107
+ }
108
+ unknownKeys(block, PLACE_KEYS, where, errors);
109
+ places[id] = readPlace(block, where, null, serverMax, sceneExists, errors, destinations, bundle);
110
+ }
111
+ }
112
+ }
113
+ return errors.length ? { errors, manifest: null } : { errors, manifest: { contract: CONTRACT_VERSION, places } };
114
+ }
115
+
116
+ function readPlace(block, where, defaultScene, serverMax, sceneExists, errors, destinations, bundle) {
117
+ const place = {};
118
+
119
+ place.title = typeof block.title === 'string' ? block.title.trim() : '';
120
+ if (!place.title || place.title.length > 40) {
121
+ errors.push(`${where}.title must be 1-40 characters.`);
122
+ }
123
+
124
+ place.scene = block.scene ?? defaultScene;
125
+ if (typeof place.scene !== 'string' || !/^scenes\/[^/]+\.scene$/.test(place.scene)) {
126
+ errors.push(`${where}.scene must be a scenes/*.scene path.`);
127
+ } else if (!sceneExists(place.scene)) {
128
+ errors.push(`${where}.scene names ${place.scene}, which this deck does not have.`);
129
+ }
130
+
131
+ place.minPlayers = intIn(block.minPlayers, 1, 1, MAX_PLAYERS_CAP, `${where}.minPlayers`, errors);
132
+ place.maxPlayers = intIn(block.maxPlayers, Math.min(8, serverMax), 1, MAX_PLAYERS_CAP, `${where}.maxPlayers`, errors);
133
+ if (place.minPlayers > place.maxPlayers) {
134
+ errors.push(`${where}.minPlayers is more than maxPlayers.`);
135
+ }
136
+ if (place.maxPlayers > serverMax) {
137
+ errors.push(`${where}.maxPlayers (${place.maxPlayers}) is more than server.maxPlayers (${serverMax}).`);
138
+ }
139
+
140
+ place.lateJoin = block.lateJoin ?? false;
141
+ if (typeof place.lateJoin !== 'boolean') {
142
+ errors.push(`${where}.lateJoin must be true or false.`);
143
+ }
144
+
145
+
146
+ place.controller = block.controller ?? 'walk';
147
+ if (!CONTROLLERS.includes(place.controller)) {
148
+ errors.push(
149
+ RESERVED_CONTROLLERS.includes(place.controller)
150
+ ? `${where}.controller "${place.controller}" is not built yet; v1 has ${CONTROLLERS.join(', ')}.`
151
+ : `${where}.controller must be one of ${CONTROLLERS.join(', ')}.`,
152
+ );
153
+ }
154
+
155
+ place.nearestPlayers = intIn(
156
+ block.nearestPlayers,
157
+ NEAREST_PLAYERS,
158
+ 1,
159
+ NEAREST_PLAYERS_CAP,
160
+ `${where}.nearestPlayers`,
161
+ errors,
162
+ );
163
+ place.arrival = readArrival(block.arrival, `${where}.arrival`, errors);
164
+ place.result = block.result === undefined ? null : readResult(block.result, `${where}.result`, errors);
165
+ // A game has a longest visit; a place with no result (a town) has none
166
+ // unless it declares one.
167
+ place.maxDurationSec =
168
+ block.maxDurationSec === undefined && !place.result
169
+ ? null
170
+ : intIn(block.maxDurationSec, 600, 30, 1800, `${where}.maxDurationSec`, errors);
171
+ place.sign = block.sign === undefined ? null : readSign(block.sign, place.result, `${where}.sign`, errors);
172
+ place.npcs = block.npcs === undefined ? null : readNpcs(block.npcs, destinations, bundle, `${where}.npcs`, errors);
173
+ // v1.1: below this a player has fallen and the hub catches them (§5).
174
+ place.fallY = null;
175
+ if (block.fallY !== undefined) {
176
+ if (typeof block.fallY !== 'number' || !(block.fallY >= -25 && block.fallY <= 50)) {
177
+ errors.push(`${where}.fallY must be a number of metres from -25 to 50.`);
178
+ } else {
179
+ place.fallY = block.fallY;
180
+ }
181
+ }
182
+ // v1.3: players may pick up the place's loose objects and throw them (§6).
183
+ place.grab = readGrab(block.grab, `${where}.grab`, errors);
184
+ // v1.6: idle play. Only a place that declares it carries the key, so a
185
+ // place without it reads (and packs) exactly as before.
186
+ const idle = readIdle(block.idle, `${where}.idle`, errors);
187
+ if (idle) {
188
+ place.idle = idle;
189
+ }
190
+ return place;
191
+ }
192
+
193
+ // `grab`: absent or false is none; true is the defaults; an object sets any of
194
+ // them, and may add `reach` and `steady` (v1.22), which are kept only when
195
+ // set: `steady: false` is the same as leaving it out.
196
+ function readGrab(value, where, errors) {
197
+ if (value === undefined || value === false) {
198
+ return null;
199
+ }
200
+ if (value === true) {
201
+ return { ...GRAB_DEFAULTS };
202
+ }
203
+ if (!isObject(value)) {
204
+ errors.push(`${where} must be true, false or an object.`);
205
+ return null;
206
+ }
207
+ unknownKeys(value, GRAB_KEYS, where, errors);
208
+ const grab = { ...GRAB_DEFAULTS };
209
+ for (const [key, [min, max, unit]] of Object.entries(GRAB_LIMITS)) {
210
+ if (value[key] === undefined) {
211
+ continue;
212
+ }
213
+ if (typeof value[key] !== 'number' || !(value[key] >= min && value[key] <= max)) {
214
+ errors.push(`${where}.${key} must be a number of ${unit} from ${min} to ${max}.`);
215
+ } else {
216
+ grab[key] = value[key];
217
+ }
218
+ }
219
+ if (value.reach !== undefined) {
220
+ const [min, max, unit] = GRAB_REACH_LIMITS;
221
+ if (typeof value.reach !== 'number' || !(value.reach >= min && value.reach <= max)) {
222
+ errors.push(`${where}.reach must be a number of ${unit} from ${min} to ${max}.`);
223
+ } else {
224
+ grab.reach = value.reach;
225
+ }
226
+ }
227
+ if (value.steady !== undefined && typeof value.steady !== 'boolean') {
228
+ errors.push(`${where}.steady must be true or false.`);
229
+ } else if (value.steady === true) {
230
+ grab.steady = true;
231
+ }
232
+ return grab;
233
+ }
234
+
235
+ // `idle`: absent or false is none; true is emotes and seats; an object turns
236
+ // each on by name, and `sounds` lists the deck's sound files the place's
237
+ // server may play (`hub.sound`).
238
+ function readIdle(value, where, errors) {
239
+ if (value === undefined || value === false) {
240
+ return null;
241
+ }
242
+ if (value === true) {
243
+ return { emotes: true, seats: true, sounds: [] };
244
+ }
245
+ if (!isObject(value)) {
246
+ errors.push(`${where} must be true, false or an object.`);
247
+ return null;
248
+ }
249
+ unknownKeys(value, IDLE_KEYS, where, errors);
250
+ const idle = { emotes: false, seats: false, sounds: [] };
251
+ for (const key of ['emotes', 'seats']) {
252
+ if (value[key] !== undefined && typeof value[key] !== 'boolean') {
253
+ errors.push(`${where}.${key} must be true or false.`);
254
+ } else {
255
+ idle[key] = value[key] === true;
256
+ }
257
+ }
258
+ if (value.sounds !== undefined) {
259
+ const ok =
260
+ Array.isArray(value.sounds) &&
261
+ value.sounds.length <= MAX_SOUND_FILES &&
262
+ new Set(value.sounds).size === value.sounds.length &&
263
+ value.sounds.every(isSoundPath);
264
+ if (!ok) {
265
+ errors.push(
266
+ `${where}.sounds must be a list of at most ${MAX_SOUND_FILES} different ${SOUND_EXTS.join('/')} paths of this deck.`,
267
+ );
268
+ } else {
269
+ idle.sounds = [...value.sounds];
270
+ }
271
+ }
272
+ if (!idle.emotes && !idle.seats && !idle.sounds.length) {
273
+ return null;
274
+ }
275
+ return idle;
276
+ }
277
+
278
+ export function isSoundPath(path) {
279
+ return (
280
+ typeof path === 'string' &&
281
+ SOUND_PATH.test(path) &&
282
+ // Lower case, as the engine's media glob bundles them.
283
+ SOUND_EXTS.some((ext) => path.endsWith(ext)) &&
284
+ !path.split('/').some((part) => part === '..' || part === '.' || part === '')
285
+ );
286
+ }
287
+
288
+ // Where a place's NPC minds live (§13): the place itself (every layer talks
289
+ // to ghost's one place mind), optionally a destination route whose world an
290
+ // older SDK joins instead, and how much conversation each character takes.
291
+ function readNpcs(value, destinations, bundle, where, errors) {
292
+ if (!isObject(value)) {
293
+ errors.push(`${where} must be an object.`);
294
+ return null;
295
+ }
296
+ unknownKeys(value, ['route', 'slot', 'turnsPerMinute', 'disclosure', 'followSec'], where, errors);
297
+ const npcs = { route: null, slot: 'main', turnsPerMinute: 6, disclosure: 'participants', followSec: 120 };
298
+ // A route is optional: without one the minds are the place's (ghost's place
299
+ // mind, reached from every layer); with one, an SDK that cannot address the
300
+ // place's characters from a layer joins that world instead.
301
+ const route = destinations.find((d) => d?.routeId === value.route);
302
+ if (value.route === undefined) {
303
+ // place minds only
304
+ } else if (typeof value.route !== 'string' || !route) {
305
+ errors.push(`${where}.route must name one of server.destinations' routeIds.`);
306
+ } else if (route.characters !== 'shared') {
307
+ errors.push(`${where}.route "${value.route}" must declare characters: "shared".`);
308
+ } else {
309
+ npcs.route = value.route;
310
+ }
311
+ // A place's server, not a client, decides who hears a turn (nobody but its
312
+ // speaker): ghost admits a turn's audience only for a bundle that says so.
313
+ if (!isObject(bundle) || !Array.isArray(bundle.characters) || !bundle.characters.length) {
314
+ errors.push(`${where} needs a castle.json characterBundle with the characters its NPCs speak for.`);
315
+ } else if (bundle.conversation?.version !== 1 || bundle.conversation?.authority !== 'server') {
316
+ errors.push(`${where} needs characterBundle.conversation: { "version": 1, "authority": "server", "maxListeners": 0 }.`);
317
+ }
318
+ if (value.slot !== undefined) {
319
+ if (typeof value.slot !== 'string' || !/^[A-Za-z0-9_.-]{1,64}$/.test(value.slot)) {
320
+ errors.push(`${where}.slot must be 1-64 letters, digits, '.', '_' or '-'.`);
321
+ } else {
322
+ npcs.slot = value.slot;
323
+ }
324
+ }
325
+ npcs.turnsPerMinute = intIn(value.turnsPerMinute, 6, 1, 30, `${where}.turnsPerMinute`, errors);
326
+ npcs.followSec = intIn(value.followSec, 120, 10, 600, `${where}.followSec`, errors);
327
+ if (value.disclosure !== undefined) {
328
+ // Read for decks that set it, and no longer acted on (v1.17): a player's
329
+ // conversation with a character is theirs alone, whatever this says.
330
+ if (value.disclosure !== 'participants' && value.disclosure !== 'world') {
331
+ errors.push(`${where}.disclosure must be "participants" or "world".`);
332
+ }
333
+ }
334
+ return npcs;
335
+ }
336
+
337
+ function readArrival(value, where, errors) {
338
+ const arrival = { actor: null, spread: 1.5, face: 'actor' };
339
+ if (value === undefined) {
340
+ return arrival;
341
+ }
342
+ if (!isObject(value)) {
343
+ errors.push(`${where} must be an object.`);
344
+ return arrival;
345
+ }
346
+ unknownKeys(value, ['actor', 'spread', 'face'], where, errors);
347
+ if (value.actor !== undefined) {
348
+ if (typeof value.actor !== 'string' || !value.actor || value.actor.length > 128) {
349
+ errors.push(`${where}.actor must be a scene actor id.`);
350
+ } else {
351
+ arrival.actor = value.actor;
352
+ }
353
+ }
354
+ if (value.spread !== undefined) {
355
+ if (typeof value.spread !== 'number' || !(value.spread >= 0 && value.spread <= 5)) {
356
+ errors.push(`${where}.spread must be a number of metres from 0 to 5.`);
357
+ } else {
358
+ arrival.spread = value.spread;
359
+ }
360
+ }
361
+ if (value.face !== undefined) {
362
+ if (value.face === 'actor' || value.face === 'center' || (typeof value.face === 'number' && Number.isFinite(value.face))) {
363
+ arrival.face = value.face;
364
+ } else {
365
+ errors.push(`${where}.face must be "actor", "center" or a number of degrees.`);
366
+ }
367
+ }
368
+ return arrival;
369
+ }
370
+
371
+ function readResult(value, where, errors) {
372
+ if (!isObject(value)) {
373
+ errors.push(`${where} must be an object.`);
374
+ return null;
375
+ }
376
+ unknownKeys(value, ['outcomes', 'score', 'stats'], where, errors);
377
+ const result = { outcomes: OUTCOMES, score: null, stats: {} };
378
+ if (value.outcomes !== undefined) {
379
+ if (
380
+ !Array.isArray(value.outcomes) ||
381
+ !value.outcomes.length ||
382
+ !value.outcomes.every((o) => OUTCOMES.includes(o)) ||
383
+ new Set(value.outcomes).size !== value.outcomes.length
384
+ ) {
385
+ errors.push(`${where}.outcomes must be a non-empty list drawn from ${OUTCOMES.join(', ')}.`);
386
+ } else {
387
+ result.outcomes = [...value.outcomes];
388
+ }
389
+ }
390
+ if (value.score !== undefined) {
391
+ const score = value.score;
392
+ if (!isObject(score)) {
393
+ errors.push(`${where}.score must be an object.`);
394
+ } else {
395
+ unknownKeys(score, ['unit', 'better', 'min', 'max'], `${where}.score`, errors);
396
+ const unit = score.unit ?? 'points';
397
+ const better = score.better ?? 'higher';
398
+ if (!SCORE_UNITS.includes(unit)) {
399
+ errors.push(`${where}.score.unit must be one of ${SCORE_UNITS.join(', ')}.`);
400
+ }
401
+ if (better !== 'higher' && better !== 'lower') {
402
+ errors.push(`${where}.score.better must be "higher" or "lower".`);
403
+ }
404
+ const min = score.min ?? 0;
405
+ const max = score.max ?? 1e9;
406
+ if (!Number.isFinite(min) || !Number.isFinite(max) || min > max) {
407
+ errors.push(`${where}.score.min and max must be finite with min ≤ max.`);
408
+ }
409
+ result.score = { unit, better, min, max };
410
+ }
411
+ }
412
+ if (value.stats !== undefined) {
413
+ if (!isObject(value.stats) || Object.keys(value.stats).length > MAX_STATS) {
414
+ errors.push(`${where}.stats must be an object of at most ${MAX_STATS} names.`);
415
+ } else {
416
+ for (const [name, type] of Object.entries(value.stats)) {
417
+ if (!/^[a-zA-Z][a-zA-Z0-9_]{0,23}$/.test(name) || (type !== 'number' && type !== 'string')) {
418
+ errors.push(`${where}.stats.${name}: a stat is a short name and "number" or "string".`);
419
+ } else {
420
+ result.stats[name] = type;
421
+ }
422
+ }
423
+ }
424
+ }
425
+ return result;
426
+ }
427
+
428
+ function readSign(value, result, where, errors) {
429
+ if (!isObject(value)) {
430
+ errors.push(`${where} must be an object.`);
431
+ return null;
432
+ }
433
+ unknownKeys(value, ['model', 'board'], where, errors);
434
+ const sign = { model: null, board: null };
435
+ if (value.model !== undefined) {
436
+ if (typeof value.model !== 'string' || !/\.pxmodel$/.test(value.model)) {
437
+ errors.push(`${where}.model must be a .pxmodel path.`);
438
+ } else {
439
+ sign.model = value.model;
440
+ }
441
+ }
442
+ if (value.board !== undefined) {
443
+ const numeric = value.board === 'score' ? Boolean(result?.score) : result?.stats?.[value.board] === 'number';
444
+ if (!numeric) {
445
+ errors.push(`${where}.board must be "score" (with result.score declared) or a declared numeric stat.`);
446
+ } else {
447
+ sign.board = value.board;
448
+ }
449
+ }
450
+ return sign;
451
+ }
452
+
453
+ // Check one result a game reports against its place's declared shape. Returns
454
+ // `{ error }` or `{ result }`, the result reduced to declared fields.
455
+ export function checkResult(place, value) {
456
+ const shape = place.result;
457
+ if (!shape) {
458
+ return { error: `place "${place.title}" declares no result` };
459
+ }
460
+ if (!isObject(value)) {
461
+ return { error: 'a result is an object' };
462
+ }
463
+ // v1.1: the outcome may be left out where the score says it all (a solo
464
+ // time trial, a co-op run's time); a result still says something.
465
+ const hasOutcome = value.outcome !== undefined && value.outcome !== null;
466
+ if (hasOutcome && !shape.outcomes.includes(value.outcome)) {
467
+ return { error: `outcome must be one of ${shape.outcomes.join(', ')}` };
468
+ }
469
+ const hasScore = value.score !== undefined && value.score !== null;
470
+ if (!hasOutcome && !(shape.score && hasScore)) {
471
+ return { error: 'a result without an outcome needs a score' };
472
+ }
473
+ const out = hasOutcome ? { outcome: value.outcome } : {};
474
+ if (shape.score) {
475
+ if (value.score !== undefined && value.score !== null) {
476
+ if (typeof value.score !== 'number' || !Number.isFinite(value.score)) {
477
+ return { error: 'score must be a finite number' };
478
+ }
479
+ if (value.score < shape.score.min || value.score > shape.score.max) {
480
+ return { error: `score ${value.score} is outside ${shape.score.min}..${shape.score.max}` };
481
+ }
482
+ out.score = value.score;
483
+ }
484
+ } else if (value.score !== undefined && value.score !== null) {
485
+ return { error: 'this place declares no score' };
486
+ }
487
+ if (value.stats !== undefined) {
488
+ if (!isObject(value.stats)) {
489
+ return { error: 'stats must be an object' };
490
+ }
491
+ const stats = {};
492
+ for (const [name, v] of Object.entries(value.stats)) {
493
+ const type = Object.hasOwn(shape.stats, name) ? shape.stats[name] : null;
494
+ if (!type) {
495
+ return { error: `stat "${name}" is not declared` };
496
+ }
497
+ if (type === 'number' ? typeof v !== 'number' || !Number.isFinite(v) : typeof v !== 'string' || v.length > 40) {
498
+ return { error: `stat "${name}" must be a ${type === 'number' ? 'finite number' : 'string of at most 40 characters'}` };
499
+ }
500
+ stats[name] = v;
501
+ }
502
+ out.stats = stats;
503
+ }
504
+ for (const key of Object.keys(value)) {
505
+ if (!['outcome', 'score', 'stats'].includes(key)) {
506
+ return { error: `"${key}" is not part of a result` };
507
+ }
508
+ }
509
+ return { result: out };
510
+ }
511
+
512
+ // What a client is told about the place it is in: everything the hub chrome
513
+ // draws from, and nothing it does not need.
514
+ export function publicPlace(id, place) {
515
+ return {
516
+ contract: CONTRACT_VERSION,
517
+ id,
518
+ title: place.title,
519
+ scene: place.scene,
520
+ controller: place.controller,
521
+ maxDurationSec: place.maxDurationSec,
522
+ // v1.3: the hub chrome offers Grab only where this is set; a place
523
+ // without it is sent exactly what it was.
524
+ ...(place.grab ? { grab: { ...place.grab } } : {}),
525
+ // v1.6: likewise idle play.
526
+ ...(place.idle ? { idle: { emotes: place.idle.emotes, seats: place.idle.seats, sounds: [...place.idle.sounds] } } : {}),
527
+ result: place.result
528
+ ? { score: place.result.score ? { unit: place.result.score.unit, better: place.result.score.better } : null }
529
+ : null,
530
+ };
531
+ }
532
+
533
+ function intIn(value, fallback, min, max, where, errors) {
534
+ if (value === undefined) {
535
+ return fallback;
536
+ }
537
+ if (!Number.isInteger(value) || value < min || value > max) {
538
+ errors.push(`${where} must be a whole number from ${min} to ${max}.`);
539
+ return fallback;
540
+ }
541
+ return value;
542
+ }
543
+
544
+ function unknownKeys(block, allowed, where, errors) {
545
+ for (const key of Object.keys(block)) {
546
+ if (!allowed.includes(key)) {
547
+ errors.push(`${where}.${key} is not part of the hub contract v${CONTRACT_VERSION}.`);
548
+ }
549
+ }
550
+ }
551
+
552
+ function isObject(value) {
553
+ return value !== null && typeof value === 'object' && !Array.isArray(value);
554
+ }