> For the complete documentation index, see [llms.txt](https://docs.edgegap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.edgegap.com/zh/learn/distributed-relay/relay-transport-samples.md).

# 传输示例

Edgegap 中继的传输示例，展示在匹配系统或大厅将玩家分组后如何创建中继会话。

在通过匹配器或大厅管理你的玩家，然后使用 Edgegap API 为他们创建一个中继会话后，你需要在中继准备就绪后将玩家连接到中继。Edgegap 提供了专门用于完成这项工作的传输方式，本指南将向你展示如何在项目中实现它。该传输可在 [此处在我们的 GitHub 上](https://github.com/edgegap/relay-transport-template-model/tree/main).

在 Unity 中，目前该传输有以下 netcode 版本：

* Mirror；
* Fishnet；
* Unity Netcode for GameObjects（NGO）。

### 添加传输

下载适用于你的 netcode 的正确传输后，你需要将其包含到项目中。首先，将它添加到项目文件中的以下位置：

* **Mirror** ：添加 `Edgegap` 下的文件夹 `Assets/Mirror/Transports`;
* **Fishnet** ：添加 `Edgegap KcpTransport` 下的文件夹 `Assets/Fishnet/Plugins`;
* **NGO** ：添加 `EdgegapRelay` 和 `kcp2k` 下的文件夹 `Assets/Edgegap`.

然后，添加 `EdgegapKcpTransport` 脚本到你的 `NetworkManager` gameObject，并确保将这个新组件拖到 `Transport` gameObject 的 Transport 属性中。

{% hint style="info" %}
如果存在该选项，请务必禁用 `Relay GUI` 中 `EdgegapKcpTransport` 的组件 `NetworkManager`。否则，在尝试连接到中继时它会产生干扰。

该选项主要存在于该传输的 Mirror 和 NGO 版本中。
{% endhint %}

### 连接到中继

在完成匹配并创建中继会话后，使用 Edgegap API 确定中继何时准备好接受连接。一旦准备就绪，请使用 API 响应中提供的数据来设置传输的值。你需要在相应字段中填入以下值：

* 中继的 `IP` 地址用作 `传输的中继地址`;
* 该 `会话授权令牌` 用作 `传输的会话 ID`;
* 该 `用户的授权令牌` 用作 `传输的用户 ID`.

#### 服务器/主机连接

* 中继的 `服务器端口` 值用作 `传输的中继端口` .

#### 客户端连接

* 中继的 `客户端端口` 值用作 `传输的中继端口` .

{% hint style="info" %}
每个玩家都会有自己唯一的授权令牌，但会话令牌在会话中的每个玩家之间保持不变。
{% endhint %}

### 使用 Mirror

{% code collapsedlinecount="10" %}

```cs
// `data` 是反序列化后的 API 响应，已转换为 JSON
// `_EdgegapTransport` 是 EdgegapKcpTransport

// 将 uint? 转换为 uint
uint sessionAuthorizationToken = data.authorization_token ?? 0;

//TODO 找出哪个会话用户与该玩家匹配，`i` 表示它在列表中的位置
uint userAuthorizationToken = data.session_users?[i].authorization_token ?? 0;

_EdgegapTransport.ChangeValue(
    data.relay.ip,
    data.relay.ports.client.port,
    data.relay.ports.server.port,
    data.session_id,
    sessionAuthorizationToken,
    userAuthorizationToken
);

// 如果是主机玩家，则执行 `NetworkManager.Singleton.StartHost();`
// 或者，如果是客户端，则执行 `NetworkManager.Singleton.StartClient();` 
```

{% endcode %}

### 使用 Fishnet

{% code collapsedlinecount="10" %}

```cs
// `data` 是反序列化后的 API 响应，已转换为 JSON
// `_transport` 是 EdgegapKcpTransport

// 将 uint? 转换为 uint
uint sessionAuthorizationToken = data.authorization_token ?? 0;

//TODO 找出哪个会话用户与该玩家匹配，`i` 表示它在列表中的位置
uint userAuthorizationToken = data.session_users?[i].authorization_token ?? 0;

Relay relay = data.relay;
string address = relay.ip;
ushort serverPort = relay.ports.server.port;
ushort clientPort = relay.ports.client.port;

var relayData = new EdgegapRelayData(
    address,
    serverPort,
    clientPort,
    userAuthorizationToken,
    sessionAuthorizationToken
);
_transport.SetEdgegapRelayData(relayData);

// 如果是主机，则执行 `_transport.StartConnection(true);`
// 或者，如果是客户端，则执行 `_transport.StartConnection(false);`
```

{% endcode %}

### 使用 NGO

{% code collapsedlinecount="10" %}

```cs
// `data` 是反序列化后的 API 响应，已转换为 JSON
// `_EdgegapTransport` 是 EdgegapKcpTransport

// 将 uint? 转换为 uint
uint sessionAuthorizationToken = data.authorization_token ?? 0;

//TODO 找出哪个会话用户与该玩家匹配，`i` 表示它在列表中的位置
uint userAuthorizationToken = data.session_users?[i].authorization_token ?? 0;

_EdgegapTransport.relayAddress = data.relay.ip;
_EdgegapTransport.relayGameClientPort = data.relay.ports.client.port;
_EdgegapTransport.relayGameServerPort = data.relay.ports.server.port;
_EdgegapTransport.sessionId = sessionAuthorizationToken;
_EdgegapTransport.userId = userAuthorizationToken;

// 如果是主机玩家，则执行 `NetworkManager.Singleton.StartHost();`
// 或者，如果是客户端，则执行 `NetworkManager.Singleton.StartClient();` 
```

{% endcode %}

### 使用 ApiResponse

{% code collapsedlinecount="10" %}

```cs
public class ApiResponse
{
    public string session_id { get; set; }
    public uint? authorization_token { get; set; }
    public string status { get; set; }
    public bool ready { get; set; }
    public bool linked { get; set; }
    public object? error { get; set; }
    public List<SessionUser>? session_users { get; set; }
    public Relay relay { get; set; }
    public object? webhook_url { get; set; }
}
```

{% endcode %}

一旦这些值设置正确，就使用传输将每个玩家连接到中继。稍等片刻后，你就可以开始游戏了！

### 示例项目

以下项目是使用 Edgegap 中继传输的简单示例。

要让它们正常工作，请打开命令提示符终端，并通过以下方式下载项目： `git clone [URL]` 命令。然后通过 Unity Hub 在编辑器中打开项目文件夹，再更改 `RelayProfileToken` 在 `HelloWorldManager` 的组件 `NetworkManager` gameObject 中的值，改为你自己的中继配置文件令牌。

* [Mirror 示例](https://github.com/edgegap/relay-sample-unity-mirror-)
* [Fishnet 示例](https://github.com/edgegap/relay-sample-unity-fishnet-)
* [NGO 示例](https://github.com/edgegap/relay-sample-unity-ngo-helloworld)

{% hint style="info" %}
使用你自定义的 [Relay Profile 令牌](https://app.edgegap.com/relay-management/dashboard) 在 `HelloWorldManager.cs` 或 `EdgegapRelayService.cs`.
{% endhint %}
