@pretty-chitty/core 2.0.0 → 2.1.0

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 (318) hide show
  1. package/README.md +8 -0
  2. package/dist/components/ActionLogDisplay.d.ts.map +1 -1
  3. package/dist/components/ActionLogDisplay.js +1 -1
  4. package/dist/components/ActionLogDisplay.js.map +1 -1
  5. package/dist/components/BottomBarButton.d.ts +3 -1
  6. package/dist/components/BottomBarButton.d.ts.map +1 -1
  7. package/dist/components/BottomBarButton.js +3 -2
  8. package/dist/components/BottomBarButton.js.map +1 -1
  9. package/dist/components/ContextGalleryDisplay.d.ts.map +1 -1
  10. package/dist/components/ContextGalleryDisplay.js +1 -1
  11. package/dist/components/ContextGalleryDisplay.js.map +1 -1
  12. package/dist/components/DemoWrapper.d.ts +30 -2
  13. package/dist/components/DemoWrapper.d.ts.map +1 -1
  14. package/dist/components/DemoWrapper.js +79 -36
  15. package/dist/components/DemoWrapper.js.map +1 -1
  16. package/dist/components/FullScreenGalleryDisplay.d.ts.map +1 -1
  17. package/dist/components/FullScreenGalleryDisplay.js +2 -2
  18. package/dist/components/FullScreenGalleryDisplay.js.map +1 -1
  19. package/dist/components/Gallery/BuiltItem.d.ts +6 -2
  20. package/dist/components/Gallery/BuiltItem.d.ts.map +1 -1
  21. package/dist/components/Gallery/BuiltItem.js +28 -9
  22. package/dist/components/Gallery/BuiltItem.js.map +1 -1
  23. package/dist/components/Gallery/GalleryController.d.ts +18 -0
  24. package/dist/components/Gallery/GalleryController.d.ts.map +1 -1
  25. package/dist/components/Gallery/GalleryController.js +67 -0
  26. package/dist/components/Gallery/GalleryController.js.map +1 -1
  27. package/dist/components/Gallery/GalleryViewer.d.ts +6 -1
  28. package/dist/components/Gallery/GalleryViewer.d.ts.map +1 -1
  29. package/dist/components/Gallery/GalleryViewer.js +48 -10
  30. package/dist/components/Gallery/GalleryViewer.js.map +1 -1
  31. package/dist/components/Gallery/LayoutManager.d.ts +6 -0
  32. package/dist/components/Gallery/LayoutManager.d.ts.map +1 -1
  33. package/dist/components/Gallery/LayoutManager.js +23 -3
  34. package/dist/components/Gallery/LayoutManager.js.map +1 -1
  35. package/dist/components/Gallery/constants.d.ts +2 -0
  36. package/dist/components/Gallery/constants.d.ts.map +1 -1
  37. package/dist/components/Gallery/constants.js +2 -0
  38. package/dist/components/Gallery/constants.js.map +1 -1
  39. package/dist/components/Gallery/registry.d.ts +34 -0
  40. package/dist/components/Gallery/registry.d.ts.map +1 -0
  41. package/dist/components/Gallery/registry.js +17 -0
  42. package/dist/components/Gallery/registry.js.map +1 -0
  43. package/dist/components/GameDesigner.d.ts.map +1 -1
  44. package/dist/components/GameDesigner.js +42 -10
  45. package/dist/components/GameDesigner.js.map +1 -1
  46. package/dist/components/InlineGalleryDisplay.d.ts.map +1 -1
  47. package/dist/components/InlineGalleryDisplay.js +2 -2
  48. package/dist/components/InlineGalleryDisplay.js.map +1 -1
  49. package/dist/components/LiveButton.d.ts.map +1 -1
  50. package/dist/components/LiveButton.js +5 -2
  51. package/dist/components/LiveButton.js.map +1 -1
  52. package/dist/components/MatchViewer.d.ts +6 -1
  53. package/dist/components/MatchViewer.d.ts.map +1 -1
  54. package/dist/components/MatchViewer.js +9 -3
  55. package/dist/components/MatchViewer.js.map +1 -1
  56. package/dist/components/Panel/MultiPanel.d.ts.map +1 -1
  57. package/dist/components/Panel/MultiPanel.js +18 -0
  58. package/dist/components/Panel/MultiPanel.js.map +1 -1
  59. package/dist/components/Panel/PanelContents.d.ts.map +1 -1
  60. package/dist/components/Panel/PanelContents.js +92 -23
  61. package/dist/components/Panel/PanelContents.js.map +1 -1
  62. package/dist/components/Panel/PanelTabStack.d.ts.map +1 -1
  63. package/dist/components/Panel/PanelTabStack.js +1 -1
  64. package/dist/components/Panel/PanelTabStack.js.map +1 -1
  65. package/dist/components/PanelSpark.d.ts.map +1 -1
  66. package/dist/components/PanelSpark.js +3 -2
  67. package/dist/components/PanelSpark.js.map +1 -1
  68. package/dist/components/Playground.d.ts.map +1 -1
  69. package/dist/components/Playground.js +10 -4
  70. package/dist/components/Playground.js.map +1 -1
  71. package/dist/components/PromptControls.d.ts.map +1 -1
  72. package/dist/components/PromptControls.js +4 -2
  73. package/dist/components/PromptControls.js.map +1 -1
  74. package/dist/components/SparkLineChart.d.ts.map +1 -1
  75. package/dist/components/SparkLineChart.js +22 -26
  76. package/dist/components/SparkLineChart.js.map +1 -1
  77. package/dist/components/TimeControlBar.d.ts.map +1 -1
  78. package/dist/components/TimeControlBar.js +5 -3
  79. package/dist/components/TimeControlBar.js.map +1 -1
  80. package/dist/components/TokenizedMarkdown.d.ts +23 -0
  81. package/dist/components/TokenizedMarkdown.d.ts.map +1 -0
  82. package/dist/components/TokenizedMarkdown.js +144 -0
  83. package/dist/components/TokenizedMarkdown.js.map +1 -0
  84. package/dist/components/TokenizedMessage.d.ts +6 -0
  85. package/dist/components/TokenizedMessage.d.ts.map +1 -1
  86. package/dist/components/TokenizedMessage.js +20 -19
  87. package/dist/components/TokenizedMessage.js.map +1 -1
  88. package/dist/components/TopBarPlayers.d.ts.map +1 -1
  89. package/dist/components/TopBarPlayers.js +1 -1
  90. package/dist/components/TopBarPlayers.js.map +1 -1
  91. package/dist/components/Tutorial/BrowserNarration.d.ts +55 -0
  92. package/dist/components/Tutorial/BrowserNarration.d.ts.map +1 -0
  93. package/dist/components/Tutorial/BrowserNarration.js +240 -0
  94. package/dist/components/Tutorial/BrowserNarration.js.map +1 -0
  95. package/dist/components/Tutorial/TutorialBox.d.ts +26 -0
  96. package/dist/components/Tutorial/TutorialBox.d.ts.map +1 -0
  97. package/dist/components/Tutorial/TutorialBox.js +239 -0
  98. package/dist/components/Tutorial/TutorialBox.js.map +1 -0
  99. package/dist/components/Tutorial/TutorialDevPanel.d.ts +9 -0
  100. package/dist/components/Tutorial/TutorialDevPanel.d.ts.map +1 -0
  101. package/dist/components/Tutorial/TutorialDevPanel.js +92 -0
  102. package/dist/components/Tutorial/TutorialDevPanel.js.map +1 -0
  103. package/dist/components/Tutorial/TutorialOverlay.d.ts +7 -0
  104. package/dist/components/Tutorial/TutorialOverlay.d.ts.map +1 -0
  105. package/dist/components/Tutorial/TutorialOverlay.js +1132 -0
  106. package/dist/components/Tutorial/TutorialOverlay.js.map +1 -0
  107. package/dist/components/Tutorial/targetRects.d.ts +67 -0
  108. package/dist/components/Tutorial/targetRects.d.ts.map +1 -0
  109. package/dist/components/Tutorial/targetRects.js +241 -0
  110. package/dist/components/Tutorial/targetRects.js.map +1 -0
  111. package/dist/game/Chit.d.ts +7 -0
  112. package/dist/game/Chit.d.ts.map +1 -1
  113. package/dist/game/Chit.js +20 -5
  114. package/dist/game/Chit.js.map +1 -1
  115. package/dist/game/ClientTimeState.d.ts +14 -0
  116. package/dist/game/ClientTimeState.d.ts.map +1 -1
  117. package/dist/game/ClientTimeState.js +17 -0
  118. package/dist/game/ClientTimeState.js.map +1 -1
  119. package/dist/game/Game.d.ts +6 -0
  120. package/dist/game/Game.d.ts.map +1 -1
  121. package/dist/game/GameTheme.d.ts +3 -0
  122. package/dist/game/GameTheme.d.ts.map +1 -1
  123. package/dist/game/GameTheme.js +2 -0
  124. package/dist/game/GameTheme.js.map +1 -1
  125. package/dist/game/Match.d.ts +8 -2
  126. package/dist/game/Match.d.ts.map +1 -1
  127. package/dist/game/Match.js +4 -1
  128. package/dist/game/Match.js.map +1 -1
  129. package/dist/game/Pick.d.ts +2 -0
  130. package/dist/game/Pick.d.ts.map +1 -1
  131. package/dist/game/Pick.js +17 -1
  132. package/dist/game/Pick.js.map +1 -1
  133. package/dist/game/PlayerPromptStatusChit.d.ts +8 -0
  134. package/dist/game/PlayerPromptStatusChit.d.ts.map +1 -1
  135. package/dist/game/PlayerPromptStatusChit.js +5 -1
  136. package/dist/game/PlayerPromptStatusChit.js.map +1 -1
  137. package/dist/game/Prompt.d.ts +15 -0
  138. package/dist/game/Prompt.d.ts.map +1 -1
  139. package/dist/game/Prompt.js +16 -0
  140. package/dist/game/Prompt.js.map +1 -1
  141. package/dist/game/Turn.d.ts +15 -4
  142. package/dist/game/Turn.d.ts.map +1 -1
  143. package/dist/game/Turn.js +173 -60
  144. package/dist/game/Turn.js.map +1 -1
  145. package/dist/game/TurnState.d.ts +12 -1
  146. package/dist/game/TurnState.d.ts.map +1 -1
  147. package/dist/game/TurnState.js +15 -3
  148. package/dist/game/TurnState.js.map +1 -1
  149. package/dist/game/ai/AiClientPrompts.d.ts +20 -3
  150. package/dist/game/ai/AiClientPrompts.d.ts.map +1 -1
  151. package/dist/game/ai/AiClientPrompts.js +42 -6
  152. package/dist/game/ai/AiClientPrompts.js.map +1 -1
  153. package/dist/game/ai/AiPlayerView.js +2 -0
  154. package/dist/game/ai/AiPlayerView.js.map +1 -1
  155. package/dist/game/clientTransport/ClientPrompts.d.ts +20 -1
  156. package/dist/game/clientTransport/ClientPrompts.d.ts.map +1 -1
  157. package/dist/game/clientTransport/ClientPrompts.js +30 -1
  158. package/dist/game/clientTransport/ClientPrompts.js.map +1 -1
  159. package/dist/game/clientTransport/ClientTime.d.ts +13 -0
  160. package/dist/game/clientTransport/ClientTime.d.ts.map +1 -1
  161. package/dist/game/clientTransport/ClientTime.js +51 -11
  162. package/dist/game/clientTransport/ClientTime.js.map +1 -1
  163. package/dist/game/tutorial/TutorialController.d.ts +300 -0
  164. package/dist/game/tutorial/TutorialController.d.ts.map +1 -0
  165. package/dist/game/tutorial/TutorialController.js +1182 -0
  166. package/dist/game/tutorial/TutorialController.js.map +1 -0
  167. package/dist/game/tutorial/TutorialRuntime.d.ts +89 -0
  168. package/dist/game/tutorial/TutorialRuntime.d.ts.map +1 -0
  169. package/dist/game/tutorial/TutorialRuntime.js +261 -0
  170. package/dist/game/tutorial/TutorialRuntime.js.map +1 -0
  171. package/dist/game/tutorial/TutorialTheme.d.ts +28 -0
  172. package/dist/game/tutorial/TutorialTheme.d.ts.map +1 -0
  173. package/dist/game/tutorial/TutorialTheme.js +39 -0
  174. package/dist/game/tutorial/TutorialTheme.js.map +1 -0
  175. package/dist/game/tutorial/allowed.d.ts +2 -0
  176. package/dist/game/tutorial/allowed.d.ts.map +1 -0
  177. package/dist/game/tutorial/allowed.js +119 -0
  178. package/dist/game/tutorial/allowed.js.map +1 -0
  179. package/dist/game/tutorial/checks.d.ts +58 -0
  180. package/dist/game/tutorial/checks.d.ts.map +1 -0
  181. package/dist/game/tutorial/checks.js +144 -0
  182. package/dist/game/tutorial/checks.js.map +1 -0
  183. package/dist/game/tutorial/createDemoMatch.d.ts +47 -0
  184. package/dist/game/tutorial/createDemoMatch.d.ts.map +1 -0
  185. package/dist/game/tutorial/createDemoMatch.js +67 -0
  186. package/dist/game/tutorial/createDemoMatch.js.map +1 -0
  187. package/dist/game/tutorial/defineTutorial.d.ts +353 -0
  188. package/dist/game/tutorial/defineTutorial.d.ts.map +1 -0
  189. package/dist/game/tutorial/defineTutorial.js +86 -0
  190. package/dist/game/tutorial/defineTutorial.js.map +1 -0
  191. package/dist/game/tutorial/runTutorial.d.ts +63 -0
  192. package/dist/game/tutorial/runTutorial.d.ts.map +1 -0
  193. package/dist/game/tutorial/runTutorial.js +273 -0
  194. package/dist/game/tutorial/runTutorial.js.map +1 -0
  195. package/dist/hooks/usePanelNavigation.d.ts +28 -0
  196. package/dist/hooks/usePanelNavigation.d.ts.map +1 -0
  197. package/dist/hooks/usePanelNavigation.js +36 -0
  198. package/dist/hooks/usePanelNavigation.js.map +1 -0
  199. package/dist/hooks/useTimeController.d.ts +2 -1
  200. package/dist/hooks/useTimeController.d.ts.map +1 -1
  201. package/dist/hooks/useTimeController.js +6 -2
  202. package/dist/hooks/useTimeController.js.map +1 -1
  203. package/dist/hooks/useTutorial.d.ts +48 -0
  204. package/dist/hooks/useTutorial.d.ts.map +1 -0
  205. package/dist/hooks/useTutorial.js +16 -0
  206. package/dist/hooks/useTutorial.js.map +1 -0
  207. package/dist/index.d.ts +36 -0
  208. package/dist/index.d.ts.map +1 -1
  209. package/dist/index.html +12 -0
  210. package/dist/index.js +19 -2
  211. package/dist/index.js.map +1 -1
  212. package/dist/main.0792d734cde2c688d5f7.hot-update.js +16991 -0
  213. package/dist/main.0792d734cde2c688d5f7.hot-update.js.map +1 -0
  214. package/dist/main.0792d734cde2c688d5f7.hot-update.json +1 -0
  215. package/dist/pretty-chitty.js +204513 -0
  216. package/dist/pretty-chitty.js.map +1 -0
  217. package/dist/rendering/CameraWrapperPerspective.d.ts +5 -0
  218. package/dist/rendering/CameraWrapperPerspective.d.ts.map +1 -1
  219. package/dist/rendering/CameraWrapperPerspective.js +16 -0
  220. package/dist/rendering/CameraWrapperPerspective.js.map +1 -1
  221. package/dist/rendering/ChitGalleryItemInstance.d.ts +1 -0
  222. package/dist/rendering/ChitGalleryItemInstance.d.ts.map +1 -1
  223. package/dist/rendering/ChitGalleryItemInstance.js +12 -0
  224. package/dist/rendering/ChitGalleryItemInstance.js.map +1 -1
  225. package/dist/rendering/ChitRenderInstance.d.ts +9 -1
  226. package/dist/rendering/ChitRenderInstance.d.ts.map +1 -1
  227. package/dist/rendering/ChitRenderInstance.js +28 -0
  228. package/dist/rendering/ChitRenderInstance.js.map +1 -1
  229. package/dist/rendering/RootChitRenderInstance.d.ts +2 -0
  230. package/dist/rendering/RootChitRenderInstance.d.ts.map +1 -1
  231. package/dist/rendering/RootChitRenderInstance.js +29 -0
  232. package/dist/rendering/RootChitRenderInstance.js.map +1 -1
  233. package/dist/utilities/Annotations.d.ts +15 -0
  234. package/dist/utilities/Annotations.d.ts.map +1 -1
  235. package/dist/utilities/Annotations.js +31 -7
  236. package/dist/utilities/Annotations.js.map +1 -1
  237. package/dist/utilities/CanvasStack/CanvasStack.d.ts +2 -0
  238. package/dist/utilities/CanvasStack/CanvasStack.d.ts.map +1 -1
  239. package/dist/utilities/CanvasStack/CanvasStack.js +4 -0
  240. package/dist/utilities/CanvasStack/CanvasStack.js.map +1 -1
  241. package/dist/utilities/TokenizedText.d.ts +6 -0
  242. package/dist/utilities/TokenizedText.d.ts.map +1 -1
  243. package/dist/utilities/TokenizedText.js.map +1 -1
  244. package/dist/utilities/zIndex.d.ts +1 -0
  245. package/dist/utilities/zIndex.d.ts.map +1 -1
  246. package/dist/utilities/zIndex.js +1 -0
  247. package/dist/utilities/zIndex.js.map +1 -1
  248. package/package.json +3 -2
  249. package/src/library/components/ActionLogDisplay.tsx +1 -0
  250. package/src/library/components/BottomBarButton.tsx +5 -0
  251. package/src/library/components/ContextGalleryDisplay.tsx +2 -0
  252. package/src/library/components/DemoWrapper.tsx +147 -44
  253. package/src/library/components/FullScreenGalleryDisplay.tsx +3 -0
  254. package/src/library/components/Gallery/BuiltItem.ts +30 -9
  255. package/src/library/components/Gallery/GalleryController.ts +72 -1
  256. package/src/library/components/Gallery/GalleryViewer.tsx +54 -10
  257. package/src/library/components/Gallery/LayoutManager.ts +30 -6
  258. package/src/library/components/Gallery/constants.ts +2 -0
  259. package/src/library/components/Gallery/registry.ts +44 -0
  260. package/src/library/components/GameDesigner.tsx +121 -12
  261. package/src/library/components/InlineGalleryDisplay.tsx +5 -0
  262. package/src/library/components/LiveButton.tsx +8 -5
  263. package/src/library/components/MatchViewer.tsx +14 -3
  264. package/src/library/components/Panel/MultiPanel.tsx +21 -0
  265. package/src/library/components/Panel/PanelContents.tsx +70 -1
  266. package/src/library/components/Panel/PanelTabStack.tsx +1 -0
  267. package/src/library/components/PanelSpark.tsx +9 -4
  268. package/src/library/components/Playground.tsx +48 -21
  269. package/src/library/components/PromptControls.tsx +7 -3
  270. package/src/library/components/SparkLineChart.tsx +23 -27
  271. package/src/library/components/TimeControlBar.tsx +5 -3
  272. package/src/library/components/TokenizedMarkdown.tsx +224 -0
  273. package/src/library/components/TokenizedMessage.tsx +28 -32
  274. package/src/library/components/TopBarPlayers.tsx +12 -9
  275. package/src/library/components/Tutorial/BrowserNarration.ts +233 -0
  276. package/src/library/components/Tutorial/TutorialBox.tsx +506 -0
  277. package/src/library/components/Tutorial/TutorialDevPanel.tsx +297 -0
  278. package/src/library/components/Tutorial/TutorialOverlay.tsx +1301 -0
  279. package/src/library/components/Tutorial/targetRects.ts +273 -0
  280. package/src/library/game/Chit.ts +21 -5
  281. package/src/library/game/ClientTimeState.ts +18 -0
  282. package/src/library/game/Game.ts +7 -0
  283. package/src/library/game/GameTheme.ts +4 -0
  284. package/src/library/game/Match.ts +12 -2
  285. package/src/library/game/Pick.ts +16 -1
  286. package/src/library/game/PlayerPromptStatusChit.ts +5 -1
  287. package/src/library/game/Prompt.ts +20 -0
  288. package/src/library/game/Turn.ts +179 -61
  289. package/src/library/game/TurnState.ts +26 -3
  290. package/src/library/game/ai/AI_GUIDE.md +10 -0
  291. package/src/library/game/ai/AiClientPrompts.ts +60 -11
  292. package/src/library/game/ai/AiPlayerView.ts +2 -0
  293. package/src/library/game/clientTransport/ClientPrompts.ts +31 -1
  294. package/src/library/game/clientTransport/ClientTime.ts +54 -13
  295. package/src/library/game/serialize.test.ts +275 -0
  296. package/src/library/game/tutorial/TUTORIAL_GUIDE.md +411 -0
  297. package/src/library/game/tutorial/TutorialController.test.ts +731 -0
  298. package/src/library/game/tutorial/TutorialController.ts +1286 -0
  299. package/src/library/game/tutorial/TutorialRuntime.ts +311 -0
  300. package/src/library/game/tutorial/TutorialTheme.ts +67 -0
  301. package/src/library/game/tutorial/allowed.ts +145 -0
  302. package/src/library/game/tutorial/checks.ts +186 -0
  303. package/src/library/game/tutorial/createDemoMatch.ts +115 -0
  304. package/src/library/game/tutorial/defineTutorial.ts +414 -0
  305. package/src/library/game/tutorial/runTutorial.ts +331 -0
  306. package/src/library/game/undo.test.ts +282 -0
  307. package/src/library/hooks/usePanelNavigation.tsx +65 -0
  308. package/src/library/hooks/useTimeController.tsx +6 -2
  309. package/src/library/hooks/useTutorial.tsx +76 -0
  310. package/src/library/index.ts +57 -2
  311. package/src/library/rendering/CameraWrapperPerspective.ts +17 -0
  312. package/src/library/rendering/ChitGalleryItemInstance.ts +12 -0
  313. package/src/library/rendering/ChitRenderInstance.ts +34 -0
  314. package/src/library/rendering/RootChitRenderInstance.ts +30 -1
  315. package/src/library/utilities/Annotations.ts +35 -7
  316. package/src/library/utilities/CanvasStack/CanvasStack.ts +6 -1
  317. package/src/library/utilities/TokenizedText.ts +6 -0
  318. package/src/library/utilities/zIndex.ts +1 -0
