NDS Roller

This is my implementation of a dice roller for FFG/EDGE Studio's narrative dice system.

Version 3.0.0 Update

The package is now written in TypeScript and ships its own type definitions. Breaking changes:

• Invalid input throws. roll, toIcons, and the name/letter helpers throw an NdsError on invalid input, instead of logging to the console and returning ''/null or skipping the die.
• Named exports. Every function is also available as a named export. The default export still works.

  import nds from 'nds-roller';
  import { roll, toIcons, NdsError, type RollResult } from 'nds-roller';

• kind on each die result. Results in dice include kind: 'die' | 'symbol' | 'numeric', which TypeScript can use to narrow the result type.
• No deep imports. The package now declares an exports map. Only 'nds-roller' can be imported. Paths like 'nds-roller/src/utils/roll.js' no longer resolve.
• ESM only. Die images are imported as .png modules, so you need a bundler that handles image imports (Vite, webpack, etc.), as in 2.x.
• Symbols added directly to a pool ('s', 'a', ...) don't have a bundled image yet. Use imageUrl for these.

Exported types include RollResult, RollSummary, RollOptions, DieResult (NarrativeDieResult | SymbolResult | NumericDieResult), SymbolTotal, LogEntry, DiceInput, DieName, DieLetter, SymbolName, SymbolLetter, and NumericDie. Runtime type guards (isDiceInput, isDieName, isDieLetter, isSymbolName, isSymbolLetter, isNumericDie) are exported for validating untyped input.

Version 2.0.0 Update

In prior versions, image was the image url to the die face. This is an imgur url that no longer works in certain countries. If you would like to continue using the imgur link, that is now found on imageUrl.

Die face images are now included, and provided directly on the image property.

Usage

nds.roll

Provide an array of dice, and get the randomized result. This is a basic implementation using JavaScript's Math.random() method. Results are returned in a variety of reports including dice name/face/symbol information, total symbols, symbols after cancelling, and a string reporting the canceled result.

Add a note as the second parameter which will be returned with the outcome and saved in the log.

NOTE: dice output order will be the same as the input order.

Throws an NdsError if the pool is not an array or contains an invalid die.

import nds from 'nds-roller';

// Use dice colors or names, and add symbols
const dicePool = ['proficiency', 'g', 'p', 'b', 's', 'h'];
nds.roll(dicePool, 'Test roll');
/**
 * {
 *    dice: [
 *       { kind: 'die', name: 'proficiency', face: 12, symbols: 't', image: '...', imageUrl: '...' },
 *       { kind: 'die', name: 'ability', face: 7, symbols: 'sa', image: '...', imageUrl: '...' },
 *       { kind: 'die', name: 'difficulty', face: 8, symbols: 'fh', image: '...', imageUrl: '...' },
 *       { kind: 'die', name: 'boost', face: 2, symbols: '', image: '...', imageUrl: '...' },
 *       { kind: 'symbol', name: 'success', face: 's', symbols: 's', imageUrl: '...' },
 *       { kind: 'symbol', name: 'threat', face: 'h', symbols: 'h', imageUrl: '...' },
 *    ],
 *    total: { s: 3, a: 1, t: 1, f: 1, h: 2, d: 0, num: 0 },
 *    result: { s: 2, t: 1, h: 1 },
 *    summary: '2 success, 1 threat, 1 triumph',
 *    note: 'Test roll',
 * }
 */

// Roll d10s and d100s
const numberPool = ['10', '10', '100'];
nds.roll(numberPool);
/**
 * {
 *    dice: [
 *       { kind: 'numeric', name: '10', total: 4, symbols: '' },
 *       { kind: 'numeric', name: '10', total: 6, symbols: '' },
 *       { kind: 'numeric', name: '100', total: 61, symbols: '' },
 *    ],
 *    total: { s: 0, a: 0, t: 0, f: 0, h: 0, d: 0, num: 71 },
 *    result: { num: 71 },
 *    summary: '71'
 * }
 */

Super characteristics

Pass { super: true } as the third parameter for a check made with a super characteristic. Each triumph rolled on a proficiency die adds another proficiency die to the roll. Triumphs on those added dice add more, until no new triumphs are rolled. Added dice are appended to dice with bonus: true and count toward total, result, and summary. Triumph symbols added directly ('t') do not trigger extra dice.

nds.roll(['y', 'g', 'p'], 'Super check', { super: true });
/**
 * {
 *    dice: [
 *       { name: 'proficiency', face: 12, symbols: 't', ... },
 *       { name: 'ability', face: 5, symbols: 'a', ... },
 *       { name: 'difficulty', face: 1, symbols: '', ... },
 *       { name: 'proficiency', face: 4, symbols: 'ss', bonus: true, ... },
 *    ],
 *    ...
 * }
 */

nds.toIcons

Turn symbol abbreviations into HTML icons. Acceptable inputs are a string or array of symbol abbreviations, or an object with abbreviation symbol keys and numerical values (such as the total and result values provided by roll (see above)).

Unknown characters are passed through unchanged. Throws an NdsError if the input is not a string, array, or object.

WARNING: older browsers/devices may not correctly display these icons - use with caution.

import nds from 'nds-roller';

// get icons from a string
nds.toIcons('satfhd'); // ✲▲❂✖▼⦻

// get icons from an array
nds.toIcons(['s', 'a', 't', 'f', 'h', 'd']) // ✲▲❂✖▼⦻

// get icons from a roll result
nds.toIcons(nds.roll(['y', 'g', 'p']).result) // ✲✲▼

nds.getDieName / nds.getDieLetter

Turn a die letter into its name, or vice versa.

import nds from 'nds-roller';

nds.getDieName('g');
// 'ability'

nds.getDieLetter('ability');
// 'g'

nds.getDieName('z');
// throws NdsError

nds.getSymbolName / nds.getSymbolLetter

Turn a symbol letter into its name, or vice versa.

import nds from 'nds-roller';

nds.getSymbolName('t');
// 'triumph'

nds.getSymbolLetter('threat');
// 'h'

nds.getSymbolName('z');
// throws NdsError

nds.log

Gives a readout of all previous rolls including the outcome, note, and timestamp. This log is mutable and can be manipulated.

nds.log;
/**
 * [
 *    {
 *       outcome: {
 *          dice: [...],
 *          total: {...},
 *          result: {...},
 *          summary: '...',
 *          note: 'Test roll',
 *       },
 *       timestamp: new Date(),
 *    },
 *    {...}
 * ]
 */

Abbreviations

Dice

| abbreviation | full name | reason | | ------------ | ----------- | -------- | | y | proficiency | [y]ellow | | g | ability | [g]reen | | b | boost | [b]lue | | r | challenge | [r]ed | | p | difficulty | [p]urple | | k | setback | blac[k] |

Symbols

| abbreviation | full name | | ------------ | ----------- | | s | [s]uccess | | a | [a]dvantage | | t | [t]riumph | | f | [f]ailure | | h | t[h]reat | | d | [d]espair |