Community/OGID Specification

OGID — OpenGammon Position ID

OGID is the canonical string format for a complete backgammon game state: board, cube, dice, game state, score, and match context. It round-trips with GNUbg and XG position IDs and is the universal currency across the HedgeHog engine, training data, and the WASM API.

Format

An OGID is up to 11 colon-separated fields:

white_positions:black_positions:cube:dice:color:game_state:score_w:score_b:match_length:move_id:nrof_checkers

Standard opening position:

11jjjjjhhhccccc:ooddddd88866666:N0N::W:IW:0:0:1:0

Minimum required pattern (fields 1–5):

^[0-9a-p]*:[0-9a-p]*:[BWND\?]\d+[OTPN]:\d{0,2}:[WB]

Fields 1–2 · Checker Positions

Each checker is one character. The character's base-26 value (0–9, a–p) is the pip it occupies. Field 1 is white's checkers, field 2 is black's.

Pip 0 (char 0) = White's bar
Pips 1–24 = Board points
Pip 25 (char p) = Black's bar

Characters are conventionally grouped in descending pip order, but any order parses identically — multiplicity is what matters.

Example

11jjjjjhhhccccc

11 — 2 checkers on pip 1
jjjjj — 5 checkers on pip 19
hhh — 3 checkers on pip 17
ccccc — 5 checkers on pip 12

Character → Pip

Char	Pip	Char	Pip	Char	Pip
0	0	9	9	i	18
1	1	a	10	j	19
2	2	b	11	k	20
3	3	c	12	l	21
4	4	d	13	m	22
5	5	e	14	n	23
6	6	f	15	o	24
7	7	g	16	p	25
8	8	h	17

Field 3 · Cube State

Three parts: [owner][value][action], matching ([BWND?])(\d+)([OTPN]). The value is an exponent of 2 (3 means cube is at 8).

Owner

N	Centered (neither player owns it)
W	White owns the cube
B	Black owns the cube
D	Dead cube (cannot be used)
?	Unknown / uninitialized

Action

N	Normal — no pending action
O	Offered — double pending
T	Taken — double just accepted
P	Passed / dropped — game ends

Examples

N0N — centered at 1, no action
W2N — white owns cube at 4
B1O — black owns cube at 2, double offered
W3T — white owns cube at 8, double just taken
B2P — black owns cube at 4, dropped (game over)

Field 4 · Dice

Two digits (each 1–6), or empty if no dice have been rolled.

(empty) — no dice rolled
31 — 3 and 1
66 — double sixes

Field 5 · Color

Which player reached this position (i.e. who just moved). The other side is on roll.

W	White reached this position — Black to move
B	Black reached this position — White to move

Field 6 · Game State (optional)

Captures the turn state machine. An empty value is treated as C for backwards compatibility.

Turn phases

Code	Meaning	Next states
IW	Initial position, white's opening roll	→ IW (with dice) → IB
IB	Opening roll resolved, first player moves	→ C
R	Dice rolled, awaiting checker play	→ C
C	Checker play complete, opponent's turn	→ D, PR
A	After take — like C but cube was just taken	→ D, PR
D	Double offered, awaiting take/pass	→ A, P
P	Passed / dropped cube, game ending	→ G, M
PR	Pre-roll, dice being rolled	→ R

Terminal states

Code	Meaning	Next states
G	Game over (not match)	→ IW (new game)
M	Match over	→ F
F	Finished (terminal)	—
RG	Resigned game	→ apply win → G or M
RM	Resigned match	→ apply win → M
FF	Forfeit	→ apply win → M

Typical flow

C → PR (roll) → R (move) → C
C → D (offer) → A (take) → PR → R → C
C → D (offer) → P (drop) → G → IW  (new game)

Opening:  IW (no dice) → IW (one die) → IB (both rolled) → C

Fields 7–11 · Match Context (optional)

#	Field	Default	Notes
7	White score	0	Integer points in current match
8	Black score	0	Integer points in current match
9	Match length	0	`[length][modifier][max_games]` — see below
10	Move ID	0	Monotonic counter for the current game/match
11	Checkers per side	15	Only set for non-standard variants

Match-length modifiers

(none)	Normal match
C	Crawford game (no doubling when one side is 1 point away)
L	Post-Crawford game (game immediately after Crawford)
G	Fixed number of games (followed by count)

Examples:

1 — 1-point match
7C — 7-point match, Crawford game
7L — 7-point match, post-Crawford
0 — unlimited money game
0G5 — money game capped at 5 games

Point Numbering

Black's Home Board          Black's Outer Board
  24  23  22  21  20  19      18  17  16  15  14  13
 +---+---+---+---+---+---+  +---+---+---+---+---+---+
 | o |   |   |   |   | X |  |   | X |   |   |   | o | Black's bar (pip 25)
 | o |   |   |   |   | X |  |   | X |   |   |   | o |
 |   |   |   |   |   | X |  |   | X |   |   |   | o |
 |   |   |   |   |   | X |  |   |   |   |   |   | o |
 |   |   |   |   |   | X |  |   |   |   |   |   | o |
 +---+---+---+---+---+---+  +---+---+---+---+---+---+
 +---+---+---+---+---+---+  +---+---+---+---+---+---+
 |   |   |   |   |   | o |  |   | o |   |   |   | X |
 |   |   |   |   |   | o |  |   | o |   |   |   | X |
 |   |   |   |   |   | o |  |   | o |   |   |   | X |
 | X |   |   |   |   | o |  |   |   |   |   |   | X |
 | X |   |   |   |   | o |  |   |   |   |   |   | X | White's bar (pip 0)
 +---+---+---+---+---+---+  +---+---+---+---+---+---+
   1   2   3   4   5   6       7   8   9  10  11  12
White's Home Board          White's Outer Board

Interop with GNUbg & XG

The HedgeHog engine provides lossless conversion between OGID and the binary position IDs used by GNU Backgammon and eXtreme Gammon:

Function	Direction
gnubg_to_ogid()	GNUbg Position ID + Match ID → OGID
ogid_to_gnubg()	OGID → GNUbg Position ID + Match ID

A Python reference implementation lives in scripts/ogid_transformer.py with round-trip tests.

← Back to Developers & Community