game-start

AlterLab GameForge——项目入门工作流

每个游戏项目都有一个起点，但起点的样子并不总是一样。你可能正面对一个空文件夹，除了满腔热情什么都没有。你可能有一份厚厚的设计文档，却一行代码也没写。你也可能刚接手一个别人六个月前开始编写的代码库。这个工作流会判断你目前的状态，让你马上行动起来，避免在已经完成的步骤上浪费时间。

核心理念：从项目的实际情况出发。诊断当前状态，补上缺口，并指出下一个有意义的行动。Hollow Knight 最初只是一次游戏 Jam 的草图。Stardew Valley 最初是一个学习练习。Undertale 最初是一个受 EarthBound 启发的演示。它们都没有遵循教科书所谓的“正确”起点——但每个项目都经历过一个时刻：零散的热情开始转化为有条理的执行。这个工作流就是为了把握这一刻。

目的与触发条件

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

• 开发者说“我想开始做一款新游戏”或“帮我搭建项目”
• 有人加入现有项目，需要熟悉项目情况
• 团队想检查当前项目结构是否健康
• 独立开发者有一堆零散文件，希望整理成适合投入生产的结构
• 在游戏开发场景中，有人问“我到底该从哪里开始？”

解决的问题：

• 新项目开始时的分析瘫痪
• 随项目规模扩大而变得难以管理的混乱文件结构
• 导致后续困惑的文档缺失
• 跳过基础决策，导致项目从第一天起就背上技术债
• 新团队成员花上好几天才弄清楚各项内容的位置

关键规则

1. 绝不覆盖已有成果。 如果项目中已经有文件、结构或文档， 就要保留。可以建议重新整理，但未经明确确认，绝不删除。

2. 先检测，再建议。 在提出行动建议前，始终先扫描项目状态。 不要假设项目是空的，也不要假设现有项目组织得井井有条。

3. 确认前不预设引擎。 如果无法从项目文件中检测到引擎，就要询问。 不要猜。错误地假设引擎会浪费大量时间。

4. 文档不是可选项。 每个项目至少需要：概念文档、技术架构说明和任务跟踪系统。这些并非官僚主义——它们是未来的你迫切需要的记忆。ConcernedApe 在 Stardew Valley 的开发过程中一直维护着一份设计文档，即使他是独立开发者也不例外。这份文档避免了长达四年的开发工作偏离方向。

5. 从一开始就要诚实评估项目范围。 如果有人描述了一个需要 200 小时的项目，却说自己只有 3 个周末，就要立即指出这一点。语气要友善，但必须立即指出。独立游戏的废弃项目堆里，满是那些两年来一直“快做完了”的项目。

6. 遵循共享标准。 所有结构决策都应符合 docs/collaboration-protocol.md 中记录的规范。所有设计术语都应遵循 docs/game-design-theory.md。

项目检测（自动填充）

这些值会在技能内容到达 Claude 之前，通过 shell 预处理自动注入。 它们提供实时项目数据，让状态检测从事实出发， 而非基于假设。

• 引擎：!ls project.godot *.unity *.uproject 2>/dev/null | head -1 || echo "No engine project file detected"
• Git 状态：!git log --oneline -5 2>/dev/null || echo "No git history"
• 源文件数量：!find . -name "*.gd" -o -name "*.cs" -o -name "*.cpp" -o -name "*.h" -o -name "*.rs" -o -name "*.js" 2>/dev/null | wc -l
• 现有文档：!ls -1 docs/ 2>/dev/null || echo "No docs directory"
• 设计目录：!ls -1 design/ 2>/dev/null || echo "No design directory"
• 测试目录：!ls -1 tests/ 2>/dev/null || echo "No tests directory"
• 构建配置：!ls Makefile CMakeLists.txt SConstruct *.sln package.json Cargo.toml 2>/dev/null | head -3 || echo "No build config detected"
• 项目历史时长：!git log --reverse --format="%ar" 2>/dev/null | head -1 || echo "Unknown — no git history"
• 活跃贡献者：!git shortlog -sn --no-merges 2>/dev/null | head -5 || echo "Unknown — no git history"
• TODO/FIXME 数量：!grep -r "TODO\|FIXME\|HACK\|XXX" src/ 2>/dev/null | wc -l || echo "0"

