Clean-room in practice

mcrs builds the behavior of the game from descriptions of that behavior and never from the game’s code. This page explains who may read what, what the repository may contain, and what to do if you have already read the game’s code. It retells docs/clean-room.md in plain words. That file is the rule, so if this page and the file differ, the file is right.

Two people do the two jobs

Suppose the project needs the whitelist check at login. One person, the specification author, finds out what the game does and writes it down as rules. A second person, the implementer, writes the Rust code from those rules and never looks at the game’s code. Because the two jobs belong to two people, the code cannot grow out of the game’s code.

	Specification author	Implementer
Output	A file in docs/spec/	Code, tests, design notes
May read	Any source, the game’s code included	docs/spec/, public player-facing documentation, artifacts the game produced, this repository’s code that the rules allow
Must not	Write the shape of the game’s code into the spec	Read decompiled, deobfuscated or mapped game code

“Artifacts the game produced” means the data pack, the reports in assets/mcrs/reports/, captured packets, saves, and the output of tools/vanilla-oracle. This output is evidence, and a parity test compares our output with it.

A specification states behavior, which is inputs, outputs, order, timing and constants as data. It leaves out class, method, field and variable names, and it leaves out the structure of a function.

One person does not take both roles for the same behavior. You can still be an author for one behavior and an implementer for another. The next section describes the one exception, where an AI agent writes the code.

If you have read the game’s code

Many Paper and Fabric developers read decompiled game code every day. If you read the game’s code about some behavior, you do not write the code for that behavior here by hand. You have two ways to contribute to it anyway.

The first way is to write the specification and let a second person write the code from it.

The second way is to give the implementer role to an AI agent. This is the only exception to the rule that one person does not take both roles, and it has two conditions:

1. You read the specification and make sure that it is correct.
2. You make sure that the agent has no access to the game’s code or to pieces of it. Check its files, its prompt and its tools. The agent works from the same sources as any implementer.

mcrs does not restrict contributions that an AI agent writes. We welcome them, provided that you know how the game is structured, because someone has to judge whether the specification and the result are right.

Why these precautions exist

All of these rules have one purpose. They make sure that nobody copies code or algorithms from the original game, or from modifications of it, by accident.

If you are not sure whether you have read the code about a behavior, say so in the issue.

What the repository does not contain

The rule covers code, comments, tests, design notes, commit messages and issues. None of them contains these three things:

• Names of classes, methods or fields of the game’s code.
• Text that calls code a port, a transcription or a mirror of the game’s code. Do not write “port of” in a commit or a doc.
• A test, tool or script that reads the game’s code.

The community uses a few names of the game’s code as common terms, and those are allowed everywhere: ResourceKey, TagKey, BlockPos, SectionPos, ColumnPos and PalettedContainer. A new name joins this list only after a review.

You can name the public APIs of other projects, such as Paper, Bukkit, Velocity and Minestom, because they are not the game’s code.

A provenance label says how far to trust a rule

Each rule in a spec carries a provenance label, which records where the rule comes from. For example, source_suggested means that the author read the reference behavior and states only behavior. When an experiment against the game confirms the rule, the label changes to a confirmed one. A reader uses the label to judge how much to trust a rule. Section 0.3 of docs/spec/registry.md defines the labels.

World generation is the exception

The world generation code stays as it is and keeps its history. The exception covers the crates mcrs_minecraft_worldgen*, mcrs_minecraft_biome and crates/mcrs_minecraft_vanilla_worldgen/, with their design notes. New work in these places follows the normal rules, and a change that touches a game name there removes the name.

Old commit messages may name the game’s code too. History is not rewritten, because a rewrite would break every clone. New commit messages follow the rules.

A new behavior takes two issues

1. An issue asks for a specification, and the author writes it under docs/spec/.
2. A second issue asks for the implementation and cites the rule IDs.
3. The implementer works from the spec. A question goes back to the author, and the answer goes into the spec so that the next reader finds it there and not in a chat.

Next: Specs and parity describes the spec format.