Skip to content
RANDSUMgames

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.

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.

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)

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.

The pipeline is internal to the @randsum/games build. It runs at build time, not at runtime.

  1. Read: each .randsum.json spec is loaded and validated against the JSON Schema
  2. Normalize: the spec is transformed into a semantic intermediate representation
  3. Generate: TypeScript source is produced: input types, roll function, result types, error handling
  4. Write: the generated .ts file is written to src/ 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.

  • 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.json and understand a game’s dice mechanics
  • No runtime cost: specs are compiled away; the published package is plain JavaScript