> ## Documentation Index
> Fetch the complete documentation index at: https://docs.awokenlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory

> Twelve recall and observation minigames - watch something, then remember it.

Twelve games built around memorising something before it disappears. Defaults live in `config/games/memory.lua`.

<Info>
  Set an option once in `config/games/memory.lua` to apply it server-wide, or pass it in a single call to change it just that once. Every game also accepts [shared options](/resources/awoken-minigames/configuration/overview#shared-options) like `canCancel`, `title` and `theme`.
</Info>

***

## Simon Says

Watch the grid flash tiles one by one, then click them back in the same order. Each round adds one more tile.

**Export:** `exports['awoken_minigames']:SimonSays(opts)` - returns `true` only on a win.

| Option            | Default | Notes                                                                                                                                                                                                         |
| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gridSize`        | `4`     | NxN grid (`3`-`8`).                                                                                                                                                                                           |
| `rounds`          | `5`     | Max sequence length; each round adds one tile.                                                                                                                                                                |
| `stages`          | *(1)*   | Run several back-to-back: an integer repeats this config N times, or an array of per-stage overrides (max 10). See [Multi-stage games](/resources/awoken-minigames/configuration/overview#multi-stage-games). |
| `canCancel`       | `true`  |                                                                                                                                                                                                               |
| `autoStart`       | `false` | Shows a "press to start" gate. `true` starts immediately.                                                                                                                                                     |
| `mistakesAllowed` | `0`     | Wrong clicks tolerated per stage (`0` = strict).                                                                                                                                                              |

```lua Presets theme={"dark"}
-- Tutorial
exports['awoken_minigames']:SimonSays({ gridSize = 3, rounds = 3 })
-- (defaults)
exports['awoken_minigames']:SimonSays({})
-- Hard
exports['awoken_minigames']:SimonSays({ gridSize = 5, rounds = 6 })
-- Expert
exports['awoken_minigames']:SimonSays({ gridSize = 6, rounds = 8 })
-- Forgiving
exports['awoken_minigames']:SimonSays({ gridSize = 5, rounds = 6, mistakesAllowed = 2 })
```

***

## Memory

Some tiles light up at once, then hide. Click the ones that were lit - order doesn't matter.

**Export:** `exports['awoken_minigames']:Memory(opts)` - returns `true` only on a win.

| Option            | Default | Notes                                                                                                                                                                                                         |
| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gridSize`        | `4`     | NxN grid (`3`-`8`).                                                                                                                                                                                           |
| `patternSize`     | `5`     | Tiles lit in the pattern (never more than the grid can hold).                                                                                                                                                 |
| `memorizeTime`    | `2000`  | Ms the pattern stays visible.                                                                                                                                                                                 |
| `stages`          | *(1)*   | Run several back-to-back: an integer repeats this config N times, or an array of per-stage overrides (max 10). See [Multi-stage games](/resources/awoken-minigames/configuration/overview#multi-stage-games). |
| `canCancel`       | `true`  |                                                                                                                                                                                                               |
| `autoStart`       | `false` | Shows a "press to start" gate. `true` starts immediately.                                                                                                                                                     |
| `mistakesAllowed` | `0`     | Wrong clicks tolerated per stage (`0` = strict).                                                                                                                                                              |

```lua Presets theme={"dark"}
-- Tutorial
exports['awoken_minigames']:Memory({ gridSize = 3, patternSize = 3, memorizeTime = 3000 })
-- (defaults)
exports['awoken_minigames']:Memory({})
-- Hard
exports['awoken_minigames']:Memory({ gridSize = 5, patternSize = 7, memorizeTime = 1800 })
-- Expert
exports['awoken_minigames']:Memory({ gridSize = 6, patternSize = 9, memorizeTime = 1500 })
-- Forgiving
exports['awoken_minigames']:Memory({ gridSize = 5, patternSize = 7, mistakesAllowed = 3 })
```

<Tip>
  For a harder game, raise `patternSize` and lower `memorizeTime` together. A bigger grid on its own is actually easier, since the same lit tiles are spread over more space.
</Tip>

***

## Memory Colors

A grid of coloured cells flashes, then hides. Before the timer runs out, pick how many cells were the colour you're asked about.

**Export:** `exports['awoken_minigames']:MemoryColors(opts)` - returns `true` only on a win.

| Option            | Default | Notes                                                            |
| ----------------- | ------- | ---------------------------------------------------------------- |
| `gridSize`        | `5`     | Board is gridSize x gridSize (`3`-`8`).                          |
| `memorizeTime`    | `5000`  | Ms the colours stay visible.                                     |
| `answerTime`      | `10000` | Ms to answer each round.                                         |
| `rounds`          | `3`     | Rounds to clear to win (`1`-`20`).                               |
| `mistakesAllowed` | `0`     | Wrong/late answers tolerated (retries).                          |
| `canCancel`       | `true`  |                                                                  |
| `autoStart`       | `true`  | Starts immediately. `false` shows a "press to start" gate first. |

```lua Presets theme={"dark"}
-- Tutorial
exports['awoken_minigames']:MemoryColors({ gridSize = 4, memorizeTime = 6000, answerTime = 12000, rounds = 2, mistakesAllowed = 2 })
-- Standard
exports['awoken_minigames']:MemoryColors({ memorizeTime = 4000, answerTime = 9000 })
-- Hard
exports['awoken_minigames']:MemoryColors({ gridSize = 6, memorizeTime = 3000, answerTime = 8000, rounds = 4 })
-- Expert
exports['awoken_minigames']:MemoryColors({ gridSize = 7, memorizeTime = 2500, answerTime = 7000, rounds = 5 })
-- Forgiving
exports['awoken_minigames']:MemoryColors({ gridSize = 6, memorizeTime = 4000, answerTime = 12000, rounds = 4, mistakesAllowed = 3 })
```

***

## Verbal Memory

A word flashes up - say whether you've SEEN it before or it's NEW. Reach the target number of correct calls before you run out of strikes.

**Export:** `exports['awoken_minigames']:VerbalMemory(opts)` - returns `true` only on a win.

| Option         | Default                                   | Notes                                                            |
| -------------- | ----------------------------------------- | ---------------------------------------------------------------- |
| `maxStrikes`   | `3`                                       | Strikes tolerated before failing (`>= 1`).                       |
| `wordsToShow`  | `50`                                      | Words you must survive to win. Capped to the size of `words`.    |
| `wordDuration` | `5000`                                    | Ms allowed per word before it strikes.                           |
| `words`        | *(the list in `config/games/memory.lua`)* | The word pool. Upper-cased and de-duplicated on load.            |
| `canCancel`    | `true`                                    |                                                                  |
| `autoStart`    | `true`                                    | Starts immediately. `false` shows a "press to start" gate first. |

```lua Presets theme={"dark"}
-- Tutorial
exports['awoken_minigames']:VerbalMemory({ maxStrikes = 5, wordsToShow = 10, wordDuration = 7000 })
-- Standard
exports['awoken_minigames']:VerbalMemory({ wordsToShow = 30 })
-- Hard
exports['awoken_minigames']:VerbalMemory({ maxStrikes = 2, wordsToShow = 40, wordDuration = 3500 })
-- Your own word pool
exports['awoken_minigames']:VerbalMemory({ words = { 'OXY', 'CASH', 'BURNER', 'PLATES' }, wordsToShow = 4 })
```

### The word pool

The 160 words live in `config/games/memory.lua` - **add, remove or translate them freely**. Entries are upper-cased and de-duplicated on load, so case and accidental repeats are fine.

```lua config/games/memory.lua theme={"dark"}
AwokenMinigamesConfig.verbalMemory = {
    wordsToShow = 50,
    words = {
        'APPLE', 'HOUSE', 'WATER', 'LIGHT', 'PAPER',
        -- ...add your own here
    },
}
```

<Warning>
  Keep the pool bigger than `wordsToShow`, or the game runs out of fresh words and gets too easy. The 160 words that ship cover the default of 50 comfortably.
</Warning>

<Tip>
  `wordsToShow = 50` is a long round - drop it to `20`-`30` for anything players do often.
</Tip>

***

## Numbered Sequence

Numbers appear briefly on random grid cells, then hide. Click the cells in order from lowest number to highest, from memory.

**Export:** `exports['awoken_minigames']:NumberedSequence(opts)` - returns `true` only on a win.

| Option            | Default | Notes                                                            |
| ----------------- | ------- | ---------------------------------------------------------------- |
| `gridSize`        | `4`     | NxN grid (`3`-`8`).                                              |
| `sequenceLength`  | `6`     | Numbers placed (never more than the grid can hold).              |
| `rounds`          | `3`     | Rounds to clear (`1`-`10`).                                      |
| `showTime`        | `4000`  | Ms the numbers stay visible (`>= 500`).                          |
| `guessTime`       | `10000` | Ms to recall the sequence (`>= 1000`).                           |
| `mistakesAllowed` | `2`     | Wrong presses tolerated per round.                               |
| `canCancel`       | `true`  |                                                                  |
| `autoStart`       | `true`  | Starts immediately. `false` shows a "press to start" gate first. |

```lua Presets theme={"dark"}
-- Tutorial
exports['awoken_minigames']:NumberedSequence({ sequenceLength = 4, rounds = 1, showTime = 5000, guessTime = 12000, mistakesAllowed = 3 })
-- (defaults)
exports['awoken_minigames']:NumberedSequence({})
-- Hard
exports['awoken_minigames']:NumberedSequence({ gridSize = 5, sequenceLength = 8, showTime = 3500, guessTime = 9000, mistakesAllowed = 1 })
-- Expert
exports['awoken_minigames']:NumberedSequence({ gridSize = 6, sequenceLength = 10, rounds = 4, showTime = 3000, guessTime = 8000, mistakesAllowed = 0 })
-- Max
exports['awoken_minigames']:NumberedSequence({ gridSize = 8, sequenceLength = 12, showTime = 3500, guessTime = 11000, mistakesAllowed = 1 })
```

***

## Var Hack

Numbered blocks drift around and flash their number, then go blank. Click them in order from lowest to highest before the countdown runs out.

**Export:** `exports['awoken_minigames']:VarHack(opts)` - returns `true` only on a win.

| Option            | Default | Notes                                                            |
| ----------------- | ------- | ---------------------------------------------------------------- |
| `blocks`          | `5`     | Drifting variable blocks (`2`-`12`).                             |
| `speed`           | `20`    | Solve countdown, seconds (`3`-`120`).                            |
| `memorizeTime`    | `4000`  | Ms the indices stay visible (`1000`-`15000`).                    |
| `mistakesAllowed` | `0`     | Wrong clicks tolerated before fail.                              |
| `canCancel`       | `true`  |                                                                  |
| `autoStart`       | `true`  | Starts immediately. `false` shows a "press to start" gate first. |

```lua Presets theme={"dark"}
-- Tutorial
exports['awoken_minigames']:VarHack({ blocks = 3, speed = 25, memorizeTime = 6000, mistakesAllowed = 2 })
-- (defaults)
exports['awoken_minigames']:VarHack({})
-- Hard
exports['awoken_minigames']:VarHack({ blocks = 7, speed = 16, memorizeTime = 3500 })
-- Expert
exports['awoken_minigames']:VarHack({ blocks = 9, speed = 14, memorizeTime = 3000 })
-- Forgiving
exports['awoken_minigames']:VarHack({ blocks = 6, speed = 30, memorizeTime = 5000, mistakesAllowed = 3 })
```

***

## Pairs

Flip face-down cards two at a time to find matching pairs. Matches stay face up. Clear every pair before time (or your attempts) run out.

**Export:** `exports['awoken_minigames']:Pairs(opts)` - returns `true` only on a win.

| Option        | Default  | Notes                                                            |
| ------------- | -------- | ---------------------------------------------------------------- |
| `gridSize`    | `4`      | Board is gridSize x gridSize (`2`-`8`).                          |
| `timeLimit`   | `120000` | Total ms budget (`0` = no limit).                                |
| `maxAttempts` | `0`      | Pair reveals allowed (`0` = unlimited).                          |
| `canCancel`   | `true`   |                                                                  |
| `autoStart`   | `true`   | Starts immediately. `false` shows a "press to start" gate first. |

```lua Presets theme={"dark"}
-- Tutorial
exports['awoken_minigames']:Pairs({ gridSize = 2, timeLimit = 0 })
-- (defaults)
exports['awoken_minigames']:Pairs({})
-- Standard
exports['awoken_minigames']:Pairs({ timeLimit = 90000 })
-- Attempt limit
exports['awoken_minigames']:Pairs({ maxAttempts = 14 })
-- Hard
exports['awoken_minigames']:Pairs({ gridSize = 6, timeLimit = 180000 })
```

***

## Recall

A path of cells lights up one after another, then hides. Click the cells back in the same order. Each round adds one more cell.

**Export:** `exports['awoken_minigames']:Recall(opts)` - returns `true` only on a win.

| Option            | Default | Notes                                                     |
| ----------------- | ------- | --------------------------------------------------------- |
| `gridSize`        | `4`     | Grid is gridSize x gridSize (`3`-`7`).                    |
| `startLength`     | `3`     | Path length on round 1 (`2`-`gridSize^2`).                |
| `rounds`          | `5`     | Number of rounds; each adds one cell.                     |
| `showMs`          | `520`   | How long each cell flashes during playback (`>= 140`).    |
| `mistakesAllowed` | `0`     | Wrong clicks tolerated before failing.                    |
| `timeLimit`       | `0`     | Ms to reproduce each path (`0` = no limit).               |
| `canCancel`       | `true`  |                                                           |
| `autoStart`       | `false` | Shows a "press to start" gate. `true` starts immediately. |

```lua Presets theme={"dark"}
-- Warmup
exports['awoken_minigames']:Recall({ rounds = 4, showMs = 560 })
-- (defaults)
exports['awoken_minigames']:Recall({})
-- Timed
exports['awoken_minigames']:Recall({ gridSize = 5, startLength = 4, rounds = 6, showMs = 460, timeLimit = 8000 })
-- Expert
exports['awoken_minigames']:Recall({ gridSize = 6, startLength = 5, rounds = 7, showMs = 340, timeLimit = 7000 })
-- Savant
exports['awoken_minigames']:Recall({ gridSize = 7, startLength = 5, rounds = 8, showMs = 260, timeLimit = 6000, canCancel = false })
```

***

## Observe

A scene of coloured symbols flashes up briefly, then hides. Answer multiple-choice questions about what you saw.

**Export:** `exports['awoken_minigames']:Observe(opts)` - returns `true` only on a win.

| Option            | Default | Notes                                                     |
| ----------------- | ------- | --------------------------------------------------------- |
| `items`           | `6`     | Glyphs shown in the scene each round (`3`-`12`).          |
| `studyMs`         | `2500`  | Ms the scene stays visible before it hides.               |
| `rounds`          | `5`     | Questions to answer to win (`1`-`12`).                    |
| `mistakesAllowed` | `1`     | Wrong answers tolerated before failing.                   |
| `timeLimit`       | `0`     | Per-question answer time in ms (`0` = no limit).          |
| `canCancel`       | `true`  |                                                           |
| `autoStart`       | `false` | Shows a "press to start" gate. `true` starts immediately. |

```lua Presets theme={"dark"}
-- Quick Glance
exports['awoken_minigames']:Observe({ items = 5, studyMs = 3000, rounds = 4 })
-- (defaults)
exports['awoken_minigames']:Observe({})
-- Flash Memory
exports['awoken_minigames']:Observe({ items = 8, studyMs = 1600, rounds = 6, mistakesAllowed = 0 })
-- Pressure Test
exports['awoken_minigames']:Observe({ items = 7, studyMs = 2000, rounds = 6, timeLimit = 5000 })
-- Photographic
exports['awoken_minigames']:Observe({ items = 10, studyMs = 1400, rounds = 8, mistakesAllowed = 0, timeLimit = 4000 })
```

***

## Tally

A grid of coloured cells flashes up briefly, then hides. Pick how many cells were the colour you're asked about.

**Export:** `exports['awoken_minigames']:Tally(opts)` - returns `true` only on a win.

| Option            | Default | Notes                                                            |
| ----------------- | ------- | ---------------------------------------------------------------- |
| `gridSize`        | `5`     | Board is gridSize x gridSize cells (`3`-`8`).                    |
| `colors`          | `3`     | Distinct colours in play (`2`-`5`).                              |
| `studyMs`         | `2500`  | Ms the coloured grid stays visible.                              |
| `rounds`          | `5`     | Questions to answer correctly to win (`1`-`15`).                 |
| `mistakesAllowed` | `1`     | Wrong answers tolerated before failing (`0`-`10`).               |
| `timeLimit`       | `0`     | Ms to answer each question (`0` = no per-question limit).        |
| `canCancel`       | `true`  |                                                                  |
| `autoStart`       | `true`  | Starts immediately. `false` shows a "press to start" gate first. |

```lua Presets theme={"dark"}
-- Quick Glance
exports['awoken_minigames']:Tally({ gridSize = 4, colors = 2, studyMs = 1400, rounds = 4, mistakesAllowed = 0 })
-- (defaults)
exports['awoken_minigames']:Tally({})
-- Timed Pressure
exports['awoken_minigames']:Tally({ colors = 4, studyMs = 2200, rounds = 6, timeLimit = 6000 })
-- Overload
exports['awoken_minigames']:Tally({ gridSize = 7, colors = 5, studyMs = 3500, rounds = 8, mistakesAllowed = 2, timeLimit = 8000 })
-- Marathon
exports['awoken_minigames']:Tally({ gridSize = 6, colors = 4, studyMs = 3000, rounds = 10, mistakesAllowed = 3 })
```

***

## Chroma Lock

A colour is shown, then hidden. Rebuild it from memory using the hue, saturation and lightness sliders, then submit.

**Export:** `exports['awoken_minigames']:ChromaLock(opts)` - returns `true` only on a win.

| Option            | Default | Notes                                                                                                                                       |
| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `rounds`          | `3`     | Colours to reproduce to win (`1`-`6`).                                                                                                      |
| `studyMs`         | `3000`  | Ms the target colour is shown before it hides.                                                                                              |
| `timeLimit`       | `20000` | Ms to reproduce it (`0` = no limit). Running it out costs a mistake.                                                                        |
| `tolerance`       | `12`    | How close the match must be, as a CIE94 deltaE (`1`-`40`). Lower is stricter: `5` is expert-tight, `12` demanding but fair, `20`+ generous. |
| `mistakesAllowed` | `1`     | Failed rounds tolerated before the lock jams.                                                                                               |
| `canCancel`       | `true`  |                                                                                                                                             |
| `autoStart`       | `false` | Shows a rules gate. `true` starts immediately.                                                                                              |

```lua Presets theme={"dark"}
-- Tutorial
exports['awoken_minigames']:ChromaLock({ rounds = 1, studyMs = 6000, timeLimit = 0, tolerance = 25 })
-- (defaults)
exports['awoken_minigames']:ChromaLock({})
-- Hard
exports['awoken_minigames']:ChromaLock({ rounds = 4, studyMs = 2000, tolerance = 8 })
-- Expert
exports['awoken_minigames']:ChromaLock({ rounds = 5, studyMs = 1200, tolerance = 5, mistakesAllowed = 0 })
-- Glance
exports['awoken_minigames']:ChromaLock({ rounds = 3, studyMs = 700, tolerance = 15 })
```

<Tip>
  A failed round briefly shows the target colour next to your attempt, so players can see how close they were.
</Tip>

***

## Pitch Lock

A tone plays, then stops. Slide a control by ear until it matches the pitch you just heard, then submit.

**Export:** `exports['awoken_minigames']:PitchLock(opts)` - returns `true` only on a win.

<Warning>
  This game needs sound - it's unplayable muted. Use a different game if you can't be sure the player has audio.
</Warning>

| Option            | Default | Notes                                                                                                                                                  |
| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `rounds`          | `3`     | Tones to match to win (`1`-`6`).                                                                                                                       |
| `listenMs`        | `2500`  | Ms the target tone plays before it stops.                                                                                                              |
| `timeLimit`       | `20000` | Ms to match it (`0` = no limit). Running it out costs a mistake.                                                                                       |
| `tolerance`       | `50`    | How close the match must be, in musical **cents** (`10`-`200`). 100 cents = a semitone. `25` is expert-tight, `50` fair but demanding, `100` generous. |
| `minFrequency`    | `220`   | Lowest target Hz (A3).                                                                                                                                 |
| `maxFrequency`    | `880`   | Highest target Hz (A5).                                                                                                                                |
| `mistakesAllowed` | `1`     | Failed rounds tolerated before it jams.                                                                                                                |
| `canCancel`       | `true`  |                                                                                                                                                        |
| `autoStart`       | `false` | Shows a rules gate. `true` starts immediately.                                                                                                         |

```lua Presets theme={"dark"}
-- Tutorial
exports['awoken_minigames']:PitchLock({ rounds = 1, listenMs = 4000, timeLimit = 0, tolerance = 100, maxFrequency = 440 })
-- (defaults)
exports['awoken_minigames']:PitchLock({})
-- Hard
exports['awoken_minigames']:PitchLock({ rounds = 4, listenMs = 1500, tolerance = 30 })
-- Expert
exports['awoken_minigames']:PitchLock({ rounds = 5, listenMs = 800, tolerance = 20, mistakesAllowed = 0 })
-- Wide range
exports['awoken_minigames']:PitchLock({ minFrequency = 110, maxFrequency = 1760, tolerance = 60 })
```

<Tip>
  Players get one replay per round (press R), and a failed round shows how far off they were and which way ("140 cents sharp").
</Tip>