Hytale Modding API: Panduan Pengembangan Plugin Server Lengkap

Sistem plugin server < p > Hytale memberikan pengembang kontrol dalam-dalam atas setiap aspek permainan. Jika Anda telah menulis plugin Bukkit atau Spigot untuk Minecraft, transisi ini langsung - tetapi arsitektur Hytale secara fundamental berbeda dalam cara yang penting. Panduan ini berjalan Anda melalui segala sesuatu dari penataan awal ke penyebaran produksi. < / p > < h2 > Arsitektur Overview < / h2 > < p > Sebelum menulis kode apapun, memahami bagaimana pencetakan Hytale bekerja: < / p > < ul > < li > < kuat > Klien adalah perender. < / strong > Hytale C # client handle graphics, input, and audio - tetapi tidak mengandung logika permainan. Semua simulasi berjalan di server Java, bahkan dalam pemutar tunggal. < / li > < li > < strong > Semuanya server- side. < / strong > Ketika pemain bergabung dengan server modded, aset kustom dan aliran perilaku secara otomatis. Tidak perlu mods klien. < / li > < li > < strong > Empat kategori modding ada: < / strong > Asset Data (JSON), Aset Seni (model blok), Plugin Server (Java), dan Skrip Visual (segera datang). < / li > < / ul > < p > Server plugin adalah kategori yang paling kuat - mereka memberikan akses Java penuh ke server waktu jalan, termasuk Entitas Componen System, pipeline, perintah kerangka kerja, dan manipulasi dunia. < / p > < h2 > Pengaturan Lingkungan Pengembangan < / h2 > < h3 > Prasyarat < / h3 > < tabel > < head > < tr > < th > Alat < / th > < th > Versi < / th > < th > Catatan < / th > < / tr > < / tr > < / thead > < tbody > < tr > < td > < strong > Java < / strong > < / td > < td > 25 + < / td > < td > < td > Hytale menggunakan fitur modern termasuk thread virtual (Proyek Loom) < / td > < / tr > < tr > < td > < strong > Intellij IDEA < / strong > < / td > < td > < td > < td > < td > Direkomendasikan IDE - free Community Edition works fine < / td > < / tr > < tr > < td > < strong > Gradle < / strong > < / td > < / td > 9.2.0 + < / td > < td > Sistem (termasuk dalam template plugin) < / td > < / tr > < tr > < td > < strong > Git < / strong > < / td > < td > Versi terbaru < / td > < td > Untuk mengkloning template resmi < / td > < / tr > < / tbody > < / tabel > < h3 > Klone Template Resmi < / h3 > < p > Hypixel Studios menyediakan template plugin resmi di GitHub: < / p > < pre > < kode > git clone https: / / github.com / HytaleModding / plugin- tempate.git MyFirstPlugin cd MyFirstPlugin < / code > < / pre > < p > Buka proyek dalam IDEA IntelliJ dan biarkan Gradle sync. Templat ini termasuk struktur direktori yang benar, konfigurasi, dan ketergantungan server API. < / p > < p > Alternatif, < strong > HytaleIO Projek Generator < / strong > di hytaleio.com / project- generator dapat membuat Plugin, Mod, atau kombo (combo) projek scaffolding dengan web UI. < / p > < h2 > Plugin Struktur < / h2 > < p > Setiap plugin Hytale mengikuti tata letak direktori ini: < / p > < pre > < kode > your-plugin / Dessassrc / main / java / com / yourname / yourplugin / Plugin-mu. java # Main titik masukan Affresrc / main / sumberdaya / Daftar muatan. json # Plugin metadata (dibutuhkan) Aset Common / # Shared (model, tekstur) Server: Dibangun oleh gradle.kts Tempat duduk. Gradle.kts Gradle.properties < / code > < / pre > < h3 > manifestasi json < / h3 > < p > Setiap plugin membutuhkan < code > manifesjson < / code > di akar dari JAR yang dikompilasi. Ini adalah Hytale setara dengan < kode > plugin.yml < / code >: < / p > < pre > < kode > { "Grup": "com.yourname", "Nama": "YourPluginName", "Main": "com.yourname.yourplugin.YourPlugin", "Versi": "1.0.0", "Deskripsi": "Apa yang plugin Anda lakukan", "Penulis": ["Nama": "Nama Anda"}], "Serververversion": "*", "Ketergantungan": {}, "Ketergantungan Pilihan": {}, "LoadBefore": [], "DisabledByDefault": salah, "IncludeAssetPack": salah } < / code > < / pre > < p > Identifier plugin dibentuk sebagai < code > Grup: Nama < / code > (misalnya, < kode > com.yourname: Nama PluginName < / code >). < kode > Main < / code > titik field ke kelas masukan anda - salah ambil dan plugin tidak akan dimuat. < / p > < h2 > Lifecycle Plugin < / h2 > < p > kelas utama Anda memperluas < kode > JavaPlugin < / kode > dan memiliki empat fase lifecycle: < / p > < pre > < kode > kelas publik Anda Lebar plugin JavaPlugin { public YourPlugin (@ Nonnull JavaPluginInit) { super (init); getLogger () .info ("Plugin dibangun!"); ] @ Override publik void setup () { / / Tahap 2: Peristiwa register, perintah, sistem ECS / / Ini adalah di mana sebagian besar kode pendaftaran Anda pergi ] @ Override publik void start () { / / Tahap 3: Server siap untuk pemain / / Mulai tugas yang dijadwalkan, koneksi terbuka ] @ Override publik membatalkan shutdown () { / / Tahap 4: Membersihkan sebelum server berhenti / / Simpan data, tutup koneksi, batalkan tugas ] } < / code > < / pre > < tabel > < head > < tr > < th > Tahap < / th > < th > Metode < / th > < ke > < th > < th > Apa yang akan dilakukan < / th > < / tr > < / thead > < tbody > < tr > < td > 1. Konstruksi < / td > < td > Konstruktor < / td > < td > Inisialisasi dasar, log < / td > < / tr > < tr > < td > 2. Setup < / td > < td > < kode > setup () < / code > < / td > < td > < td > Peristiwa pendaftaran, perintah, komponen ECS, dan sistem < / td > < / tr > < tr > < td > 3. Mulai < / td > < td > < kode > mulai () < / code > < / td > < td > < td > Mulai tugas, server menerima pemain < / td > < / tr > < tr > < td > 4. Matikan < / td > < td > < kode > shutdown () < / code > < / td > < td > < td > Simpan data, bersihkan sumber daya < / td > < / tr > < / tbody > < / tabel > < h2 > Sistem Dual Event < / h2 > < p > Ini adalah konsep yang paling penting untuk dipahami. Hytale memiliki < strong > dua event systems terpisah < / strong >, dan menggunakan yang salah adalah kesalahan umum. < / p > < h3 > Event Bus - Peristiwa Server Global < / h3 > < p > The < kode > EventBus < / code > menangani peristiwa serverwide seperti koneksi pemain, obrolan, dan penmuat dunia. Penangan register melalui < code > EventRegistry < / code > disediakan ke plugin Anda: < / p > < pre > < kode > @ Override publik void setup () { / / Sinkronisasi peristiwa global getEventRegistry () .registerGlobal ( Player Ready Event.class, event - > { getLogger () .info ("Pemutar bergabung:" + event.getPlayer () .getUsername (); ] ); / / Async event (like PlayerChattings) getEventRegistry () .registerAsyncGlobal ( PlayerChatevent.class, masa depan - > { masa depan. maka terima (acara - > { jika (event.getMessage () .contains ("spam") { event.setCancelled (true); ] }; ] ); } < / code > < / pre > < p > < strong > Acara Kunci Peristiwa bus: < / strong > < / p > < ul > < li > < kode > PlayerConnectEvent < / code > / < kode > PlayerDisconnectEvent < / code > - lifecycle koneksi < / li > < li > < kode > PlayerReadyEvent < / code > - pemutar terisi penuh dan siap < / li > < li > < kode > PlayerChattings < / code > - pesan percakapan (async, cancellable) < / li > < li > < kode > AddPlayerToWorldEvent < / code > - pemutar memasuki dunia < / li > < li > < kode > StartWorldEvent < / code > / < kode > AddWorldWorldEvent < / code > / < kode > RemoveWorld Event < / code > - manajemen dunia < / li > < / ul > < p > < kuat > Prioritas acara: < / strong > Gunakan < kode > EventPrioritas. AWAL < / code > untuk menjalankan pertama dan memodifikasi peristiwa sebelum penangan lain melihatnya. Gunakan < kode > EventPrioritas. LATE < / code > untuk melihat kondisi akhir setelah semua penangan lain telah diproses. < / p > < h3 > ECS Kejadian - Entity- Aksi Khusus < / h3 > < p > Entity-level acara seperti block breaking, block asting, dan kerusakan ditangani melalui < strong > Entitas Componen System < / strong >, bukan EventBus. Anda membuat sebuah < code > EntityEventSystem < / code >: < / p > < pre > < kode > kelas publik BlockBreakHandler extend EntityEventSystem & lt; EntityStore, BreakBlock Peristiwa & gt; { @ Override public Query getQuery () { entitas / / Target dengan komponen spesifik kembali Query.building () .build (); ] @ Override Kelas publik & lt; BreakBlockEvent & gt; getEventType () { kembali BreakBlockEvent.class; ] @ Override public void handle (EntityStore store, Buffer Buffer Perintah, BreakBlock Event) { / / Proses blok istirahat / / Batal dalam fase filter, tidak di sini ] } < / code > < / pre > < p > < kuat > Aturan kritis: < / strong > Hanya membatalkan acara ECS selama tahap < strong > filter < / strong >. Pembatalan dalam fase pemeriksaan tidak memiliki efek karena aksi telah terjadi. < / p > < h2 > Entitas Komponen Sistem (ECS) < / h2 > < p > Hytale menggunakan arsitektur ECS gubahan. Memahami ini adalah penting bagi setiap plugin tidak-sepele. < / p > < h3 > Core Konsep < / h3 > < ul > < li > < strong > Entitas < / strong > - hanya ID unik, tidak berisi data itu sendiri < / li > < li > < strong > Komponen < / strong > - murni data kontainer yang dicantumkan ke sebuah entitas < / li > < li > < strong > Sistem < / strong > - logika yang memproses entitas dengan kombinasi komponen tertentu < / li > < li > < strong > Ref < / strong > - penanganan aman ke sebuah entitas (tidak pernah menyimpan referensi entitas langsung) < / li > < li > < strong > Store < / strong > - entitas yang mengatur menggunakan Archetypes untuk tata letak memori yang efisien < / li > < / ul > < h3 > Komponen Gubahan < / h3 > < pre > < kode > nilai kelas publik Aplikasi data Komponen & lt; EntityStore & gt; { skor int publik = 0; tim public String = "; publik lama bergabung Pada = Sistem.TimetMillis (); @ Override clone publik ScoreData () { Salinan ScoreData = ScoreData baru (); copy.score = this.score; Ganti. tim = this.team; Ganti. bergabung Pada = ini.bergabung Pada; salinan kembali; ] } < / code > < / pre > < p > Komponen harus mengimplementasikan < kode > clone () < / code >. Lampirkan mereka ke entitas untuk menyimpan data gubahan - skor, tim, cooldowns, inventory, atau setiap keadaan game- spesifik. < / p > < h3 > Memahami PlayerRef < / h3 > < p > A "Player" dalam Hytale bukan kelas khusus - itu adalah entitas terdiri dari komponen. < kode > PlayerRef < / code > sebenarnya adalah komponen yang menyimpan nama pengguna pemutar, UUID, bahasa, dan handler jaringan. Ini tetap aktif selama pemutar tersambung. < / p > < h2 > Registrasi Perintah < / h2 > < p > Perintah mengimplementasi perintah < kode > < / code > antar muka: < / p > < pre > < kode > kelas publik Spawn Perintah implementasi Perintah { @ Override string publik getName () {return "spawn";} @ Override public void execution (Command Sender sender, String [] args) { if (sender instanceof Player player) { / / Pemain teleport untuk spawn sender.sendMessage ("Teleporting to spawn"...); ] ] ] / / Register dalam setup () commander Registy.registerCommand (new SpawnCommand ())); < / code > < / pre > < p > Kedua < kode > Pemutar < / kode > dan < kode > Perintah < / kode > mendukung < kode > Hasame () < / code > cek. Sistem perizinan built-in mendukung perizinan tingkat pengguna, warisan grup, dan pencocokan wildcard. < / p > < h2 > Build dan Deploy < / h2 > < h3 > Building < / h3 > < pre > < kode >. / gradlew build < / code > < / pre > < p > Keluaran JAR menuju ke < kode > build / libs / < / code >. < / p > < h3 > Jalur Pemindahan < / h3 > < tabel > < head > < tr > < th > Platform < / th > < th > Direktori Mod < / th > < / tr > < / thead > < tbody > < tr > < td > Windows (lokal) < / td > < kode >% AppData% / Roaming / Hytale / UserData / Mods / < / code > < / td > < / tr > < / tr > < tr > < td > server Linux < / td > < kode > / opt / hytale / Server / mods / < / code > < / td > < / tr > < / tr > < / tbody > < / tabel > < p > Reloading Hot adalah sebagian didukung untuk perubahan kecil - gunakan < kode > Ctrl + F9 < / code > dalam Intelli J untuk membangun kembali tanpa restart penuh. Perubahan besar memerlukan sebuah server restart. < kode > EventRegistry < / code > otomatis membersihkan penangan ketika sebuah plugin membongkar. < / p > < h3 > Penerbitan ke CurseForge < / h3 > < p > CurseForge mengakui tiga tipe mod: < / p > < ul > < li > < strong > Packs < / strong > - paket aset / isi (data JSON, model, tekstur) < / li > < li > < strong > Plugin < / strong > - Berkas Java JAR menggunakan server API < / li > < li > < strong > Awal Plugin < / strong > - bootstrap plugin untuk transformasi kelas rendah (maju, gunakan luar biasa) < / li > < / ul > < h2 > Sumber Daya Masyarakat < / h2 > < p > Komunitas modding telah membangun dokumentasi yang luas melebihi apa yang disediakan Studio Hypixel: < / p > < tabel > < head > < tr > < th > Resource < / th > < th > Fokus < / th > < / tr > < / thead > < tbody > < tr > < td > < strong > HytaleModding.dev < / strong > < / td > < td > < td > Guides, docs, tools - 8.000 + Discord anggota < / td > < / tr > < tr > < td > < strong > Britakee Studios GitBook < / strong > < / td > Comprehensive tutorial diuji untuk Packs dan Plugin < / td > < / tr > < tr > < td > < strong > HytaleDocs.com < / strong > < / td > < td > Community wiki dan API reference < / td > < / tr > < / tr < tr > < td > < strong > Hytale-Toolkit (GitHub) < / strong > < / td > < td > Decompicked sumber, javaks, semantic kode pencarian < / td > < / tr > < tr > < td > < strong > Patcher (GitHub) < / strong > < / td > < td > Menelusuri server JAR sebagai projek IntelliJ < / td > < / tr > < / tbody > < / tabel > < p > < strong > Catatan: < / strong > Server JAR tidak obfuskated dan dapat secara bebas didekompilasi. Studios Hypixel telah berkomitmen untuk merilis kode sumber server penuh dalam waktu 1-2 bulan peluncuran EA. < / p > < h2 > Apa yang datang < / h2 > < ul > < li > < strong > source code rilis server < / strong > - diduga oleh Maret 2026 < / li > < li > < strong > Skrip Visual < / strong > - node-based scripting untuk pemrogram tidak-asli (mirip dengan Blueprints Unreal) < / li > < li > < strong > Development karunia < / strong > - Hypixel Studios berencana untuk menawarkan hadiah bagi kontribusi masyarakat < / li > < li > < strong > Ekspansi dokumentasi resmi < / strong > - diakui sebagai tidak lengkap, yang diperluas berdasarkan umpan balik masyarakat < / li > < / ul > < p > Siap untuk menyebarkan plugin Anda? Daftar server mod Anda pada < a href = "/" > HytaleCharts < / a > sehingga pemain dapat menemukan penciptaan Anda. Untuk pola pengembangan mini-spesifik, periksa < a href = "/ news / hytale -ubahan -minigame-server- pengembangan -guide" > Panduan Minigames Kustom < / a >. < / p >