GammonView
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.gvabbinary,.gvaJSON conversion,.xg/.bgfimport, compute-on-read stats, OGID. Zero third-party deps —pip install gammonviewandimport gvformatanywhere, 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.gvabbytes out),analyze_file(the same work stopping at the OGXM document), and single-position analysis. Depends ongvformat+ 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 |
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"
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_classis 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.balancedwas retired in September 2026 for costing what the preset above it cost.world_class_fastwas retired in October 2026 once faster rollouts madeworld_classnearly as cheap: on 11 matches it took 74% ofworld_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
gvformatis an independent implementation, butbinary.pyandexport.py(and their JS mirrors) are genuine ports of its C++ sources: the chunk struct layouts andparse_ply_analysis_jsonfromogxm_io.cpp/ogxm_json.cpp, and_TurnStatefromogxm_replay.cpp'sreplay_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.pyandgvformat-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 intodist/.gvengine-js/src/entry.cppis 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.6.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| gammonview-3.6.2.tar.gz | 4.0 MB | With provenance | Details for gammonview-3.6.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| gammonview-3.6.2-py3-none-any.whl | Python 3 | none | any | Details for gammonview-3.6.2-py3-none-any.whl |
Total release size: 4.3 MB
Release files / gammonview-3.6.2.tar.gz
| Download URL | gammonview-3.6.2.tar.gz |
|---|---|
| Size | 4.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f35b739893e69ac660a48febe6f863e765f59ca83cdc07b744f521cb0e07f653
|
|
BLAKE2b-256 checksum How to use checksums |
bcf601b83030a3c7a6d70fa91778aad812d1b7d8151ce435e2852ca4ca5ccb33
|
| 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 logRelease files / gammonview-3.6.2-py3-none-any.whl
| Download URL | gammonview-3.6.2-py3-none-any.whl |
|---|---|
| Size | 323.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
59f72dbfbee1347c6da0670f02561c32147a364245df110d35a5292c29cf6e4d
|
|
BLAKE2b-256 checksum How to use checksums |
edeb8e3de0b74b83dbe2716773383d49d07c81ee46dcd334722286813b68063b
|
| 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 logSecurity for gammonview 3.6.2
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.
Attestation for gammonview-3.6.2.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 logA 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.