Hytale Modding API : Le guide complet de développement du plugin serveur

Le système de plugin serveur d'Hytale donne aux développeurs un contrôle profond sur tous les aspects du jeu. Si vous avez écrit des plugins Bukkit ou Spigot pour Minecraft, la transition est simple — mais l'architecture d'Hytale est fondamentalement différente de manière importante. Ce guide vous accompagne dans tout, de la configuration initiale au déploiement de la production. Architecture Aperçu Avant d'écrire un code, comprenez comment fonctionne le moudage de Hytale : Le client est un rendeur. Le client C# d'Hytale gère les graphiques, les entrées et l'audio — mais ne contient aucune logique de jeu. Toutes les simulations se déroulent sur le serveur Java, même en solo. Tout est côté serveur. Lorsque les joueurs rejoignent un serveur à moted, les actifs personnalisés et le flux de comportement automatiquement. Pas besoin de mods client. Quatre catégories existent: Data Assets (JSON), Art Assets (modèles Blockbench), Server Plugins (Java) et Visual Scripting (à venir). Les plugins de serveur sont la catégorie la plus puissante — ils vous donnent l'accès complet Java à l'exécution du serveur, y compris le système de composants de l'entité, pipeline d'événements, cadre de commande et manipulation mondiale. Configuration de l'environnement de développement Préalables OutilVersionNotes Java25+ Hytale utilise des fonctionnalités modernes incluant des threads virtuels (Project Loom) IntelliJ IDEACommunauté ou ultimeRecommandé IDE — L'édition communautaire gratuite fonctionne bien Gradle9.2.0+Système de construction (inclus dans le modèle de plugin) Git Toute version récente Pour le clonage du modèle officiel Cluner le modèle officiel Hypixel Studios fournit un modèle de plugin officiel sur GitHub: clone-git https://github.com/HytaleModding/plugin-template.git Ma première phrase cd MyFirstPlugin Ouvrez le projet dans IntelliJ IDEA et laissez Gradle synchroniser. Le modèle comprend la structure correcte du répertoire, la configuration de construction et les dépendances de l'API du serveur. Alternativement, le HytaleIO Générateur de projet à hytaleio.com/générateur de projet peut créer des échafaudages de projet Plugin, Mod ou Full (combo) avec une interface utilisateur Web. Structure de la solution Chaque plugin Hytale suit cette disposition de répertoire: votre-plugin/ - Src/main/java/com/votre nom/votreplugin/ - Votre Pluie. Java # Point d'entrée principal Src/main/ressources/ │ Manifeste. json # métadonnées du plugin (obligatoire) │ - - Actifs communs/ # Actifs partagés (modèles, textures) │ - - Serveur/ # Actifs de données côté serveur - Bâtir.gradle.kts Paramètres.gradle.kts Défauts d'utilisation manifest.json Chaque plugin nécessite un manifest.json à la racine du JAR compilé. Ceci est l'équivalent d'Hytale du plugin.yml de Bukkit: { "Groupe": "com.votre nom", "Nom" : "Votre NomPlugin", "Main": "com.votrenom.votreplugin.VotrePlugin", "Version": "1.0.0", "Description": "Ce que votre plugin fait", "Auteurs": [{"Nom": "VotreNom"}], "Version serveur": "*", Dépendances: {}, "Dépendances facultatives": {}, "Prendre avant": [], "DisabledByDefault": faux, "Comprend AssetPack": faux } L'identificateur du plugin est formé comme Groupe:Nom (p. ex., com.votre nom:Votre NomPlugin). Le Main champ point à votre classe d'entrée — faux et le plugin ne se charge pas. Cycle de vie des légumes Votre classe principale s'étend JavaPlugin et comporte quatre phases de cycle de vie: Votre Extension du plugin JavaPlugin { public YourPlugin(@Nonnull JavaPluginInit init) { super(init); getLogger().info("Plugin construit!"); } @Override configuration du vide public() { // Phase 2 : enregistrement des événements, commandes, systèmes ECS // C'est là que va la plupart de votre code d'enregistrement } @Override début du vide public() { // Phase 3: Serveur est prêt pour les joueurs // Démarrer les tâches programmées, ouvrir les connexions } @Override fermeture du vide public() { // Phase 4: Nettoyage avant l'arrêt du serveur // Enregistrer les données, fermer les connexions, annuler les tâches } } PhaseMéthode Que faire ici Construction Initialisation de base, enregistrement 2. Configurationsetup() Enregistrer les événements, les commandes, les composants et les systèmes du SCE 3. Démarrerstart() Commencer les tâches, le serveur accepte les joueurs 4. Arrêtshutdown() Enregistrer les données, nettoyer les ressources Le système de double événement C'est le concept le plus important à comprendre. Hytale a deux systèmes d'événements distincts, et utiliser le mauvais est une erreur courante. Événement Bus — Global Server Events Le EventBus gère les événements à l'échelle du serveur comme les connexions de lecteur, le chat et le chargement mondial. Enregistrez les gestionnaires via le EventRegistry fourni à votre plugin: @ Dépassement configuration du vide public() { // Événement mondial synchrone getEventRegistry().registrerGlobal( PlayerReadyEvent.class, événement -> { getLogger().info("Jouer rejoint: " + event.getPlayer().getUsername()); } ); // événement Async (comme PlayerChatEvent) getEventRegistry().registrerAsyncGlobal( LecteurChatEvent.class, avenir -> { l'avenir. puisAccept(événement -> { si (event.getMessage().contient("spam") { event.setAnnulé(vrai); } }); } ); } Événement clé Événements de bus: PlayerConnectEvent / PlayerDisconnectEvent — cycle de vie de la connexion PlayerReadyEvent — le lecteur est complètement chargé et prêt PlayerChatEvent — messages de chat (async, cancellable) AddPlayerToWorldEvent — lecteur entrant dans un monde StartWorldEvent / AddWorldEvent / SupprimerWorld Événement — gestion mondiale Priorités de l'événement : Utiliser EventPriority. EARLY pour exécuter le premier et modifier les événements avant que d'autres gestionnaires les voient. Utiliser EventPriority. LATE pour voir l'état final après le traitement de tous les autres gestionnaires. ECS Événements — Actions spécifiques à l'entité Les événements de niveau d'entité comme la rupture de bloc, le placement de bloc et les dommages sont gérés par le système Component d'entité, et non par l'EventBus. Vous créez un SystèmeEntityEvent: classe publiqueBlockBreakHandler étend EntitéEventSystem { @Override enquête publique getQuery() { // Entités cibles ayant des composantes spécifiques retourner Query.builder().build(); } @Override public Class getEventType() { retour BreakBlockEvent.class; } @Override poignée publique vide (Store d'Entité, tampon de commande, Verrouillage Manifestation) { // Procéder à la rupture du bloc // Annuler dans la phase filtre, pas ici } } Règle critique: Annule uniquement les événements du SCE durant la phase filter. L'annulation dans la phase d'inspection n'a aucun effet parce que l'action s'est déjà produite. Système de composants d'entité (SCE) Hytale utilise une architecture ECS personnalisée. Comprendre cela est essentiel pour tout plugin non trivial. Concepts de base Entité — juste un ID unique, ne contient aucune donnée elle-même Component — contenant de données pures attaché à une entité Système — logique qui traite les entités avec des combinaisons de composants spécifiques Ref — poignée sûre pour une entité (ne jamais stocker de références d'entités directes) Store — gère les entités utilisant des Archetypes pour une mise en page efficace de la mémoire Composants personnalisés classe publique Score Mise en œuvre des données Composante { score int public = 0; équipe à cordes publique = "; public depuis longtemps rejoint À = System.currentTimeMillis(); @Override public ScoreCanone de données() { ScoreCopie des données = nouveau ScoreData(); copie.score = ce.score; Reçu. équipe = cette équipe; Reçu. rejoint A = ce.joint À; copie de retour; } } Les composants doivent implémenter clone(). Les joindre aux entités pour stocker des données personnalisées — scores, équipes, cooldowns, inventaires ou tout état spécifique au jeu. Comprendre le PlayerRef Un "Player" dans Hytale n'est pas une classe spéciale, c'est une entité composée de composants. PlayerRef est en fait un composant qui stocke le nom d'utilisateur, UUID, la langue et le gestionnaire de réseau du lecteur. Il reste actif tant que le lecteur est connecté. Inscription du commandant Commandes implémentent l'interface Commande: classe publique Commande implémente Commande { @Override chaîne publique getName() { retourner "spawn"; } @Override public vide execut(CommandSender sender, String[] args) { si (instance du lecteur) { // Lecteur de téléportation sender.sendMessage("Téléportation pour frayer..."); } } } // S'enregistrer en configuration() commandeRegistry.registerCommand(new SpawnCommand()); Les deux Player et CommandSender supportent apermis() vérifications. Le système de permissions intégré prend en charge les permissions au niveau de l'utilisateur, l'héritage de groupe et la correspondance de wildcard. Construire et déployer Bâtiment ./gradlew build La sortie JAR va à build/libs/. Pistes de déploiement Platforme Mod Directory Windows (local)%AppData%/Roaming/Hytale/UserData/Mods/ Serveur Linux/opt/hytale/Server/mods/ Le rechargement à domicile est partiellement pris en charge pour des modifications mineures — utiliser Ctrl+F9 dans Intelli J pour reconstruire sans redémarrage complet. Les changements majeurs nécessitent un redémarrage du serveur. Le EventRegistry nettoie automatiquement les gestionnaires lorsqu'un plugin se décharge. L'édition à la malédictionForge CurseForge reconnaît trois types de mod: Packs — packs actifs/contenus (données JSON, modèles, textures) Plugins — Fichiers JAR Java utilisant l'API du serveur Principaux plugins — plugins bootstrap pour les transformations de classe de bas niveau (avancées, utilisez avec parcimonie) Ressources communautaires La communauté de moudding a construit une vaste documentation au-delà de ce que Hypixel Studios fournit : RessourceFocus HytaleModding.dev Guides, documents, outils — 8 000 membres Discord Britakee Studios GitBookTutoriels complets testés pour Packs et Plugins HytaleDocs.comRéférence du wiki communautaire et de l'API Hytale-Toolkit (GitHub)Source décompilée, javadocs, recherche de code sémantique Patcher (GitHub) Parcourir le serveur JAR comme un projet IntelliJ Note: Le serveur JAR n'est pas occulté et peut être librement décompilé. Hypixel Studios s'est engagé à publier le code source complet du serveur dans les 1–2 mois suivant le lancement d'EA. Ce qui arrive Release du code source du serveur — attendu d'ici mars 2026 Scripts visuels — scripts basés sur des nœuds pour des non-programmeurs (similaires à des plans virtuels) Bourses de développement — Hypixel Studios prévoit offrir des primes pour les contributions communautaires Élargissement de la documentation officielle — reconnu comme incomplet, étant élargi en fonction de la rétroaction de la collectivité Prêt à déployer votre plugin? Listez votre serveur mobile sur