Skip to the content

Sugoroku documentation

Sugoroku API: every export

Every export of every entry point, each with its own page. This page keeps the addresses the old one-page reference had.

@johnmorrisdotca/sugoroku/draw

BoardLayoutclass

The layout of a board, a function of its options: where each point, the bar, each tray, the rail and the dice sit, all in landscape units.

BoardOptionstype

The cube, viewing side, home direction and orientation used to calculate board geometry.

boardSizefunction

The width and height the board is drawn in, which is the other way about when it stands up.

Boxtype

A box: where something is, in landscape units before any turning.

colourStylefunction

The inline custom properties of a drawing: the named board and checkers, then any colour given.

MOST_DRAWNconstant

How many checkers are drawn on a stack before the last one carries the count.

Orientationtype

Whether the board lies across the page or stands up in it.

SUGOROKU_BOARDSconstant

The boards the drawing knows by name, set against any theme.

SUGOROKU_COLOUR_NAMESconstant

The names of the colours, as the custom properties spell them (--sg- and the name in kebab case).

SUGOROKU_STYLEconstant

THE STYLE a Sugoroku board is drawn with: colours as custom properties (--sg-felt, --sg-white and the rest of SugorokuColours), light by default and dark when the device is, and the one rule that matters for a game played with fingers and a mouse: nothing on the board can be selected, dragged or double-tapped.

@johnmorrisdotca/sugoroku/play

createSoundsfunction

A player for the sounds, which makes its audio only when first asked to play, as browsers insist on a gesture first.

ensureSugorokuPlayStylefunction

Put the style in the page once: in the document's head, or in the shadow root the host is in.

packagedSoundsfunction

The sounds' addresses beside the package's code, or an empty set where import.meta.url is not an address (some test runners).

SoundNametype

THE SOUNDS OF A BOARD, optional: a checker set down, a checker hit, the dice and the cube.

SoundPlayertype

Optional board-sound playback and cleanup methods.

SUGOROKU_PLAY_STYLEconstant

THE STYLE a playable Sugoroku board wears (mountSugoroku, <sugoroku-board>): the drawing's own (SUGOROKU_STYLE), the board's box, its buttons and its lines of words.

SUGOROKU_STRINGSconstant

The native English and Japanese labels, announcements and interpolation templates.

SugorokuLanguagetype

THE WORDS A SUGOROKU BOARD SAYS, in English and Japanese: the buttons, the line that says whose turn it is and what to do, and the result of a game.

sugorokuLanguageOffunction

The language an element or its page is in: its own lang, or the nearest above, and English unless that begins with ja.

SugorokuMounttype

The mounted native board, current game/match/record, actions and cleanup handle.

SugorokuMountOptionstype

Native variant, rules, seed, computer, display, control, sound and event-callback choices.

sugorokuSayfunction

A line in a language with its {name}s filled in.

@johnmorrisdotca/sugoroku/element

defineBoardfunction

Defines the default playable board, or a subclass under a custom tag.

definePositionfunction

Defines a static position, or a subclass under a host's tag.

readEmbedPositionfunction

Reads a GNU position ID or bounded JSON position; null means invalid counts or input.

SugorokuBoardclass

Native custom element with reflected setup and presentation.

SugorokuPositionclass

A read-only backgammon position, drawn by the native SVG writer.

@johnmorrisdotca/sugoroku/element/define

defineBoardfunction

Defines the default playable board, or a subclass under a custom tag.

definePositionfunction

Defines a static position, or a subclass under a host's tag.

readEmbedPositionfunction

Reads a GNU position ID or bounded JSON position; null means invalid counts or input.

SugorokuBoardclass

Native custom element with reflected setup and presentation.

SugorokuPositionclass

A read-only backgammon position, drawn by the native SVG writer.

@johnmorrisdotca/sugoroku

agreeDrawfunction

The game drawn by agreement.

allHomefunction

Whether every checker of side still in play is in its home board (own points 1 to 6): the condition for bearing off.

BARconstant

The number a move's from has when a checker comes from the bar (or from off the board at the start of a race).

beaverDoublefunction

Beaver: the side that was doubled redoubles and keeps the cube; the side that doubled must now take it or drop it.

boardPointfunction

The point on the board, 1 to 24 counting the way white counts, that is side's own point own.

canBeaverfunction

Whether the side that was doubled may beaver: redouble at once and keep the cube.

canDoublefunction

Whether the side on turn may offer a double now.

canPlayAllfunction

Whether every die of need (highest first) can be played from position, in some order.

chanceOfWinningfunction

The chance, 0 to 1, that side wins from here, by the evaluation, or by the Keith count's rule of thumb in a race (as 0.5 plus a share of the count's lead).

checkersOffunction

