---

⭐ Fantasy 是什么？

Fantasy 是一个零反射、高性能的 C# 游戏服务器框架，专为大型多人在线游戏打造。

✨ 核心特点

⚡ 零反射架构 · 🚀 Native AOT 支持 · 🧭 Control Center 与服务发现
🌐 多协议支持 · 🔥 分布式架构 · 🎮 ECS 设计 · 🤖 AI 赋能开发

🤖 AI 赋能开发

Fantasy 已提供专用 fantasy-net Skill，可配合 Claude、Codex、OpenCode、OpenClaw 等 AI Agent 使用。

它可以帮助你：

• 学习 Fantasy 框架与核心机制
• 编写 Entity / Component / System、协议、Handler、配置和数据库代码
• 设计 Roaming、Address、SphereEvent、HTTP、Unity 接入等功能
• 审查 Fantasy 项目代码是否符合框架规范，快速定位问题

这让 Fantasy 不只是“可以配合 AI 使用”，而是已经具备面向 AI 的知识组织和开发支持能力，显著降低上手门槛，也非常适合 Vibe Coding。

你可以直接这样问 AI：

• 帮我在 Fantasy 里创建一个 Player 实体和对应的 AwakeSystem
• 帮我写一个 EventAwaiter 版本的玩家确认流程
• 帮我检查这段 Roaming 代码有没有问题，是否符合 Fantasy 规范
• 帮我写一个包含 Gate、Map、MapControl、MongoDB 的 Fantasy.config

👉 AI 赋能与 Skill 使用指南 👉 AI Skill 安装说明与功能介绍

适用场景

• 🏰 MMORPG - 分布式架构、跨服通信、实体寻址系统
• ⚔️ 实时对战游戏 - KCP 低延迟协议、高性能 ECS 架构
• 🎲 回合制/卡牌游戏 - 可靠的 TCP/WebSocket 通信、数据持久化
• 🌍 开放世界游戏 - 场景管理、实体层级系统
• 🏪 H5/小游戏 - WebSocket 协议支持、Unity WebGL 兼容
• 🎰 高并发游戏 - 分布式部署、对象池优化

多协议支持

• 🔌 TCP - 稳定可靠，服务器间内网通信首选
• ⚡ KCP - 低延迟 UDP 可靠传输协议，适合实时对战游戏
• 🌍 WebSocket - 原生支持 H5/小游戏，Unity WebGL 一键发布
• 🌐 HTTP - RESTful API、Web 后台管理、GM 工具完美集成

核心优势

📡 网络通信

// ❌ 传统框架需要 50+ 行代码
var message = new C2G_LoginRequest();
message.Account = "player123";
message.Password = "password";
var bytes = ProtoBuf.Serialize(message);
var response = await session.Call(opCode, bytes);
// ... 还要手动处理回调、超时、错误处理

// ✅ Fantasy 只需 1 行代码(自动生成扩展方法)
var response = await session.C2G_Login("player123", "password");

⚡ 零反射 + Native AOT 极致性能

// 传统框架: 运行时反射扫描注册(慢 + 不支持 AOT)
// Assembly.GetTypes().Where(t => typeof(IMessageHandler).IsAssignableFrom(t))...

// Fantasy: 编译时自动生成注册代码(快 + AOT 友好)
// 无需任何手动注册,源生成器自动完成一切
public class C2G_LoginHandler : Message<Session, C2G_Login, G2C_Login>
{
    protected override async FTask Run(Session session, C2G_Login request, G2C_Login response)
    {
        // 框架自动路由到这里,零反射开销
        response.Token = await AuthService.Login(request.Account);
    }
}

🧭 内置 Control Center 与服务发现

告别固定服务器列表和按数量取模。Fantasy 提供开箱即用的管理后台与高性能服务发现，让服务器拓扑可以随业务动态扩缩容。

• ✅ 可视化拓扑管理 - 统一管理 Machine、Process、World、Database 和 Scene，并持久化到本地
• ✅ 自动服务生命周期 - Scene 启动后自动注册，批量心跳续租，正常关闭主动下线，异常退出自动过期
• ✅ 多游戏环境隔离 - 原生支持 Namespace、WorldGroup 和 World 范围查询
• ✅ 稳定负载路由 - 支持随机选择与 Rendezvous Hash，增减节点时只迁移部分请求
• ✅ 高性能调用链 - 热路径读取本地缓存，发现到的 Address 可直接用于 Scene.Send 和 Scene.Call

using NetServiceDiscovery = Fantasy.ServiceDiscovery;

var mapAddress = await NetServiceDiscovery.DiscoverAddressByHashAsync(
    SceneType.Map,
    routingKey: accountId,
    worldId: worldId);

if (mapAddress == 0)
    throw new InvalidOperationException("No online Map scene was discovered.");

