mancala/docs/specs/tutorial/requirements.md

# Tutorial: requirements

Status: implemented on branch `feature/tutorial` (based on `develop`).
Scope: `packages/core`, web app; the mobile app gets the rules only (see R5).

## Goals

Someone who has never played Mangala can learn it in a few minutes, and anyone can look a rule up later, also in
the middle of a game. Three parts, from reading to playing:

1. **Rules**: one page with every rule, a short text and a small board for each. Always reachable.
2. **Lessons**: one short interactive step per rule; the player makes the move the rule is about on a prepared
   board and sees what happens. Runs in the browser, without the server.
3. **Practice game**: a real game against the Easy bot with hints: which moves give an extra turn or capture, and
   after every move a sentence about what happened.

## Terms

- **Store**: the large pit on each side (in the texts "hazine"); stones in it count for the player.
- **Lesson**: one rule taught on a prepared position with a task, e.g. "End your move in your store".
- **Hint**: in the practice game, the effect a move would have right away (extra turn, capture, stones to store).
  Hints never look further ahead than the move itself.
- **Newcomer**: someone on a device where no game has been played and the tutorial has not been opened or
  dismissed.

## Requirements

### R1. Rules
- R1.1 A rules page ("How to play" / "Nasıl oynanır") lists, in order: the board and the goal, sowing, the extra
  turn, capturing an even pit, capturing from an empty pit, the end of the game and who wins, and the clock.
- R1.2 Each rule has at most three sentences and a small board that shows it (before and after the move).
- R1.3 The texts describe exactly what the game does (`packages/mancala.js` and the backend's port), including the
  details beginners miss: the first stone goes back into the pit it was taken from, a single stone moves to the next
  pit, the opponent's store is skipped.
- R1.4 The rules can be reached from the header on every page, and from the game page without leaving the game
  (a panel over the game; the game and its clock go on).
- R1.5 Each rule links to its lesson.

### R2. Lessons
- R2.1 There is a lesson for each rule in R1.1 except the clock: six in all, in the order of R1.1.
- R2.2 A lesson shows the rule's text, a board with a prepared position and a task. The player plays on the real
  board (same look, animation and move preview as a game).
- R2.3 A move that fulfils the task is praised and the next lesson is offered. Any other move is animated, then
  explained ("This move ended in the opponent's pit, so the turn passed") and the position is set back so they can
  try again.
- R2.4 Where a lesson needs the opponent to move, the opponent's move is scripted and shown like the bot's.
- R2.5 Lessons work without a connection to the server and need no login.
- R2.6 Completed lessons are remembered on the device and marked in the list. Lessons can be taken in any order
  and repeated.
- R2.7 After the last lesson, the player is offered the practice game.

### R3. Practice game
- R3.1 The practice game is a game against the Easy bot with hints turned on, started from the tutorial. It is
  otherwise a normal bot game (clock, saving, history).
- R3.2 While it is the player's turn, every pit whose move gives an extra turn or captures is marked, with what it
  does ("Extra turn", "Captures 5").
- R3.3 After every move, of either side, one sentence says what happened, built from the move: e.g. "The bot's
  last stone landed in its store: it plays again" or "You captured 6 stones from an even pit".
- R3.4 Hints can be turned on and off in every game against the bot; the choice is remembered on the device.
- R3.5 Hints are only available in games against the bot. Games between people never show them, also not to
  spectators.

### R4. Newcomers
- R4.1 A newcomer sees a banner on the home page: "New to Mangala? Learn it in 3 minutes" with "Start" and
  "Not now". "Not now" hides it for good on that device.
- R4.2 The banner does not show once the tutorial has been opened or a game has been played on the device.
- R4.3 Nothing is forced: a newcomer can start a game without the tutorial.

### R5. Mobile app
- R5.1 The mobile app shows the same rules (same texts, from `packages/core`) on a rules screen reachable from the
  help screen and from the game screen's header.
- R5.2 Lessons and the practice game's hints on mobile are out of scope until the mobile app gets the new design
  (`TODO.md`, Web redesign).

### R6. Languages
- R6.1 All texts exist in English and Turkish. Turkish uses the usual Mangala words (kuyu, hazine, taş).

## Out of scope (TODO)
- Lessons and hints in the mobile app (R5.2).
- Hints that look ahead (warning about a move that gives the opponent a capture); the bot's search could provide
  them later.
- Strategy lessons beyond the rules.
- Keeping tutorial progress per account instead of per device.