castle-web-cli 0.4.229 → 0.4.231

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