Schema Overview
Every game is generated from a .randsum.json spec, a declarative description of a game’s dice mechanics. You never write TypeScript for a game: you write a JSON spec, and the codegen pipeline produces a fully typed module.
Games are data, not code
Section titled “Games are data, not code”Traditional game integrations require writing custom TypeScript for each system: dice logic, input validation, result interpretation and type definitions. This leads to inconsistent APIs, duplicated patterns, and maintenance burden that scales with each new game.
RANDSUM takes a different approach: every game is a JSON spec. The spec describes what the game’s dice mechanics do, not how to implement them. A build-time codegen pipeline reads these specs and produces the same shape of TypeScript for every game: the same API, the same error handling, the same kinds of types.
What a spec describes
Section titled “What a spec describes”A .randsum.json file defines:
- Pools: the dice used (sides, quantity)
- Tables: outcome lookup tables mapping numeric ranges to result strings
- Outcomes: how to interpret a roll result (table lookup, range matching, pool conditions)
- Inputs: what the caller provides (action rating, modifier, advantage mode) with types and validation
- Roll: how to assemble the dice, apply modifiers, resolve the total, and determine the outcome
- Conditional overrides: alternate behavior based on input values (e.g., zero-dice rolls in Blades)
Example: Salvage Union
Section titled “Example: Salvage Union”This is the actual salvageunion.randsum.json spec. It is the richest spec in the package, with many roll tables, range-based outcomes and dynamic table selection:
{"$schema": "https://randsum.dev/schemas/v1/randsum.json","name": "Salvage Union","shortcode": "salvageunion","version": "1.0.0","game_url": "https://leyline.press/products/salvage-union/",
"roll": { "inputs": { "tableName": { "type": "string" } }, "dice": { "pool": { "sides": 20 }, "quantity": 1 }, "resolve": { "remoteTableLookup": { "url": "https://salvageunion.io/schema/roll-tables.json", "find": { "field": "name", "input": "tableName", "errorMessage": "Invalid Salvage Union table name: \"${value}\"" }, "tableField": "table", "resultMapping": { "key": { "$lookupResult": "key" }, "label": { "$lookupResult": "result.label", "fallback": { "$lookupResult": "key" } }, "description": { "$lookupResult": "result.value" }, "tableName": { "$input": "tableName" }, "table": { "$foundTable": "table" }, "roll": { "expr": "total" } } } }}}From this spec, the codegen pipeline produces a fully typed roll() function that accepts a table name (like 'Core Mechanic' or 'Critical Injury'), rolls 1d20, looks up the result in the matching table by range, and returns a rich result with label, description, and tableName. The remoteTableLookup data is fetched at build time and baked into the generated code, so there are no network calls at runtime.
How codegen works
Section titled “How codegen works”The pipeline is internal to the @randsum/games build. It runs at build time, not at runtime.
- Read: each
.randsum.jsonspec is loaded and validated against the JSON Schema - Normalize: the spec is transformed into a semantic intermediate representation
- Generate: TypeScript source is produced: input types, roll function, result types, error handling
- Write: the generated
.tsfile is written tosrc/and checked into git
The generated code calls roll() from @randsum/roller/roll directly, with no schema runtime and no spec parsing at execution time. Each game is plain TypeScript.
Why this approach
Section titled “Why this approach”- Consistency: every game has the same API shape:
roll(input) -> { result, total, rolls } - Type safety: input types, result types, and error codes are generated from the spec
- Easy to add games: write a JSON spec, run codegen, submit a PR
- Human-readable: anyone can read a
.randsum.jsonand understand a game’s dice mechanics - No runtime cost: specs are compiled away; the published package is plain JavaScript
Learn more
Section titled “Learn more”- Schema Reference: field-by-field documentation for
.randsum.jsonspecs - The Schema API: validate specs and generate code from a script
- Contributing a Game: a step-by-step guide to adding a new game system