Configuration de CannonRTP

CannonRTP répartit ses réglages globaux dans plusieurs fichiers de plugins/CannonRTP/. Chaque canon possède également son propre fichier dans plugins/CannonRTP/cannons/.

Organisation des fichiers

Fichier	Rôle
plugins/CannonRTP/config.yml	Réglages généraux : état de la configuration initiale, langue, intervalle des particules, délai entre lancements, priorité des modèles de canon, identifiant de ressource Spigot et réglages de mise à jour Nightbreak
plugins/CannonRTP/landing.yml	Recherche des atterrissages : taille de la file, limite de tentatives, durée de chute lente, listes de matériaux dangereux et comportement en cas d'erreur de protection
plugins/CannonRTP/sounds.yml	Sons de la séquence de lancement
plugins/CannonRTP/messages.yml	Messages destinés aux joueurs, préfixes et listes de titres
plugins/CannonRTP/protection.yml	Activation et réglages des intégrations de protection par plugin
plugins/CannonRTP/cannons/<id>.yml	Un fichier par canon, pouvant contrôler plusieurs placements
plugins/CannonRTP/cannons_disabled/	Dossier des configurations de canons fournies avec des packs de contenu actuellement désactivés. Le menu /wc setup déplace les fichiers entre cannons/ et cannons_disabled/ à l'activation ou à la désactivation d'un pack.
plugins/CannonRTP/content_packages/<package>.yml	Métadonnées générées pour chaque pack Nightbreak : version, lien de téléchargement et préfixes permettant de retrouver ses fichiers. Elles ne se modifient normalement pas à la main.
plugins/CannonRTP/imports/	Dossier de dépôt des importations manuelles de contenu. Voir Packs de contenu.
plugins/CannonRTP/nightbreak-changelogs.yml	État de lecture de la boîte de réception partagée /wcchangelog. Voir Notifications de notes de version.

Le plugin fournit trois exemples de configuration de canon :

• example_cannonrtp.yml — modèle de référence vide nommé Example World Cannon, désactivé par défaut. Utilisez-le comme référence YAML pour écrire vos propres fichiers.
• cannonrtp_free_cannon.yml — activé, sans placement, utilisant le modèle FMM gratuit cannonrtp.
• cannonrtp_premium_cannon.yml — activé, sans placement, utilisant le modèle FMM premium cannonrtp_premium.

Aucun ne contient de valeur dans cannonLocations par défaut. Rien n'apparaît donc dans le monde avant qu'un administrateur n'exécute /wc create ou /wc place. Aucun ne définit targetWorld : chaque placement fait donc atterrir les joueurs dans le monde où il se trouve.

CannonRTP recrée chacun de ces trois fichiers absent de cannons/ à chaque chargement des configurations de canons. Supprimer l'un d'eux avec /wc delete, ou le déplacer lors de la désactivation de son pack de contenu, laisse après le rechargement une nouvelle copie par défaut sans placement.

config.yml

Clé	Valeur par défaut	Comportement
setupDone	false	Indique si la première configuration Nightbreak est terminée
language	english	Fichier de traduction à charger. La version 1 fournit uniquement l'anglais ; cette clé prévoit de futurs packs de traduction
runtime.particleIntervalTicks	15	Intervalle exact entre les affichages des particules du canon au repos, en ticks du serveur ; minimum 1. Utilisez 1 pour un affichage à chaque tick
runtime.launchCooldownSeconds	30	Secondes d'attente entre deux lancements acceptés pour un joueur ; minimum 0, avec 0 pour désactiver. Un CannonRTPLaunchEvent annulé ne démarre pas ce délai.
runtime.cannonModelPriority	[cannonrtp_premium, cannonrtp]	Liste des noms de modèles FreeMinecraftModels, examinée de haut en bas. Le premier modèle trouvé est utilisé pour les canons sans customModel propre. Si aucun n'est disponible, des particules en orbite le remplacent.
runtime.spigotResourceId	""	Identifiant de ressource Spigot utilisé pour la recherche de version. Laissez vide pour désactiver cette recherche.
nightbreak.autoDownloadPluginUpdates	false	Ajoutée par MagmaCore, intégré au JAR. Avec true, CannonRTP télécharge automatiquement, quelques minutes après le démarrage, les mises à jour disponibles du plugin et du contenu. Les mises à jour de contenu sont utilisées après le prochain redémarrage ; une mise à jour du plugin suit nightbreak.applyPluginUpdatesWithoutRestart. Le téléchargement automatique du plugin nécessite un jeton Nightbreak valide et une adhésion de soutien active. Laissez false pour utiliser le bouton de mise à jour en jeu.
nightbreak.applyPluginUpdatesWithoutRestart	never	Ajoutée par MagmaCore, intégré au JAR. Détermine quand une mise à jour du plugin téléchargée est appliquée en rechargeant CannonRTP depuis le nouveau JAR. never attend le prochain redémarrage. when-empty l'applique immédiatement si aucun joueur n'est connecté ; sinon, vérifie toutes les 30 secondes et l'applique dès que le serveur est vide. immediately l'applique dès la fin du téléchargement. Toute autre valeur compte comme never. Le rechargement annule les lancements en cours comme décrit dans Protection contre les déclenchements répétés. /wc applypluginupdate applique manuellement une mise à jour téléchargée, quel que soit ce réglage.

