API d'extension (preview)

Statut preview — pas encore annoncée publiquement. L'API d'extension est fonctionnellement complète et utilisée en interne par les samples fournis avec le plugin, mais elle n'a pas encore été officiellement annoncée pour usage par des tiers. Jusqu'à l'annonce, des changements cassants sont autorisés à chaque release (y compris les patchs). Si vous expérimentez, pinnez votre extension à un SHA git précis.

C'est quoi

Une API Java typée sous fr.wasabii.voxelBench.api qui permet à un plugin d'enregistrer ses propres tests de benchmark auprès de VoxelBench. Une fois enregistré, un test apparaît dans /bench tests list, est auto-complété dans /bench test, tourne via la même orchestration qu'un test intégré, et produit le même format de rapport — avec des champs de provenance identifiant votre plugin comme auteur.

Exemple minimal

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

Ajoutez depend: [VoxelBench] dans votre plugin.yml pour que Bukkit active le plugin hôte en premier.

Statut des symboles individuels

L'API porte des marqueurs @ApiStatus(STABLE | EXPERIMENTAL | INTERNAL) sur chaque type et méthode public. Une fois l'API annoncée :

• STABLE → figé sur les releases minor/patch.
• EXPERIMENTAL → peut changer à n'importe quelle release minor.
• INTERNAL → aucune promesse de compatibilité.

Jusqu'à l'annonce, les trois se comportent comme EXPERIMENTAL.

Quand sera-t-elle annoncée ?

Quand :

1. Une baseline japicmp sera committée et la CI échouera sur les diffs cassants.
2. Le jar d'API sera publié sur au moins un registre public (Modrinth, Hangar, ou Maven Central).
3. Le site aura une section API d'extension stable (cette page sortira du statut "preview").

D'ici là : expérimentez, donnez des retours, mais ne diffusez pas une extension publique que vous ne pouvez pas re-build facilement.