`mch`

mch is a highly-compatible lightweight benchmark harness for Minecraft: Java Edition¹.

Warning

Use a world dedicated for benchmarking.

Ensure that the benchmark target is idempotent for accurate results.

Remember that the benchmark results may be affected by Minecraft/JVM/OS/HW.

Do not replace functions in mch namespace.

Supported versions

Usage

Download mch.jar into the same directory as server.jar.

Create mch-config.json with the following content in the directory and add options to it.

{
  "$schema": "https://raw.githubusercontent.com/mcenv/mch/main/mch-config-schema.json"
}

Run the following command to start the benchmarks.
```
java -jar mch.jar
```
The benchmark results will be dumped to mch-results.format.

See samples for more details.

Requirements

Java 17+

Options

Name	Description	Default
`auto_start`	Automatically start benchmarking	`true`
`warmup_iterations`	Number of warmup iterations	`5`
`measurement_iterations`	Number of measurement iterations	`5`
`time`	Duration of iterations in seconds	`10`
`forks`	Number of forks	`5`
`time_unit`	Output time unit (`ns`, `us`, `ms`, `s`, `m`)	`s`
`mc`	Path to Minecraft server	`server.jar`
`output`	Output file name without extension	`mch-results`
`formats`	Output formats (`json`, `md`)
`jvm_args`	JVM arguments to use with forks
`mc_args`	Minecraft arguments to use with forks	`nogui`
`parsing_benchmarks`	Commands for parsing benchmark
`execute_benchmarks`	Commands for execute benchmark

Fixtures

Function tag	Description
`#mch:setup`	To be run once before each group of the function benchmarks
`#mch:setup.trial`	To be run before each run of the group
`#mch:setup.iteration`	To be run before each iteration of the run
`#mch:teardown.iteration`	To be run after each iteration of the run
`#mch:teardown.trial`	To be run after each run of the group
`#mch:teardown`	To be run once after each group of the function benchmarks

Commands

Command	Description
`_`	Returns `0`
`_ <string>`	Takes a string and returns `0`

NOT OFFICIAL MINECRAFT PRODUCT. NOT APPROVED BY OR ASSOCIATED WITH MOJANG. ↩