Reference

Rolls and exact odds

import { … } from "@johnmorrisdotca/korokoro";

101.0 kB minified and gzipped, with everything it imports (measured with esbuild)

Korokoro コロコロ: fair dice, exact odds, and a history that remembers.

The core is plain functions over plain data, with no dependency and no DOM: roll, read the odds, keep a history and summarise it. The tap-to-roll tray is mountRoller in ./ui/mount.ts, exported here too.

Exports

Name	Kind	What it is
`addToHistory`	function	Add a roll to the end, oldest dropped past the limit.
`asChance`	function	A fraction as a number, for showing.
`canHold`	function	Whether some dice of a roll can be held while the rest are thrown again: plain dice only, none rerolled, exploding, kept or dropped, counted, raised, lowered or sorted.
`chanceAnyAtLeast`	function	The chance that at least one of several throws of a roll reaches a target: a set of six ability scores holding at least one 16, say.
`chanceAtLeast`	function	The chance of this total or more: "what do I need to beat a DC of 15".
`chanceAtMost`	function	The chance of this total or less.
`chanceExactly`	function	The chance of exactly this total.
`chancesOf`	function	The chance of each face of one die of a group, from its lowest face up.
`checkMath`	function	Whether a formula can be used with kinds of dice whose totals run over these ranges: the problem, or null when there is none.
`checkNotation`	function	A spec from notation, or which part of the text was refused and why.
`chinchirorinHandWithin`	function	The chance that three dice make a chinchirorin hand within a number of throws: each throw makes one half the time, so three come to 7 in 8.
`chiSquareTail`	function	The upper tail of a chi-square distribution: the chance that a fair die strays at least this far.
`cliLanguage`	function	The language the command line speaks: `--lang`, or the environment's, or the system's; Japanese for `ja…`, English for anything else.
`CliResult`	type	What the command line came to.
`CliSurroundings`	type	What the command line is run in.
`Cloth`	type	A cloth's name.
`clothVars`	function	A cloth as the tray's CSS variables; nothing for a name that is not a cloth, so the tray keeps its own.
`Compare`	type	A number a die is compared with: at a face (`=`), at or below it (`<=`), at or above it (`>=`), or anything but it (`<>`).
`compareText`	function	A comparison as notation writes it: `>=8`, `=1`, `<>3`.
`countsSuccesses`	function	Whether a kind of dice is counted for successes, not added up.
`crapsPass`	function	The chance that a craps shooter passes: a natural on the come-out, or a point that comes again before a seven.
`createRollSound`	function	The tray's sound for one window.
`cryptoSource`	function	The platform's cryptographic generator, buffered so a roll of ten dice is one call.
`CSV_COLUMNS`	constant	The columns of the CSV export, in order.
`csvCell`	function	One cell of CSV.
`CustomFace`	type	One face of a custom die: what it says, what it is worth in a total if it is worth anything, and a colour for it.
`customFaces`	function	A custom die's faces, checked: the faces as given if every one is sound, or undefined.
`decodeDiceWar`	function	Text read back into the game it records, every move played again through the rules, so that what comes back is exactly the game those moves make.
`DEFAULT_SPEC`	constant	The dice a tray shows when nothing else is asked for: 2d6.
`DICE_WAR_LIMITS`	constant	What a table may be set up with.
`diceCount`	function	How many dice a roll asks for, over all its kinds.
`DiceGroup`	type	Some dice of one kind, with their own rules: the `2d20kh1` of `2d20kh1+1d4`.
`diceOf`	function	The dice of a roll: as recorded, or worked out from its faces for a roll made by hand or by an older version.
`DiceSet`	type	A set of dice with a name: a roll somebody wants to find again, such as "Longsword" for `1d8+3` or "Skirmish" for `2d[Hit=1,Miss=0,Miss=0]`.
`diceText`	function	The dice of a roll as plain text, in the order thrown: `6 4 2 (1)`.
`DiceWarChances`	type	What a total is worth against the other players' totals in one throw.
`diceWarComputerFaces`	function	A computer's dice for a throw: from the game's seed, the round, the war and the seat, so the same game always rolls the same.
`DiceWarGame`	type	A game of Dice War: its table, seed and moves (what is kept), and what they make.
`DiceWarGoal`	type	How a game is played to its end.
`DiceWarMove`	type	A move: the dice the people at the table rolled, by seat, such as `{ faces: { "0": [4] } }`.
`diceWarOdds`	function	The exact odds of one throw of Dice War among `players` players, from the package's own odds for the dice: the chance the throw is settled at once and the chance of war, and, for a total you name, how it fares against everybody else's.
`DiceWarOptions`	type	What a game of Dice War is set up with.
`diceWarOver`	function	Whether a game is over.
`diceWarPeopleToRoll`	function	The seats whose dice a move must hand in now: the people among those who roll.
`DiceWarRoll`	type	One player's roll in a throw: their faces, and what they add up to.
`diceWarSpec`	function	The dice a game rolls, as a spec the rest of the package reads.
`DiceWarThrow`	type	One throw of the table: everybody who had to roll, in seat order, the war it was in (0 for the round's first throw), the seats that tied for highest, and who took the stake: null where the throw was a tie and the war goes on, or the round was called off.
`diceWarWinners`	function	The seats that won a game that is over: the player who reached the score, or the most points when the rounds ran out, shared where level.
`DIE_SIDES`	constant	The dice the tray offers as buttons: the polyhedral set, the thirty-sided die, and the percentile die.
`DIE_SIZE_PX`	constant	The pixels of each size.
`DieHandle`	type	What `mountDie` hands back.
`dieName`	function	What one kind of die is called: `d6`, `dF`, a loaded `d6{6:3}`, a custom `d[Yes,No,Maybe]`.
`DieOptions`	type	What a lone die is told when it is made.
`dieOutcomes`	function	One die of a kind worked through its own rules, before any keeping or dropping: the chance of each amount it adds to the total, from `least` up.
`DieRoll`	type	One die of a roll: the face it showed and what became of it.
`DieSides`	type	One of the dice the tray has a button for.
`DieSize`	type	How big the die is drawn: 48, 96 or 150 pixels across.
`DieStatus`	type	One die as it was thrown.
`Distribution`	type	Exact odds for a spec, worked out rather than simulated: every total the dice can make and how likely it is.
`distributionHolding`	function	The odds of a roll with some of its dice held: the held faces are settled, and only the rest are still to be thrown.
`distributionOf`	function	Every total a spec can make and its chance.
`encodeDiceWar`	function	A game of Dice War as text: its table, its seed and its moves, which is all there is to keep.
`evaluateMath`	function	What a formula comes to, given each kind's total.
`exactCounts`	function	The odds as exact whole numbers, for the dice that have them: plain dice added up, one die kept from a pool (advantage), loaded and custom dice the same way (their weights are whole numbers, so their odds are exact fractions), and several such kinds added together while that stays quick.
`ExactCounts`	type	The odds as whole numbers: how many of the equally likely outcomes make each total.
`expectedHighest`	function	The average of the highest total among several throws of a roll.
`expectedTotal`	function	The average total over many rolls.
`ExplodeKind`	type	How exploding dice are added up: each as a die of its own, all into the die that threw them (`!!`), or with one taken off each extra die (`!p`), or both (`!!p`).
`EXPORT_FORMAT`	constant	The shape of the JSON this package writes.
`Exported`	type	A whole JSON export.
`exportedRoll`	function	One roll as the JSON export writes it.
`ExportedRoll`	type	One roll as the JSON export writes it.
`FaceChance`	type	One face of a die and how often it comes up, beside how often it would on a fair one.
`faceChances`	function	Every face of one die of a group with its chance, beside the fair die's.
`faceRange`	function	The lowest and highest face of one die.
`faceStats`	function	How often each face of one kind of die came up in a history, with a chi-square test of whether that looks fair.
`FaceStats`	type	How often each face of one kind of die came up, and whether that looks fair.
`Fairness`	type	What a fairness test makes of a die.
`FAIRNESS_MINIMUM_EACH`	constant	The fewest throws of each face a fairness test wants before it will say anything: the usual rule for a chi-square.
`fairnessTest`	function	Is this die fair?
`findPresets`	function	The presets a search finds: every word typed has to be in the name, another name, the one-line description or the notation.
`formatNotation`	function	Notation for a spec: the inverse of `parseNotation`.
`formulaText`	function	A formula's roll with each kind of dice written as it fell: `([6 1]+3)*2-[3]`.
`fromJSON`	function	Rolls from JSON that `toJSON` wrote, or a history that `serializeHistory` did.
`GameFamily`	type	The shelves the games are kept on.
`getPreset`	function	A preset by its id, its name or any of its other names: `getPreset("yahtzee")` and `getPreset("Yacht")` are the same game.
`groupOf`	function	The kind of dice one die of a roll belongs to, with its rules, faces and weights.
`groupRange`	function	The least and the most one kind of dice can total, its own rules applied.
`groupsOf`	function	The kinds of dice in a roll, in order: the spec's own first, then the rest.
`groupTotals`	function	What each kind of dice of a roll came to, in order: what a formula puts together.
`hasTotal`	function	Whether a roll's total says anything.
`HISTORY_LIMIT`	constant	A history keeps the latest rolls and forgets the oldest past this many.
`isCloth`	function	Whether a text names a cloth.
`isDieSides`	function	One of the dice the tray has a button for.
`isFair`	function	Whether a roll is of plain fair dice and nothing else: no loaded die, and no custom die either, whose faces are whatever somebody made them.
`isLoaded`	function	Whether a roll has a loaded die in it.
`isPlainDice`	function	Whether a kind of dice is plain enough to be rolled in any number: a fair numbered or Fate die, all added or one kept, under no other rule.
`isSides`	function	Any die this package can throw: two to a thousand sides, or a Fate die.
`isSuccessRoll`	function	Whether the first thing a roll says is a number of successes: every kind of dice in it is counted.
`Keep`	type	Which dice count towards the total.
`keptCount`	function	How many dice of one group count towards the total.
`keptFaces`	function	Which faces count towards the total when one is kept.
`KOROKORO_CLOTHS`	constant	THE CLOTHS A TRAY MAY BE LAID IN: the same five the whole family offers, and itsutsu.com's boards — green (the tray's own, unless said), blue, red, black, and wood.
`LOADED_PRESETS`	constant	Three loaded dice to try, each an old trick with a long record.
`LoadedPreset`	type	Loaded dice, kept in one place and in plain sight.
`loadedWeights`	function	A loaded die's weights, checked and in lowest terms: one whole number from 0 to `MAX_WEIGHT` for each face, at least two faces that can come up.
`loadHistory`	function	Read a kept history.
`loadingOf`	function	What a loaded die's loading comes to, as exact fractions, for the face it favours most: `{ face: 6, loaded: [3, 8], fair: [1, 6] }` is "6 comes up 3 in 8, not 1 in 6".
`loadSets`	function	The sets kept on a device.
`luckOf`	function	How lucky a total was, from 0 (the worst the dice can do) to 1 (the best): the share of rolls it beats, counting a tie as half.
`makeSet`	function	A set from a name and a roll, or null when the name is empty or too long or the dice cannot be rolled.
`MathFunction`	type	The functions a formula may call.
`mathGroups`	function	Which kinds of dice a formula uses, in the order it names them.
`MathNode`	type	Arithmetic over the kinds of dice in a roll: `(2d6+3)*2`, `1d20-1d4`, `floor(4d6/2)`, `max(1d6,1d8)`.
`MathProblem`	type	Why a formula cannot be used, when it cannot.
`mathRange`	function	The least and the most a sound formula can come to, given each kind's range.
`mathText`	function	A formula as notation writes it, with brackets only where they are needed.
`MAX_DICE`	constant	The most dice in one roll: a fireball's 8d6, Farkle's six and a pool of ten all fit.
`MAX_DICE_BY_CODE`	constant	The most dice in one roll made from code, for a caller that asks: `parseNotation(text, { maxDice })`, `normalizeSpec(spec, { maxDice })` and `roll(spec, source, { maxDice })` each take a roll past `MAX_DICE` up to this.
`MAX_EXPLODING_SIDES`	constant	The largest die that may explode: past this the exact odds stop being quick to count.
`MAX_EXPLOSIONS`	constant	How many more dice one exploding die may throw.
`MAX_FACE_VALUE`	constant	The largest number a custom face may be worth, either way.
`MAX_FACES`	constant	The most faces a custom die has, and the fewest is two.
`MAX_GROUPS`	constant	The most kinds of dice in one roll: `1d20+1d4` is two.
`MAX_LABEL`	constant	The longest a custom face's words may be, in characters.
`MAX_LOADED_SIDES`	constant	The largest die that may be loaded.
`MAX_MATH_AMOUNT`	constant	The largest amount, either way, any step of a formula may come to.
`MAX_MATH_DIVISOR`	constant	The largest bottom of a fraction any step may have: what it may be divided by, all told.
`MAX_MATH_NODES`	constant	The most steps a formula may have.
`MAX_MATH_NUMBER`	constant	The largest whole number written in a formula.
`MAX_MATH_PAIRS`	constant	The most pairs of amounts any one step of a formula's odds may have to put together.
`MAX_MATH_TOTALS`	constant	The widest span of totals a formula may have.
`MAX_MODIFIER`	constant	The largest bonus, either way: a roll adds or takes away at most this.
`MAX_REROLLS`	constant	How many times one die is thrown again by a reroll-until (`r<`).
`MAX_ROLL_LABEL`	constant	The longest a roll's label may be, in characters.
`MAX_SET_NAME`	constant	The longest a set's name may be, in characters.
`MAX_SETS`	constant	The most sets kept on one device.
`MAX_SIDES`	constant	The most sides a numbered die has.
`MAX_TIMES`	constant	The most times one roll may be repeated as a set: `6#4d6dl1` is six.
`MAX_UNIQUE_SIDES`	constant	The largest die whose dice may be asked to all differ (`u`).
`MAX_WEIGHT`	constant	The heaviest a face of a loaded die may be weighted.
`mayExplode`	function	Whether the dice may explode: numbered dice of a hundred sides or fewer, all of them kept.
`mayReroll`	function	Whether a reroll at this face leaves something to do: it must reroll the lowest face and spare the highest.
`mayRerollUntil`	function	Whether a die may be rerolled until it clears this face: the reroll must match the lowest face and no more than half of them.
`meets`	function	Whether a number meets a comparison.
`MIN_DICE`	constant	The fewest dice in one roll.
`MIN_SIDES`	constant	The fewest sides a numbered die has: a coin.
`mostLikely`	function	The most likely totals: several when the peak is flat, as it is for one die.
`mountDie`	function	Put one die in an element.
`mountRoller`	function	Put a dice tray into an element.
`newSeed`	function	A short seed anybody can read aloud or type: eight letters and digits.
`normalizeSpec`	function	A spec brought into range, so a hand-typed or stored one can never roll eleven dice, five kinds or a die with no faces.
`NotationCheck`	type	What `checkNotation` found: the spec, or the part it refused and why.
`NotationOptions`	type	How to read a notation.
`NotationProblem`	type	Dice notation, the way a character sheet writes it.
`Outcome`	type	How a roll is read in a game.
`OutcomeOdds`	type	One line of a game's odds: an outcome, the words for it, and its chance as a whole-number count of the equally likely throws.
`parseHistory`	function	A kept history read back from its text.
`parseNotation`	function	A spec from notation, or null when the text is not dice this roller can throw.
`parseSets`	function	Sets read back from their text.
`patternsOf`	function	Every way the dice of a spec can fall, kind by kind, each with how many of the equally likely throws fall that way.
`playDiceWar`	function	The game after this move, or null for one the rules refuse: the game is over, a person's dice are missing or are not dice of this game, or dice are handed in for a seat that does not roll them.
`playsByNewRules`	function	Whether a kind of dice is played by a rule added in 1.7.0, one that changes what it can total: a reroll or an explosion at a comparison, compounding or penetrating dice, `min` or `max`, or counted successes.
`PlaySound`	type	Anything that makes a roll's sound: the built-in one, or a page's own.
`Preset`	type	The dice for a game, and how the game reads them.
`presetOdds`	function	The exact odds of each outcome of a game's first roll: a natural in craps, each hand in chinchirorin, each result of a Risk battle.
`PresetReading`	type	What a game makes of a roll: the outcome, and the words for it.
`PresetRoll`	type	A game's dice thrown and read.
`presets`	constant	Game presets with their dice, readings and English/Japanese help.
`PRESETS`	constant	Game presets with their dice, readings and English/Japanese help.
`presetSpec`	function	A preset's dice, as a spec.
`randomInt`	function	A fair integer in [0, n).
`RandomSource`	type	Where the randomness comes from.
`rangeOf`	function	The lowest and highest totals a spec can produce.
`readDice`	function	What happened to each die of a roll, from its faces alone: which were rerolled, which exploded, which were dropped.
`readDiceAs`	function	Read a roll the way a reading does, with the rolls before it in the same game where that matters.
`READING_WORDS`	constant	English and Japanese outcome text, keyed by reading.outcome.
`ReadingId`	type	The name of a reading.
`readPreset`	function	Read a roll the way a game does.
`readResults`	function	Results typed or pasted from a real die, such as `3 5 6 6 1` or `3,5,6`: whole numbers separated by spaces, commas or new lines.
`readSet`	function	A set from a link's query, or null when it holds none or its dice cannot be rolled.
`readShared`	function	A shared roll from a query string, or null when it does not describe one this roller could have thrown.
`readSharedMany`	function	A shared set of rolls from a query string, or null when it does not hold one: as many rolls as the notation's `#` says, each with faces its dice could show.
`resultText`	function	A roll's result as it would be said: its total, or for dice that are only words, the words.
`roll`	function	Throw the dice.
`Roll`	type	One throw of the dice: what was asked for, every die thrown, and the total.
`RollerHandle`	type	What `mountRoller` hands back: the tray, driven from code.
`RollerOptions`	type	Everything a tray can be told when it is mounted.
`RollerSize`	type	How much of the tray is drawn: the felt alone, the felt and the choice of dice, or all of it.
`RollerStrings`	type	Every word the tray says, in English and Japanese.
`rollFrom`	function	A roll put back together from its spec and its faces: for a history read from storage and a roll read from a link.
`rollHeld`	function	Hold some dice of a roll and throw the rest again, as Yacht and Farkle do.
`rollLabel`	function	A roll's label, checked: a few words with no control characters and nothing notation is written with, or undefined.
`rollMany`	function	Throw the same dice several times in one go, as ability scores are rolled: `4d6dl1` six times.
`RollOptions`	type	What `roll` and `rollMany` may be told beside the dice and the source.
`rollPreset`	function	Throw a game's dice and read them.
`RollSet`	type	The same roll thrown several times in one go, with what the set comes to.
`RollSound`	type	The tray's own sound: `play` for each throw, `close` when the tray goes.
`RollSpec`	type	What to roll: the dice, the bonus, and the rules.
`rollText`	function	One roll on one line: `2d20kh1+5: 22 [17 (4)]`, or for a formula `(2d6+3)2: 20 ([6 1]+3)2`.
`rulesText`	function	The modifiers of one kind of dice as notation writes them, in the one order they are written: `>=8f=1!`, `r<3kh3`.
`runCli`	function	Run the command line.
`saveHistory`	function	Keep a history.
`seededSource`	function	sfc32 started from a text seed: the same seed gives the same rolls on every platform, forever.
`serializeHistory`	function	A history as text, to keep in a browser's storage or anywhere else.
`serializeSets`	function	Sets as text, to keep in storage.
`setOf`	function	What a set of rolls comes to: their sum, the highest and the lowest.
`setQuery`	function	A set as a link's query: the dice and the name, for anybody to open and keep.
`SHARE_VERSION`	constant	The version of the notation a link is written in.
`shareQuery`	function	A roll as a link.
`shareQueryMany`	function	A set of rolls as a link: the notation with its `6#`, and every roll's faces, the rolls parted by semicolons.
`Sides`	type	A die of any size from a coin to a d1000, or a Fate die, whose faces are −1, 0 and +1.
`sidesOf`	function	The kind of die one die of a roll is.
`soundMath`	function	A formula given by hand, checked for its shape alone: the nodes are what they say they are.
`SoundThrow`	type	The sound of a roll: a shake while the dice tumble and a knock as each one lands.
`specOf`	function	A spec from its kinds of dice and a bonus, brought into range.
`spreadMath`	function	The odds of a formula: the chance of each whole number it can come to, given the chance of each total of each kind of dice.
`spreadOf`	function	How far a typical roll lands from the average.
`startDiceWar`	function	A new game, or null for a table it is not played at: fewer than two or more than eight players, dice or sides out of range, a goal out of range.
`Stats`	type	Everything worth saying about a history of rolls.
`statsOf`	function	Stats for a history, oldest roll first.
`StorageLike`	type	The storage a browser offers, or anything shaped like it.
`storeSets`	function	Keep the sets.
`STRINGS`	constant	The built-in words, in English and Japanese.
`toCSV`	function	Rolls as CSV for a spreadsheet: a header, then a row for each roll, lines ended CRLF as RFC 4180 has them.
`toJSON`	function	Rolls as JSON, two spaces deep, with the format's number first.
`totalOf`	function	The kept faces added up, plus the bonus.
`totalStats`	function	The totals of every roll of one spec in a history, beside what the odds expect.
`TotalStats`	type	The totals of one spec: seen against what the odds promise.
`toText`	function	Rolls as plain text, one to a line, each with its time in UTC, oldest first as given.
`TypedResults`	type	What `readResults` found in somebody's typed results.
`valueOfFace`	function	What a face of a group's die is worth in a total: its number, or for a custom face its value, which is 0 when it is only words.
`VERSION`	constant	The version of this package, as `package.json` has it.
`waysToShut`	function	Every way to make a total from different numbers 1 to 9, largest first: the tiles a Shut the Box roll may shut.
`withoutSet`	function	The sets without the one of that name.
`withSet`	function	The sets with one added, newest first.
`yahtzeeWithin`	function	The chance of a Yahtzee (five dice alike) within a number of rolls, holding the largest group each time: 1 roll is 1 in 1296, and the usual three come to 347897 in 7558272, about 4.6%.

View source Edit on GitHubMade from the source of @johnmorrisdotca/korokoro 1.16.0.