مرجع 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 تشير إلى انتهاء المهلة أو الطرد أو الخروج أو إيقاف الخادم هذا الحدث أيضاً غير قابل للإلغاء حيث أن قطع الاتصال قد حدث بالفعل على مستوى الشبكة. فئة 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 والبوابات وأنظمة المهام نظام البرمجة المرئية لسلوكيات اللعبة بروتوكول الشبكة لمعالجة الحزم المخصصة تذكر أنه مع تقدم Hytale عبر الوصول المبكر، قد يتطور API. ابق على اتصال مع المجتمع والوثائق الرسمية مع تطورها.