Hytale Modding API: De Complete Server Plugin Ontwikkelingsgids

Hytale's server plugin systeem geeft ontwikkelaars diepe controle over elk aspect van het spel. Als je hebt geschreven Bukkit of Spigot plugins voor Minecraft, de transitie is rechttoe rechtaan Deze gids begeleidt je door alles van de eerste installatie tot productie-implementatie. Architectuur Overzicht Begrijp voordat je een code schrijft hoe Hytale's modding werkt: De client is een renderer. Hytale's C#-client verwerkt graphics, input en audio, maar bevat geen spellogica. Alle simulatie draait op de Java-server, zelfs in singleplayer. Alles is aan de serverzijde. Wanneer spelers zich aansluiten bij een modded server, aangepaste activa en gedrag stream automatisch. Geen client-mods nodig. Vier modding categorieën bestaan: Data Assets (JSON), Art Assets (Blockbench modellen), Server Plugins (Java) en Visual Scripting (binnenkort). Serverplug-ins zijn de meest krachtige categorie die ze je volledige Java toegang geven tot de server runtime, inclusief het Entity Component System, event pipeline, command framework en wereldmanipulatie. Ontwikkelingsomgeving instellen Voorwaarden GereedschapVersieAantekeningen Java25+ Hytale maakt gebruik van moderne functies, waaronder virtuele threads (Project Loom) IntelliJ IDEACommunity or UltimateAanbevolen IDE gratis Community Edition werkt prima Gradle 9.2.0+Build system (included in the plugin sjabloon) Git Elke recente versie Voor het klonen van het officiële sjabloon Verwijder het officiële sjabloon Hypixel Studios biedt een officieel plugin-sjabloon op GitHub: git kloon https://github.com/HytaleModding/plugin-template.git Mijn eerste plugin cd MyFirstPlugin Open het project in Intellij IDEA en laat Gradle synchroniseren. Het sjabloon bevat de juiste mapstructuur, opbouwconfiguratie en server API afhankelijkheden. Alternatief, de HytaleIO Project Generator bij hytaleio.com/project-generator kan Plugin, Mod of Full (combo) project steigers maken met een web UI. Pluginstructuur Elke Hytale-plugin volgt deze mapindeling: uw-plugin/ Src/main/java/com/yourname/yourplugin/ │ Uw plugin. java # Hoofd ingang punt ├── src/main/resources/ │ manifest. json # Plugin metadata (nodig) │ ├── Gemeenschappelijke/ # gedeelde activa (modellen, texturen) │ ├── build.gradle.kts ├── instellingen.gradle.kts manifest.json Elke plugin vereist een manifest.json aan de root van de gecompileerde JAR. Dit is Hytale's equivalent van Bukkit's plugin.yml: { "Groep": "com.yourname," "Naam": "Uw pluginnaam," "Main": "com.yourname.yourplugin.Yourplugin," "Versie": "1.0.0," "Beschrijving": "Wat uw plugin doet," "Authors": [{"Naam": "Uw naam"}], "ServerVersion": "*," "Dependencies": {}, "OptionalDependencies": {}, "LoadBefore": [], "DisabledByDefault": vals, "IncludesAssetPack": onwaar } De plugin-identificatie wordt gevormd als Groep:Naam (bv. com.yourname:YourPluginName). De Main veld wijst naar uw entry class plugin-levenscyclus Je hoofdklasse breidt Javaplugin uit en heeft vier levenscyclusfasen: publieke klasse Uw Plugin breidt zich uit Javaplugin { public YourPlugin(@Nonnull JavaPluginInit init) { super(init); getLogger().info("Plugin constructed!"); } @Override publieke leegte setup() { / / Fase 2: Registreer gebeurtenissen, commando's, ECS-systemen / / Dit is waar de meeste van uw registratie code gaat } @Override publieke leegte start() { / / Fase 3: Server is klaar voor spelers / / Geplande taken starten, verbindingen openen } @Override publiek ongeldige sluiting() { / / Fase 4: Opruimen voordat de server stopt / / Gegevens opslaan, verbindingen sluiten, taken annuleren } } faseMethode Wat moet u hier doen 1. Constructie Constructor Basisinitialisatie, loggen 2. Setupsetup() Registreer gebeurtenissen, commando's, ECS-componenten en -systemen 3. Startstart() Start taken, de server accepteert spelers 4.Shutdownshutdown() Gegevens opslaan, bronnen opruimen Het Dual Event System Dit is het belangrijkste concept om te begrijpen. Hytale heeft twee afzonderlijke gebeurtenissystemen , en het gebruik van de verkeerde is een veel voorkomende fout. Evenement Bus: Global Server Events De EventBus behandelt serverwijde gebeurtenissen zoals spelerverbindingen, chat en wereldladen. Registreer handlers via de EventRegistry die aan uw plugin is gegeven: @ Overschrijven publieke leegte setup() { // Synchroon globaal evenement getEventRegistry().registerGlobal( SpelerReadyEvent.class, gebeurtenis -> { getLogger().info("Player aangesloten: " + event.getPlayer().getUsername()); } ); // Async-evenement (zoals PlayerChatEvent) getEventRegistry().registerAsyncGlobal( SpelerChatEvent.class, toekomst -> { toekomst. danAccept(event -> { als (event.getMessage().bevat("spam")) { event.setGeannuleerd(true); } }); } ); } Kenmerken Busgebeurtenissen: PlayerConnectEvent / PlayerDisconnectEvent Levensduur van de verbinding PlayerReadyEvent Player volledig geladen en klaar PlayerChatEvent AddPlayerToWorldEvent StartWorldEvent / ToevoegenWorldEvent / VerwijderWorld Gebeurtenis Wereldbeheer Gebeurtenisprioriteiten: Gebruik EvenementPrioriteit. EARLY eerst uitvoeren en gebeurtenissen aanpassen voordat andere begeleiders ze zien. Gebruik EvenementPrioriteit. LATE om de eindtoestand te zien nadat alle andere verwerkers zijn verwerkt. ECS Gebeurtenissen en specifieke acties van de entiteit Entity-niveau gebeurtenissen zoals blokbreuk, blok plaatsen en schade worden behandeld via het Entity Component System, niet de EventBus. U maakt een aan EntiteitEventSystem: public class BlockBreakHandler breidt EntityEventSysteem { @Override public Query getQuery() { // Doelentiteiten met specifieke componenten return Query.builder().build(); } @Override public Class getEventType() { terugkeer BreakBlockEvent.class; } @Override public void handle(EntityStore store, Commandobufferbuffer, BreakBlock Evenement) { / / De blokbreuk verwerken / / Annuleren in de filterfase, niet hier } } Kritieke regel: Alleen ECS-gebeurtenissen tijdens de filter fase annuleren. Annulering in de inspectiefase heeft geen effect omdat de actie reeds heeft plaatsgevonden. Entity Component System (ECS) Hytale maakt gebruik van een aangepaste ECS architectuur. Dit begrijpen is essentieel voor elke niet-triviale plugin. Core Concepts Entity Component Systeem Logica die entiteiten verwerkt met specifieke componentencombinaties Ref Store Aangepaste componenten publieke klasse Score Uitvoeren van gegevens Component { publieke int score = 0; publiek tekenreeksteam = ""; publiek lang verbonden At = System.currentTimeMillis(); @Override publieke ScoreData kloon() { ScoreData copy = nieuwe ScoreData(); copy.score = this.score; Begrepen. team = this.team; Begrepen. verbonden Bij = dit. at; exemplaar van terugkeer; } } Componenten moeten clone() implementeren. Voeg ze toe aan entiteiten om aangepaste gegevens op te slaan scores, teams, afkoelingen, inventarissen of een game-specifieke status. Begrijpende spelerRef Een "Player" in Hytale is geen speciale klasse, het is een entiteit die bestaat uit componenten. PlayerRef is eigenlijk een component die de gebruikersnaam, UUID, taal en netwerkafhandeling van de speler opslaat. Het blijft actief zolang de speler verbonden is. Command Registratie Commands implementeren de Command interface: publieke klasse Spawn Commando implementeert Commando { @Override public String getName() { return "spion"; } @Override publieke leegte uitvoeren(CommandSender afzender, String[] args) { if (stuur instantie van speler) { / / Teleporteer speler om te paaien sender.sendMessage("Teleporting to paain ..."); } } } // Register in setup() commandoRegistry.registerCommand(new SpawnCommand()); Beide Player en CommandSender ondersteuning heefttoestemming() controles. Het ingebouwde permissiesysteem ondersteunt gebruikersrechten, groepsovererving en wildcardmatching. Bouw en zet in Gebouw ./gradlew build De uitvoer JAR gaat naar build/libs/. Implementatiepaden Platform Mod Directory Windows (local)%AppData%/Roaming/Hytale/UserData/Mods/ Linux-server/opt/hytale/Server/mods/ Hot herladen wordt gedeeltelijk ondersteund voor kleine wijzigingen J te herbouwen zonder een volledige herstart. Belangrijke wijzigingen vereisen een server herstart. De EventRegistry reinigt automatisch de handlers wanneer een plugin wordt verwijderd. Publiceren naar CurseForge CurseForge herkent drie mod types: Packs Plugins Early Plugins communautaire middelen De modding community heeft uitgebreide documentatie opgebouwd die verder gaat dan wat Hypixel Studios biedt: ResourceFocus HytaleModding.dev Hulplijnen, docs, tools 8.000+ Discord-leden Britakee Studios GitBookGeheel geteste tutorials voor Packs en Plugins HytaleDocs.comCommunity wiki en API-referentie Hytale-Toolkit (GitHub)Gecompileerde bron, javadocs, semantische codezoekopdracht Patcher (GitHub) Blader door de server JAR als een IntelliJ project Opmerking: De server JAR is niet verduisterd en kan vrij gedecompileerd worden. Hypixel Studios heeft toegezegd de volledige broncode van de server vrij te geven binnen 1 Wat komt eraan Serverbroncode vrijgeven Verwacht tegen maart 2026 Visual Scripting Ontwikkelingspremies Officiële documentatieuitbreiding Klaar om je plugin in te zetten? Geef je modded-server een overzicht van HytaleCharts zodat spelers je creatie kunnen vinden. Bekijk voor minigamespecifieke ontwikkelingspatronen onze