# Root RPG

The `@randsum/games/root-rpg` subpath provides mechanics for [Root RPG](https://magpiegames.com/pages/root-rpg), a tabletop roleplaying game set in the world of the Root board game. It uses a 2d6 + bonus system with success thresholds similar to Powered by the Apocalypse games.

[Official Site](https://magpiegames.com/pages/root-rpg)

## Installation

<CodeExample lang="bash" code={`bun add @randsum/games`} />
  <CodeExample lang="bash" code={`npm install @randsum/games`} />
  ## Usage

<CodeExample code={`// Roll with a stat bonus
const { result, total } = roll(2)
// result: 'Strong Hit' | 'Weak Hit' | 'Miss'`} />

<CodeExample code={`const { result } = roll(0)

switch (result) {
  case 'Strong Hit':
    // 10+ total: complete success
    break
  case 'Weak Hit':
    // 7-9 total: partial success with cost
    break
  case 'Miss':
    // 6- total: failure
    break
}`} />

<CodeExample code={`roll(2)   // Strong stat
roll(0)   // No bonus
roll(-1)  // Penalty`} />

## API

### `roll(bonus: number)`

**Input:**

| Parameter | Type | Description |
|---|---|---|
| `bonus` | `number` | Stat modifier (-20 to +20) |

**Returns:** `GameRollResult` with:

| Property | Type | Description |
|---|---|---|
| `result` | `RootRpgRollResult` | `'Strong Hit' \| 'Weak Hit' \| 'Miss'` |
| `total` | `number` | Sum of 2d6 + bonus |
| `rolls` | `RollRecord[]` | Raw dice data from the core roller |

## Outcomes

| Outcome | Total | Description |
|---|---|---|
| `Strong Hit` | 10+ | Complete success -- you achieve your goal |
| `Weak Hit` | 7-9 | Partial success -- you do it, but with a cost or complication |
| `Miss` | 6- | Failure -- things go badly |

## Error handling

Game `roll()` can throw two types of errors:

- **`ValidationError`** (from `@randsum/roller`) -- numeric input out of range or not finite (e.g., `bonus: 999` when max is 20)
- **`SchemaError`** (from `@randsum/games/root-rpg`) -- game-specific issues like unmatched outcome tables

<CodeExample code={`try {
  roll(999)
} catch (error) {
  if (error instanceof ValidationError) {
    // Out-of-range bonus (must be -20 to 20)
    console.log(error.code)    // 'VALIDATION_ERROR'
  } else if (error instanceof SchemaError) {
    // Game-specific error
    console.log(error.code)    // 'NO_TABLE_MATCH'
  }
}`} />

## Types

<CodeExample code={``} />

## Schema

This game is powered by a `.randsum.json` spec that defines the 2d6+bonus resolution and outcome tiers. The TypeScript code is generated from this spec at build time. See [Schema Overview](https://randsum.dev/games/schema/overview/) for how game specs work.

## Links

- [npm package](https://www.npmjs.com/package/@randsum/games)
- [Source code](https://github.com/RANDSUM/randsum/tree/main/packages/games)