# LockstepArcade-TEngine-Fantasy-Demo

**Repository Path**: M-QH/LockstepArcade-TEngine-Fantasy-Demo

## Basic Information

- **Project Name**: LockstepArcade-TEngine-Fantasy-Demo
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-17
- **Last Updated**: 2026-04-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Lockstep Arcade Fantasy Demo

<div align="center">

### 基于 TEngine + Fantasy + BattleCore 的服务端权威帧同步格斗技术 Demo

<p>
  <img src="https://img.shields.io/badge/Unity-2022.3.62f2-blue?style=flat-square" alt="Unity" />
  <img src="https://img.shields.io/badge/.NET-9.0-blueviolet?style=flat-square" alt=".NET" />
  <img src="https://img.shields.io/badge/Framework-TEngine-00a6a6?style=flat-square" alt="TEngine" />
  <img src="https://img.shields.io/badge/Server-Fantasy-4b7bec?style=flat-square" alt="Fantasy" />
  <img src="https://img.shields.io/badge/Transport-KCP-2d98da?style=flat-square" alt="KCP" />
  <img src="https://img.shields.io/badge/Simulation-Fix64-success?style=flat-square" alt="Fix64" />
  <img src="https://img.shields.io/badge/Status-Tech%20Demo-orange?style=flat-square" alt="Status" />
</p>

</div>

<div align="center">

### - **本项目是半成品，UI、格斗、网络系统都还不够完善，因为最近需要专注于其他项目，又不想这个 Demo 吃灰，就先开源此demo搏大家一笑。**
### - **本人没有帧同步和服务器开发经验，Demo 仅用于学习和技术验证，请谨慎使用和学习，以免被带入误区。**
### - **本项目有大量的 Vibe Coding，可能会有一些意想不到的 Bug，请谨慎使用。**
### - **后续可能会更新，后续更新不太可能。**

</div>

## 项目介绍

这是一个围绕“确定性仿真 + 服务端权威帧同步 + 客户端预测回滚”搭建的技术演示项目。

项目使用 Unity + TEngine 作为客户端壳层，Fantasy + KCP 作为服务端通信基础设施，并通过共享 `BattleCore` 的方式，让客户端与服务端运行同一套战斗规则代码，重点演示以下链路：

- 本地战斗与联机战斗共用同一套战斗核心
- 房间创建、入房、准备、开战的完整联机流程
- 客户端预测、权威帧对账、输入不一致回滚重演
- 基于定点数的确定性战斗仿真
- 回放录制与播放

这个仓库的目标不是商业成品模板，而是一个可以跑通、可阅读、可继续扩展的帧同步格斗 Demo。

## 文档快速预览

- [README](README.md)：项目概览、启动方式、核心结构。
- [技术 Demo 架构说明](docs/architecture/TECH_DEMO_ARCHITECTURE.md)：客户端壳层、共享 BattleCore、服务端权威层的完整说明。

## 为什么做这个 Demo

1. 不只演示本地 30 FPS 逻辑帧驱动，还把房间、联机开战、权威广播链路接了起来。
2. 不只做“状态同步”，而是明确采用输入驱动的帧同步思路，适合格斗游戏场景。
3. BattleCore 通过源码共享的方式同时服务客户端和服务端，方便验证规则一致性。
4. 项目结构尽量贴近真实工程拆分，适合作为学习 TEngine + Fantasy 双端协作的样例。

## 当前已实现能力

- `30 FPS` 确定性逻辑帧推进
- `60 FPS` 渲染插值显示
- `Fix64 / FixVector2 / FixVector3` 定点数仿真
- 本地双人战斗
- 登录、建房、入房、准备、开战
- 服务端权威帧推进与帧广播
- 客户端预测、回滚与状态哈希校验
- 轻攻击、重攻击、受击、防御、KO
- 回放录制与本地播放

## 快速启动

### 环境要求

- Windows
- Unity `2022.3.62f2`
- .NET SDK `9.x`
- 服务端默认监听：`127.0.0.1:20000`

### 1. 服务端相关

服务端部分这里不展开细说，这里的文档布局和使用方法与官方教程类似，建议直接参考 Fantasy 官方教程：

