奇门项目技术文档

奇门项目技术文档

这套文档按工程责任边界组织。总入口只负责导航；客户端、服务端分别讲各自实现；只有“联机同步”专题会把两端放进同一条时序里。这样阅读单个模块时不会在前后端代码之间来回跳，又能在排查跨端问题时看到完整链路。

文档分区

flowchart LR
    P[系统全景] --> C[客户端]
    P --> S[服务端]
    C <--> N[联机同步]
    S <--> N
    T[内容生产] --> C
    T --> S
    D[本地开发与排错] --> C
    D --> S

一、系统全景

先建立全局认识，只讲系统边界、部署拓扑和数据归属，不展开某一端的局部代码。

文章解决的问题
01 系统全景：总体架构与分布式拓扑Client、Login、Lobby、Battle、Redis、MySQL、ZooKeeper 怎样组成一套系统

二、客户端运行时总览

这一组只负责启动、装配和玩家主链路，细节继续进入 Logic 或 Rendering。

文章解决的问题
02 Unity 客户端运行架构Unity、Entitas、Zenject、资源和主循环怎样配合
11 客户端启动模块ClientProxy、初始化顺序、系统注册和进入游戏
26 资源加载、热更新与生命周期CfgAssetsPath、AMF、XAsset、Bundle、对象池与释放怎样组成完整资源链路

三、客户端 Logic

只关注状态、规则、系统调度、地图事件和移动意图，不展开材质、动画、特效和 UI。

文章解决的问题
23 客户端 Logic：状态、规则与系统调度四个 Context、System 生命周期、实体/移动/HP/刷怪逻辑和跨层规则

四、客户端 Rendering

只关注逻辑结果如何落成 GameObject、Animator、VFX、Lightmap、镜头和 UI。

文章解决的问题
24 客户端 Rendering：View、动画、特效与 UICore 到 View 的异步桥接、位置同步、动画、对象池和表现排错

五、客户端跨层专题

单个功能天然会跨过 Logic 和 Rendering，但文章内部会明确标出每段属于哪一层。

文章解决的问题
18 玩家控制、创建、出生点与动画玩家 Logic 怎样创建和移动，Rendering 怎样接 Animator
20 客户端寻路、NavMesh 资源与移动表现导航数据、移动策略和 Agent 表现怎样衔接

六、服务端

只关注 .NET 服务进程、Actor、业务状态、校验、持久化和节点协调。客户端如何渲染和预测不在这里展开。

文章解决的问题
03 服务端节点实现与分布式协调Login/Lobby/Battle/Manager/Worker 的职责，注册发现、负载与数据存储
21 Battle 移动权威与服务端校验Battle 怎样接收移动、校验归属和状态、更新权威值、广播或返回失败

七、联机同步

这一组专门处理跨端边界。会话页讲“连到谁”，状态同步页讲“连接后数据怎样往返”。

文章解决的问题
04 网络、登录与协议Login、Lobby、Battle 三段连接与协议生成规则
12 网络会话模块NetworkManager 怎样建连、切服、缓存 SessionId 和重连
22 联机同步：移动包、预测、广播与纠偏一次移动怎样从本地输入跨过 Battle，再成为其他客户端上的远端表现

八、Unity Editor 扩展

Editor 菜单、Inspector、导入器、代码生成和构建流水线与运行时代码分开阅读。

文章解决的问题
25 Unity Editor 扩展：地图、配置、资源与构建MenuItem、CustomEditor、AssetPostprocessor、配置生成、Bundle 和 CI

九、内容生产与玩法配置

这部分讲离线产物怎样同时进入客户端和服务端，以及地图、刷怪、配置、光照等可直接执行的制作流程。

文章解决的问题
05 地图编辑、导出与双端加载地图从 Unity 编辑场景变成前后端共同读取的数据
06 寻路系统寻路概念和主要链路的快速导读
07 刷怪、触发器、AI 与掉落波次、触发器、AI 和掉落的整体关系
08 配置系统Excel 生成、运行时加载和版本一致性
13 地图导出模块Gather、Bake、二进制导出和复制服务端的操作手册
14 寻路模块NavMesh、随机落点和路径校验的模块手册
15 刷怪与战斗模块刷怪波次、随机模板、AI 入口和掉落的模块手册
16 配置模块Excel/文本配置生成、加载和检查的模块手册
19 光照与 Lightmap 烘焙Editor 局部 Bake、纹理产物和运行时加载验收

十、本地开发、排错与学习

文章解决的问题
09 本地隔离环境、联调与排错怎样启动本地服务以及定位登录、切服、Battle 故障
10 学习路线与源码索引按学习目标定位代码入口
17 本地联调模块本地隔离服、日志和联调验收清单

推荐阅读路线

新接手工程

  1. 01 系统全景
  2. 02 Unity 客户端运行架构 或 03 服务端节点实现
  3. 04 网络、登录与协议
  4. 22 联机同步
  5. 再进入玩家、地图、寻路、刷怪或光照专题

客户端开发

  1. 02 Unity 客户端运行架构
  2. 23 客户端 Logic
  3. 24 客户端 Rendering
  4. 26 资源加载、热更新与生命周期
  5. 18 玩家控制、创建、出生点与动画
  6. 20 客户端寻路与移动表现
  7. 需要理解服务器回包时再读 22 联机同步

服务端开发

  1. 03 服务端节点实现与分布式协调
  2. 12 网络会话模块
  3. 21 Battle 移动权威与服务端校验
  4. 需要还原用户端表现时再读 22 联机同步

地图与战斗内容制作

  1. 25 Unity Editor 扩展
  2. 13 地图导出模块
  3. 19 光照与 Lightmap 烘焙
  4. 20 客户端寻路与移动表现
  5. 15 刷怪与战斗模块

阅读和维护约定

  • 客户端 标签只解释 Unity 进程内的责任。
  • Logic 标签保存状态和规则，不把 Animator、Renderer 或 UI 当作业务真相。
  • Rendering 标签消费逻辑结果，不决定服务端权威状态。
  • Editor 标签只描述制作/生成/构建工具，不能成为 Player 运行依赖。
  • 服务端 标签只解释 .NET 节点和 Actor 内的责任。
  • 联机同步 标签必须同时给出消息方向、权威归属、失败行为和两端源码入口。
  • 修改节点、端口或服务发现：更新 01、03、04、09、12。
  • 修改战斗协议或同步阈值：更新 21、22，并检查 20。
  • 修改地图格式或导出器：更新 05、13，并检查 14、15、19、20、21。
  • 修改配置生成和加载：更新 08、16，并确认客户端与服务端产物来自同一批生成。
  • 修改资源路径、分包、加载或释放：更新 26，并检查 02、11、19、24、25。

新增客户端与知识库模块

文章解决的问题
26 场景加载、地图装配与相机跟随Unity Scene、战斗地图装配、玩家出生、相机绑定、跟随与震动
27 可复用技术知识库模板如何记录源码证据、生命周期、迁移接口和排错清单，让模块能跨项目复用

图像资源

截图均来自当前 Unity 工程和编辑器场景：

地图编辑器实景

MapRoot 场景视图

章节