game-reverse-document

AlterLab GameForge —— 逆向文档工作流

大多数游戏项目始于热情，而非文档。开发者制作原型、反复迭代并构建项目。几周后，代码库已经可以运行，但没人——包括原作者——能不逐个阅读所有文件就说清它的架构。没有设计文档，因为设计是在代码中逐步形成的。没有架构决策记录，因为决策都是当场做出的，从未记录下来。这是独立游戏开发的常态，假装不是这样并不诚实。

这种工作流颠倒了传统的文档编写流程。它不再先写文档再构建项目，而是读取现有代码，产出本应从一开始就存在的文档。输出并非自动生成的 API 文档，而是可供人阅读的设计文档，用游戏开发的语言而非代码的语言来记录设计意图、架构和游戏系统。

逆向文档可以满足三项关键需求：入门（新团队成员只需数小时，而非数周的代码考古，就能了解项目）、知识留存（在原开发者忘记决策缘由之前记录下来）以及问题诊断（将系统并列记录后，系统之间的不一致便会显现）。

用途与触发条件

在以下情况下使用此工作流：

• 原型可以运行，但完全没有文档
• 新团队成员需要了解现有代码库
• 原开发者即将离开，需要转移知识
• 项目已经复杂到作者开始跟不上各个系统
• 有人说“把这个记录下来”或“这段代码是做什么的？”
• 游戏创作马拉松的原型将升级为完整项目，需要正式文档
• 现有项目需要设计文档，以供发行商、投资者参考或帮助团队达成共识

此工作流解决的问题：

• 代码可以运行，却没人能解释或安全地修改
• 入门需要花数周阅读代码，而非数小时阅读文档
• 架构决策隐而不见——它们藏在代码中，却从未被记录
• 游戏机制存在于代码中，却未在任何设计文档中描述
• 系统之间相互矛盾，因为没人梳理过它们之间的交互
• 孤立的代码毫无作用，却没人有把握将其删除

关键规则

1. 先阅读，再编写。 不要凭假设编写文档。先扫描实际代码库。输出中的每项陈述都必须能追溯到具体文件或代码模式。请附上文件路径和行号。

2. 意图优先于实现。 记录代码这样做的原因，而不只是它做了什么。一个施加重力的函数，不应描述为“施加向下的力”，而应描述为“施加移动约束，以防止无限跳跃”。Celeste 的代码库中有许多阐明意图的注释，例如“土狼时间：离开平台后，玩家仍可在 6 帧内跳跃”。这就是目标文档应达到的意图说明水平。

3. 标明不确定之处。 如果代码意图含糊不清，就直说。使用 [UNVERIFIED] 标记相关部分，并请开发者澄清。把猜测的意图当作事实记录，比留下一处空白更糟糕。

4. 围绕系统，而非文件组织文档。 按游戏系统（移动、战斗、物品栏、UI）组织文档，而不是按文件结构组织。一个移动系统可能涉及 3 个目录中的 5 个文件。文档应先介绍系统，再列出相关文件。Dead Cells 的内部文档按游戏系统组织所有内容——战斗、生物群系、进度、敌人——因为这符合设计师思考游戏的方式，而非文件树的组织方式。

5. 发现不一致，不要忽略。 如果移动代码假定采用基于瓦片的移动，而碰撞代码假定采用连续移动，这就是一项文档发现，不应掩盖。请将其标明。Factorio 的代码库是内部一致性的典范——每个系统对“刻”的含义、“传送带”能运送什么，以及实体如何交互，都有一致的理解。当文档揭示两个系统在基本概念上存在分歧时，你就抢在问题发布之前发现了 bug。

6. 三种模式，共用一条流水线。 三种模式共用同一条代码分析流水线。变化的是输出格式，而非分析深度。

工作流

---

🧠 阶段 1：项目扫描

目标：在阅读代码之前，了解项目结构、引擎和组织方式。

