bgammon

package module
v0.0.0-...-d14a855 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 11, 2026 License: AGPL-3.0 Imports: 10 Imported by: 3

README

bgammon - Backgammon server powering bgammon.org

GoDoc Translate Donate

Play

Browser and Desktop

Click here to play using your browser.

Download Boxcars at https://bgammon.org/download

Source code is available here.

Android

Boxcars for Android is available here.

Source code is available here.

Terminal

ssh bgammon.org -p 5000

Source code is available here.

Translate

Translation is handled online.

Support

Please share issues and suggestions here.

The bgammon protocol is specified in PROTOCOL.md.

Information on how to play backgammon is available here.

Documentation

Overview

Package bgammon provides an interface for connecting to the bgammon.org online backgammon server.

Index

Constants

View Source 
const (
	SpaceHomePlayer   int8 = 0  // Current player's home.
	SpaceHomeOpponent int8 = 25 // Opponent player's home.
	SpaceBarPlayer    int8 = 26 // Current player's bar.
	SpaceBarOpponent  int8 = 27 // Opponent player's bar.
)
View Source 
const (
	CommandLogin         = "login"         // Log in with username and password, or as a guest.
	CommandLoginJSON     = "loginjson"     // Log in with username and password, or as a guest, and enable JSON messages.
	CommandRegister      = "register"      // Register an account.
	CommandRegisterJSON  = "registerjson"  // Register an account and enable JSON messages.
	CommandResetPassword = "resetpassword" // Request password reset link via email.
	CommandPassword      = "password"      // Change password.
	CommandSet           = "set"           // Change account setting.
	CommandAchievements  = "achievements"  // Retrieve achievement IDs, names and descriptions.
	CommandReplay        = "replay"        // Retrieve replay.
	CommandHistory       = "history"       // Retrieve player match and achievement history.
	CommandHelp          = "help"          // Print help information.
	CommandJSON          = "json"          // Enable or disable JSON formatted messages.
	CommandSay           = "say"           // Send chat message.
	CommandList          = "list"          // List available matches.
	CommandCreate        = "create"        // Create match.
	CommandJoin          = "join"          // Join match.
	CommandLeave         = "leave"         // Leave match.
	CommandDouble        = "double"        // Offer double to opponent.
	CommandResign        = "resign"        // Decline double offer and resign game.
	CommandRoll          = "roll"          // Roll dice.
	CommandMove          = "move"          // Move checkers.
	CommandReset         = "reset"         // Reset checker movement.
	CommandOk            = "ok"            // Confirm checker movement and pass turn to next player.
	CommandRematch       = "rematch"       // Offer (or accept) a rematch after a match has been finished.
	CommandFollow        = "follow"        // Follow a player.
	CommandUnfollow      = "unfollow"      // Un-follow a player.
	CommandBoard         = "board"         // Print current board state in human-readable form.
	CommandPong          = "pong"          // Response to server ping.
	CommandDisconnect    = "disconnect"    // Disconnect from server.
	CommandMOTD          = "motd"          // Read (or write) the message of the day.
	CommandBroadcast     = "broadcast"     // Send a message to all players.
	CommandDefcon        = "defcon"        // Apply restrictions to guests to prevent abuse.
	CommandRename        = "rename"        // Rename an account.
	CommandKick          = "kick"          // Kick a user from the server.
	CommandBan           = "ban"           // Ban an IP address or account.
	CommandUnban         = "unban"         // Unban an IP address or account.
	CommandShutdown      = "shutdown"      // Prevent the creation of new matches.
)
View Source 
const (
	EventTypeWelcome      = "welcome"
	EventTypeHelp         = "help"
	EventTypePing         = "ping"
	EventTypeNotice       = "notice"
	EventTypeSay          = "say"
	EventTypeList         = "list"
	EventTypeFailedCreate = "failedcreate"
	EventTypeJoined       = "joined"
	EventTypeFailedJoin   = "failedjoin"
	EventTypeLeft         = "left"
	EventTypeFailedLeave  = "failedleave"
	EventTypeBoard        = "board"
	EventTypeRolled       = "rolled"
	EventTypeFailedRoll   = "failedroll"
	EventTypeMoved        = "moved"
	EventTypeFailedMove   = "failedmove"
	EventTypeFailedOk     = "failedok"
	EventTypeWin          = "win"
	EventTypeSettings     = "settings"
	EventTypeAchievements = "achievements"
	EventTypeReplay       = "replay"
	EventTypeHistory      = "history"
)
View Source 
const (
	DimNone   int8 = 0
	DimPlayer int8 = 1
	DimAll    int8 = 2
)
View Source 
const (
	SpeedSlow    int8 = 0
	SpeedMedium  int8 = 1
	SpeedFast    int8 = 2
	SpeedInstant int8 = 3
)
View Source 
const (
	VariantBackgammon int8 = 0
	VariantAceyDeucey int8 = 1
	VariantTabula     int8 = 2
)
View Source 
const BoardSpaces = 28