使用这些自动填充的数据，跳过下方的步骤 0。如果引擎字段显示检测到了项目文件，则跳过引擎检测提示。如果源文件数量为零，则处于状态 1（空项目）。如果源文件数量不为零，但文档目录为空，则项目可能存在文档缺口。Git 历史时长和贡献者数量有助于区分个人开发项目和团队项目，这会影响建议的工作流复杂度。

工作流

步骤 0：项目状态检测

在提出任何建议之前，先扫描以下信号以评估当前状态。 结合上方的自动填充数据进行判断——其中许多问题可能已经有了答案。

STATE DETECTION MATRIX
---------------------------------------------------------------
Signal                          | Indicates
---------------------------------------------------------------
No files / empty directory      | State 1: Empty Project
Design docs but no source code  | State 2: Concept Exists
Source code + design docs       | State 3: In-Progress
Mature codebase + CI + tests    | State 4: Existing Project
---------------------------------------------------------------

Engine Detection Signals:
- project.godot, *.gd, *.tscn        --> Godot Engine
- *.unity, *.cs, ProjectSettings/     --> Unity
- *.uproject, *.cpp + UE macros       --> Unreal Engine
- package.json + Phaser/PixiJS        --> Web-based engine
- Cargo.toml + Bevy/macroquad         --> Rust-based engine
- No recognizable engine files        --> Ask the user

运行检测并报告结果，然后转到相应的状态处理流程。

---

状态 1：空项目

一张白纸。大多数个人开发者和小团队都从这里开始。

步骤 1.1 -- 选择引擎（如果尚未决定）：

• 如实说明取舍，避免盲目推崇某个引擎
• 对于 2D 像素艺术：Godot 轻量且便于快速制作原型——Cassette Beasts 和 Dome Keeper 证明它能够打造商业品质的游戏
• 对于需要素材商店的 3D 项目：Unity 拥有最广泛的生态系统和最多的学习资源
• 对于 AAA 级画面：Unreal 能够胜任，但需要更强的硬件和专业知识
• 对于网页分发：Phaser、PixiJS 或 PlayCanvas
• 最好的引擎就是团队已经熟悉的引擎。相比糟糕的引擎选择，项目中途切换引擎毁掉的游戏更多
• 选择后，转到相应的引擎专家技能

步骤 1.2 -- 定义概念（如有需要，转到 game-brainstorm）：

• 至少记录：暂定名称、类型、平台、核心机制、目标受众
• 如果用户已有概念，则以结构化格式记录
• 如果用户没有概念，则在继续之前转到 game-brainstorm

步骤 1.3 -- 创建初始文件结构：

以下是建议的通用起始结构。请根据引擎进行调整。

project-root/
  design/
    gdd/                  -- Game Design Document and sub-documents
    narrative/            -- Story outlines, dialogue scripts, lore bibles
    levels/               -- Level layouts, progression maps, zone designs
    balance/              -- Economy spreadsheets, difficulty curves, tuning tables
  docs/
    architecture/         -- Technical architecture decisions and diagrams
    api/                  -- Internal API documentation for game systems
  src/
    core/                 -- Engine initialization, main loop, global managers
    gameplay/             -- Player mechanics, enemy behaviors, interaction systems
    ai/                   -- NPC behavior trees, pathfinding, decision-making
    ui/                   -- Menus, HUD, in-game UI components
    tools/                -- Editor extensions, debug tools, dev utilities
  assets/
    art/                  -- Sprites, textures, models, animations
    audio/                -- Music tracks, sound effects, ambient loops
    vfx/                  -- Particle systems, shader effects, post-processing
    shaders/              -- Custom shader files
    data/                 -- JSON/XML config files, localization strings, data tables
  tests/
    unit/                 -- Isolated component tests
    integration/          -- System interaction tests
    playtest/             -- Playtest session logs and feedback forms
  production/
    sprints/              -- Sprint plans, retrospectives, velocity charts
    milestones/           -- Milestone definitions and completion criteria
  prototypes/             -- Throwaway prototypes (never promote to production code)