@@ -0,0 +1,273 @@
1
+ import { Vector3 } from "three";
2
+ import { Chit } from "../../game/Chit";
3
+ import { PlayerChit } from "../../game/PlayerChit";
4
+ import { RootChit } from "../../game/RootChit";
5
+ import { RootChitRenderInstance } from "../../rendering/RootChitRenderInstance";
6
+ import { Target, selectChits } from "../../game/tutorial/defineTutorial";
7
+ import { UI_ALIASES } from "../../game/tutorial/allowed";
8
+ import { RegisteredGallery, galleryRegistry } from "../Gallery/registry";
9
+
10
+ export type Rect = { left: number; top: number; right: number; bottom: number };
11
+
12
+ export function rectCenter(r: Rect) {
13
+ return { x: (r.left + r.right) / 2, y: (r.top + r.bottom) / 2 };
14
+ }
15
+
16
+ export function unionRects(rects: Rect[]): Rect | undefined {
17
+ if (rects.length === 0) return undefined;
18
+ return rects.reduce((acc, r) => ({
19
+ left: Math.min(acc.left, r.left),
20
+ top: Math.min(acc.top, r.top),
21
+ right: Math.max(acc.right, r.right),
22
+ bottom: Math.max(acc.bottom, r.bottom),
23
+ }));
24
+ }
25
+
26
+ function parseScreen(v: number | string, extent: number) {
27
+ if (typeof v === "number") return v;
28
+ const s = v.trim();
29
+ if (s.endsWith("%")) return (parseFloat(s) / 100) * extent;
30
+ return parseFloat(s);
31
+ }
32
+
33
+ /** The panel root (chit with its own viewer) a chit renders in, if it renders at all */
34
+ export function panelRootOf(chit: Chit): RootChitRenderInstance | undefined {
35
+ return chit.renderInstance?.rootRenderInstance;
36
+ }
37
+
38
+ /**
39
+ * Whether a panel is in front, by the chit that shows it: false for a panel behind another in its tab
40
+ * group (during a tab slide it still paints, from where it would be).
41
+ */
42
+ export type PanelShown = (chit: Chit) => boolean;
43
+
44
+ /** Whether a chit's panel is currently in front and painting */
45
+ export function chitVisible(chit: Chit, shown?: PanelShown): boolean {
46
+ const root = panelRootOf(chit);
47
+ if (!root) return false;
48
+ if (root.paused) return false;
49
+ if (shown && !shown(chit)) return false;
50
+ const ri = chit.renderInstance;
51
+ if (!ri || !ri.group.visible) return false;
52
+ // Inside a gallery container the chit's own box is not on the table
53
+ for (let p = chit.parent; p; p = p.parent) {
54
+ if (p.renderInstance?.absorbsClickEventsForChildren) return false;
55
+ }
56
+ return true;
57
+ }
58
+
59
+ /**
60
+ * Screen (page) rectangle of a chit: its bounding box corners through the tweened world transform and
61
+ * the panel camera. Offset and scale are in bbox units (half-extent = 0.5).
62
+ */
63
+ export function projectChit(
64
+ chit: Chit,
65
+ offset?: { x?: number; y?: number; z?: number },
66
+ scale?: { x?: number; y?: number },
67
+ shown?: PanelShown,
68
+ ): Rect | undefined {
69
+ const ri = chit.renderInstance;
70
+ const root = ri?.rootRenderInstance;
71
+ if (!ri || !root || !chitVisible(chit, shown)) return undefined;
72
+ const bbox = ri.bbox;
73
+ if (bbox.scale.length() === 0) return undefined;
74
+
75
+ ri.group.updateWorldMatrix(true, false);
76
+ bbox.updateMatrix();
77
+ const sx = (scale?.x ?? 1) / 2;
78
+ const sy = (scale?.y ?? 1) / 2;
79
+ const ox = offset?.x ?? 0;
80
+ const oy = offset?.y ?? 0;
81
+ const oz = offset?.z ?? 0;
82
+ const corners: Vector3[] = [];
83
+ for (const x of [-sx, sx]) {
84
+ for (const y of [-sy, sy]) {
85
+ for (const z of [-0.5, 0.5]) {
86
+ corners.push(new Vector3(x + ox, y + oy, z + oz));
87
+ }
88
+ }
89
+ }
90
+ const rects: Rect[] = [];
91
+ for (const c of corners) {
92
+ c.applyMatrix4(bbox.matrix); // bbox local → chit space (position + size)
93
+ c.applyMatrix4(ri.group.matrixWorld); // chit space (tweened) → world
94
+ c.project(root.camera);
95
+ if (!Number.isFinite(c.x) || !Number.isFinite(c.y)) return undefined;
96
+ const screen = root.convertCameraSpaceToScreenSpace(c.x, c.y);
97
+ if (!screen) return undefined;
98
+ rects.push({ left: screen.x, top: screen.y, right: screen.x, bottom: screen.y });
99
+ }
100
+ const rect = unionRects(rects)!;
101
+ // Clip to the panel so a chit half off-panel is not drawn over its neighbour
102
+ const tl = root.convertCameraSpaceToScreenSpace(-1, 1);
103
+ const br = root.convertCameraSpaceToScreenSpace(1, -1);
104
+ if (tl && br) {
105
+ rect.left = Math.max(rect.left, tl.x);
106
+ rect.top = Math.max(rect.top, tl.y);
107
+ rect.right = Math.min(rect.right, br.x);
108
+ rect.bottom = Math.min(rect.bottom, br.y);
109
+ if (rect.right <= rect.left || rect.bottom <= rect.top) return undefined;
110
+ }
111
+ return rect;
112
+ }
113
+
114
+
115
+ export function projectUi(container: HTMLElement, name: string): Rect | undefined {
116
+ // The overlay only holds the box and the SVG; the UI it points at is its siblings, so search the viewer
117
+ const scope: ParentNode = container.parentElement ?? document;
118
+ const names = UI_ALIASES[name] ?? [name];
119
+ const el = names
120
+ .map((n) => scope.querySelector(`[data-tutorial-target="${CSS.escape(n)}"]`) as HTMLElement | null)
121
+ .find((e) => e && e.getBoundingClientRect().width > 0);
122
+ if (!el) return undefined;
123
+ return rectOfElement(el);
124
+ }
125
+
126
+ function rectOfElement(el: HTMLElement): Rect | undefined {
127
+ if (!el) return undefined;
128
+ const r = el.getBoundingClientRect();
129
+ if (r.width === 0 && r.height === 0) return undefined;
130
+ return { left: r.left, top: r.top, right: r.right, bottom: r.bottom };
131
+ }
132
+
133
+ export type ResolvedTarget = {
134
+ /** Page-space rects, one per chit (or one for a UI / screen target) */
135
+ rects: Rect[];
136
+ /** Chits the target names that are not on screen right now (other panel, not rendered yet) */
137
+ hidden: Chit[];
138
+ /** Chits shown in an open gallery but scrolled out of its view */
139
+ offscreenInGallery: { gallery: RegisteredGallery; chit: Chit }[];
140
+ /** All chits the selector named */
141
+ chits: Chit[];
142
+ };
143
+
144
+ /**
145
+ * Where a chit is on screen. An open gallery wins over the table (it is where the player acts on it,
146
+ * and a full-screen one covers the table); the small context gallery only when nothing else shows it.
147
+ */
148
+ function locateChit(
149
+ chit: Chit,
150
+ galleries: RegisteredGallery[],
151
+ offset?: { x?: number; y?: number; z?: number },
152
+ scale?: { x?: number; y?: number },
153
+ shown?: PanelShown,
154
+ ): { rect?: Rect; offscreen?: RegisteredGallery } {
155
+ let offscreen: RegisteredGallery | undefined;
156
+ for (const g of galleries.filter((g) => g.kind !== "context")) {
157
+ const found = g.locate(chit);
158
+ if (found === "offscreen") offscreen ??= g;
159
+ else if (found) return { rect: adjust(found, offset, scale) };
160
+ }
161
+ if (offscreen) return { offscreen };
162
+ const onTable = projectChit(chit, offset, scale, shown);
163
+ if (onTable) return { rect: onTable };
164
+ for (const g of galleries.filter((g) => g.kind === "context")) {
165
+ const found = g.locate(chit);
166
+ if (found && found !== "offscreen") return { rect: adjust(found, offset, scale) };
167
+ }
168
+ return {};
169
+ }
170
+
171
+ /** Offset/scale in bbox units, applied to a flat (gallery) rect: +y is toward the top */
172
+ function adjust(r: Rect, offset?: { x?: number; y?: number }, scale?: { x?: number; y?: number }): Rect {
173
+ const w = r.right - r.left;
174
+ const h = r.bottom - r.top;
175
+ const cx = (r.left + r.right) / 2 + (offset?.x ?? 0) * w;
176
+ const cy = (r.top + r.bottom) / 2 - (offset?.y ?? 0) * h;
177
+ const hw = (w * (scale?.x ?? 1)) / 2;
178
+ const hh = (h * (scale?.y ?? 1)) / 2;
179
+ return { left: cx - hw, top: cy - hh, right: cx + hw, bottom: cy + hh };
180
+ }
181
+
182
+ export function resolveTarget<P extends PlayerChit, R extends RootChit<P>>(
183
+ target: Target<P, R>,
184
+ root: R | undefined,
185
+ me: P | undefined,
186
+ container: HTMLElement,
187
+ shown?: PanelShown,
188
+ find?: (id: string) => Chit | undefined,
189
+ ): ResolvedTarget {
190
+ if (typeof target === "function" || "chit" in target) {
191
+ const selector = typeof target === "function" ? target : target.chit;
192
+ const offset = typeof target === "function" ? undefined : target.offset;
193
+ const scale = typeof target === "function" ? undefined : target.scale;
194
+ const galleries = galleryRegistry.list(container.parentElement);
195
+ const chits = selectChits(selector, root, me);
196
+ const rects: Rect[] = [];
197
+ const hidden: Chit[] = [];
198
+ const offscreenInGallery: { gallery: RegisteredGallery; chit: Chit }[] = [];
199
+ chits.forEach((c) => {
200
+ const found = locateChit(c, galleries, offset, scale, shown);
201
+ if (found.rect) rects.push(found.rect);
202
+ else if (found.offscreen) offscreenInGallery.push({ gallery: found.offscreen, chit: c });
203
+ else hidden.push(c);
204
+ });
205
+ return { rects, hidden, offscreenInGallery, chits };
206
+ }
207
+ if ("ui" in target) {
208
+ let name: string | undefined;
209
+ if (typeof target.ui === "function") {
210
+ if (root && me) {
211
+ try {
212
+ name = target.ui(root, me);
213
+ } catch {
214
+ name = undefined;
215
+ }
216
+ }
217
+ } else {
218
+ name = target.ui;
219
+ }
220
+ // A counter (`spark:<chitId>`) floats over its owner's panel: while that panel is behind another,
221
+ // the counter is hidden there too, so it counts as hidden (to reveal), not as a place to point at
222
+ if (name?.startsWith("spark:") && shown && find) {
223
+ const owner = find(name.slice("spark:".length));
224
+ if (owner && !shown(owner)) return { rects: [], hidden: [owner], offscreenInGallery: [], chits: [] };
225
+ }
226
+ const r = name ? projectUi(container, name) : undefined;
227
+ return { rects: r ? [r] : [], hidden: [], offscreenInGallery: [], chits: [] };
228
+ }
229
+ const bounds = container.getBoundingClientRect();
230
+ const x = bounds.left + parseScreen(target.screen.x, bounds.width);
231
+ const y = bounds.top + parseScreen(target.screen.y, bounds.height);
232
+ return { rects: [{ left: x - 1, top: y - 1, right: x + 1, bottom: y + 1 }], hidden: [], offscreenInGallery: [], chits: [] };
233
+ }
234
+
235
+ /** Converts a page-space rect into the overlay's own coordinate space */
236
+ export function toLocal(rect: Rect, bounds: DOMRect): Rect {
237
+ return {
238
+ left: rect.left - bounds.left,
239
+ top: rect.top - bounds.top,
240
+ right: rect.right - bounds.left,
241
+ bottom: rect.bottom - bounds.top,
242
+ };
243
+ }
244
+
245
+ /**
246
+ * Where a target's chits sit on the table, and in which panel: for zooming in on something small.
247
+ * `inGallery` when any of them is shown in an open gallery instead (nothing to zoom on the table).
248
+ */
249
+ export function tableRects<P extends PlayerChit, R extends RootChit<P>>(
250
+ target: Target<P, R>,
251
+ root: R | undefined,
252
+ me: P | undefined,
253
+ container: HTMLElement,
254
+ shown?: PanelShown,
255
+ ): { rects: { rect: Rect; panel: RootChitRenderInstance }[]; inGallery: boolean } {
256
+ if (typeof target !== "function" && !("chit" in target)) return { rects: [], inGallery: false };
257
+ const selector = typeof target === "function" ? target : target.chit;
258
+ const offset = typeof target === "function" ? undefined : target.offset;
259
+ const scale = typeof target === "function" ? undefined : target.scale;
260
+ const galleries = galleryRegistry.list(container.parentElement).filter((g) => g.kind !== "context");
261
+ const rects: { rect: Rect; panel: RootChitRenderInstance }[] = [];
262
+ let inGallery = false;
263
+ for (const c of selectChits(selector, root, me)) {
264
+ if (galleries.some((g) => !!g.locate(c))) {
265
+ inGallery = true;
266
+ continue;
267
+ }
268
+ const rect = projectChit(c, offset, scale, shown);
269
+ const panel = panelRootOf(c);
270
+ if (rect && panel) rects.push({ rect, panel });
271
+ }
272
+ return { rects, inGallery };
273
+ }
@@ -16,6 +16,7 @@ export const ORDERED_CHILDREN = "orderedChildren";
16
16
 
