Developers & Community

OGXM Match Format

OGXM is HedgeHog's compact binary format for a whole match plus its analysis. It stores each turn as a small ply record (dice, checker steps, and cube actions) and reconstructs every board position by replaying them, so no positions are stored on disk. Analysis (per-move evaluations and alternatives) rides along in separate, ancillary sections that can be stripped without touching the moves. It reads from C++, from the browser via WASM, and from Python via a JSON projection. The current format is version 2.1; version 1 files still load, and are converted on the way in.

A file says where its match came from the way a chess PGN header does. Version 2.1 types the event (name, year, stage, round, table, city, country), the platform (its host name and its own match id, together a stable citation) and a record per player: the platform's user id, the rating before the match with the name of its rating system, country, and whether the player is a human, a bot or an engine. Every field is a fact fixed by the end of the match, so a signed analysis never goes stale when a rating moves afterwards.

How big is a file?

Mean file size of finished matches analysed on HedgeHog, at each length, split into the match part (moves) and the analysis part. The moves are the thin band at the base of each bar.

The lever for size is the alternatives. Default analysis keeps every legal move for each decision, not just the top few. Capping alternatives or leaving out their per-move probabilities (9 bytes each instead of 19) cuts size sharply, and a match-only OGXM is 10-70× smaller than one with full analysis. Every file here is far inside the format's 64 MiB limit.

The frozen version 1 format, which the library still reads: binary and JSON. The specifications are licensed CC BY 4.0: anyone may implement them, and credit is owed only by a copy or adaptation of the documents, never by a reader or writer.

Match databases: OGXM streams

An OGXM stream (.ogxms) is complete OGXM files back to back, with no header or index of its own, so a month of a platform's matches is one file and cat a.ogxm b.ogxm > s.ogxms makes one. Every member carries its own checksum, so a reader tells a corrupt match from a good one and can resume after it. A truncated download still reads: every complete match before the cut comes out. Streams compress with zstd as .ogxms.zst and are read straight from the decompressor.

zstdcat matches.ogxms.zst | ogxm_stream count
zstdcat matches.ogxms.zst | ogxm_stream verify --resync
zstdcat matches.ogxms.zst | ogxm_stream split out/     # one .ogxm per match
zstdcat matches.ogxms.zst | ogxm_stream to-jsonl > matches.jsonl

A match split out of a stream opens here like any other: drop the .ogxm on the analyse page. The JSON lines are for pandas or jq; the binary members are what to store and exchange.

Reading OGXM in your own code

libogxm is the reference codec, the same one HedgeHog runs: every rule of the format lives in it, so a file it accepts is a file every OGXM reader accepts. Releases are tagged (build against a tag, never main) and each one ships, for x86_64 and aarch64 Linux, the ogxm Python wheel with the library inside it (also on PyPI), and the library with the ogxm_stream and ogxm_convert tools.

# pip install ogxm
import ogxm

for member in ogxm.iter_stream(open("matches.ogxms", "rb")):
    doc = ogxm.binary_to_json(member)
    print(doc.get("site"), doc.get("match_ref"), doc["player_white"], doc["player_black"])

Analysis Handoff

If you run a backgammon platform, you can send a finished match to HedgeHog for analysis with a single link - no server-to-server call, no API key, no account. The match travels in the URL fragment, which browsers never transmit. It goes from your page straight into the engine running in the player's own browser. Your server never posts it to us, and it never lands in our access logs.

https://hedgehog-bg.com/analyze#h1.mat.gz.H4sIAAAAAAAA_+1Y...

// Build a HedgeHog analysis link for a match: JellyFish .mat text, or the
// bytes of an OGXM file (a Uint8Array) with format 'ogxm'.
// The payload rides in the URL fragment, which browsers never transmit -
// the match goes from this page straight into the user's engine.
async function hedgehogLink(match, format = 'mat') {
    const packed = new Uint8Array(await new Response(
        new Blob([match]).stream().pipeThrough(new CompressionStream('gzip'))
    ).arrayBuffer());

    let bin = '';
    for (const b of packed) bin += String.fromCharCode(b);
    const payload = btoa(bin)
        .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');

    return `https://hedgehog-bg.com/analyze#h1.${format}.gz.${payload}`;
}

// Point a link at it, or window.open() it from a click handler.
document.querySelector('#analyse').href = await hedgehogLink(matText);

Will a match fit?

Comfortably. .mat is repetitive ASCII and compresses about 3.3×. Measured over 1,500 real files:

Partner API

A handoff link opens HedgeHog for the player. The partner API is for an application that keeps the player in its own window: a desktop study tool, a browser app, a club or play site sends a match or a position to HedgeHog's server on behalf of one of its users and reads the analysis back. The user connects their HedgeHog account once, over standard OAuth 2.0, and your application never sees their password.

python3 hedgehog_partner_client.py --client-id https://example.com/oauth/client.json match.mat

Translations

Each catalogue is every interface message for one language, as JSON keyed by where the message appears. A language's glossary is the backgammon vocabulary its catalogue follows, with the terms no language translates.

To review a language or correct a message, edit its catalogue against its glossary and send it to hello@hedgehog-bg.com. Keep every placeholder in braces ({n}, {name}) as it is, and keep the | between a message's plural forms.