Reference

Rules and records

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

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

Narabe 並べ: one rules engine for forty-eight abstract board games.

Every game is a row of data (VARIANT_SPECS), and every function takes a GameState and returns a new one. Start with createGame, play with playMove, movePiece, placePiece, twistBoard or passTurn, and ask turnChoices what the player to move may do. Records are plain move lists: replayMoves and replayGame read them back, undoMove steps one back.

Deeper pieces (each rule module on its own) are reachable by path as well, for example @johnmorrisdotca/narabe/rules/go.

Exports

Name	Kind	What it is
`ALL_BOARD_SIZES`	constant	Every size any game here is played on, for the schemas at the API edge.
`availableOpenings`	function	The openings these settings may use: what the variant offers, less the colour-swapping ones when a handicap is bound to a colour — and only the free opening under a head start.
`Blocked`	type	An intersection the rules have taken out of play.
`BLOCKED`	constant	The unavailable-cell marker.
`BOARD_GRIDS`	constant	Where a game's stones sit when it is drawn its own way: on the crossings, or in the squares.
`BOARD_SIZES`	constant	Board is `size` × `size`.
`BoardGrid`	type	Where a game's stones sit when it is drawn the way it is traditionally played: on the crossings of the lines, as in go and gomoku, or inside the squares, as in tic-tac-toe, Othello and checkers.
`boardSizesFor`	function	The board sizes a variant plays on, smallest first — the order they are drawn in.
`BRAZILIAN_DRAUGHTS_RULES`	constant	Brazilian draughts: the international rules of capture and crowning on 8×8, with twelve men, and the draws of the Brazilian confederation's own rules (CBJD, Regras Oficiais) rather than the FMJD's 8×8 set, which differs.
`campOf`	function	Whose home camp `point` lies in, or null for the open board.
`campSize`	function	Pieces a side has on `size`: the squares of its camp.
`campSquares`	function	The squares of a colour's home camp.
`CANADIAN_CHECKERS_RULES`	constant	Canadian checkers: the international rules on 12×12, thirty men a side in five rows.
`canBeDrawn`	function	Whether this game can be drawn at all.
`canChooseColour`	function	Whether the game is waiting on a seat to pick a colour.
`canExtendOpening`	function	Swap2 only: the first chooser may add two stones and pass the choice back.
`canForfeit`	function	Whether a recorded forfeit could have been written here: only where the clock had no pass to write instead.
`canGrowBoard`	function	Whether resizing is enabled and a larger native board is available.
`canPass`	function	Whether passing is on offer: forced in a piece game with nothing to lay, free at any point in Go.
`canShrinkBoard`	function	Whether resizing is enabled and a smaller native board is available.
`canSkip`	function	Whether skipping is enabled and a legal corner stone can burn the turn.
`canSwapSeats`	function	Whether the seat to play may trade seats right now.
`canTwist`	function	Whether the colour to move owes a quarter turn before the move is complete.
`canUndo`	function	Whether undo is enabled and a recorded move can be removed.
`CAPTURE_CHOICES`	constant	The free-choice and maximum-capture draughts modes.
`CaptureChoice`	type	Which capture a checkers-family player may choose, when more than one is on offer.
`capturePaths`	function	The squares each capture has passed through so far, move by move, or null for a move that took nothing.
`Cell`	type	One intersection of the board: a stone, an obstacle, a hotspot, a wormhole, or nothing.
`cellAt`	function	Read a cell from a valid zero-based board point; null means empty.
`centreSquares`	function	The four centre squares, top-left first.
`checkersHasCapture`	function	Whether any of `stone`'s pieces on the board has a capture available right now.
`CheckersRules`	type	How one game of the checkers family is played, as data: the rows of men each side sets out, which way a man may take, how far a king may travel, which capture must be chosen, and what crowning does to a capture under way.
`chooseColour`	function	The deciding seat takes `stone`.
`ColourRules`	type	The rules one colour actually plays under: the variant's spec for that colour with the handicap laid over it.
`COLUMN_LETTERS`	constant	Column letters used in coordinate labels, left to right.
`columnLetter`	function	Column letter, left to right: A, B, C ...
`createGame`	function	Create an initial immutable position from native settings and an opening roll.
`CROWN_MID_CAPTURE`	constant	The supported promotion behavior during a capture chain.
`CrownMidCapture`	type	What becomes of a man that reaches the far row in the middle of a capture.
`DEFAULT_BOARD_SIZE`	constant	The default side length for an unconstrained board.
`DEFAULT_CAPTURES_TO_WIN`	constant	Enemy stones to capture for a win in the capture game: five pairs.
`DEFAULT_SETTINGS`	constant	The defaults used when creating a game without overrides.
`DEFAULT_SWAPS_PER_SEAT`	constant	The default seat-swap allowance for each player.
`defaultBoardFor`	function	The board a game OPENS on, where nothing else has said: its own `defaultBoard` if it has one, else the first of its boards.
`DIRECTIONS`	constant	The four line orientations through a point.
`discCount`	function	Count black and white discs currently on a board.
`DRAW_LIMIT_LIST`	constant	The selectable configured game-length limits.
`DRAW_LIMIT_MIN_POINTS`	constant	The smallest board a length means anything on, in points.
`DRAW_LIMIT_SHARE`	constant	The board fractions used by configured draw limits.
`DRAW_LIMITS`	constant	The shares of the board a game may be called a draw at.
`DrawLimit`	type	When a game nobody has won is called a draw.
`drawnByLength`	function	Whether a finished game was drawn because it ran to its length, rather than because the board filled or both sides made a line at once.
`dropTarget`	function	Where a stone dropped into `col` lands, or null when the column is full.
`emptyPoints`	function	Every intersection still open: no stone, no obstacle.
`endedWithNoMoves`	function	Whether the game ended because neither side had a move: two forced passes, the last two moves on the record.
`ENDGAME_COUNT_KINDS`	constant	The specific-ending and material-balance draw count modes.
`EndgameCount`	type	An ending that must be won within so many moves or it is a draw, once each player has made `movesEach` more moves inside it.
`EndgameCountKind`	type	The two shapes an endgame count is written in — see `EndgameCount`.
`endsOnItsOwn`	function	Whether the rules alone guarantee this game ends.
`ENGLISH_CHECKERS_RULES`	constant	English draughts, American checkers: three rows of men, a man takes forward only, a king moves one square, any capture may be chosen, and a man crowned by a capture ends the move there.
`extendOpening`	function	The chooser declines to choose and lays two more stones instead.
`findWinningLine`	function	The winning line through `point`, if the stone there completes one under the rule that applies to its colour.
`FIRST_PLAYERS`	constant	The supported opening colours and random opener choice.
`FIRST_STONE`	constant	Black opens unless the settings say otherwise.
`FirstPlayer`	type	Who opens.
`flipsAt`	function	The discs a stone of `stone` at `point` would turn.
`footprintAt`	function	The absolute cells of an orientation anchored with its origin at `anchor`.
`footprintFits`	function	Whether every cell of a footprint is on the board and empty.
`FORBIDDEN_PATTERNS`	constant	The named forbidden shapes checked by line games.
`forbiddenAt`	function	Why `stone` may not play `point`, or null when it may.
`ForbiddenPattern`	type	Shapes a colour may be forbidden from making.
`forbiddenPoints`	function	Every empty point the colour to move is forbidden from playing right now.
`forbiddenReason`	function	Why the colour to move may not play `point`, when a forbidden shape is why.
`forfeitOnRecord`	function	A missed turn, as the position the record will replay it to.
`forfeitTurn`	function	Takes the turn away from the colour to move without a stone: the graceful penalty for a missed deadline.
`GAME_STATUS`	constant	The playing, won and drawn outcome labels.
`GameSettings`	type	Native rule, layout, opening, handicap and optional action settings.
`GameState`	type	The complete immutable position and its move history, seats and outcome.
`GameStatus`	type	Whether the game is playing, won or drawn.
`groupAt`	function	The connected group of stones sharing the colour at `from`, and the empty points touching any of them — its liberties.
`growBoard`	function	Returns the game on a larger board, or the state unchanged when it cannot grow.
`Handicap`	type	Extra restrictions one colour plays under, so a stronger player can give a weaker one a fair game.
`HANDICAP_RULES`	constant	The handicap toggles, in the order the settings list them.
`HandicapRule`	type	The toggles of a handicap, without the colour that carries them.
`HandicapTerms`	type	EVERYTHING THAT MAKES A GAME UNEVEN ON PURPOSE, as `hasHandicap` reads it: the per-colour handicap and the head start.
`hasFlipMove`	function	Whether the colour has a legal disc-flipping move.
`hasHandicap`	function	Whether any handicap is in force for anyone: harder rules for one colour, or a head start for one.
`HEAD_START_FREE_TURNS`	constant	The free turns a head start may give, none included.
`HeadStart`	type	A start given to one colour — the weaker player's — before the game is even.
`HeadStartTurns`	type	The most free turns a game offers as a head start: 0 where it offers none.
`HEX_LINE_DIRECTIONS`	constant	The three line orientations on the hexagon lattice — see rules/hexagon.ts for the embedding.
`Hot`	type	A hotspot: an intersection that counts as either colour's stone in a line.
`HOT`	constant	The cell marker that counts as either colour in a line.
`indexOf`	function	Convert a board point into its row-major array index.
`inLayingPhase`	function	Classic reversi: the first four discs are laid by the players, in the centre, with no flipping.
`inMovePhase`	function	Whether the colour to move has all its pieces down and must now slide one.
`INTERNATIONAL_DRAUGHTS_RULES`	constant	International draughts, from the FMJD's official rules (Annex 1, 2018, and the 2024 Annexes).
`isDarkSquare`	function	Checkers is played on one colour of square only: the board's own dark squares.
`isKingAt`	function	Whether the piece at `at`, if any, is a king.
`isLegalMove`	function	Whether the colour to move may play `point`: on the board, empty, allowed by the opening, not a shape the variant forbids that colour, the landing cell of its column in a drop game, and not while a twist or a slide is owed.
`isOnBoard`	function	Whether both coordinates are within the square board.
`isStone`	function	Narrows a cell to a played stone, excluding empties and obstacles.
`KOMI`	constant	Go: stones never move once played, and nothing about a line ever decides anything.
`landingPoints`	function	The one landing cell per column with room: the only cells a drop can fill.
`lastMove`	function	The point of the latest stone or piece move; null when no point was played.
`leavesNoStone`	function	Whether a recorded move put nothing on the board: a pass, or a turn the clock took away.
`legalPoints`	function	Every intersection the colour to move may play right now.
`LINE_RULES`	constant	The at-least, exact and open-exact winning line modes.
`lineDirectionsFor`	function	The directions a winning line may run: the hexagon's three axes on a hexagon board, the square's four otherwise.
`LineRule`	type	What a completed line has to look like to win.
`longestPossibleGame`	function	The most moves a game of these settings can contain, or null when nothing in the rules bounds it.
`Move`	type	A move rebuilt by the engine, including captures and other replay effects.
`MOVE_KINDS`	constant	The stable labels used in move records.
`MOVE_NARROWINGS`	constant	The reasons a move list is restricted to captures.
`MoveInput`	type	The shape of a move as a record or a request carries it, without the colour.
`MoveKind`	type	`place`: an ordinary stone.
`MoveNarrowing`	type	A rule that has narrowed the moves on offer below what the pieces could make: a capture that must be made, or carried on, instead of a step; or — where the game takes the most — the capture taking the most pieces, over shorter ones the pieces also have.
`movePiece`	function	Slides a piece one step, or in checkers a step or a capture.
`movesBeforeDraw`	function	How many moves may be played before a game nobody has won is a draw, or null when it is to be played out.
`mustPass`	function	Whether the colour to move has nothing it may play.
`nextBoardSize`	function	The next size up, or null when the board is already the largest.
`NO_HANDICAP`	constant	The default terms with no colour-bound rule restrictions.
`NO_HEAD_START`	constant	Nobody given a start: the even game, which is most games.
`NO_POINT`	constant	A pass has no point on the board.
`noBoundReason`	function	What stops this game being bounded by its board, or null when nothing does.
`NoBoundReason`	type	Why a game has no bound, or null when the board is its bound.
`normaliseSettings`	function	Settings that agree with their variant: a pinned line length wins over the player's choice, an opening the variant does not offer falls back to free, and a handicap rules out the openings that swap colours.
`OBSTACLE_LAYOUTS`	constant	The native empty and star-point obstacle layouts.
`ObstacleLayout`	type	`none`: every intersection is playable.
`OPENING_CHOICE_EXTEND`	constant	The one opening choice that is not a colour.
`OPENING_RULE_LIST`	constant	All supported opening identifiers in display order.
`OPENING_RULES`	constant	The stable identifiers for supported opening protocols.
`OPENING_STAGES`	constant	The stages of the opening protocol.
`OpeningChoice`	type	A decision taken during the opening: a colour, or two more stones.
`OpeningRule`	type	How the first stones go down.
`OpeningStage`	type	Where a swap-style opening stands.
`OpeningState`	type	The opening protocol stage, acting seat and recorded colour choices.
`orientations`	function	Every distinct way the piece can lie: four rotations, each also mirrored.
`orientCells`	function	The piece turned `turns` quarter turns and, if asked, mirrored — the shape a player has in hand.
`otherStone`	function	The other stone colour.
`passesOwed`	function	The position after every pass the rules force: none when the colour to move has something to play, one when only it is stuck, and two — ending the game — when neither side can move.
`passTurn`	function	Takes a turn without a stone.
`Piece`	type	A piece from the queue: its cells relative to the top-left of its bounding box.
`PIECE_PREVIEW`	constant	How many queued pieces a player is shown ahead of the one in hand.
`PIECE_QUEUES`	constant	The domino and tetromino queue identifiers.
`PieceCell`	type	One cell of a multi-cell piece, with the colour it carries.
`pieceMoves`	function	Where a piece of the colour to move may step from `from`; empty if it may not move.
`piecePlacements`	function	Every legal footprint of the piece in hand.
`PieceQueue`	type	Which queue of pieces a game draws from.
`piecesHome`	function	How many of `stone`'s pieces stand in the far camp.
`PieceTally`	type	A side's pieces, as an endgame count names them.
`Placement`	type	Where a stone goes when played.
`PLACEMENTS`	constant	The free, dropped and supported-edge placement modes.
`placePiece`	function	Lays the piece in hand on `cells`.
`playMove`	function	Plays the stone to move at `point`.
`Point`	type	Zero-based board coordinates.
`pointName`	function	Renju-style name for an intersection, e.g.
`pointOf`	function	Convert a row-major array index into board coordinates.
`POOL_CHECKERS_RULES`	constant	Pool checkers, from the American Pool Checker Association's Tournament Rules of Play (2016): men take both ways (rule 14), kings fly (15, 18), any capture may be chosen — "not compelled to take the greater or lesser number" (20) — and a capture once begun is completed (21).
`previousBoardSize`	function	The next size down, or null when the board is already the smallest.
`quadrantCount`	function	How many quadrants a board of this size holds.
`quadrantOrigin`	function	The top-left corner of quadrant `quadrant`.
`queuedPiece`	function	The piece the colour to move must lay next, or null outside the piece games.
`ReplayFacts`	type	What a replay needs to know about a record that its moves cannot say.
`replayGame`	function	The position as it stands now.
`replayMoves`	function	Replays a record through the engine: every position it passed through, including the ones a swap-opening decision produced.
`replayTimeline`	function	Rebuilds every position a game passed through by replaying its moves.
`resign`	function	Gives the game up.
`resolveOpener`	function	The colour that opens.
`resolvePlacement`	function	Where a stone played at `point` actually goes: the same point, or in a drop game the bottom of its column.
`rowNumber`	function	Row number counted from the bottom edge, so the bottom row is 1.
`RULE_VARIANT_LIST`	constant	The variants in the order the browser and the filters list them.
`RULE_VARIANTS`	constant	The stable identifiers for all forty-eight rule variants.
`rulesFor`	function	The rules a colour plays under: the variant's spec for that colour, with the handicap laid over it when the handicap belongs to that colour.
`RuleVariant`	type	The named rule sets.
`RUSSIAN_DRAUGHTS_RULES`	constant	Russian draughts (shashki), from the Russian Draughts Federation's rules (ФШР, shashki.ru) and the FMJD/IDF rules for 8×8 draughts: men take both ways, kings fly, any capture may be chosen whatever it takes (FMJD-64 4.13), and a man that reaches the far row in the middle of a capture is crowned there and carries on capturing as a king (4.14).
`scoreArea`	function	The area score: every stone on the board, plus every empty region whose only neighbours are one colour.
`Seat`	type	The two people at the board.
`seatOf`	function	The seat holding `stone` right now.
`SEATS`	constant	The first and second player seat labels.
`seatToPlay`	function	The seat whose turn it is.
`SECOND_STONE_EXCLUSIONS`	constant	Half-widths of the central square a handicapped second stone must leave.
`SEED_RANGE`	constant	Seeds are 31-bit integers, small enough for every store and reproducible everywhere.
`seededRandom`	function	A small seeded random number generator, so anything a game decides by chance — where the dead squares fall, which pieces come next — is fixed by the seed stored with the game and comes out the same on every replay.
`shrinkBoard`	function	Returns the game on a smaller board, or the state unchanged when the ring that would be removed is in use.
`singlesLeft`	function	Single stones the colour to move may still lay instead of a piece.
`sizeForVariant`	function	The board this variant will actually be played on, given a size somebody asked for.
`skipMove`	function	Burns the turn on a corner stone.
`skipTarget`	function	Where a skipped turn puts its stone: the open intersection furthest from the action, picked from the corner chosen by `roll`.
`SlideMove`	type	What a record needs of a move to say whether it slid, jumped, or went on jumping.
`slideWord`	function	A slide as the draughts records write it: square to square with an arrow, a capture with a colon (g5:e3), and a multi-jump as every square it landed on (g5:e3:c1).
`STAR_POINTS`	constant	Hoshi (star point) positions drawn on the board, by board size: the four corner points, plus tengen at the centre, and for 19×19 the side points too.
`STAR_RADIUS`	constant	How many rows deep each of the star's six points is.
`starCampOf`	function	Whose home point `point` lies in, or null outside both.
`starCampSize`	function	Pieces a side has: the cells of one point, ten on the standard board.
`starPiecesHome`	function	How many of `stone`'s pieces stand in the far point.
`starSize`	function	The side of the square array a star of this radius is embedded in.
`STARTING_DISCS`	constant	The fixed, laid or absent starting-disc layouts.
`StartingDiscs`	type	How a flipping game begins: nothing, the fixed four, or four the players lay themselves.
`Stone`	type	One of the two stone colours.
`STONELESS_WORDS`	constant	How a written move list says the two moves that have no point.
`stonelessWord`	function	How a written record says a move with no point, or null for a move that has one.
`STONES`	constant	The black and white stone labels.
`stonesLeft`	function	Stones the colour to move still has to place before the turn passes.
`StoredGame`	type	The stored shape of a game, as both the API and the pages see it.
`swapSeats`	function	Trades seats: the player to move hands over their colour and takes the opponent's stones instead.
`TRADITIONAL_HEAD_STARTS`	constant	The traditional head starts, see TraditionalHeadStart.
`TraditionalHeadStart`	type	The head start a game's own tradition gives a weaker player, where it has one: Go's handicap stones on the star points, Othello's corners, and draughts' piece odds, the men taken off the stronger side before the start.
`TURN_CHOICE_KINDS`	constant	The piece-moving and stone-placement choice modes.
`TurnChoiceKind`	type	Whether a turn moves a piece already on the board, or places on a point.
`turnChoices`	function	What the colour to move may do this turn — every piece that has a move, or every point that may be played — and whether a rule narrowed it.
`TurnChoices`	type	What the colour to move may do this turn, as the engine answers it — see `turnChoices`.
`turnPassedBy`	function	The colour whose turn passed because it had no move, as the latest turn left the board — or null when nobody's did.
`Twist`	type	A quarter turn of one quadrant, which ends a move in the twist games.
`twistBoard`	function	Turns one quadrant to finish the move.
`undoMove`	function	Removes the last move, putting back anything it captured, a piece where it came from, and a twisted quadrant the way it was.
`upcomingPieces`	function	The pieces after the one in hand, for the preview.
`VARIANT_SPECS`	constant	Every rule set, as data.
`VariantSpec`	type	One rule set, as data.
`WIN_LENGTH`	constant	Stones in a line needed to win, unless a variant pins it.
`WIN_LENGTHS`	constant	Line lengths a player may pick in the variants that leave it open.
`WIN_REASONS`	constant	The recorded reasons a game is won.
`winOnTime`	function	Ends the game against a player who has run out of time.
`WinReason`	type	How a won game was won.
`Worm`	type	A wormhole: a line entering it comes out of its partner and carries on.
`WORM`	constant	The linked wormhole-cell marker.
`WRAP_MODES`	constant	The supported board edge-wrapping modes.
`WrapMode`	type	Which edges of the board join up: a plane, a cylinder, or a torus.

View source Edit on GitHubMade from the source of @johnmorrisdotca/narabe 1.3.0.