The whole count of each side's checkers: on the board, on the bar, yet to enter, and off.

choosePlayfunction

The play the computer makes for the rest of the turn of the side on turn, from the plays the rules leave it.

computerActionfunction

What the side that has to act in a game would do, if the computer were playing it.

ComputerActiontype

What the computer does next in a game, for the side it plays.

ComputerOptionstype

Strength, tie-breaking randomness, lookahead time budget and evaluation weights for computer decisions.

concedefunction

Give up the game: side loses.

concedeKindfunction

What a side gives up if it gives up the game now, which is the worst the position could come to: a single game once it has borne a checker off; a gammon if nothing of the other side's can still hit it; otherwise a backgammon where it may have a checker caught in the other side's home board.

countAtfunction

How many of side's checkers stand on its own point own (1 to 24).

Cubetype

The doubling cube: what it shows, and who may turn it (null while it stands in the middle, for either).

cubeInPlayfunction

Whether the cube is in play in a game of a match, given whether this is the Crawford game.

cubeIsDeadfunction

The cube is dead when turning it could not matter: it already shows enough for either side to win the match with a win.

DEFAULT_RULESconstant

The rules a variant is played with when nothing else is asked: a single game with no cube and no gammons.

DiceSourcetype

Where dice come from: each call is the number on one die, 1 to 6.

diceToPlayfunction

The dice a roll gives to play, highest first: a double of a game that plays doubles four times is four of them.

Directiontype

How the sides' tracks lie on the board.

dropDoublefunction

Drop the double that was offered: the side that drops it loses the game, at the cube's value before the double, or for a beaver at its value once the double was taken.

endTurnfunction

End the side on turn's turn, once everything it had to play has been played.

evaluatefunction

The score of a position for side, with the other side to move, as a game where bearing off first wins.

evaluateForfunction

The score as side plays to win or to lose: a game played to lose is judged the other way up.

EVALUATION_WEIGHTSconstant

The weights the computer plays with: set by hand and then held against random changes of themselves, none of which won more often over two thousand games.

finishGamefunction

The match after a game's result: the score added up, the Crawford game accounted for, and the match over if it is decided.

formatMovefunction

One move as text: 24/18, bar/22*, 6/off.

formatPlayfunction

The text of a whole turn: moves of one checker joined, equal moves counted, the farthest-back checker first.

formatPositionfunction

A position as text, for any variant: each side's checkers as point:count in that side's own numbering, highest point first, then the bar, those yet to enter and those borne off, [white, black] each.

formatRecordHeaderfunction

The header lines of a record: its version, the variant, the rules and the seed.

formatResultfunction

The line that closes a game, with what it came to.

formatTurnfunction

One line of a game: a turn, with its dice and its play.

GameResulttype

The decided winner, ending, win kind, cube multiplier and points.

GameStatetype

The immutable game phase, board, dice, remaining moves, cube and optional result.

Goaltype

What it takes to win.

hashSeedfunction

A whole number from a seed given as a number or as text: the same seed is always the same number, in every browser and every Node.

Hoptype

A step of a written play: one checker, one die's distance (or off), as written.

inContactfunction

Whether the two sides can still hit one another.

inPlayfunction

Every checker of side that is still in the game: on the board, on the bar or yet to enter.

keithCountfunction

The Keith count of a side, a pip count corrected for how badly the checkers are placed for bearing off: plus 2 for each checker beyond the first on the 1-point, 1 for each beyond the first on the 2-point and beyond three on the 3-point, and 1 for each empty point among the 4, 5 and 6, and then the side on roll adds a seventh (rounded down).

legalMovesfunction

The moves the side on turn may make next.

legalPlaysfunction

Every different turn a side may make with a roll: one for each position that playing the roll as the rules require can leave, with one way of getting there.

legalPlaysOffunction

Every different way the side on turn may play out the rest of its turn: for the dice it has yet to play, from where the position stands now.

Matchtype

A MATCH: games played one after another to a number of points, or without end in money play.

mirrorPointfunction

The other side's own number for the point that is side's own point own.

Movetype

ONE CHECKER MOVED BY ONE DIE, in the mover's own numbering: from its own point from (or the BAR, 25, for a checker entering from the bar or from off the board at the start of a race) to its own point to (0 for borne off).

movesOfDiefunction

Every move of one die that side may make from position, one for each point a checker can start from.

multiplierOffunction

What a win of kind is worth, after the rules: a single win when gammons do not count, or when the Jacoby rule holds them back because the cube was never turned.

newGamefunction

A new game, waiting for the opening throw.

nextMovesfunction

The moves that may be made next, by a side that still has the dice need (highest first) to play from position: every move that leaves the rest of need playable.

offerDoublefunction

Offer a double: the other side must now take it or drop it.

onBoardfunction

