RANDSUM

https://randsum.dev/docs
Admin
RANDSUM is a zero-dependency, TypeScript-first dice notation and rolling engine for tabletop RPG...
Tokens:1,182
Snippets:12
Trust Score:5
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install @randsum/roller with Bun or npm

Source: https://randsum.dev

Install the @randsum/roller package using either Bun or npm. Both commands are equivalent and install the same package.

```bash
bun add @randsum/roller
```

```bash
npm i @randsum/roller
```

--------------------------------

### Validate and roll user input

Source: https://randsum.dev

Example of validating user input with isDiceNotation before rolling. Throws an error for invalid notation, then returns the total and a breakdown of each roll's initial dice, final dice, and description.

```typescript
import { roll } from '@randsum/roller'
import { isDiceNotation } from '@randsum/roller/validate'

function rollFromUserInput(input: string) {
  if (!isDiceNotation(input)) {
    throw new Error(`Invalid notation: ${input}`)
  }

  const { total, rolls } = roll(input)

  return {
    total,
    breakdown: rolls.map(r => ({
      dice: r.initialRolls,
      final: r.rolls,
      description: r.description
    }))
  }
}
```

--------------------------------

### Salvage Union .randsum.json config

Source: https://randsum.dev

Example .randsum.json configuration file for the Salvage Union game system. It defines a single d20 roll with a remote table lookup, mapping the result fields. This config is used by @randsum/games to generate a typed roller.

```json
{
  "name": "Salvage Union",
  "shortcode": "salvageunion",
  "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 table: \"${value}\""
        },
        "tableField": "table",
        "resultMapping": {
          "key": { "$lookupResult": "key" },
          "label": { "$lookupResult": "result.label" },
          "description": { "$lookupResult": "result.value" },
          "tableName": { "$input": "tableName" }
        }
      }
    }
  }
}
```

--------------------------------

### Roll 4d6L with @randsum/roller

Source: https://randsum.dev

Basic usage of the roll function from @randsum/roller. Rolls '4d6L' (4 six-sided dice, drop lowest) and logs the total, initial rolls, final rolls, and description. The output shows the expected results.

```typescript
import { roll } from '@randsum/roller'


const { total, rolls } = roll('4d6L')


console.log(total)
// 15
console.log(rolls[0].initialRolls)
// [1, 5, 4, 6]
console.log(rolls[0].rolls)
// [4, 5, 6]
console.log(rolls[0].description)
// ["Roll 4 6-sided dice", "Drop lowest"]
```
Tokens:
Raw