Intégrations
VoxelBench s'intègre avec des plugins populaires pour étendre ses fonctionnalités. Toutes les intégrations sont optionnelles : elles s'activent automatiquement quand le plugin correspondant est détecté au démarrage (LiteBans doit en plus être activé), et une intégration défaillante n'arrête jamais VoxelBench.
Les logs de démarrage indiquent quels hooks ont été attachés.
PlaceholderAPI
Les placeholders PlaceholderAPI s'utilisent dans les scoreboards, tab lists, hologrammes et autres plugins. Un placeholder qui n'a pas de valeur à afficher renvoie N/A.
Les placeholders TPS et MSPT de Métriques serveur lisent le moniteur de ticks propre à VoxelBench, qui ne tourne qu'une fois démarré par quelque chose : le tableau de bord web, le mode push, les boss bars, le monitoring distant ou un test. D'ici là, ils renvoient
N/A(les variantes couleur, état et barre renvoientGRAY,UNKNOWNet[??????????]). Les placeholders de durée de tick ci-dessous sont toujours disponibles.
Métriques serveur
| Placeholder | Description |
|---|---|
%voxelbench_tps% | TPS actuel |
%voxelbench_tps_avg%, %voxelbench_tps_min%, %voxelbench_tps_max% | TPS moyen, minimum et maximum |
%voxelbench_tps_color% | GREEN, YELLOW, RED (ou GRAY si non mesuré) |
%voxelbench_tps_colored% | TPS actuel précédé d'un code couleur |
%voxelbench_tps_status% | GOOD, WARNING, CRITICAL (ou UNKNOWN) |
%voxelbench_tps_bar% | Barre texte de 0 à 20 TPS |
%voxelbench_mspt% | MSPT actuel |
%voxelbench_mspt_avg%, %voxelbench_mspt_min%, %voxelbench_mspt_max% | MSPT moyen, minimum et maximum |
%voxelbench_mspt_color%, %voxelbench_mspt_colored%, %voxelbench_mspt_status% | Équivalents des variantes TPS, pour le MSPT |
%voxelbench_ram_used%, %voxelbench_ram_free%, %voxelbench_ram_max% | Heap JVM utilisé, libre et maximum, en Mo |
%voxelbench_ram_percent% | Utilisation du heap en pourcentage |
%voxelbench_ram_color%, %voxelbench_ram_colored%, %voxelbench_ram_status%, %voxelbench_ram_bar% | Couleur, valeur colorée, statut et barre pour l'utilisation du heap |
%voxelbench_cpu% (ou cpu_percent) | Utilisation CPU du processus serveur, en pourcentage |
%voxelbench_cpu_color%, %voxelbench_cpu_colored%, %voxelbench_cpu_status%, %voxelbench_cpu_bar% | Couleur, valeur colorée, statut et barre pour l'utilisation CPU |
%voxelbench_entities% (ou entities_total) | Entités dans tous les mondes |
%voxelbench_entities_hostile%, %voxelbench_entities_passive%, %voxelbench_entities_items% | Mobs hostiles, animaux et items au sol |
%voxelbench_entities_color%, %voxelbench_entities_status% | Couleur et statut pour le nombre d'entités |
%voxelbench_chunks% (ou chunks_loaded) | Chunks chargés dans tous les mondes |
%voxelbench_chunks_color%, %voxelbench_chunks_status% | Couleur et statut pour le nombre de chunks |
%voxelbench_players% (ou players_online) | Joueurs connectés |
%voxelbench_players_max% | Nombre maximum de joueurs |
Placeholders de durée de tick
Ils lisent les métriques de tick que VoxelBench mesure dès le démarrage (voir Métriques de tick, GC et CPU) : rien n'a besoin d'être démarré avant. Sans suffixe de fenêtre, ils couvrent la dernière minute ; ajoutez _10s, _1m, _5m ou _15m pour une autre fenêtre (par exemple %voxelbench_mspt_p95_10s%). Ils renvoient N/A pendant environ une seconde après la première demande, et chaque fois que la valeur n'est pas mesurée sur le serveur.
| Placeholder | Description |
|---|---|
%voxelbench_tick_source% | Origine des durées de tick : paper_tick_event (Paper), main_thread_cpu (Spigot) ou folia_region_tick_event (Folia) |
%voxelbench_mspt_p50%, %voxelbench_mspt_p95%, %voxelbench_mspt_p99% | Médiane, 95e et 99e centile de la durée des ticks, en ms. Sous Spigot, le temps CPU du thread principal par tick ; sous Folia, les ticks de région, toutes régions confondues |
%voxelbench_mspt_peak% | Tick le plus long, en ms. %voxelbench_mspt_max% ci-dessus est une autre valeur : le relevé le plus haut du moniteur de ticks |
%voxelbench_tps_10s%, %voxelbench_tps_1m%, %voxelbench_tps_5m%, %voxelbench_tps_15m% | Ticks par seconde sur la fenêtre, plafonnés à 20 (Paper et Spigot ; N/A sous Folia) |
Benchmark
| Placeholder | Description |
|---|---|
%voxelbench_score% | VoxelScore total du dernier benchmark |
%voxelbench_score_cpu% | Sous-score single-core du dernier benchmark |
%voxelbench_score_gameplay% | Sous-score gameplay du dernier benchmark |
%voxelbench_score_memory%, %voxelbench_score_disk% | Placeholders hérités ; le VoxelScore actuel n'a pas de sous-score mémoire ni disque |
%voxelbench_score_grade% | Note sous forme de lettre (S, A, B, C, D ou F) déduite du dernier VoxelScore |
%voxelbench_benchmark_running% | true pendant qu'un test ou un benchmark tourne |
%voxelbench_benchmark_status% | RUNNING ou IDLE |
Les placeholders de score n'ont de valeur qu'après un benchmark complet terminé et noté depuis le dernier démarrage du serveur.
Placeholders Spark
Lorsque Spark est disponible (voir Spark). Ils renvoient N/A sinon, sauf spark_available, qui renvoie false.
| Placeholder | Description |
|---|---|
%voxelbench_spark_available% | Si Spark est disponible (true/false) |
%voxelbench_spark_tps% (ou spark_tps_10s) | TPS Spark (10 secondes) |
%voxelbench_spark_tps_1m% | TPS Spark (1 minute) |
%voxelbench_spark_tps_5m% | TPS Spark (5 minutes) |
%voxelbench_spark_tps_15m% | TPS Spark (15 minutes) |
%voxelbench_spark_mspt% (ou spark_mspt_10s) | MSPT moyen Spark (10 secondes) |
%voxelbench_spark_mspt_1m% | MSPT moyen Spark (1 minute) |
%voxelbench_spark_mspt_95% | MSPT Spark au 95e percentile (10 secondes) |
%voxelbench_spark_mspt_median% | MSPT médian Spark (10 secondes) |
%voxelbench_spark_cpu_system% | Utilisation CPU du système (1 minute) |
%voxelbench_spark_cpu_process% | Utilisation CPU du processus JVM (1 minute) |
%voxelbench_spark_gc% | Résumé du GC |
Placeholder DiscordSRV
| Placeholder | Description |
|---|---|
%voxelbench_discordsrv_available% | Si DiscordSRV est disponible (true/false) |
Dynmap
L'intégration Dynmap ajoute des couches visuelles à votre carte en direct.
Configuration
integrations:
dynmap:
enabled: true
update-interval-seconds: 30
layers:
entity-heatmap:
enabled: true
thresholds:
low: 50 # En dessous : non dessiné ; au-dessus : jaune
medium: 150 # Jaune → Orange
high: 300 # Orange → Rouge
performance-markers:
enabled: true
entity-threshold: 200
test-zones:
enabled: true
Couches
Les couches sont rafraîchies toutes les update-interval-seconds à partir des entités présentes dans les chunks chargés.
Heatmap de densité d'entités
Couche « VoxelBench - Entity Density ». Affiche la densité d'entités par chunk avec des zones colorées (les chunks sous le seuil low ne sont pas dessinés) :
- Jaune : entre
lowetmedium(modéré) - Orange : entre
mediumethigh(élevé) - Rouge : au-dessus de
high(critique)
Marqueurs d'alerte de performance
Couche « VoxelBench - Performance Alerts ». Place un marqueur sur les chunks dont le nombre d'entités atteint entity-threshold. Utile pour repérer les zones qui causent du lag.
Marqueurs de zones de test
Couche « VoxelBench - Active Tests ». La couche est créée, mais la version actuelle n'y dessine pas encore les zones de test.
Permissions
L'API Dynmap ne permet pas aux plugins de définir les permissions des couches. Pour restreindre l'accès aux couches VoxelBench, éditez plugins/dynmap/markers.yml et ajoutez une permission à chaque ensemble de marqueurs :
sets:
voxelbench.heatmap:
perm: voxelbench.dynmap.heatmap
voxelbench.performance:
perm: voxelbench.dynmap.alerts
voxelbench.testzones:
perm: voxelbench.dynmap.testzones
| Permission | Couche |
|---|---|
voxelbench.dynmap | Toutes les couches : il accorde les nœuds ci-dessous |
voxelbench.dynmap.heatmap | Heatmap de densité d'entités |
voxelbench.dynmap.alerts | Marqueurs d'alerte de performance |
voxelbench.dynmap.testzones | Zones de test actives |
voxelbench.dynmap.view est aussi déclarée, mais aucun ensemble de marqueurs de cet exemple ne l'utilise : seule, elle n'affiche aucune couche.
Les joueurs doivent être connectés à Dynmap ET avoir la permission appropriée.
Spark
L'intégration Spark expose les métriques de Spark via PlaceholderAPI (voir Placeholders Spark), pour afficher des chiffres TPS, MSPT, CPU et GC de qualité Spark dans n'importe quel plugin compatible PlaceholderAPI.
VoxelBench détecte aussi bien le plugin Spark que la version de Spark intégrée à Paper 1.21+. Comme ce Spark intégré se charge après les plugins, VoxelBench refait la détection 5 secondes après le démarrage.
Configuration
integrations:
spark:
enabled: true
DiscordSRV
L'intégration DiscordSRV est prévue pour publier les résultats de benchmark et les alertes de performance dans un salon Discord.
État actuel : VoxelBench détecte DiscordSRV et lit les réglages ci-dessous, mais la version actuelle ne publie encore aucune notification : aucun message n'est envoyé à la fin d'un benchmark ou d'un test, ni lors d'une chute de TPS. Seul le placeholder
%voxelbench_discordsrv_available%est fonctionnel.
Configuration
integrations:
discordsrv:
enabled: true
channel-id: "" # ID du salon Discord (vide = salon principal de DiscordSRV)
notifications:
benchmark-results: true # Résultats de fin de benchmark
test-results: false # Résultats des tests individuels
tps-alerts: true # Alertes de chute de TPS
tps-alert-threshold: 18.0 # Seuil de TPS pour les alertes
Si channel-id est vide, le salon principal configuré dans DiscordSRV est utilisé. Pour obtenir l'ID d'un salon, activez le Mode développeur dans Discord (Paramètres utilisateur → Avancés), faites un clic droit sur le salon puis Copier l'identifiant du salon.
LiteBans
Quand LiteBans est installé, VoxelBench écoute l'API d'événements de LiteBans et transmet chaque sanction que LiteBans enregistre (ban, ban temporaire, mute, mute temporaire, kick, et la levée d'un ban ou d'un mute) avec le joueur et le modérateur, comme événement de modération au monitoring distant de VoxelBench, le tableau de bord de voxelbench.com réservé aux serveurs liés. Les commandes tapées dans le chat ne sont pas lues : une commande refusée par LiteBans, ou traitée par un autre plugin, n'envoie rien. Les avertissements ne sont pas transmis. Une version de LiteBans trop ancienne pour fournir l'API d'événements n'envoie aucun événement de modération.
L'intégration est désactivée par défaut sur une nouvelle installation, puisqu'elle envoie les noms de joueurs qui n'ont rien accepté : réglez remote-monitoring.events.litebans.enabled: true puis redémarrez le serveur. Le motif saisi par le modérateur n'est envoyé qu'avec include-reason: true. Cela n'a d'effet que si le monitoring distant est activé pour un serveur lié. Les bans, mutes et kicks peuvent être suivis séparément avec remote-monitoring.events.litebans (voir Configuration).
Multiverse-Core
Quand Multiverse-Core est installé, les mondes plats créés par VoxelBench (avec /bench world create, ou les mondes de benchmark temporaires) sont importés dans Multiverse avec /mv import et apparaissent donc dans /mv list.
Sans Multiverse, VoxelBench crée et supprime ces mondes avec l'API Bukkit standard. L'intégration ne s'appuie que sur les commandes de Multiverse, pas sur son API interne, et il n'y a rien à configurer.
Ajouter d'autres intégrations
Le système de hooks de VoxelBench est conçu pour se dégrader proprement :
- Les hooks ne sont chargés que lorsque le plugin correspondant est présent
- Si une intégration échoue, VoxelBench continue de fonctionner normalement
- Les intégrations détectées sont actives par défaut, sauf LiteBans (voir LiteBans) ; Dynmap, Spark et DiscordSRV peuvent être désactivées dans
config.yml
Pour ajouter vos propres tests de benchmark depuis un autre plugin, voir Créer une extension.