Floodgate事件总线揭秘FloodgateEventBus与SkinApplyEvent开发实战指南【免费下载链接】FloodgateHybrid mode plugin to allow for connections from Geyser to join online mode servers.项目地址: https://gitcode.com/gh_mirrors/fl/FloodgateFloodgate 是连接 Geyser 与在线模式 Java 服务器的混合模式插件它的事件总线FloodgateEventBus是二次开发的入口。本文带你完整理解 Floodgate 事件总线的三层架构并通过皮肤事件 SkinApplyEvent 动手实战如何获取总线、注册监听器、控制事件顺序、取消皮肤应用。事件总线是什么为什么需要它Floodgate 在玩家登录、皮肤下发、插件卸载等关键节点都会触发内部事件。事件总线就是这些事件的广播中心解耦皮肤应用、账号绑定、统计上报等功能各自监听事件互不干扰可拦截事件可被取消Cancellable插件可以阻止默认行为有序执行通过PostOrder控制监听器在 EARLY / NORMAL / LAST 阶段执行对开发者来说想让自己的插件响应 Floodgate 的行为比如玩家皮肤即将被替换时插入自定义逻辑事件总线就是官方支持的标准做法。三层架构接口、实现、订阅者Floodgate 的事件系统分为清晰的三层层级类作用API 接口FloodgateEventBus暴露给第三方插件的总线接口核心实现EventBus基于 GeyserMC 事件框架的EventBusImpl订阅实现EventSubscriber把监听方法包装成总线上的订阅FloodgateEventBus本身只是一个薄封装继承自 GeyserMC 通用事件框架public interface FloodgateEventBus extends EventBusObject, FloodgateSubscriber? { } 接口定义api/src/main/java/org/geysermc/floodgate/api/event/FloodgateEventBus.java#L30真正的实现类EventBus负责创建订阅者并把Subscribe注解上的postOrder执行顺序、ignoreCancelled是否忽略已取消事件参数传递下去 实现类core/src/main/java/org/geysermc/floodgate/event/EventBus.java#L39-L62如何拿到事件总线实例最推荐的方式是通过FloodgateApi获取无需关心注入细节FloodgateEventBus eventBus FloodgateApi.getInstance().getEventBus();内部由InstanceHolder静态持有总线实例在插件初始化时通过set()一次性注入并带有一个UUID key防止跨实例误用 获取方法api/src/main/java/org/geysermc/floodgate/api/FloodgateApi.java#L154-L156 实例持有者api/src/main/java/org/geysermc/floodgate/api/InstanceHolder.java#L36-L44SkinApplyEvent 皮肤事件详解SkinApplyEvent是 Floodgate 目前对外暴露的核心事件当 Floodgate 收到一个玩家皮肤、准备应用到服务器玩家身上时触发。它携带三类信息接口定义在 api/src/main/java/org/geysermc/floodgate/api/event/skin/SkinApplyEvent.java#L39-L73player()即将接收皮肤的FloodgatePlayercurrentSkin()玩家当前已应用的皮肤可能为nullnewSkin()待应用的新皮肤可通过newSkin(SkinData)替换皮肤数据结构SkinData包含两部分value()Base64 纹理数据和signature()签名这是 Bedrock 平台向服务器证明皮肤合法性的关键。关键行为默认情况下事件会被取消接口注释中有一句非常重要的说明 当hasSkin为 true 时事件默认会被取消——因为 Floodgate 默认只在玩家还没有皮肤时才应用皮肤。也就是说如果你只想观察皮肤流监听方法里做日志即可如果你想强制覆盖玩家已有皮肤需要在监听器中调用event.setCancelled(false)把它重新放行。事件的具体实现是SkinApplyEventImpl继承自AbstractCancellable只允许修改newSkin、不允许修改玩家对象保证了事件的不可变语义 事件实现core/src/main/java/org/geysermc/floodgate/event/skin/SkinApplyEventImpl.java#L35-L67实战监听 SkinApplyEvent 的三个步骤第一步定义订阅类订阅者需要实现FloodgateSubscriberT接口对 GeyserMCSubscriber的标记性继承 订阅者接口api/src/main/java/org/geysermc/floodgate/api/event/FloodgateSubscriber.java#L30import org.geysermc.floodgate.api.event.FloodgateSubscriber; import org.geysermc.floodgate.api.event.skin.SkinApplyEvent; public class MySkinListener implements FloodgateSubscriberSkinApplyEvent { Subscribe public void onSkinApply(SkinApplyEvent event) { // 观察或修改皮肤数据 event.newSkin(newSkinData); } }第二步控制执行顺序Floodgate 内部监听器大量使用Subscribe(order PostOrder.EARLY)/PostOrder.LAST来卡位。例如 Velocity 端的监听器在 velocity/src/main/java/org/geysermc/floodgate/listener/VelocityListener.java#L122 就用PostOrder.EARLY保证先于普通监听执行。经验法则想先于所有业务逻辑PostOrder.EARLY想最后兜底、看最终结果PostOrder.LAST只想旁观、事件被取消时不参与加上ignoreCancelled true第三步注册到总线FloodgateEventBus eventBus FloodgateApi.getInstance().getEventBus(); eventBus.subscribe(new MySkinListener());也可以直接订阅函数式处理器EventBus.makeSubscription同时支持Subscriber和Consumer两种形式eventBus.subscribe(SkinApplyEvent.class, event - logger.info(Skin for event.player().getName()), PostOrder.EARLY);这种函数式写法在核心代码里也很常见例如关闭时清理资源 函数式订阅示例core/src/main/java/org/geysermc/floodgate/module/CommonModule.java#L102事件从哪里发出看一条完整链路以皮肤上传为例可以清楚看到事件源 → 总线 → 监听器的完整链路玩家通过 Bedrock 上传皮肤WebSocket 客户端接收数据core/src/main/java/org/geysermc/floodgate/skin/SkinUploadSocket.java#L47SkinUploadManager收到消息后构造SkinApplyEventImpl并通过总线的Subscribe处理器分发core/src/main/java/org/geysermc/floodgate/skin/SkinUploadManager.java#L69各平台Spigot / Bungee / Velocity的SkinApplier根据事件是否被取消决定最终是否向 Java 端下发皮肤例如 spigot/src/main/java/org/geysermc/floodgate/pluginmessage/SpigotSkinApplier.java这条链路体现了 Floodgate 事件设计的精髓平台差异被隔离在监听器里事件本身保持平台无关。常见问题清单 问题说明监听器没被触发确认订阅的是SkinApplyEvent接口而不是SkinApplyEventImpl实现类事件总是已取消默认行为见上文需要时手动setCancelled(false)拿不到总线插件加载太早InstanceHolder尚未初始化建议监听PostEnableEvent后再订阅想区分执行先后使用PostOrder.EARLY / NORMAL / LAST 生命周期事件参考core/src/main/java/org/geysermc/floodgate/event/lifecycle/PostEnableEvent.java总结Floodgate 事件总线虽小接口只有几行但麻雀虽小五脏俱全FloodgateEventBus负责暴露能力EventBus负责调度EventSubscriber负责把监听方法挂到总线上而SkinApplyEvent则是最典型的可取消 可修改 有序执行综合案例。掌握这三层结构和PostOrder的用法你就能安全地把自己的逻辑织入 Floodgate 的玩家生命周期而不必修改任何平台插件代码。【免费下载链接】FloodgateHybrid mode plugin to allow for connections from Geyser to join online mode servers.项目地址: https://gitcode.com/gh_mirrors/fl/Floodgate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考