Installation de MegaBlock Survivors

Le processus d'installation de MegaBlock Survivors s'articule autour des packages de contenu gérés par Nightbreak, avec une prise en charge optionnelle des modèles via FreeMinecraftModels.

Prérequis

• Java 21
• Un serveur compatible Paper/Spigot sur la ligne d'API 1.21.4

Intégrations optionnelles :

• FreeMinecraftModels -- modèles personnalisés de mobs et d'armes (dépendance optionnelle)
• LibsDisguises -- dépendance optionnelle pour un support visuel supplémentaire

Ce que MegaBlock Survivors crée

Au démarrage, MegaBlock Survivors initialise ou utilise ces chemins sous plugins/MegaBlockSurvivors/ :

plugins/MegaBlockSurvivors/config.yml
plugins/MegaBlockSurvivors/translations.yml
plugins/MegaBlockSurvivors/content_packages/
plugins/MegaBlockSurvivors/imports/
plugins/MegaBlockSurvivors/worlds/
plugins/MegaBlockSurvivors/npcs/
plugins/MegaBlockSurvivors/leaderboard.yml
plugins/MegaBlockSurvivors/meta_progression.yml
plugins/MegaBlockSurvivors/stats-dump.log
plugins/MegaBlockSurvivors/version.txt

Il charge également automatiquement un monde de lobby créé par l'opérateur nommé mbs_spawn si son dossier existe sur le disque. Le plugin ne crée ni ne modifie ce monde -- il se contente de le charger. Plusieurs fonctionnalités du plugin retombent silencieusement sur un comportement par défaut si mbs_spawn est absent :

• L'hologramme du classement (ancré à (4.5, 67, -14.5) dans mbs_spawn) n'est pas invoqué et un avertissement est journalisé.
• La téléportation à la connexion (SpawnLobbyListener) envoie les joueurs entrants à (0.5, 65, 0.5) dans mbs_spawn avec un yaw de 180 -- contournée lorsque le joueur a une partie active.
• La fin de partie ramène le joueur vers mbs_spawn s'il existe.

Configuration

config.yml contient :

Clé	Type	Défaut	Description
setupDone	booléen	false	Indique si le guide d'installation initial a été complété

Traductions

Toutes les chaînes destinées aux utilisateurs (messages de chat, titres de dialogues, barres de boss, textes d'hologrammes, descriptions de commandes) sont chargées depuis translations.yml. Les opérateurs de serveur peuvent localiser ou repersonnaliser chaque ligne sans toucher au jar. Fonctionnalités prises en charge :

• Codes couleur classiques préfixés par & et codes hexadécimaux &#RRGGBB.
• Balises de dégradé MagmaCore telles que <gradient:#FF0000:#00FF00>text</gradient>.
• Jetons {placeholder} qui sont substitués par le plugin au moment de l'exécution.
• Les clés manquantes apparaissent comme un marqueur visible [translations: key.name], ce qui rend les entrées non définies faciles à repérer en jeu.

Le fichier est régénéré avec les entrées par défaut à la première exécution et à chaque rechargement du plugin, de sorte que les nouvelles chaînes ajoutées apparaissent automatiquement.

Données persistantes des joueurs

Fichier	Rôle
leaderboard.yml	Entrées de classement par compartiment (6 sections : 2 modes de jeu x 3 difficultés), plafonnées à 100 entrées par compartiment.
meta_progression.yml	Solde d'Échos d'Âme et niveaux des pistes d'amélioration par joueur. Indexé par UUID du joueur.
stats-dump.log	Journal en lignes JSON, en mode ajout uniquement, de chaque partie terminée, écrit à la fin du match.

Avertissement d'installation initiale

Lorsque setupDone vaut false, le plugin affiche un avertissement d'installation initiale aux joueurs disposant de la permission megablocksurvivors.* lors de leur connexion. L'avertisseur est configuré (via NightbreakFirstTimeSetupSpec) avec uniquement une commande d'installation, il oriente donc les joueurs vers /mbs setup (le navigateur de contenu) et non vers une étape d'initialisation/de téléchargement. /mbs initialize n'est pas enregistrée dans cette version ; /mbs downloadall est enregistrée mais ne récupère que le jar du plugin puisque les packages de contenu sont désactivés (voir la page Commandes) -- utilisez plutôt /mbs setup.

Procédure recommandée pour la première installation

1. Installez MegaBlock Survivors et démarrez le serveur une fois. Les fichiers de traduction et de configuration sont écrits à la première exécution.
2. Liez votre compte Nightbreak avec /nightbreaklogin <token>.
3. Exécutez /mbs setup pour ouvrir le navigateur de contenu Nightbreak et installer / activer les packages souhaités.
4. Exécutez /mbs reload si vous déposez manuellement du contenu dans imports/, ou après avoir basculé des packages dans content_packages/.

/nightbreaklogin <token> est fourni par le flux de compte partagé Nightbreak/MagmaCore, pas par le plugin.yml de MegaBlock Survivors.

Packages de contenu

Les packages de contenu sont configurés via des fichiers YAML dans le dossier content_packages/. Chaque package peut définir :

Champ	Type	Description
isEnabled	booléen	Indique si le package est actif
name	chaîne	Nom d'affichage du package
description	liste de chaînes	Lignes de description
downloadLink	chaîne	URL de téléchargement manuel
version	entier	Numéro de version du package
nightbreakSlug	chaîne	Slug de contenu Nightbreak pour les téléchargements automatiques
schematicFiles	liste de chaînes	Fichiers de schématiques inclus dans le package
worldFolders	liste de chaînes	Dossiers de mondes inclus
worldContainerFolders	liste de chaînes	Dossiers de conteneurs de mondes inclus
modelFolders	liste de chaînes	Dossiers de modèles pour FreeMinecraftModels
markerFileName	chaîne	Fichier marqueur permettant de détecter si le package est installé
category	enum	FREE, PREMIUM ou RESOURCES
toggleable	booléen	Indique si le package peut être activé/désactivé

Configuration des PNJ

Les PNJ (donneurs de quêtes du lobby, marchands) sont configurés via des fichiers YAML dans npcs/. Les PNJ sont réinvoqués au chargement des chunks afin de survivre aux cycles de déchargement/rechargement des chunks du lobby. Un clic droit sur un PNJ exécute son interactionCommand configuré.

Deux PNJ sont livrés avec le plugin et s'invoquent automatiquement dans mbs_spawn lorsque ce monde est chargé :

PNJ	Emplacement par défaut	Déguisement	Commande d'interaction
Match Starter	mbs_spawn, 0, 67, -15	VILLAGER	mbs start
Meta Progression	mbs_spawn, -9, 66, -13	PIGLIN	mbs meta

Chacun peut être désactivé, déplacé ou reconfiguré en modifiant le YAML correspondant dans npcs/. Les déguisements nécessitent LibsDisguises pour s'afficher ; sans lui, le PNJ apparaît toujours en tant qu'entité de base à l'emplacement configuré.

Champs YAML des PNJ

Champ	Type	Description
isEnabled	booléen	Indique si le PNJ apparaît
name	chaîne	Nom interne
location	chaîne	Format world,x,y,z,pitch,yaw
disguise	chaîne	Type d'entité LibsDisguises (optionnel)
interactionCommand	chaîne	Commande à exécuter lorsqu'un joueur fait un clic droit sur le PNJ
nameTag	chaîne	Hologramme flottant au-dessus du PNJ (codes couleur autorisés)

Notifications de mise à jour de version

Lorsque le plugin détecte un changement de version (en comparant avec version.txt), il notifie la console et tous les OPs en ligne.