Specs and parity tests

A specification says what the game does, and a parity test checks that our output equals output the game produced. This page shows how each is built and how the two meet in a pair of issues. The exact rules for writing a spec are in docs/spec/README.md, and this page only helps you find your way around them.

What a spec contains

Take docs/spec/whitelist.md as the model. Its parts follow the conventions that section 0 of docs/spec/registry.md defines for all specs.

Part	What it holds
Field/Value table	The game version and the protocol version the spec was written for.
Terms (0.1)	Each term of the domain, defined once. The text uses the same word every time.
Provenance (0.2)	The labels black_box_confirmed, source_suggested, documentation, design and unresolved.
ID prefixes (0.3)	A short prefix per subject, for example WL-JOIN for the whitelist check at login.
Rules	One heading per rule, with an ID like WL-JOIN-002, the behavior, a provenance line, its kind and its confidence.
Intentional deviations	Where we choose not to copy an accident of the game, with the reason.
Unresolved	What is not decided yet.
Experiments and captured results	How each source_suggested rule can be confirmed, and the results already captured.

A rule has one of six kinds: wire, client agreement, semantic, layout, deviation or unspecified. A parity test must not compare an unspecified rule.

On 2026-11-09, docs/spec/ holds 67 files, the README included.

ASD-STE100 applies only inside docs/spec

Specifications use Simplified Technical English (ASD-STE100): one word for one concept, short sentences, simple tenses, active voice, “must” for a requirement. This site does not use that style. Write this site in plain English, and write docs/spec in ASD-STE100.

A new behavior takes a pair of issues

A new behavior takes two issues, as Clean-room in practice describes. Block breaking is an example. Its task asks for the specification and the implementation as two steps, with a second agent that implements from docs/spec/ only.¹ The task for teleport confirmation asks for a specification first, and then for engine tests per rule.² How to contribute describes the agent roles for such a pair.

A good pair looks like this:

1. Issue A, label clean-room: “Specify X”. It is done when docs/spec/x.md is merged and states which inputs, outputs and order matter.
2. Issue B: “Implement X”. It is done when each rule has a test that names its rule ID.

A spec PR is a docs PR and does not touch code. An implementation PR cites rule IDs and does not change the spec. If the spec is wrong or silent, go back to issue A.

Edition-specific rules, WIP

Specifications do not yet mark which rules belong to which game edition. This is planned.³

Fixtures come from the game through the oracle

A fixture is a file the game produced. The table tools/fixtures.json is the single place that states a fixture’s name, the Gradle task that makes it and the folder it goes to. It has 49 entries, and about 14 of them concern world generation.

A second file, tools/captures.json, records the game version at which each fixture was captured. A test fails by name for every fixture whose version is not the one in assets/minecraft/version.json, so after a snapshot update that test is your to-do list. Move to a new snapshot covers the rest of the update.

The tool that takes the captures is tools/vanilla-oracle. It runs no game client and no server. It loads the game’s own libraries and dumps values. One command recaptures a fixture:

cargo run -p mcrs_minecraft_update -- recapture <fixture name>

The oracle knows the game's code

The sources of tools/vanilla-oracle call the game’s code directly. An implementer must not read them. Read the fixture and the capture procedure next to it (*_capture_procedure.md), which describe what is captured and not how the game computes it. A specification author may read the oracle.

A parity test compares against a fixture

A parity test lives in a file named parity.rs or *_parity.rs. It loads its expected values from a fixture through mcrs_minecraft_fixtures, because the test claims to match the game and only a file the game produced can back that claim. The parity check of xtask warns when such a test loads no fixture or compares against a literal. Run the check with scripts/hooks/run-checks commit.

To add a parity test, capture the fixture with the oracle as its README describes, load the fixture in a *_parity.rs test, and name the rule ID in the test name.

A report of the rules that no test names is planned.⁴

The parity of world generation is a special case. The reference dumps cover chosen seeds and chunks, so “matches vanilla” there means “matches on these dumps”. Parity explains this.

Footnotes

1. Partial#474 Asks for the specification and the plugin of block breaking. ↩

2. Partial#623 Asks to specify which accept confirms a teleport, and the resend of an unconfirmed one. ↩

3. WIP#656 Plans that specifications mark edition-specific rules. ↩

4. WIP#507 Plans a report of the specification rules that no test checks. ↩