# GameDesigner

**Repository Path**: xxmfl/GameDesigner

## Basic Information

- **Project Name**: GameDesigner
- **Description**: Verxel(原GDNet)双端Rpc网络框架用于Unity3D，窗体程序和控制台项目开发, 高效稳定, 高性能高并发, 各种协议一键切换: gcp, udx, kcp, tcp, web, http 包含各种模块, AOI模块, Recast寻路模块, GameCore客户端框架等等
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 165
- **Created**: 2026-06-20
- **Last Updated**: 2026-06-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GameDesigner - 游戏开发框架

<div align="center">

![Unity](https://img.shields.io/badge/Unity-2021.3+-black?style=for-the-badge&logo=unity)
![C#](https://img.shields.io/badge/C%23-9.0+-blue?style=for-the-badge&logo=c-sharp)
![.NET](https://img.shields.io/badge/.NET-8.0-512BD4?style=for-the-badge&logo=dotnet)
![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)

**专为游戏设计的前后端网络框架与可视化状态机**

</div>

---

## 项目简介

GameDesigner 是一个面向 Unity 引擎的游戏开发框架，核心提供**前后端网络通信**和**可视化动作状态机**两大能力。框架采用模块化设计，各模块可独立使用也可组合部署，同时提供 .NET Framework 4.8（Unity 端）和 .NET 8.0（独立服务器端）双构建目标。

**作者**: 冷月 | **协议**: MIT

---

## 架构概览

```
GameDesigner/
├── Core/                    # 基础层：序列化、RPC、SyncVar、线程安全容器、软浮点
├── Network/                 # 网络层：Client/Server、多传输协议、适配器模式
├── StateMachine~/           # 可视化状态机：图表编辑器、行为组件、动画集成
├── ActorSystem~/            # 角色系统：Actor/Skill/Buff/Property
├── Entities~/               # ECS 架构：Entity/Component/World
├── AOI~/                    # 兴趣区域：九宫格空间分区
├── MVC~/                    # MVC 框架：ViewBind 可视化绑定
├── NetworkComponent~/       # Unity 网络组件：NetworkObject/Transform/Animator
├── GameCore~/               # 游戏基础设施：UI/资源/场景/音频/事件/对象池
├── NonLockStep~/            # 非锁步同步：确定性物理、回滚、BEPUphysics
├── Distributed~/            # 分布式：一致性哈希、负载均衡、唯一ID
├── Recast~/                 # 寻路：Recast/Detour 封装
├── Table/                   # 配置表：Excel→代码、JSON/二进制序列化
├── Serialize/               # JSON 序列化（内嵌 Newtonsoft.Json）
├── Helper/                  # 工具集：加密、压缩、MySQL、代码生成
├── Extensions/              # 扩展方法：Client/Server/Unity/UniTask
├── Editor/                  # 编辑器工具：模块导入、序列化构建、属性绘制
├── UniTask/                 # 零分配 async/await（内嵌）
├── K4os.Hash.xxHash/        # xxHash32/64 快速哈希（内嵌）
├── SoftFloat/               # 软浮点 sfloat/bigfloat（确定性跨平台）
└── Example~/                # 示例项目
```

---

## 模块详解

### 1. Core - 核心基础层

框架的底层基础设施，所有其他模块都依赖于此。

**主要功能：**

- **二进制序列化** (`BinarySerialize`): 高性能二进制序列化器，支持 IL2CPP 友好模式，可用于网络传输和本地存储
- **RPC 系统** (`Net.Share`): 基于 `[Rpc]` 特性的远程过程调用，支持多种路由模式（EntityRpc、Scene、Notice、Local 等）
- **SyncVariable 同步变量**: `SyncVariable<T>` 泛型同步包装器，通过脏标记自动检测变更并同步，支持 `OnValueChanged` 回调
- **线程安全容器** (`Net.System`): 提供 `FastList`、`HashSetEx`、`QueueSafe`、`Segment` 等高性能线程安全数据结构
- **缓冲池** (`BufferPool`/`Segment`): 字节缓冲池与分片管理，减少 GC 压力
- **定时器系统** (`TimerManager`/`TimerSchedule`): 高精度定时器调度
- **软浮点** (`SoftFloat`): `sfloat` (IEEE 754 binary32) 和 `bigfloat` 的纯软件实现，保证跨平台确定性

**使用示例：**

```csharp
using Net.Share;

public class PlayerData
{
    // SyncVariable 泛型同步变量，值变更自动标记脏并触发回调
    public SyncVariable<int> Health = new SyncVariable<int>(100, OnHealthChanged);
    public SyncVariable<float> Speed = new SyncVariable<float>(5f);
    public SyncVariable<string> Name = new SyncVariable<string>("Player");

    private static void OnHealthChanged(int newValue)
    {
        Debug.Log($"血量变化: {newValue}");
    }

    // Rpc 特性标记远程方法，支持字节码/哈希/字符串三种路由标识
    [Rpc(100)]
    public void Attack(int targetId, float damage)
    {
        // 该函数可被远程调用
    }
}
```

---

### 2. Network - 网络通信层

完整的前后端网络通信框架，支持多种传输协议和灵活的可插拔架构。

**主要功能：**

- **服务端** (`Net.Server.ServerBase`): 抽象服务器基类，通过 `ISerializeAdapter`、`IPackageAdapter`、`IRpcAdapter`、`IRpcModelFactory` 四组适配器接口实现完全可定制的网络栈
- **客户端** (`Net.Client.Client`): 抽象客户端基类，提供 `OnConnected`、`OnConnectFailed`、`OnReconnect`、`OnDisconnect` 等完整的事件体系，内置断线重连和排队机制
- **客户端对等体** (`Net.Server.ClientPeer`): 服务端持有的玩家连接对象，继承 `ClientUnitBase`，管理单连接的收发、心跳和线程分配
- **场景管理** (`Net.Server.SceneBase<Client>`): 服务端场景/房间，容纳玩家集合，支持帧同步操作分发和线程组迁移
- **多传输协议**: 内置 Gcp / Kcp / Udx / WebSocket 四种传输层实现，位于 `Network/Gcp~/`、`Network/Kcp~/`、`Network/Udx~/`、`Network/Web~/`
- **网络命令** (`Net.Share.NetCmd`): 定义全部内置协议命令码（心跳、RPC、同步、排队等），用户自定义命令从 100 开始
- **流量统计** (`NetworkTrafficStatistics`): 实时收发字节数和数据包统计

**使用示例：**

```csharp
using Net.Server;
using Net.Client;
using Net.Share;

// --- 定义 RPC 方法 ---
public class GameRpc
{
    [Rpc(100)]
    public void PlayerMove(long playerId, float x, float y, float z) { }

    [Rpc(101)]
    public void PlayerAttack(long playerId, int skillId) { }
}

// --- 服务端 ---
public class GameServer : ServerBase
{
    protected override void OnStart()
    {
        // 可替换适配器
        SerializeAdapter = new BinarySerializeAdapter();
        PackageAdapter = new PackageAdapter();
        RpcAdapter = new NormalRpcAdapter { Mode = AdapterMode.Server };
    }

    protected override void OnClientConnected(ClientPeer client)
    {
        Debug.Log($"玩家连接: {client.UserId}");
    }
}

// --- 客户端 ---
public class GameClient : Client
{
    public GameClient()
    {
        OnConnected += () => Debug.Log("连接成功");
        OnConnectFailed += () => Debug.Log("连接失败");
        OnReconnect += () => Debug.Log("重连成功");
        OnDisconnect += () => Debug.Log("断开连接");
    }
}
```

---

### 3. StateMachine - 可视化状态机

Unity 编辑器内完整的可视化状态机系统，支持动画状态机、子状态机、行为组件等。

**主要功能：**

- **可视化编辑器** (`StateMachineWindow`/`GraphEditor`): 在 Unity Editor 中拖拽创建状态节点和连线
- **状态** (`GameDesigner.State`): 密封类，包含 `transitions` 过渡数组、`behaviours` 行为数组、`actionSystem` 动作系统开关
- **过渡** (`GameDesigner.Transition`): 状态之间的连线，支持 `exitTime` 定时过渡和 `ScriptControl` 脚本控制模式
- **行为组件** (`BehaviourBase`): 类似 Unity Component 的附加机制，`State.AddComponent<T>()` 动态添加行为
- **动画模式** (`AnimationMode`): 支持 Animation / Animator / MeshAnimator / Timeline / Time / None 六种模式
- **播放模式** (`AnimPlayMode`): Random（随机）、Sequence（顺序）、Code（代码控制）
- **状态层** (`IStateLayer`): 多层状态机支持
- **状态类型** (`StateType`): None / SubStateMachine / Parent，支持嵌套子状态机
- **软浮点支持**: 定义 `ENABLE_SFLOAT` 后过渡时间使用 `sfloat` 保证确定性

**使用示例：**

```csharp
using GameDesigner;

public class PlayerStateMachine : StateMachineView
{
    private void Start()
    {
        // 获取状态机控制器
        var sm = Controller.GetStateMachine(0);

        // 获取默认状态的过渡，添加脚本控制行为
        var defaultState = sm.DefaultState;
        defaultState.AddComponent<OnStartBehaviour>();

        // 通过代码切换状态
        sm.PerformTransition(sm.CurrState.transitions[0]);
    }
}

// 自定义行为组件
public class OnStartBehaviour : BehaviourBase
{
    public override void OnEnter()
    {
        Debug.Log($"进入状态: {State.Name}");
    }

    public override void OnUpdate()
    {
        // 每帧更新逻辑
    }

    public override void OnExit()
    {
        Debug.Log($"离开状态: {State.Name}");
    }
}
```

---

### 4. ActorSystem - 角色系统

面向 RPG 类型游戏的角色管理框架，定义 Actor / Skill / Buff / Property 四层抽象。

**主要功能：**

- **角色基类** (`ActorSystem.ActorBase`): 继承 `Net.Entities.Component`，可融入 ECS 架构，持有 `Commands` 字典路由操作指令，实现 `IGridObject` 接口与 AOI 系统联动
- **泛型角色** (`ActorBase<ACTOR, PROPERTY, SKILL, BUFF>`): 携带属性/技能/Buff 的完整角色，自动遍历更新技能冷却和 Buff 生命周期
- **技能** (`ActorSystem.SkillBase`): 管理冷却时间 (`CooldownTime`/`CurrentCooldownTime`)，`UseSkill()` 检查冷却并触发 `OnUseSkill()` 虚方法
- **Buff** (`ActorSystem.BuffBase`): 生命周期回调 `OnStart()` → `OnUpdate()` → `OnEnd()`，`OnTrigger()` 用于 DOT 类效果的克隆触发
- **属性** (`ActorSystem.PropertyBase`): 最小化基类，提供 `IsDeath` 判定，由用户扩展具体属性

**使用示例：**

```csharp
using ActorSystem;

// 自定义属性
public class HeroProperty : PropertyBase
{
    public int Health = 100;
    public int MaxHealth = 100;
    public int Mana = 50;
    public int Attack = 10;

    public override bool IsDeath => Health <= 0;
}

// 自定义技能
public class FireballSkill : SkillBase<Hero, HeroProperty, FireballSkill, HeroBuff>
{
    public override void OnUseSkill()
    {
        // Self 是泛型约束提供的当前角色引用
        Self.Property.Mana -= 10;
        Debug.Log("释放火球术");
    }
}

// 自定义 Buff
public class PoisonBuff : BuffBase<Hero>
{
    private float tickTimer;

    public override void OnStart()
    {
        Debug.Log($"{Target.Name} 中毒");
    }

    public override bool OnUpdate()
    {
        tickTimer += Time.deltaTime;
        if (tickTimer >= 1f)
        {
            tickTimer = 0f;
            Target.Property.Health -= 5;
        }
        return true; // 返回 true 持续生效
    }

    public override void OnEnd()
    {
        Debug.Log($"{Target.Name} 中毒效果结束");
    }
}

// 自定义角色
public class Hero : ActorBase<Hero, HeroProperty, FireballSkill, HeroBuff>
{
    public override void UseSkill(int index)
    {
        if (index < Skills.Count)
            Skills[index].UseSkill();
    }
}
```

---

### 5. Entities - ECS 实体组件系统

不依赖 Unity 的纯 C# ECS 架构，可用于服务端逻辑。

**主要功能：**

- **世界** (`Net.Entities.World`): 实体容器，通过 `Init()` 自动扫描 `[RuntimeInitializeOnLoadMethod]` 特性完成初始化，管理根实体和定时事件
- **实体** (`Net.Entities.Entity`): 密封类，API 设计模仿 `GameObject`（`gameObject` 属性指向自身、`active` 激活开关），支持父子层级 (`Parent`/`Childs`)，组件通过 `FastList<Component>` 存储
- **组件** (`Net.Entities.Component`): 基类，持有 `Entity` 反向引用，提供 `GetComponent<T>()`/`GetComponentInChildren<T>()` 等 Unity 风格查询方法

**使用示例：**

```csharp
using Net.Entities;

public class MyWorld : World
{
    public override void OnInit(params object[] args)
    {
        var entity = new Entity { active = true };
        AddEntity(entity);

        var comp = entity.AddComponent<MyComponent>();
    }
}

public class MyComponent : Component
{
    public void DoSomething()
    {
        // 通过 Entity 访问同实体上的其他组件
        var other = GetComponent<OtherComponent>();
    }
}
```

---

### 6. AOI - 兴趣区域

九宫格空间分区系统，用于优化大型多人在线场景的网络同步。

**主要功能：**

- **网格世界** (`Net.AOI.GridWorld`): 将世界划分为矩形网格，`GridType.Horizontal`（3D 游戏）/ `GridType.Vertical`（2D 游戏）
- **网格** (`Grid`): 单个网格单元，持有其中的对象列表
- **Unity 组件** (`Net.Component.AOIObject`): MonoBehaviour，`Start()` 自动注册到 `AOIManager.I.world`，支持 `OnMainRoleEnter`/`OnMainRoleExit` UnityEvent
- **接口** (`IGridObject`): `Identity`、`Position`、`Grid`、`MainRole`，由 `ActorBase` 和 `AOIObject` 实现
- **回调**: `OnEnter(IGridObject)` / `OnExit(IGridObject)` / `OnEnterGrid(Grid)` / `OnLeaveGrid(Grid)`

**使用示例：**

```csharp
using Net.AOI;
using Net.Component;
using UnityEngine;

public class GameAOISetup : MonoBehaviour
{
    public int gridWidth = 10;
    public int gridHeight = 10;
    public Vector2 worldSize = new Vector2(1000, 1000);

    private void Awake()
    {
        // 初始化九宫格世界
        var world = new GridWorld();
        world.Init(Vector2.zero, new Vector2(gridWidth, gridHeight), worldSize);
        AOIManager.I.world = world;
    }
}

// 挂载 AOIObject 组件的 GameObject 会自动注册到网格系统
// 实现 IGridObject 的自定义对象
public class Monster : ActorBase
{
    public override void OnEnter(IGridObject gridObject)
    {
        if (gridObject.MainRole)
        {
            // 玩家进入视野，开始同步该怪物
            Debug.Log("玩家进入视野，激活怪物");
        }
    }

    public override void OnExit(IGridObject gridObject)
    {
        if (gridObject.MainRole)
        {
            // 玩家离开视野，停止同步
            Debug.Log("玩家离开视野，休眠怪物");
        }
    }
}
```

---

### 7. MVC - 模型视图控制器

Unity 编辑器可视化数据绑定框架。

**主要功能：**

- **ViewBind** (`MVC.ViewBind`): MonoBehaviour，包含 `List<Field>` 列表，每个 Field 将字符串名称关联到 Unity Object 引用，支持运行时 `To<T>()` 类型转换获取
- **可视化编辑器** (`ViewBindEditor`): Inspector 面板中拖拽绑定 UI 控件到字段
- **AppContext**: 应用上下文，协调 Model/View/Controller

**使用示例：**

```csharp
using MVC;
using UnityEngine;
using UnityEngine.UI;

public class LoginView : ViewBind
{
    private void Start()
    {
        // 通过名称获取绑定的 UI 控件
        var usernameInput = fields.Find(f => f.name == "UsernameInput").To<InputField>();
        var passwordInput = fields.Find(f => f.name == "PasswordInput").To<InputField>();
        var loginBtn = fields.Find(f => f.name == "LoginBtn").To<Button>();

        loginBtn.onClick.AddListener(() =>
        {
            Debug.Log($"登录: {usernameInput.text}");
        });
    }
}
```

---

### 8. NetworkComponent - Unity 网络组件

Unity 端网络同步组件，自动处理 Transform、Animator 等的网络同步。

**主要功能：**

- **NetworkObject** (`Net.UnityComponent.NetworkObject`): 网络身份根组件，`[DisallowMultipleComponent]`，管理 `Identity`、`IsLocal`、`prefabHash`，持有所有 `NetworkBehaviour` 子组件和 `syncVarInfos` 字典
- **NetworkBehaviour** (`Net.UnityComponent.NetworkBehaviour`): 抽象基类，`[DefaultExecutionOrder(1000)]`，通过 `netObj` 属性访问所属 NetworkObject
- **NetworkTransform** (`Net.UnityComponent.NetworkTransform`): 继承 `NetworkTransformBase`，自动同步 Transform 的位置/旋转/缩放
- **NetworkAnimator** (`BuildComponent.NetworkAnimator`): 自动生成的组件，检测 Animator 173 个字段的变更并通过 `AddOperation` 发送同步指令
- **NetworkSceneManager**: 场景加载/卸载的网络同步

**使用示例：**

```csharp
using Net.UnityComponent;
using UnityEngine;

public class PlayerNetworkSetup : NetworkBehaviour
{
    public GameObject playerPrefab;

    public override void Start()
    {
        base.Start(); // 调用 Init()

        if (IsLocal)
        {
            // 本地玩家逻辑
            Camera.main.transform.SetParent(transform);
        }
    }

    // 通过 SyncVariable 同步玩家属性
    public SyncVariable<int> Score = new SyncVariable<int>();
}
```

---

### 9. GameCore - 游戏基础设施

游戏运行时的通用系统集合，通过 `GameCore.Global` 单例统一访问。

**主要功能：**

- **Global** (`GameCore.Global`): 继承 `SingletonMono<Global>` 的服务定位器，`[DefaultExecutionOrder(-50)]`，通过静态属性（`Global.UI`、`Global.Audio`、`Global.Event` 等）暴露所有子系统
- **UIManager**: 基于 `UIBase<T>` 的表单管理，提供 `OpenFormAsync<T>()` 异步界面加载、界面栈导航、Loading/Message/Tips/Wait 内置界面
- **SceneManager**: 支持 Unity `LoadSceneAsync` 和 Addressable 资源的异步场景加载，内置加载进度 UI
- **EventManager**: 事件总线，支持字符串和枚举两种事件键，`AddEvent`/`DispatchEvent` 模式
- **ObjectPool**: 泛型 `PoolListCache<T>` 对象池，`UnSpawn()` 回收对象
- **AudioManager**: 音效/背景音乐管理和混音
- **ResourcesManager**: AssetBundle 资源加载和生命周期管理，支持引用计数自动释放
- **AssetReference**: 资源引用追踪组件，绑定 GameObject 生命周期自动释放 AB 包

#### ResourcesManager 资源引用计数自动释放

加载资源时传入 `support` 参数（MonoBehaviour），框架会自动在 support 的 GameObject 上挂载 `AssetReference` 组件追踪引用。当 GameObject 被 Destroy 时，自动释放对应 AB 包的引用计数。引用归零后，在资源管理器的 Update 定时中延迟卸载 AB 包（默认 5 秒）。

```csharp
using GameCore;
using UnityEngine;

public class EnemyController : MonoBehaviour
{
    // 加载单个资源，绑定到 this.gameObject 生命周期
    public async UniTask LoadResources()
    {
        // 同步加载，传入 support 自动管理
        var prefab = Global.Resources.LoadAsset<GameObject>("Assets/Prefabs/enemy.prefab", this);

        // 异步加载
        var prefab2 = await Global.Resources.LoadAssetAsync<GameObject>(
            "Assets/Prefabs/boss.prefab", this);

        // 加载子资源（Sprite 图集等）
        var sprites = Global.Resources.LoadAssetWithSubAssets<Sprite>(
            "Assets/Sprites/ui_atlas.png", this);

        // 异步加载子资源
        var sprites2 = await Global.Resources.LoadAssetWithSubAssetsAsync<Sprite>(
            "Assets/Sprites/effects_atlas.png", this);
    }
}

// 当 EnemyController.gameObject 被 Destroy 时，
// 所有通过它加载的 AB 包引用自动减 1，
// 引用归零后 5 秒内自动卸载 AB 包
```

**手动控制释放：**

如果需要在 GameObject 销毁前主动释放某些资源，通过 `AssetReference` 组件操作：

```csharp
// 获取 AssetReference 组件
var assetRef = GetComponent<AssetReference>();

// 释放单个资源
assetRef.ReleaseAsset(someSprite);

// 批量释放
assetRef.ReleaseAssets(sprites);
```

**手动绑定（延迟绑定）：**

当加载或实例化时未传入 `support`，可在之后手动将资源绑定到指定 MonoBehaviour 的生命周期：

```csharp
// 先加载（无 support）
var prefab = Global.Resources.LoadAsset<GameObject>("Assets/Prefabs/enemy.prefab");

// 使用 Unity 原生 Object.Instantiate 实例化
var instance = Object.Instantiate(prefab, parent: transform);

// 手动绑定：第一个参数是 AB 持久化资源引用，第三个参数是实例化后的对象
// 当 instance 被 Destroy 时，AB 引用自动释放
Global.Resources.BindAsset(prefab, "Assets/Prefabs/enemy.prefab", instance);

// 此后 this.gameObject 销毁时，对应 AB 自动释放
```

**工作原理：**

1. `LoadAsset<T>(path, this)` → 加载资源 → 在 `this.gameObject` 上获取或添加 `AssetReference` 组件
2. `AssetReference.AddRef(assetObject, bundleName)` → 记录该资源引用次数，调用 `RetainAssetBundle` 增加 AB 全局引用
3. `GameObject.Destroy()` → `AssetReference.OnDestroy()` → 遍历所有追踪资源，释放对应 AB 引用
4. AB 引用归零 → 开始排期计时（`ReleaseDelay`，默认 5 秒）
5. 计时到期 → `Update()` 中自动调用 `UnloadAssetBundle` 卸载 AB 包
6. 排期内若有新加载同一 AB → 引用重新 > 0 → 自动取消排期

**多个资源共享同一 AB 包：**

当多个 asset 来自同一个 AB 包时，只有所有 asset 的引用都释放后 AB 才会被卸载：

```csharp
// enemy 和 boss 都来自 "characters" AB 包
var enemy = Global.Resources.LoadAsset<GameObject>("Assets/Prefabs/enemy.prefab", this);
var boss = Global.Resources.LoadAsset<GameObject>("Assets/Prefabs/boss.prefab", this);

// this.gameObject 销毁时，两个引用一起释放，"characters" AB 才会排期卸载
```

**subAssets 场景：**

```csharp
// 加载图集中的所有 Sprite，全部绑定到 this 生命周期
var sprites = Global.Resources.LoadAssetWithSubAssets<Sprite>(
    "Assets/Sprites/ui_atlas.png", this);
// 每个 sprite 都被独立追踪，this 销毁时全部释放

// 也可以提前释放部分
var assetRef = GetComponent<AssetReference>();
assetRef.ReleaseAsset(sprites[0]); // 只释放第一个，其余仍受保护
```
- **TimerManager**: 游戏逻辑定时器
- **ConfigManager**: 游戏配置管理
- **PlayerPrefsManager**: 本地持久化存储

**使用示例：**

```csharp
using GameCore;
using UnityEngine;

public class GameBootstrap : MonoBehaviour
{
    private async void Start()
    {
        // 通过 Global 静态属性访问所有子系统
        Global.Event.AddEvent("OnGameStart", (args) =>
        {
            Debug.Log("游戏开始");
        });

        // 异步打开界面
        var loginPanel = await Global.UI.OpenFormAsync<LoginPanel>(UIMode.Replace);

        // 异步加载场景
        await Global.Scene.LoadAssetSceneAsync("BattleScene", LoadSceneMode.Single,
            progress => Global.UI.Loading.UpdateProgress(progress),
            () => Debug.Log("场景加载完成"));
    }
}
```

---

### 10. NonLockStep - 非锁步同步

确定性帧同步替代方案，适用于需要物理模拟的多人游戏。

**主要功能：**

- **LockstepManager** (`NonLockStep.LockstepManager<T, SYSTEM, ENTITY>`): CRTP 泛型单例，管理 `Systems` 和 `Entities` 集合，提供 `NTime`/`NTimer`/`NRandom` 静态确定性时钟
- **NRigidbody**: 基于 BEPUphysics 的确定性刚体，替代 Unity Rigidbody，支持碰撞/触发监听器 (`ICollisionEnterListener` 等)
- **NCharacterController**: 确定性角色控制器
- **确定性随机** (`NRandom`): 基于种子的确定性随机数生成
- **软浮点模式**: 定义 `ENABLE_SFLOAT` 后使用 `sfloat` 保证跨平台确定性
- **帧追赶**: `maxCatchUpFrames` 控制最大追赶帧数

**使用示例：**

```csharp
using NonLockStep;

public class GameLockstep : LockstepManager<GameLockstep, GameSystem, GameEntity>
{
    public override void OnInitialize()
    {
        // 注册系统
        Systems.Add(new MovementSystem());
        Systems.Add(new CombatSystem());
    }

    protected override void OnUpdateLogic()
    {
        // 固定帧率逻辑更新
        foreach (var sys in Systems)
        {
            sys.UpdateLogic();
        }
    }
}

public class DeterministicBullet : MonoBehaviour, IEntity
{
    public NRigidbody rigidbody;

    public void Initialize()
    {
        rigidbody = GetComponent<NRigidbody>();
        GameLockstep.I.Entities.Add(this);
    }

    public void UpdateLogic()
    {
        // 确定性物理计算
    }

    public int CalculateChecksum()
    {
        return transform.position.GetHashCode();
    }
}
```

---

### 11. Distributed - 分布式系统

分布式游戏服务器集群的基础设施。

**主要功能：**

- **一致性哈希** (`Net.Distributed.ConsistentHashing<T>`): 基于 `SortedDictionary<uint, VirtualNode<T>>` 的哈希环实现，通过虚拟节点 (`virtualNodeReplicas`) 平衡分布
- **虚拟节点** (`VirtualNode<T>`): 支持 `StartHash`/`EndHash` 区间和泛型 `Token`
- **负载均衡** (`LoadBalance`): 玩家到服务器的分配策略
- **唯一 ID 生成** (`UniqueIdGenerator`): 雪花算法风格的分布式 ID

**使用示例：**

```csharp
using Net.Distributed;

// 一致性哈希用于服务器分配
var hashing = new ConsistentHashing<string>(virtualNodeReplicas: 150);

// 添加服务器节点
hashing.AddNode("server-01");
hashing.AddNode("server-02");
hashing.AddNode("server-03");

// 根据玩家 ID 分配服务器
string serverId = hashing.GetNode("player_12345");
Debug.Log($"玩家被分配到: {serverId}");

// 服务器下线时移除
hashing.RemoveNode("server-02");
// player_12345 会被重新分配到其他节点
string newServer = hashing.GetNode("player_12345");
```

---

### 12. Recast - 寻路系统

Recast/Detour 导航网格的 C# 封装，支持托管和原生两种后端。

**主要功能：**

- **NavmeshSystem** (`Net.AI.NavmeshSystem`): unsafe 代码，使用 `float*` 路径缓冲区 (2048×3)，管理 `FastList<AgentEntity>` 寻路代理集合
- **后端切换**: 定义 `RECAST_NATIVE` 使用原生 C DLL (`RecastDll.dll` 576KB)，否则使用托管 `RecastNet.dll`
- **AgentEntity**: 寻路代理实体
- **Unity 集成** (`NavmeshSystemUnity`): MonoBehaviour 封装

**使用示例：**

```csharp
using Net.AI;
using UnityEngine;

public class PathfindingSetup : MonoBehaviour
{
    private NavmeshSystem navmesh;

    private void Start()
    {
        navmesh = new NavmeshSystem();
        // 从文件加载导航网格
        navmesh.Init("navmesh.bin");

        // 计算路径
        var agent = new AgentEntity();
        agent.SetDestination(new Vector3(100, 0, 100));
        navmesh.Agents.Add(agent);
    }
}
```

---

### 13. Table - 配置表系统

Excel 配置表到 C# 代码的完整管线。

**主要功能：**

- **TableConfig** (`Net.Table.TableConfig`): 支持 JSON 和二进制两种格式加载，客户端服务端双端可用
- **TypeSolver**: 类型解析器，自动推断 Excel 列对应的 C# 类型
- **TableBinarySerialize**: 配置表二进制序列化（比 JSON 更快更小）
- **Collectors/Solvers**: 数组/List/Vector 等集合类型的解析器

**使用示例：**

```csharp
using Net.Table;

// 加载 JSON 配置表
var config = new TableConfig();
config.LoadTable(File.ReadAllText("HeroConfig.json"));

// 或加载二进制配置表
config.LoadTableFile("HeroConfig.bytes");

// 读取数据
var dataSet = config.DataSet;
foreach (DataRow row in dataSet.Tables["Hero"].Rows)
{
    int id = (int)row["Id"];
    string name = (string)row["Name"];
    int attack = (int)row["Attack"];
    Debug.Log($"英雄: {id} - {name} (攻击力: {attack})");
}
```

---

### 14. Helper 工具集

20+ 个工具类，覆盖游戏开发的常见需求。

| 类名 | 用途 |
|---|---|
| `InvokeHelperBuild` (51KB) | 代码生成引擎 |
| `AssemblyHelper` (27KB) | 程序集反射与扫描 |
| `EncryptHelper` (9KB) | 数据加密（AES/RSA/XOR） |
| `CertificateHelper` (10KB) | SSL 证书管理 |
| `MySQLHelper` (14KB) | MySQL 数据库操作 |
| `CloneHelper` (10KB) | 对象深拷贝 |
| `SerializeHelper` | 序列化辅助 |
| `SyncVarHelper` | SyncVar 辅助 |
| `AntiCheatHelper` | 反作弊辅助 |
| `UnZipHelper` (14KB) | ZIP 压缩解压 |
| `CRCHelper` | CRC32 校验 |
| `ByteHelper` | 字节操作 |
| `DateTimeHelper` (12KB) | 时间日期工具 |
| `MathHelper` (12KB) | 数学函数 |
| `RandomHelper` | 随机数工具 |
| `PathHelper` | 文件路径 |
| `StringHelper` | 字符串处理 |
| `ArrayHelper` (16KB) | 数组操作 |

---

### 15. Editor - 编辑器工具

Unity Editor 中的开发辅助工具。

**主要功能：**

- **模块导入窗口** (`ImportSettingWindow`): 可视化勾选需要导入的框架模块
- **快速序列化构建** (`FastSerialize2BuildTools`): 为 IL2CPP 生成 AOT 友好的序列化代码
- **代码生成工具** (`InvokeHelperTools`): 生成网络方法调用代码
- **属性绘制器**: Vector2/3/4、Matrix4x4 等类型的 Inspector 绘制
- **外部引用工具** (`ExternalReferenceTools`): 检查和管理程序集引用
- **代码混淆窗口** (`CodeObfuscationWindow`): 基于 dnlib 的代码混淆

---

## 示例项目

框架提供了 14 个示例项目，位于 `GameDesigner/Example~/`：

| 示例 | 说明 |
|---|---|
| `Example1` | 基础示例场景 |
| `Example2` | 进阶示例场景 |
| `ExampleServer~` | .NET 服务端示例（Windows Forms） |
| `DistributedExampleServer~` | 分布式服务端示例 |
| `HttpFileServer~` | HTTP 文件服务器示例 |
| `Server&Client` | 客户端-服务端联调 |
| `ActorDemo` | 角色系统示例 |
| `AOIExample` | AOI 兴趣区域示例 |
| `LockStep` | 锁步同步示例 |
| `StateExample` | 状态机示例 |
| `GameCoreDemo` | GameCore 基础设施示例 |
| `GameDemo` | 完整游戏 Demo |
| `Recast` | 寻路系统示例 |

---

## 快速开始

### 环境要求

- Unity 2021.3 LTS+
- .NET Framework 4.8（Unity 端）
- .NET 8.0 SDK（独立服务器端）
- Visual Studio 2019+ / Rider

### 安装

1. 将项目导入 Unity:
   - 打开 Unity Hub → "Add Project From Disk" → 选择项目根目录
   - 或通过 Unity Package Manager 添加 `com.gamedesigner.network`

2. 配置模块导入:
   - Unity 菜单栏 `GameDesigner → Import Window`
   - 勾选需要的模块，点击导入

### 构建

**Unity 端 (.NET Framework 4.8):**
```bash
dotnet build GameDesigner.csproj -c Release
```

**独立服务器 (.NET 8.0):**
```bash
dotnet build GameDesignerCore.csproj -c Release
```

独立服务器构建只包含 Network、Core、Serialize、Extensions、Helper 等核心模块，排除 Unity 依赖。

---

## 许可证

MIT License - 详见 [LICENSE](LICENSE)