How many checkers side has on the board's points, not counting the bar, the reserve and those borne off.

openingFromfunction

An opening throw from a source: one die for white and one for black.

opponentAtfunction

How many of the other side's checkers stand on the point that is side's own point own.

parseHopsfunction

The hops a written play names, in the order written: a chain of three points is two hops, and 13/11(2) is two.

parsePlayfunction

The moves a written play makes with a roll, or null if it is not a legal play of that roll.

parsePositionfunction

The position that text of formatPosition's kind stands for, or null if it is not one.

Phasetype

Where a game has got to.

pipCountfunction

The pip count of a side: the sum of every checker's distance from being borne off.

Playtype

A WHOLE TURN: the moves a side makes with a roll, in the order it makes them, and the position they leave.

playMovefunction

Make one move for the side on turn, given as the checker's own point it leaves and the one it goes to.

playMovesfunction

The position after a list of moves, made one after another.

playTurnfunction

Make a whole play (the moves of legalPlays) for the side on turn and end the turn.

POINTSconstant

The points on the board.

pointsToGofunction

How many points a side still needs to win the match: 0 in money play, where there is no such thing.

positionFromIdfunction

The position an ID stands for, with onRoll to move, or null if the text is not an ID.

positionIdfunction

The ID of a position with onRoll to move, or null if it cannot be written in this form.

positionKeyfunction

A position as a short string that is the same for the same position, for keeping a set of them.

Presettype

A NAMED WAY OF PLAYING: a variant with its rules.

presetByKeyfunction

The preset with this key, or undefined.

presetByNamefunction

The preset a site's printed name leads to, or undefined.

PRESETSconstant

Every named way of playing, in the order of docs/VARIANTS.md.

Randomtype

A source of random numbers from 0 up to but not including 1.

randomDicefunction

Dice that are not seeded: from the device's own random numbers.

RECORD_VERSIONconstant

The record format's version, the number after sugoroku on the first line.

RecordSeedtype

A seed in a record: all digits means a number, anything else is text.

ReplayErrortype

A refused record with its one-based line number and reason.

ReplayOktype

A successfully validated record, its settings, completed games and optional current game.

resolveRulesfunction

The rules with anything left out filled from DEFAULT_RULES.

rollDicefunction

Roll the dice for the side on turn, which must not be waiting on an answer to a double.

rollFromfunction

A roll of count dice from a source.

rollOpeningfunction

The opening throw: one die for white and one for black.

Rulestype

HOW A GAME IS SCORED AND STAKED, beside the variant's board.

rulesProblemsfunction

What goes wrong with a set of rules, as sentences; empty when they are fine.

seededDicefunction

A SEEDED DICE SEQUENCE: the same seed is the same dice, one die after another, in every browser and every Node, so a game can be played again from its seed and a server can tell whether the dice a game says it had are the dice it should have had.

seededRandomfunction

The mulberry32 stream: the same seed makes the same numbers everywhere.

Settingstype

The settings of a game: the variant's row and the rules.

settingsForfunction

Settings from a variant key (or a row) and rules, left-out rules filled in.

Sidetype

THE TWO SIDES.

sideIndexfunction

0 for white and 1 for black: where a side's counts are kept in a position.

SIDESconstant

Both sides, white first.

sideToActfunction

Whether a side is the one the computer would act for at this moment of a game: the side on turn, or the side that must answer a double.

startCountsfunction

Which points a side's checkers start on, as an array indexed by own point 1 to 24 (index 0 is point 1).

startGamefunction

The first game, or the next game, of a match.

startReservefunction

How many checkers each side begins off the board, to be entered with the dice.

stepComputerfunction

Carry out one step of what the computer would do, with dice from dice.

Strengthtype

THE COMPUTER PLAYER, in four strengths.

STRENGTHSconstant

The strengths, weakest first.

takeDoublefunction

Take the double that was offered.

turnIsPlayedfunction

Whether the turn is played out and the side on turn has only to end it.

undoMovefunction

Take back the last move made this turn.

VARIANT_KEYSconstant

The variants' keys, in the order the demo lists them.

VariantSpectype

A native variant’s checker counts, starting layout, dice, directions, opening and winning goal.

VERSIONconstant

The package's version.

wantsToDoublefunction

Whether the computer, to move before it rolls, should offer a double.

wantsToTakefunction

Whether the computer, doubled, should take.

winChancefunction

A chance of winning, 0 to 1, that a score in pips stands for: the logistic curve, which a lead of 25 pips in a position of this kind takes to about three in four.

winKindfunction

The kind of win a game that winner has won by bearing off is: single, gammon or backgammon, before the rules say what they count for.

WinKindtype

What kind of win it was, which is how many times the cube's value it scores.

withCountsfunction

A copy of a position with some counts changed.