特性	说明
🌉 事件即网络消息	`EventBase` 可直接实现 `IShrinkNetworkMessage / IShrinkNetworkRequest` 参与网络同步
🔁 自动双端分发	本地 `EventBus.TriggerEvent(...)` 后，可自动转发到远端并重新进入远端 `EventBus`
✅ HasResult 请求语义	请求型事件支持 `EventResult` 与取消状态回传
📉 增量事件去重	`IShrinkNetworkDeltaEvent` 按 `SessionId + EventType + DeltaKey` 做版本过滤
🧩 按键接入	`ShrinkNetworkEventBusComponent` 注入网络服务，随依赖激活和撤回
🧰 更顺手的扩展 API	`session.PublishEventAsync(...)`、`session.RequestEventAsync(...)`、`service.UseEventBusBridge(...)`

📦 依赖

ShrinkNetwork
ShrinkEventBus
Unity 2022.3+

⚙️ 安装前提

桥接层默认假设你已经有：

一套正常工作的 ShrinkNetworkService
一套正常工作的 ShrinkEventBus
事件类型明确声明 [ShrinkNetworkEvent] + [ShrinkNetworkMessage]

🚀 快速上手

第一步：声明广播型网络事件

using ShrinkEventBus;
using ShrinkNetwork;
using ShrinkNetwork.Integration;

[ShrinkNetworkEvent]
[ShrinkNetworkMessage(3001, "room/player_ready")]
public sealed class PlayerReadyEvent : EventBase, IShrinkNetworkMessage
{
    public string PlayerId { get; set; } = string.Empty;
    public string RoomId { get; set; } = string.Empty;
}

第二步：正常启动网络服务

var service = new ShrinkNetworkService(
    new ShrinkMessagePackNetworkSerializer(),
    new ShrinkNetworkMessageRegistry(),
    new ShrinkNetworkRouter());

service.AutoRegisterAll();
service.BindTransport(new ShrinkTcpClientTransport("127.0.0.1", 17001));

ContextLoader 项目由 Starter 组合根装配 ShrinkNetworkEventBusComponent。Standalone 项目需要显式调用 service.UseEventBusBridge(...)；仅绑定传输不会再通过反射接桥。

第三步：像普通事件一样触发

EventBus.TriggerEvent(new PlayerReadyEvent
{
    PlayerId = "10001",
    RoomId = "alpha"
});

注册之后：

本地事件先按正常 EventBus 流程执行
桥接层自动把该事件转发到当前 ShrinkNetworkService 的在线 session
远端收到后重新进入远端 EventBus.TriggerEventAsync(...)

📖 核心概念

事件声明规则

可桥接事件需要同时满足：

继承 EventBase
实现 IShrinkNetworkMessage 或 IShrinkNetworkRequest
标记 [ShrinkNetworkEvent]
标记 [ShrinkNetworkMessage(opcode, route)]

如果缺少这些条件，桥接层会忽略该事件类型。

广播型事件

广播型事件只需要：

EventBase
IShrinkNetworkMessage
[ShrinkNetworkEvent]
[ShrinkNetworkMessage(...)]

适合：

玩家就绪
房间状态变更
UI 同步通知

手动定向发送时，推荐直接用扩展：

await session.PublishEventAsync(new PlayerReadyEvent
{
    PlayerId = "10001",
    RoomId = "alpha"
});

增量事件

如果事件本身就是 delta，而不是完整状态，可以实现 IShrinkNetworkDeltaEvent：

[ShrinkNetworkEvent]
[ShrinkNetworkMessage(3002, "room/player_state_delta")]
public sealed class PlayerStateDeltaEvent : EventBase, IShrinkNetworkMessage, IShrinkNetworkDeltaEvent
{
    public string PlayerId { get; set; } = string.Empty;
    public int Hp { get; set; }

    public string DeltaKey => PlayerId;
    public long DeltaVersion { get; set; }
}

桥接层会按：

SessionId + EventType + DeltaKey

记录已应用版本：

新版本进入远端 EventBus
旧版本或重复版本直接丢弃

这套语义是“事件自己声明 delta 载荷”，不是自动做字段 diff。

HasResult 请求型事件

如果事件同时满足：

[ShrinkNetworkEvent]
[ShrinkNetworkMessage(...)]
[HasResult]
IShrinkNetworkRequest

就可以走“远端裁决”语义：

[Cancelable]
[HasResult]
[ShrinkNetworkEvent]
[ShrinkNetworkMessage(3010, "room/can_use_skill")]
public sealed class CanUseSkillEvent : EventBase, IShrinkNetworkRequest
{
    public string PlayerId { get; set; } = string.Empty;
    public string SkillId { get; set; } = string.Empty;
}

var outcome = await session.RequestEventAsync(new CanUseSkillEvent
{
    PlayerId = "10001",
    SkillId = "fireball"
});

if (outcome.IsSuccess && outcome.Result == EventResult.ALLOW)
{
    // 允许释放技能
}

当前回传内容只有：

EventResult
IsCanceled
ErrorCode / ErrorMessage

不会自动回传整个事件对象上其他字段的最终改动。

🔧 API 参考

ContextLoader 接入

// ShrinkApp.Starter.Basic 组合根自动加入 ShrinkNetworkEventBusComponent。
// 组件注入 shrink.service.network 后注册，网络提供者撤回时注销。

显式接入

Standalone 或需要自定义 session 过滤时：

service.UseEventBusBridge(new ShrinkNetworkEventBusBridgeOptions
{
    SessionFilter = (session, evt) => session.SessionId > 0,
    DispatchScheduler = new ShrinkNetworkUnityMainThreadDispatchScheduler()
});

如果网络事件数量较大并且需要明确的每帧预算，使用 ShrinkNetworkDispatchQueue，在 Unity 主线程的 Update 中调用 PumpAsync(maxItems)；队列满时默认拒绝，避免无界堆积。

发送扩展

session.PublishEventAsync<TEvent>(eventArgs, route = null)
session.RequestEventAsync<TEvent>(eventArgs, options = null)
service.BroadcastEventAsync<TEvent>(eventArgs, sessionFilter = null, route = null)

🏗️ 工作流

本地 EventBus.TriggerEvent(evt)
  ├─ 本地订阅链正常执行
  ├─ Bridge 监听 OnEventTriggered
  ├─ 识别为 [ShrinkNetworkEvent]
  ├─ 自动转发到在线 session
  └─ 远端收到后重新进入 EventBus.TriggerEventAsync(evt)

请求型事件则额外带回：

远端 EventResult / IsCanceled / ErrorCode

✅ 最佳实践

广播型事件和请求型事件分开设计，不要一个类型同时混两种用途
高实时状态优先实现 IShrinkNetworkDeltaEvent
需要“远端裁决”的事件显式标记 [HasResult]
优先走 session.PublishEventAsync(...) / session.RequestEventAsync(...)，不要在业务层到处直接调用底层 bridge

⚠️ 注意事项

核心网络程序集不反射发现桥接包；桥接生命周期只来自组合组件或显式 API
当前只回传 EventResult 与取消状态，不自动同步事件对象其它字段改动
桥接层会抑制“远端收到后再次回传”的回环转发
如果你需要按目标 session 精细控制广播范围，使用 UseEventBusBridge(...) 或 BroadcastEventAsync(...)

📄 License

MIT

README.md Unescape Escape

ShrinkNetwork.Integration.EventBus

✨ 特性概览