مرجع 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 ارث‌بری می‌کند که رجیستری‌ها و هوک‌های ضروری چرخه حیات را فراهم می‌کند. مراحل چرخه حیات پلاگین 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، Portal و سیستم‌های Quest سیستم اسکریپت‌نویسی بصری برای رفتارهای بازی پروتکل شبکه برای مدیریت بسته‌های سفارشی به یاد داشته باشید که با پیشرفت Hytale در دسترسی زودهنگام، API ممکن است تکامل یابد. با جامعه و مستندات رسمی در ارتباط بمانید.