PROJECT SCAN PROTOCOL
-------------------------------------------------
Step 1: Detect engine and framework
  Scan for:
  - project.godot, *.gd, *.tscn         --> Godot
  - *.unity, *.cs, ProjectSettings/      --> Unity
  - *.uproject, *.cpp/*.h with UE macros --> Unreal Engine
  - package.json with game libs          --> Web/JS game framework
  - Cargo.toml with game crates          --> Rust game framework
  - None of the above                    --> Custom engine or unknown

Step 2: Map directory structure
  Produce a tree of the project with annotations:
  /project-root/
    /src/ or /scripts/    -- Game logic
    /assets/ or /art/     -- Visual and audio assets
    /scenes/ or /levels/  -- Level/scene data
    /ui/                  -- User interface
    /data/ or /config/    -- Game data, settings
    /tests/               -- Test files (if any)
    /docs/                -- Existing documentation (if any)

Step 3: Measure project scale
  - Total source files: [N]
  - Total lines of code: [approximate]
  - Number of scenes/levels: [N]
  - Number of asset files: [N]
  - Estimated project complexity: [small / medium / large]

Step 4: Check for existing documentation
  - README present: [Y/N]
  - Design document present: [Y/N]
  - Inline comments density: [sparse / moderate / thorough]
  - Architecture docs present: [Y/N]
-------------------------------------------------

---

🎯 阶段 2：系统检测

目标：通过代码模式识别不同的游戏系统。

无论使用何种引擎或语言，游戏系统都会在代码中留下可识别的特征。本阶段通过扫描典型模式，识别项目中包含哪些系统。

SYSTEM DETECTION HEURISTICS
-------------------------------------------------
MOVEMENT SYSTEM:
  Signals: velocity variables, position updates per frame, input axis
  reading, acceleration/deceleration curves, ground detection, gravity
  application, jump state machines, character controller references
  Common files: Player.*, CharacterController.*, Movement.*, Locomotion.*

COMBAT SYSTEM:
  Signals: damage calculation functions, health/HP variables, hit detection,
  attack state machines, weapon data structures, damage types/resistances,
  invincibility frames, knockback vectors
  Common files: Combat.*, Weapon.*, DamageSystem.*, Health.*, Attack.*

INVENTORY SYSTEM:
  Signals: item data structures, add/remove item functions, capacity limits,
  item stacking logic, equipment slots, item categories/types
  Common files: Inventory.*, Item.*, Equipment.*, ItemDatabase.*

UI SYSTEM:
  Signals: UI element references, menu state machines, HUD update functions,
  button callbacks, screen transition logic, UI animation triggers
  Common files: UIManager.*, HUD.*, Menu.*, Screen.*, Panel.*

AUDIO SYSTEM:
  Signals: sound effect triggers, music track management, volume controls,
  audio bus routing, spatial audio positioning, adaptive music states
  Common files: AudioManager.*, SoundManager.*, Music.*, SFX.*

SAVE/LOAD SYSTEM:
  Signals: serialization logic, file I/O operations, data persistence,
  save slot management, auto-save triggers, data migration
  Common files: SaveManager.*, SaveLoad.*, GameData.*, Persistence.*

AI SYSTEM:
  Signals: state machines (enemy states), pathfinding calls, behavior trees,
  decision-making logic, perception/detection systems, patrol patterns
  Common files: AI.*, Enemy.*, Behavior.*, StateMachine.*, NPC.*

PROGRESSION SYSTEM:
  Signals: XP/level calculations, unlock conditions, skill trees,
  achievement tracking, milestone checks, difficulty scaling
  Common files: Progression.*, Level.*, Unlock.*, Achievement.*, XP.*

PHYSICS/COLLISION:
  Signals: collision callbacks, physics material references, raycast
  usage, trigger zones, force application, rigid body management
  Common files: Physics.*, Collision.*, Trigger.*, WorldInteraction.*

CAMERA SYSTEM:
  Signals: camera follow logic, zoom controls, screen shake, camera
  bounds, cinematic camera paths, split-screen management
  Common files: Camera.*, CameraController.*, CameraManager.*
-------------------------------------------------

对于每个检测到的系统，记录：

SYSTEM INVENTORY
-------------------------------------------------
System          | Files Involved     | Complexity | Dependencies
-------------------------------------------------
[Movement]      | [file1, file2]     | [low/med/  | [depends on Physics,
[Combat]        | [file1, file2]     |  high]     |  Input, etc.]
[UI]            | [file1, file2]     |            |
...             |                    |            |
-------------------------------------------------

ORPHANED CODE (files that do not belong to any detected system):
  - [file] -- Purpose: [unclear / deprecated / utility / unknown]

MISSING SYSTEMS (expected but not found):
  - [e.g., "No save system detected -- game state is not persisted"]
  - [e.g., "No audio management -- sounds may be ad-hoc or missing"]

---

🚨 阶段 3：机制提取

目标：根据代码行为识别游戏机制，而不只是看代码结构。

机制是支配交互的规则。代码实现机制，但机制本身是一种设计概念。本阶段旨在弥合两者之间的差距。

MECHANICS EXTRACTION
-------------------------------------------------
For each identified system, extract:

MECHANIC: [name, e.g., "Double Jump"]
  Implementation: [file:line -- brief code description]
  Rule: [the game design rule, e.g., "Player may jump once in the air
         after a ground jump. Air jump has 80% of ground jump force."]
  Parameters: [tunable values -- jump force, gravity, cooldown, etc.]
  Interactions: [how this mechanic connects to other mechanics]
  Design intent: [VERIFIED: developer confirmed / INFERRED: based on
                  code behavior / UNVERIFIED: unclear, needs clarification]
-------------------------------------------------

请查找：

• 状态机——每种状态都可能对应玩家或敌人的一种独立行为
• 输入处理程序——每个输入绑定都揭示一项玩家动作
• 碰撞响应——每个碰撞回调都揭示一条交互规则
• 计时器和冷却时间——每个计时器都揭示一项节奏或平衡设计决策
• 常量和配置值——每个可调数值都揭示一个平衡参数

---

📋 阶段 4：依赖关系映射

目标：直观展示各系统之间的交互方式。

DEPENDENCY MAP
-------------------------------------------------
[Movement] ---uses---> [Physics/Collision]
[Movement] ---reads--> [Input]
[Combat]   ---uses---> [Physics/Collision]
[Combat]   ---modifies-> [Health (in Movement entity)]
[UI]       ---reads--> [Health]
[UI]       ---reads--> [Inventory]
[Save]     ---reads--> [all systems with persistent state]
-------------------------------------------------

TIGHT COUPLINGS (potential refactoring targets):
  - [System A] directly modifies internal state of [System B]
    instead of using events/signals. Fragile if either changes.

CIRCULAR DEPENDENCIES:
  - [System A] depends on [System B] which depends on [System A].
    May cause initialization order bugs.

ISOLATED SYSTEMS:
  - [System X] has no dependencies and nothing depends on it.
    Verify: is this intentional or orphaned code?

---

🛠️ 模式 1：设计文档生成（design）

输出：一份逆向工程生成的游戏设计文档。

请参阅 @templates/game-design-document.md，了解规范的 GDD 模板。

# Reverse-Engineered Game Design Document

## Project Overview
- **Project name:** [from project config or directory name]
- **Engine:** [detected engine and version]
- **Genre:** [inferred from mechanics -- e.g., platformer, RPG, puzzle]
- **Estimated scope:** [small/medium/large based on file count and systems]

## Core Mechanics
[For each mechanic extracted in Phase 3, described in design language]

### [Mechanic Name]
**What the player experiences:** [description from player perspective]
**How it works:** [design-level explanation, not code]
**Tunable parameters:** [list of values that affect feel/balance]
**Design intent:** [VERIFIED/INFERRED/UNVERIFIED]

## Game Systems
[For each system detected in Phase 2]

### [System Name]
**Purpose:** [what this system contributes to the player experience]
**Components:** [files and classes involved]
**Key behaviors:** [bullet list of what this system does]
**Dependencies:** [what it needs from other systems]
**Provides to others:** [what other systems consume from it]

## System Interaction Map
[Dependency map from Phase 4, in readable format]

## Identified Gaps
[Missing systems, orphaned code, inconsistencies]

## Balance Parameters
[All tunable values extracted from code, organized by system]

## Recommendations
[Suggestions for design documentation that should be written manually
 to supplement what code analysis can provide -- narrative design,
 art direction, audio design, player onboarding]

---

📊 模式 2：架构决策记录（architecture）

输出：一份记录代码模式和架构选择的架构决策记录。

请参阅 @templates/architecture-decision-record.md，了解规范的 ADR 模板。

# Architecture Overview: [Project Name]

## Technology Stack
- **Engine:** [name and version]
- **Language:** [primary language]
- **Key libraries/plugins:** [detected dependencies]

## Project Structure
[Annotated directory tree from Phase 1]

## Architectural Patterns Detected

### Pattern: [e.g., "Singleton Manager Pattern"]
**Where:** [files using this pattern]
**Purpose:** [why this pattern was likely chosen]
**Trade-offs:** [benefits and risks of this pattern in this context]
**ADR:** We use [pattern] for [reason]. This was likely chosen because
[inferred rationale]. Alternative approaches include [alternatives].

### Pattern: [e.g., "Component-Based Architecture"]
[Same structure]

## System Architecture
[For each system, describe its internal architecture]

### [System Name]
**Architecture:** [pattern used -- state machine, event-driven, etc.]
**Entry points:** [where execution starts for this system]
**Data flow:** [how data moves through the system]
**Extension points:** [where new behavior can be added]
**Coupling assessment:** [tight/loose, and to what]

## Cross-Cutting Concerns
- **State management:** [how game state is managed globally]
- **Event system:** [how systems communicate -- direct calls, signals, events]
- **Error handling:** [how errors are handled -- or not]
- **Configuration:** [how game parameters are stored and loaded]
- **Testing:** [test coverage, testability of architecture]

## Technical Debt Register
[Issues identified during code analysis]
| Area | Issue | Severity | Suggested Fix |
|------|-------|----------|---------------|
| [system] | [problem] | [high/med/low] | [recommendation] |

## Recommendations
[Architectural improvements, refactoring opportunities, scalability concerns]

---

🎭 模式 3：概念文档生成（concept）

输出：一份从可玩原型中提取的游戏概念文档。

请参阅 @templates/game-concept.md，了解规范的概念模板。

# Game Concept Document: [Project Name]
*Reverse-engineered from playable prototype*

## Core Concept
**One-sentence pitch:** [inferred from core mechanics and theme]
**Core verb:** [the primary action the player performs]
**Core loop:** [the repeating cycle of play identified from code]

## Player Experience
**What the player does:** [moment-to-moment gameplay from mechanics]
**What the player feels:** [inferred emotional experience]
**What makes it interesting:** [unique mechanical interactions found]

## Mechanics Summary
[Condensed from Phase 3 -- design-language descriptions only]

## Visual Style
**Art approach:** [inferred from assets -- pixel art, 3D, vector, etc.]
**Color palette:** [extracted from art assets or UI if present]
**Visual complexity:** [minimalist / moderate / detailed]

## Audio Profile
**Music:** [present/absent, style if detectable]
**SFX:** [present/absent, coverage of mechanics]
**Audio completeness:** [placeholder / partial / complete]

## Scope Assessment
**Current state:** [prototype / alpha / beta / near-complete]
**Content volume:** [levels, items, enemies, etc. counted from data]
**Estimated completion:** [what remains to be built for a shippable game]

## Strengths (from code evidence)
[What the prototype does well -- tight mechanics, clean architecture, etc.]

## Gaps (from code evidence)
[What is missing or incomplete -- no save system, no audio, no UI, etc.]

## Recommendations for Full Development
[What to prioritize if taking this prototype to a full game]

质量检查

每次逆向文档整理都必须验证：

QUALITY CHECKLIST
-------------------------------------------------
[ ] Every documented system traces to specific source files
[ ] Ambiguous intent is marked [UNVERIFIED], not guessed
[ ] Orphaned code is identified and listed
[ ] System dependencies are mapped, including circular dependencies
[ ] Inconsistencies between systems are flagged (not hidden)
[ ] All tunable parameters are extracted and listed
[ ] The documentation is organized by game system, not file structure
[ ] Missing expected systems are noted (no save, no audio, etc.)
[ ] The output matches the requested mode (design/architecture/concept)
[ ] File paths are absolute and accurate
[ ] The documentation is useful to someone who has never seen the code
-------------------------------------------------

交叉引用

• @templates/game-design-document.md -- 设计模式输出的模板
• @templates/architecture-decision-record.md -- 架构模式输出的模板
• @templates/game-concept.md -- 概念模式输出的模板
• @docs/coding-standards.md -- 分析期间用于核对的代码规范
• @docs/game-design-theory.md -- 用于描述机制的设计词汇
• @docs/collaboration-protocol.md -- 如何与团队共享逆向文档整理的发现
• 工作流交接：输出会交由 game-design-review 进行验证、 交由 game-code-review 进行架构评估，或交由 game-scope-check 对已记录的系统进行 范围评估

示例用例

1. “我有一个游戏创作马拉松原型，想把它做成正式项目。” 使用概念模式运行。扫描原型，提炼核心概念，找出可行之处和缺失内容，并生成一份可指导完整开发的概念文档。

2. “一位新开发者即将加入，需要了解代码库。” 使用架构模式运行。生成一份架构概览，梳理系统、模式、依赖项和扩展点。新开发者只需阅读文档， 无需逐个文件仔细查找。

3. “我们已经开发了几个月，但从未写过设计文档。” 使用设计模式运行。从代码中提取机制、系统和参数。生成一份 GDD，记录游戏设计的当前状态， 包括在没有文档的情况下开发时出现的缺漏和不一致之处。

4. “记录这个模块，以便我能安全地重构它。” 对特定路径使用架构模式运行。梳理模块的内部结构、 依赖项和耦合点。生成的 ADR 会说明哪些内容可以安全修改， 以及改动哪些内容会导致问题。

5. “我忘了自己为什么要这样构建这个系统。” 对特定系统路径使用设计模式运行。提取机制和参数， 以重建设计意图。标记所有标注为 [UNVERIFIED] 的内容，供开发者在记忆尚未完全淡去时 确认或更正。

属于 AlterLab GameForge 的独立游戏开发技能套件。