var response = await scene.Call(mapAddress, new G2A_TestRequest());

👉 服务发现使用指南

🌉 Roaming 路由系统

// 定义 Roaming 消息(.proto 文件)
message C2M_EnterMap // IRoamingRequest
{
    int32 MapId = 1;
}

message M2C_EnterMap // IRoamingResponse
{
    int32 ErrorCode = 1;
    int64 SceneId = 2;
}

// Gate 服务器自动转发到目标 Map 服务器,无需任何配置
// 客户端只需连接 Gate,剩下的交给框架处理
var response = await session.C2M_EnterMap(1001);

// 服务端在 Map 服务器处理(不是 Gate 服务器!)
public class C2M_EnterMapHandler : Roaming<Session, C2M_EnterMap, M2C_EnterMap>
{
    protected override async FTask Run(Session session, C2M_EnterMap request, M2C_EnterMap response)
    {
        // 这里运行在 Map 服务器上,Gate 已自动转发
        var scene = await CreateMapScene(request.MapId);
        response.SceneId = scene.Id;
        response.ErrorCode = 0;
    }
}

Roaming 核心价值

• ✅ 自动服务器路由 - 客户端无需知道目标服务器地址
• ✅ 零配置转发 - Gate 根据消息类型自动转发到正确的服务器
• ✅ 透明的分布式 - 开发体验与单服务器一致
• ✅ 灵活的服务器扩展 - 轻松添加新的游戏服务器类型

🌐 跨服通信轻松实现

// 服务器 A 发布跨服事件
await sphereEvent.PublishToRemoteSubscribers(new WorldBossDefeatedEvent
{
    BossId = 1001,
    KillerGuildId = 5201314
});

// 服务器 B/C/D... 自动接收并处理
// 跨服公告、跨服排行榜、跨服 PVP 轻松搞定

🎮 多协议支持,一套代码多场景

// 同一个消息定义,支持 TCP/KCP/WebSocket/HTTP 全协议
// 无需修改任何代码,只需配置文件切换协议类型
var session = await NetworkHelper.Connect("127.0.0.1:20000", NetworkProtocolType.TCP);
// 或 NetworkProtocolType.KCP / WebSocket / HTTP

🚀 ECS 架构,开发效率拉满

// 定义实体
public class Player : Entity
{
    public string Name { get; set; }
    public int Level { get; set; }
}

// 添加组件(组合式设计,灵活扩展)
player.AddComponent<BagComponent>();
player.AddComponent<EquipmentComponent>();
player.AddComponent<SkillComponent>();

// 系统自动执行(源生成器自动注册,零配置)
public class PlayerAwakeSystem : AwakeSystem<Player>
{
    protected override void Awake(Player self)
    {
        Log.Info($"玩家 {self.Name} 上线了!");
    }
}

---

平台支持

---

📋 环境要求

---

🛠️ Fantasy CLI 脚手架工具

Fantasy CLI 是官方提供的项目脚手架和管理工具，帮助你快速创建和管理 Fantasy 项目。

安装

dotnet tool install -g Fantasy.Cli

⚠️ macOS/Linux 用户注意事项

在 macOS 或 Linux 上安装后，如果无法直接使用 fantasy 命令，需要将 .NET tools 路径添加到 PATH 环境变量：

macOS (zsh - 默认 Shell):

echo 'export PATH="$PATH:$HOME/.dotnet/tools"' >> ~/.zshrc
source ~/.zshrc

macOS (bash):

echo 'export PATH="$PATH:$HOME/.dotnet/tools"' >> ~/.bash_profile
source ~/.bash_profile

Linux (bash):

echo 'export PATH="$PATH:$HOME/.dotnet/tools"' >> ~/.bashrc
source ~/.bashrc

验证安装:

fantasy --version

快速使用

创建新项目:

fantasy init                    # 交互式创建项目
fantasy init -n MyGameServer    # 使用项目名快速创建

添加框架组件:

fantasy add                     # 交互式选择组件
fantasy add -t protocolexporttool  # 添加协议导出工具
fantasy add -t networkprotocol     # 添加网络协议
fantasy add -t nlog                # 添加 NLog 日志

更多详细信息，请查看 Fantasy.Cli 文档

---

💬 社区与支持

• QQ 讨论群: 569888673 （点击加群：链接）
• 联系邮箱: [email protected]
• GitHub Issues: 提交问题
• 官方网站: www.code-fantasy.com
• B站视频教程: 空间主页

---

🙏 感谢所有为 Fantasy 做出贡献的开发者

---

🤝 优质开源项目推荐

• ET Framework - Fantasy 的设计灵感来源,完善的分布式游戏服务器框架
• TEngine - Unity框架解决方案,新手友好的全平台开发框架
• Legends-Of-Heroes - LOL风格的球球大作战,基于ET框架的完整游戏项目

---