Спецификации и parity-тесты

Спецификация описывает, что делает игра, а parity-тест проверяет, что наш результат совпадает с результатом, который выдала игра. Здесь показано, как устроено то и другое и как они сходятся в паре issue. Точные правила написания спецификации лежат в docs/spec/README.md, а эта страница только помогает в них сориентироваться.

Из чего состоит спецификация

Возьмите за образец docs/spec/whitelist.md. Ее части следуют соглашениям, которые раздел 0 файла docs/spec/registry.md задает для всех спецификаций.

Часть	Что в ней
Таблица Field/Value	Версия игры и версия протокола, для которых написана спецификация.
Термины (0.1)	Каждый термин домена, определенный один раз. В тексте всегда стоит одно и то же слово.
Происхождение (0.2)	Метки black_box_confirmed, source_suggested, documentation, design и unresolved.
Префиксы ID (0.3)	Короткий префикс на тему, например WL-JOIN для проверки белого списка при входе.
Правила	По заголовку на правило: ID вроде WL-JOIN-002, поведение, строка происхождения, вид правила и уверенность.
Намеренные отклонения	Где мы решили не копировать случайность игры, и почему.
Нерешенное	Что пока не решено.
Эксперименты и снятые результаты	Как можно подтвердить каждое правило source_suggested, и уже снятые результаты.

У правила один из шести видов: wire, client agreement, semantic, layout, deviation или unspecified. Правило вида unspecified parity-тест сравнивать не должен.

На 2026-11-09 в docs/spec/ лежат 67 файлов, включая README.

ASD-STE100 действует только внутри docs/spec

Спецификации пишутся на упрощенном техническом английском (Simplified Technical English, ASD-STE100): одно слово на одно понятие, короткие предложения, простые времена, активный залог, “must” для требования. На этом сайте такой стиль не применяется. Сайт пишите простым английским, а docs/spec - по ASD-STE100.

Новому поведению нужна пара issue

Новому поведению нужны две issue, как описано на странице Clean-room на практике. Возьмем ломание блока. Его задача просит спецификацию и реализацию двумя шагами, причем второй агент реализует только по docs/spec/.¹ Задача о подтверждении телепорта просит сначала спецификацию, а затем тесты движка на каждое правило.² Роли агентов для такой пары описаны в разделе Как внести вклад.

Хорошая пара выглядит так:

1. Issue A с меткой clean-room: “Specify X”. Она готова, когда docs/spec/x.md влит и говорит, какие входы, выходы и порядок имеют значение.
2. Issue B: “Implement X”. Она готова, когда у каждого правила есть тест, который называет ID этого правила.

PR со спецификацией - это PR с документацией, кода он не трогает. PR с реализацией ссылается на ID правил и спецификацию не меняет. Если спецификация ошибается или молчит, вернитесь к issue A.

Правила для конкретной редакции, WIP

Спецификации пока не помечают, какие правила к какой редакции игры относятся. Это запланировано.³

Фикстуры снимает с игры оракул

Фикстура - это файл, который выдала игра. Имя фикстуры, задача Gradle, которая ее создает, и папка, куда она попадает, записаны в одном месте, в таблице tools/fixtures.json. В ней 49 записей, из них около 14 относятся к генерации мира.

Второй файл, tools/captures.json, хранит версию игры, на которой снята каждая фикстура. Тест падает поименно для каждой фикстуры, чья версия не совпадает с assets/minecraft/version.json, поэтому после обновления снапшота этот тест становится вашим списком дел. Остальное про обновление есть на странице Переход на новый снапшот.

Фикстуры снимает инструмент tools/vanilla-oracle. Ни клиент, ни сервер игры он не запускает. Он загружает библиотеки самой игры и выгружает значения. Одну фикстуру переснимает одна команда:

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

Оракул знает код игры

Исходники tools/vanilla-oracle вызывают код игры напрямую. Исполнителю читать их нельзя. Читайте фикстуру и лежащую рядом процедуру съемки (*_capture_procedure.md): в них сказано, что снимается, но не как игра это вычисляет. Автор спецификации оракул читать может.

Parity-тест сравнивает с фикстурой

Parity-тест лежит в файле parity.rs или *_parity.rs. Ожидаемые значения он загружает из фикстуры через mcrs_minecraft_fixtures, потому что тест заявляет совпадение с игрой, а подтвердить это может только файл, который выдала игра. Проверка parity из xtask предупреждает, когда такой тест не загружает фикстуру или сравнивает с литералом. Запускается она командой scripts/hooks/run-checks commit.

Чтобы добавить parity-тест, снимите фикстуру оракулом, как описано в его README, загрузите ее в тесте *_parity.rs и назовите ID правила в имени теста.

Отчет о правилах, которые не называет ни один тест, запланирован.⁴

Parity генерации мира - особый случай. Эталонные дампы покрывают выбранные сиды и чанки, поэтому “совпадает с ванилью” там значит “совпадает на этих дампах”. Подробнее об этом на странице Совпадение с ванилью.

Footnotes

1. Частично#474 Просит спецификацию и плагин ломания блока. ↩

2. Частично#623 Просит описать, какое подтверждение принимает телепорт, и повторную отправку неподтвержденного. ↩

3. В работе#656 Планирует, что спецификации помечают правила, которые относятся к одной редакции. ↩

4. В работе#507 Планирует отчет о правилах спецификаций, которые не проверяет ни один тест. ↩