landing.yml

Clé	Valeur par défaut	Comportement
preloadedLocationsPerCannon	10	Nombre total de destinations sûres que le plugin essaie de conserver en file par canon ; minimum 1
chargedLocationsPerCannon	1	Nombre de destinations nécessaires pour afficher Ready ; minimum 1, plafonné à preloadedLocationsPerCannon. Une seule destination en file suffit pour lancer un joueur : ce seuil ne concerne que l'étiquette visuelle.
searchTimeoutAttempts	100	Nombre de recherches échouées avant l'état Exhausted ; minimum 10. Les recherches sont limitées globalement à une tentative par tick, soit 20 par seconde, répartie équitablement entre les canons actifs.
slowFallingSeconds	60	Durée maximale de Chute lente après le largage ; minimum 1. L'effet est retiré plus tôt si le joueur atterrit.
failOpenOnProtectionErrors	false	Bloque par défaut l'atterrissage si une API de protection provoque une erreur. Utilisez true pour poursuivre les atterrissages lorsqu'un plugin de protection ne peut pas être interrogé correctement. Avec false, une intégration de protection activée qui n'a pas pu se charger empêche aussi tous les canons de chercher (voir Intégrations de protection).
unsafeGroundMaterials	[LAVA, MAGMA_BLOCK, CAMPFIRE, SOUL_CAMPFIRE, CACTUS, POWDER_SNOW]	Matériaux qui rendent une surface d'atterrissage inadmissible
unsafeBodyMaterials	[LAVA, WATER, FIRE, SOUL_FIRE, SWEET_BERRY_BUSH, POWDER_SNOW, COBWEB]	Matériaux interdits dans toute la colonne verticale d'atterrissage et de largage, y compris l'espace de la tête à l'arrivée

Les matériaux utilisent les noms de l'énumération Bukkit Material. Les entrées invalides sont signalées par des avertissements dans les logs, puis ignorées.

sounds.yml

Clé	Valeur par défaut	Comportement
levitationStart.sound	BLOCK_BEACON_ACTIVATE	Son joué au début de la phase de recherche
levitationStart.volume	1.0
levitationStart.pitch	1.15
blastOff.sound	ENTITY_GENERIC_EXPLODE	Son joué au début de la phase de tir
blastOff.volume	1.0
blastOff.pitch	0.9

Les sons acceptent les noms de l'énumération Bukkit Sound, comme BLOCK_BEACON_ACTIVATE, ou des clés avec espace de noms, comme minecraft:block.beacon.activate. Un nom de style énumération est converti en remplaçant chaque tiret bas par un point : un son dont la clé contient un tiret bas, comme minecraft:block.note_block.pling, doit donc être écrit sous forme de clé avec espace de noms. Un nom de son invalide produit un avertissement dans les logs et aucun son n'est joué à cette étape. Laissez un son vide pour ne rien jouer. Un volume ou une hauteur inférieurs à 0 sont ramenés à 0.

messages.yml

Tous les messages prennent en charge les dégradés MagmaCore, les balises MiniMessage et les anciens codes couleur &. La variable $prefix est remplacée par le préfixe configuré.

