Skip to main content

GammonView

CI engine Python 3.10+ Licence: MIT

The backgammon analysis backend behind gammonview.com: read and write the site's .gvab/.gva match files, import .mat/.xg/.bgf, analyze a match or a single position with the bgsage engine, and compute per-decision error rate (PR), luck and cube statistics.

Those files are based on OGXM — the chunked match format from HedgeHog, not ours — extended to carry what bgsage's analysis produces. This repo reads OGXM; what it writes is that extended form. See The format.

It ships as two importable Python packages, plus a JavaScript port of the codec and a WebAssembly build of the engine for the browser:

  • gvformat — the pure-stdlib codec: read/write the .gvab binary, .gva JSON conversion, .xg/.bgf import, compute-on-read stats, OGID. Zero third-party deps — pip install gammonview and import gvformat anywhere, no engine required. This is the format layer: everything else here, Python and JavaScript alike, reads and writes through it.
  • gvanalysis — the bgsage-powered analysis: analyze_match (a match file in, analyzed .gvab bytes out), analyze_file (the same work stopping at the OGXM document), and single-position analysis. Depends on gvformat + bgsage (the [engine] extra). Dependencies flow one way: gvanalysis → gvformat, never back.
  • @gammonview/gvformat — the same codec in JavaScript, on npm. What reads the analysis in the browser. See In the browser.
  • gvengine-js/ — bgsage compiled to WebAssembly, held by its tests to native bgsage's numbers, so a position read in a browser and on a server agree. Not yet published.

Install

To use the packages, install from PyPI — no clone needed:

pip install gammonview               # the codec alone (gvformat), no engine
pip install "gammonview[engine]"     # adds bgsage, for gvanalysis

To work on them, clone the repo and let uv build the environment — it installs both packages in editable mode, plus bgsage and the test dependencies:

git clone https://github.com/gammonview/gammonview-analysis.git
cd gammonview-analysis
uv sync
uv run python tests/run_all.py --fast     # ~3s, no engine needed

Every command below is written uv run … for that checkout; from a plain pip install, drop the prefix.

Quickstart

Server one-liner — analyze a dropped match and get the analyzed .gvab back, ready to store and ship to the client:

from gvanalysis import analyze_match
data = analyze_match("match.xg", preset="world_class")   # analyzed .gvab bytes

It runs the engine over every decision, and the bytes carry the match and the analysis. Any input the codec reads works — .xg, .bgf, .mat, .gva, .gvab — and one that already carries analysis keeps it, with ours appended, so an .xg comes back with XG's judgement and ours side by side.

It returns .gvab (binary), always — that is the artifact to store and ship. For the JSON, read_gvab(data) is the .gva; to stop a step earlier and work with the document itself, analyze_file returns it directly. (The CLI is the other way round: gvan-match writes .gva unless asked for --gvab, because a file you open by hand is likelier to want to be readable.)

The format

.gvab files are OGXM v2 — the match format of HedgeHog, in the version it writes today — and nothing else. Any conforming OGXM v2 reader loads them, replays every game and finds every decision v2 has a field for; HedgeHog's own codec checks each of our test files for exactly that.

What GammonView keeps that v2 has no field for — the analysis of an illegal play, which decisions count toward PR, the match's site as the source named it — travels in ANNO records keyed x-gammonview-…, the namespace v2 reserves for producers outside the spec. Another reader keeps them and ignores them; ours reads them back, so nothing is lost either way. docs/OGXM_V2_PROFILE.md says exactly how a document maps onto v2.

In match play the file stores equities as match-winning chances, v2's unit, converted through each position's own score; our document and .gva hold normalized equity, and the reader converts back.

We read OGXM, both versions. read_gvab takes a v1 or v2 file this repo never wrote, including one carrying another engine's analysis, and gvan-match appends its own analysis block rather than replacing what is already there. Files written before 2.0.0 are OGXM v1 with a GVAN chunk (docs/v1/OGXM_FORMAT_SPEC_GAMMONVIEW.md); they stay readable for good.

