# Zzz Od Dev Gameplay Onboarding

> 当一个已有 app / 玩法(代码已写、跨多画面)需要写玩法机制 doc 时用。

- Skill: `onedragon-anything/zzz-od-dev-gameplay-onboarding` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add onedragon-anything/zzz-od-dev-gameplay-onboarding`
- Raw SKILL.md: https://api.skillmd.com/api/skills/onedragon-anything/zzz-od-dev-gameplay-onboarding/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: onedragon-anything (https://skillmd.com/u/onedragon-anything)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/onedragon-anything/zzz-od-dev-gameplay-onboarding

---


# 玩法建档(理解游戏机制 → 串多画面 → 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 **玩法机制完整**(目标 / 资源 / 循环 / 子玩法含义);代码编排降附录;来源置信度标注;双向引用齐;缺口标记。