# @randsum/games

Roll dice for Salvage Union, D&D, Blades in the Dark, PbtA, and more with typed, game-specific functions. Each game package validates input, rolls using the core engine, and interprets the result according to that system's rules.

All game packages are powered by `@randsum/roller`, which implements the full [RANDSUM Dice Notation (RDN) Specification](https://notation.randsum.dev).

## Available games
**Salvage Union**
`@randsum/games/salvageunion` -- D20 table-based rolls for mech combat and salvage operations.

    [View documentation](https://randsum.dev/games/salvageunion/)

**D&D 5th Edition**
`@randsum/games/fifth` -- Ability checks, saving throws, attack rolls with advantage/disadvantage.

    [View documentation](https://randsum.dev/games/fifth/)

**Blades in the Dark**
`@randsum/games/blades` -- Dice pool action rolls with critical, success, partial, and failure outcomes.

    [View documentation](https://randsum.dev/games/blades/)

**Powered by the Apocalypse**
`@randsum/games/pbta` -- 2d6+stat rolls for Dungeon World, Monster of the Week, Apocalypse World, and more.

    [View documentation](https://randsum.dev/games/pbta/)

**Daggerheart**
`@randsum/games/daggerheart` -- Hope and fear dice with amplification and advantage/disadvantage.

    [View documentation](https://randsum.dev/games/daggerheart/)

**Root RPG**
`@randsum/games/root-rpg` -- 2d6+bonus with Strong Hit, Weak Hit, and Miss outcomes.

    [View documentation](https://randsum.dev/games/root-rpg/)

## How they work

Every game package follows a three-step pipeline: validate input, roll dice, interpret the result.

<CodeExample code={`// 1. Validate — checks that tableName matches a known table
// 2. Roll — executes the d20 roll via @randsum/roller
// 3. Interpret — looks up the result in the matching table by range
const result = roll('Core Mechanic')

console.log(result.result.label)       // 'Success' | 'Tough Choice' | 'Failure' | ...
console.log(result.result.description) // full outcome text
console.log(result.total)              // d20 roll
console.log(result.rolls)              // raw RollRecord[] from the roller`} />

## Common patterns

All game packages share these characteristics:

- **Single `roll()` export** — each subpath exports one `roll()` function as the main API
- **Game-specific input types** — typed input objects, not raw notation strings
- **`GameRollResult` return type** — includes `result` (game outcome), `total`, `rolls`, and optional `details`
- **Input validation** — throws `ValidationError` (from roller) for out-of-range numeric input and `SchemaError` for game-specific issues like invalid enum values or unmatched outcome tables
- **No cross-dependencies** — game packages depend only on `@randsum/roller`, never on each other
- **Under 8KB bundled** — lightweight subpath imports (Salvage Union is larger due to table data)

## Quick comparison

| Game | Dice | Input | Outcomes |
|---|---|---|---|
| `salvageunion` | 1d20 | `tableName` (string) | Table result with label + description |
| `fifth` | 1d20 or 2d20 | `modifier`, `rollingWith`, `crit` | Numeric total |
| `blades` | Nd6 pool | `rating` (number, 0-6) | `critical`, `success`, `partial`, `failure` |
| `pbta` | 2d6 | `stat`, `forward`, `ongoing`, `rollingWith` | `strong_hit`, `weak_hit`, `miss` |
| `daggerheart` | Hope/Fear dice | `modifier`, `amplifyHope`, `amplifyFear`, `rollingWith` | `critical hope`, `hope`, `fear` |
| `root-rpg` | 2d6 | `bonus` (number) | `Strong Hit`, `Weak Hit`, `Miss` |

## Installation

Install `@randsum/games` once, then `} />
**Games are data, not code:** Every game package is code-generated from a `.randsum.json` spec — a declarative description of the game's dice mechanics, input validation, and outcome interpretation. The TypeScript you import is produced by a build-time codegen pipeline, not hand-written. See the [Schema Overview](https://randsum.dev/games/schema/overview/) for how this works.

## What's next

- **[Getting Started](https://randsum.dev/games/getting-started/)** — install, roll your first game-specific dice, read the result
- **[Schema Overview](https://randsum.dev/games/schema/overview/)** — how `.randsum.json` specs power the codegen pipeline
- **Individual game pages** — detailed docs for each supported system (linked in the cards above)