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,627 @@
1
+ // Server-declared motion and colour of scene actors (contract §10, v1.1),
2
+ // kept apart so they can be tested without the engine. `h` is the hub layer's
3
+ // state: `actors` (the place's scene), `sim` (bodies, clock), `moves`,
4
+ // `poses`, `tints`, `tintWant`, `tintBudget`, `warned`.
5
+ //
6
+ // A game moves a scene actor whose `Body` is kinematic: the kit drives the
7
+ // body here and multiplayer-3d already sends every kinematic body's pose to
8
+ // every client. It recolours an actor drawn by a `Shape`: the colour rides in
9
+ // the snapshot like `hidden`, and the hub client paints it. Both are bounded so
10
+ // a game cannot flood a client: so many movers at once, so many colour changes
11
+ // a second, a box the world already keeps players in.
12
+
13
+ export const MAX_MOVERS = 64;
14
+ export const MOVE_MAX_MS = 60000;
15
+ // Colour changes a second across the place, with a burst; a change past the
16
+ // budget waits (the newest colour wins), so every client repaints at most so
17
+ // many meshes a second.
18
+ export const TINT_RATE = 20;
19
+ export const TINT_BURST = 40;
20
+ export const MAX_TINTS = 128;
21
+ // The box a moved actor stays in: multiplayer-3d's world bounds.
22
+ const BOUNDS = { xz: 200, low: -30, high: 80 };
23
+ // A turn a move may ask for at most (a hundred turns): enough for any spin,
24
+ // small enough that interpolating it stays finite.
25
+ const MAX_TURN_DEG = 36000;
26
+ const COLOR = /^#[0-9a-f]{6}$/;
27
+ const DEG = Math.PI / 180;
28
+
29
+ export function newActorState() {
30
+ return {
31
+ // actorId -> { from, to, startAt, endAt }: a move under way
32
+ moves: new Map(),
33
+ // actorId -> { x, y, z, rotationY }: where a moved actor was last put
34
+ poses: new Map(),
35
+ // actorId -> '#rrggbb': what clients paint, and changes waiting on the budget
36
+ tints: new Map(),
37
+ tintWant: new Map(),
38
+ tintBudget: { tokens: TINT_BURST, at: null },
39
+ // playerId -> { text, color }: the tag over a player's avatar
40
+ marks: new Map(),
41
+ // handovers `hub.reset` made, waiting for the session's next broadcast
42
+ // list, and actorId -> { claimable, until }: objects held unclaimable
43
+ // just after a reset (v1.3)
44
+ pendingHandovers: [],
45
+ resetHolds: new Map(),
46
+ // copy id -> { from, at, actor }: actors the game spawned (v1.2)
47
+ spawned: new Map(),
48
+ spawnCount: 0,
49
+ spawnBudget: { tokens: SPAWN_BURST, at: null },
50
+ // playerId -> { speed, jump }: a player's own controller tuning (v1.2),
51
+ // and what was last sent of each
52
+ tunes: new Map(),
53
+ sentTunes: new Map(),
54
+ };
55
+ }
56
+
57
+ export function warnOnce(h, key, text) {
58
+ h.warned ??= new Set();
59
+ if (!h.warned.has(key)) {
60
+ h.warned.add(key);
61
+ console.warn(`[hub] ${text}`);
62
+ }
63
+ }
64
+
65
+ // A scene actor of the place, or a copy the game spawned from one.
66
+ function sceneActor(h, id) {
67
+ if (typeof id !== 'string') {
68
+ return null;
69
+ }
70
+ return h.actors.find((a) => a.id === id) ?? h.spawned.get(id)?.actor ?? null;
71
+ }
72
+
73
+ export function isActor(h, id) {
74
+ return sceneActor(h, id) !== null;
75
+ }
76
+
77
+ // What `hub.actorsWith` hands a game for each actor: its marker, where it
78
+ // stands, and the size and body it was authored with, so a zone need not
79
+ // repeat its Shape in its marker's props.
80
+ export function describe(actor, name) {
81
+ const shape = actor.components.Shape;
82
+ return {
83
+ id: actor.id,
84
+ props: actor.components[name],
85
+ t: actor.components.Transform,
86
+ shape: shape
87
+ ? {
88
+ kind: shape.kind ?? 'box',
89
+ width: shape.width,
90
+ height: shape.height,
91
+ depth: shape.depth,
92
+ radius: shape.radius,
93
+ }
94
+ : null,
95
+ body: actor.components.Body?.type ?? null,
96
+ };
97
+ }
98
+
99
+ // The pose a moved actor is at now: its last move's, else as authored.
100
+ function poseOf(h, actor) {
101
+ const kept = h.poses.get(actor.id);
102
+ if (kept) {
103
+ return { ...kept };
104
+ }
105
+ const t = actor.components.Transform ?? {};
106
+ return { x: t.x ?? 0, y: t.y ?? 0, z: t.z ?? 0, rotationY: t.rotationY ?? 0 };
107
+ }
108
+
109
+ // `hub.move(actorId, to, { overMs })`: put a kinematic scene actor at `to`
110
+ // (`{ x, y, z, rotationY }`, any subset; the rest stays), at once or in a
111
+ // straight line over `overMs`. A later move replaces one under way, from
112
+ // wherever it has got to. Returns whether the move was taken.
113
+ export function move(h, actorId, to, options) {
114
+ const actor = sceneActor(h, actorId);
115
+ if (!actor) {
116
+ warnOnce(h, `move:${actorId}`, `hub.move: "${actorId}" is not an actor of this place's scene`);
117
+ return false;
118
+ }
119
+ if (actor.components.Body?.type !== 'kinematic' || !h.sim?.bodies.get(actorId)) {
120
+ warnOnce(h, `move:${actorId}`, `hub.move: "${actorId}" needs a Body of type "kinematic" and a Shape`);
121
+ return false;
122
+ }
123
+ if (!to || typeof to !== 'object') {
124
+ return false;
125
+ }
126
+ if (!h.moves.has(actorId) && h.moves.size >= MAX_MOVERS) {
127
+ warnOnce(h, 'move:max', `hub.move: at most ${MAX_MOVERS} actors move at once`);
128
+ return false;
129
+ }
130
+ const from = currentPose(h, actor);
131
+ const target = { ...from };
132
+ for (const key of ['x', 'y', 'z', 'rotationY']) {
133
+ if (to[key] === undefined) {
134
+ continue;
135
+ }
136
+ if (typeof to[key] !== 'number' || !Number.isFinite(to[key])) {
137
+ warnOnce(h, `move:nan:${actorId}`, `hub.move: ${key} must be a finite number`);
138
+ return false;
139
+ }
140
+ target[key] = to[key];
141
+ }
142
+ if (Math.abs(target.rotationY) > MAX_TURN_DEG) {
143
+ warnOnce(h, `move:turn:${actorId}`, `hub.move: rotationY is at most ${MAX_TURN_DEG} degrees either way`);
144
+ return false;
145
+ }
146
+ if (Math.abs(target.x) > BOUNDS.xz || Math.abs(target.z) > BOUNDS.xz || target.y < BOUNDS.low || target.y > BOUNDS.high) {
147
+ warnOnce(h, `move:bounds:${actorId}`, `hub.move: "${actorId}" would leave the world`);
148
+ return false;
149
+ }
150
+ const overMs = options?.overMs;
151
+ const span = typeof overMs === 'number' && Number.isFinite(overMs) ? Math.max(0, Math.min(MOVE_MAX_MS, overMs)) : 0;
152
+ const now = h.sim.timeMs;
153
+ h.moves.set(actorId, { from, to: target, startAt: now, endAt: now + span });
154
+ return true;
155
+ }
156
+
157
+ // Where a moving actor is between its moves' ends.
158
+ function currentPose(h, actor) {
159
+ const m = h.moves.get(actor.id);
160
+ return m ? poseAt(m, h.sim.timeMs) : poseOf(h, actor);
161
+ }
162
+
163
+ function poseAt(m, now) {
164
+ const span = m.endAt - m.startAt;
165
+ const k = span <= 0 ? 1 : Math.max(0, Math.min(1, (now - m.startAt) / span));
166
+ const lerp = (a, b) => a + (b - a) * k;
167
+ return {
168
+ x: lerp(m.from.x, m.to.x),
169
+ y: lerp(m.from.y, m.to.y),
170
+ z: lerp(m.from.z, m.to.z),
171
+ rotationY: lerp(m.from.rotationY, m.to.rotationY),
172
+ };
173
+ }
174
+
175
+ // Each tick, before the physics step: every move under way puts its body
176
+ // where it should be by now, through Rapier's kinematic target, so players
177
+ // and bodies it meets are pushed the way a door pushes them. A finished move
178
+ // is dropped; its body stays.
179
+ export function driveMoves(h) {
180
+ const now = h.sim.timeMs;
181
+ for (const [id, m] of h.moves) {
182
+ const body = h.sim.bodies.get(id);
183
+ const actor = sceneActor(h, id);
184
+ if (!body || !actor) {
185
+ h.moves.delete(id);
186
+ continue;
187
+ }
188
+ const pose = poseAt(m, now);
189
+ const t = actor.components.Transform ?? {};
190
+ body.setNextKinematicTranslation({ x: pose.x, y: pose.y, z: pose.z });
191
+ body.setNextKinematicRotation(quat(t.rotationX ?? 0, pose.rotationY, t.rotationZ ?? 0));
192
+ if (now >= m.endAt) {
193
+ // A finished turn is kept within one turn, so a spin that keeps asking
194
+ // for another turn from where it is never grows.
195
+ pose.rotationY = ((pose.rotationY % 360) + 360) % 360;
196
+ h.moves.delete(id);
197
+ }
198
+ h.poses.set(id, pose);
199
+ }
200
+ }
201
+
202
+ // `hub.tint(actorId, color)`: paint a Shape actor `#rrggbb` for everyone;
203
+ // null puts back its authored colour. Not an actor drawn by a Model (a paint
204
+ // would rebuild the whole model on every client), nor a dynamic body (the
205
+ // client rebuilds a body whose Shape changed, which would stop it dead).
206
+ export function tint(h, actorId, color) {
207
+ const actor = sceneActor(h, actorId);
208
+ if (!actor?.components.Shape || actor.components.Model || actor.components.Body?.type === 'dynamic') {
209
+ warnOnce(h, `tint:${actorId}`, `hub.tint: "${actorId}" is not a Shape actor of this place's scene without a Model or a dynamic Body`);
210
+ return false;
211
+ }
212
+ if (color === null || color === undefined) {
213
+ h.tintWant.set(actorId, null);
214
+ return true;
215
+ }
216
+ const clean = typeof color === 'string' ? color.toLowerCase() : '';
217
+ if (!COLOR.test(clean)) {
218
+ warnOnce(h, `tint:color:${actorId}`, 'hub.tint: a colour is "#rrggbb"');
219
+ return false;
220
+ }
221
+ if (!paintedAfter(h).has(actorId) && paintedAfter(h).size >= MAX_TINTS) {
222
+ warnOnce(h, 'tint:max', `hub.tint: at most ${MAX_TINTS} actors are tinted at once`);
223
+ return false;
224
+ }
225
+ h.tintWant.set(actorId, clean);
226
+ return true;
227
+ }
228
+
229
+ // The actors that will be painted once every waiting change has landed.
230
+ function paintedAfter(h) {
231
+ const out = new Set(h.tints.keys());
232
+ for (const [id, color] of h.tintWant) {
233
+ if (color === null) {
234
+ out.delete(id);
235
+ } else {
236
+ out.add(id);
237
+ }
238
+ }
239
+ return out;
240
+ }
241
+
242
+ // Each tick: the waiting colour changes the budget allows reach `tints`, the
243
+ // map the snapshot carries. One that changes nothing costs nothing.
244
+ export function flushTints(h) {
245
+ const now = h.sim?.timeMs ?? 0;
246
+ const budget = h.tintBudget;
247
+ if (budget.at !== null) {
248
+ budget.tokens = Math.min(TINT_BURST, budget.tokens + ((now - budget.at) / 1000) * TINT_RATE);
249
+ }
250
+ budget.at = now;
251
+ // Clears first, so a paint never waits on (or squeezes past the cap ahead
252
+ // of) a clear queued after it; a paint that would pass the cap waits.
253
+ for (const clearing of [true, false]) {
254
+ for (const [id, color] of h.tintWant) {
255
+ if ((color === null) !== clearing) {
256
+ continue;
257
+ }
258
+ const same = color === null ? !h.tints.has(id) : h.tints.get(id) === color;
259
+ if (!same) {
260
+ if (budget.tokens < 1 || (color !== null && !h.tints.has(id) && h.tints.size >= MAX_TINTS)) {
261
+ continue;
262
+ }
263
+ budget.tokens -= 1;
264
+ if (color === null) {
265
+ h.tints.delete(id);
266
+ } else {
267
+ h.tints.set(id, color);
268
+ }
269
+ }
270
+ h.tintWant.delete(id);
271
+ }
272
+ }
273
+ }
274
+
275
+ // `hub.mark(playerId, { text, color })`: a coloured tag the hub chrome draws
276
+ // over a player's avatar for everyone -- a team, who is it. `text` is up to
277
+ // MARK_TEXT characters (none draws a dot), `color` `#rrggbb`; null clears it.
278
+ // One mark per player, so the snapshot holds at most a place's players.
279
+ export const MARK_TEXT = 16;
280
+
281
+ export function mark(h, playerId, spec) {
282
+ if (typeof playerId !== 'string' || !h.players.has(playerId)) {
283
+ warnOnce(h, `mark:${playerId}`, `hub.mark: "${playerId}" is not a player here`);
284
+ return false;
285
+ }
286
+ if (spec === null || spec === undefined) {
287
+ h.marks.delete(playerId);
288
+ return true;
289
+ }
290
+ const color = typeof spec?.color === 'string' ? spec.color.toLowerCase() : '';
291
+ if (!COLOR.test(color)) {
292
+ warnOnce(h, 'mark:color', 'hub.mark: a mark needs a colour "#rrggbb"');
293
+ return false;
294
+ }
295
+ const text = spec.text === undefined || spec.text === null ? '' : String(spec.text).slice(0, MARK_TEXT);
296
+ h.marks.set(playerId, { text, color });
297
+ return true;
298
+ }
299
+
300
+ export function marksOf(h) {
301
+ return Object.fromEntries(h.marks);
302
+ }
303
+
304
+ // `hub.spawn(fromActorId, { x, y, z, rotationY })`: a copy of one of the
305
+ // place's scene actors (its template), for everyone, at a point; returns the
306
+ // copy's id, which is never reused, or null. `hub.despawn(id)` removes a copy.
307
+ // A copy is an actor like its template: move, tint, hide and label it. The
308
+ // template may be hidden (a prototype nobody sees). Not a template with a
309
+ // dynamic Body (its ownership is the multiplayer kit's), nor a player, door or
310
+ // NPC. Bounded: MAX_SPAWNED copies alive, SPAWN_RATE spawns a second with
311
+ // bursts of SPAWN_BURST, so the snapshot and every client's actor count stay
312
+ // small.
313
+ export const MAX_SPAWNED = 96;
314
+ export const SPAWN_RATE = 10;
315
+ export const SPAWN_BURST = 40;
316
+ const NOT_TEMPLATES = ['Player', 'HubDoor', 'HubNpc', 'HubPad', 'Pickup'];
317
+
318
+ export function spawn(h, fromId, at, engine) {
319
+ const template = typeof fromId === 'string' ? h.actors.find((a) => a.id === fromId) : null;
320
+ const c = template?.components;
321
+ if (!c || !c.Transform || !c.Shape || NOT_TEMPLATES.some((name) => c[name]) || c.Body?.type === 'dynamic') {
322
+ warnOnce(h, `spawn:${fromId}`, `hub.spawn: "${fromId}" is not a scene actor of this place that can be copied (a Shape; no dynamic Body, Pickup, player, door, pad or NPC)`);
323
+ return null;
324
+ }
325
+ const t = c.Transform;
326
+ const point = { x: t.x ?? 0, y: t.y ?? 0, z: t.z ?? 0, rotationY: t.rotationY ?? 0 };
327
+ for (const key of ['x', 'y', 'z', 'rotationY']) {
328
+ if (at?.[key] === undefined) {
329
+ continue;
330
+ }
331
+ if (typeof at[key] !== 'number' || !Number.isFinite(at[key])) {
332
+ warnOnce(h, 'spawn:nan', `hub.spawn: ${key} must be a finite number`);
333
+ return null;
334
+ }
335
+ point[key] = at[key];
336
+ }
337
+ point.rotationY = ((point.rotationY % 360) + 360) % 360;
338
+ if (Math.abs(point.x) > BOUNDS.xz || Math.abs(point.z) > BOUNDS.xz || point.y < BOUNDS.low || point.y > BOUNDS.high) {
339
+ warnOnce(h, 'spawn:bounds', 'hub.spawn: that point is outside the world');
340
+ return null;
341
+ }
342
+ if (h.spawned.size >= MAX_SPAWNED) {
343
+ warnOnce(h, 'spawn:max', `hub.spawn: at most ${MAX_SPAWNED} copies at once`);
344
+ return null;
345
+ }
346
+ const budget = h.spawnBudget;
347
+ const now = h.sim?.timeMs ?? 0;
348
+ if (budget.at !== null) {
349
+ budget.tokens = Math.min(SPAWN_BURST, budget.tokens + ((now - budget.at) / 1000) * SPAWN_RATE);
350
+ }
351
+ budget.at = now;
352
+ if (budget.tokens < 1) {
353
+ warnOnce(h, 'spawn:rate', `hub.spawn: at most ${SPAWN_RATE} spawns a second`);
354
+ return null;
355
+ }
356
+ budget.tokens -= 1;
357
+ // A fresh id: never one the scene authored or an earlier copy had.
358
+ let id;
359
+ do {
360
+ h.spawnCount += 1;
361
+ id = `${fromId}~${h.spawnCount}`;
362
+ } while (h.actors.some((a) => a.id === id) || h.spawned.has(id));
363
+ const components = { ...c, Transform: { ...t, x: point.x, y: point.y, z: point.z, rotationY: point.rotationY } };
364
+ const actor = { id, components };
365
+ h.spawned.set(id, { from: fromId, at: point, actor });
366
+ // The copy's body, as the world builds a scene actor's: solid or a sensor,
367
+ // fixed or kinematic; a kinematic one's pose reaches every client.
368
+ if (h.sim && engine?.createBody) {
369
+ const rb = engine.createBody(h.sim, actor, components.Transform, c.Shape, c.Body);
370
+ h.sim.bodies.set(id, rb);
371
+ if (c.Body?.type === 'kinematic') {
372
+ h.sim.objects?.set(id, {
373
+ body: rb,
374
+ home: { x: point.x, y: point.y, z: point.z },
375
+ claimable: false,
376
+ fast: false,
377
+ owner: null,
378
+ reportedAt: 0,
379
+ claimedAt: 0,
380
+ epoch: 0,
381
+ ack: null,
382
+ });
383
+ }
384
+ }
385
+ return id;
386
+ }
387
+
388
+ export function despawn(h, id, engine) {
389
+ if (!h.spawned.delete(id)) {
390
+ return false;
391
+ }
392
+ h.moves.delete(id);
393
+ h.poses.delete(id);
394
+ h.tints.delete(id);
395
+ h.tintWant.delete(id);
396
+ h.hidden?.delete(id);
397
+ h.labels?.delete(id);
398
+ for (const mine of h.labelsMe?.values() ?? []) {
399
+ mine.delete(id);
400
+ }
401
+ if (h.sim && engine?.removeActor) {
402
+ engine.removeActor(h.sim, id);
403
+ }
404
+ return true;
405
+ }
406
+
407
+ // A copy a client reported gone (the multiplayer kit's GONE, which drops its
408
+ // body) is gone for the game too.
409
+ export function dropLostSpawns(h, engine) {
410
+ for (const [id, entry] of h.spawned) {
411
+ if (engine?.createBody && h.sim && !h.sim.bodies.has(id)) {
412
+ despawn(h, id, engine);
413
+ }
414
+ }
415
+ }
416
+
417
+ // The authored components of every template a live copy was made from, so a
418
+ // client draws a copy as authored whatever has become of its template there
419
+ // (painted, hidden, reported gone before this client joined).
420
+ export function templatesOf(h) {
421
+ // No prototype: a template may be called `__proto__`.
422
+ const out = Object.create(null);
423
+ for (const { from } of h.spawned.values()) {
424
+ if (!Object.hasOwn(out, from)) {
425
+ out[from] = h.actors.find((a) => a.id === from)?.components ?? null;
426
+ }
427
+ }
428
+ return out;
429
+ }
430
+
431
+ export function spawnedOf(h) {
432
+ const out = Object.create(null);
433
+ for (const [id, { from, at }] of h.spawned) {
434
+ out[id] = { from, ...at };
435
+ }
436
+ return out;
437
+ }
438
+
439
+ export function tintsOf(h) {
440
+ return Object.fromEntries(h.tints);
441
+ }
442
+
443
+ function quat(rx, ry, rz) {
444
+ const cx = Math.cos(rx * DEG * 0.5);
445
+ const sx = Math.sin(rx * DEG * 0.5);
446
+ const cy = Math.cos(ry * DEG * 0.5);
447
+ const sy = Math.sin(ry * DEG * 0.5);
448
+ const cz = Math.cos(rz * DEG * 0.5);
449
+ const sz = Math.sin(rz * DEG * 0.5);
450
+ return {
451
+ x: sx * cy * cz + cx * sy * sz,
452
+ y: cx * sy * cz - sx * cy * sz,
453
+ z: cx * cy * sz + sx * sy * cz,
454
+ w: cx * cy * cz - sx * sy * sz,
455
+ };
456
+ }
457
+
458
+ // `hub.tune(playerId, { speed, jump })`: one player's own walk controller,
459
+ // as multipliers of the place's preset (its scene Player's `speed` and
460
+ // `jumpSpeed`): +1 speed games. Clamped to TUNE_BOUNDS; null puts the preset
461
+ // back. The server's movement clamp for that player follows it, so a tuned
462
+ // player is not pulled back, and nobody else moves faster.
463
+ export const TUNE_BOUNDS = { speed: [0.25, 3], jump: [0.5, 2.5] };
464
+
465
+ export function tune(h, playerId, spec) {
466
+ if (typeof playerId !== 'string' || !h.players.has(playerId)) {
467
+ warnOnce(h, `tune:${playerId}`, `hub.tune: "${playerId}" is not a player here`);
468
+ return false;
469
+ }
470
+ if (spec === null || spec === undefined) {
471
+ h.tunes.delete(playerId);
472
+ return true;
473
+ }
474
+ const out = { speed: 1, jump: 1 };
475
+ for (const key of ['speed', 'jump']) {
476
+ if (spec[key] === undefined) {
477
+ continue;
478
+ }
479
+ if (typeof spec[key] !== 'number' || !Number.isFinite(spec[key])) {
480
+ warnOnce(h, 'tune:nan', `hub.tune: ${key} must be a finite number`);
481
+ return false;
482
+ }
483
+ const [lo, hi] = TUNE_BOUNDS[key];
484
+ out[key] = Math.round(Math.min(hi, Math.max(lo, spec[key])) * 100) / 100;
485
+ }
486
+ if (out.speed === 1 && out.jump === 1) {
487
+ h.tunes.delete(playerId);
488
+ } else {
489
+ h.tunes.set(playerId, out);
490
+ }
491
+ return true;
492
+ }
493
+
494
+ // Each tick: every tuned body's movement clamp (`maxSpeed`, read by
495
+ // multiplayer-3d's players.setPose) follows its tuning, so a respawned body
496
+ // gets it again; and each player is told their own tuning when it changes.
497
+ export function applyTunes(h, baseMaxSpeed) {
498
+ for (const [playerId, body] of h.sim?.players ?? []) {
499
+ const t = h.tunes.get(playerId);
500
+ const factor = t ? Math.max(1, t.speed, t.jump) : 1;
501
+ body.maxSpeed = factor === 1 ? undefined : baseMaxSpeed * factor;
502
+ const json = JSON.stringify(t ?? null);
503
+ if ((h.sentTunes.get(playerId) ?? 'null') !== json) {
504
+ h.sentTunes.set(playerId, json);
505
+ h.session?.send(playerId, { k: 'hub-tune', tune: t ?? null });
506
+ }
507
+ }
508
+ }
509
+
510
+ // `hub.pose(actorId)`: where a scene actor's body is now, as the server
511
+ // simulates it -- `{ x, y, z, rotationY, velocity: { x, y, z }, owner }`,
512
+ // `owner` the player whose client simulates it (a loose object near them) or
513
+ // null -- or null for an actor with no body (v1.3).
514
+ export function pose(h, actorId) {
515
+ const body = typeof actorId === 'string' ? h.sim?.bodies.get(actorId) : null;
516
+ if (!body) {
517
+ return null;
518
+ }
519
+ const t = body.translation();
520
+ const q = body.rotation();
521
+ const v = body.linvel?.() ?? { x: 0, y: 0, z: 0 };
522
+ // Its heading: the way its forward (+z) points, on the ground, in degrees
523
+ // (for an upright body, its Transform.rotationY).
524
+ const yaw = Math.atan2(2 * (q.x * q.z + q.w * q.y), 1 - 2 * (q.x * q.x + q.y * q.y)) / DEG;
525
+ return {
526
+ x: t.x,
527
+ y: t.y,
528
+ z: t.z,
529
+ rotationY: ((yaw % 360) + 360) % 360,
530
+ velocity: { x: v.x, y: v.y, z: v.z },
531
+ owner: h.sim.objects?.get(actorId)?.owner ?? null,
532
+ };
533
+ }
534
+
535
+ // `hub.reset(actorId, at?)`: put a loose object (a dynamic scene actor) back
536
+ // -- where it was authored, or at `at` (`{ x, y, z, rotationY }`, any
537
+ // subset) -- at rest. A client simulating it is told it is the server's again
538
+ // (a multiplayer-3d handover, so that client stops moving its copy), and the
539
+ // object is placed. Bounded like a spawn: RESET_RATE a second with bursts of
540
+ // RESET_BURST, and inside the world box. Returns whether it was put back.
541
+ export const RESET_RATE = 20;
542
+ export const RESET_BURST = 40;
543
+ // After a reset nobody may be granted the object for this long, so every
544
+ // client has the reset pose before one can simulate it again.
545
+ export const RESET_HOLD_MS = 500;
546
+
547
+ export function reset(h, actorId, at, engine) {
548
+ const actor = typeof actorId === 'string' ? h.actors.find((a) => a.id === actorId) : null;
549
+ const entry = actor?.components.Body?.type === 'dynamic' ? h.sim?.objects?.get(actorId) : null;
550
+ if (!entry?.body) {
551
+ warnOnce(h, `reset:${actorId}`, `hub.reset: "${actorId}" is not a dynamic actor of this place's scene`);
552
+ return false;
553
+ }
554
+ const t = actor.components.Transform ?? {};
555
+ const point = { x: entry.home.x, y: entry.home.y, z: entry.home.z, rotationY: t.rotationY ?? 0 };
556
+ for (const key of ['x', 'y', 'z', 'rotationY']) {
557
+ if (at?.[key] === undefined) {
558
+ continue;
559
+ }
560
+ if (typeof at[key] !== 'number' || !Number.isFinite(at[key])) {
561
+ warnOnce(h, 'reset:nan', `hub.reset: ${key} must be a finite number`);
562
+ return false;
563
+ }
564
+ point[key] = at[key];
565
+ }
566
+ point.rotationY = ((point.rotationY % 360) + 360) % 360;
567
+ if (Math.abs(point.x) > BOUNDS.xz || Math.abs(point.z) > BOUNDS.xz || point.y < BOUNDS.low || point.y > BOUNDS.high) {
568
+ warnOnce(h, 'reset:bounds', 'hub.reset: that point is outside the world');
569
+ return false;
570
+ }
571
+ h.resetBudget ??= { tokens: RESET_BURST, at: null };
572
+ const budget = h.resetBudget;
573
+ const now = h.sim.timeMs;
574
+ if (budget.at !== null) {
575
+ budget.tokens = Math.min(RESET_BURST, budget.tokens + ((now - budget.at) / 1000) * RESET_RATE);
576
+ }
577
+ budget.at = now;
578
+ if (budget.tokens < 1) {
579
+ warnOnce(h, 'reset:rate', `hub.reset: at most ${RESET_RATE} resets a second`);
580
+ return false;
581
+ }
582
+ budget.tokens -= 1;
583
+ // Taken back from its owner first: the handover (at rest) is queued for the
584
+ // next broadcast (`flushHandovers`), and a report from that owner's old
585
+ // grant is dropped.
586
+ if (entry.owner && engine?.release) {
587
+ const rows = [];
588
+ engine.release(h.sim, entry.owner, [actorId], rows);
589
+ for (const row of rows) {
590
+ if (row[0] === actorId) {
591
+ row.fill(0, 2, 8);
592
+ }
593
+ h.pendingHandovers.push(row);
594
+ }
595
+ }
596
+ // Not claimable for a moment, so no client is handed it before it has the
597
+ // reset pose (`releaseResetHolds` gives it back).
598
+ if (!h.resetHolds.has(actorId)) {
599
+ h.resetHolds.set(actorId, { claimable: entry.claimable, until: 0 });
600
+ }
601
+ h.resetHolds.get(actorId).until = now + RESET_HOLD_MS;
602
+ entry.claimable = false;
603
+ entry.body.setTranslation({ x: point.x, y: point.y, z: point.z }, true);
604
+ entry.body.setRotation(quat(t.rotationX ?? 0, point.rotationY, t.rotationZ ?? 0), true);
605
+ entry.body.setLinvel({ x: 0, y: 0, z: 0 }, true);
606
+ entry.body.setAngvel?.({ x: 0, y: 0, z: 0 }, true);
607
+ return true;
608
+ }
609
+
610
+ // Each tick (place and step): hand the session the handovers resets made,
611
+ // whenever they were made, and let reset objects be claimed again once their
612
+ // hold is over.
613
+ export function flushHandovers(h, handovers) {
614
+ if (handovers && h.pendingHandovers.length) {
615
+ handovers.push(...h.pendingHandovers.splice(0));
616
+ }
617
+ const now = h.sim?.timeMs ?? 0;
618
+ for (const [id, hold] of h.resetHolds) {
619
+ if (now >= hold.until) {
620
+ const entry = h.sim?.objects?.get(id);
621
+ if (entry) {
622
+ entry.claimable = hold.claimable;
623
+ }
624
+ h.resetHolds.delete(id);
625
+ }
626
+ }
627
+ }