> ## 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.

# Dexterity

> Four minigames for steady hands and quick reactions.

Four games built around steady hands and quick reactions. Defaults live in `config/games/dexterity.lua`.

<Info>
  Set an option once in `config/games/dexterity.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>

***

## Shake

Shake the mouse back and forth to fill a meter. It drains the whole time, so keep moving until it reaches the target before time runs out.

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

| Option      | Default | Notes                                                                                               |
| ----------- | ------- | --------------------------------------------------------------------------------------------------- |
| `target`    | `100`   | Fill units needed to win.                                                                           |
| `gainPerPx` | `0.024` | Fill added per pixel of mouse movement. Travel is speed-capped, so filling needs sustained shaking. |
| `decay`     | `16`    | Fill drained per second.                                                                            |
| `timeLimit` | `12000` | Ms before you fail (`0` = no limit).                                                                |
| `canCancel` | `true`  |                                                                                                     |
| `autoStart` | `false` | Shows a "press to start" gate. `true` starts immediately.                                           |

```lua Presets theme={"dark"}
-- Warm Up
exports['awoken_minigames']:Shake({ target = 70, gainPerPx = 0.03, decay = 10, timeLimit = 15000 })
-- (defaults)
exports['awoken_minigames']:Shake({})
-- Frantic
exports['awoken_minigames']:Shake({ target = 110, gainPerPx = 0.028, decay = 30, timeLimit = 10000 })
-- Endurance
exports['awoken_minigames']:Shake({ target = 180, gainPerPx = 0.023, decay = 18, timeLimit = 0 })
-- Sprint
exports['awoken_minigames']:Shake({ target = 75, gainPerPx = 0.032, decay = 22, timeLimit = 5000, canCancel = false })
```

***

## Cascade

Letters fall from the top. Press the matching key to clear the lowest one. Clear enough of them before too many reach the floor.

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

| Option      | Default              | Notes                                                     |
| ----------- | -------------------- | --------------------------------------------------------- |
| `charset`   | `'ABCDEFGHIJKLMNOP'` | Letters that can fall (uppercased).                       |
| `fallSpeed` | `70`                 | Px/s a letter descends at the start.                      |
| `spawnMs`   | `900`                | Ms between letter spawns at the start.                    |
| `speedRamp` | `6`                  | Px/s the fall speed gains each second.                    |
| `target`    | `15`                 | Letters to clear to win.                                  |
| `maxMissed` | `4`                  | Letters that may reach the floor before losing.           |
| `timeLimit` | `0`                  | Ms cap (`0` = no limit).                                  |
| `canCancel` | `true`               |                                                           |
| `autoStart` | `false`              | Shows a "press to start" gate. `true` starts immediately. |

```lua Presets theme={"dark"}
-- Warmup
exports['awoken_minigames']:Cascade({ charset = 'ABCDEFGH', fallSpeed = 55, spawnMs = 1100, speedRamp = 3, target = 10, maxMissed = 6 })
-- (defaults)
exports['awoken_minigames']:Cascade({})
-- Full Alphabet
exports['awoken_minigames']:Cascade({ charset = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', fallSpeed = 80, spawnMs = 820, speedRamp = 7, target = 20, maxMissed = 3 })
-- Blitz
exports['awoken_minigames']:Cascade({ fallSpeed = 110, spawnMs = 650, speedRamp = 12, target = 20, maxMissed = 3, timeLimit = 45000 })
-- Sudden Death
exports['awoken_minigames']:Cascade({ charset = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', fallSpeed = 90, spawnMs = 780, speedRamp = 8, target = 15, maxMissed = 0 })
```

***

## Fishing

Fish drift around a pool. Hold your cursor over a fish to fill its ring and land it (the ring drains if you slip off), then move to the next. Each fish is kept the moment you land it, so landing 2 of 3 still keeps those 2.

**Exports:**

* `exports['awoken_minigames']:Fishing(opts)` - returns `true` only if every fish is landed.
* `exports['awoken_minigames']:FishingResult(opts)` - returns a table `{ success, caught, total, cancelled }`, for a fishing script that rewards **per catch** (award `caught` regardless of `success`).

| Option       | Default | Notes                                                                                       |
| ------------ | ------- | ------------------------------------------------------------------------------------------- |
| `fishCount`  | `3`     | Fish to land, all of them (`2`-`10`).                                                       |
| `fishSpeed`  | `0.6`   | Drift speed factor (`0.15`-`3`); higher = faster.                                           |
| `hoverTime`  | `1400`  | Ms of hovering to land one fish (`400`-`5000`).                                             |
| `ramp`       | `0`     | Difficulty ramp (`0`-`3`): each landed fish speeds the rest up by this factor (`0` = flat). |
| `silhouette` | `false` | Draw fish as dark shadows (mystery catch).                                                  |
| `timeLimit`  | `0`     | Ms budget (`0` derives from count x `hoverTime`).                                           |
| `canCancel`  | `true`  |                                                                                             |
| `autoStart`  | `true`  | Starts immediately. `false` shows a "press to start" gate first.                            |

```lua Presets theme={"dark"}
-- Easy Catch
exports['awoken_minigames']:Fishing({ fishCount = 2, fishSpeed = 0.4, hoverTime = 1100 })
-- Standard (defaults)
exports['awoken_minigames']:Fishing({})
-- Double Haul
exports['awoken_minigames']:Fishing({ fishCount = 4, fishSpeed = 0.85, hoverTime = 1500 })
-- Trophy Run
exports['awoken_minigames']:Fishing({ fishCount = 6, fishSpeed = 1.2, hoverTime = 1700 })
-- Ramping
exports['awoken_minigames']:Fishing({ fishCount = 5, fishSpeed = 0.55, hoverTime = 1400, ramp = 0.4 })

-- Detailed result for a fishing script (reward per catch):
local r = exports['awoken_minigames']:FishingResult({ fishCount = 3 })
-- r.caught = fish landed this game; r.total = pool size; r.success = all landed
```

<Tip>
  Use `FishingResult` if a partial haul should still pay out - plain `Fishing` only tells you win or lose, so a 2-of-3 game counts as a loss.
</Tip>

***

## Cooldown

Sweep the mouse over glowing reactor cells to cool them. Get the overall temperature down to the target before it overheats or time runs out.

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

| Option       | Default | Notes                                                                                               |
| ------------ | ------- | --------------------------------------------------------------------------------------------------- |
| `gridSize`   | `7`     | Reactor board is gridSize x gridSize cells (`4`-`12`); smaller = the cursor covers more, so easier. |
| `heatRate`   | `0.34`  | How fast heat builds (`0.05`-`3`).                                                                  |
| `coolPower`  | `1.5`   | How strongly the cursor cools nearby cells (`0.2`-`4`).                                             |
| `threshold`  | `25`    | Win when overall temperature drops to/below this % (`1`-`90`).                                      |
| `overheatAt` | `100`   | Lose if overall temperature reaches this % (`threshold`+`5`-`100`).                                 |
| `timeLimit`  | `32000` | Ms to stabilise the reactor (`0` = no limit).                                                       |
| `canCancel`  | `true`  |                                                                                                     |
| `autoStart`  | `false` | Shows a "press to start" gate. `true` starts immediately.                                           |

```lua Presets theme={"dark"}
-- Quick Vent
exports['awoken_minigames']:Cooldown({ gridSize = 6, heatRate = 0.28, coolPower = 1.6, threshold = 30, timeLimit = 25000 })
-- (defaults)
exports['awoken_minigames']:Cooldown({})
-- Overload
exports['awoken_minigames']:Cooldown({ gridSize = 9, heatRate = 0.4, coolPower = 1.55, threshold = 25, overheatAt = 95, timeLimit = 45000 })
-- Meltdown Watch
exports['awoken_minigames']:Cooldown({ gridSize = 7, heatRate = 0.55, coolPower = 1.7, threshold = 27, overheatAt = 85, timeLimit = 40000 })
-- Endless Vent
exports['awoken_minigames']:Cooldown({ gridSize = 7, heatRate = 0.38, coolPower = 1.55, threshold = 24, timeLimit = 0 })
```