BoardSpaces is the total number of spaces needed to represent a backgammon board.

Variables

View Source 
var HelpText = map[string]string{
	CommandLogin:         "[username] [password] - Log in. A random username is assigned when none is provided.",
	CommandRegister:      "<email> <username> <password> - Register an account. A valid email address must be provided.",
	CommandResetPassword: "<email> - Request a password reset link via email.",
	CommandPassword:      "<old> <new> - Change account password.",
	CommandSet:           "<name> <value> - Change account setting. Available settings: highlight, pips and moves.",
	CommandAchievements:  "- Retrieve achievement IDs, names and descriptions.",
	CommandReplay:        "<id> - Retrieve replay of the specified game.",
	CommandHistory:       "<username> [page] - Retrieve match history of the specified player.",
	CommandHelp:          "[command] - Request help for all commands, or optionally a specific command.",
	CommandSay:           "<message> - Send a chat message. This command can only be used after creating or joining a match.",
	CommandList:          "- List all matches.",
	CommandCreate:        "<public>/<private [password]> <points> <variant> [name] - Create a match. A variant value of 0 represents a standard game, a value of 1 represents an acey-deucey game and a value of 2 represents a tabula game.",
	CommandJoin:          "<id>/<username> [password] - Join match by match ID or by player.",
	CommandLeave:         "- Leave match.",
	CommandDouble:        "- Offer double to opponent.",
	CommandResign:        "- Resign game. Resigning when a double is offered will decline the offer.",
	CommandRoll:          "- Roll dice.",
	CommandMove:          "<from-to> [from-to]... - Move checkers.",
	CommandReset:         "- Reset pending checker movement.",
	CommandOk:            "[1-6] - Accept double offer or confirm checker movement. The parameter for this command only applies in acey-deucey games.",
	CommandRematch:       "- Request (or accept) a rematch after a match has been finished.",
	CommandFollow:        "<username> - Follow a player. A notification is shown whenever a followed player goes online or offline.",
	CommandUnfollow:      "<username> - Un-follow a player.",
	CommandBoard:         "- Request current match state.",
	CommandPong:          "<message> - Sent in response to server ping event to prevent the connection from timing out.",
	CommandDisconnect:    "- Disconnect from the server.",
	CommandMOTD:          "[message] - View (or set) message of the day. Specifying a new message of the day is only available to server administrators.",
	CommandBroadcast:     "<message> - Send a message to all players. This command is only available to server administrators.",
	CommandDefcon:        "[level] - Apply restrictions to guests to prevent abuse. Levels:\n1. Disallow new accounts from being registered.\n2. Only registered users may connect.\n3. Only registered users may chat and set custom match titles.\n4. Warning message is broadcast to all users.\n5. Normal operation.",
	CommandRename:        "<old> <new> - Rename an account.",
	CommandKick:          "<username> [reason] - Kick a user from the server.",
	CommandBan:           "<username> [reason] - Ban a user by IP addresss and account (if logged in).",
	CommandUnban:         "<IP>/<username> - Unban a user by IP address or account.",
	CommandShutdown:      "<minutes> <reason> - Prevent the creation of new matches and periodically warn players about the server shutting down. This command is only available to server administrators.",
}

Functions

func DecodeEvent 

func DecodeEvent(message []byte) (interface{}, error)

func FlipMoves 

func FlipMoves(moves [][]int8, player int8, variant int8) [][]int8

func FlipSpace 

func FlipSpace(space int8, player int8, variant int8) int8

func FormatAndFlipMoves 

func FormatAndFlipMoves(moves [][]int8, player int8, variant int8) []byte

func FormatMoves 

func FormatMoves(moves [][]int8) []byte

func FormatSpace 

func FormatSpace(space int8) []byte

func HomeRange 

func HomeRange(player int8, variant int8) (from int8, to int8)

HomeRange returns the start and end space of the provided player's home board.

func IterateSpaces 

func IterateSpaces(from int8, to int8, variant int8, f func(space int8, spaceCount int8))

func NewBoard 

func NewBoard(variant int8) []int8

NewBoard returns a new backgammon board represented as integers. Positive integers represent player 1's checkers and negative integers represent player 2's checkers. The board's space numbering is always from the perspective of the current player (i.e. the 1 space will always be in the current player's home board).

func OpponentCheckers 

func OpponentCheckers(checkers int8, player int8) int8

func ParseSpace 

func ParseSpace(space string) int8

func PlayerCheckers 

func PlayerCheckers(checkers int8, player int8) int8

func RollForMove 

func RollForMove(from int8, to int8, player int8, variant int8) int8

