Extension API (Preview)

Preview status — not announced for public use yet. The extension API is functionally complete and used internally by the samples bundled with the plugin, but it hasn't been officially announced for third-party use. Until the announcement, breaking changes are allowed on every release (including patches). Pin your extension to a specific git SHA if you experiment.

What it is

A typed Java API under fr.wasabii.voxelBench.api that lets a plugin register its own benchmark tests with VoxelBench. Once registered, a test shows up in /bench tests list, autocompletes in /bench test, runs through the same orchestration as a built-in test, and produces the same report format — with provenance fields identifying your plugin as the author.

Minimal example

public class MyExtension extends JavaPlugin {
    @Override
    public void onEnable() {
        VoxelBenchAPI api = VoxelBenchAPI.getInstance();
        api.getTestRegistry().register(
            TestDescriptor.builder()
                .id("myplugin.cacheBench")
                .displayName("Cache Throughput")
                .category(TestCategory.EXTENSION)
                .author("YourName")
                .version("1.0.0")
                .tags("cache", "io")
                .documentationUrl("https://example.com/myplugin/cache-bench")
                .params(
                    ParamSpec.intParam("iterations").defaultValue(100).range(1, 10_000).build()
                )
                .metrics(
                    MetricSpec.scalar("ops_per_sec").unit("ops/s").higherIsBetter(true).primary(true).build()
                )
                .builder(ctx -> new MyCacheBench())
                .build(),
            this);
    }
}

Add depend: [VoxelBench] to your plugin.yml so Bukkit enables the host plugin first.

Status of individual symbols

The API carries @ApiStatus(STABLE | EXPERIMENTAL | INTERNAL) markers on every public type and method. Once the API is announced:

• STABLE → frozen across minor/patch releases.
• EXPERIMENTAL → may change in any minor release.
• INTERNAL → no compat promise at all.

Until announcement, all three behave like EXPERIMENTAL.

When will it be announced?

When:

1. A japicmp baseline is checked in and CI fails on breaking diffs.
2. The api jar is published to at least one public registry (Modrinth, Hangar, or Maven Central proper).
3. The site has a stable Extension API section (this page graduates out of "preview").

Until then: experiment, give feedback, but don't ship a public extension you can't easily rebuild.