| name | zzz-od-dev-gameplay-onboarding |
| description | 当一个已有 app / 玩法(代码已写、跨多画面)需要写玩法机制 doc 时用。 |
玩法建档(理解游戏机制 → 串多画面 → gameplay doc)
拿到已有功能(app 代码已写、跨多画面)时,把玩法机制(玩家视角:这是什么 / 目标 / 资源 / 经济循环 / 子玩法游戏含义)沉淀成 docs/game/gameplay/<name>.md(参考型 = 写当前现状)。
⚠️ 核心:写玩法,不写代码编排。 gameplay doc 给智能体理解游戏机制做决策,不是读懂代码。代码(@operation_node)是反推玩法的工具,编排细节降为附录或留给 screen doc。(教训:随便观.md 第一版写成「app 节点链 + config 开关」说明书 = 代码视角,已翻转。)
定位与边界
- 管:跨 ≥2 画面的已有 app 的玩法机制知识(参考 doc,写现状)。
- 不管:单画面细节(zzz-od-dev-screen-onboarding 管);代码编排细节(附录简述或留代码注释);新玩法从 0 设计 spec(待实践补);运行时识别。
- 判据:跨多画面才建 gameplay doc;单画面用 screen doc。
信息源(理解玩法,玩法优先)
- 游戏机制(玩法本体,顶层):玩法是什么 / 目标(如复兴度)/ 资源(货币/材料)/ 经济循环 / 子玩法游戏含义 / 核心机制(如托管 vs 手动)。来源:网络攻略/wiki(米游社优先,官方论坛)/ 实玩 / 实拍。这是 doc 主体。
- app 代码(反推工具):
@operation_node 链 + config 开关 + 子 op 委托 → 反推玩法意图(哪些子玩法、分支条件、退出),验证玩法机制理解。不是 doc 主体,编排降为附录。
- screen doc:每画面 id_mark / area / 细节(引用,不重复)。
- 实拍:入口路径 / 互斥态 / 条件态 / 资源数字(代码不体现,实拍确认;复用 zzz-od-dev-screen-onboarding 的 interact
>名字< 判据)。
读代码是为了反推玩法,不是把代码结构搬进 doc。玩法机制以游戏实际为准(攻略 + 实拍交叉验证),代码只是实现。
流程
- 理解玩法机制(先):网络搜(米游社 / wiki / 攻略)+ 实玩 / 实拍,理清:这是什么 / 目标 / 资源 / 经济循环 / 核心机制 / 子玩法游戏含义。
- 代码反推(验证):读 app
@operation_node 链 + config,反推 / 验证玩法(哪些子玩法、分支、退出);不明的再实拍 / 问用户。
- 写玩法 doc(玩家视角):按下方结构,玩法机制为主体。
- 代码编排降附录:app 节点链 + config 压缩成一节附录(供读代码参考),不放主体。
- 双向引用:
gameplay.involves_screens + 各 screen.appears_in。
- 缺口 / 待确认:无 screen_info / 攻略冲突 / 未实拍 → 标记(不编)。
gameplay doc 结构(玩法视角)
- frontmatter:
gameplay_name / involves_screens。
- 这是什么:玩法定位、在游戏里的位置、如何解锁。
- 玩法目标:玩家要达成什么(如复兴度)、里程碑。
- 核心资源:货币 / 材料 / 道具表(作用 + 来源)。
- 经济循环(核心):主循环链图(产 → 加工 → 卖 → 升级)+ 辅循环。
- 核心机制:如托管 vs 手动(互斥 / 收益对比)、关键系统(如邦布劳动力)。
- 子玩法:每子玩法一段游戏含义(玩家视角做什么),引用 screen doc 细节。
- 日常 / 周期:刷新周期、日常节奏。
- 入口:大世界 → 进玩法(Transport + interact)。
- 附录:自动化实现:代码编排 + config(压缩,非玩法)。
- 信息来源与置信度:标注实拍确认 / 据攻略 / 待确认。
判据(防坑)
- 玩法机制以游戏实际为准:攻略 + 实拍交叉验证;数字 / 机制标来源(实拍 / 攻略);不确定标「待确认」或问用户,别编。
- config 开关:记玩法含义(如托管 / 手动互斥),不只记代码开关名。
- 不重复 screen doc:gameplay 写玩法机制,screen 写单画面,互相引用。
- 参考 doc 写当前现状(游戏实际);设计 / 预期另存 spec。
- ⚠️ 玩法权威 / 代码反推 / 编排降附录 —— 见开篇「核心」段(此处不复述,防三处重复)。
收尾判据
- gameplay doc 玩法机制完整(目标 / 资源 / 循环 / 子玩法含义);代码编排降附录;来源置信度标注;双向引用齐;缺口标记。