La page Messages et titres présente toutes les clés de messages, les variables et les listes de titres utilisées pendant le lancement.

Champs de configuration propres à chaque canon

Chaque fichier plugins/CannonRTP/cannons/<id>.yml contient les champs suivants :

Champ	Valeur par défaut	Remarques
isEnabled	true pour les canons nouvellement créés	Les canons désactivés ne se déclenchent pas, ne font apparaître ni étiquette ni modèle, et affichent Disabled dans /wc list et /wc status
displayName	CannonRTP, ou le nom fourni à la création	Utilisé dans les messages, les informations de statut et l'étiquette flottante
cannonLocations	liste vide	Liste de chaînes sérialisées world,x,y,z,yaw,pitch. Une configuration peut produire plusieurs placements dans le monde. Gérée par /wc create, /wc place et /wc remove.
targetWorld	monde du joueur à la création	Permet d'envoyer les joueurs dans un autre monde que celui du canon. S'il est vide ou absent, chaque placement fait atterrir les joueurs dans son propre monde. Le monde doit être chargé à l'exécution ; sinon, le canon suspend le préchargement et /wc status indique Target world <name> is not loaded.
searchCenter	null	Sans valeur, la recherche part de la position du canon s'il est dans le monde cible, sinon du point d'apparition du monde cible. S'il désigne une position dans un autre monde, ses coordonnées X et Z sont utilisées dans le monde cible.
triggerRadius	1.75	Rayon autour du canon utilisé pour détecter les joueurs ; minimum 0,5 bloc
minSearchRadius	500	Distance minimale de recherche d'atterrissage depuis le centre ; minimum 0
maxSearchRadius	5000	Distance maximale de recherche, toujours portée au minimum à minSearchRadius + 1
launchWarmupTicks	42	Durée de la phase Searching, en ticks ; minimum 1
verticalBoostTicks	45	Durée de la phase Firing, en ticks ; minimum 0. 0 supprime la poussée ascendante ; le son de décollage, l'effet d'explosion et le titre de destination sont tout de même joués avant la téléportation.
verticalBoostVelocity	1.35	Vitesse ascendante appliquée à chaque tick de la phase de tir ; minimum 0
enableParticles	true	Active l'animation de particules en orbite au repos. Elle n'est affichée que si aucun modèle personnalisé n'est actif et qu'un joueur est à moins de 36 blocs.
requiredPermission	""	Permission supplémentaire facultative propre à ce canon. Les joueurs possédant cannonrtp.use mais pas cette permission reçoivent le message de refus configuré.
customModel	""	Nom facultatif d'un modèle FreeMinecraftModels propre au canon. S'il est vide ou indisponible, le plugin utilise runtime.cannonModelPriority.

Valeurs à la création d'un canon

Lorsque vous exécutez /wc create <id> :

• l'identifiant est converti en minuscules et les caractères autres que a-z, 0-9, _ et - sont remplacés par _
• displayName vaut CannonRTP, sauf si vous avez utilisé /wc create <id> <display_name> ; les tirets bas de <display_name> deviennent des espaces
• la position actuelle du joueur est ajoutée à cannonLocations
• targetWorld reçoit le monde actuel du joueur
• searchCenter reste indéfini : la recherche utilise la position du canon s'il se trouve dans le monde cible, sinon le point d'apparition de ce monde

Après la création, le plugin affiche le chemin absolu du fichier de configuration. Vous pouvez ainsi modifier à la main displayName, customModel, requiredPermission, les rayons de recherche et les réglages de lancement.

Intégration FreeMinecraftModels

Si FreeMinecraftModels est installé et qu'un modèle valide est trouvé grâce au customModel du canon ou à la liste globale runtime.cannonModelPriority :

• une entité de modèle statique apparaît à la position du canon
• l'étiquette flottante est placée à 2,0 blocs au-dessus du canon, au lieu de 1,2 sans modèle, pour ne pas traverser celui-ci
• les particules en orbite au repos sont masquées tant que le modèle est actif
• au début de la phase de recherche d'un lancement, le canon joue son animation fire si elle existe ; le joueur reçoit Invisibilité pendant cette phase pour ne pas gêner l'animation

