Game spec creator
Help users create .randsum.json specs for custom TTRPG dice mechanics. Use when someone wants to define a new game system, translate tabletop game rules into declarative specs, or understand the RANDSUM spec format.From its SKILL.md
npx -y skills add RANDSUM/randsum --skill game-spec-creatorAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 13 stars13 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its file declares
Copied from the file, not written here
The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.
SKILL.md
6.5 KB, as published. Nobody here has run it
Game Spec Creator
Create .randsum.json specs that declaratively define tabletop RPG dice mechanics. A spec describes a four-stage pipeline -- Dice -> Modify -> Resolve -> Outcome -- and generates a typed TypeScript roll() function via codegen.
Spec Structure
Every spec requires these top-level fields:
{
"$schema": "https://randsum.dev/schemas/v1/randsum.json",
"name": "My Game",
"shortcode": "mygame",
"game_url": "https://example.com",
"version": "1.0.0",
"roll": { ... }
}
Optional top-level sections for reuse across rolls:
pools-- Named dice pool definitions. Reference with{ "$ref": "#/pools/<name>" }.tables-- Lookup tables mapping roll values to result strings.outcomes-- Named outcome operations for result classification.
The roll Object
The roll object defines the pipeline:
| Field | Stage | Required | Purpose |
|---|---|---|---|
inputs | -- | No | Declare runtime parameters (stat, modifier, rating) |
dice | 1 | Yes* | Pool reference + quantity. *Or use dicePools for multi-pool rolls |
modify | 2 | No | Modifier chain (keepHighest, keepLowest, add, cap) |
resolve | 3 | Yes | Resolution: "sum", countMatching, tableLookup, or comparePool |
outcome | 4 | No | Map resolved value to a game result string |
when | -- | No | Conditional overrides based on input values |
details | -- | No | Extra typed fields returned alongside the result |
postResolveModifiers | -- | No | Arithmetic applied after resolve (e.g. 2d6+stat) |
Inputs
Inputs are typed parameters the caller passes at roll time. Bind them in the pipeline with { "$input": "paramName" }.
"inputs": {
"modifier": { "type": "integer", "minimum": -5, "maximum": 5, "default": 0 },
"mode": { "type": "string", "enum": ["Normal", "Advantage"], "optional": true }
}
Types: integer, string, boolean. Inputs can have default, minimum/maximum, enum, optional, and description.
Dice
Single pool (inline or referenced):
"dice": { "pool": { "sides": 20 }, "quantity": 1 }
"dice": { "pool": { "$ref": "#/pools/actionDice" }, "quantity": { "$input": "rating" } }
Multi-pool (use dicePools instead of dice):
"dicePools": {
"hope": { "pool": { "sides": 12 } },
"fear": { "pool": { "sides": 12 } }
}
Modify
Array of modifier operations applied to individual dice before resolving:
"modify": [
{ "keepHighest": 1 },
{ "add": { "$input": "modifier" } },
{ "cap": { "min": 1, "max": 20 } }
]
Available: keepHighest, keepLowest, add, cap, markDice/keepMarked.
Resolve
"sum"-- Total all remaining dice{ "countMatching": { "operator": ">=", "value": 7 } }-- Count successes{ "tableLookup": { "$ref": "#/tables/myTable" } }-- Map total through a table{ "comparePoolHighest": { "pools": ["a","b"], "outcomes": {...} } }-- Compare pools
Outcome
Map the resolved value to game result strings:
"outcome": {
"ranges": [
{ "min": 10, "max": 27, "result": "strong_hit" },
{ "min": 7, "max": 9, "result": "weak_hit" },
{ "min": -11, "max": 6, "result": "miss" }
]
}
Also supports tableLookup (with $ref or inline) and degreeOfSuccess for PF2e-style tiers.
Conditional Overrides (when)
Override pipeline stages based on input values. First match wins; unspecified stages fall through:
"when": [{
"condition": { "input": "mode", "operator": "=", "value": "Advantage" },
"override": {
"dice": { "pool": { "sides": 20 }, "quantity": 2 },
"modify": [{ "keepHighest": 1 }, { "add": { "$input": "modifier" } }]
}
}]
Pool Conditions
Check dice composition rather than totals -- used in tables for mechanics like Blades criticals:
{
"poolCondition": { "countWhere": { "operator": "=", "value": 6 }, "atLeast": 2 },
"result": "critical"
}
Use atLeastRatio (0-1) instead of atLeast for proportion-based checks.
Guided Workflow
When helping a user create a spec, follow these steps:
1. Identify the core mechanic
Ask: What dice do you roll? What determines success or failure? Classify it:
- Sum-based: Roll dice, add modifiers, compare to target (D&D, PbtA)
- Pool-based: Roll many dice, count successes (World of Darkness, Shadowrun)
- Keep-best/worst: Roll multiple, keep highest or lowest (Blades, advantage/disadvantage)
- Comparison: Compare two pools (Daggerheart hope/fear)
- Table lookup: Roll and consult a table (Salvage Union, random encounters)
2. Map inputs
What does the player choose or provide? Common patterns:
- Numeric modifier (stat bonus, skill rank)
- Pool size (action rating, dice pool count)
- Mode selection (advantage/disadvantage, boost/cut)
- Table name (which random table to roll on)
3. Build the pipeline
Define pools, modifiers, resolution strategy, and outcome ranges. Use when for variant mechanics. Validate against packages/games/randsum.json.
Common Patterns
Tiered outcomes (PbtA-style): Range-based outcome with strong hit / weak hit / miss.
Keep highest with fallback (Blades-style): keepHighest: 1 default, when rating=0 overrides to keepLowest: 1 with 2 dice.
Advantage/Disadvantage (D&D-style): when conditions that change pool quantity and keep strategy.
Pool conditions (criticals): poolCondition in table ranges to detect multiple max-value dice.
Multi-pool comparison (Daggerheart-style): dicePools + comparePoolHighest resolve.
Post-resolve arithmetic: postResolveModifiers for bonuses applied after resolution (not per-die).
Boolean-conditional values: { "$input": "flag", "ifTrue": 20, "ifFalse": 12 } for inputs that change die size.
Validation and Testing
- Meta-schema:
packages/games/randsum.json(orhttps://randsum.dev/schemas/v1/randsum.json) - Run codegen:
bun run --filter @randsum/games gen - Run tests:
bun run --filter @randsum/games test - Check bundle size: each game should be under 8 KB (except table-heavy games)
Examples
See references/SPEC_EXAMPLES.md for complete working specs at three complexity levels.