引擎特定的替代方案：

• **Godot 项目：**适用标准的 Godot 布局：scripts/、scenes/、resources/、addons/。design/、docs/ 和 production/ 目录放在项目根目录，与 project.godot 并列。
• Unity 项目：Assets/Scripts/、Assets/Prefabs/、Assets/Scenes/。design/、docs/ 和 production/ 目录放在项目根目录，与 Assets/ 并列。
• Unreal 项目：Source/、Content/、Config/。design/、docs/ 和 production/ 目录放在项目根目录。 这种结构是建议，而非要求。GameForge hooks 会检测多个常规位置（src/、scripts/、Scripts/、Source/、Assets/Scripts/、lib/）中的源代码。如果项目已有结构，请保留它——在合适的位置添加 design/、docs/ 和 production/ 叠加目录。

步骤 1.4 -- 生成入门文档：

• 创建一份精简的游戏概念文档（参考 templates/game-concept.md）
• 创建一份技术架构说明，阐明引擎选择理由
• 创建一份 TODO.md，列出近期后续步骤
• 根据所选引擎设置基本的 .gitignore

步骤 1.5 -- 建议后续步骤：

• 如果游戏概念还不够完善，运行 game-brainstorm 进一步完善
• 确定 3-5 个设计支柱（方法论请参考 docs/game-design-theory.md）
• 构建首个一次性原型，测试核心机制
• 估算范围，并使用 game-sprint-plan 规划第一个冲刺

---

状态 2：已有概念（有文档，无代码）

用户已考虑过游戏设计，但尚未开始构建。

步骤 2.1 -- 审查现有文档：

• 阅读所有设计文档并评估其完整性
• 对照 8 个必需的 GDD 章节进行检查（参考 docs/game-design-theory.md）
• 找出定义完善的内容和存在缺漏的内容

步骤 2.2 -- 差距分析：

• 标出缺失的章节：核心循环定义、支柱陈述、范围估算、 技术要求、美术风格参考、音频方向、UI 线框图、进度系统
• 将每项差距评为关键（阻碍开发）、重要（之后会造成困惑） 或可有可无（润色项）

步骤 2.3 -- 结构评估：

• 文档是否按标准结构组织，还是散落各处？
• 如果散落各处，建议按 design/ 层级重新组织
• 检查文档之间是否存在矛盾

步骤 2.4 -- 建议后续行动：

• 优先填补关键缺漏（通常是：核心循环和技术架构）
• 交由 game-design-review 对设计文档进行全面审查
• 如果尚不存在，请按照状态 1 的步骤 1.3 创建文件结构
• 确定开始编写代码的合适时机（通常是在定义核心循环并详细说明一个支柱机制之后）

---

状态 3：进行中（有代码和文档）

开发工作正在进行。目标是评估项目状况并建议优先事项。

步骤 3.1 -- 扫描代码库：

• 统计源文件数量，估算项目规模
• 找出主要语言和引擎
• 检查是否有测试文件（是否进行了任何测试？）
• 查找配置文件、构建脚本和 CI 设置
• 扫描代码库中的 TODO、FIXME、HACK，并报告数量

步骤 3.2 -- 文档覆盖情况：

• 是否存在 GDD？完整度如何？
• 是否有技术文档？
• 复杂系统是否有行内代码注释？
• 是否有帮助新贡献者快速上手的 README？

步骤 3.3 -- 结构健康状况：

• 文件结构是否组织合理？
• 是否有需要拆分的庞大上帝文件？
• 游戏逻辑与引擎专属代码是否分离？
• 资源是否经过整理，还是都堆放在扁平目录中？

步骤 3.4 -- 优先级建议：

