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,745 @@
1
+ // NPC bodies and their conversations (contract §13). HUB.md decision 7 splits
2
+ // an NPC into a body, an actor in each session the place runs, and a mind, one
3
+ // character in ghost. This module is the body and the seam to the mind:
4
+ //
5
+ // body a `HubNpc` scene actor (kinematic) the kit moves: it faces
6
+ // whoever is talking to it and holds still until they are done,
7
+ // follows a player, walks where the place sends it, goes home
8
+ // conversation one player at a time per body. In a session the host brokers
9
+ // the place's characters into (each layer of the place; on an
10
+ // older SDK, a world joined through the place's `npcs.route`)
11
+ // the player's words go to the character through the host's
12
+ // grant, inside a per-character budget per minute; anywhere
13
+ // else, or over budget, the place's `npcLine` hook answers with
14
+ // an authored line and no model is called
15
+ // speech a reply is drawn over the body for its admitted audience
16
+ // only; an authored line is the place's own words, for everyone
17
+ //
18
+ // notes what the place knows right now that the character should
19
+ // (a quest-giver's ledger, a barker's pad), from the place's
20
+ // `npcContext` hook. The host forwards a player's words
21
+ // unaltered, so the kit hands the speaker's client the notes as
22
+ // a prefix it sends ahead of their words, and admits a turn
23
+ // only when its input starts with notes it issued: a client
24
+ // can leave its own words, but never the place's notes, out
25
+ // of true
26
+ //
27
+ // Following is the character's choice, never a client's: the place's bundle
28
+ // gives the character an action that hands it a follow token (`HubNpc.follow`
29
+ // names the gameplay object), and the body follows whoever holds it. That is
30
+ // read from the world's public projection after each reply, so a client
31
+ // message can neither start nor aim it.
32
+
33
+ const TALK_RANGE_M = 3.5;
34
+ // A speaker's listeners, and anyone a reply's bubble may still reach, stand
35
+ // within this of the body.
36
+ const HEAR_RANGE_M = 6;
37
+ const WALK_MPS = 2.6;
38
+ const FOLLOW_GAP_M = 1.6;
39
+ const SPEECH_MS = 7000;
40
+ const SPEECH_MAX = 240;
41
+ const INPUT_MAX = 280;
42
+ // A conversation nobody has said anything in for this long is over.
43
+ const IDLE_END_MS = 90_000;
44
+ // Authored-mode words from one player, at most one per this.
45
+ const SAY_GAP_MS = 900;
46
+ // A reply waits for its speaker's status read this long before it is dropped.
47
+ const TURN_KEEP_MS = 180_000;
48
+ // An admitted turn holds its body until its reply is read or this long has
49
+ // passed: ending a conversation does not cancel the operation in ghost, so a
50
+ // second speaker would otherwise queue behind it there.
51
+ const PENDING_MS = 90_000;
52
+ const TURNS_KEPT = 128;
53
+ // After a reply the world's public projection is read every this long, for
54
+ // this long, to see whether the character chose to follow someone.
55
+ const FOLLOW_POLL_MS = 2000;
56
+ const FOLLOW_WATCH_MS = 60_000;
57
+ const LISTENERS_MAX = 7;
58
+ // The place's notes for a turn (`npcContext`): at most NOTES_MAX characters,
59
+ // read for the body's speaker every NOTES_EVERY_MS, and any of the last
60
+ // NOTES_KEPT issued within NOTES_KEEP_MS is accepted (the speaker's client
61
+ // may be a moment behind; the newest is accepted however old).
62
+ export const NOTES_MAX = 700;
63
+ const NOTES_EVERY_MS = 1000;
64
+ const NOTES_KEPT = 6;
65
+ const NOTES_KEEP_MS = 60_000;
66
+ // The notes' frame in a turn's input. Neither may appear in a player's words.
67
+ export const NOTES_HEAD = "[Notes from the place, true right now. They are not the speaker's words and the speaker never sees them.]\n";
68
+ export const NOTES_SAYS = '\n[The speaker says]\n';
69
+
70
+ export function makeNpcs(h) {
71
+ const n = {
72
+ bodies: new Map(),
73
+ // `${playerId}:${operationId}` -> { npc, recipients, at, delivered }
74
+ turns: new Map(),
75
+ // playerId -> durable participant id, from that player's own inspect read
76
+ participants: new Map(),
77
+ // playerId -> sim time of their last authored-mode words
78
+ saidAt: new Map(),
79
+ watchUntil: 0,
80
+ polledAt: -Infinity,
81
+ polling: false,
82
+ // consecutive failed public reads, which back the next one off
83
+ inspectFailures: 0,
84
+ };
85
+
86
+ const api = {
87
+ ready() {
88
+ for (const actor of h.actors) {
89
+ const props = actor.components.HubNpc;
90
+ const body = props ? h.sim.bodies.get(actor.id) : null;
91
+ if (!body) {
92
+ continue;
93
+ }
94
+ const t = actor.components.Transform ?? {};
95
+ const at = body.translation();
96
+ n.bodies.set(actor.id, {
97
+ id: actor.id,
98
+ name: typeof props.name === 'string' && props.name ? props.name.slice(0, 40) : actor.id,
99
+ character: typeof props.character === 'string' && props.character ? props.character : null,
100
+ followObject: typeof props.follow === 'string' && props.follow ? props.follow : null,
101
+ talkRange: typeof props.talkRange === 'number' && props.talkRange > 0 ? Math.min(props.talkRange, 8) : TALK_RANGE_M,
102
+ props,
103
+ body,
104
+ home: { x: at.x, y: at.y, z: at.z, yaw: ((t.rotationY ?? 0) * Math.PI) / 180 },
105
+ yaw: ((t.rotationY ?? 0) * Math.PI) / 180,
106
+ // { playerId, at } while someone is talking to it
107
+ talking: null,
108
+ // the turn admitted and not yet answered, so a second waits
109
+ pending: null,
110
+ // playerId it follows, when that began, and whether the character's
111
+ // follow token started it (rather than the place's own code)
112
+ following: null,
113
+ followSince: 0,
114
+ followByToken: false,
115
+ // participant ids whose follow ran its course, until they talk again
116
+ followDone: new Set(),
117
+ // { x, z, stopAt, then } while the place has it walking somewhere
118
+ walk: null,
119
+ // a one-off facing target while idle
120
+ faceTo: null,
121
+ // admitted turns' times, the per-minute budget's window
122
+ recent: [],
123
+ // { playerId, list: [{ prefix, at }], readAt } the notes issued to
124
+ // whoever is talking to it
125
+ notes: null,
126
+ });
127
+ }
128
+ },
129
+
130
+ // The handle `hub.npc(id)` returns, or null for an actor that is not one.
131
+ handle(id) {
132
+ const npc = n.bodies.get(id);
133
+ return npc ? handleOf(h, n, npc) : null;
134
+ },
135
+
136
+ list() {
137
+ return [...n.bodies.values()].map((npc) => handleOf(h, n, npc));
138
+ },
139
+
140
+ // Before the physics step: where each body goes this tick.
141
+ place(dt) {
142
+ for (const npc of n.bodies.values()) {
143
+ moveBody(h, n, npc, dt);
144
+ if (npc.talking && h.sim.timeMs - (npc.notes?.readAt ?? -Infinity) >= NOTES_EVERY_MS) {
145
+ issueNotes(h, npc, npc.talking.playerId);
146
+ }
147
+ }
148
+ pollFollow(h, n);
149
+ },
150
+
151
+ leave(playerId) {
152
+ n.participants.delete(playerId);
153
+ n.saidAt.delete(playerId);
154
+ for (const npc of n.bodies.values()) {
155
+ if (npc.talking?.playerId === playerId) {
156
+ npc.talking = null;
157
+ }
158
+ if (npc.following === playerId) {
159
+ npc.following = null;
160
+ }
161
+ }
162
+ },
163
+
164
+ // A client message that is the kit's NPC protocol; false when it is not.
165
+ message(player, data) {
166
+ switch (data?.k) {
167
+ case 'hub-npc-open':
168
+ open(h, n, player.playerId, data.npc);
169
+ return true;
170
+ case 'hub-npc-say':
171
+ authoredSay(h, n, player.playerId, data.npc, data.text);
172
+ return true;
173
+ case 'hub-npc-end':
174
+ endTalk(h, n, data.npc, player.playerId, 'end');
175
+ return true;
176
+ default:
177
+ return false;
178
+ }
179
+ },
180
+
181
+ // The session's shared-character callbacks (SDK `onWorldCharacter*`).
182
+ async onTurn(turn) {
183
+ await admitTurn(h, n, turn);
184
+ },
185
+ async onCommand(request) {
186
+ // Follow and every other action are the character's own tool, checked
187
+ // by ghost; no client command reaches a hub place's world.
188
+ request.reject('HUB_NPC_COMMAND_NOT_ALLOWED');
189
+ },
190
+ async onRead(request) {
191
+ await routeRead(h, n, request);
192
+ },
193
+ };
194
+ return api;
195
+ }
196
+
197
+ function handleOf(h, n, npc) {
198
+ return {
199
+ id: npc.id,
200
+ name: npc.name,
201
+ character: npc.character,
202
+ props: npc.props,
203
+ get at() {
204
+ const p = npc.body.translation();
205
+ return { x: p.x, y: p.y, z: p.z };
206
+ },
207
+ get talkingTo() {
208
+ return npc.talking?.playerId ?? null;
209
+ },
210
+ get following() {
211
+ return npc.following;
212
+ },
213
+ get walking() {
214
+ return npc.walk !== null;
215
+ },
216
+ get busy() {
217
+ return npc.talking !== null || npc.walk !== null || npc.following !== null;
218
+ },
219
+ say(text, options = {}) {
220
+ say(h, npc, text, options);
221
+ },
222
+ face(target) {
223
+ npc.faceTo = target ?? null;
224
+ },
225
+ walkTo(at, { stopAt = 0.3, then } = {}) {
226
+ if (!at || !Number.isFinite(at.x) || !Number.isFinite(at.z)) {
227
+ return;
228
+ }
229
+ npc.walk = { x: at.x, z: at.z, stopAt, then: typeof then === 'function' ? then : null };
230
+ },
231
+ home(then) {
232
+ npc.walk = { x: npc.home.x, z: npc.home.z, stopAt: 0.2, then: typeof then === 'function' ? then : null, home: true };
233
+ },
234
+ follow(playerId) {
235
+ npc.following = playerId ?? null;
236
+ npc.followSince = h.sim?.timeMs ?? 0;
237
+ npc.followByToken = false;
238
+ },
239
+ stop() {
240
+ npc.walk = null;
241
+ npc.following = null;
242
+ },
243
+ end() {
244
+ if (npc.talking) {
245
+ endTalk(h, n, npc.id, npc.talking.playerId, 'place');
246
+ }
247
+ },
248
+ };
249
+ }
250
+
251
+ function say(h, npc, text, { to, ttlMs = SPEECH_MS, about } = {}) {
252
+ const line = `${npc.name}: ${String(text ?? '')}`.slice(0, SPEECH_MAX);
253
+ h.npcLabel(npc.id, line, { style: 'speech', ttlMs, to, about });
254
+ }
255
+
256
+ // Whether a block hides these two players from each other.
257
+ function hiddenPair(h, a, b) {
258
+ return Boolean(h.blockedPairs?.()?.get(a)?.has(b));
259
+ }
260
+
261
+ function distanceTo(h, npc, playerId) {
262
+ const player = h.sim?.players.get(playerId);
263
+ if (!player) {
264
+ return Infinity;
265
+ }
266
+ const at = npc.body.translation();
267
+ return Math.hypot(player.at.x - at.x, player.at.z - at.z);
268
+ }
269
+
270
+ // Whether this body's conversations go to its character: the host brokers the
271
+ // place's characters into this session (a layer of the place, or a world the
272
+ // platform placed through the place's route on an older SDK), and the actor
273
+ // names one.
274
+ function hasMind(h, npc) {
275
+ return Boolean(h.place.npcs && npc.character && sessionCharacters(h));
276
+ }
277
+
278
+ // The session's shared characters: `session.characters` on an SDK with place
279
+ // characters (a layer or a world), `session.world.characters` on older ones.
280
+ function sessionCharacters(h) {
281
+ return h.session?.characters ?? h.session?.world?.characters ?? null;
282
+ }
283
+
284
+ function open(h, n, playerId, npcId) {
285
+ const npc = n.bodies.get(npcId);
286
+ if (!npc || distanceTo(h, npc, playerId) > npc.talkRange) {
287
+ h.ctx.send(playerId, { k: 'hub-npc', npc: npcId, open: false, why: 'far' });
288
+ return;
289
+ }
290
+ if (npc.talking && npc.talking.playerId !== playerId) {
291
+ h.ctx.send(playerId, { k: 'hub-npc', npc: npcId, open: false, why: 'busy' });
292
+ line(h, npc, playerId, 'busy');
293
+ return;
294
+ }
295
+ npc.talking = { playerId, at: h.sim.timeMs };
296
+ // A new conversation can ask again for what an earlier one finished.
297
+ const participant = n.participants.get(playerId);
298
+ if (participant) {
299
+ npc.followDone.delete(participant);
300
+ }
301
+ const mind = hasMind(h, npc);
302
+ h.ctx.send(playerId, {
303
+ k: 'hub-npc',
304
+ npc: npcId,
305
+ open: true,
306
+ mind,
307
+ character: mind ? npc.character : null,
308
+ name: npc.name,
309
+ hearRange: HEAR_RANGE_M,
310
+ disclosure: h.place.npcs?.disclosure ?? 'participants',
311
+ });
312
+ npc.notes = null;
313
+ if (!mind) {
314
+ line(h, npc, playerId, 'hello');
315
+ return;
316
+ }
317
+ issueNotes(h, npc, playerId);
318
+ }
319
+
320
+ // The place's notes for the character about this speaker now, framed as the
321
+ // prefix their client sends ahead of their words, or null for none.
322
+ function notesPrefix(h, npc, playerId) {
323
+ let notes = null;
324
+ try {
325
+ notes = h.hooks.npcContext?.(h.ctx, h.ctx.npc(npc.id), playerId) ?? null;
326
+ } catch (err) {
327
+ console.warn(`[hub] npcContext failed: ${err?.stack ?? err}`);
328
+ }
329
+ if (typeof notes !== 'string') {
330
+ return null;
331
+ }
332
+ // The frame's brackets are the kit's alone, so nothing in the notes (a
333
+ // username) can close it early.
334
+ const text = notes.replace(/[[\]]/g, '').trim().slice(0, NOTES_MAX);
335
+ return text ? `${NOTES_HEAD}${text}${NOTES_SAYS}` : null;
336
+ }
337
+
338
+ // Reads the notes for the speaker of a body with a mind and, when they
339
+ // changed (or `force`, after a turn was refused for its notes), sends them to
340
+ // that speaker's client.
341
+ function issueNotes(h, npc, playerId, { force = false } = {}) {
342
+ const now = h.sim.timeMs;
343
+ if (!hasMind(h, npc)) {
344
+ return;
345
+ }
346
+ if (npc.notes?.playerId !== playerId) {
347
+ npc.notes = { playerId, list: [], readAt: -Infinity };
348
+ }
349
+ npc.notes.readAt = now;
350
+ const prefix = notesPrefix(h, npc, playerId);
351
+ const list = npc.notes.list;
352
+ if ((list.at(-1)?.prefix ?? null) === prefix) {
353
+ if (list.length) {
354
+ list.at(-1).at = now;
355
+ }
356
+ if (force) {
357
+ h.ctx.send(playerId, { k: 'hub-npc-notes', npc: npc.id, prefix });
358
+ }
359
+ return;
360
+ }
361
+ list.push({ prefix, at: now });
362
+ while (list.length > NOTES_KEPT) {
363
+ list.shift();
364
+ }
365
+ h.ctx.send(playerId, { k: 'hub-npc-notes', npc: npc.id, prefix });
366
+ }
367
+
368
+ // The player's own words in a turn's input, or null when the input does not
369
+ // start with notes this body issued them (or with none, when the place gave
370
+ // none), or the words try to frame notes of their own. A place without
371
+ // `npcContext` gives no notes, and its turns are the words as they came.
372
+ function wordsOf(h, npc, speaker, input) {
373
+ if (typeof input !== 'string') {
374
+ return null;
375
+ }
376
+ if (typeof h.hooks.npcContext !== 'function') {
377
+ return input;
378
+ }
379
+ const now = h.sim.timeMs;
380
+ const list = npc.notes?.playerId === speaker ? npc.notes.list : [];
381
+ const accepted = list.filter((e, i) => i === list.length - 1 || now - e.at <= NOTES_KEEP_MS);
382
+ // Notes first: an accepted empty entry (the place gave none a moment ago)
383
+ // matches every input, so it is tried last.
384
+ const prefixes = accepted.map((e) => e.prefix).filter((p) => p !== null);
385
+ if (!accepted.length || accepted.some((e) => e.prefix === null)) {
386
+ prefixes.push('');
387
+ }
388
+ const prefix = prefixes.find((p) => input.startsWith(p));
389
+ if (prefix === undefined) {
390
+ return null;
391
+ }
392
+ const words = input.slice(prefix.length);
393
+ if (words.includes(NOTES_HEAD.trim()) || words.includes(NOTES_SAYS.trim())) {
394
+ return null;
395
+ }
396
+ return words;
397
+ }
398
+
399
+ function endTalk(h, n, npcId, playerId, why) {
400
+ const npc = n.bodies.get(npcId);
401
+ if (!npc || npc.talking?.playerId !== playerId) {
402
+ return;
403
+ }
404
+ npc.talking = null;
405
+ h.ctx.send(playerId, { k: 'hub-npc', npc: npcId, open: false, why });
406
+ }
407
+
408
+ // The place's authored words for this moment (`npcLine`), or the kit's.
409
+ function line(h, npc, playerId, why, text) {
410
+ let said = null;
411
+ try {
412
+ said = h.hooks.npcLine?.(h.ctx, h.ctx.npc(npc.id), playerId, { why, text: text ?? null }) ?? null;
413
+ } catch (err) {
414
+ console.warn(`[hub] npcLine failed: ${err?.stack ?? err}`);
415
+ }
416
+ if (said === null || said === undefined) {
417
+ said = DEFAULT_LINES[why]?.(npc.name, h.ctx.username(playerId)) ?? null;
418
+ }
419
+ if (said) {
420
+ // The line may name the player (the kit's hello does): nobody a block
421
+ // hides them from is ever sent it, a player who arrives later included.
422
+ say(h, npc, said, { about: playerId });
423
+ // `why` lets the speaker's panel say an answer was scripted, not the mind's.
424
+ h.ctx.send(playerId, { k: 'hub-npc-line', npc: npc.id, text: String(said).slice(0, SPEECH_MAX), why });
425
+ }
426
+ }
427
+
428
+ const DEFAULT_LINES = {
429
+ hello: (name, who) => `Hello, ${who}.`,
430
+ busy: (name) => `${name} is talking with someone else.`,
431
+ budget: (name) => `${name} has a crowd to answer. Try again in a moment.`,
432
+ unavailable: (name) => `${name} doesn't catch that. Try again in a moment.`,
433
+ };
434
+
435
+ // Words to a body with no mind here (the dev serve, a session the host brokers
436
+ // no characters into): the place answers from its authored lines.
437
+ function authoredSay(h, n, playerId, npcId, text) {
438
+ const npc = n.bodies.get(npcId);
439
+ if (!npc || npc.talking?.playerId !== playerId || typeof text !== 'string') {
440
+ return;
441
+ }
442
+ const now = h.sim.timeMs;
443
+ if (now - (n.saidAt.get(playerId) ?? -Infinity) < SAY_GAP_MS || hasMind(h, npc)) {
444
+ return;
445
+ }
446
+ n.saidAt.set(playerId, now);
447
+ npc.talking.at = now;
448
+ line(h, npc, playerId, 'authored', text.slice(0, INPUT_MAX));
449
+ }
450
+
451
+ // A turn the host granted: the kit admits it only for the player this body is
452
+ // talking to, standing near it, with listeners who are near it too, inside the
453
+ // character's budget. Anything else is refused before a model is called.
454
+ async function admitTurn(h, n, turn) {
455
+ const speaker = turn.speaker.playerId;
456
+ // Several bodies may share one character (the town's barkers): the one this
457
+ // speaker is talking to.
458
+ const bodies = [...n.bodies.values()].filter((b) => b.character === turn.characterId);
459
+ const npc = bodies.find((b) => b.talking?.playerId === speaker) ?? bodies[0];
460
+ const npcs = h.place.npcs;
461
+ if (!npc || !npcs || !hasMind(h, npc)) {
462
+ turn.reject('HUB_NPC_UNKNOWN');
463
+ return;
464
+ }
465
+ if (npc.talking?.playerId !== speaker || distanceTo(h, npc, speaker) > npc.talkRange + 1) {
466
+ turn.reject('HUB_NPC_NOT_TALKING');
467
+ return;
468
+ }
469
+ const audience = turn.audience;
470
+ if (
471
+ audience.disclosure !== npcs.disclosure ||
472
+ audience.characterIds.length ||
473
+ audience.players.length > LISTENERS_MAX ||
474
+ audience.players.some((p) => distanceTo(h, npc, p.playerId) > HEAR_RANGE_M) ||
475
+ // A listener a block hides from the speaker never hears their conversation.
476
+ audience.players.some((p) => hiddenPair(h, speaker, p.playerId))
477
+ ) {
478
+ turn.reject('HUB_NPC_AUDIENCE');
479
+ return;
480
+ }
481
+ // The same operation again (a client retrying after a lost receipt) is the
482
+ // turn already admitted: ghost replays it, so it neither waits behind
483
+ // itself nor spends the budget twice.
484
+ const key = `${speaker}:${turn.operationId}`;
485
+ const existing = n.turns.get(key) ?? (npc.pending?.key === key ? npc.pending : null);
486
+ // A replay was checked when it was first admitted; its notes may be gone.
487
+ const words = existing ? null : wordsOf(h, npc, speaker, turn.input);
488
+ if (!existing && words === null) {
489
+ turn.reject('HUB_NPC_NOTES');
490
+ // The client may have missed the newest: send them again for its retry.
491
+ issueNotes(h, npc, speaker, { force: true });
492
+ return;
493
+ }
494
+ if (!existing) {
495
+ if (npc.pending && !npc.pending.delivered && h.sim.timeMs - npc.pending.at < PENDING_MS) {
496
+ turn.reject('HUB_NPC_BUSY');
497
+ return;
498
+ }
499
+ const now = Date.now();
500
+ npc.recent = npc.recent.filter((at) => now - at < 60_000);
501
+ if (npc.recent.length >= npcs.turnsPerMinute) {
502
+ turn.reject('HUB_NPC_BUDGET');
503
+ line(h, npc, speaker, 'budget');
504
+ return;
505
+ }
506
+ npc.recent.push(now);
507
+ }
508
+ npc.talking.at = h.sim.timeMs;
509
+ const record = existing ?? {
510
+ key,
511
+ npc: npc.id,
512
+ speaker,
513
+ recipients: new Set([speaker, ...audience.players.map((p) => p.playerId)]),
514
+ at: h.sim.timeMs,
515
+ delivered: false,
516
+ };
517
+ // Only a new turn takes the body; a replay leaves whatever holds it.
518
+ if (!existing) {
519
+ npc.pending = record;
520
+ }
521
+ try {
522
+ await turn.send();
523
+ } catch (err) {
524
+ if (npc.pending === record && !existing) {
525
+ npc.pending = null;
526
+ }
527
+ // Ghost's place-mind queue for this character is full (one running, ten
528
+ // waiting town-wide): the place's busy line, not its unavailable one.
529
+ // Ghost's town-wide budget for this character is spent this minute: the
530
+ // place's budget line, as for its own per-character budget.
531
+ const why =
532
+ err?.code === 'CAULDRON_SHARED_CHARACTER_BUSY'
533
+ ? 'busy'
534
+ : err?.code === 'CAULDRON_SHARED_CHARACTER_BUDGET'
535
+ ? 'budget'
536
+ : 'unavailable';
537
+ line(h, npc, speaker, why);
538
+ throw err;
539
+ }
540
+ // A replayed admission keeps the first record, so a reply is shown once.
541
+ if (!existing) {
542
+ n.turns.set(key, record);
543
+ trimTurns(h, n);
544
+ // What the speaker said, for the place (a quest-giver asked for another).
545
+ try {
546
+ h.hooks.npcHeard?.(h.ctx, h.ctx.npc(npc.id), speaker, { text: words });
547
+ } catch (err) {
548
+ console.warn(`[hub] npcHeard failed: ${err?.stack ?? err}`);
549
+ }
550
+ }
551
+ }
552
+
553
+ function trimTurns(h, n) {
554
+ const now = h.sim?.timeMs ?? 0;
555
+ for (const [key, turn] of n.turns) {
556
+ if (n.turns.size <= TURNS_KEPT && now - turn.at < TURN_KEEP_MS) {
557
+ break;
558
+ }
559
+ n.turns.delete(key);
560
+ }
561
+ }
562
+
563
+ // A player's own read. A status read that carries their turn's finished reply
564
+ // is when its admitted audience sees it over the body: the reply is ghost's
565
+ // canonical text, never a client's message.
566
+ async function routeRead(h, n, request) {
567
+ const type = request.query?.type;
568
+ if (type !== 'inspect' && type !== 'status' && type !== 'history') {
569
+ request.reject('HUB_NPC_READ_NOT_ALLOWED');
570
+ return;
571
+ }
572
+ const result = await request.read();
573
+ const speaker = request.speaker.playerId;
574
+ if (type === 'inspect' && typeof result?.participantId === 'string') {
575
+ n.participants.set(speaker, result.participantId);
576
+ return;
577
+ }
578
+ if (type !== 'status') {
579
+ return;
580
+ }
581
+ const turn = n.turns.get(`${speaker}:${request.query.operationId}`);
582
+ const done = result?.status === 'completed' || result?.status === 'interrupted';
583
+ if (!turn || turn.delivered || !done) {
584
+ return;
585
+ }
586
+ // Finished, with words or without (an interrupted turn may have none):
587
+ // either way the body is free for its next turn.
588
+ turn.delivered = true;
589
+ const npc = n.bodies.get(turn.npc);
590
+ if (!npc) {
591
+ return;
592
+ }
593
+ if (npc.pending === turn) {
594
+ npc.pending = null;
595
+ }
596
+ if (typeof result.response === 'string' && result.response.trim()) {
597
+ // Checked again: a block may have come between them since the turn.
598
+ const to = [...turn.recipients].filter(
599
+ (playerId) => h.sim?.players.has(playerId) && !hiddenPair(h, turn.speaker, playerId),
600
+ );
601
+ say(h, npc, unquote(result.response), { to, about: turn.speaker });
602
+ }
603
+ // The reply may have come with the character's follow action.
604
+ n.watchUntil = h.sim.timeMs + FOLLOW_WATCH_MS;
605
+ n.polledAt = -Infinity;
606
+ }
607
+
608
+ // Who each body's follow token is held by, from the world's public
609
+ // projection, mapped to a player here through their own inspect read.
610
+ function pollFollow(h, n) {
611
+ const world = sessionCharacters(h);
612
+ const now = h.sim?.timeMs ?? 0;
613
+ const following = [...n.bodies.values()].some((npc) => npc.following && npc.followByToken);
614
+ const gap = Math.min(FOLLOW_POLL_MS * 2 ** n.inspectFailures, 60_000);
615
+ if (!world || n.polling || (now > n.watchUntil && !following) || now - n.polledAt < gap) {
616
+ return;
617
+ }
618
+ if (![...n.bodies.values()].some((npc) => npc.followObject)) {
619
+ return;
620
+ }
621
+ n.polling = true;
622
+ n.polledAt = now;
623
+ world
624
+ .publicInspect()
625
+ .then((view) => {
626
+ n.inspectFailures = 0;
627
+ applyFollow(h, n, view);
628
+ })
629
+ .catch((err) => {
630
+ // Backed off, not given up: a transient failure must not stop a later
631
+ // follow from being seen.
632
+ n.inspectFailures = Math.min(n.inspectFailures + 1, 5);
633
+ console.warn(`[hub] NPC follow could not read the world's public projection: ${err?.message ?? err}`);
634
+ })
635
+ .finally(() => {
636
+ n.polling = false;
637
+ });
638
+ }
639
+
640
+ function applyFollow(h, n, view) {
641
+ const objects = view?.gameplay?.objects ?? {};
642
+ for (const npc of n.bodies.values()) {
643
+ if (!npc.followObject) {
644
+ continue;
645
+ }
646
+ const holder = objects[npc.followObject]?.holderId ?? null;
647
+ const playerId = holder ? [...n.participants].find(([, p]) => p === holder)?.[0] ?? null : null;
648
+ if (playerId && !npc.followDone.has(holder) && h.sim.players.has(playerId)) {
649
+ if (npc.following !== playerId) {
650
+ npc.following = playerId;
651
+ npc.followSince = h.sim.timeMs;
652
+ npc.followByToken = true;
653
+ }
654
+ } else if (npc.following && npc.followByToken && !playerId) {
655
+ npc.following = null;
656
+ }
657
+ }
658
+ }
659
+
660
+ // One body's tick: a conversation holds it facing its speaker; otherwise it
661
+ // walks where the place sent it, or follows, or faces what it was told to.
662
+ function moveBody(h, n, npc, dt) {
663
+ const now = h.sim.timeMs;
664
+ if (npc.talking) {
665
+ const gone = !h.sim.players.has(npc.talking.playerId);
666
+ const idle = now - npc.talking.at > IDLE_END_MS;
667
+ const far = distanceTo(h, npc, npc.talking.playerId) > HEAR_RANGE_M + 2;
668
+ if (gone || idle || far) {
669
+ endTalk(h, n, npc.id, npc.talking.playerId, gone ? 'left' : idle ? 'idle' : 'far');
670
+ }
671
+ }
672
+ const followLimit = (h.place.npcs?.followSec ?? 120) * 1000;
673
+ if (npc.following && (!h.sim.players.has(npc.following) || now - npc.followSince > followLimit)) {
674
+ const participant = n.participants.get(npc.following);
675
+ if (participant) {
676
+ npc.followDone.add(participant);
677
+ }
678
+ npc.following = null;
679
+ npc.walk ??= { x: npc.home.x, z: npc.home.z, stopAt: 0.2, then: null, home: true };
680
+ }
681
+
682
+ let next = null;
683
+ if (npc.talking) {
684
+ faceToward(npc, h.sim.players.get(npc.talking.playerId)?.at);
685
+ } else if (npc.walk) {
686
+ const w = npc.walk;
687
+ const step = stepToward(npc, w.x, w.z, w.stopAt, dt);
688
+ next = step.next;
689
+ if (step.arrived) {
690
+ npc.walk = null;
691
+ if (w.home) {
692
+ npc.yaw = npc.home.yaw;
693
+ }
694
+ try {
695
+ w.then?.();
696
+ } catch (err) {
697
+ console.warn(`[hub] an NPC walk's then failed: ${err?.stack ?? err}`);
698
+ }
699
+ }
700
+ } else if (npc.following) {
701
+ const at = h.sim.players.get(npc.following)?.at;
702
+ if (at) {
703
+ next = stepToward(npc, at.x, at.z, FOLLOW_GAP_M, dt).next;
704
+ }
705
+ } else if (npc.faceTo) {
706
+ const target = typeof npc.faceTo === 'string' ? h.sim.players.get(npc.faceTo)?.at : npc.faceTo;
707
+ faceToward(npc, target);
708
+ }
709
+ if (next) {
710
+ npc.body.setNextKinematicTranslation(next);
711
+ }
712
+ npc.body.setNextKinematicRotation({ x: 0, y: Math.sin(npc.yaw / 2), z: 0, w: Math.cos(npc.yaw / 2) });
713
+ }
714
+
715
+ function faceToward(npc, at) {
716
+ if (!at) {
717
+ return;
718
+ }
719
+ const p = npc.body.translation();
720
+ if (Math.hypot(at.x - p.x, at.z - p.z) > 0.05) {
721
+ npc.yaw = Math.atan2(at.x - p.x, at.z - p.z);
722
+ }
723
+ }
724
+
725
+ // Straight-line walking, no navigation: a place puts its NPCs where a straight
726
+ // walk does not cross anything solid.
727
+ function stepToward(npc, x, z, stopAt, dt) {
728
+ const p = npc.body.translation();
729
+ const dx = x - p.x;
730
+ const dz = z - p.z;
731
+ const d = Math.hypot(dx, dz);
732
+ if (d <= stopAt + 1e-3) {
733
+ return { arrived: true, next: null };
734
+ }
735
+ npc.yaw = Math.atan2(dx, dz);
736
+ const stride = Math.min(d - stopAt, WALK_MPS * dt);
737
+ return { arrived: false, next: { x: p.x + (dx / d) * stride, y: p.y, z: p.z + (dz / d) * stride } };
738
+ }
739
+
740
+ // A model sometimes wraps its whole line in quotes; a speech bubble is quotes
741
+ // enough.
742
+ function unquote(text) {
743
+ const t = text.trim();
744
+ return t.length > 1 && /^["“]/.test(t) && /["”]$/.test(t) ? t.slice(1, -1).trim() : t;
745
+ }