About Korokoro

Architecture

The core is plain functions over plain data with no DOM and no dependency: dice, notation, exact odds, history and statistics, each in a module of its own, with the command line a pure function too. The tray is a small DOM layer under ui/, and the React component, the Vue component and the custom element are thin wrappers around it, each its own entry point, so a page loads only what it uses. The tabletop games are data (games/): a preset is a line of dice and a named reading, rarely new code.

src/
├── cli.ts             the command line as a pure function: arguments in, text and an exit code out
├── dice.ts            the dice the tray offers as buttons: the polyhedral set, the d30 and the percentile die
├── element-define.ts  the "/element/define" entry: registers the custom element by being imported
├── element.ts         the "/element" entry: the tray as a custom element for any page
├── export.ts          rolls written out as JSON, CSV or plain text, and read back
├── history.ts         the latest rolls, forgetting the oldest past a limit
├── index.ts           the main entry: dice, notation, odds, history and statistics, plus the tray to mount
├── loaded.ts          loaded dice, kept in plain sight: the weights are part of a die's name
├── math.ts            arithmetic over the kinds of dice in a roll
├── notation.ts        dice notation as a character sheet writes it, read into a spec and written back
├── odds.ts            exact odds for a spec, worked out rather than simulated
├── random.ts          where the randomness comes from, and how a seed replaces it
├── react.tsx          the "/react" entry: the tray as a React component
├── sets.ts            a named set of dice somebody wants to find again, kept on the device
├── share.ts           rolls as links, and the version of the notation a link is written in
├── stats.ts           everything worth saying about a history of rolls
├── version.ts         the version of this package, as package.json has it
├── vue.ts             the "/vue" entry: the tray as a Vue component
├── games/  the board and tabletop games whose dice the tray can set up and read
│   ├── odds.ts      exact odds for games that take more than one roll
│   ├── presets.ts   each game as a preset: its dice and how it reads them, and finding one by name
│   ├── readings.ts  how a roll is read in a game: a small set of named functions
│   └── words.ts     the words for every outcome of every reading, in English and Japanese
└── ui/  the tray that draws and rolls the dice
    ├── cloth.ts        the cloths a tray may be laid in
    ├── die.ts          one die on its own, rolling or only showing a face
    ├── dom.ts          a few lines of DOM building, so the tray needs no framework
    ├── faces.ts        each die drawn as its own shape
    ├── games.ts        the control for games: a search box and the games on their shelves
    ├── more.ts         everything one level down from the default tray: custom dice, loaded dice and saved sets
    ├── mount.ts        the tray itself: mounting it on a page, and the options it takes
    ├── panels.ts       the panels under the tray, drawn fresh from the state they are handed
    ├── sound.ts        the sound of a roll
    ├── sounds-data.ts  the tray's recorded dice, as base64 AAC audio, for the "/sounds" entry
    ├── strings.ts      every word the tray says, in English and Japanese
    └── style.ts        the tray's look, injected once per document

Tests sit beside the code they test (*.test.ts), and src/docs.test.js runs the README's examples. bin/ is the few lines that hand the command line the real process, scripts/ builds the demo and the documentation site and checks the package as npm packs it, conformance/ is the vectors another language's port checks itself against, tray/ taps the tray in real browsers, website/ and docs/ are the documentation, and demo/ is the page published on GitHub Pages.

The name

Korokoro (コロコロ) is a Japanese sound-word for something small and round rolling or tumbling along: a die across a table, an acorn down a slope. Japanese has a great many words of this kind, which name a thing by the sound or the feel of it, and this one is the sound of what the package does. Say it in four even beats: ko-ro-ko-ro.

Dice, as it happens, are saikoro (サイコロ) in Japanese, which ends on the same two beats. We make no claim about where either word comes from; it is a pleasant echo.

Where it comes from, and where it is used

Korokoro was built for Itsutsu, a site for board games, puzzles, card games and dice games played at your own pace. Itsutsu (五つ) is Japanese for "five", after five in a row, the game the site began with. The site needed dice that were fair and that anybody could check, and once they existed they seemed worth sharing.

Used by

• Itsutsu, for its dice.

That is the whole list so far. Using Korokoro in something? Open an Add my project issue and we will add you.

The family

Korokoro has siblings, each made for the same site, each MIT, each at github.com/johnmorrisdotca:

• Kyuubu (キューブ, how Japanese says "cube"): a turning cube for the browser, 2×2 to 7×7, drawn in CSS 3D.
• Toranpu (トランプ, the everyday Japanese word for a deck of playing cards): ten card games as pure rules.
• Tane (種, a seed, the kind you plant): seeded random numbers and daily seeds. Korokoro's seeded rolls are the same idea.
• Hitotsu (一つ, "one"): a colour-card game, named for the call a player makes with one card left.
• Narabe (並べ, "line them up"): a rules engine for gomoku, Reversi, Go, checkers and many more.
• Tenka (天下, "under heaven"): a world-conquest game for two to six.
• Kumimoji (組み文字, "letters put together"): a crossword tile race in English and Japanese.

Roadmap

• More notation, as tables ask for it (Notation compared keeps the list)
• Standalone executables of the command line, for machines without Node
• The documentation in Japanese
• More games: suggest one
• BCDice's notation, which Japanese tables use, as a candidate
• Ports to other languages are welcome: there is a specification and a conformance suite to write one against
• A hosted HTTP API: not planned, because it needs a server. The command line and the package will cover programs.
• Exploding dice that are kept or dropped, once a table's rule is chosen

Left out on purpose: shared live rooms, which need a server, dice skins for sale, and 3D dice. Korokoro runs from a static page and costs nothing to host.

Ideas and pull requests are welcome.

Contributing

See CONTRIBUTING.md. In short:

pnpm install
pnpm check        # lint, types and tests
pnpm test:tray    # the demo and the documentation site, built and tapped in real browsers
pnpm site         # build the demo into ./site, then serve it

Please follow the code of conduct.

Licence

MIT © John Morris. The dice recordings are CC0; see SOUNDS.md.