17
17
  const EXTRA_SERIALIZATION_PROPS_ARRAY = ["id", "_parent", "_parentOutlet", "_parentOutletIndex", "_parentFallback"];
18
18
  const EXTRA_SERIALIZATION_PROPS_SET = new Set(EXTRA_SERIALIZATION_PROPS_ARRAY);
19
+ const DELETED_SERIALIZED = JSON.stringify({ ____deleted: true });
19
20
 
20
21
  const dirtyProxyCache = new WeakMap<object, object>();
21
22
 
@@ -460,7 +461,10 @@ export class Chit extends ObjectWithProps {
460
461
  /** @internal */
461
462
  @NonEditable public children: Chit[] = [];
462
463
 
463
- /** @internal */
464
+ /**
465
+ * Visits this chit and everything under it, depth first. Return false from `fn` to skip a chit's
466
+ * children. Handy in tutorial selectors and checks ("every card on the table").
467
+ */
464
468
  public walk(fn: (c: Chit) => boolean | void) {
465
469
  if (fn(this) === false) {
466
470
  return;
@@ -505,6 +509,7 @@ export class Chit extends ObjectWithProps {
505
509
  if (!propsOnly) {
506
510
  this._version++;
507
511
  if (j.____deleted) {
512
+ this.forgetFallbackUnlessHidden();
508
513
  this.setParent();
509
514
  return;
510
515
  }
@@ -681,7 +686,7 @@ export class Chit extends ObjectWithProps {
681
686
  return result;
682
687
  }
683
688
 
684
- /** @internal */
689
+ /** Like `chit.walk` over several roots, visiting each chit (by id) once. */
685
690
  public static walk(chits: Chit[], fn: (c: Chit) => boolean | void) {
686
691
  const seenIds = new Set();
687
692
  chits.forEach((chit) =>
@@ -725,10 +730,21 @@ export class Chit extends ObjectWithProps {
725
730
  return result;
726
731
  }
727
732
 
733
+ /**
734
+ * A deleted chit keeps its `parentFallback` only when that fallback hides its children, as a bag does: then the
735
+ * chit is "back in the bag", invisible, and can come out again. Any other fallback (a piece a new chit was made to
736
+ * come from) would keep the deleted chit alive and drawn beside it, since the renderer never destroys a parentless
737
+ * chit that still has a fallback. Undo deletes chits this way, so without this an undone piece lingers on screen.
738
+ * @internal
739
+ */
740
+ public forgetFallbackUnlessHidden() {
741
+ if (this._parentFallback && this._parentFallback.shouldRenderChild(this)) {
742
+ this._parentFallback = undefined;
743
+ }
744
+ }
745
+
728
746
  /** @internal */
729
747
  public static deletedIfSerialized(): string {
730
- return JSON.stringify({
731
- ____deleted: true,
732
- });
748
+ return DELETED_SERIALIZED;
733
749
  }
734
750
  }
@@ -10,6 +10,24 @@ export class ClientTimeState {
10
10
  public animationSpeedMultiplier = new EventChannel<number>(1);
11
11
  public animationSpeedOverrideMultiplier = new EventChannel<number | undefined>(undefined);
12
12
  public isLoading = new EventChannel<boolean>(true);
13
+ /**
14
+ * The furthest clock this client may show, or undefined to follow the game. A tutorial holds the
15
+ * board here to talk about what is on screen while the game itself plays on; raising or lifting the
16
+ * hold lets the board animate on from where it stopped. Only this client's view is affected.
17
+ */
18
+ public timelineHold = new EventChannel<number | undefined>(undefined);
19
+
20
+ /** The furthest clock the board may play to: the game's latest, or the hold if that is lower */
21
+ public playableClock(maxClock: number) {
22
+ const hold = this.timelineHold.value;
23
+ return hold === undefined ? maxClock : Math.min(hold, maxClock);
24
+ }
25
+ /**
26
+ * Open live instead of replaying what happened since the player's last answer, once (the next
27
+ * `setStartTime`). For a viewer on a match that was just rebuilt (a tutorial's Back), where the
28
+ * replay would only re-show moves the player already watched.
29
+ */
30
+ public skipInitialReplay = false;
13
31
 
14
32
  private currentlyAnimating = new Set<string>();
15
33
  public setAnimationState(key: string, isAnimating: boolean) {
@@ -9,6 +9,7 @@ import { ChitRenderSpec } from "../rendering/ChitRenderSpec";
9
9
  import { TokenDefinition } from "../utilities/TokenizedText";
10
10
  import { GameMetaData } from "./GameMetaData";
11
11
  import type { GameAi } from "./ai/defineAi";
12
+ import type { TutorialSpec } from "./tutorial/defineTutorial";
12
13
 
13
14
  export interface IChitLibrary<P extends PlayerChit, R extends RootChit<P>> {
14
15
  [key: string]: new () => Chit;
@@ -69,4 +70,10 @@ export interface Game<P extends PlayerChit, R extends RootChit<P>> {
69
70
  * pick the best. Without this, AI players pick at random (weighted by `demoPickWeight`).
70
71
  */
71
72
  ai?: GameAi<P, R, any>;
73
+
74
+ /**
75
+ * Scripted tutorials (see `defineTutorial`). A host starts one with `DemoWrapper` (or the bundle's
76
+ * `createDemoMatchViewer`) by id; the Playground's Demo tab lists them.
77
+ */
78
+ tutorials?: TutorialSpec<P, R>[];
72
79
  }
@@ -1,4 +1,5 @@
1
1
  import Color from "color";
2
+ import type { TutorialTheme } from "./tutorial/TutorialTheme";
2
3
 
3
4
  export const DEFAULT_FONT_FAMILY = "Quicksand, sans-serif";
4
5
 
@@ -103,6 +104,9 @@ export class GameTheme {
103
104
  public inlineGalleryButtonBackgroundColor = "#000000";
104
105
  public inlineGalleryButtonForegroundColor = "rgba(255,255,255,0.5)";
105
106
 
107
+ /** Overrides for the tutorial overlay's colours (see `TutorialTheme`); the rest derive from this theme */
108
+ public tutorial?: Partial<TutorialTheme>;
109
+
106
110
  /** Reference to .png or .jpg file to show as box art in advertising the game */
107
111
  public boxArt = "";
108
112
  /** Reference to .png or .jpg file to show as a screenshot in advertising the game */
@@ -5,7 +5,7 @@ import { Game, GameResult } from "./Game";
5
5
  import { ServerTime } from "./serverTransport/ServerTime";
6
6
  import { PlayerInfo } from "./PlayerInfo";
7
7
  import { DestroyError, MismatchError, RerunError, Turn } from "./Turn";
8
- import { TurnState } from "./TurnState";
8
+ import { RngSource, TurnState } from "./TurnState";
9
9
  import { IMatchStorage } from "./MatchStorage";
10
10
  import { ServerPrompts } from "./serverTransport/ServerPrompts";
11
11
  import { EventChannel } from "../utilities/EventChannel";
@@ -15,6 +15,12 @@ import { PlayerChit } from "./PlayerChit";
15
15
  import { AiPlayerHandle, ConnectAiPlayerOptions, connectAiPlayer } from "./ai/connectAiPlayer";
16
16
  import type { AiMemoryStore } from "./ai/AiClientPrompts";
17
17
 
18
+ /** Engine-level knobs for a match (as opposed to the game's own `matchOptions`). */
19
+ export type MatchConfig = {
20
+ /** Where fresh random draws come from. Default: `Math.random`. See `RngSource`. */
21
+ rngSource?: RngSource;
22
+ };
23
+
18
24
  /** Options for {@link Match.seatAiPlayers}: applied to every bot it seats. */
19
25
  export type SeatAiPlayersOptions = Omit<ConnectAiPlayerOptions, "difficulty" | "params" | "choose" | "memoryStore">;
20
26
 
@@ -91,7 +97,10 @@ export class Match<P extends PlayerChit, R extends RootChit<P>> {
91
97
  public players: PlayerInfo[],
92
98
  private matchStorage: IMatchStorage,
93
99
  private matchOptions?: any,
94
- ) {}
100
+ private config: MatchConfig = {},
101
+ ) {
102
+ this.state.rngSource = config.rngSource;
103
+ }
95
104
 
96
105
  async load() {
97
106
  const savedState = await this.matchStorage.readState();
@@ -103,6 +112,7 @@ export class Match<P extends PlayerChit, R extends RootChit<P>> {
103
112
  return;
104
113
  }
105
114
  this.state = new TurnState();
115
+ this.state.rngSource = this.config.rngSource;
106
116
  this.state.deserialize(savedState);
107
117
  if (this.errorState.value) {
108
118
  this.turn.value?.destroy();
@@ -326,18 +326,32 @@ export class DragPick<C extends Chit> extends Pick {
326
326
 
327
327
  public dropTargets: DragTarget<any, C>[] = [];
328
328
 
329
+ /** Focus the draggable chits themselves (no argument), or the given chits, when the prompt stages in */
330
+ focus(chit?: Chit | Chit[]): this {
331
+ if (!chit) {
332
+ this.focusChits.push(...this.chits);
333
+ } else if (Array.isArray(chit)) {
334
+ this.focusChits.push(...chit);
335
+ } else {
336
+ this.focusChits.push(chit);
337
+ }
338
+ return this;
339
+ }
340
+
329
341
  /** @internal */
330
342
  serializeDetails() {
331
343
  const result: any = {
332
344
  c: this.chits.map((chit) => chit.id),
333
345
  d: this.dropTargets.map((dropTarget) => dropTarget.chits.map((chit) => chit.id)),
346
+ f: this.focusChits.map((chit) => chit.id),
334
347
  };
335
348
  return result;
336
349
  }
337
350
 
338
351
  /** @internal */
339
- deserializeDetails({ c, d }: { c: string[]; d: string[][] }, findChit: FindChit): void {
352
+ deserializeDetails({ c, d, f }: { c: string[]; d: string[][]; f?: string[] }, findChit: FindChit): void {
340
353
  this.chits = c.map((chitId) => findChit(chitId) as C).filter((d) => d);
354
+ this.focusChits = (f ?? []).map((chitId) => findChit(chitId)).filter((d) => d);
341
355
  this.dropTargets = d.map((dropIds: string[]) => {
342
356
  const result = new DragTarget<any, C>();
343
357
  result.chits = dropIds.map((chitId: string) => findChit(chitId)).filter((d) => d);
@@ -375,6 +389,7 @@ export class DragPick<C extends Chit> extends Pick {
375
389
  prompt.resolvePick(this, { chitId: c.id!, targetChitId: droppedChit.id! });
376
390
  };
377
391
  });
392
+ this.processFocus();
378
393
  }
379
394
 
380
395
  /** @internal */
@@ -9,7 +9,11 @@ export class PlayerPromptStatusChit extends Chit {
9
9
  public latestPromptMessage?: string;
10
10
  /** Plain-text form of {@link latestPromptMessage} for storage, match lists and notifications. @internal */
11
11
  public latestPromptMessageText?: string;
12
- /** @internal */
12
+ /**
13
+ * The prompt this player is being asked right now, on the side that runs the match (undefined when
14
+ * it is not their turn). Read it, do not resolve it: answers go through the player's own client.
15
+ * Headless tutorial runs and harnesses use it to see whose turn it is.
16
+ */
13
17
  @NonEditable public latestPrompt = new EventChannel<Prompt | undefined>(undefined, 50);
14
18
  /** @internal */
15
19
  @NonEditable public latestPromptResponseTime = 0;
@@ -20,8 +20,17 @@ const defaultFindChit: FindChit = () => {
20
20
 
21
21
  type FindChit = (id: string) => Chit;
22
22
 
23
+ /** What a player is trying to do with a prompt; a `PromptGuard` says whether it goes through. */
24
+ export type PromptAction = { type: "pick"; pick: Pick; value: any } | { type: "undo"; fullReset: boolean };
25
+ export type PromptGuard = (action: PromptAction) => boolean;
26
+
23
27
  export abstract class Prompt {
24
28
  public id = "";
29
+ /**
30
+ * Set on the client (see `ClientPrompts.guard`) to vet a player's answers before they are sent: a
31
+ * tutorial lets through only the moves its current step asks for. Not serialized.
32
+ */
33
+ public guard?: PromptGuard;
25
34
  public resolved = false;
26
35
  public clock = 0;
27
36
  public response: any;
@@ -73,6 +82,11 @@ export abstract class Prompt {
73
82
  }
74
83
 
75
84
  stepBack(fullReset: boolean = false) {
85
+ // The guard goes first: a tutorial turns Undo into its own Back, which works even where the
86
+ // engine could not undo (after a draw)
87
+ if (this.guard && !this.guard({ type: "undo", fullReset })) {
88
+ return;
89
+ }
76
90
  if (!this.canReset) {
77
91
  throw new Error("Cannot be stepped back");
78
92
  }
@@ -254,6 +268,12 @@ export class PickPrompt extends Prompt {
254
268
  }
255
269
 
256
270
  resolvePick(pick: Pick, value: any) {
271
+ if (this.resolved) {
272
+ return;
273
+ }
274
+ if (this.guard && !this.guard({ type: "pick", pick, value })) {
275
+ return;
276
+ }
257
277
  const idx = this.picks.indexOf(pick);
258
278
  this.resolve({ idx, value, pickType: pick.type });
259
279
  }