- [Fantasy 官方教程：创建您的第一个应用](https://www.code-fantasy.com/top/creating-your-app/)


### 2. 打开客户端

- 使用 Unity `2022.3.62f2` 打开 [Client/Unity](Client/Unity)
- 进入 Play Mode

### 3. 从首页选择入口

- `Home -> StartLocalBattle`
  直接进入本地双人战斗
- `Home -> SetRoom`
  登录、建房或入房、准备、开始联机战斗
- `Home -> ReplayLocalRecord`
  播放最近一次本地录制

## 推荐验证流程

### 本地战斗验证

- 从 `Home -> StartLocalBattle` 进入
- 验证移动、跳跃、下蹲、防御、轻重攻击、受击、KO、回放

### 单人联网联调

- 启动服务端
- 进入 `Home -> SetRoom`
- 使用任意账号密码登录
- 创建房间
- 等待第二名玩家入房并双方 `Ready` 后开始战斗

### 双客户端联机验证

- 启动一个服务端
- 启动两个客户端
- 使用不同账号登录
- 一端建房，另一端入房
- 双方准备后开始战斗

## 项目结构概览

```text
.
├── BattleCore                                  # 共享战斗核心工程，服务端引用同一套战斗源码
├── Client
│   └── Unity
│       └── Assets/GameScripts/HotFix/GameLogic
│           ├── Battle                          # 帧同步、输入、仿真、渲染、回放
│           ├── Deterministic                   # Fix64 / FixVector2 / FixVector3 / FixMath
│           ├── NetWork                         # Fantasy 客户端接入、协议与房间流程
│           ├── Procedure                       # Home / Lobby / Battle 流程切换
│           └── UI                              # 首页、Lobby、战斗 HUD、结算等界面
├── Config                                      # 配置表资源
├── Server
│   ├── Main                                    # 服务端入口
│   ├── Entity                                  # 共享数据结构、协议、实体组件
│   └── Hotfix                                  # 房间、战斗、消息处理逻辑
├── Tools                                       # 启服脚本、协议导出工具等
└── docs                                        # 架构说明文档
```

## 核心技术链路

```mermaid
flowchart LR
    A["Home / Lobby UI"] --> B["FantasyManager"]
    B --> C["Fantasy Session (KCP)"]
    C --> D["Server Handler"]
    D --> E["RoomManageComponentSystem"]
    E --> F["BattleSession"]
    F --> G["SimulationWorld (Authoritative)"]
    E --> H["G2C_FrameCommand"]
    H --> I["FrameRunner"]
    I --> J["Predict / Rollback / Hash Check"]
    J --> K["RenderInterpolator + BattleCoreUI"]
```

客户端负责 UI、流程、输入采样、预测与回滚触发；服务端负责房间、权威帧推进、输入接收窗口校验与帧广播；战斗规则则由客户端与服务端共享同一套 `BattleCore` 源码实现。

## BattleCore 设计重点

- `FrameRunner` 负责逻辑帧驱动、网络模式配置、回滚与重演
- `SimulationWorld` 负责组件管理、系统执行、快照保存、状态哈希
- 当前系统顺序为：
  - `InputSystem`
  - `JumpSystem`
  - `MovementSystem`
  - `CollisionSystem`
  - `StateSystem`
  - `CombatSystem`
- `RenderInterpolator` 负责 30 FPS 逻辑帧到 60 FPS 渲染的插值显示
- `ReplaySystem` 负责战斗录制与回放

## 确定性规则

帧同步战斗逻辑必须保持确定性，仿真层请始终遵守以下约束：

- 不要在仿真逻辑中使用 `float` / `double`
- 不要在仿真逻辑中直接使用 `UnityEngine.Vector3`
- 不要在仿真逻辑中依赖 `Time.deltaTime`
- 所有位置、速度、碰撞、伤害、状态持续时间统一使用定点数
- 客户端和服务端的战斗规则实现必须保持一致

## 协议与联机流程

当前已经接通的主要联机消息包括：

- `C2G_LoginRequest` / `G2C_LoginResponse`
- `C2G_CreateRoomRequest` / `G2C_CreateRoomResponse`
- `C2G_JoinRoomRequest` / `G2C_JoinRoomResponse`
- `C2G_LeaveRoomRequest` / `G2C_LeaveRoomResponse`
- `C2G_SetReadyRequest` / `G2C_SetReadyResponse`
- `C2G_StartBattleRequest` / `G2C_StartBattleResponse`
- `G2C_RoomSnapshot`
- `G2C_StartFrameSync`
- `C2G_NextFrameCommand`
- `G2C_FrameCommand`

联机主流程为：

`登录 -> 房间同步 -> Ready -> StartFrameSync -> 输入上传 -> 权威帧广播 -> 预测对账 -> 回滚重演`

## 依赖与版本

- [TEngine](https://github.com/ALEXTANGXIAO/TEngine) `6.0.0`：Unity 客户端框架
- [Fantasy.Unity](https://github.com/qq362946/Fantasy) `2025.2.1423`：客户端网络接入
- `Fantasy-Net`：服务端网络与实体框架，当前在 `Server/Entity/Entity.csproj` 中使用浮动版本引用
- [HybridCLR](https://github.com/focus-creative-games/hybridclr) `8.11.0`：热更新方案
- [YooAsset](https://github.com/tuyoogame/YooAsset) `2.3.17`：资源管理
- [UniTask](https://github.com/Cysharp/UniTask) `2.5.10`：异步任务方案
- `Newtonsoft.Json` `3.2.1`：Unity 侧 JSON 支持
- Luban：配置表生成工具，本仓库未锁定工具版本号

## 后续方向

- [ ] 完善UI：包括房间选择、设置、结算、对战中。
- [ ] 完善动画：下蹲动画、下蹲攻击动画等还不够全面。
- [ ] 完善网络功能:包括完善的房间系统、断线重连、断线等待、反作弊、下发录像等等。
- [ ] 完善格斗逻辑:立回、硬直、手感等问题。
- [ ] 完善一些基本逻辑：包括多语言、画面、设置、按键设置、手柄支持等。
- [ ] 继续完善客户端预测与全链路回滚体验

## 开源资源与致谢

- 定点数实现基于 `FixMath.NET` 相关代码与命名空间适配，用于客户端与服务端共享确定性仿真能力
- 帧动画资源使用了 Pixel Moon Studio 的素材：
  [Male Realistic Pixel Art Template Sprite Pack](https://pixel-moon-studio.itch.io/male-realistic-pixel-art-template-sprite-pack)
- 感谢 TEngine、Fantasy、HybridCLR、YooAsset、UniTask 等开源项目提供的基础能力