Hytale Modding API: Den komplette guiden for utvikling av servertillegg

Hytales serverplugin-system gir utviklere dyp kontroll over alle aspekter av spillet. Hvis du har skrevet Bukkit- eller Spigot-plugins for Minecraft, er overgangen enkel - men Hytales arkitektur er fundamentalt annerledes på måter som betyr noe. Denne guiden går gjennom alt fra første installasjon til produksjon. Arkitektur Oversikt Før du skriver en kode, forstår du hvordan Hytales modning fungerer: Kunden er en render. Hytales C#-klient håndterer grafikk, inngang og lyd — men inneholder ingen spilllogikk. All simulering kjører på Java-serveren, selv i enkeltspiller. Alt er serverside. Når spillere blir med i en modifisert server, tilpassede eiendeler og oppførselsstrøm automatisk. Ingen klientmodninger trengs. Fire modningskategorier eksisterer: Datasett (JSON), Art Assets (Blockbench-modeller), Serverplugins (Java) og Visual Scripting (kommer snart). Server-plugins er den mest kraftige kategorien — de gir deg full Java-tilgang til serverens kjøringstid, inkludert Entity Component System, hendelsesrørledning, kommandorammeverk og verdensmanipulasjon. Utviklingsmiljøoppsett Forespørsler VerktøyVersjonNoter Java25+ Hytale bruker moderne funksjoner, inkludert virtuelle tråder (prosjektloom) IntelliJ IDEACommunity eller Ultimate Anbefales IDE — gratis Community Edition fungerer fint Gradle9.2.0+Byggsystem (inkludert i plugin-malen) git En ny versjon For kloning av den offisielle malen Klone den offisielle malen Hypixel Studios gir en offisiell plugin-mal på GitHub: git klon https://github.com/HyttaleModding/plugin-template.git MyFirstPlugin cd MyFirstPlugin Åpne prosjektet i IntelliJ IDEA og la Gradle synkronisere. Malen inneholder riktig katalogstruktur, bygge konfigurasjon og server-API-avhengigheter. Alternativt, HyttaleIO Prosjektgenerator på hytaleio.com/project-generator kan opprette Plugin, Mod eller Full (combo) prosjekt stillaser med en web-UI. Plugin-struktur Alle Hytale-tillegg følger denne mappelayouten: din-plugin/ Src/main/java/com/ditt navn/plugin/ │ └ Java # Hovedinngangspunkt Src/main/ressources/ │ ├ json # Plugin metadata (krevet) Felles / # Delte eiendeler (modeller, teksturer) │ └└─ Server Server/ # Server-side dataressurser Bygg.gradle.kts innstillinger.gradle.kts Kundeområde manifest.json Hver plugin krever en manifest.json ved roten av den kompilerte JAR. Dette er Hytales ekvivalent med Bukkits plugin.yml: { "Gruppe": "comcom.yourname", " Navn": "PluginName", "Main": "comcom.yourname.yourplugin.YourPlugin", "Versjon": "1.0.0", Beskrivelse":What Hva plugin gjør", " Forfattere - [{"navn], "Serverion": "**", "Nødvändighet": {}, "Valgfridepensjon": {} "Last før": [], DeaktivertStandard - falsk, " Inkluderer AssetPack": falsk } Plugin-identifikatoren dannes som Gruppe: Navn (f.eks. com.yourname:YourPluginName). Main felt peker på oppføringsklassen din - få dette feil og plugin vil ikke laste. Plugin livssyklus Hovedklassen din strekker seg JavaPlugin og har fire livssyklusfaser: Offentlig klasse Din Tilleggsmodulen utvider JavaPlugin { offentlig YourPlugin(@Nonnull JavaPluginInit init) { super(init); getLogger().info("Plugin konstruert!"); } @ Override Offentlig ugyldig oppsett() { // Fase 2: Registrer hendelser, kommandoer, ECS-systemer // Det er her de fleste av din registreringskode går } @ Override offentlig ugyldig start() { // Fase 3: Server er klar for spillere // Start planlagte oppgaver, åpne tilkoblinger } @ Override offentlig ugyldig avslutting () { // Fase 4: Opprydding før serveren stopper // Lagre data, lukke tilkoblinger, avbryte oppgaver } } FaseMetode Hva skal jeg gjøre her 1. KonstruksjonConstructor Grunnleggende initialisering, logging 2. Oppsettsetup() Registrer hendelser, kommandoer, ECS-komponenter og systemer 3. Start start() Start oppgaver, serveren godtar spillere 4. Shutdownshutdown() Lagre data, rengjøringsressurser Dual Event System Dette er det viktigste konseptet å forstå. Hytale har to separate hendelsessystemer, og å bruke feil er en vanlig feil. Event Buss — Globale serverbegivenheter The EventBus håndterer serverbredde hendelser som spillertilkoblinger, chat og verdenslasting. Registrer håndterere gjennom EventRegistry som leveres til plugin: @ Overstyr Offentlig ugyldig oppsett() { // Synkrone globale hendelser getEventRegistry().RegistrerGlobal( SpillerReadyEvent.class, hendelse -> { getLogger().info("Player ble med: " + event.getPlayer().getusername()); } ), // Async event (som PlayerChatEvent) getEventRegistry().registerAsyncGlobal( SpillerChatEvent.class, fremtid -> { Fremtiden. deretter akseptere(event -> { hvis (event.getMessage().contacts("spam")) { event.set Avbryt( true); } }); } ), } Key Event Buss hendelser: PlayerConnectEvent / PlayerConnectEvent — tilkoblings livssyklus PlayerReadyEvent — spilleren fullt lastet og klar PlayerChatEvent — chatmeldinger (sync, cancellable) AddPlayerToWorldEvent — spiller som går inn i en verden StartWorldEvent / AddWorldEvent / RemoveWorld Event — verdensadministrasjon Hendelsesprioriteter: Bruk EventPriority. EARLY å kjøre først og endre hendelser før andre brukere ser dem. Bruk EventPriority. LATE å se den endelige tilstanden etter at alle andre ledere har behandlet. ECS Hendelser — Entitetsspesifikke handlinger Entity-nivå hendelser som blokkbrudd, blokk plassering og skade håndteres gjennom Entity Component System, ikke EventBus. Du oppretter en EntityEventSystem: Offentlig klasse BlockBreakHandler utvide EntityEventSystem { @ Override offentlig spørring getQuery() { // Målenheter med spesifikke komponenter tilbakespørsel.builder().build(); } @ Override offentlig klasse getEventType() { tilbake BreakBlockEvent.class; } @ Override offentlig ugyldig håndtak(EntityStore butikken, KommandoBuffer buffer, BreakBlock Hendelseshending) { // Prosesser blokkbruddet // Avbryt i filterfasen, ikke her } } Kritisk regel: Bare kanseller ECS hendelser under filter fase. Avbestilling i inspeksjonsfasen har ingen effekt fordi handlingen allerede skjedde. Entity Component System (ECS) Hytale bruker en egen ECS arkitektur. Å forstå dette er viktig for alle ikke-trivial plugin. Korebegrep Entity — bare en unik ID, inneholder ingen data selv Component — ren databeholder som er knyttet til en enhet System — logikk som behandler enheter med spesifikke komponentkombinasjoner Ref — sikker håndtak til en enhet (aldri lagre direkte enhetsreferanser) Store — administrerer enheter som bruker arketyper for effektiv minnelayout Tilpassede komponenter offentlig klassescore Data implementasjoner Komponent< EntityStore> { Offentlig intens score = 0; offentlig streng team = "; Offentlige var lenge med At = System.currentTimeMillis(); @ Override Offentlig ScoreData Clone () { ScoreData copy = ny ScoreData(); copy.score = denne.score; kopi. team = dette teamet; kopi. bli med På = dette.joined ved; returkopi; } } Komponenter må implementere clone(). Legg dem til enheter for å lagre egendefinerte data - scorer, lag, nedkjølinger, oppfinnelser eller spillspesifikk tilstand. Forståelig spillerRef A "Player" i Hytale er ikke en spesiell klasse — det er en enhet som består av komponenter. PlayerRef er faktisk en komponent som lagrer spillerens brukernavn, UUID, språk og nettverkshåndtering. Den forblir aktiv så lenge spilleren er tilkoblet. Commander Registrering Kommandorer implementerer Command grensesnitt: Offentlig klasse Spawn Kommando implementerer kommando { @ Override offentlig streng getName() { retur "spawn"; } @ Override offentlig ugyldig utføre(CommandSender avsender, String[] args) { Hvis (sender instans av spilleren) { // Teleporter spiller å gyte Avsender.sendMessage("Å gyte..."); } } } // Registrer deg i setup() commandRegistry.registerCommand(ny SpawnCommand()); Both Player og CommandSender støtte hasPermission() sjekker. Det innebygde autorisasjonssystemet støtter tillatelser fra brukernivå, gruppearv og jokertegn. Bygg og avsett Bygging ./gradlew build Utgangen JAR går til build/libs/. Distribusjonsstier Platform Mod Directory Windows (lokal)%AppData%/Roaming/Hytale/UserData/Mods/ Linux-server/opt/hytale/Server/mods/ Hot reloading støttes delvis for mindre endringer - bruk Ctrl+F9 i Intelli J til å gjenoppbygge uten full omstart. Store endringer krever en server omstart. EventRegistry renser automatisk opp håndterere når et plugin losser. Publishering to CurseForge CurseForge gjenkjenner tre mod-typer: Packs — aktiva/innholdspakker (JSON data, modeller, teksturer) Plugins - Java JAR-filer ved hjelp av serveren API Early Plugins — bootstrap-plugins for lavnivåklassetransformasjoner (avansert, bruk sparsomt) Samfunnsressurser Moding-samfunnet har bygget omfattende dokumentasjon utover det HyPixel Studios gir: ResourceFocus HyttaleModding.dev Guider, dokumenter, verktøy — 8000+ Discord-medlemmer Britake Studios GitBookTotalt testet opplæring for pakker og plugins HytaleDocs.comCommunity wiki og API referanse Hytale-Toolkit (GitHub)Dekompilert kilde, javadocs, semantisk kodesøk Patcher (GitHub) Bla gjennom serveren JAR som et IntelliJ-prosjekt Merk: Serveren JAR er ikke obfuscated og kan fritt dekompileres. Hypixel Studios har forpliktet seg til å frigjøre hele kildekoden til serveren innen 1–2 måneder etter lanseringen av EA. Hva kommer Server-kodeutgivelse — forventet i mars 2026 Visual scripting — nodebasert skripting for ikke-programmerere (likner Unreal Blueprints) Development bounties — Hypixel Studios planlegger å tilby bounties for samfunnsbidrag Offisiell dokumentasjonsekspansjon — anerkjent som ufullstendig, og utvides basert på community reback Ready å distribuere plugin? Vis din modede server på