KiHan ActFramework详解
KiHan ActFramework 详解
Lua 活动框架。1000+ 个 Act（限时运营活动）的统一写法。
源码：Assets/Resources/LuaScript/KiHan/ActFramework/，五层结构（Base / Entity / Component / HFSM / Data）
0. 一句话总览：乐高类比
| 概念 | 类比 |
|---|---|
Entity |
乐高底盘（选哪种底盘决定活动形态） |
Component |
标准积木块（网络/UI事件/红点/定时器…插上就能用） |
ActLib |
工具箱（通用函数库） |
HFSM |
变速箱（分层状态机，桥接 C# StateMachineWrapper） |
1. 五层目录结构
| 目录 | 内容 |
|---|---|
Base/ |
ActEntityBase（Component 容器+生命周期驱动）、ActComponentBase（CopyType 机制 + F2EE 拷贝）、ComponentDefine |
Entity/ |
5 种核心 Entity + UI/ Mesh/ AggregatePages/ MiniGame 四个子目录 |
Component/ |
11 个标准 Component + AI/ Mesh/ ActMiniGame |
HFSM/ |
LuaMotionFsmBase + LuaStateBase + LuaTransitionBase |
Data/ |
ActStableData（不受 GC 清除的稳定数据） |
5 种核心 Entity（选型决策）
| Entity | 用途 | Component 数 |
|---|---|---|
ActEntity |
基础活动 | Network + Mock + UIBindData |
ActBehaviourEntity |
完整活动面板（活动中心内嵌） | 10 |
ActUIWindowEntity |
独立入口窗口 | — |
ActPopupWindowEntity |
弹窗（Wrapper） | 8 |
ActEvtInterfaceEntity |
纯事件接口（无界面） | 8 |
11 个标准 Component（按需插拔）
Network（通信）/ UIEvt / BtnEvt / UIBindData（20+ 种 Bind）/ CustomEvt / GameEvt / RedPoint / Timer / StateMachine / UIGroup（互斥）/ MokeDebug（Mock 调试），另有特效裁剪父子、AgpData、AI 行为树等。
2. 编码优先级铁律 ★（最重要的一节）
1 | 1. Entity 内置能力（__protected.SendActCmd / SetTimer / OnRegBtnEvents / DelayRefreshActRP） |
扩展原则：
| 场景 | 做法 |
|---|---|
| 整块逻辑需复用 | 提取到 ActLib（判断”足够通用”：≥2 个活动用、不依赖特定活动数据） |
| 基础设施缺失 | 扩 ActFramework：新增 Component（继承 ActComponentBase）或 Entity |
CS.* 裸调用频繁 |
封装成 ActLib_XXX.lua.txt 收口 |
3. 与 Plugin 框架的边界
| ActFramework | Plugin 框架 | |
|---|---|---|
| 语言 | Lua | C# |
| 目标实体 | 限时活动 Act（1000+） | 长期系统 Plugin（144） |
| 注册 | ActCenterPlugin 子注册 |
KHPluginManager 全局 |
| 生命周期 | 活动期内（有限） | 持续（部分常驻） |
| 范式 | Entity + Component 组合 | MVC（Plugin/Model/Operation/View） |
4. 必知重点与坑
- 选基类先查样板：
domains/act-taxonomy.md按 28 个 domain 分组，先找同类活动抄骨架，别照错样板 - 老式全局函数是反例：新代码用 Entity 内置 / ActLib；
iEachOne、List_New等 C# 集合桥接函数无替代仍需使用 - UI 基类三代演进：
LuaBehaviour → LuaUIWindow → ActBehaviourEntity，新活动一律用新式 Entity - 模板刷新：改
templates/act-analysis-template.md后要重跑tools/probe_act.py增量刷新实体文档（幂等安全）
5. 排查速查
| 现象 | 先查 |
|---|---|
| 活动面板打不开 | Entity 选型对不对；是否走了 ActCenterPlugin 注册 |
| 发协议没反应 | 用 __protected.SendActCmd 还是老 SendCmdHandleForAct；协议号对不对 |
| 红点不刷新 | __protected.DelayRefreshActRP 是否调用；ActRedPointComponent 是否挂上 |
| 找同类参考 | domains/act-taxonomy.md → entities/acts/Act_{ID}.md |
| 活动策划案原文 | kb_query.py get_design_doc <活动号>（改老活动前必读） |
6. 记忆口诀
Entity 是底盘，Component 是积木，ActLib 是工具箱；
能力四级找：内置 → ActLib → CS. → 老全局（别用）。*
相关笔记
- [[KiHan Plugin框架详解]]（C# 侧对照）
- [[KiHan状态机架构详解]]（Act 被哪个环节调度）
本文从 LearnByCompany 原始文档 自动同步。
本博客所有文章除特别声明外，均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来源 岁迹！
相关推荐
2026-09-19
KiHan 新人知识库阅读路线
-–title: KiHan 新人知识库阅读路线 tags: [KiHan, 新人入门, 知识库, 阅读路线] source: Others/AIDev/context/{framework,domains,entities} created: 2026-09-18-– KiHan 新人知识库阅读路线 适用对象：刚接手 KiHan 项目的开发/策划/测试新人 知识库根目录：Others/AIDev/（SVN 管理），本文所有相对路径均以此为基准 0. 先记住一句话不要一头扎进 entities/ 的 1043 篇 Act 文档。 正确顺序是： 1234建坐标系（overview + 路由 + 规则） → 读框架（framework/，最稳定） → 用领域文档串联（domains/） → entities/ 只按任务按需检索 配套认知：全库 1862 篇文档中约 2/3 是 AI 生成未经人工核实。每篇文档头部都有 confidence 字段，它决定你能信几分。 confidence 含义 检索权重...
2026-09-19
KiHan 热更双引擎详解
KiHan 热更双引擎详解 两套热更通道：Lua 脚本（xLua）+ C# 代码（ILRuntime），加上资源 bundle，构成完整更新体系。“我这个改动能不能热更”看这一篇。 0. 三个破除谣言的澄清 ★（源码核验） 只有一个引擎：xLua。没有”V1=SLua / V2=xLua 双引擎” 全工程 using SLua 命中 0 次；SLua 只是腾讯 Pandora 运营 SDK 残留 Lua 框架核心不在 Assets/Scripts/，在 Packages/khengine/Runtime/Lua/ LuaVirtualMachine / LuaClass / RuntimeLuaProxy / LuaCodec 全在 khengine 包内 V1 与 V2 共享同一个 xLua VM 全工程 new LuaEnv() 只出现一处（LuaVirtualMachine.cs:39）；RuntimeLuaProxy 是 V1↔V2 桥梁 1. 三语三层运行时 层 载体 能否热更 判定 ...
2026-09-19
KiHan 项目认知清单
KiHan 项目认知清单 对应知识库 AIDev/context/ 的三层核心（截图红框）： 层 回答的问题 谁写的 认知目标 framework/ 用什么造——框架/库怎么用 人工通读源码 懂机制 entities/ 造了什么——单个模块是什么 工具批量 + 人工深度 会检索 domains/ 怎么串起来——跨模块规律 人/AI 二次提炼 通链路 用法：Obsidian 里直接点击方框打勾。每条尽量附”自验标准”——能讲给别人听才算过。 A. framework 层认知（懂机制）🏗️A1. 调度主干 状态机四层：能画出 Context → Workflow → Phase → Adapter 的层级图，并说出各层职责 → [[KiHan状态机架构详解]] 15 种 Context：能说出 Boot/Game/Duplicate/PKNS 各是什么玩法，SwitchTargetList 白名单是干嘛的 Boot 语义：知道 Boot = 启动期（版本检查→启动7步→服务器登录），不是...
2026-09-19
KiHan Plugin框架详解
KiHan Plugin 框架详解 KiHan 144 个 C# 业务模块（商城/公会/忍具/充值…）的统一写法。源码：Assets/Scripts/Plugin/Infrastructure/在架构中的位置：被状态机拉起 → KHGameFlow.BuildGame() → KHPluginManager.Instance.initializePlugins() 0. 一句话总览：部门类比 类 类比 职责 Plugin 部门经理 模块入口 / 开窗 / 资源 / 消息派发（Controller） Operation 办事员 按”事项名”接单干活（行为单元） Model 档案柜 存数据，网络回包自动归档 View(UIWindow) 对外柜台 界面展示 KHPluginManager 公司总机 按名字找部门、转接消息 核心约定：Plugin 是 Controller，Model 是数据，Operation 是行为。三者靠「消息字符串」解耦，不直接互调。 1. 核心概念 基类 数...
2026-09-19
KiHan Manager台账速查
KiHan Manager 台账速查 Assets/Scripts/Manager/ 下 78 个 *Manager.cs 的反查台账。查”某系统归哪个 Manager 管”从这里开始。 0. 单例形态（先认清，源码逐个核验过） 形态 代表 备注 普通类 + 手写静态单例 KHDataManager(getInstance)、KHMovieManager、KHEffectManager、KHAudioRecordManager、GVoiceManager、ExpandPackManager 事件靠内持/全局 dispatcher KHEventDispatcher + 静态单例 KHResManager、KHBattleManager、KHAudioManager、KHCityPlayerManager、VersionManager 自身即事件源，可 dispatchEvent Singleton<T>（MonoBehaviour） KHMultiCameraManager 靠 LateUpdate 轮询 SimpleSinglet...
2026-09-19
KiHan状态机架构详解
-–title: KiHan 状态机架构详解（Context / Workflow / Phase / Adapter） tags: [KiHan, 架构, 状态机, Context, Workflow, Phase, Adapter, Boot, Duplicate] created: 2026-09-18 confidence: high source: 源码直读（GameEntry/KHGameFlow.cs、Module/KHGameLevelContext.cs、Module/Workflow/、Module/PhaseAdapter/、Module/Boot/、Module/Duplicate/）-– KiHan 状态机架构详解 本文基于 Others/AIDev/context/framework/state-machine-framework.md 与真实源码对照整理 源码根目录：Assets/Scripts/ 适用：想理解 KiHan...