• 按影响对发现的问题排序：哪些问题最可能在近期造成麻烦？
• 如果结构存在问题，建议具体的重构目标
• 建议能在下个月节省时间的文档任务
• 如果没有测试，建议从最关键的系统开始

---

状态 4：现有项目（成熟代码库）

这是一个成熟稳定的项目。目标是进行坦诚的审计，而非走过场。

步骤 4.1 -- 架构审计：

• 梳理高层架构：有哪些系统，它们如何通信？
• 检查依赖方向：是否存在循环依赖？
• 评估状态管理模式：是清晰的状态机，还是一团布尔变量？
• 评估数据管线：游戏玩法数值是由数据驱动，还是硬编码？ 步骤 4.2 —— 文档审计：
• 对文档覆盖率进行 0% 至 100% 的评估：有多少系统具备文档？
• 检查文档的新鲜度：文档是否与当前情况一致，还是描述着 6 个月前的游戏？
• 找出风险最高的未文档化系统（复杂度最高、文档最少）

步骤 4.3 —— 技术健康检查：

• 评估测试覆盖率：哪些内容经过测试，哪些没有？
• 扫描性能：关键路径上是否存在明显问题？
• 审计依赖项：是否存在过时的软件包或安全问题？
• 检查构建状态：项目能否顺利构建？是否有被忽略的警告？

步骤 4.4 —— 建议：

• 按投入与影响对行动列表进行优先级排序
• 聚焦风险：最有可能导致生产事故的是什么？
• 提出流程改进建议（CI、测试、代码审查实践）
• 找出应在下一个重要功能开发前处理的技术债务

输出格式

该工作流会生成一份项目状态报告，结构如下：

# Project State Report
**Project:** [name]
**Date:** [date]
**Detected State:** [Empty / Concept / In-Progress / Existing]
**Engine:** [detected or user-specified]

## Current State Assessment
[Summary of what was found]

## Completed Items
- [What is already in good shape]

## Gaps & Issues
| Item | Severity | Category | Recommended Action |
|------|----------|----------|-------------------|
| ...  | Critical | Docs     | ...               |

## File Structure
[Current structure vs. recommended structure, with specific changes needed]

## Recommended Next Steps
1. [Highest priority action]
2. [Second priority]
3. [Third priority]

## Suggested Workflow Sequence
- [ ] [First workflow to run, e.g., game-brainstorm]
- [ ] [Second workflow, e.g., game-design-review]
- [ ] [Third workflow, e.g., game-sprint-plan]

质量标准

成功的项目接入需满足以下所有条件：

• 检测到的状态准确反映实际情况（没有错误假设）
• 每个关键缺口都已识别，并附有具体的建议措施
• 文件结构已创建，或已提供重组计划
• 用户清楚知道下一步该做什么——没有歧义
• 针对引擎的指导与实际使用的引擎相符
• 建议的工作流顺序合理且可执行
• 对后续步骤的时间估算诚实，不盲目乐观
• 报告针对该项目量身定制，而非泛泛而谈的模板内容

示例用例

1. “我想制作我的第一款游戏。” 检测到空项目后，询问引擎偏好和游戏概念，搭建完整的目录结构，创建初始文档，并转交给 game-brainstorm。

2. “我有一份 GDD，但还没开始编写代码。现在该做什么？” 检测到状态 2，检查 GDD 的完整性，找出缺口，建议在编写代码前补齐关键章节，并建议何时开始制作原型。

3. “我接手了队友离职后留下的项目。帮我了解一下。” 检测到状态 4，执行完整的架构审计，梳理各个系统，找出未文档化的部分，并为新开发者编写入门指南。

4. “我们有一个原型，但它越来越混乱。该重构结构吗？” 检测到状态 3，扫描代码库中的结构问题，统计 TODO 和 FIXME，评估测试覆盖率，并提出具体的重构优先事项。

5. “为一款 2D roguelike 新建一个 Godot 项目。” 检测到空项目以及已知的引擎和游戏类型后，按照 Godot 特定惯例创建目录结构，生成包含 roguelike 相关章节的概念文档框架，并转交给 Godot 引擎专家提供设置指导。