RollForMove returns the roll needed to move a checker from the provided spaces.

func SortMoves 

func SortMoves(moves [][]int8)

SortMoves sorts moves from highest to lowest.

func SpaceDiff 

func SpaceDiff(from int8, to int8, variant int8) int8

func ValidSpace 

func ValidSpace(space int8) bool

Types

type Client 

type Client interface {
	Address() string
	HandleReadWrite()
	Write(message []byte)
	Terminate(reason string)
	Terminated() bool
}

type Command 

type Command string

type Crawford 

type Crawford int8
const (
	CrawfordPending Crawford = 0 // Crawford Rule has not yet been activated. Doubling is allowed.
	CrawfordActive  Crawford = 1 // Crawford Rule is active for this game. Doubling is not allowed.
	CrawfordExpired Crawford = 2 // Crawford Rule was active during a previous game. Doubling is allowed.
)

type Event 

type Event struct {
	Type   string
	Player string
}

type EventAchievement 

type EventAchievement struct {
	ID          int
	Name        string
	Description string
}

type EventAchievements 

type EventAchievements struct {
	Event
	Achievements []*EventAchievement
}

type EventBoard 

type EventBoard struct {
	Event
	GameState
}

type EventFailedCreate 

type EventFailedCreate struct {
	Event
	Reason string
}

type EventFailedJoin 

type EventFailedJoin struct {
	Event
	Reason string
}

type EventFailedLeave 

type EventFailedLeave struct {
	Event
	Reason string
}

type EventFailedMove 

type EventFailedMove struct {
	Event
	From   int8
	To     int8
	Reason string
}

type EventFailedOk 

type EventFailedOk struct {
	Event
	Reason string
}

type EventFailedRoll 

type EventFailedRoll struct {
	Event
	Reason string
}

type EventHistory 

type EventHistory struct {
	Event
	Page                   int
	Pages                  int
	Matches                []*HistoryMatch
	Achievements           []*HistoryAchievement
	CasualBackgammonSingle int
	CasualBackgammonMulti  int
	CasualAceyDeuceySingle int
	CasualAceyDeuceyMulti  int
	CasualTabulaSingle     int
	CasualTabulaMulti      int
}

type EventJoined 

type EventJoined struct {
	Event
	GameID       int
	PlayerNumber int8
}

type EventLeft 

type EventLeft struct {
	Event
}

type EventList 

type EventList struct {
	Event
	Games []GameListing
}

type EventMoved 

type EventMoved struct {
	Event
	Moves [][]int8
}

type EventNotice 

type EventNotice struct {
	Event
	Message string
}

type EventPing 

type EventPing struct {
	Event
	Message string
}

type EventReplay 

type EventReplay struct {
	Event
	ID      int
	Content []byte
}

type EventRolled 

type EventRolled struct {
	Event
	Roll1    int8
	Roll2    int8
	Roll3    int8 // Used in tabula games.
	Selected bool // Whether the roll is selected by the player (used in acey-deucey games).
}

type EventSay 

type EventSay struct {
	Event
	Message string
}

type EventSettings 

type EventSettings struct {
	Event
	AutoPlay      bool
	Highlight     bool
	Pips          bool
	Moves         bool
	Flip          bool
	Traditional   bool
	Advanced      bool
	MuteJoinLeave bool
	MuteChat      bool
	MuteRoll      bool
	MuteMove      bool
	MuteBearOff   bool
	Dim           int8
	Speed         int8
}

type EventType 

type EventType string

type EventWelcome 

type EventWelcome struct {
	Event
	PlayerName string
	Clients    int
	Games      int
}

type EventWin 

type EventWin struct {
	Event
	Points   int8
	Rating   int
	Resigned string
}

type Game 

type Game struct {
	Started int64
	Ended   int64

	Player1 Player
	Player2 Player

	Variant int8 // 0 - Backgammon, 1 - Acey-deucey, 2 - Tabula.
	Board   []int8
	Turn    int8

	Roll1 int8
	Roll2 int8
	Roll3 int8 // Used in tabula games.

	Moves  [][]int8 // Pending moves.
	Winner int8

	Points        int8     // Points required to win the match.
	Crawford      Crawford // Crawford Rule status.
	DoubleValue   int8     // Doubling cube value.
	DoublePlayer  int8     // Player that currently posesses the doubling cube.
	DoubleOffered bool     // Whether the current player is offering a double.

	Reroll bool // Used in acey-deucey.
	// contains filtered or unexported fields
}

func NewGame 

func NewGame(variant int8) *Game

func (*Game) AddLocalMove 

func (g *Game) AddLocalMove(move []int8) bool

AddLocalMove adds a move without performing any validation. This is useful when adding a move locally while waiting for an EventBoard response from the server.

func (*Game) AddMoves 

