这一页讲的是和 AI 工具合作开发游戏的完整方法。如果你还没有跑通第一个游戏，先去看 90 分钟课堂版。

01. 什么是 arcade-ai skill

arcade-ai skill 是一份给 AI 看的说明文件（不是给你看的手册）。它告诉 AI：

  • 用哪些命令初始化项目和启动编辑器
  • 改代码之前要读哪些文档
  • 哪些 API 存在，哪些是 AI 常犯的错误
  • 如何检查编译结果

装了 skill，AI 才知道怎么正确做游戏。没有它，AI 很可能写出"看起来合理但 MakeCode 根本运行不了"的代码。

02. 两种安装方式

方式 A：一行命令（推荐）

在终端里运行（需要 Node.js）：

npx arcade-ai init my-game --tool claude

把 claude 换成你用的工具：

AI 工具 填写 生成的规则文件
Claude Code claude CLAUDE.md
Codex codex AGENTS.md
WorkBuddy workbuddy AGENTS.md
Trae trae .trae/rules/

命令运行后，AI 工具打开 my-game/ 目录时会自动读取规则文件，skill 就生效了。

之后让 AI 帮你跑剩下的命令（启动 Studio、初始化模板等），不需要你自己操作。

方式 B：直接把 skill 内容贴给 AI

不想跑命令，或者用的是网页版 AI 工具：

  1. 打开 https://raw.githubusercontent.com/guolin/arcade-ai/main/SKILL.md
  2. 全选复制内容
  3. 粘贴到 AI 对话框开头，然后说：
请根据以上 arcade-ai skill，帮我创建一个 MakeCode Arcade 游戏。
项目名叫 my-game，用 platformer 模板。
先把环境搭好，启动本地 Studio，我再告诉你游戏主题。

AI 会自己运行 npx arcade-ai init、npx aca dev，所有命令由它来跑。

03. 和 AI 对话的方法

开始前：让 AI 主动读文档

skill 里要求 AI 在改代码前先读 reference/ 里的文档。你不需要记文档内容，但可以提醒 AI：

帮我加功能之前，先读一下 reference/pitfalls.md 和 
reference/arcade-api.md，确认 API 用法再写。

小步迭代，每次一个功能

❌ 这样容易得到你看不懂的大段代码：

帮我做一个完整的冒险游戏，有 3 关、Boss、道具和排行榜。

✅ 这样容易测试、容易理解：

在现在的游戏里加一种新敌人：
从屏幕右边出现，向左移动，碰到玩家扣 1 条命，
飞出左边屏幕后自动消失。
加完后解释你用了哪些 API。

主题设计先于写代码

让 AI 帮你设计玩法，确认了再动代码：

我想把这个躲避游戏改成"心理健康"主题。
先帮我设计：游戏标题、3 种可收集物、2 种障碍物、胜利条件。
不要写代码，先出方案让我选。

选完方案再说"好，按这个方案改代码"。这样不会写一半又推翻。

让 AI 解释它的改动

每次改完之后：

用一两句话解释你改了什么，我需要在面试里讲出来。

你不需要背代码，但要能说出"这里是控制苹果掉落的，那里是碰撞加分的"。

04. 调试：让 AI 读报错

改完代码等约 30 秒，AI 会自动检查 game/.aca-status。如果有报错，把它发给 AI：

.aca-status 里有报错，帮我修一下：

[粘贴报错内容]

不需要你自己看懂报错。MakeCode 编译器的报错信息很精确，AI 对照 reference/pitfalls.md 基本都能直接修对。

常见的 AI 自己会犯的错（skill 里有列出）：

  • sprite.flipX = true → 实际要用 sprite.setFlag(SpriteFlag.FlipX, true)
  • info.lives → 实际要用 info.life()
  • sprites.allOfType() → 实际要用 sprites.allOfKind()

AI 读了 skill 之后会避开这些，但如果还是报错，让它对照 pitfalls.md 自查。

05. 什么代码不要直接用

就算 AI 写了，你也要小心这些：

完全看不懂的大段代码：你在 Review 面试里需要解释核心逻辑。如果一行都看不懂，让 AI 先解释再继续。

MakeCode 不支持的语法：

  • fetch()、document、window（浏览器 API）
  • async/await、Promise
  • Node.js 的 fs、path

AI 装了 skill 后一般不会写这些，但如果出现，让它重写。

06. AI 面试会问什么

通过 Review 推荐后会有一次简短面试，常见问题：

  • 你的游戏怎么赢，怎么输？
  • 玩家、敌人、道具分别是什么 SpriteKind？
  • 哪段代码控制分数？哪段控制生命？
  • AI 帮你改了什么？你自己做了什么决定？
  • 如果要把胜利分数从 20 改成 30，改哪里？

准备方法：每次让 AI 改完代码，让它用一两句话解释改了什么，你自己复述一遍确认能说清楚。

07. 开发日志怎么写

每次 AI 帮你做了一个改动，写一篇日志：

标题：加了金色苹果

我想让游戏更有奖励感，让 AI 加了金色苹果。
AI 用 onUpdateInterval 做定时生成，用 onOverlap 检测碰撞加 5 分。

第一次苹果出现太频繁，我让 AI 把间隔从 5 秒改到 10 秒，好多了。

我学到的：普通苹果和金色苹果可以都是 Food 类型，用不同图片区分。
下次想把金色苹果改成"好心情能量球"，配套换图。

三篇这样的日志 + Share 链接，就可以提交 Review 了。

准备好提交了吗？

有这些，去 提交项目与审核：

  • ✅ 至少 3 篇开发日志
  • ✅ MakeCode Share 链接（https://makecode.com/_xxxxxx）
  • ✅ README（游戏叫什么、怎么玩、AI 帮了什么）
  • ✅ 能说出游戏的胜负条件和核心代码在哪里