מדריך API לשרת Hytale: אירועים, הודעות ומדריך לפיתוח תוספים

הבנת ארכיטקטורת שרת Hytale API שרת Hytale בנוי על ארכיטקטורת Java חזקה שתהיה מוכרת לכל מי שעבד עם תוספי שרתי Minecraft. עם החזרה ל-Legacy Engine, למפתחים יש כעת גישה לבסיס קוד בשל ומנוסה שמעדיף נגישות מודינג על פני מורכבות חוצת פלטפורמות. בלב השרת נמצאת חבילת com.hypixel.hytale.server.core, המספקת את הבסיס לכל פעולות צד השרת. זה כולל ניהול שחקנים, טיפול בעולמות, שיגור אירועים ועיבוד פקודות. אירועי חיבור שחקנים: טיפול בכניסה ויציאה אחת הדרישות הנפוצות ביותר לכל תוסף שרת היא תגובה לשחקנים שמצטרפים או עוזבים. API של Hytale מספק שני אירועים חיוניים למטרה זו. PlayerConnectEvent מופעל כאשר שחקן מתחבר בהצלחה לשרת, אירוע זה נותן לכם גישה להפניית השחקן לפני שהוא מופיע לחלוטין בעולם. מאפיינים עיקריים כוללים: playerRef - מופע PlayerRef המכיל UUID, שם משתמש ומידע רשת player - ישות Player שתייצג אותם בעולם world - מופע World שאליו הם מצטרפים holder - מחזיק מאגר ישויות לגישה לרכיבים בניגוד לאירועים מסוימים אחרים, PlayerConnectEvent אינו ניתן לביטול. אם אתם צריכים למנוע משחקן להצטרף, עליכם לטפל בזה בשכבת האימות. eventRegistry.register(PlayerConnectEvent::class.java) { event -> val player = event.playerRef logger.info("Player connected: ${player.username}") // Send welcome message player.sendMessage(Message.raw("Welcome to the server!")) } PlayerDisconnectEvent מופעל כאשר שחקן עוזב את השרת, אירוע זה כולל הקשר חשוב על הסיבה לניתוק: playerRef - הפניית השחקן העוזב disconnectReason - ערך enum המציין timeout, kick, יציאה או כיבוי שרת אירוע זה גם אינו ניתן לביטול מכיוון שהניתוק כבר התרחש ברמת הרשת. מחלקת Message: עיצוב טקסט עשיר בעלי שרתים שמעוניינים ליצור חוויות צ'אט מלוטשות יבלו זמן רב עם מחלקת Message. הממוקמת בחבילת ההודעות הליבתית, היא מספקת API שוטף לבניית טקסט מעוצב. יצירת הודעות בסיסיות // Simple text message val msg = Message.raw("Hello, world!") // With color formatting val styled = Message.raw("Important!") .color("red") .bold(true) .italic(false) .monospace(true) החלפת פרמטרים לתוכן דינמי, השתמשו במצייני מקום של פרמטרים: val welcome = Message.raw("Welcome, {name}! You have {coins} coins.") .param("name", player.username) .param("coins", playerData.coinBalance.toString()) קישורים לחיצים הודעות יכולות לכלול היפר-קישורים לחיצים: val linked = Message.raw("Click here to visit our website") .link("https://example.com") דפוסי רישום אירועים מערכת האירועים של Hytale תומכת הן בטיפול סינכרוני והן באסינכרוני באירועים, ומעניקה למפתחים גמישות בהתאם לדרישות הביצועים. רישום סינכרוני לאירועים שדורשים עיבוד מיידי בתהליכון השרת: eventRegistry.register(PlayerInteractEvent::class.java) { event -> if (event.actionType == ActionType.RIGHT_CLICK) { // Process the interaction event.setCancelled(true) } } רישום אסינכרוני לאירועים שניתן לעבד מחוץ לתהליכון הראשי (כמו מיתון צ'אט): eventRegistry.registerAsync(PlayerChatEvent::class.java) { future -> future.thenApply { event -> // Perform async chat filtering if (containsBannedWords(event.content)) { event.setCancelled(true) } event } } טבלת אירועים נפוצים הנה מדריך מהיר לאירועים הנפוצים ביותר בפיתוח שרתים: שם האירועניתן לביטולמאפיינים עיקריים PlayerConnectEventלאplayerRef, player, world, holder PlayerDisconnectEventלאplayerRef, disconnectReason PlayerChatEventכן (אסינכרוני)sender, targets, content, formatter PlayerInteractEventכןplayer, actionType, itemInHand, targetBlock, targetEntity PlayerDeathEventלאplayer PlayerRespawnEventלאplayer BreakBlockEventכןitemInHand, targetBlock, blockType PlaceBlockEventכןitemInHand, targetBlock, rotation DamageBlockEventכןitemInHand, targetBlock, currentDamage, damage DropItemEventכןitem, location CraftRecipeEventכןcraftedRecipe, quantity בניית פקודות מותאמות אישית מערכת הפקודות מאפשרת לכם לרשום פקודות slash שהשחקנים יכולים לבצע בצ'אט. מימוש פקודה בסיסית class MyCommand : Command { override fun getName(): String = "mycommand" override fun execute(sender: CommandSender, args: Array<String>) { sender.sendMessage(Message.raw("Hello from my custom command!")) } } // Register in your plugin's setup phase commandRegistry.registerCommand(MyCommand()) שימוש ב-CommandManager ניתן גם לבצע פקודות באופן תכנותי: val commandManager = CommandManager.get() commandManager.handleCommand(sender, "time day") מחזור חיי התוסף ומבנהו כל תוסף שרת Hytale מרחיב את מחלקת הבסיס JavaPlugin, המספקת רישומים חיוניים ו-hooks של מחזור חיים. שלבי מחזור חיי התוסף Construction - יצירת מופע מחלקת התוסף PreLoad - אתחול אסינכרוני לפני הפעלת השרת Setup - רישום רכיבים, אירועים ופקודות Start - השרת מוכן לקבל שחקנים Shutdown - ניקוי לפני כיבוי השרת מאפייני תוסף עיקריים // Available in your plugin class logger: HytaleLogger // Logging capability manifest: PluginManifest? // Plugin metadata from manifest file eventRegistry: EventRegistry // Register event listeners commandRegistry: CommandRegistry // Register commands dataDirectory: Path // Plugin storage location taskRegistry: TaskRegistry // Scheduled task management עוזר תצורה תוספים יכולים לטעון בקלות קבצי תצורה בפורמט JSON: // Using default config.json val config: Config<MyConfigClass> = withConfig(MyConfigClass.CODEC) // Using custom filename val config: Config<MyConfigClass> = withConfig("custom-name.json", MyConfigClass.CODEC) עבודה עם שחקנים מחלקת PlayerRef היא הממשק העיקרי שלכם לאינטראקציה עם שחקנים מחוברים. זהות ומיקום השחקן val player: PlayerRef = event.playerRef // Identity val uuid: UUID = player.uuid val name: String = player.username val language: String = player.language // Position val transform: Transform = player.transform val worldUuid: UUID = player.worldUuid val headRotation: Vector3f = player.headRotation גישה לישות השחקן לאינטראקציות עמוקות יותר כמו ניהול מלאי, גשו לישות Player: val playerEntity: Player = player.entity // Inventory operations val inventory: Inventory = playerEntity.inventory playerEntity.sendInventory() // UI managers val hotbar = playerEntity.hotbarManager val windows = playerEntity.windowManager val pages = playerEntity.pageManager val hud = playerEntity.hudManager // Permissions val canBuild: Boolean = playerEntity.hasPermission("server.build") ניהול עולמות ויקום סינגלטון Universe מספק גישה לכל העולמות והשחקנים המחוברים. val universe = Universe.get() // Player access val allPlayers: List<PlayerRef> = universe.players val playerCount: Int = universe.playerCount val specificPlayer: PlayerRef? = universe.getPlayer(uuid) // World access val worlds: Map<String, World> = universe.worlds val defaultWorld: World? = universe.defaultWorld val specificWorld: World? = universe.getWorld("my-world") // World management val newWorld: CompletableFuture<World> = universe.addWorld("new-world") val loaded: CompletableFuture<World> = universe.loadWorld("existing-world") אזהרת בטיחות תהליכונים גישה לרכיבים חייבת להתרחש בתהליכון העולם. תמיד עטפו פעולות בבלוק execute: world.execute { // Safe component access here val entities = world.getEntities() } צעדים הבאים למפתחי שרתים עם מדריך API זה כבסיס, אתם מוכנים להתחיל לבנות תוספי שרת Hytale. משאבים עיקריים לחקירה: מערכת Entity Component System (ECS) למניפולציית ישויות מתקדמת מודולים מובנים כמו NPC, פורטלים ומערכות משימות מערכת סקריפטים חזותית להתנהגויות משחק פרוטוקול רשת לטיפול בחבילות מותאמות אישית זכרו שככל ש-Hytale מתקדם דרך גישה מוקדמת, ה-API עשוי להתפתח. הישארו מחוברים לקהילה ולתיעוד הרשמי ככל שהוא מתפתח.