Contributing

How the API is proven

The rule is that every game event has override, prepend and append, for both native and Wasm plugins. A test shows each mode changing the outcome, and another test shows that with no plugin the outcome is vanilla. The judge is:

python tools/api_check.py           # derive the events, run the tests, judge
python tools/api_check.py --list    # just the derived events

Deriving the events

The checker reads the code. No list of events is kept by hand:

  1. every plugins::hook(shared, "<name>", …) call outside test code;
  2. every plugins::fire / plugins::cancelled event name, each of which must also be a hook point;
  3. every row of the generated PACKET_NAMES;
  4. every root of the game's command tree, plus BUILT_IN in commands.rs;
  5. a fixed list of subsystems (world generation, structures, movement, block hardness and breaking, loot, damage, spawning, AI, commands, chat, redstone, fluids, portals, packets). Each must have real hook points.

The seven tests

For every event, api_tests! writes:

TestPasses when
vanilla_no plugin and an all-modes Pass plugin give the same outcome, on both paths, and the plugin was actually called
prepend_native, prepend_wasmthe prepend was called and the outcome differs from vanilla
override_native, override_wasmthe override was called and the outcome differs from vanilla
append_native, append_wasmthe append was called and the outcome differs from vanilla

The Wasm tests compile a real module from text and load it with WasmPlugin::load, the loader plugins/*.wasm goes through. The answer crosses linear memory as JSON.

A hook point that is named but not wired fails, because the plugin is never called. A hook whose answer is ignored fails too, because the outcome does not change.

From docs/api/contributing/proof.md in the RustMC repository at bbd81209ad.