# ShrinkNetwork.Integration.EventBus

`ShrinkNetwork` 与 `ShrinkEventBus` 的桥接层。目标不是“把网络生命周期抛几个普通事件出来”，而是让某些 `EventBase` 类型本身就能作为网络消息声明，并在本地与远端之间保持一致的事件语义。

## ✨ 特性概览

| 特性 | 说明 |
|------|------|
| 🌉 **事件即网络消息** | `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]`

## 🚀 快速上手

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

```csharp
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;
}
```

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

```csharp
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(...)`；仅绑定传输不会再通过反射接桥。

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

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

注册之后：

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

## 📖 核心概念

### 事件声明规则

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

1. 继承 `EventBase`
2. 实现 `IShrinkNetworkMessage` 或 `IShrinkNetworkRequest`
3. 标记 `[ShrinkNetworkEvent]`
4. 标记 `[ShrinkNetworkMessage(opcode, route)]`

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

### 广播型事件

广播型事件只需要：

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

适合：

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

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

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

### 增量事件

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

```csharp
[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 请求型事件

如果事件同时满足：

1. `[ShrinkNetworkEvent]`
2. `[ShrinkNetworkMessage(...)]`
3. `[HasResult]`
4. `IShrinkNetworkRequest`

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

```csharp
[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;
}
```

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

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

当前回传内容只有：

- `EventResult`
- `IsCanceled`
- `ErrorCode / ErrorMessage`

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

## 🔧 API 参考

### ContextLoader 接入

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

### 显式接入

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

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

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

### 发送扩展

```csharp
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](LICENSE)