.gva is our document as JSON — the same content as the .gvab, in the shape docs/OGXM_JSON_SPEC_GAMMONVIEW.md describes.

In the browser

The codec has a JavaScript twin, published to npm as @gammonview/gvformat:

npm install @gammonview/gvformat
import { read_gvab, convert_mat, parse_ogid } from '@gammonview/gvformat';

const match = read_gvab(bytes);           // .gvab -> .gva JSON
const dropped = convert_mat(matText);     // .mat  -> .gva JSON, no analysis
const pos   = parse_ogid(match.games[0].plies[0].ogid_before);

An ESM port of gvformat — the same reads, writes, source converters and OGID handling, with no engine, no WebAssembly and no build step. It is how gammonview.com parses a dropped .xg/.bgf/.mat client-side and renders the .gvab the Python side produced.

The port lives in gvformat-js/ and is maintained here rather than downstream. Python and JavaScript must agree byte-for-byte — the same .gvab in gives the same .gva JSON out — and the two test suites check that from either side.

There is no JavaScript port of gvanalysis, but the engine itself runs in a browser: gvengine-js/ is bgsage compiled to WebAssembly, with a single-threaded and a threaded build. It covers what match analysis asks of the engine — n-ply checker and cube decisions, checker_eval's staged screen, 2T/3T rollouts of whole decisions, named plays and single boards, and luck's 21-roll sweep — held by parity tests to within 5e-6 of native bgsage's equities. Not yet published; its README has the calls and measured costs.

Command-line tools

Entry points are defined in pyproject.toml and run with uv run:

CLI What it does
gvan-match Analyze a match (.xg, .bgf, .mat, .gva/.ogxm, .gvab), compute per-move PR → .gva/.gvab
gvan-batch The same over many files or a directory, one output each
gvan-position Analyze a single position from an XGID or OGID; --dice prints its dice map
xg2gva Convert an eXtreme Gammon .xg file to .gva JSON (no engine)
bgf2gva Convert a BGBlitz .bgf file to .gva JSON (no engine)
uv run gvan-match match.xg --preset world_class --gvab    # an .xg straight in, binary out
uv run gvan-match match.gvab --preset fast                # re-analyze a binary, append
uv run gvan-match match.mat --link                        # print a shareable URL
uv run gvan-batch matches/ --preset fast                  # a dir -> its match files
uv run gvan-position "XGID=-b----E-C---eE---c-e----B-:0:-1:1:31:0:0:0:0"
uv run gvan-position "11ccccchhhjjjjj:66666888dddddoo:N0N:13:B:R:0:0:0:0"
uv run gvan-position "<id>" --dice                        # the equity after each of the 36 rolls
uv run gvan-position "<id>" --dice --play "13/7 8/7"      # a checker play: the replies to that play

--dice is XG's Dice Distribution, as gvanalysis.dicemap.dice_distribution returns it: at a cube decision the side on roll's equity after each roll's best play (--after-take for the rolls after a double and a take, in the cube before the double as D/T is), with each die's average; at a checker play the opponent's replies to one play, in your equity, each marked with the cube decision it leaves you (D/T, D/P, TG). Read at 2-ply by default, any n-ply level with --level.

An input keeps any analysis it already carries — ours is appended as a new block rather than replacing it. (xg2gva/bgf2gva exist for conversion on its own; analysis does not need them.) --link encodes the whole match into a gammonview.com URL fragment, so it needs no hosted file; --browser opens it.

Analysis presets

--preset selects an eXtreme Gammon–style scheme: a cheap first pass screens every decision, and a stronger pass runs only where it is needed. The four built-ins:

Preset (aliases) 1st pass Middle tier 2nd pass XG equivalent
very_quick (vq) 2ply — — Very quick
fast (f) 2ply — 3ply Fast
deep (d) 3ply — — Deep
deep_plus (dp) 3ply — truncated2 — (Deep, with errors rolled out)
world_class (wc) 3ply 4ply truncated2 World Class (XG Roller+)

The second pass runs on an error; the middle tier runs on a borderline decision the screen would otherwise have settled. fast is the default.

Which one to use

493 matches were analyzed by XG at World Class and by world_class, then compared decision by decision:

mean gap to XG's match PR PR within 1 of XG same cube action as XG
world_class@2 0.420 92.0% 96.2%

Measured 2026-10-21. Against the September world_class on the same matches the gap moved by −0.003, inside the noise (95% CI [−0.010, +0.004]), while the run took 1.83× less time: 3 h 31 m against 6 h 25 m on a 24-core M2 Ultra, or about 150 ms per ply. See the write-up.

Mean gap is the average distance between the two ratings of the same player-match, in either direction: rate a match with world_class and XG rates it about 0.42 PR away, typically. It is not what following the preset costs you. Priced by XG's own equities, a player who made world_class's recommended checker play every time would post a PR of 0.333, inside what XG itself calls world-class play. (That figure predates the September retune and was not re-measured.)

  • world_class is the analysis to trust. It routes as XG World Class does: checker plays from a 3-ply screen to 4-ply on near-ties, cubes from a 3-ply screen to 4-ply within 0.12 of the double or take point, any wrong cube action rolled out, and checker errors over 0.02 rolled out. Most of what separates it from XG is the engine, not the search depth, and no preset can spend its way past that. Resign errors, which BMAB's configuration counts, are a separate switch (--resign-errors) that any preset can run with.
  • If you want cheap, drop to deep, which costs about a tenth as much. Nothing sits between them any more. balanced was retired in September 2026 for costing what the preset above it cost. world_class_fast was retired in October 2026 once faster rollouts made world_class nearly as cheap: on 11 matches it took 74% of world_class's time for a PR 0.13 away from it. Both names now fail with a message saying so.

Every number above measures similarity to XG, which is not the same as being right — where the two engines differ there is no arbiter here to say which is correct. docs/PRESET_ACCURACY.md is the full experiment: how the presets split on checker play versus the cube, why rolling out costs agreement with XG, and the evidence that the residual disagreement is systematic rather than noise.

Presets live in gvanalysis/presets.py; every analysis records the preset's version (world_class@2), and custom presets can be added via presets.yaml. See docs/CLI.md for the full reference — every flag, how the tiers fire, parallelism, preset versions and custom presets.

Documentation

Doc What it covers
docs/CLI.md Full command-line reference — every flag, presets, parallelism
gvformat-js/README.md The JavaScript package — API, layout, parity rules
gvengine-js/README.md bgsage in the browser — the calls, the two builds, measured costs, building
CONTRIBUTING.md How to run the tests, the conventions, what a good change looks like
CHANGELOG.md Release history, including the measurements behind several design decisions
CLAUDE.md Maintainer and coding-agent notes: design rationale, measurements, and the rituals around an engine upgrade
docs/OGXM_JSON_SPEC_GAMMONVIEW.md The 2.0 document — the JSON .gva holds and read_gvab returns (match → game → ply → analysis): every key, its type and units, and the OGXM v2 field it maps to
docs/OGXM_V2_PROFILE.md How a document is written as OGXM v2 — the mapping, the x-gammonview annotations, and what reading back can change
docs/v1/OGXM_FORMAT_SPEC_GAMMONVIEW.md The OGXM v1 .gvab layout written before 2.0.0, including the GVAN chunk — still read
docs/OGXM_COMPUTED_FIELDS.md Fields the reader computes rather than stores (PR, luck-MWC, MWC, classification)
docs/METHODOLOGY.md PR / luck / cube-decision methodology and filters
docs/PRESET_ACCURACY.md What each preset costs in accuracy, measured against XG over 493 matches

