Как внести вклад

mcrs принимает pull request (PR) со стороны. Эта страница поможет выбрать роль, объяснит, чего от вас требует правило clean-room, и покажет, как изменение проходит путь от issue до слияния.

Выберите роль

Роль	Что делать	С чего начать
Автор спецификации	Описать поведение игры правилами в docs/spec/. Читать можно любой источник, в том числе код игры.	Спецификации и parity-тесты
Исполнитель	Написать код на Rust и тесты по спецификации. Код игры читать нельзя никогда.	Clean-room на практике
Parity-тестер	Сравнить наш результат с тем, что выдала игра, и сообщить о расхождении или починить его.	Спецификации и parity-тесты
Документация и перевод	Написать или перевести страницы этого сайта.	Как писать эту документацию

Для разных задач можно брать разные роли, но две роли для одного и того же поведения взять нельзя. Причина в правиле clean-room, о нем следующий раздел.

Чего требует правило clean-room

mcrs реализует поведение игры по спецификациям и никогда по коду игры. Чтобы так и оставалось, две половины работы делают два разных человека.

Автор спецификации может читать любой источник. В спецификацию он записывает только поведение, то есть входы, выходы, порядок, время и константы. Исполнитель пишет код по этой спецификации и читает только четыре вещи: docs/spec/, публичную документацию о том, что видит игрок, артефакты, которые выдала игра, и код этого репозитория. Один человек не берет обе роли для одного поведения.

Кроме того, в репозитории нет имен классов, методов и полей кода игры. Исключение сделано для шести имен, которыми сообщество пользуется как обычными терминами: ResourceKey, TagKey, BlockPos, SectionPos, ColumnPos и PalettedContainer.

Полные правила записаны в docs/clean-room.md, а пересказ есть на странице Clean-room на практике.

Если вы читали код игры

Многие разработчики под Paper и Fabric каждый день читают декомпилированный код игры. Здесь это знание полезно, потому что для знакомого вам поведения вы можете стать автором спецификации. Но если вы читали код игры про какое-то поведение, своими руками писать его код здесь нельзя.

Реализацию все равно можно сделать, если отдать ее ИИ-агенту. Вы читаете спецификацию и проверяете, что она верна, и следите, чтобы у агента не было доступа к коду игры или его фрагментам. mcrs не ограничивает вклад, написанный ИИ. Мы ему рады, если вы сами разбираетесь в том, как устроена игра. Условия описаны на странице Clean-room на практике.

Эти предосторожности нужны, чтобы никто случайно не скопировал код или алгоритмы оригинальной игры или ее модификаций. Если не уверены, читали ли вы код по задаче, скажите об этом в issue. Никто не будет против.

Путь pull request

1. Найдите или откройте issue. Новому поведению игры нужны две issue. Первая просит спецификацию, вторая просит реализацию и ссылается на ID правил спецификации. Эта пара описана в docs/clean-room.md, в разделе “A new behaviour”.
2. Напишите спецификацию или реализуйте уже готовую. Тест называет ID правила, которое он проверяет.
3. Запустите тесты командами ниже.
4. Откройте PR. Шаблон pull request спрашивает, что вы изменили и зачем, как проверили и обновлена ли документация.
5. Дождитесь CI, он запускает lint, clippy, test и portability. Что делает каждая из проверок, рассказано на странице Сборка и тесты.

cargo nextest run -p <crate>        # один крейт
cargo nextest run --workspace       # все, перед коммитом
cargo nextest run --profile full    # плюс исчерпывающие прогоны

Эти три команды взяты из раздела Development в README. Для них нужен установленный раннер cargo-nextest, а первый запуск скачивает клиентский jar игры, чтобы достать из него датапак.

WIP

Подробного гайда по настройке пока нет. Он появится к альфе для игроков. До тех пор пользуйтесь Quick start в README и техническими заметками, на которые ссылается этот раздел.

Работа с агентом

Инструкции для агентов, которые пишут код, лежат в репозитории. AGENTS.md читает любой агент, а CLAUDE.md - ссылка на этот файл. В нем собраны правила, которые действуют везде: слои, clean-room, стиль, тесты и путь до main. Все более частное разложено по четырем местам.

Путь	Что там лежит
.agents/skills	Скиллы, которые AGENTS.md называет словами “Load <name>”, например rust-style, efficient-testing и ship. .claude/skills/ ссылается на те же папки.
.agents/rules	По одному файлу правил на домен: codec, memory, rendering и simulation. В заголовке правила перечислены пути крейтов, к которым оно относится. .claude/rules/ ссылается на эти файлы.
.claude/agents	Роли implementer, spec-author и reviewer.
.claude/hooks/cargo-guard.sh	Хук Claude Code, который отклоняет cargo test. Почему, объясняет страница Сборка и тесты.

Claude Code сам подгружает скиллы, правила и роли. С другим инструментом то же самое делается вручную. Там, где AGENTS.md говорит “Load <name>”, прочитайте .agents/skills/<name>/SKILL.md. Перед правкой крейта прочитайте правило его домена. Чтобы дать агенту роль, скопируйте ее текст из .claude/agents/ в задание агента.

Роли агентов разводят две роли clean-room. spec-author описывает поведение и не пишет код реализации, а implementer никогда не читает декомпилированный, деобфусцированный или размеченный маппингами код игры.

Документация в том же PR

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

Задачи для первого PR

Эти шесть issue подходят для первого pull request. Что просит каждая и какая для нее нужна роль, написано на странице Первые задачи.

• Баг: исходящая очередь отбрасывает пакеты состояния.¹
• Типизированные пакеты для cookies, transfer и чата.²
• Пример status ping.³
• Эхо-бот чата поверх сетевого слоя.⁴
• Пример инспектора пакетов.⁵
• Отчет о правилах спецификаций, которые не называет ни один тест.⁶

Как быстро проходит ревью

К 2026-11-09 было влито 26 pull request от 5 авторов, не считая владельца. Медианное время от открытия до слияния составило около 12 часов. Самый быстрый PR влили примерно за 40 минут, самый долгий примерно за 5 дней. Выборка маленькая, и почти всю работу ревьюит один человек, поэтому считайте эти числа ориентиром, а не обещанием.

Подсчет можно повторить командой gh pr list -R andreypfau/mcrs --state merged --limit 300 --json number,author,createdAt,mergedAt, а потом уберите из результата PR автора andreypfau.

Где спросить

Вопросы задавайте в Discord или в issue, над которой работаете. Решения записаны в issue с меткой decision.

Footnotes

1. В работе#308 Исходящая очередь отбрасывает пакеты обычного и низкого приоритета после 256 записей. ↩

2. В работе#295 Типизированные пакеты для cookies, transfer, custom query и чата игроков. ↩

3. В работе#290 Пример status ping к встроенному серверу. ↩

4. В работе#293 Эхо-бот чата, которому нужен только сетевой слой. ↩

5. В работе#289 Инспектор пакетов, который декодирует записанную сессию без неизвестных пакетов. ↩

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