Mirage

英文原文正文为项目原始 README（英文），本站后续会翻译为中文，当前仅剔除图片与无关章节并统一排版。

什么是海市蜃楼？

Mirage 是一个适用于 Unity 的高级网络库。它模块化、高性能，并且设计易于使用，无论你是在制作 MMO、合作游戏还是 FPS。

Mirage 已在发布的游戏中通过实战检验，并且在设计时考虑了安全性，提供了许多工具来帮助防止多人游戏中的漏洞利用。

Mirage 是开源的。欢迎提交错误报告和反馈，你可以在 Github 上打开一个 issue 或加入 Discord。

快速浏览

// Server/Client events — listen from anywhere, no central manager needed
public class GameSetup : MonoBehaviour
{
    public NetworkServer Server;
    public NetworkClient Client;

    private void Awake()
    {
        Server.Authenticated.AddListener(OnPlayerJoined);
        Server.Disconnected.AddListener(OnPlayerLeft);
        Client.Authenticated.AddListener(OnConnected);
    }

    private void OnPlayerJoined(INetworkPlayer player) { /* spawn logic */ }
    private void OnPlayerLeft(INetworkPlayer player) { /* cleanup logic */ }
    private void OnConnected(INetworkPlayer player) { /* client ready */ }
}

// NetworkBehaviour — SyncVars, RPCs, and Identity events
public class PlayerCombat : NetworkBehaviour
{
    [SyncVar]
    public int health = 100;

    private void Awake()
    {
        Identity.OnStartServer.AddListener(OnStartServer);
    }

    private void OnStartServer() { /* server-side init */ }

    [ServerRpc]
    // Rate limit to block spam
    [RateLimit(Refill = 1, MaxTokens = 5, Penalty = 10)]
    public void CmdAttack(NetworkIdentity target)
    {
        // validate and apply damage
    }

    [ServerRpc]
    [RateLimit(Refill = 1, MaxTokens = 5, Penalty = 50)]
    // return values so client can await result to know if they were successful or not
    public UniTask<bool> CmdBuyItem(int itemId)
    {
        if (!HasEnoughGold(itemId))
            return UniTask.FromResult(false);

        AddItemToInventory(itemId);
        return UniTask.FromResult(true);
    }
}

安装

要安装 Mirage，请按照以下步骤操作：

1) Mirage 需要至少 Unity 2022 LTS。你可以通过 Unity 网站或 Unity Hub 安装 Unity 2022 LTS。

你也可以使用更新的版本，但强烈建议使用 LTS 版本，因为较新的版本可能包含漏洞、故障，甚至可能直接破坏游戏项目。
2) 创建一个新项目或打开现有项目。如果打开现有项目，强烈建议在安装 Mirage 之前进行备份。
4) 添加 OpenUPM 注册表。点击 Edit 菜单，然后选择 Project settings...，选择 Package Manager，并像这样添加一个作用域注册表：

名称: OpenUPM

网址: https://package.openupm.com

作用域：

• com.cysharp.unitask
• com.openupm
• com.miragenet
• com.miragenet.mirage

4) 关闭项目设置。
5) 通过点击 Window 菜单并选择 Package Manager 来打开包管理器。然后选择 Packages，My Registries，选择 Mirage 的最新版本并点击安装，如下所示：
6) 你可以随时返回包管理器卸载 Mirage 或升级它。

替代方法：通过 Git URL 安装

如果你希望直接从 GitHub 安装特定版本或哈希值，可以在 Packages/manifest.json 文件的 dependencies 部分添加以下行：

"com.miragenet.mirage": "https://github.com/MirageNet/Mirage.git?path=/Assets/Mirage#v156.2.4",

Migrate from Mirror

如果你已经有一个使用 Mirror 的项目，并且想将其迁移到 Mirage，建议查看我们的 迁移指南 以便顺利过渡。还请查看下面的标题，因为 Mirage 与其他网络库有一些主要区别。

与 Mirror 的比较

Mirage 是 Mirror 的一个硬分叉，增加了许多功能、性能改进和安全改进。

Mirage 的一些显著功能：

• 结构良好的代码库 — 系统间边界清晰，易于导航和理解
• 无静态状态 — 多个服务器/客户端实例可以在同一个 Unity 进程运行
• 严格的错误处理 — 无效调用会抛出异常，使错误立即显现，而不是静默破坏状态
• 网络行为可以在根对象或子对象上
• 服务器 RPC 可以 返回值
• 位打包 可轻松优化网络消息并减少带宽
• 通过属性进行速率限制和最大长度 验证
• 错误标记 用于跟踪行为异常的客户端及其产生的错误
• 版本定义
• 快速播放模式支持

Mirage 建立在基本的支柱之上：

• 干净、可读的代码库，遵循 C# 规范
• 没有单例或全局静态状态
• 高测试覆盖率

开发环境设置

如果你想为 Mirage 做出贡献，请按照以下步骤操作：

Linux 和 Mac

1) 确保已安装 git。在 Linux 上，通过你的包管理器安装。在 macOS 上，它包含在 Xcode 命令行工具中。
2) 克隆 Mirage 仓库：

    git clone https://github.com/MirageNet/Mirage.git

3) 在 Unity 2022.3 LTS 或更高版本中打开克隆的仓库。

窗口

1) 安装 git 或使用您首选的 git 客户端。
2) 以管理员身份，使用符号链接支持进行克隆：

    git clone -c core.symlinks=true https://github.com/MirageNet/Mirage.git

如果你不想使用管理员权限，[为你的账户添加符号链接支持](https://www.joshkel.com/2018/01/18/symlinks-in-windows/)。
如果你不启用符号链接，你将能够在 Mirage 上工作，但 Unity 将看不到示例。

3) 在 Unity 2022.3 LTS 或更高版本中打开并尽情享受！

传输与套接字

Mirage 支持多种数据传输方式：

• 原生 UDP 套接字（Windows 和 Linux 默认）并可回退到 C# UDP 套接字（macOS 及其他平台默认）
• Steam（通过 MirageSteamworks）
• Epic 在线服务（通过 EpicSocket）
• WebGL 客户端的 WebSocket（通过 SimpleWebSocket）

相关项目

• MirageStandalone — 在没有 Unity 的情况下运行 Mirage 服务器
• Mirage.Core — 核心序列化和网络功能，独立于框架
• Mirage.Godot — Godot 的 Mirage 网络功能

贡献

1. 请参阅上面的开发环境设置。
2. Fork 这个 Mirage 仓库。
3. 使用你新的 fork，创建你的功能分支：git checkout -b my-new-feature
4. 然后提交你的更改：git commit -am 'Add some feature'
5. 将其推送到分支：git push origin my-new-feature
6. 提交一个 pull 请求，并让团队审核你的工作。 :smiley:

团队将尽快审核，并给出批准、要求修改或详细说明拒绝的原因。

感谢使用 Mirage，我们希望看到你的项目取得成功！