Hytale Modding API: The Complete Server Plugin Development Guide

Hytales serverpluginsystem ger utvecklarna djup kontroll över alla aspekter av spelet. Om du har skrivit Bukkit eller Spigot plugins för Minecraft är övergången enkel - men Hytales arkitektur är fundamentalt annorlunda på sätt som betyder något. Denna guide går igenom allt från första installationen till produktionsutplacering. Arkitektur Översikt Innan du skriver någon kod, förstå hur Hytales modding fungerar: Kunden är en renderer. Hytales C#-klient hanterar grafik, inmatning och ljud - men innehåller ingen spellogik. All simulering körs på Java-servern, även i singleplayer. Allt är server-side. När spelare går med i en moddad server, anpassade tillgångar och beteendeströmmar automatiskt. Inga klientmods behövs. Fyra moddingkategorier finns: Datatillgångar (JSON), Art Assets (Blockbench-modeller), Server Plugins (Java) och Visual Scripting (kommer snart). Server plugins är den mest kraftfulla kategorin - de ger dig full Java tillgång till serverns runtime, inklusive Entity Component System, händelsepipeline, kommandoram och världsmanipulation. Development Environment Setup Förutsättningar ToolVersionNotes Java25+ Hytale använder moderna funktioner, inklusive virtuella trådar (Project Loom) IntelliJ IDEACommunity or UltimateRekommenderas IDE – gratis Community Edition fungerar bra Gradle9.2.0+Build system (ingår i plugin mallen) Git Ny version För att klona den officiella mallen Klon den officiella mallen Hypixel Studios ger en officiell pluginmall på GitHub: git clone https://github.com/HytaleModding/plugin-template.git MyFirstPlugin cd MyFirstPlugin Öppna projektet i IntelliJ IDEA och låt Gradle synkronisera. Mallen innehåller rätt katalogstruktur, bygg konfiguration och server API-beroende. Alternativt, HytaleIO Project Generator på hytaleio.com/project-generator kan skapa Plugin, Mod eller Full (combo) projektställning med ett webb-UI. Pluginstruktur Varje Hytale plugin följer denna katalog layout: your-plugin/ src/main/java/com/yourname/yourplugin/ Din plugin. Java # Main Entry Point src/main/resources/ 😂 json # Plugin metadata (krävs) Common/ # Delade tillgångar (modeller, texturer) ★ Server / # Server-side datatillgångar bygga.gradle.kts Inställningar.gradle.kts ẓle.properties manifest.json Varje plugin kräver en manifest.json vid roten till den sammanställda JAR. Detta är Hytales motsvarighet till Bukkits plugin.yml: { "Group": "com.yourname" "Namn": "YourPluginName" "Main": "com.yourname.yourplugin.YourPlugin" "Version": "1.0.0", "Beskrivning": "Vad ditt plugin gör", Författarna: [Namn]: "YourName" "ServerVersion": "*", "Beroende": , "OptionalDependencies": , "LoadBefore": [] "DisabledByDefault": falsk, IncludesAssetPack: falsk ≤/code> Plugin-identifieraren bildas som Group:Name (t.ex. com.yourname:YourPluginName). Huvud fält pekar på din inträdesklass - få detta fel och pluginet kommer inte att laddas. Plugin Lifecycle Din huvudklass sträcker sig JavaPlugin och har fyra livscykelfaser: public class Your Plugin sträcker sig JavaPlugin { Public YourPlugin(@Nonnull JavaPluginInit init) super(init); getLogger () info ("Plugin konstruerad!") } @Override offentligt tomrum setup() { //// Fas 2: Registrera händelser, kommandon, ECS-system //// Det är där de flesta av din registreringskod går } @Override offentlig tomrumstart() { //// Fas 3: Server är redo för spelare //// Starta schemalagda uppgifter, öppna anslutningar } @Override offentlig tomrumstängning() { //// Fas 4: Rengöring innan servern slutar //// Spara data, nära anslutningar, avbryta uppgifter } ≤/code> Phase>Method Vad gör du här 1. ConstructionConstructor Grundläggande initialisering, loggning 2. Setupsetup() Registrera händelser, kommandon, ECS-komponenter och system 3. Startstart() Starta uppgifter, servern accepterar spelare 4. Shutdownshutdown() Spara data, rengöringsresurser Dual Event System Detta är det viktigaste konceptet att förstå. Hytale har två separata händelsesystem, och att använda fel är ett vanligt misstag. Event Bus – Global Server Events The EventBus hanterar serveromfattande händelser som spelaranslutningar, chatt och världsbelastning. Registrera hanterare genom EventRegistry som ges till ditt plugin: @ Override offentligt tomrum setup() { Synkron global händelse GetEventRegistry().registerGlobal() PlayerReadyEvent.class, Event -> { getLogger().info("Player gick med:" + event.getPlayer().getUsername(); } ); Async händelse (som PlayerChatEvent) fåEventRegistry().registerAsyncGlobal() PlayerChatEvent.class, Framtid -> Framtiden. Sedan Accept(event) Om (event.getMessage().innehåller ("spam") { Event.setCancelled (sann); } }); } ); ≤/code> Key Event Busshändelser: PlayerConnectEvent/PlayerDisconnectEvent Anslutningslivscykeln PlayerReadyEvent spelaren fullt laddad och redo PlayerChatEvent -- chattmeddelanden (async, cancellable) AddPlayerToWorldEvent – spelare som går in i en värld StartWorldEvent/AddWorldEvent/RemoveWorld Event - världsledning Eventprioriteringar: Använd EventPriority. Tidigt för att köra först och ändra händelser innan andra hanterare ser dem. Använd EventPriority. LATE för att se det slutliga tillståndet efter att alla andra hanterare har behandlats. ECS Händelser – Entitetsspecifika åtgärder Entity-nivå händelser som blockbrytning, blockplacering och skador hanteras genom Entity Component System, inte EventBus. Du skapar en EntityEventSystem: public class BlockBreakHandler utökar EntityEventSystem Kritisk regel: Annullera endast ECS-händelser under filter-fasen. Avbokning i inspektfasen har ingen effekt eftersom åtgärden redan inträffade. Entity Component System (ECS) Hytale använder en anpassad ECS-arkitektur. Att förstå detta är viktigt för alla icke-triviala plugin. Core Concepts Entity - bara ett unikt ID, innehåller inga data själv Component - ren databehållare kopplad till en enhet System logik som bearbetar enheter med specifika komponentkombinationer Ref -- säker handtag till ett företag (förvara aldrig direktentitetsreferenser) Store - hanterar enheter som använder arketyper för effektiv minneslayout Custom Components Public class Score Data implementerar Komponent & lt; EntityStore & gt; offentlig int score = 0; Public String team = ""; Offentligt länge gått vid = System.currentTimeMillis(); @Override offentlig ScoreData klon() { ScoreData copy = new ScoreData(); copy.score = this.score; kopiera. team = this.team; kopiera. Förenade Vid = this.joined vid; returnera kopia; } ≤/code> Komponenter måste genomföra klon(). Bifoga dem till enheter för att lagra anpassade data - poäng, lag, nedkylningar, inventeringar eller något spelspecifikt tillstånd. Understanding PlayerRef En "Player" i Hytale är inte en speciell klass - det är en enhet bestående av komponenter. PlayerRef är faktiskt en komponent som lagrar spelarens användarnamn, UUID, språk och nätverkshanterare. Den förblir aktiv så länge spelaren är ansluten. Kommandoregistrering Kommandon implementerar Kommando gränssnitt: Public class Spawn Command implementerar Command @Override Public String getName() { returnera "spawn"; } @Override offentligt tomrum utför (CommandSender-sändare, String [] argument) Om (sender instans av spelare) //// Teleportspelare till spawn Sändare.sendMessage ("Teleporting to spawn..."); } } } // Registrera dig i setup() kommandotRegistry.registerCommand (new SpawnCommand(); Både Player och CommandSender support hasPermission() checkar. Det inbyggda behörighetssystemet stöder användarnivåbehörigheter, grupparv och wildcard-matchning. Build and Deploy Building ./gradlew build Utgången JAR går till build/libs/. Deployment Paths Plattform Mod Directory Windows (local)%AppData%/Roaming/Hytale/UserData/Mods/ Linux-server/opt/hytale/Server/mods/ Hot reloading stöds delvis för mindre förändringar - använd Ctrl+F9 i Intelli J för att bygga om utan full omstart. Stora förändringar kräver en server omstart. EventRegistry rensar automatiskt handtagen när ett plugin lossar. Publishing to CurseForge CurseForge erkänner tre modtyper: Packs — tillgång/innehållspaket (JSON-data, modeller, texturer) Plugins — Java JAR-filer som använder servern API Early Plugins -- bootstrap plugins för klassomvandlingar på låg nivå (avancerade, använd sparsamt) Kommunitetsresurser Den modding gemenskapen har byggt omfattande dokumentation utöver vad Hypixel Studios ger: ResourceFocus HytaleModding.dev Guider, docs, verktyg - 8 000+ Discord-medlemmar Britakee Studios GitBookComprehensive testade tutorials för Packs and Plugins HytaleDocs.comCommunity wiki och API referens Hytale-Toolkit (GitHub)Decompiled source, javadocs, semantisk kodsökning Patcher (GitHub) Bläddra på servern JAR som ett IntelliJ-projekt Note: Servern JAR är inte förvirrad och kan fritt dekompileras. Hypixel Studios har åtagit sig att släppa hela serverkällkoden inom 1-2 månader efter EA-lanseringen. Vad kommer Server source code release Förväntad i mars 2026 Visual Scripting — nodbaserad scripting för icke-programmerare (liknande Unreal Blueprints) Development bounties - Hypixel Studios planerar att erbjuda bounties för samhällsbidrag Officiell dokumentationsexpansion - erkänd som ofullständig, utvidgas baserat på gemenskapsfeedback Ready to deploy your plugin? Lista din modded server på HytaleCharts så att spelare kan hitta din skapelse. För minigamespecifika utvecklingsmönster, kolla in vår Anpassad Minigames Guide.