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,527 @@
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
+ // Idle play (v1.6, §6): emotes, seats and the place's own sounds. Sounds are
32
+ // files of the deck, listed so the server can refuse any other name.
33
+ export const IDLE_KEYS = ['emotes', 'seats', 'sounds'];
34
+ export const SOUND_EXTS = ['.mp3', '.wav', '.m4a'];
35
+ export const MAX_SOUND_FILES = 16;
36
+ const SOUND_PATH = /^[A-Za-z0-9_@-][A-Za-z0-9_./@-]{0,199}$/;
37
+
38
+ const PLACE_KEYS = [
39
+ 'title',
40
+ 'scene',
41
+ 'minPlayers',
42
+ 'maxPlayers',
43
+ 'lateJoin',
44
+ 'maxDurationSec',
45
+ 'controller',
46
+ 'arrival',
47
+ 'result',
48
+ 'sign',
49
+ 'npcs',
50
+ 'nearestPlayers',
51
+ 'fallY',
52
+ 'grab',
53
+ 'idle',
54
+ ];
55
+ const TOP_KEYS = ['contract', 'places', ...PLACE_KEYS];
56
+
57
+ const DEFAULT_SCENE = 'scenes/main.scene';
58
+
59
+ export function readManifest(castleJson, sceneExists = () => true) {
60
+ const errors = [];
61
+ const hub = castleJson?.hub;
62
+ if (!isObject(hub)) {
63
+ return { errors: ['castle.json has no `hub` block: a hub-game deck declares one.'], manifest: null };
64
+ }
65
+ if (hub.contract !== CONTRACT_VERSION) {
66
+ errors.push(
67
+ Number.isInteger(hub.contract) && hub.contract > CONTRACT_VERSION
68
+ ? `hub.contract is ${hub.contract}, newer than this kit's ${CONTRACT_VERSION}: update the castle.hub-game import.`
69
+ : `hub.contract must be ${CONTRACT_VERSION}.`,
70
+ );
71
+ }
72
+ unknownKeys(hub, TOP_KEYS, 'hub', errors);
73
+ const defaultScene =
74
+ typeof castleJson?.editor?.defaultPlayFile === 'string' ? castleJson.editor.defaultPlayFile : DEFAULT_SCENE;
75
+ const serverMax = Number.isInteger(castleJson?.server?.maxPlayers) ? castleJson.server.maxPlayers : MAX_PLAYERS_CAP;
76
+ const destinations = Array.isArray(castleJson?.server?.destinations) ? castleJson.server.destinations : [];
77
+ const bundle = castleJson?.characterBundle ?? null;
78
+
79
+ const places = {};
80
+ places[MAIN_PLACE] = readPlace(hub, 'hub', defaultScene, serverMax, sceneExists, errors, destinations, bundle);
81
+ if (hub.places !== undefined) {
82
+ if (!isObject(hub.places)) {
83
+ errors.push('hub.places must be an object of place id -> place.');
84
+ } else {
85
+ for (const [id, block] of Object.entries(hub.places)) {
86
+ const where = `hub.places.${id}`;
87
+ if (!PLACE_ID.test(id) || id === MAIN_PLACE) {
88
+ errors.push(`${where}: a place id is [a-z][a-z0-9-]{0,23} and not "${MAIN_PLACE}".`);
89
+ continue;
90
+ }
91
+ if (!isObject(block)) {
92
+ errors.push(`${where} must be an object.`);
93
+ continue;
94
+ }
95
+ unknownKeys(block, PLACE_KEYS, where, errors);
96
+ places[id] = readPlace(block, where, null, serverMax, sceneExists, errors, destinations, bundle);
97
+ }
98
+ }
99
+ }
100
+ return errors.length ? { errors, manifest: null } : { errors, manifest: { contract: CONTRACT_VERSION, places } };
101
+ }
102
+
103
+ function readPlace(block, where, defaultScene, serverMax, sceneExists, errors, destinations, bundle) {
104
+ const place = {};
105
+
106
+ place.title = typeof block.title === 'string' ? block.title.trim() : '';
107
+ if (!place.title || place.title.length > 40) {
108
+ errors.push(`${where}.title must be 1-40 characters.`);
109
+ }
110
+
111
+ place.scene = block.scene ?? defaultScene;
112
+ if (typeof place.scene !== 'string' || !/^scenes\/[^/]+\.scene$/.test(place.scene)) {
113
+ errors.push(`${where}.scene must be a scenes/*.scene path.`);
114
+ } else if (!sceneExists(place.scene)) {
115
+ errors.push(`${where}.scene names ${place.scene}, which this deck does not have.`);
116
+ }
117
+
118
+ place.minPlayers = intIn(block.minPlayers, 1, 1, MAX_PLAYERS_CAP, `${where}.minPlayers`, errors);
119
+ place.maxPlayers = intIn(block.maxPlayers, Math.min(8, serverMax), 1, MAX_PLAYERS_CAP, `${where}.maxPlayers`, errors);
120
+ if (place.minPlayers > place.maxPlayers) {
121
+ errors.push(`${where}.minPlayers is more than maxPlayers.`);
122
+ }
123
+ if (place.maxPlayers > serverMax) {
124
+ errors.push(`${where}.maxPlayers (${place.maxPlayers}) is more than server.maxPlayers (${serverMax}).`);
125
+ }
126
+
127
+ place.lateJoin = block.lateJoin ?? false;
128
+ if (typeof place.lateJoin !== 'boolean') {
129
+ errors.push(`${where}.lateJoin must be true or false.`);
130
+ }
131
+
132
+
133
+ place.controller = block.controller ?? 'walk';
134
+ if (!CONTROLLERS.includes(place.controller)) {
135
+ errors.push(
136
+ RESERVED_CONTROLLERS.includes(place.controller)
137
+ ? `${where}.controller "${place.controller}" is not built yet; v1 has ${CONTROLLERS.join(', ')}.`
138
+ : `${where}.controller must be one of ${CONTROLLERS.join(', ')}.`,
139
+ );
140
+ }
141
+
142
+ place.nearestPlayers = intIn(
143
+ block.nearestPlayers,
144
+ NEAREST_PLAYERS,
145
+ 1,
146
+ NEAREST_PLAYERS_CAP,
147
+ `${where}.nearestPlayers`,
148
+ errors,
149
+ );
150
+ place.arrival = readArrival(block.arrival, `${where}.arrival`, errors);
151
+ place.result = block.result === undefined ? null : readResult(block.result, `${where}.result`, errors);
152
+ // A game has a longest visit; a place with no result (a town) has none
153
+ // unless it declares one.
154
+ place.maxDurationSec =
155
+ block.maxDurationSec === undefined && !place.result
156
+ ? null
157
+ : intIn(block.maxDurationSec, 600, 30, 1800, `${where}.maxDurationSec`, errors);
158
+ place.sign = block.sign === undefined ? null : readSign(block.sign, place.result, `${where}.sign`, errors);
159
+ place.npcs = block.npcs === undefined ? null : readNpcs(block.npcs, destinations, bundle, `${where}.npcs`, errors);
160
+ // v1.1: below this a player has fallen and the hub catches them (§5).
161
+ place.fallY = null;
162
+ if (block.fallY !== undefined) {
163
+ if (typeof block.fallY !== 'number' || !(block.fallY >= -25 && block.fallY <= 50)) {
164
+ errors.push(`${where}.fallY must be a number of metres from -25 to 50.`);
165
+ } else {
166
+ place.fallY = block.fallY;
167
+ }
168
+ }
169
+ // v1.3: players may pick up the place's loose objects and throw them (§6).
170
+ place.grab = readGrab(block.grab, `${where}.grab`, errors);
171
+ // v1.6: idle play. Only a place that declares it carries the key, so a
172
+ // place without it reads (and packs) exactly as before.
173
+ const idle = readIdle(block.idle, `${where}.idle`, errors);
174
+ if (idle) {
175
+ place.idle = idle;
176
+ }
177
+ return place;
178
+ }
179
+
180
+ // `grab`: absent or false is none; true is the defaults; an object sets any of
181
+ // them.
182
+ function readGrab(value, where, errors) {
183
+ if (value === undefined || value === false) {
184
+ return null;
185
+ }
186
+ if (value === true) {
187
+ return { ...GRAB_DEFAULTS };
188
+ }
189
+ if (!isObject(value)) {
190
+ errors.push(`${where} must be true, false or an object.`);
191
+ return null;
192
+ }
193
+ unknownKeys(value, Object.keys(GRAB_DEFAULTS), where, errors);
194
+ const grab = { ...GRAB_DEFAULTS };
195
+ for (const [key, [min, max, unit]] of Object.entries(GRAB_LIMITS)) {
196
+ if (value[key] === undefined) {
197
+ continue;
198
+ }
199
+ if (typeof value[key] !== 'number' || !(value[key] >= min && value[key] <= max)) {
200
+ errors.push(`${where}.${key} must be a number of ${unit} from ${min} to ${max}.`);
201
+ } else {
202
+ grab[key] = value[key];
203
+ }
204
+ }
205
+ return grab;
206
+ }
207
+
208
+ // `idle`: absent or false is none; true is emotes and seats; an object turns
209
+ // each on by name, and `sounds` lists the deck's sound files the place's
210
+ // server may play (`hub.sound`).
211
+ function readIdle(value, where, errors) {
212
+ if (value === undefined || value === false) {
213
+ return null;
214
+ }
215
+ if (value === true) {
216
+ return { emotes: true, seats: true, sounds: [] };
217
+ }
218
+ if (!isObject(value)) {
219
+ errors.push(`${where} must be true, false or an object.`);
220
+ return null;
221
+ }
222
+ unknownKeys(value, IDLE_KEYS, where, errors);
223
+ const idle = { emotes: false, seats: false, sounds: [] };
224
+ for (const key of ['emotes', 'seats']) {
225
+ if (value[key] !== undefined && typeof value[key] !== 'boolean') {
226
+ errors.push(`${where}.${key} must be true or false.`);
227
+ } else {
228
+ idle[key] = value[key] === true;
229
+ }
230
+ }
231
+ if (value.sounds !== undefined) {
232
+ const ok =
233
+ Array.isArray(value.sounds) &&
234
+ value.sounds.length <= MAX_SOUND_FILES &&
235
+ new Set(value.sounds).size === value.sounds.length &&
236
+ value.sounds.every(isSoundPath);
237
+ if (!ok) {
238
+ errors.push(
239
+ `${where}.sounds must be a list of at most ${MAX_SOUND_FILES} different ${SOUND_EXTS.join('/')} paths of this deck.`,
240
+ );
241
+ } else {
242
+ idle.sounds = [...value.sounds];
243
+ }
244
+ }
245
+ if (!idle.emotes && !idle.seats && !idle.sounds.length) {
246
+ return null;
247
+ }
248
+ return idle;
249
+ }
250
+
251
+ export function isSoundPath(path) {
252
+ return (
253
+ typeof path === 'string' &&
254
+ SOUND_PATH.test(path) &&
255
+ // Lower case, as the engine's media glob bundles them.
256
+ SOUND_EXTS.some((ext) => path.endsWith(ext)) &&
257
+ !path.split('/').some((part) => part === '..' || part === '.' || part === '')
258
+ );
259
+ }
260
+
261
+ // Where a place's NPC minds live (§13): the place itself (every layer talks
262
+ // to ghost's one place mind), optionally a destination route whose world an
263
+ // older SDK joins instead, and how much conversation each character takes.
264
+ function readNpcs(value, destinations, bundle, where, errors) {
265
+ if (!isObject(value)) {
266
+ errors.push(`${where} must be an object.`);
267
+ return null;
268
+ }
269
+ unknownKeys(value, ['route', 'slot', 'turnsPerMinute', 'disclosure', 'followSec'], where, errors);
270
+ const npcs = { route: null, slot: 'main', turnsPerMinute: 6, disclosure: 'participants', followSec: 120 };
271
+ // A route is optional: without one the minds are the place's (ghost's place
272
+ // mind, reached from every layer); with one, an SDK that cannot address the
273
+ // place's characters from a layer joins that world instead.
274
+ const route = destinations.find((d) => d?.routeId === value.route);
275
+ if (value.route === undefined) {
276
+ // place minds only
277
+ } else if (typeof value.route !== 'string' || !route) {
278
+ errors.push(`${where}.route must name one of server.destinations' routeIds.`);
279
+ } else if (route.characters !== 'shared') {
280
+ errors.push(`${where}.route "${value.route}" must declare characters: "shared".`);
281
+ } else {
282
+ npcs.route = value.route;
283
+ }
284
+ // A place's server, not a client, decides who hears a turn: ghost admits
285
+ // a turn's audience only for a bundle that says so.
286
+ if (!isObject(bundle) || !Array.isArray(bundle.characters) || !bundle.characters.length) {
287
+ errors.push(`${where} needs a castle.json characterBundle with the characters its NPCs speak for.`);
288
+ } else if (bundle.conversation?.version !== 1 || bundle.conversation?.authority !== 'server') {
289
+ errors.push(`${where} needs characterBundle.conversation: { "version": 1, "authority": "server", "maxListeners": 0 }.`);
290
+ }
291
+ if (value.slot !== undefined) {
292
+ if (typeof value.slot !== 'string' || !/^[A-Za-z0-9_.-]{1,64}$/.test(value.slot)) {
293
+ errors.push(`${where}.slot must be 1-64 letters, digits, '.', '_' or '-'.`);
294
+ } else {
295
+ npcs.slot = value.slot;
296
+ }
297
+ }
298
+ npcs.turnsPerMinute = intIn(value.turnsPerMinute, 6, 1, 30, `${where}.turnsPerMinute`, errors);
299
+ npcs.followSec = intIn(value.followSec, 120, 10, 600, `${where}.followSec`, errors);
300
+ if (value.disclosure !== undefined) {
301
+ if (value.disclosure !== 'participants' && value.disclosure !== 'world') {
302
+ errors.push(`${where}.disclosure must be "participants" or "world".`);
303
+ } else {
304
+ npcs.disclosure = value.disclosure;
305
+ }
306
+ }
307
+ return npcs;
308
+ }
309
+
310
+ function readArrival(value, where, errors) {
311
+ const arrival = { actor: null, spread: 1.5, face: 'actor' };
312
+ if (value === undefined) {
313
+ return arrival;
314
+ }
315
+ if (!isObject(value)) {
316
+ errors.push(`${where} must be an object.`);
317
+ return arrival;
318
+ }
319
+ unknownKeys(value, ['actor', 'spread', 'face'], where, errors);
320
+ if (value.actor !== undefined) {
321
+ if (typeof value.actor !== 'string' || !value.actor || value.actor.length > 128) {
322
+ errors.push(`${where}.actor must be a scene actor id.`);
323
+ } else {
324
+ arrival.actor = value.actor;
325
+ }
326
+ }
327
+ if (value.spread !== undefined) {
328
+ if (typeof value.spread !== 'number' || !(value.spread >= 0 && value.spread <= 5)) {
329
+ errors.push(`${where}.spread must be a number of metres from 0 to 5.`);
330
+ } else {
331
+ arrival.spread = value.spread;
332
+ }
333
+ }
334
+ if (value.face !== undefined) {
335
+ if (value.face === 'actor' || value.face === 'center' || (typeof value.face === 'number' && Number.isFinite(value.face))) {
336
+ arrival.face = value.face;
337
+ } else {
338
+ errors.push(`${where}.face must be "actor", "center" or a number of degrees.`);
339
+ }
340
+ }
341
+ return arrival;
342
+ }
343
+
344
+ function readResult(value, where, errors) {
345
+ if (!isObject(value)) {
346
+ errors.push(`${where} must be an object.`);
347
+ return null;
348
+ }
349
+ unknownKeys(value, ['outcomes', 'score', 'stats'], where, errors);
350
+ const result = { outcomes: OUTCOMES, score: null, stats: {} };
351
+ if (value.outcomes !== undefined) {
352
+ if (
353
+ !Array.isArray(value.outcomes) ||
354
+ !value.outcomes.length ||
355
+ !value.outcomes.every((o) => OUTCOMES.includes(o)) ||
356
+ new Set(value.outcomes).size !== value.outcomes.length
357
+ ) {
358
+ errors.push(`${where}.outcomes must be a non-empty list drawn from ${OUTCOMES.join(', ')}.`);
359
+ } else {
360
+ result.outcomes = [...value.outcomes];
361
+ }
362
+ }
363
+ if (value.score !== undefined) {
364
+ const score = value.score;
365
+ if (!isObject(score)) {
366
+ errors.push(`${where}.score must be an object.`);
367
+ } else {
368
+ unknownKeys(score, ['unit', 'better', 'min', 'max'], `${where}.score`, errors);
369
+ const unit = score.unit ?? 'points';
370
+ const better = score.better ?? 'higher';
371
+ if (!SCORE_UNITS.includes(unit)) {
372
+ errors.push(`${where}.score.unit must be one of ${SCORE_UNITS.join(', ')}.`);
373
+ }
374
+ if (better !== 'higher' && better !== 'lower') {
375
+ errors.push(`${where}.score.better must be "higher" or "lower".`);
376
+ }
377
+ const min = score.min ?? 0;
378
+ const max = score.max ?? 1e9;
379
+ if (!Number.isFinite(min) || !Number.isFinite(max) || min > max) {
380
+ errors.push(`${where}.score.min and max must be finite with min ≤ max.`);
381
+ }
382
+ result.score = { unit, better, min, max };
383
+ }
384
+ }
385
+ if (value.stats !== undefined) {
386
+ if (!isObject(value.stats) || Object.keys(value.stats).length > MAX_STATS) {
387
+ errors.push(`${where}.stats must be an object of at most ${MAX_STATS} names.`);
388
+ } else {
389
+ for (const [name, type] of Object.entries(value.stats)) {
390
+ if (!/^[a-zA-Z][a-zA-Z0-9_]{0,23}$/.test(name) || (type !== 'number' && type !== 'string')) {
391
+ errors.push(`${where}.stats.${name}: a stat is a short name and "number" or "string".`);
392
+ } else {
393
+ result.stats[name] = type;
394
+ }
395
+ }
396
+ }
397
+ }
398
+ return result;
399
+ }
400
+
401
+ function readSign(value, result, where, errors) {
402
+ if (!isObject(value)) {
403
+ errors.push(`${where} must be an object.`);
404
+ return null;
405
+ }
406
+ unknownKeys(value, ['model', 'board'], where, errors);
407
+ const sign = { model: null, board: null };
408
+ if (value.model !== undefined) {
409
+ if (typeof value.model !== 'string' || !/\.pxmodel$/.test(value.model)) {
410
+ errors.push(`${where}.model must be a .pxmodel path.`);
411
+ } else {
412
+ sign.model = value.model;
413
+ }
414
+ }
415
+ if (value.board !== undefined) {
416
+ const numeric = value.board === 'score' ? Boolean(result?.score) : result?.stats?.[value.board] === 'number';
417
+ if (!numeric) {
418
+ errors.push(`${where}.board must be "score" (with result.score declared) or a declared numeric stat.`);
419
+ } else {
420
+ sign.board = value.board;
421
+ }
422
+ }
423
+ return sign;
424
+ }
425
+
426
+ // Check one result a game reports against its place's declared shape. Returns
427
+ // `{ error }` or `{ result }`, the result reduced to declared fields.
428
+ export function checkResult(place, value) {
429
+ const shape = place.result;
430
+ if (!shape) {
431
+ return { error: `place "${place.title}" declares no result` };
432
+ }
433
+ if (!isObject(value)) {
434
+ return { error: 'a result is an object' };
435
+ }
436
+ // v1.1: the outcome may be left out where the score says it all (a solo
437
+ // time trial, a co-op run's time); a result still says something.
438
+ const hasOutcome = value.outcome !== undefined && value.outcome !== null;
439
+ if (hasOutcome && !shape.outcomes.includes(value.outcome)) {
440
+ return { error: `outcome must be one of ${shape.outcomes.join(', ')}` };
441
+ }
442
+ const hasScore = value.score !== undefined && value.score !== null;
443
+ if (!hasOutcome && !(shape.score && hasScore)) {
444
+ return { error: 'a result without an outcome needs a score' };
445
+ }
446
+ const out = hasOutcome ? { outcome: value.outcome } : {};
447
+ if (shape.score) {
448
+ if (value.score !== undefined && value.score !== null) {
449
+ if (typeof value.score !== 'number' || !Number.isFinite(value.score)) {
450
+ return { error: 'score must be a finite number' };
451
+ }
452
+ if (value.score < shape.score.min || value.score > shape.score.max) {
453
+ return { error: `score ${value.score} is outside ${shape.score.min}..${shape.score.max}` };
454
+ }
455
+ out.score = value.score;
456
+ }
457
+ } else if (value.score !== undefined && value.score !== null) {
458
+ return { error: 'this place declares no score' };
459
+ }
460
+ if (value.stats !== undefined) {
461
+ if (!isObject(value.stats)) {
462
+ return { error: 'stats must be an object' };
463
+ }
464
+ const stats = {};
465
+ for (const [name, v] of Object.entries(value.stats)) {
466
+ const type = Object.hasOwn(shape.stats, name) ? shape.stats[name] : null;
467
+ if (!type) {
468
+ return { error: `stat "${name}" is not declared` };
469
+ }
470
+ if (type === 'number' ? typeof v !== 'number' || !Number.isFinite(v) : typeof v !== 'string' || v.length > 40) {
471
+ return { error: `stat "${name}" must be a ${type === 'number' ? 'finite number' : 'string of at most 40 characters'}` };
472
+ }
473
+ stats[name] = v;
474
+ }
475
+ out.stats = stats;
476
+ }
477
+ for (const key of Object.keys(value)) {
478
+ if (!['outcome', 'score', 'stats'].includes(key)) {
479
+ return { error: `"${key}" is not part of a result` };
480
+ }
481
+ }
482
+ return { result: out };
483
+ }
484
+
485
+ // What a client is told about the place it is in: everything the hub chrome
486
+ // draws from, and nothing it does not need.
487
+ export function publicPlace(id, place) {
488
+ return {
489
+ contract: CONTRACT_VERSION,
490
+ id,
491
+ title: place.title,
492
+ scene: place.scene,
493
+ controller: place.controller,
494
+ maxDurationSec: place.maxDurationSec,
495
+ // v1.3: the hub chrome offers Grab only where this is set; a place
496
+ // without it is sent exactly what it was.
497
+ ...(place.grab ? { grab: { ...place.grab } } : {}),
498
+ // v1.6: likewise idle play.
499
+ ...(place.idle ? { idle: { emotes: place.idle.emotes, seats: place.idle.seats, sounds: [...place.idle.sounds] } } : {}),
500
+ result: place.result
501
+ ? { score: place.result.score ? { unit: place.result.score.unit, better: place.result.score.better } : null }
502
+ : null,
503
+ };
504
+ }
505
+
506
+ function intIn(value, fallback, min, max, where, errors) {
507
+ if (value === undefined) {
508
+ return fallback;
509
+ }
510
+ if (!Number.isInteger(value) || value < min || value > max) {
511
+ errors.push(`${where} must be a whole number from ${min} to ${max}.`);
512
+ return fallback;
513
+ }
514
+ return value;
515
+ }
516
+
517
+ function unknownKeys(block, allowed, where, errors) {
518
+ for (const key of Object.keys(block)) {
519
+ if (!allowed.includes(key)) {
520
+ errors.push(`${where}.${key} is not part of the hub contract v${CONTRACT_VERSION}.`);
521
+ }
522
+ }
523
+ }
524
+
525
+ function isObject(value) {
526
+ return value !== null && typeof value === 'object' && !Array.isArray(value);
527
+ }