# fantasy-game
**Repository Path**: bbzhengcheng/fantasy-game
## Basic Information
- **Project Name**: fantasy-game
- **Description**: testtesttesttesttesttesttesttesttesttesttesttesttesttesttesttesttesttesttesttest
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main2dnew
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-08-13
- **Last Updated**: 2026-09-27
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
[](LICENSE)
[](https://dotnet.microsoft.com/)
[](https://docs.microsoft.com/en-us/dotnet/csharp/)
[](https://unity.com/)
[](https://github.com/qq362946/Fantasy/stargazers)
**简体中文** | **[English](README.en.md)**
**[📖 官方文档](Docs/README.md)** | **[🚀 快速开始](Docs/README.md)** | **[💬 QQ 群: 569888673](http://qm.qq.com/cgi-bin/qm/qr?_wv=1027&k=yourqrcode)**
---
# ⭐ 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 使用指南](Docs/05-AI/01-FantasySkill.md)**
👉 **[AI Skill 安装说明与功能介绍](Skills/README.md)**
## 适用场景
- 🏰 **MMORPG** - 分布式架构、跨服通信、实体寻址系统
- ⚔️ **实时对战游戏** - KCP 低延迟协议、高性能 ECS 架构
- 🎲 **回合制/卡牌游戏** - 可靠的 TCP/WebSocket 通信、数据持久化
- 🌍 **开放世界游戏** - 场景管理、实体层级系统
- 🏪 **H5/小游戏** - WebSocket 协议支持、Unity WebGL 兼容
- 🎰 **高并发游戏** - 分布式部署、对象池优化
## 多协议支持
- 🔌 **TCP** - 稳定可靠，服务器间内网通信首选
- ⚡ **KCP** - 低延迟 UDP 可靠传输协议，适合实时对战游戏
- 🌍 **WebSocket** - 原生支持 H5/小游戏，Unity WebGL 一键发布
- 🌐 **HTTP** - RESTful API、Web 后台管理、GM 工具完美集成
## 核心优势
### 📡 网络通信
```csharp
// ❌ 传统框架需要 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 极致性能
```csharp
// 传统框架: 运行时反射扫描注册(慢 + 不支持 AOT)
// Assembly.GetTypes().Where(t => typeof(IMessageHandler).IsAssignableFrom(t))...
// Fantasy: 编译时自动生成注册代码(快 + AOT 友好)
// 无需任何手动注册,源生成器自动完成一切
public class C2G_LoginHandler : Message
{
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`
```csharp
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());
```
👉 **[服务发现使用指南](Docs/04-Advanced/NetworkDevelopment/11-ServiceDiscovery.md)**
### 🌉 Roaming 路由系统
```csharp
// 定义 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
{
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 根据消息类型自动转发到正确的服务器
- ✅ **透明的分布式** - 开发体验与单服务器一致
- ✅ **灵活的服务器扩展** - 轻松添加新的游戏服务器类型
### 🌐 跨服通信轻松实现
```csharp
// 服务器 A 发布跨服事件
await sphereEvent.PublishToRemoteSubscribers(new WorldBossDefeatedEvent
{
BossId = 1001,
KillerGuildId = 5201314
});
// 服务器 B/C/D... 自动接收并处理
// 跨服公告、跨服排行榜、跨服 PVP 轻松搞定
```
### 🎮 多协议支持,一套代码多场景
```csharp
// 同一个消息定义,支持 TCP/KCP/WebSocket/HTTP 全协议
// 无需修改任何代码,只需配置文件切换协议类型
var session = await NetworkHelper.Connect("127.0.0.1:20000", NetworkProtocolType.TCP);
// 或 NetworkProtocolType.KCP / WebSocket / HTTP
```
### 🚀 ECS 架构,开发效率拉满
```csharp
// 定义实体
public class Player : Entity
{
public string Name { get; set; }
public int Level { get; set; }
}
// 添加组件(组合式设计,灵活扩展)
player.AddComponent();
player.AddComponent();
player.AddComponent();
// 系统自动执行(源生成器自动注册,零配置)
public class PlayerAwakeSystem : AwakeSystem
{
protected override void Awake(Player self)
{
Log.Info($"玩家 {self.Name} 上线了!");
}
}
```
---
## 平台支持
| 平台 | 支持状态 | 说明 |
|------|-------|------------------|
| 🖥️ **Windows Server** | ✅ 完全支持 | 游戏服务器首选平台 |
| 🐧 **Linux Server** | ✅ 完全支持 | [Docker/Kubernetes 容器化部署](Docs/04-Advanced/14-Deployment.md) |
| 🍎 **macOS** | ✅ 完全支持 | 开发调试友好 |
| 🎮 **Unity (Win/Mac/iOS/Android)** | ✅ 完全支持 | 2022.3.62+ |
| 🌐 **Unity WebGL (H5)** | ✅ 完全支持 | WebSocket 协议 |
| 🎯 **Godot** | ❌ 暂未支持 | .NET 版本 Godot |
| 🖼️ **WinForms / WPF** | ❌ 暂未支持 | GM 工具、服务器监控面板 |
| 📟 **Console** | ❌ 暂未支持 | 独立游戏、机器人、压测工具 |
---
## 📋 环境要求
| 组件 | 版本要求 | 说明 |
|------|---------------------------|------|
| **.NET SDK** | 8.0+ | [下载地址](https://dotnet.microsoft.com/download) |
| **Unity** | 2022.3.62+ | 客户端开发（可选） |
| **IDE** | VS 2022 / Rider / VS Code | 推荐 Rider 或 VS 2022 |
| **MongoDB** | 4.0+ | 数据库（可选，使用内存模式可不装） |
---
## 🛠️ Fantasy CLI 脚手架工具
Fantasy CLI 是官方提供的项目脚手架和管理工具，帮助你快速创建和管理 Fantasy 项目。
### 安装
```bash
dotnet tool install -g Fantasy.Cli
```
**⚠️ macOS/Linux 用户注意事项**
在 macOS 或 Linux 上安装后，如果无法直接使用 `fantasy` 命令，需要将 .NET tools 路径添加到 PATH 环境变量：
**macOS (zsh - 默认 Shell):**
```bash
echo 'export PATH="$PATH:$HOME/.dotnet/tools"' >> ~/.zshrc
source ~/.zshrc
```
**macOS (bash):**
```bash
echo 'export PATH="$PATH:$HOME/.dotnet/tools"' >> ~/.bash_profile
source ~/.bash_profile
```
**Linux (bash):**
```bash
echo 'export PATH="$PATH:$HOME/.dotnet/tools"' >> ~/.bashrc
source ~/.bashrc
```
**验证安装:**
```bash
fantasy --version
```
### 快速使用
**创建新项目:**
```bash
fantasy init # 交互式创建项目
fantasy init -n MyGameServer # 使用项目名快速创建
```
**添加框架组件:**
```bash
fantasy add # 交互式选择组件
fantasy add -t protocolexporttool # 添加协议导出工具
fantasy add -t networkprotocol # 添加网络协议
fantasy add -t nlog # 添加 NLog 日志
```
更多详细信息，请查看 [Fantasy.Cli 文档](Fantasy.Packages/Fantasy.Cil/README.md)
---
## 💬 社区与支持
- **QQ 讨论群**: **569888673** （点击加群：[链接](http://qm.qq.com/cgi-bin/qm/qr?_wv=1027&k=yourqrcode)）
- **联系邮箱**: 362946@qq.com
- **GitHub Issues**: [提交问题](https://github.com/qq362946/Fantasy/issues)
- **官方网站**: [www.code-fantasy.com](https://www.code-fantasy.com/)
- **B站视频教程**: [空间主页](https://space.bilibili.com/382126312)
---
## 🙏 感谢所有为 Fantasy 做出贡献的开发者
[](https://github.com/qq362946/Fantasy/graphs/contributors)
---
## 🤝 优质开源项目推荐
- [ET Framework](https://github.com/egametang/ET) - Fantasy 的设计灵感来源,完善的分布式游戏服务器框架
- [TEngine](https://github.com/ALEXTANGXIAO/TEngine) - Unity框架解决方案,新手友好的全平台开发框架
- [Legends-Of-Heroes](https://github.com/FlameskyDexive/Legends-Of-Heroes) - LOL风格的球球大作战,基于ET框架的完整游戏项目
---
### 🎉 如果 Fantasy 对你有帮助，请给个 Star ⭐
### 让更多人发现这个项目！
**Built with ❤️ by Fantasy Team | Made for Game Developers**
[⬆ 回到顶部](#fantasy-framework)