@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.
- package/README.md +8 -0
- package/dist/components/ActionLogDisplay.d.ts.map +1 -1
- package/dist/components/ActionLogDisplay.js +1 -1
- package/dist/components/ActionLogDisplay.js.map +1 -1
- package/dist/components/BottomBarButton.d.ts +3 -1
- package/dist/components/BottomBarButton.d.ts.map +1 -1
- package/dist/components/BottomBarButton.js +3 -2
- package/dist/components/BottomBarButton.js.map +1 -1
- package/dist/components/ContextGalleryDisplay.d.ts.map +1 -1
- package/dist/components/ContextGalleryDisplay.js +1 -1
- package/dist/components/ContextGalleryDisplay.js.map +1 -1
- package/dist/components/DemoWrapper.d.ts +30 -2
- package/dist/components/DemoWrapper.d.ts.map +1 -1
- package/dist/components/DemoWrapper.js +79 -36
- package/dist/components/DemoWrapper.js.map +1 -1
- package/dist/components/FullScreenGalleryDisplay.d.ts.map +1 -1
- package/dist/components/FullScreenGalleryDisplay.js +2 -2
- package/dist/components/FullScreenGalleryDisplay.js.map +1 -1
- package/dist/components/Gallery/BuiltItem.d.ts +6 -2
- package/dist/components/Gallery/BuiltItem.d.ts.map +1 -1
- package/dist/components/Gallery/BuiltItem.js +28 -9
- package/dist/components/Gallery/BuiltItem.js.map +1 -1
- package/dist/components/Gallery/GalleryController.d.ts +18 -0
- package/dist/components/Gallery/GalleryController.d.ts.map +1 -1
- package/dist/components/Gallery/GalleryController.js +67 -0
- package/dist/components/Gallery/GalleryController.js.map +1 -1
- package/dist/components/Gallery/GalleryViewer.d.ts +6 -1
- package/dist/components/Gallery/GalleryViewer.d.ts.map +1 -1
- package/dist/components/Gallery/GalleryViewer.js +48 -10
- package/dist/components/Gallery/GalleryViewer.js.map +1 -1
- package/dist/components/Gallery/LayoutManager.d.ts +6 -0
- package/dist/components/Gallery/LayoutManager.d.ts.map +1 -1
- package/dist/components/Gallery/LayoutManager.js +23 -3
- package/dist/components/Gallery/LayoutManager.js.map +1 -1
- package/dist/components/Gallery/constants.d.ts +2 -0
- package/dist/components/Gallery/constants.d.ts.map +1 -1
- package/dist/components/Gallery/constants.js +2 -0
- package/dist/components/Gallery/constants.js.map +1 -1
- package/dist/components/Gallery/registry.d.ts +34 -0
- package/dist/components/Gallery/registry.d.ts.map +1 -0
- package/dist/components/Gallery/registry.js +17 -0
- package/dist/components/Gallery/registry.js.map +1 -0
- package/dist/components/GameDesigner.d.ts.map +1 -1
- package/dist/components/GameDesigner.js +42 -10
- package/dist/components/GameDesigner.js.map +1 -1
- package/dist/components/InlineGalleryDisplay.d.ts.map +1 -1
- package/dist/components/InlineGalleryDisplay.js +2 -2
- package/dist/components/InlineGalleryDisplay.js.map +1 -1
- package/dist/components/LiveButton.d.ts.map +1 -1
- package/dist/components/LiveButton.js +5 -2
- package/dist/components/LiveButton.js.map +1 -1
- package/dist/components/MatchViewer.d.ts +6 -1
- package/dist/components/MatchViewer.d.ts.map +1 -1
- package/dist/components/MatchViewer.js +9 -3
- package/dist/components/MatchViewer.js.map +1 -1
- package/dist/components/Panel/MultiPanel.d.ts.map +1 -1
- package/dist/components/Panel/MultiPanel.js +18 -0
- package/dist/components/Panel/MultiPanel.js.map +1 -1
- package/dist/components/Panel/PanelContents.d.ts.map +1 -1
- package/dist/components/Panel/PanelContents.js +92 -23
- package/dist/components/Panel/PanelContents.js.map +1 -1
- package/dist/components/Panel/PanelTabStack.d.ts.map +1 -1
- package/dist/components/Panel/PanelTabStack.js +1 -1
- package/dist/components/Panel/PanelTabStack.js.map +1 -1
- package/dist/components/PanelSpark.d.ts.map +1 -1
- package/dist/components/PanelSpark.js +3 -2
- package/dist/components/PanelSpark.js.map +1 -1
- package/dist/components/Playground.d.ts.map +1 -1
- package/dist/components/Playground.js +10 -4
- package/dist/components/Playground.js.map +1 -1
- package/dist/components/PromptControls.d.ts.map +1 -1
- package/dist/components/PromptControls.js +4 -2
- package/dist/components/PromptControls.js.map +1 -1
- package/dist/components/SparkLineChart.d.ts.map +1 -1
- package/dist/components/SparkLineChart.js +22 -26
- package/dist/components/SparkLineChart.js.map +1 -1
- package/dist/components/TimeControlBar.d.ts.map +1 -1
- package/dist/components/TimeControlBar.js +5 -3
- package/dist/components/TimeControlBar.js.map +1 -1
- package/dist/components/TokenizedMarkdown.d.ts +23 -0
- package/dist/components/TokenizedMarkdown.d.ts.map +1 -0
- package/dist/components/TokenizedMarkdown.js +144 -0
- package/dist/components/TokenizedMarkdown.js.map +1 -0
- package/dist/components/TokenizedMessage.d.ts +6 -0
- package/dist/components/TokenizedMessage.d.ts.map +1 -1
- package/dist/components/TokenizedMessage.js +20 -19
- package/dist/components/TokenizedMessage.js.map +1 -1
- package/dist/components/TopBarPlayers.d.ts.map +1 -1
- package/dist/components/TopBarPlayers.js +1 -1
- package/dist/components/TopBarPlayers.js.map +1 -1
- package/dist/components/Tutorial/BrowserNarration.d.ts +55 -0
- package/dist/components/Tutorial/BrowserNarration.d.ts.map +1 -0
- package/dist/components/Tutorial/BrowserNarration.js +240 -0
- package/dist/components/Tutorial/BrowserNarration.js.map +1 -0
- package/dist/components/Tutorial/TutorialBox.d.ts +26 -0
- package/dist/components/Tutorial/TutorialBox.d.ts.map +1 -0
- package/dist/components/Tutorial/TutorialBox.js +239 -0
- package/dist/components/Tutorial/TutorialBox.js.map +1 -0
- package/dist/components/Tutorial/TutorialDevPanel.d.ts +9 -0
- package/dist/components/Tutorial/TutorialDevPanel.d.ts.map +1 -0
- package/dist/components/Tutorial/TutorialDevPanel.js +92 -0
- package/dist/components/Tutorial/TutorialDevPanel.js.map +1 -0
- package/dist/components/Tutorial/TutorialOverlay.d.ts +7 -0
- package/dist/components/Tutorial/TutorialOverlay.d.ts.map +1 -0
- package/dist/components/Tutorial/TutorialOverlay.js +1132 -0
- package/dist/components/Tutorial/TutorialOverlay.js.map +1 -0
- package/dist/components/Tutorial/targetRects.d.ts +67 -0
- package/dist/components/Tutorial/targetRects.d.ts.map +1 -0
- package/dist/components/Tutorial/targetRects.js +241 -0
- package/dist/components/Tutorial/targetRects.js.map +1 -0
- package/dist/game/Chit.d.ts +7 -0
- package/dist/game/Chit.d.ts.map +1 -1
- package/dist/game/Chit.js +20 -5
- package/dist/game/Chit.js.map +1 -1
- package/dist/game/ClientTimeState.d.ts +14 -0
- package/dist/game/ClientTimeState.d.ts.map +1 -1
- package/dist/game/ClientTimeState.js +17 -0
- package/dist/game/ClientTimeState.js.map +1 -1
- package/dist/game/Game.d.ts +6 -0
- package/dist/game/Game.d.ts.map +1 -1
- package/dist/game/GameTheme.d.ts +3 -0
- package/dist/game/GameTheme.d.ts.map +1 -1
- package/dist/game/GameTheme.js +2 -0
- package/dist/game/GameTheme.js.map +1 -1
- package/dist/game/Match.d.ts +8 -2
- package/dist/game/Match.d.ts.map +1 -1
- package/dist/game/Match.js +4 -1
- package/dist/game/Match.js.map +1 -1
- package/dist/game/Pick.d.ts +2 -0
- package/dist/game/Pick.d.ts.map +1 -1
- package/dist/game/Pick.js +17 -1
- package/dist/game/Pick.js.map +1 -1
- package/dist/game/PlayerPromptStatusChit.d.ts +8 -0
- package/dist/game/PlayerPromptStatusChit.d.ts.map +1 -1
- package/dist/game/PlayerPromptStatusChit.js +5 -1
- package/dist/game/PlayerPromptStatusChit.js.map +1 -1
- package/dist/game/Prompt.d.ts +15 -0
- package/dist/game/Prompt.d.ts.map +1 -1
- package/dist/game/Prompt.js +16 -0
- package/dist/game/Prompt.js.map +1 -1
- package/dist/game/Turn.d.ts +15 -4
- package/dist/game/Turn.d.ts.map +1 -1
- package/dist/game/Turn.js +173 -60
- package/dist/game/Turn.js.map +1 -1
- package/dist/game/TurnState.d.ts +12 -1
- package/dist/game/TurnState.d.ts.map +1 -1
- package/dist/game/TurnState.js +15 -3
- package/dist/game/TurnState.js.map +1 -1
- package/dist/game/ai/AiClientPrompts.d.ts +20 -3
- package/dist/game/ai/AiClientPrompts.d.ts.map +1 -1
- package/dist/game/ai/AiClientPrompts.js +42 -6
- package/dist/game/ai/AiClientPrompts.js.map +1 -1
- package/dist/game/ai/AiPlayerView.js +2 -0
- package/dist/game/ai/AiPlayerView.js.map +1 -1
- package/dist/game/clientTransport/ClientPrompts.d.ts +20 -1
- package/dist/game/clientTransport/ClientPrompts.d.ts.map +1 -1
- package/dist/game/clientTransport/ClientPrompts.js +30 -1
- package/dist/game/clientTransport/ClientPrompts.js.map +1 -1
- package/dist/game/clientTransport/ClientTime.d.ts +13 -0
- package/dist/game/clientTransport/ClientTime.d.ts.map +1 -1
- package/dist/game/clientTransport/ClientTime.js +51 -11
- package/dist/game/clientTransport/ClientTime.js.map +1 -1
- package/dist/game/tutorial/TutorialController.d.ts +300 -0
- package/dist/game/tutorial/TutorialController.d.ts.map +1 -0
- package/dist/game/tutorial/TutorialController.js +1182 -0
- package/dist/game/tutorial/TutorialController.js.map +1 -0
- package/dist/game/tutorial/TutorialRuntime.d.ts +89 -0
- package/dist/game/tutorial/TutorialRuntime.d.ts.map +1 -0
- package/dist/game/tutorial/TutorialRuntime.js +261 -0
- package/dist/game/tutorial/TutorialRuntime.js.map +1 -0
- package/dist/game/tutorial/TutorialTheme.d.ts +28 -0
- package/dist/game/tutorial/TutorialTheme.d.ts.map +1 -0
- package/dist/game/tutorial/TutorialTheme.js +39 -0
- package/dist/game/tutorial/TutorialTheme.js.map +1 -0
- package/dist/game/tutorial/allowed.d.ts +2 -0
- package/dist/game/tutorial/allowed.d.ts.map +1 -0
- package/dist/game/tutorial/allowed.js +119 -0
- package/dist/game/tutorial/allowed.js.map +1 -0
- package/dist/game/tutorial/checks.d.ts +58 -0
- package/dist/game/tutorial/checks.d.ts.map +1 -0
- package/dist/game/tutorial/checks.js +144 -0
- package/dist/game/tutorial/checks.js.map +1 -0
- package/dist/game/tutorial/createDemoMatch.d.ts +47 -0
- package/dist/game/tutorial/createDemoMatch.d.ts.map +1 -0
- package/dist/game/tutorial/createDemoMatch.js +67 -0
- package/dist/game/tutorial/createDemoMatch.js.map +1 -0
- package/dist/game/tutorial/defineTutorial.d.ts +353 -0
- package/dist/game/tutorial/defineTutorial.d.ts.map +1 -0
- package/dist/game/tutorial/defineTutorial.js +86 -0
- package/dist/game/tutorial/defineTutorial.js.map +1 -0
- package/dist/game/tutorial/runTutorial.d.ts +63 -0
- package/dist/game/tutorial/runTutorial.d.ts.map +1 -0
- package/dist/game/tutorial/runTutorial.js +273 -0
- package/dist/game/tutorial/runTutorial.js.map +1 -0
- package/dist/hooks/usePanelNavigation.d.ts +28 -0
- package/dist/hooks/usePanelNavigation.d.ts.map +1 -0
- package/dist/hooks/usePanelNavigation.js +36 -0
- package/dist/hooks/usePanelNavigation.js.map +1 -0
- package/dist/hooks/useTimeController.d.ts +2 -1
- package/dist/hooks/useTimeController.d.ts.map +1 -1
- package/dist/hooks/useTimeController.js +6 -2
- package/dist/hooks/useTimeController.js.map +1 -1
- package/dist/hooks/useTutorial.d.ts +48 -0
- package/dist/hooks/useTutorial.d.ts.map +1 -0
- package/dist/hooks/useTutorial.js +16 -0
- package/dist/hooks/useTutorial.js.map +1 -0
- package/dist/index.d.ts +36 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.html +12 -0
- package/dist/index.js +19 -2
- package/dist/index.js.map +1 -1
- package/dist/main.0792d734cde2c688d5f7.hot-update.js +16991 -0
- package/dist/main.0792d734cde2c688d5f7.hot-update.js.map +1 -0
- package/dist/main.0792d734cde2c688d5f7.hot-update.json +1 -0
- package/dist/pretty-chitty.js +204513 -0
- package/dist/pretty-chitty.js.map +1 -0
- package/dist/rendering/CameraWrapperPerspective.d.ts +5 -0
- package/dist/rendering/CameraWrapperPerspective.d.ts.map +1 -1
- package/dist/rendering/CameraWrapperPerspective.js +16 -0
- package/dist/rendering/CameraWrapperPerspective.js.map +1 -1
- package/dist/rendering/ChitGalleryItemInstance.d.ts +1 -0
- package/dist/rendering/ChitGalleryItemInstance.d.ts.map +1 -1
- package/dist/rendering/ChitGalleryItemInstance.js +12 -0
- package/dist/rendering/ChitGalleryItemInstance.js.map +1 -1
- package/dist/rendering/ChitRenderInstance.d.ts +9 -1
- package/dist/rendering/ChitRenderInstance.d.ts.map +1 -1
- package/dist/rendering/ChitRenderInstance.js +28 -0
- package/dist/rendering/ChitRenderInstance.js.map +1 -1
- package/dist/rendering/RootChitRenderInstance.d.ts +2 -0
- package/dist/rendering/RootChitRenderInstance.d.ts.map +1 -1
- package/dist/rendering/RootChitRenderInstance.js +29 -0
- package/dist/rendering/RootChitRenderInstance.js.map +1 -1
- package/dist/utilities/Annotations.d.ts +15 -0
- package/dist/utilities/Annotations.d.ts.map +1 -1
- package/dist/utilities/Annotations.js +31 -7
- package/dist/utilities/Annotations.js.map +1 -1
- package/dist/utilities/CanvasStack/CanvasStack.d.ts +2 -0
- package/dist/utilities/CanvasStack/CanvasStack.d.ts.map +1 -1
- package/dist/utilities/CanvasStack/CanvasStack.js +4 -0
- package/dist/utilities/CanvasStack/CanvasStack.js.map +1 -1
- package/dist/utilities/TokenizedText.d.ts +6 -0
- package/dist/utilities/TokenizedText.d.ts.map +1 -1
- package/dist/utilities/TokenizedText.js.map +1 -1
- package/dist/utilities/zIndex.d.ts +1 -0
- package/dist/utilities/zIndex.d.ts.map +1 -1
- package/dist/utilities/zIndex.js +1 -0
- package/dist/utilities/zIndex.js.map +1 -1
- package/package.json +3 -2
- package/src/library/components/ActionLogDisplay.tsx +1 -0
- package/src/library/components/BottomBarButton.tsx +5 -0
- package/src/library/components/ContextGalleryDisplay.tsx +2 -0
- package/src/library/components/DemoWrapper.tsx +147 -44
- package/src/library/components/FullScreenGalleryDisplay.tsx +3 -0
- package/src/library/components/Gallery/BuiltItem.ts +30 -9
- package/src/library/components/Gallery/GalleryController.ts +72 -1
- package/src/library/components/Gallery/GalleryViewer.tsx +54 -10
- package/src/library/components/Gallery/LayoutManager.ts +30 -6
- package/src/library/components/Gallery/constants.ts +2 -0
- package/src/library/components/Gallery/registry.ts +44 -0
- package/src/library/components/GameDesigner.tsx +121 -12
- package/src/library/components/InlineGalleryDisplay.tsx +5 -0
- package/src/library/components/LiveButton.tsx +8 -5
- package/src/library/components/MatchViewer.tsx +14 -3
- package/src/library/components/Panel/MultiPanel.tsx +21 -0
- package/src/library/components/Panel/PanelContents.tsx +70 -1
- package/src/library/components/Panel/PanelTabStack.tsx +1 -0
- package/src/library/components/PanelSpark.tsx +9 -4
- package/src/library/components/Playground.tsx +48 -21
- package/src/library/components/PromptControls.tsx +7 -3
- package/src/library/components/SparkLineChart.tsx +23 -27
- package/src/library/components/TimeControlBar.tsx +5 -3
- package/src/library/components/TokenizedMarkdown.tsx +224 -0
- package/src/library/components/TokenizedMessage.tsx +28 -32
- package/src/library/components/TopBarPlayers.tsx +12 -9
- package/src/library/components/Tutorial/BrowserNarration.ts +233 -0
- package/src/library/components/Tutorial/TutorialBox.tsx +506 -0
- package/src/library/components/Tutorial/TutorialDevPanel.tsx +297 -0
- package/src/library/components/Tutorial/TutorialOverlay.tsx +1301 -0
- package/src/library/components/Tutorial/targetRects.ts +273 -0
- package/src/library/game/Chit.ts +21 -5
- package/src/library/game/ClientTimeState.ts +18 -0
- package/src/library/game/Game.ts +7 -0
- package/src/library/game/GameTheme.ts +4 -0
- package/src/library/game/Match.ts +12 -2
- package/src/library/game/Pick.ts +16 -1
- package/src/library/game/PlayerPromptStatusChit.ts +5 -1
- package/src/library/game/Prompt.ts +20 -0
- package/src/library/game/Turn.ts +179 -61
- package/src/library/game/TurnState.ts +26 -3
- package/src/library/game/ai/AI_GUIDE.md +10 -0
- package/src/library/game/ai/AiClientPrompts.ts +60 -11
- package/src/library/game/ai/AiPlayerView.ts +2 -0
- package/src/library/game/clientTransport/ClientPrompts.ts +31 -1
- package/src/library/game/clientTransport/ClientTime.ts +54 -13
- package/src/library/game/serialize.test.ts +275 -0
- package/src/library/game/tutorial/TUTORIAL_GUIDE.md +411 -0
- package/src/library/game/tutorial/TutorialController.test.ts +731 -0
- package/src/library/game/tutorial/TutorialController.ts +1286 -0
- package/src/library/game/tutorial/TutorialRuntime.ts +311 -0
- package/src/library/game/tutorial/TutorialTheme.ts +67 -0
- package/src/library/game/tutorial/allowed.ts +145 -0
- package/src/library/game/tutorial/checks.ts +186 -0
- package/src/library/game/tutorial/createDemoMatch.ts +115 -0
- package/src/library/game/tutorial/defineTutorial.ts +414 -0
- package/src/library/game/tutorial/runTutorial.ts +331 -0
- package/src/library/game/undo.test.ts +282 -0
- package/src/library/hooks/usePanelNavigation.tsx +65 -0
- package/src/library/hooks/useTimeController.tsx +6 -2
- package/src/library/hooks/useTutorial.tsx +76 -0
- package/src/library/index.ts +57 -2
- package/src/library/rendering/CameraWrapperPerspective.ts +17 -0
- package/src/library/rendering/ChitGalleryItemInstance.ts +12 -0
- package/src/library/rendering/ChitRenderInstance.ts +34 -0
- package/src/library/rendering/RootChitRenderInstance.ts +30 -1
- package/src/library/utilities/Annotations.ts +35 -7
- package/src/library/utilities/CanvasStack/CanvasStack.ts +6 -1
- package/src/library/utilities/TokenizedText.ts +6 -0
- package/src/library/utilities/zIndex.ts +1 -0
|
@@ -0,0 +1,411 @@
|
|
|
1
|
+
# Writing a scripted tutorial for a Pretty Chitty game
|
|
2
|
+
|
|
3
|
+
This guide is for whoever adds a tutorial to a game, whether a person or a coding agent. Follow it
|
|
4
|
+
top to bottom. When you're done:
|
|
5
|
+
|
|
6
|
+
- `src/tutorial.ts` exports one `defineTutorial(...)` per locale, listed on `Game.tutorials`,
|
|
7
|
+
- every step either narrates or asks the player to do one thing and checks it against game state,
|
|
8
|
+
- every random draw and every bot move the script relies on is pinned to the step it happens in,
|
|
9
|
+
- a `runTutorial` test proves the script can be completed.
|
|
10
|
+
|
|
11
|
+
The reference implementation is the engine's own demo: `src/demo/market/tutorial.ts` (the script),
|
|
12
|
+
`src/demo/market/MarketGame.ts` (the game it runs on) and `src/demo/market/tutorial.test.ts`.
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## How it works (read this first)
|
|
17
|
+
|
|
18
|
+
- A tutorial runs **the way a demo game runs**: an in-process match on ephemeral storage, the person
|
|
19
|
+
in one seat and an engine bot in every other seat. A demo *is* a tutorial with no steps. Hosts start
|
|
20
|
+
one with `DemoWrapper` (`createDemoMatchViewer` in a bundle); the Playground's **Demo** tab lists
|
|
21
|
+
every tutorial the game declares.
|
|
22
|
+
- The script is a list of **steps**. A step shows text in a floating box (markdown with the game's
|
|
23
|
+
`:token:` icons), optionally reads it aloud, and draws **rings** and **arrows** on a 2D layer over
|
|
24
|
+
the player. Targets are selectors over game state (`(root, me) => me.hand`), re-resolved every
|
|
25
|
+
frame, so highlights follow chits as they move and the overlay switches to whatever panel holds
|
|
26
|
+
them.
|
|
27
|
+
- A step with `waitFor` is a **"do it" step**: the box says "Your move" and shows no Next until
|
|
28
|
+
the check passes, then the tutorial moves on by itself. Checks are predicates on the state the player sees, so order and
|
|
29
|
+
alternatives are tolerated by construction.
|
|
30
|
+
- **The game only accepts what the script allows.** While a tutorial runs, every tap, drag, button
|
|
31
|
+
and undo goes through a guard: a narration step lets nothing through, and a "do it" step lets
|
|
32
|
+
through only the moves in its `allow` list. Anything else is dropped and the box shows the hint.
|
|
33
|
+
The game's **Undo button is the tutorial's Back** while a tutorial runs: it shows exactly when it
|
|
34
|
+
normally would, and pressing it (or long-pressing it) puts the board back the same way the box's
|
|
35
|
+
Back does. When the tutorial ends, everything is allowed again.
|
|
36
|
+
- **Acting ahead is stepping forward.** If, while a narration step is talking, the player makes a
|
|
37
|
+
move the *next* "do it" step allows (or taps a control it lists as `{ ui }`), the tutorial jumps
|
|
38
|
+
to that step and the move goes through. The steps skipped over still count as seen: their
|
|
39
|
+
snapshots are taken for Back and their `onEnter`/`onExit` and step events run, but their
|
|
40
|
+
narration, focus and gallery commands do not. The "do it" step itself is not narrated, since it
|
|
41
|
+
would only ask for what was just done; it moves on after the usual short beat once its check
|
|
42
|
+
passes, and narrates as usual if the check does not pass. Only the first "do it" step ahead counts,
|
|
43
|
+
so nothing jumps past a step that waits.
|
|
44
|
+
- A step without `waitFor` **narrates and moves on by itself** when its audio ends (or its reading
|
|
45
|
+
clock, when there is no audio). Set `pause: true` to wait for Next instead. The last step always
|
|
46
|
+
waits for Finish.
|
|
47
|
+
- **Back puts the game back** where it was when that step started. The runner snapshots the match as
|
|
48
|
+
each step goes live; Back hands that snapshot to the running match, which reruns from it in place
|
|
49
|
+
(decisions replay deterministically, the pinned draws and forced moves rewind with it) while the
|
|
50
|
+
viewer animates the board back. Rapid presses queue up. **Back also pauses the tutorial**: the
|
|
51
|
+
bots hold their moves, further Back and Next presses move silently between steps, and nothing plays
|
|
52
|
+
or advances until the player presses **Resume** (or completes a "do it" step, which counts as
|
|
53
|
+
resuming). Headless runs have no match to rewind, so there Back only reviews the earlier step's text.
|
|
54
|
+
- **The box never sits on what the step points at.** It takes the step's `box` placement unless that
|
|
55
|
+
hides a ring or arrow target, in which case it moves to the corner that hides the least, and it
|
|
56
|
+
moves again when a cue changes the targets. A dragged box stays put unless a target appears under it.
|
|
57
|
+
- Randomness and the bots are **scripted per step**: `step.rng` pins the values `turn.rng()` returns
|
|
58
|
+
while that step is active; `step.ai` forces the bots' moves. **A bot whose next scripted move
|
|
59
|
+
belongs to a later step waits for that step** to be on screen, so the move happens while the step
|
|
60
|
+
narrates it. It still answers the engine's own Confirm meanwhile (ending a turn the script never
|
|
61
|
+
mentions), unless that Confirm is the scripted move. Once the script runs out, the match carries on normally with the same bots.
|
|
62
|
+
- A **"do it" step that passes while it is still narrating finishes the narration** before moving
|
|
63
|
+
on (Next skips the wait).
|
|
64
|
+
|
|
65
|
+
What the engine does for you. **Do not reimplement these:**
|
|
66
|
+
|
|
67
|
+
| Situation | What the engine does |
|
|
68
|
+
|---|---|
|
|
69
|
+
| Target chit is in another panel (phone tab stack) or a zoomed panel | Switches to it, then draws (nothing is ringed while its panel is behind another) |
|
|
70
|
+
| Everything a step rings on the table sits in one panel, is under 24 px, and zooming that panel's camera cannot bring it to 40 px (the panel is too small), while full screen would grow the panel at least 1.5× — on any screen size. A board overview or anything readable in place stays in the normal layout, beside the rest of the table | Shows that panel full screen, as zooming in does (every panel becomes a tab at the bottom). Rings in another panel go back to the normal layout first, and full screen returns only if that panel needs it too (tab after tab with no context is what this avoids); a new step ringing nothing on the table leaves full screen on a bigger screen. Already full screen because the player zoomed in, it switches tabs instead of leaving |
|
|
71
|
+
| A ringed thing is still tiny (under ~28 px with the whole table shown) | Zooms its panel's camera in until it is readable (about 30% of the panel, at most 140 px, so its surroundings stay in view), and keeps that zoom while the step's later rings still show in it, and back out when the step moves on (not if the player zoomed meanwhile). Rings in a gallery do not zoom, nor a ring with `zoom: false` (which leaves the framing as it is: for rings that only flash by); `zoom: 1.6` zooms that much on a small screen whatever the size (a group of small things); the framing waits half a second, so rings that follow each other quickly (one per word) do not move it |
|
|
72
|
+
| A prompt's own strip (a toggle button's gallery that opens by itself) is up while the player only watches | Puts it away so the board gets the room; it comes back when it is the player's move or a step points into it (a gallery target, a `gallery:`/`button:` UI target, or one of its chits). A strip the player opens stays open |
|
|
73
|
+
| Narration on a phone | The next step's recording loads while a step talks; the box shows about four lines and scrolls to keep the spoken sentence in view, and stays on screen when dragged |
|
|
74
|
+
| Audio on a phone | Plays after the Start tap (the gesture browsers require) |
|
|
75
|
+
| No audio file yet | `audio: "tts"` reads the text with the browser's speech synthesis (authoring only; voices vary per device) |
|
|
76
|
+
| No audio at all | Cues run on a reading clock (3 words/second) |
|
|
77
|
+
| A pinned draw has the wrong length, or lands in a different step than declared | Warns in the console and the dev panel (throws with `strict: true`) |
|
|
78
|
+
| A forced bot move matches no legal option | Warns; the bot plays normally |
|
|
79
|
+
| Engine Confirm prompts ("confirm draw or roll", "confirm turn end") | Nothing special: point at `{ ui: "button:Confirm" }` and check the state after |
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## Before you start — make the game focus its picks
|
|
84
|
+
|
|
85
|
+
The engine brings a panel to the front on the player's turn only for picks that call `.focus()`
|
|
86
|
+
(`Chit.pick(cards, …).focus()`, `Chit.dragPick(hand, …).focus()`). A game that skips it leaves the
|
|
87
|
+
tab stack wherever the last animation put it, which on phones means the player's own panel can be
|
|
88
|
+
hidden on their turn. The tutorial's reveal is a backstop for what a step points at, not a substitute.
|
|
89
|
+
Check every pick the script will ask for:
|
|
90
|
+
|
|
91
|
+
```sh
|
|
92
|
+
grep -rn "Chit.pick\|Chit.dragPick" src/ | grep -v "\.focus("
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
## Step 1 — Decide the deal
|
|
96
|
+
|
|
97
|
+
A tutorial is written against one fixed board. Work out, in order, every random draw the game makes
|
|
98
|
+
before and during the script, and what you want each to produce:
|
|
99
|
+
|
|
100
|
+
1. The engine shuffles the seats first: one `takeRng(2 × seats)` draw. Zeros keep the order.
|
|
101
|
+
2. Then whatever `Game.run` draws before its first prompt (the deal).
|
|
102
|
+
3. Then each draw that happens while a step is active (a refill after a buy, a bot's draw…).
|
|
103
|
+
|
|
104
|
+
Find your game's draws with:
|
|
105
|
+
|
|
106
|
+
```sh
|
|
107
|
+
grep -rn "rng(\|takeRng(\|\.draw(\|\.shuffle(" src/
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Write a helper that turns "I want *this* card" into the numbers, so the script stays readable. The
|
|
111
|
+
demo's `pinDraws` does it for its deck. Pinned values are honest about their cost: if the rules or the
|
|
112
|
+
setup order change, re-tune them in the Playground (the RNG log has "copy rng" per step).
|
|
113
|
+
|
|
114
|
+
## Step 2 — Write the match block
|
|
115
|
+
|
|
116
|
+
```ts
|
|
117
|
+
match: {
|
|
118
|
+
players: [{ name: "You" }, { name: "Robin", ai: {} }, { name: "Sam", ai: {} }], // seat 0 is the person
|
|
119
|
+
options: { rounds: "3" }, // match options, like the Playground's dialog
|
|
120
|
+
rng: [[0, 0, 0, 0, 0, 0], ...SETUP_DRAWS], // seating shuffle, then the deal
|
|
121
|
+
ai: { thinkMs: [600, 1000] }, // bots: temperature 0 by default, so "normal" play is predictable
|
|
122
|
+
},
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Omit `match` entirely and you get the demo's defaults (`setupDemoGame()` seats, bots everywhere but seat 0).
|
|
126
|
+
|
|
127
|
+
The start card (before the player taps Start) shows the spec's `intro` (markdown), or the first
|
|
128
|
+
step's text when there is none. Use `intro` for a welcome line instead of a title-card step.
|
|
129
|
+
The card sits in the middle of a darkened table, and nothing on the board can be played until the
|
|
130
|
+
player taps Start (or presses → or Enter).
|
|
131
|
+
|
|
132
|
+
## Step 3 — Write the steps
|
|
133
|
+
|
|
134
|
+
```ts
|
|
135
|
+
{
|
|
136
|
+
id: "buy", // stable, unique; shows in logs and the dev panel
|
|
137
|
+
text: "**Your move.** Buy a card: tap any highlighted card you can afford.",
|
|
138
|
+
audio: narration.en.buy.url, // an imported MP3 (see "Narration files"); "tts" while authoring
|
|
139
|
+
sentenceTimes: narration.en.buy.sentenceTimes,
|
|
140
|
+
box: { anchor: "top-right" }, // or { anchor: "near", target, side }, or "keep"
|
|
141
|
+
focus: [{ ring: affordable, arrow: true, dim: true }],
|
|
142
|
+
cues: [{ at: { sentence: 1 }, focus: [...] }], // change highlights mid-narration
|
|
143
|
+
allow: { key: "market.buy" }, // the only moves accepted while waiting; "any" opens everything
|
|
144
|
+
waitFor: checks.countChanged((root, me) => me.hand, 1, "Tap one of the highlighted cards."),
|
|
145
|
+
hint: { after: 6, text: "…" }, // shown if the check hasn't passed after 6 s
|
|
146
|
+
pause: true, // wait for Next after the narration (default: move on by itself)
|
|
147
|
+
pauseAi: true, // bots hold their prompts during this step
|
|
148
|
+
rng: [[0.5, 0.5]], // draws made while this step is active
|
|
149
|
+
ai: { p1: [{ key: "market.buy", chit: affordable }] }, // forced bot moves while active
|
|
150
|
+
},
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Rules of thumb:
|
|
154
|
+
|
|
155
|
+
- **One action per "do it" step.** If the engine will ask for a Confirm afterwards, make that its own
|
|
156
|
+
step with an arrow at `{ ui: "button:Confirm" }` and `allow: { button: "Confirm" }`.
|
|
157
|
+
- **Every "do it" step needs `allow`.** It is matched like a forced bot move: `key`, `chit`,
|
|
158
|
+
`target`, `button`, or `"any"`; `allow: []` says the step waits for the bots, not the player. The
|
|
159
|
+
dev panel flags a waiting step without one, and `runTutorial` warns and then gets stuck on it.
|
|
160
|
+
- **Check state, not events.** `checks.state((root) => root.market.cards.length === 4)` passes
|
|
161
|
+
whether the player confirmed just now or a second before the step started.
|
|
162
|
+
`checks.logged(...)` only sees log lines written *during* the step.
|
|
163
|
+
- **Narrate what the bots do only when you force it.** A step that says "Robin buys a card" has
|
|
164
|
+
`ai: { p1: [{ key: "market.buy", … }] }` on it and `waitFor: checks.promptFor("me")` so the
|
|
165
|
+
tutorial waits for the bots to finish.
|
|
166
|
+
- **Pause the bots while you talk** (`pauseAi: true`) when the next thing the bots do would change
|
|
167
|
+
what the step is pointing at.
|
|
168
|
+
- **Highlight as many regions as the step needs.** `focus` is a list; each entry has its own ring
|
|
169
|
+
and arrow (`[{ ring: hand }, { ring: tableau, arrow: true }]`). A ring around several chits is one
|
|
170
|
+
box around all of them; add `separate: true` to ring each one on its own. `dim` keeps every ring
|
|
171
|
+
and arrow target of the step lit; the dim fades in and out, and stays 0.4 s through a gap with nothing ringed
|
|
172
|
+
(a tab sliding, a sentence with no ring) so it does not blink.
|
|
173
|
+
- **Point at parts of a chit** with `{ chit, offset: { y: 0.3 } }` (bbox units, half-extent 0.5, +y
|
|
174
|
+
toward the top of the chit) and `scale: { y: 0.3 }` to ring a band of it.
|
|
175
|
+
- **UI targets:** `button:<Label>`, `undo`, `log`, `time`, `players`, `prompt`,
|
|
176
|
+
`spark:<chitId>` (a counter, use `(root, me) => \`spark:${me.coins.id}\``), `panelTab:<chitId>`,
|
|
177
|
+
and the gallery ones below. Any component can expose more with a `data-tutorial-target` attribute.
|
|
178
|
+
- **Last step** has `end: "continue"` (keep playing) or `"back"`.
|
|
179
|
+
|
|
180
|
+
### Galleries
|
|
181
|
+
|
|
182
|
+
Some actions only happen in a gallery (a hand shown as a strip, a toggle button's cards), so a
|
|
183
|
+
tutorial can point into galleries, open and close them, and wait for the player to open one. The
|
|
184
|
+
demo's `market-button`, `gallery-tour` and `buy` steps use all of it.
|
|
185
|
+
|
|
186
|
+
- **Rings and arrows reach gallery items.** A chit selector finds the chit in an open gallery first
|
|
187
|
+
(full-screen, then inline), then on the table, so `ring: (root, me) => me.hand.tryGet(0)` circles
|
|
188
|
+
the card where the player can tap it. An item scrolled out of the gallery's view is scrolled in.
|
|
189
|
+
`offset`, `scale`, `separate` and `dim` work the same. Identical chits merged into one "2x" item
|
|
190
|
+
resolve to that item.
|
|
191
|
+
- **The gallery controls are UI targets:**
|
|
192
|
+
|
|
193
|
+
| Target | What it is |
|
|
194
|
+
|---|---|
|
|
195
|
+
| `button:<Label>` | the show/hide toggle in the bottom bar (a `ToggleGalleryButton`, e.g. `button:Hand`) |
|
|
196
|
+
| `gallery:toFullscreen` | the inline gallery's "full screen" button |
|
|
197
|
+
| `gallery:toInline` | the full-screen gallery's "back to inline" button |
|
|
198
|
+
| `gallery:modeButton` | whichever of those two is showing |
|
|
199
|
+
| `gallery:inline` / `gallery:fullscreen` | the gallery itself, to ring the whole strip or screen |
|
|
200
|
+
| `gallery:context` | the small context gallery in the prompt bar |
|
|
201
|
+
|
|
202
|
+
- **The script can open, switch and close galleries** with `gallery` on a step or a cue:
|
|
203
|
+
`{ of: (root, me) => me.hand }` shows a container's children (like tapping it),
|
|
204
|
+
`{ items: (root) => root.market.cards }` shows exactly those chits, `{ mode: "fullscreen" }` moves
|
|
205
|
+
the open gallery to full screen (or `"inline"`), and `"close"` closes it. `mode` defaults to the
|
|
206
|
+
player's own inline/full-screen choice. A gallery the script opened stays until a step or cue
|
|
207
|
+
changes it; Back closes it.
|
|
208
|
+
- **Waiting for the player to open one:** `waitFor: checks.galleryOpen({ of: hand })` (or
|
|
209
|
+
`{ mode: "fullscreen" }`; `checks.galleryClosed()` for the reverse), with
|
|
210
|
+
`allow: { ui: "button:Hand" }` to say the step waits for the player to use a control rather than
|
|
211
|
+
make a game move. Gallery buttons are never blocked by the guard; taps on gallery items that make
|
|
212
|
+
a move go through `allow` like any other move. Tapping that control during an earlier narration
|
|
213
|
+
step acts ahead, as above.
|
|
214
|
+
- **Headless:** `runTutorial` has no buttons, so a step that waits for the player to open a gallery
|
|
215
|
+
needs `ui: (step, ui) => step.id === "open-hand" && ui.gallery({ of: (root, me) => me.hand })`.
|
|
216
|
+
|
|
217
|
+
### Poses: changing how chits look
|
|
218
|
+
|
|
219
|
+
A pose sets properties on the **player's own copy** of a chit, and the engine renders and animates
|
|
220
|
+
the change as it would any other: a card flips over, a token turns. The match never hears of it, so
|
|
221
|
+
rules, checks, bots and the history are untouched. Put `pose` on a step (from its start) or on a cue
|
|
222
|
+
(from that point of the narration):
|
|
223
|
+
|
|
224
|
+
```ts
|
|
225
|
+
{
|
|
226
|
+
id: "welcome",
|
|
227
|
+
// the market starts face down...
|
|
228
|
+
pose: [{ chit: (root) => root.table.market.cards, set: { faceDown: true } }],
|
|
229
|
+
cues: [
|
|
230
|
+
// ...and turns over as the narration reaches it: no `set` puts the chit back as the game has it
|
|
231
|
+
{ at: { sentence: 3 }, pose: [{ chit: (root) => root.table.market.cards }] },
|
|
232
|
+
],
|
|
233
|
+
}
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
- **`set`** is an object of properties or a function `(chit) => { ... }`. Its effect is whatever the
|
|
237
|
+
chit's `render` does with those properties, so the game needs a property that drives the look you
|
|
238
|
+
want (Petty Market's `Card.faceDown` turns the card with `spec.rotateY = Math.PI`).
|
|
239
|
+
- **How long it lasts:** until the step ends, unless the pose sets `keep: true`; then until a later
|
|
240
|
+
pose of that chit or the end of the tutorial. Back puts every pose back, and the step it lands on
|
|
241
|
+
poses its own again. A step that poses the same chit as the step before keeps it posed without a
|
|
242
|
+
flicker.
|
|
243
|
+
- **The game wins.** If the match changes a posed chit, the client loads the new state over the pose.
|
|
244
|
+
- **Only properties come back.** Don't move chits between parents with a pose.
|
|
245
|
+
- **It can only show what the client knows.** A property the server hides from this player (a
|
|
246
|
+
face-down card's face) is not on the client, so a pose cannot reveal it.
|
|
247
|
+
- `runTutorial` ignores poses: they are looks, not state.
|
|
248
|
+
|
|
249
|
+
### Holding the board's timeline
|
|
250
|
+
|
|
251
|
+
The board plays the game's moments (clocks) one after another, animating each. `timeline` on a step
|
|
252
|
+
or cue holds it on a moment so the narration can talk about what just moved, while the game itself
|
|
253
|
+
carries on behind it. It changes only this player's view.
|
|
254
|
+
|
|
255
|
+
```ts
|
|
256
|
+
{
|
|
257
|
+
id: "robin",
|
|
258
|
+
// play Robin's buy and the market refill, then hold there...
|
|
259
|
+
timeline: { until: checks.logged(/A new card joins the market/) },
|
|
260
|
+
// ...and play on (Sam's pass, then the player's prompt) at the next sentence
|
|
261
|
+
cues: [{ at: { sentence: 1 }, timeline: "play" }],
|
|
262
|
+
}
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
- `"hold"` stops at the moment on screen. `{ advance: n }` plays `n` more moments, then stops.
|
|
266
|
+
`{ until: check }` plays on until a moment where the check passes (its `recentLog` counts from the
|
|
267
|
+
command). `"play"` catches up with the game and follows it again.
|
|
268
|
+
- A hold lasts until a later command, Back, or the end of the tutorial. The Skip/Live and Forward
|
|
269
|
+
buttons stop at it too.
|
|
270
|
+
- Release the board before a step that needs it: the player's prompt and most `waitFor` checks only
|
|
271
|
+
show up once the board reaches them. A "do it" step entered while the board is held warns in the
|
|
272
|
+
console unless it sets `timeline` itself.
|
|
273
|
+
- A play-through from the workbench ignores holds until it lands.
|
|
274
|
+
|
|
275
|
+
### Narration files
|
|
276
|
+
|
|
277
|
+
Ship recordings, not browser speech: an MP3 per step plus `sentenceTimes` (start of each sentence,
|
|
278
|
+
in seconds) so sentence cues and the emphasis are exact. Split text with the exported
|
|
279
|
+
`splitSentences` in your narration tooling, so its sentence count always matches the cues'. The demo generates its files with the
|
|
280
|
+
machine's text-to-speech so the pipeline is real end to end: `yarn demo:audio` renders every sentence
|
|
281
|
+
of every step with macOS `say`, measures each clip, concatenates them, and writes
|
|
282
|
+
`src/demo/market/audio/<locale>/<step>.mp3` and a generated `index.ts` with the imports and timings
|
|
283
|
+
(see `src/demo/market/audio/generate.mjs`). Swap any MP3 for a studio recording and re-run with
|
|
284
|
+
`--timings-only`, or use the workbench's sentence-timing recorder for a file whose sentences you cannot
|
|
285
|
+
measure. Audio files are bundled as assets (`*.mp3` imports resolve to URLs), so `audio` can be an
|
|
286
|
+
imported file or any URL the host serves.
|
|
287
|
+
|
|
288
|
+
Players can speed narration up (1×, 1.25×, 1.5×, 2×; remembered per device). `sentenceTimes` and
|
|
289
|
+
`at` cues are always in the recording's own seconds, so nothing in the script changes with speed.
|
|
290
|
+
|
|
291
|
+
### Text in the box
|
|
292
|
+
|
|
293
|
+
Markdown: paragraphs, **bold**, lists, headings, links, block quotes, images. `:token:` references
|
|
294
|
+
render with the same icons and player avatars as the action log. `` shows a token's
|
|
295
|
+
art at image size; a URL shows a file from the bundle. Sentence cues (`{ sentence: n }`) and the
|
|
296
|
+
narration emphasis count sentences across the whole text in document order.
|
|
297
|
+
|
|
298
|
+
### Localisation
|
|
299
|
+
|
|
300
|
+
Keep one script skeleton and one strings file per locale. The demo keeps each locale's step texts,
|
|
301
|
+
hints, title and voice in `src/demo/market/audio/strings.<locale>.json`; `intro(strings)` in
|
|
302
|
+
`tutorial.ts` builds the same steps from any of them, and `yarn demo:audio` renders each locale's
|
|
303
|
+
narration with that file's voice. Sentence cue indices survive translation as long as translators
|
|
304
|
+
keep sentence counts; `at` seconds need per-locale values when the audio differs. A host picks a
|
|
305
|
+
locale with `findTutorial(game, id, locale)` (exact match, then same language, then the first one).
|
|
306
|
+
|
|
307
|
+
### Colours and type
|
|
308
|
+
|
|
309
|
+
The overlay derives its colours from the game's `GameTheme` (highlight colour, bar colours, font).
|
|
310
|
+
Override any of them, from broadest to narrowest; later layers win:
|
|
311
|
+
|
|
312
|
+
```ts
|
|
313
|
+
theme.tutorial = { accent: "#ffcc66", arrowColor: "#ffffff" }; // the game's default (GameTheme)
|
|
314
|
+
defineTutorial({ ..., theme: { highlightColor: "#9cf" } }); // one tutorial
|
|
315
|
+
<DemoWrapper game={game} tutorial="intro" tutorialTheme={{ boxBackground: "#102030ee" }} /> // one host
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
Fields (`TutorialTheme`): `boxBackground`, `boxTextColor`, `accent` (buttons, progress, the sentence
|
|
319
|
+
being read), `boxShadow`, `borderRadius`, `arrowColor`, `highlightColor`, `highlightGlow`,
|
|
320
|
+
`dimColor`, `dimOpacity` (the spotlight), `fontFamily`, `fontScalar`, `boxWidth`.
|
|
321
|
+
|
|
322
|
+
## Step 4 — Wire it into the game
|
|
323
|
+
|
|
324
|
+
```ts
|
|
325
|
+
import { marketTutorials } from "./tutorial";
|
|
326
|
+
export class MyGame implements Game<Player, Root> {
|
|
327
|
+
// ...
|
|
328
|
+
tutorials = marketTutorials;
|
|
329
|
+
}
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
## Step 5 — Test it
|
|
333
|
+
|
|
334
|
+
```ts
|
|
335
|
+
test("intro can be completed", async () => {
|
|
336
|
+
const result = await runTutorial(new MyGame(), intro, {
|
|
337
|
+
// Optional: by default the player takes the first move the step's `allow` accepts
|
|
338
|
+
answer: (step, options) => {
|
|
339
|
+
if (step?.id === "buy") return options.findIndex((o) => o.option.key === "market.buy");
|
|
340
|
+
return undefined;
|
|
341
|
+
},
|
|
342
|
+
});
|
|
343
|
+
expect(result.outcome).toBe("completed");
|
|
344
|
+
expect(result.warnings).toEqual([]); // every pinned draw/move landed in the step that declared it
|
|
345
|
+
});
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
`runTutorial` plays the person's seat with a stand-in that answers only while a "do it" step is
|
|
349
|
+
waiting, and only with a move that step's `allow` accepts. That includes the engine's own Confirm
|
|
350
|
+
prompts, so a step that forgets `allow: { button: "Confirm" }` gets stuck in the test just as it
|
|
351
|
+
would for a player. Every other prompt it holds. The stand-in is not one of the bots, so `pauseAi`
|
|
352
|
+
never pauses it and resuming the bots never lets it act during narration. The run fails with the
|
|
353
|
+
step id when a step can never be completed, which is what a rules change that breaks the script
|
|
354
|
+
looks like.
|
|
355
|
+
|
|
356
|
+
## Step 6 — Watch it in the Playground
|
|
357
|
+
|
|
358
|
+
Demo tab → pick the tutorial → the workbench on the right shows the steps (click to jump), the live
|
|
359
|
+
check result and hint, the RNG log with step attribution and "copy rng", the bot decisions, warnings,
|
|
360
|
+
a sentence-timing recorder (space while the narration plays, then copy `sentenceTimes`), and toggles
|
|
361
|
+
for muting and showing target rects. "Open full screen" gives a phone-sized check at
|
|
362
|
+
`/demo?tutorial=<id>&locale=<locale>`.
|
|
363
|
+
|
|
364
|
+
Keyboard, anywhere a tutorial runs: **→** next step, **←** previous step, **Space** play/pause. On a
|
|
365
|
+
step waiting for the player's move, → makes the move for them: the first entry of the step's `allow`
|
|
366
|
+
(in the order written) that the prompt can take, or the UI control an entry names. It goes through the
|
|
367
|
+
same guard as a tap, so the game sees an ordinary move. Pressing → over and over plays the whole
|
|
368
|
+
tutorial. While the sentence recorder is on, Space marks a sentence instead.
|
|
369
|
+
|
|
370
|
+
In the workbench, clicking a later step **plays through to it**: narration skipped, animations
|
|
371
|
+
rushed, the player's moves made the same way, the bots playing as scripted. It waits for the board
|
|
372
|
+
to settle before each step, and the step it lands on plays as usual. Alt-click jumps without
|
|
373
|
+
playing. Back, Pause or another jump stops a play-through, and one stuck on a step for 20 s gives up
|
|
374
|
+
there. The status line shows the board's clock (for counting `{ advance: n }`) and any hold.
|
|
375
|
+
|
|
376
|
+
## Starting a tutorial from a host
|
|
377
|
+
|
|
378
|
+
A tutorial is a demo with a script, so a host starts it the way it starts a demo:
|
|
379
|
+
|
|
380
|
+
```tsx
|
|
381
|
+
import { DemoWrapper, listTutorials } from "@pretty-chitty/core";
|
|
382
|
+
|
|
383
|
+
listTutorials(game); // [{ id: "intro", locale: "en", title: "How to play", requires: [], steps: 11 }, …]
|
|
384
|
+
|
|
385
|
+
<DemoWrapper
|
|
386
|
+
game={game}
|
|
387
|
+
tutorial="intro" // an id (or a spec); omit it for a plain demo
|
|
388
|
+
locale="es" // picks the matching translation
|
|
389
|
+
tutorialTheme={{ … }} // optional colour overrides
|
|
390
|
+
onTutorialEvent={(e) => …} // "started" | "step" | "satisfied" | "completed" | "skipped"
|
|
391
|
+
onBack={() => …} // the back button, and where `end: "back"` goes
|
|
392
|
+
/>
|
|
393
|
+
```
|
|
394
|
+
|
|
395
|
+
The match is in-process and ephemeral: a reload starts the tutorial again. When the last step's
|
|
396
|
+
Finish is pressed (or the player skips), the box goes away and the same match carries on as a normal
|
|
397
|
+
game against the same bots.
|
|
398
|
+
|
|
399
|
+
---
|
|
400
|
+
|
|
401
|
+
## Checklist before you're done
|
|
402
|
+
|
|
403
|
+
- [ ] Every pick the script asks for calls `.focus()`.
|
|
404
|
+
- [ ] Every step has a unique `id` and a `text`.
|
|
405
|
+
- [ ] Every "do it" step's `waitFor` is state-based, has a `hint`, and lists what it `allow`s.
|
|
406
|
+
- [ ] Every move that only happens in a gallery has a step that opens it (or asks the player to) first.
|
|
407
|
+
- [ ] Every draw the script depends on is pinned on the step it happens in; `runTutorial` reports no warnings.
|
|
408
|
+
- [ ] Bot moves the narration mentions are forced on that step.
|
|
409
|
+
- [ ] The last step has `end`.
|
|
410
|
+
- [ ] A locale table exists per language the game ships, and `Game.tutorials` lists them all.
|
|
411
|
+
- [ ] The test passes and the script was watched once on a phone-sized screen.
|