zzz-od-dev-gameplay-onboarding

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。

信息源(理解玩法,玩法优先)

1. 游戏机制(玩法本体,顶层):玩法是什么 / 目标(如复兴度)/ 资源(货币/材料)/ 经济循环 / 子玩法游戏含义 / 核心机制(如托管 vs 手动)。来源:网络攻略/wiki(米游社优先,官方论坛)/ 实玩 / 实拍。这是 doc 主体。
2. app 代码(反推工具):@operation_node 链 + config 开关 + 子 op 委托 → 反推玩法意图(哪些子玩法、分支条件、退出),验证玩法机制理解。不是 doc 主体,编排降为附录。
3. screen doc:每画面 id_mark / area / 细节(引用,不重复)。
4. 实拍:入口路径 / 互斥态 / 条件态 / 资源数字(代码不体现,实拍确认;复用 zzz-od-dev-screen-onboarding 的 interact >名字< 判据)。

读代码是为了反推玩法,不是把代码结构搬进 doc。玩法机制以游戏实际为准(攻略 + 实拍交叉验证),代码只是实现。

流程

1. 理解玩法机制(先):网络搜(米游社 / wiki / 攻略)+ 实玩 / 实拍,理清:这是什么 / 目标 / 资源 / 经济循环 / 核心机制 / 子玩法游戏含义。
2. 代码反推(验证):读 app @operation_node 链 + config,反推 / 验证玩法(哪些子玩法、分支、退出);不明的再实拍 / 问用户。
3. 写玩法 doc(玩家视角):按下方结构,玩法机制为主体。
4. 代码编排降附录:app 节点链 + config 压缩成一节附录(供读代码参考),不放主体。
5. 双向引用:gameplay.involves_screens + 各 screen.appears_in。
6. 缺口 / 待确认:无 screen_info / 攻略冲突 / 未实拍 → 标记(不编)。

gameplay doc 结构(玩法视角)

• frontmatter:gameplay_name / involves_screens。
• 这是什么:玩法定位、在游戏里的位置、如何解锁。
• 玩法目标:玩家要达成什么(如复兴度)、里程碑。
• 核心资源:货币 / 材料 / 道具表(作用 + 来源)。
• 经济循环(核心):主循环链图(产 → 加工 → 卖 → 升级)+ 辅循环。
• 核心机制:如托管 vs 手动(互斥 / 收益对比)、关键系统(如邦布劳动力)。
• 子玩法:每子玩法一段游戏含义(玩家视角做什么),引用 screen doc 细节。
• 日常 / 周期:刷新周期、日常节奏。
• 入口:大世界 → 进玩法(Transport + interact)。
• 附录:自动化实现:代码编排 + config(压缩,非玩法)。
• 信息来源与置信度:标注实拍确认 / 据攻略 / 待确认。

判据(防坑)

• 玩法机制以游戏实际为准:攻略 + 实拍交叉验证;数字 / 机制标来源(实拍 / 攻略);不确定标「待确认」或问用户,别编。
• config 开关:记玩法含义(如托管 / 手动互斥),不只记代码开关名。
• 不重复 screen doc:gameplay 写玩法机制,screen 写单画面,互相引用。
• 参考 doc 写当前现状(游戏实际);设计 / 预期另存 spec。
• ⚠️ 玩法权威 / 代码反推 / 编排降附录 —— 见开篇「核心」段(此处不复述,防三处重复)。

收尾判据

• gameplay doc 玩法机制完整(目标 / 资源 / 循环 / 子玩法含义);代码编排降附录;来源置信度标注;双向引用齐;缺口标记。