zwitschi
f4a53e2d4f
Write the eight-beat tutorial sheet, its safe visitor script, persistence and replay rules. Add a deterministic, skippable/restartable Tutorial RefCounted state machine with headless tests. UI/GameManager wiring remains the next task. Headless 235/235, Python 94/94.
46 lines
3.0 KiB
Markdown
46 lines
3.0 KiB
Markdown
# First-shift tutorial
|
|
|
|
Status: planned for v0.8.0. The tutorial teaches the real controls and the real
|
|
inspection/wheel/radio panels; it is not a fake UI or a separate combat mode.
|
|
|
|
## Rules
|
|
|
|
- One short, safe, compliant visitor. No emergency, threat, crowd panic or random
|
|
event can interrupt the tutorial.
|
|
- Prompts advance on the performed action, not on a timer. The player can keep
|
|
moving/looking while a prompt is visible.
|
|
- The tutorial is skippable at any point. Completion and skip are both persisted
|
|
separately; a skipped tutorial can be replayed from Help/Settings.
|
|
- The tutorial state machine is independent of the shift FSM. It observes the
|
|
same actions as normal play and must be deterministic for tests.
|
|
|
|
## Beat sheet
|
|
|
|
| # | Beat | Prompt | Advances when | Notes |
|
|
| --- | --- | --- | --- | --- |
|
|
| 1 | Arrive | "Walk forward and look around. The entrance is behind you." | The guard has moved at least 1 m and looked away/returned | Start at the normal guard post, facing the street. |
|
|
| 2 | Focus | "Look at the visitor. Press Tab or the mouse wheel to cycle targets." | A target is acquired and explicitly cycled | The visitor waits at the foot of the steps; no other guest is required. |
|
|
| 3 | Wheel | "Open the action wheel with Space or left click." | The radial wheel opens on the visitor | The wheel is the real de-escalation-first wheel. |
|
|
| 4 | Inspect | "Choose Inspect and read the access evidence." | The inspection panel is opened and the policy result is visible | Use a valid wristband so the tutorial can teach both evidence and a safe admit/deny decision. |
|
|
| 5 | Direction | "Close the panel and give a polite direction." | A Level 1 polite-direction action is applied | The visitor complies; there is no escalation requirement. |
|
|
| 6 | Warning | "Give a formal warning if the visitor persists. It arms the body camera." | A Level 2 warning is applied or the body camera is switched on | Show the REC overlay and the escalation cue. |
|
|
| 7 | Radio | "Open the assistance radio and submit a short report." | The assistance report is submitted successfully | A non-emergency assistance call; no responder is required to resolve the tutorial. |
|
|
| 8 | Review | "Finish the shift and review what happened." | The shift review opens | The tutorial ends; the real review remains available for inspection. |
|
|
|
|
## Visitor script
|
|
|
|
- Display name: `Visitor`.
|
|
- Intent: `enter` (approaches the door, then waits for interaction).
|
|
- Access: valid wristband evidence; the policy result should be unambiguous.
|
|
- Behavior: compliant at every escalation level; never becomes a threat, never
|
|
joins a crowd and never triggers an emergency.
|
|
- Failure handling: if the player denies admission incorrectly, the tutorial
|
|
explains the evidence but does not fail the run; the visitor remains safe and
|
|
the review records the decision.
|
|
|
|
## Persistence and replay
|
|
|
|
Settings gain `tutorial_completed` and `tutorial_skipped`. A first launch starts
|
|
the tutorial after venue selection. Skipping sets `tutorial_skipped`; Settings/
|
|
Help offers "Replay tutorial", which clears both flags for the next shift.
|