Si FreeMinecraftModels est activé ou désactivé pendant le fonctionnement du serveur, le cache des modèles de canons est invalidé. Les versions actuelles de FMM signalent également à CannonRTP la fin d'un rechargement de contenu : les références périmées sont alors supprimées et les modèles recréés depuis le registre actualisé. CannonRTP détecte aussi directement les instances de modèles supprimées, y compris avec FMM 2.4.0, antérieur à cet événement. Tant que FMM est activé, les recréations en attente sont réessayées tous les 20 ticks jusqu'à la disponibilité d'un modèle utilisable.

Particules de remplacement au repos

Lorsqu'aucun modèle n'est actif, le canon affiche deux particules en orbite autour de son centre, DUST_COLOR_TRANSITION et FIREWORK. Leurs couleurs varient selon l'état effectif du canon :

État	Couleur principale	Couleur secondaire
Ready	orange (255, 179, 71)	or pâle (255, 241, 168)
Searching, charging / maintaining	orange chaud (255, 140, 66)	or (255, 209, 102)
Exhausted	rouge (255, 107, 107)	orange chaud (255, 159, 104)

Ces particules ne sont affichées que si un joueur est à moins de 36 blocs du canon, que enableParticles vaut true et qu'aucun modèle personnalisé n'est actif.

Étiquette flottante de statut

Chaque canon activé crée au-dessus de sa base un TextDisplay orienté vers le joueur, affichant son nom et son état actuel : Ready, Charging, Maintaining ou Exhausted. Les canons désactivés ne créent aucune étiquette. L'étiquette n'est jamais enregistrée dans les données du chunk et se recrée automatiquement au rechargement de celui-ci. Elle se trouve à 1,2 bloc au-dessus du canon, ou à 2,0 blocs lorsqu'un modèle FreeMinecraftModels est actif.

Validations à l'exécution

CannonRTP refuse les destinations candidates dans les cas suivants :

• le monde cible n'est pas chargé
• le centre de recherche est introuvable, ce qui arrive uniquement si le monde cible n'est pas chargé
• le point choisi au hasard se trouve hors de la bordure du monde
• le chunk candidat ne peut pas être chargé
• aucune surface sûre, solide et non liquide n'est trouvée
• un bloc de la colonne de largage de 52 blocs au-dessus de l'atterrissage est obstrué
• la surface ou un bloc de la colonne figure dans les listes configurées de matériaux dangereux
• une intégration de protection bloque l'atterrissage
• un écouteur de CannonRTPLocationValidationEvent rejette le candidat

Après searchTimeoutAttempts recherches échouées, soit 100 par défaut, le préchargement peut passer à Exhausted. Les destinations déjà en file restent utilisables. L'activation ne renvoie le message d'échec configuré que si la file est vide ; ce message résume les raisons de rejet courantes. Libérer une place dans la file après un lancement réinitialise le compteur de tentatives.

Le terrain cible doit déjà exister : les chunks candidats sont chargés sans génération de terrain. Générez ou explorez d'abord la zone de recherche configurée ; dans un monde neuf, une zone inexplorée peut laisser la file vide.

Protection contre les déclenchements répétés

CannonRTP empêche un joueur de déclencher un canon pendant une séquence de lancement active. Le verrou reste en place jusqu'à la fin du lancement et jusqu'à ce que le joueur ait effectivement quitté le rayon de déclenchement. Un retour de récupération au siège du canon ne peut donc pas provoquer immédiatement un nouveau lancement. Une fois un lancement accepté, un délai de récupération par joueur, commun à tous les canons du gestionnaire, s'applique pendant runtime.launchCooldownSeconds, soit 30 secondes par défaut. Il résiste aux déconnexions tant que le serveur reste en fonctionnement, utilise une horloge monotone et est effacé chaque fois que CannonRTP reconstruit ses canons : /wc reload, une mise à jour du plugin sans redémarrage, l'arrêt du plugin ou toute commande de modification de canon (create, place, remove, delete, target, center). Une reconstruction annule aussi les lancements en cours, ramène les joueurs concernés au siège de leur canon et abandonne toutes les destinations en file. Entrer trop tôt dans un canon affiche le message configurable launchCooldown. Réglez la valeur sur 0 pour désactiver ce délai.