Getting started

Korokoro has two parts: pure functions for dice and odds, and an optional browser tray. This tutorial uses the functions first, so it works in Node or a browser without a page layout.

Install

npm install @johnmorrisdotca/korokoro

The package has no runtime dependencies and includes TypeScript declarations. Save a complete example as a TypeScript file and run it with Node 22 or later, or import it in your browser project.

Read and roll

import { parseNotation, roll, seededSource } from "@johnmorrisdotca/korokoro";
const spec = parseNotation("2d6+3");
if (spec === null) throw new Error("The notation cannot be rolled");
const result = roll(spec, seededSource("first-table"), 0);
console.log(result.faces, result.total);

[ 6, 1 ] 10

A roll records its spec, physical faces, which dice count, total, time and seed. Ordinary calls use the platform's cryptographic source; the seed above makes the tutorial repeatable. The time argument is epoch milliseconds, with zero used here so the example also has a fixed timestamp.

Inspect the odds

import { parseNotation, distributionOf, expectedTotal } from "@johnmorrisdotca/korokoro";
const spec = parseNotation("2d6")!;
const odds = distributionOf(spec);
console.log(odds.min, odds.max, expectedTotal(spec));

2 12 7

For a browser interface, continue with Embed a tray. For validation and more rules, use Roll with notation. The main entry lists every function.