func (g *Game) AddMoves(moves [][]int8, local bool) (bool, [][]int8)

AddMoves adds moves to the game state. Adding a backwards move will remove the equivalent existing move.

func (*Game) Blocked 

func (g *Game) Blocked(player int8) int

func (*Game) BoardState 

func (g *Game) BoardState(player int8, local bool) []byte

func (*Game) Copy 

func (g *Game) Copy(shallow bool) *Game

func (*Game) DiceRolls 

func (g *Game) DiceRolls() []int8

func (*Game) ExpandMove 

func (g *Game) ExpandMove(move []int8, currentSpace int8, moves [][]int8, local bool) ([][]int8, bool)

func (*Game) HaveBearOffDiceRoll 

func (g *Game) HaveBearOffDiceRoll(diff int8) int8

func (*Game) HaveDiceRoll 

func (g *Game) HaveDiceRoll(from int8, to int8) int8

func (*Game) LastActive 

func (g *Game) LastActive() time.Time

func (*Game) LegalMoves 

func (g *Game) LegalMoves(local bool) [][]int8

func (*Game) MayBearOff 

func (g *Game) MayBearOff(player int8, local bool) bool

MayBearOff returns whether the provided player may bear checkers off of the board.

func (*Game) NextPartialTurn 

func (g *Game) NextPartialTurn(player int8)

func (*Game) NextTurn 

func (g *Game) NextTurn(reroll bool)

func (*Game) PartialHandled 

func (g *Game) PartialHandled() bool

func (*Game) PartialTime 

func (g *Game) PartialTime() int

func (*Game) PartialTurn 

func (g *Game) PartialTurn() int8

func (*Game) RenderSpace 

func (g *Game) RenderSpace(player int8, space int8, spaceValue int8, legalMoves [][]int8) []byte

func (*Game) Reset 

func (g *Game) Reset()

Reset resets the board state and prepares for the next game in a match. Create a new Game from scratch to start a rematch.

func (*Game) SecondHalf 

func (g *Game) SecondHalf(player int8, local bool) bool

func (*Game) SetBlocked 

func (g *Game) SetBlocked(player int8, blocked int)

func (*Game) SetPartialHandled 

func (g *Game) SetPartialHandled(handled bool)

func (*Game) TabulaBoard 

func (g *Game) TabulaBoard() (tabula.Board, bool)

func (*Game) UpdateLastActive 

func (g *Game) UpdateLastActive()

type GameListing 

type GameListing struct {
	ID       int
	Password bool
	Points   int8
	Players  int8
	Rating   int
	Name     string
}

type GameState 

type GameState struct {
	*Game
	PlayerNumber int8
	Available    [][]int8 // Legal moves.
	Forced       bool     // A forced move is being played automatically.
	Spectating   bool
}

func (*GameState) LocalPlayer 

func (g *GameState) LocalPlayer() Player

func (*GameState) MayChooseRoll 

func (g *GameState) MayChooseRoll() bool

MayChooseRoll returns whether the player may send the 'ok' command, supplying the chosen roll. This command only applies to acey-deucey games.

func (*GameState) MayDecline 

func (g *GameState) MayDecline() bool

MayDecline returns whether the player may send the 'resign' command to decline a double offer.

func (*GameState) MayDouble 

func (g *GameState) MayDouble() bool

MayDouble returns whether the player may send the 'double' command.

func (*GameState) MayOK 

func (g *GameState) MayOK() bool

MayOK returns whether the player may send the 'ok' command.

func (*GameState) MayReset 

func (g *GameState) MayReset() bool

MayReset returns whether the player may send the 'reset' command.

func (*GameState) MayRoll 

func (g *GameState) MayRoll() bool

MayRoll returns whether the player may send the 'roll' command.

func (*GameState) OpponentPlayer 

func (g *GameState) OpponentPlayer() Player

func (*GameState) Pips 

func (g *GameState) Pips(player int8) int

Pips returns the pip count for the specified player.

func (*GameState) SpaceAt 

func (g *GameState) SpaceAt(x int8, y int8) int8

type HistoryAchievement 

type HistoryAchievement struct {
	ID        int
	Replay    int
	Timestamp int64
}

type HistoryMatch 

type HistoryMatch struct {
	ID        int
	Timestamp int64
	Points    int8
	Opponent  string
	Winner    int8
}

type Player 

type Player struct {
	Number   int8 // 1 black, 2 white
	Name     string
	Rating   int
	Points   int8
	Entered  bool // Whether all checkers have entered the board. (Acey-deucey)
	Inactive int  // Inactive time. (Seconds)
	Icon     int  // Profile icon.
}

func NewPlayer 

func NewPlayer(number int8) Player

Source Files

View all Source files

Directories

Path Synopsis
cmd
bgammon-server command
pkg
server

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.