从零设计一套可复用的 Unity 手游框架：CGHGameFramework 架构实践

从零设计一套可复用的 Unity 手游框架CGHGameFramework 架构实践标签Unity · 游戏框架 · 热更新 · MMORPG · 客户端架构适合读者Unity 中高级客户端、主程/技术负责人、准备搭自研框架的同学说明本文基于本人主导落地的CGHGameFramework已在 MMO、卡牌养成、休闲棋牌多品类验证。文中代码为示意便于阅读。前言为什么又要「自研框架」做了十几年 Unity 客户端最怕的不是某个 API 不会用而是项目进入中后期后改邮件把战斗搞崩热更 DLL 误引用了UnityEngine真机加载直接挂UI 里写伤害公式和服务器对不上每个人一个XXXManager生命周期靠猜这些问题的根因往往不是「同事不行」而是边界没划清。架构设计 提前把问题关进小盒子别让它污染全局。CGHGameFramework 的目标很明确让组员只写业务主程维护基础设施同一套框架能支撑 MMO、卡牌、棋牌而不是每个品类重造轮子。一、四条设计原则原则含义落地框架 / 业务分离水电煤归框架装修归业务Assets/GameFramework/vsAssets/Game/框架程序集禁止引用Game.*Logic / View 分离可热更逻辑不碰引擎对象Logic 纯 C#View 只订阅事件做表现Entry Module统一生命周期禁止满天 Singleton全部实现IGameModule由GameFrameworkEntry驱动双热更管线代码与资源版本节奏不同HybridCLR 热更 DLLAB manifest 热更资源这四条看起来「常识」但只要有一条被破坏半年后的维护成本会指数上升。二、横向两层框架 vs 业务┌─────────────────────────────────────────┐ │ GameClient (Assets/Game/) │ ← 业务大厅 / Feature / 副本 / 牌桌 └──────────────────┬──────────────────────┘ │ 只调用 ↓ ┌──────────────────▼──────────────────────┐ │ CGHGameFramework (Assets/GameFramework/) │ ← 框架网络 / UI / 资源 / 同步 / 热更 └──────────────────┬──────────────────────┘ │ Unity Engine 服务器 CDN大白话框架 水电煤、电梯、消防——所有房间共用业务不能私改管道业务 各个商铺的装修——只能接水电不能自己挖天然气硬性红线禁止原因在框架里写业务 Panel框架被单项目绑死无法复用在业务里改NetworkManager源码升级框架变成 merge 地狱框架引用Game.*依赖倒置框架无法独立编译三、纵向分层从启动到像素玩家点图标到看见角色可以想成五层启动层 GameLauncher 合规 → remote_ops → 双热更 → 登录 → 进场景 游戏层 EntitySync / Room 玩法系统实体同步、房间 FSM、社交… Logic 层 LogicWorld 纯 C#「大脑」可热更的战斗/回合/棋牌规则 服务层 UI / Scene / Audio 看见、听见、切场景 基础设施 Network / Resource TCP、AB、配表 核心层 EventBus / Timer 事件、定时器、主线程派发记忆口诀越往下越通用、越稳定、越少改越往上越业务、越常改、越适合热更。四、唯一入口GameFrameworkEntry框架不靠「到处new Manager」而用一个总入口// 启动时GameLauncher / DriverGameFrameworkEntry.Init(GameMode.MMORPG);// 业务侧统一访问GameFrameworkEntry.UI.OpenAsyncMailPanel(ui/feature/mail/MailPanel);GameFrameworkEntry.Network.Send(newMailListReq());GameFrameworkEntry.EventBus.SubscribeMailUpdatedEvent(OnMailUpdated);GameFrameworkEntry.Resource.LoadAsyncGameObject(ui/...);为什么是 Entry Module生命周期可控Init → Update → Shutdown顺序固定新人友好不用猜 Network 谁创建的优先级EventBus 先于 Network 先于 UI减少空引用每个 Manager 实现同一契约publicinterfaceIGameModule{intPriority{get;}voidOnInit();voidOnUpdate(floatdeltaTime);voidOnShutdown();}Shutdown逆序执行避免「先拆 EventBus 后还有人发事件」。五、GameMode一套框架多种品类同一套 CGHGameFramework通过注册不同模块组合切换品类GameMode注册侧重典型产品MMORPGEntity / AOI / EntitySync / Session / 重连《王者争霸》CasualRoomManager 等不注册 MMO 同步轴《星辰少女》卡牌养成CardCasual 棋牌 Session如斗地主休闲棋牌矩阵关键洞察卡牌回合制不应硬套 EntitySync棋牌大厅不应背负城战 AOI。品类差异用「模块组合」表达而不是 fork 一整套框架。这也是后来能用同一底座铺多款棋牌/休闲的原因换的是 GameMode 与业务目录不是底层管道。六、Logic / View热更友好的战斗与玩法MMO 战斗若把公式写在MonoBehaviour里会遇到热更困难绑死场景对象难单测客户端「看起来打中」与服务器权威冲突我们的做法输入 / UI → LogicWorld纯 C#预检、镜像 HP/Buff、连招窗口 → 网络CastSkillReq → 服务器权威命中与结算 → DamageNotify → View播受击、飘字、特效可降级铁律Logic禁止引用UnityEngine保证 HybridCLR 热更边界清晰View禁止本地扣最终血量以 Notify 为准命中主路径用几何 AOI而不是城战里堆 PhysX Trigger人一多必炸棋牌同理DouDiZhuSession/ 未来的MahjongSession都是纯 C# 状态机牌桌 View 只订阅事件。七、双热更代码一条线资源一条线很多团队把「热更」说成「打个 AB」这是不精确的。代码热更HybridCLR资源热更AB产物raw.dll manifestAssetBundle manifest是否打 AB否是CDN/code/{Platform}//ab/{Platform}/节奏修逻辑、协议换皮、场景、特效iOS更谨慎可远程关闭通常放开启动顺序固定拉 remote_ops可熔断/回滚 → 代码热更 → 资源热更mandatory → 进登录 / 大厅 → 其余边玩边下上线安全热更不是「发得出去」就行必须「发错收得回」——remote_ops支持回滚版本、拉黑坏包、强制清缓存、关代码/资源热更。八、资源与内存加载契约比 API 更重要业务统一走GameFrameworkEntry.Resource.LoadAsyncT(logicalPath);// 用完GameFrameworkEntry.Resource.Release(logicalPath);配套能力逻辑路径业务不写物理 AB 名DeviceTier自动优先*_low变体引用计数 依赖序卸载公共包被占用时不会误卸MemoryManager按水位 Soft / Medium切场景 Loading 做异步 Hard含UnloadUnusedAssets长时在线内存上涨根因往往是只 Load 不 Release而不是「AB 下载到磁盘了」。磁盘缓存和运行内存要分开治理。九、网络状态同步为主的 MMO 路径《王者争霸》类项目我们选择状态同步 服务器权威而非大世界帧同步TCP Protobuf MsgIdEntitySyncSnapshot 缓冲插值 本地预测/校正断线Heartbeat → Reconnect →ResumeSession→权威 Snapshot 对齐状态同步下的「追进度」不是重放所有输入帧资产/关键操作ReliableRequestClientSeq幂等传输优化优先顺序通常是AOI / 可见集少发脏字段与降频少发协议瘦身与量化少带解包池化少解析再考虑 UDP/KCP 等通道品类需要时十、工具链把重复劳动左移主程价值很大一块是工具化Proto / Excel → C# CodegenProto / MsgId 校验冲突、缺失、字段号AB 增量 patch、边玩边下配置美术资源校验、机型分档发版菜单与渠道打包目标闭环改 Schema → 自动生成 → CI/校验门禁 → 人只写业务没有工具链的「架构漂亮」会在第三个版本被人力拖垮。十一、一张图看数据流邮件为例玩家点「邮件」 → UI.OpenAsync(MailPanel) → Network.Send(MailListReq) → 服务器 MailListResp → Handler → EventBus 发 MailUpdatedEvent → Panel 刷新列表VirtualList业务 Feature 推荐固定套路「六件套」思路Panel / Handler / 协议 / 配表 / 事件 / 入口。新人按目录找文件而不是问「这个功能写在哪」。十二、实践中的几点教训架构服务于约束不是炫技能让 10 人并行且热更可回滚比上新名词重要。品类复用靠模块开关不靠复制工程MMO / 卡牌 / 棋牌共用启动链与热更减的是「每款从零搭管道」的成本。线上问题靠机制不靠英雄remote_ops、崩溃守卫、内存水位、符号表决定你能不能在分钟级止血。AI 可以加速样板不能替代边界与验收骨架、单测、协议草稿可以交给 AI胡牌正确性、真机性能、上线权必须人来守门。结语CGHGameFramework 不是「又一个 Manager 集合」而是一套可复述的边界框架与业务谁改谁Logic 与 View 谁说了算代码与资源怎么分别热更、怎么回滚不同品类如何共用管道如果你也在搭客户端底座不妨先问自己四个问题改活动会不会必须动框架内核热更失败玩家能不能继续玩新人 30 秒能不能找到该改的文件城战卡了你能不能用 AOI/预算/分档解释而不是只说「优化一下」答得清架构就立得住。作者简介Unity 客户端主程 / 技术负责人11 年手游经验。主导 CGHGameFramework落地 MMORPG《王者争霸》、卡牌养成《星辰少女》及休闲棋牌矩阵等产品线。关注客户端工程化、双热更、状态同步与上线可运维性。转载请注明作者与出处。商业使用请联系作者。