Hytalemodding API: Den komplette Server Plugin Development Guide

< p > Hytales plugin system giver udviklere dyb kontrol over alle aspekter af spillet. Hvis du har skrevet Bukkit eller Spigot plugins til Minecraft, overgangen er ligetil - men Hytals arkitektur er grundlæggende forskellige på måder, der betyder noget. Denne guide fører dig gennem alt fra indledende opsætning til produktionsimplementering. < / p > < h2 > Arkitektur Oversigt < / h2 > < p > Før du skriver en kode, skal du forstå, hvordan Hytales modulering virker: < / p > < ul > < li > < stærk > Klienten er en renderer. < / stærk > Hytales C # klient håndterer grafik, input og lyd - men indeholder ingen spillogik. Alle simulationer kører på Java-serveren, selv i single player. < / li > Alt er serverside. Når spillere tilmelder sig en moduleret server, brugerdefinerede aktiver og adfærd stream automatisk. Ingen klient mods nødvendige. < / li > < li > < stærk > Der findes fire moduleringskategorier: < / stærk > Data Assets (JSON), Art Assets (Blockbench modeller), Server Plugins (Java), og Visual Scripting (kommer snart). < / li > < / ul > < p > Server plugins er den mest kraftfulde kategori - de giver dig fuld Java adgang til serveren runtime, herunder Entity Component System, event pipeline, kommando ramme, og verden manipulation. < / p > < h2 > Opsætning af udviklingsmiljø < / h2 > < h3 > Forudsætninger < / h3 > < tabel > < tead > < st > < th > Værktøj < / th > < th > Version < / th > < th > Noter < / th > < / st > < / thead > < tbody > < tr > < td > < stærk > Java < / stærk > < / td > < td > 25 + < / td > < td > Hytale bruger moderne funktioner, herunder virtuelle tråde (Projekt Loom) < / td > < / tr > < tr > < td > < stærk > Intelligent IDEA < / stærk > < / td > < td > Fællesskabet eller Ultimate < / td > < td > Anbefalet IDE - gratis fællesskabsudgave fungerer fint < / td > < / tr > < tr > < td > < stærk > Gradle < / strong > < / td > < td > 9.2.0 + < / td > < td > Bygningssystem (inkluderet i plugin skabelonen) < / td > < / tr > < st > < td > < stærk > Git < / stærk > < / td > < td > Enhver nyere version < / td > < td > For kloning den officielle skabelon < / td > < / tr > < / tbody > < / tabel > < h3 > Klon den officielle skabelon < / h3 > < p > Hypixel Studios giver en officiel plugin skabelon på GitHub: < / p > < pre > < kode > git klon http: / / github.com / HytaleModding / plugin- template.git MyFirstPlugin cd MyFirstPlugin < / kode > < / pre > < p > Åbn projektet i IntelligJ IDEA og lad Gradle synkronisere. skabelonen indeholder den korrekte mappestruktur, bygge konfiguration og server API afhængigheder. < / p > < p > Alternativt < stærk > Hytalio Project Generator < / strong > på hytaleio.com / project- generator kan oprette Plugin, mod, eller Full (combo) projekt stilladser med en web UI. < / p > < h2 > Plugin struktur < / h2 > < p > Hvert Hytal- plugin følger denne mappelayout: < / p > < pre > < kode > your- plugin / Name Det er YourPlugin. java # Hovedindgang / hovedressourcer / Det er et manifest. json # Plugin metadata (påkrævet) Fælles aktiver (modeller, teksturer) Name Oversat af: Destinations.gradle.kts > < / pre > < h3 > manifest.json < / h3 > < p > Hvert plugin kræver en < kode > manifest.json < / kode > ved roden af den kompilerede JAR. Dette er Hytales svarer til Bukkits < kode > plugin.yml < / kode >: < / p > < pre > < kode > [ "Gruppe": "com.yourname" "Navn": "YourPluginName" "Main": "com.yournavn.yourplugin.YourPlugin" "Version": "1.0.0" "Beskrivelse": "Hvad dit plugin gør," "Forfattere": [{"Navn": "YourName"}] "ServerVersion": "*" "Afhængighed": {}, "OptionalIndependencies": {} "LoadPre": [] "DisabledByStandard": falsk "IncludeAssetPack": falsk } < / kode > < / pre > < p > Plugin- id er dannet som < kode > Gruppe: Navn < / kode > (f.eks. < kode > com.yourname: YourPluginName < / kode >). < kode > Main < / kode > felt point til din entry class - få dette forkert og plugin vil ikke indlæse. < / p > < h2 > Plugin livscyklus < / h2 > < p > Din hovedklasse udvider < kode > JavaPlugin < / kode > og har fire livscyklusfaser: < / p > < pre > < kode > offentlig klasse Plugin udvider JavaPluginComment [ public YourPlugin (@ Nonnull JavaPlugininit) { super (init); getLogger () .info ("Plugin konstrueret!"); } @ Override public void setup () [ / / Fase 2: Registrer begivenheder, kommandoer, ECS-systemer / / Dette er, hvor de fleste af din registreringskode går } @ Override offentlig tomgangsstart () [ / / Fase 3: Serveren er klar til spillere / / Start planlagte opgaver, åbne forbindelser } @ Override offentligt tomrum nedlukning () [ / / Fase 4: Oprydning før server stopper / / Gem data, tætte forbindelser, annullér opgaver } } < / kode > < / pre > < tabel > < tead > < st > < th > Fase < / th > < th > Metode < / th > < th > Hvad skal man gøre her < / th > < / st > < / thead > < tbody > < tr > < td > 1. Konstruktion < / td > < td > Konstruktor < / td > < td > Grundlæggende initialisering, logning < / td > < / tr > < st > < td > 2. Opsætning < / td > < td > < kode > opsætning () < / kode > < / td > < td > Registrer begivenheder, kommandoer, ECS-komponenter og systemer < / td > < / tr > < st > < td > 3. Start < / td > < td > < kode > start () < / kode > < / td > < td > Start opgaver, serveren accepterer spillere < / td > < / tr > < st > < td > 4. Nedlukning < / td > < td > < kode > nedlukning () < / kode > < / td > < td > Gem data, oprydning af ressourcer < / td > < / tr > < / tbody > < / tabel > < h2 > Dual Event System < / h2 > < p > Dette er det vigtigste begreb at forstå. Hytale har < stærk > to separate event systemer < / stærk >, og ved hjælp af den forkerte er en almindelig fejl. < / p > < h3 > Begivenhed Bus - globale serverbegivenheder < / h3 > < p > The < code > EventBus < / code > håndterer serverwide begivenheder som spillerforbindelser, chat og verdens lastning. Registrer brugere gennem < koden > EventRegistry < / kode > leveret til dit plugin: < / p > < pre > < kode > @ Tilsidesæt public void setup () [ / / Synkron global begivenhed getEventRegistry () .registerGlobal ( PlayerReadyEvent.class event - > { getLogger () .info ("Player join:" + event.getPlayer () .getUsername ()); } ); / / Async begivenhed (ligesom PlayerChatEvent) getEventRegistry () .registerAsyncGlobal ( PlayerChatEvent.class Fremtid - > { Fremtid. thenAccept (begivenhed - > { hvis (vent.getMessage () .indeholder ("spam") [ event.setCancelled (true) } }); } ); } < / kode > < / pre > < p > < stærk > Nøglebegivenhed Busbegivenheder: < / strong > < / p > < ul > < li > < kode > PlayerConnectEvent < / kode > / < kode > PlayerDisconnectEvent < / kode > - tilslutningslivscyklus < / li > < li > < kode > PlayerReadyEvent < / kode > - spilleren er fuldt indlæst og klar < / li > < li > < kode > PlayerChatEvent < / code > - chatbeskeder (async, annullerbar) < / li > < li > < kode > AddPlayerToWorldEvent < / kode > - spiller ind i en verden < / li > < li > < kode > StartWorldEvent < / kode > / < kode > AddWorldEvent < / kode > / < kode > RemoveWorld Begivenhed < / kode > - global styring < / li > < / ul > < p > < stærk > Begivenhedsprioriteter: < / stærk > Brug < kode > EventPriority. EARLY < / code > til at køre først og ændre begivenheder før andre brugere se dem. Brug < kode > EventPriority. LAT < / kode > for at se den endelige tilstand efter alle andre håndterende virksomheder har behandlet. < / p > < h3 > ECS Begivenheder - Hele specifikke aktioner < / h3 > < p > Begivenheder på hele niveau som blokeringer, blokeringer og skader håndteres gennem < stærk > Entity Component System < / stærk >, ikke EventBus. Du opretter en < kode > EnhedEventSystem < / kode >: < / p > < pre > < kode > offentlig klasse BlockBreakHandler extended EntityEventSystem & lt; EntityStore, BreakBlock Begivenhed & gt; { @ Override offentlig forespørgsel getQuery () [ / / Målenheder med specifikke komponenter return Query.builder () .build (); } @ Override public Class & lt; BreakBlockEvent & gt; getEventType () [ tilbagevenden BreakBlockEvent.class } @ Override offentligt tomrum håndtag (EntityButik butik, CommandBuffer buffer BreakBlock Begivenhed) { / / Behandle blokken pause / / Annullér i filterfasen, ikke her } } < / kode > < / pre > < p > < stærk > Kritisk regel: < / stærk > Afbryd kun ECS-hændelser under < stærk > filter < / stærk > fase. Annullering i inspektionsfasen har ingen virkning, fordi handlingen allerede er sket. < / p > < h2 > Enhedskomponentsystem (ECS) < / h2 > < p > Hytale bruger en brugerdefineret ECS arkitektur. Forståelse af dette er afgørende for enhver ikke-trivielle plugin. < / p > < h3 > Kernebegreber < / h3 > < ul > < li > < stærk > Enhed < / stærk > - kun et unikt ID, indeholder ingen data i sig selv < / li > < li > < stærk > Komponent < / stærk > - ren databeholder knyttet til en enhed < / li > < li > < stærk > System < / stærk > - logik, der behandler enheder med specifikke komponentkombinationer < / li > < li > < stærk > Ref < / stærk > - sikkert håndtag til en virksomhed (aldrig gemme direkte virksomhedens referencer) < / li > < li > < stærk > Store < / stærk > - administrerer enheder, der bruger Archetypes til effektiv hukommelse layout < / li > < / ul > < h3 > Brugerdefinerede komponenter < / h3 > < pre > < kode > public class Score Dataimplementeringer Komponent & lt; EntityStore & gt; { public int score = 0 public String team = ""; offentlig lang sluttet på = System.curtTimeMillis (); @ Override offentlig ScoreData klon () [ Score Data copy = new Score Data (); copy.score = this.score; Modtaget. hold = denne .team; Modtaget. forenet På = dette. på; Retureksemplar } } < / kode > < / pre > < p > Komponenter skal implementere < kode > klon () < / kode >. Vedhæft dem til enheder til at gemme brugerdefinerede data - scorer, hold, nedkølinger, lagerbeholdninger, eller enhver game- specifik tilstand. < / p > < h3 > Forståelse PlayerRef < / h3 > < p > A "Spiller" i Hytale er ikke en speciel klasse - det er en enhed sammensat af komponenter. < kode > PlayerRef < / code > er faktisk en komponent, der gemmer spillerens brugernavn, UUID, sprog og netværksadministrator. Det forbliver aktivt, så længe spilleren er tilsluttet. < / p > < h2 > Kommandoregistrering < / h2 > < p > Kommandoer implementere < kode > Kommando < / kode > interface: < / p > < pre > < kode > offentlig klasse Spawn Kommando implementerer kommando { @ Override public String getName () {tilbagelevering "yngel";} @ Override public void execution (CommandSender sender, String [] Args) { hvis (afsender instance of Player player) { / / Teleportér spiller til yngel sender.sendMessage ("Teleportering til yngel"...) } } } / / Registrer dig i opsætning () KommandoregisterCommand (ny SpawnCommand ()); < / kode > < / pre > < p > Både < kode > Player < / kode > og < kode > CommandSender < / kode > support < kode > hasTilmission () < / kode > kontrol. Build- in tilladelser system understøtter bruger- niveau tilladelser, gruppe arv og wildcard matching. < / p > < h2 > Bygning og implementering < / h2 > < h3 > Bygning < / h3 > < pre > < kode >. / gradelew build < / code > < / pre > < p > Output JAR går til < kode > build / libs / < / code >. < / p > < h3 > Implementeringsveje < / h3 > < tabel > < tead > < st > < th > Platform < / th > < th > Mod Directory < / th > < / tr > < / thead > < tbody > < tr > < td > Windows (lokal) < / td > < td > < kode >% AppData% / Roaming / Hytale / BrugerData / Mods / < / code > < / td > < / tr > < tr > < td > Linux-server < / td > < td > < kode > / opt / hytale / server / mods / < / code > < / td > < / tr > < / tbody > < / tabel > < p > Varm genindlæsning understøttes delvist for mindre ændringer - brug < kode > Ctrl + F9 < / kode > i Intelli J at genopbygge uden en fuld genstart. Større ændringer kræver en server genstart. The < code > EventRegistry < / code > renser automatisk op, når et plugin loader. < / p > < h3 > Udgivelse til CurseForge < / h3 > < p > CurseForge genkender tre mod typer: < / p > < ul > < li > < stærk > Pakninger < / stærk > - aktiv / indholdspakker (JSON data, modeller, teksturer) < / li > < li > < stærk > Plugins < / stærk > - Java JAR filer ved hjælp af serveren API < / li > < li > < stærk > Tidlige plugins < / stærk > - bootstrap plugins til lav klasse transformationer (avanceret, brug sparsomt) < / li > < / ul > EU-midler < / h2 > < p > Moding fællesskabet har bygget omfattende dokumentation ud over hvad Hypixel Studios giver: < / p > < tabel > < tead > < st > < th > Resource < / th > < th > Fokus < / th > < / st > < / thead > < tbody > < tr > < td > < stærk > HytaleModing.dev < / strong > < / td > < td > Guider, dokumenter, værktøjer - 8.000 + Discord medlemmer < / td > < / tr > < tr > < td > < stærk > Brittakee Studios GitBook < / strong > < / td > < td > Omfattende testede tutorials til pakker og plugins < / td > < / tr > < tr > < td > < stærk > HytaleDocs.com < / strong > < / td > < td > Community wiki og API reference < / td > < / tr > < tr > < td > < stærk > Hytale- Toolkit (GitHub) < / stærk > < / td > < td > Dekomponeret kilde, javadocs, semantisk kodesøgning < / td > < / tr > < st > < td > < stærk > Patcher (GitHub) < / stærk > < / td > < td > Gennemse serveren JAR som et IntelligJ projekt < / td > < / tr > < / tbody > < / tabel > < p > < stærk > Bemærk: < / stærk > Serveren JAR er ikke forbygget og kan frit nedbrydes. Hypixel Studios har forpligtet sig til at frigive den fulde server kildekode inden for 1-2 måneder efter EA lanceringen. < / p > < h2 > Hvad kommer < / h2 > < ul > < li > < stærk > Server kildekode udgivelse < / stærk > - forventet i marts 2026 < / li > < li > < stærk > Visual Scripting < / strong > - nodebaseret scripting for ikke-programmører (svarende til Uvirkelige Blueprints) < / li > < li > < stærk > Udviklingsbonusser < / stærk > - Hypixel Studios planlægger at tilbyde bonusser for fællesskabsbidrag < / li > < li > < stærk > Officiel dokumentationsekstension < / stærk > - anerkendt som ufuldstændig, bliver udvidet baseret på feedback fra samfundet < / li > < / ul > < p > Klar til at implementere dit plugin? List din modulerede server på < a Horif = "/" > HytaleCharts < / a >, så spillerne kan finde din skabelse. For minigame-specifikke udviklingsmønstre, tjek vores < a Horif = "/ news / hytale-custom-minigame-server- development-guide" > Brugerdefineret Minigames Guide < / a >. < / p >