backgammon

README

backgammon

A pure-Go backgammon rules engine — no protocol, no I/O, no dependencies beyond the standard library.

The core is legal-turn generation: LegalTurns enumerates every complete legal turn for a position and dice roll, encoding the fiddly tabletop obligations (you must use both dice if you can; if only one is playable, it must be the larger; bar entry comes first; bear-off exact/overshoot rules) as set membership rather than a pile of special cases. Validate then just checks a submitted turn against that set — ideal for both-sides-validate multiplayer where neither client is trusted.

b := backgammon.Start()
turns := backgammon.LegalTurns(b, backgammon.White, 3, 1)
// pick one, validate it, apply it
if err := backgammon.Validate(b, backgammon.White, 3, 1, turns[0]); err == nil {
    b = backgammon.ApplyTurn(b, backgammon.White, turns[0])
}
result := b.Winner() // nil until someone bears off all 15 (plain/gammon/backgammon)

Points are numbered 1–24 in White's frame (Black's point p is 25-p); moves use each player's own numbering. Bar is From: 25, bear-off is To: 0. See the doc comments for details.

Not yet implemented: the doubling cube.

Install

go get github.com/richardwooding/backgammon

Extracted from kibitz, where it drives E2E-encrypted online backgammon.

License

MIT

Documentation

Overview

Package backgammon is a pure-Go backgammon rules engine — no protocol, no I/O, no dependencies beyond the standard library. Turn validation is generate-all-legal-turns + membership (LegalTurns / Validate), which encodes the awkward tabletop obligations (use both dice if possible; if only one can be played, the larger) without special cases — well suited to both-sides-validate multiplayer where neither end is trusted. Doubling cube: not yet implemented.

Extracted from https://github.com/richardwooding/kibitz

Index

• Variables
• func LegalTurns(b Board, c Color, d1, d2 int8) [][]Hop
• func Validate(b Board, c Color, d1, d2 int8, turn []Hop) error
• type Board
  • func ApplyTurn(b Board, c Color, turn []Hop) Board
  • func Start() Board
  • func (b *Board) PipCount(c Color) int
  • func (b *Board) Winner() *Result
• type Color
  • func (c Color) Opponent() Color
  • func (c Color) String() string
• type Hop
• type Result

Variables

var ErrIllegalTurn = errors.New("backgammon: illegal turn")

Functions

func LegalTurns

func LegalTurns(b Board, c Color, d1, d2 int8) [][]Hop

LegalTurns generates every complete legal turn for c with the given dice. A turn is an ordered hop sequence; the tabletop obligations fall out of the construction:

• all returned sequences have maximal length (use both dice if you can),
• when only one die can be played and either could be, only the larger die's hops are returned,
• an empty single sequence means no legal moves (a dance).

func Validate

func Validate(b Board, c Color, d1, d2 int8, turn []Hop) error

Validate checks a submitted complete turn against the dice, encoding membership in the legal-turn set (order matters: a hop may only be legal because an earlier hop opened it).

Types

type Board

type Board struct {
	Points [25]int8 `cbor:"1,keyasint"` // index 0 unused
	Bar    [2]int8  `cbor:"2,keyasint"`
	Off    [2]int8  `cbor:"3,keyasint"`
}

Board is the shared position. Points are numbered 1..24 in WHITE's numbering (Black's point p is 25-p); positive counts are White checkers, negative are Black.

func ApplyTurn

func ApplyTurn(b Board, c Color, turn []Hop) Board

ApplyTurn returns the board after a (validated) turn.

func Start

func Start() Board

Start is the standard opening position.

func (*Board) PipCount

func (b *Board) PipCount(c Color) int

PipCount is the classic race metric (sum of distances to bear off).

func (*Board) Winner

func (b *Board) Winner() *Result

Winner returns the game result, or nil while play continues.

type Color

type Color int8

Color identifies a player. White moves from point 24 toward 1 (in its own numbering) and bears off from 1..6; Black mirrors.

const (
	White Color = 0
	Black Color = 1
)

func (Color) Opponent

func (c Color) Opponent() Color

func (Color) String

func (c Color) String() string

type Hop

type Hop struct {
	From int8 `cbor:"1,keyasint"`
	To   int8 `cbor:"2,keyasint"`
}

Hop is one checker movement in the MOVING player's own numbering: From 1..24 for a point, 25 for the bar; To 1..24, or 0 for bearing off.

type Result

type Result struct {
	Winner Color
	// Points: 1 plain, 2 gammon (loser bore off nothing), 3 backgammon
	// (gammon + loser has a checker in the winner's home or on the bar).
	Points int
}

Result of a finished game.