@nodots/backgammon-core

Pure, deterministic backgammon game logic in TypeScript. Board, moves, play state, dice, cube, GNU position IDs, and performance-rating calculation — the same engine that runs backgammon.nodots.com in production.

Install

npm install @nodots/backgammon-core

Quick start

import { Game } from '@nodots/backgammon-core'

const game = Game.createNewGame(
  { userId: 'alice', isRobot: false },
  { userId: 'bob',   isRobot: true  },
)

const started = Game.rollForStart(game)
const rolled  = Game.roll(started)

// rolled.activePlay.moves holds every legal move option for the rolled dice.
// Execute one with Game.move, passing the origin checker container.

For AI-driven turns, pair with @nodots/backgammon-ai and call executeRobotTurnWithGNU(game).

What's in the package

| Module | Purpose | | --- | --- | | Game | State machine for a full game: initialize, roll, move, double, accept, resign, confirm. | | Play | Per-turn structure holding dice and every legal move sequence. | | Board | Twenty-four points, bar, off, and the dual-direction position system. | | Dice / Cube | Crypto-backed dice rolls and doubling-cube state. | | Move / Checker | Checker movement, hit detection, bearing off. | | History | Append-only game event log, including cube decisions. | | Services.PerformanceRatingCalculator | GNU-compatible PR calculation and error classification. | | gnuPositionId | Encode and decode GNU Backgammon 14-character position IDs. | | ascii | Render a board to an ASCII string for logs and terminals. |

Dual-direction position system

Every point on the backgammon board carries two numbers — one for the clockwise player, one for the counterclockwise player. This is deliberate: each player's home board is always positions 1–6 from their own perspective, no matter which direction they move. Move validation uses the active player's directional view of the board.

See the backgammon rules reference and the Nodots architecture papers for details.

Ecosystem

| Package | Role | | --- | --- | | @nodots/backgammon-types | Discriminated-union type contracts. | | @nodots/backgammon-core | Game logic (this package). | | @nodots/backgammon-ai | GNU-backed robot move selection and cube decisions. | | @nodots/backgammon-api-utils | Request, response, and WebSocket contracts. | | @nodots/backgammon-cli | Terminal client (ndbg). | | @nodots/gnubg-hints | Native GNU Backgammon hints addon. |

Hosted product: backgammon.nodots.com.

License

GPL-3.0. See LICENSE.