Licence

MIT. Every source file carries an SPDX header; LICENSE holds the full text.

MIT because what this repo mainly offers is a format, and a format wants to be copied in pieces — one routine lifted into another project, or the codec ported to another language. It also stays compatible in both directions at once, which matters in this ecosystem: GNU Backgammon is GPL, eXtreme Gammon and BGBlitz are proprietary, and all of them are welcome to interoperate. HedgeHog, whose format this implements, is MIT too.

bgsage, the engine behind the optional [engine] extra, is MPL-2.0, which constrains nothing here. MPL is file-level copyleft with no linking trigger: it attaches to its own files, and §3.3 expressly permits distributing a larger work under other terms. bgsage resolves from PyPI at install time and is never modified or redistributed by the Python packages, and gvformat does not touch the engine at all. The browser engine in gvengine-js/ is the exception: its C entry point is a modified bgsage file, so it stays MPL-2.0, and so does what its build produces — THIRD-PARTY-NOTICES.md has the details.

The JavaScript mirror (gvformat-js/, published as @gammonview/gvformat) is under the same licence and ships its own copy.

The GammonView logo (assets/logo.png) is excluded: it identifies the site, so it is not part of the MIT grant. Fork the code freely; use your own mark.

Third-party material

Three pieces of third-party material are incorporated. Their notices must be preserved — see THIRD-PARTY-NOTICES.md, which reproduces them in full:

  • HedgeHog (MIT, © 2026 Eran Lambooij) — OGXM is HedgeHog's format. Most of gvformat is an independent implementation, but binary.py and export.py (and their JS mirrors) are genuine ports of its C++ sources: the chunk struct layouts and parse_ply_analysis_json from ogxm_io.cpp/ogxm_json.cpp, and _TurnState from ogxm_replay.cpp's replay_game(). Those four files say so in their headers.
  • Kazaross-XG2 MET (© 2011 Neil Kazaross; transcribed for GNUbg by Michael Petch) — the match-equity table embedded in gvformat/met.py and gvformat-js/src/met.js. It ships with GNU Backgammon but is not under its GPL; its own terms require only that the notice be preserved, and it is reproduced at the top of both files.
  • bgsage (MPL-2.0, © 2026 Mark Higgins) — compiled into the browser engine by gvengine-js/build.sh, which also copies its networks and bearoff database into dist/. gvengine-js/src/entry.cpp is a modified bgsage file and stays MPL-2.0. None of the build output is committed or in the sdist.

Metadata

Release files for gammonview 3.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gammonview 3.7.0
File Size Uploaded Provenance Actions
gammonview-3.7.0.tar.gz 4.0 MB With provenance Details for gammonview-3.7.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for gammonview 3.7.0
File Interpreter ABI Platform Actions
gammonview-3.7.0-py3-none-any.whl Python 3 none any Details for gammonview-3.7.0-py3-none-any.whl

Total release size: 4.4 MB

Release files / gammonview-3.7.0.tar.gz

Download URL gammonview-3.7.0.tar.gz
Size 4.0 MB
Tags Source
SHA-256 checksum
How to use checksums
c8c531a794e5a22865b4506f4daf9d4df6a43c372f8957a0156b4bfabbec4590
BLAKE2b-256 checksum
How to use checksums
b3e10d07cc406c9a86b68d8884fe879227e011926fe446f21e3195f72862bce2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / gammonview-3.7.0-py3-none-any.whl

Download URL gammonview-3.7.0-py3-none-any.whl
Size 328.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
381857472aa7c464fe08e090eb72dede7f8582ae9f4c015196e6b8df3a3e16e7
BLAKE2b-256 checksum
How to use checksums
7f2a0a2e8deb580487d5f296648fa2d8a70ca794f448b93ae59ee8135986d4d5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for gammonview 3.7.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for gammonview-3.7.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page