---
name: qxqy-game-studio
description: 按策划案、TDD 测试用例、HTML 效果展示、千星美术参考图与素材、Lua 实现、测试、真机试玩与修复七步制作千星奇域 2D+Lua 游戏；不用于 3D 节点图。
---

# 千星 2D+Lua 游戏工作室

目标是交付可在千星奇域真机运行的 Lua 游戏与完整存档。本工作流可供不同 AI 工具读取；模拟器操作以当前宿主实际提供的 MCP 或 Harness 工具为准。

## 按需读取

首次进入或恢复会话先读 [接入与恢复](references/workflow.md)，检查工作区及当前 AI 配置中的知识库来源和实际可用性，确定一个当前步骤，再只读取下表对应文档。步骤切换时读取下一份；遇到缺项再回读相关步骤，不预先加载七份全文。

新游戏按 1→7 推进；已有工程从最早缺失的证据继续，窄修复不重做无关步骤。`PREFLIGHT` 只负责盘点已有工程、资料和能力，不计入七步。

| 当前步骤 / 何时读取 | 产物与完成条件 |
|---|---|
| [1. 策划案](references/01-game-design.md)：创意尚未明确为玩法规则 | GDD 明确核心循环、输入、胜负、P0 范围和风险。 |
| [2. TDD 制定测试用例](references/02-test-cases.md)：规则明确，需定义预期或补回归用例 | 规则到用例的追踪、操作与可观察结果、静态/schema 检查。 |
| [3. HTML 效果展示](references/03-html-prototype.md)：需要确认画面、操作与节奏 | 可打开试玩的演示、用户反馈和不可移植项。 |
| [4. 千星美术参考图和素材](references/04-art-assets.md)：HTML 体验已确认，需准备正式美术 | 参考图、素材清单、官方 imageId / 图元与 UI 还原方案。 |
| [5. Lua 编码实现](references/05-lua-implementation.md)：需搭建、实现或修复游戏 | Lua、完整存档、挂载/架构说明和 Red→Green→Regress 记录。 |
| [6. 测试](references/06-simulator-testing.md)：已有可运行版本，需验证规则与体验 | 用例、模拟器试玩/截图、设备布局与缺陷回归结果。 |
| [7. 真机试玩验证与 bug 修复](references/07-device-validation.md)：准备交付或处理真机回传 | 导入/挂载与索引校准、脚本目录绑定和更新交接、真机结果及未验证项。 |

## 贯穿各步骤的约束

- 步骤 2 在 HTML 之前，步骤 4 在 HTML 之后；步骤 1–4 不打开模拟器、不改存档、不运行 `runCase`。有效 TDD Red 要等步骤 5 的可运行骨架缺少目标生产行为；路径、JSON 和工具故障不算 Red。
- 启动前按 PREFLIGHT 查找已配置的 `miliastra-toolbox` 系列、其他知识库服务或本地文档，遵守 `AGENTS.md`，核验能否读到所需官方 2D/Lua API 与指南。已有资料直接复用，仅询问缺项；不从普通 Lua/UI 或 3D 节点经验猜接口。
- HTML 用于体验沟通；模拟器验证规则、布局与交互；真机证据验证平台实际行为。每条结果区分 `runtime=html|simulator|device`，模拟器绿灯不等于真机通过。
- 官方素材可以用；模拟器只预览 `100001–100006` 六种基础图元，其余图片显示缺失框，记录目标 ID 并在真机核验。千星原点左下、Y 向上，不能直接搬 HTML/CSS 坐标。
- 操作前检查实际工具与 schema；有 `qxqy-simulator` 操作 Skill 时按需读取，其他宿主使用相应接入指南。没有可用模拟器工具时可继续步骤 1–4，不能声称通过模拟器或真机验证。

## 决策与交接

只在玩法语义、HTML 体验、真正不同的美术方向与真机结果需要用户判断时提问。实现细节、路径、断言和控件拆分自行处理，不反复问“是否继续”。

以 `docs/production-plan.md` 记录当前步骤、退出证据、阻塞项；以 `records/playtest.md` 记录实际结果与来源。恢复与跨步骤回退规则见 [workflow.md](references/workflow.md)；阶段操作细节只在对应步骤文档维护。