使用 Gemini 和 Antigravity 构建一款三消街机游戏

1. 简介

在此 Codelab 中，您将使用 Gemini 3 和 Antigravity 编码代理构建一款名为 CloudCrush 的三消街机游戏。该游戏将使用 Go 语言编写，并使用 Cloud Run 部署到 Google Cloud。

请注意，虽然建议您具备 Go 语言知识，但由于代理会完成所有编码工作，因此您无需具备 Go 语言知识即可参加本次研讨会。此 Codelab 的主要目标是培养您协调代理来为您构建应用（而不是手动编写代码）的技能。

本 Codelab 适合希望学习高级智能体工作流的中级开发者。本实验的预计总时长为 60 分钟。在此 Codelab 中创建的资源采用基于用量的价格。

您将执行的操作

  • 使用 Go 和 Ebitengine 框架构建核心的三消游戏逻辑。
  • 使用 WebAssembly (WASM) 调整游戏，使其可在网络浏览器中运行
  • 将游戏及其高分 API 部署到 Cloud Run。
  • 编排用于测试和代码审核的专用子代理和扩展程序

前提条件

  • 具备编程语言的基础知识
  • 具备云基础设施方面的基本知识
  • 对 Google Cloud 控制台有基本的了解

学习内容

  • 如何使用编码智能体构建复杂的应用
  • 如何在多模态情境中使用 Gemini
  • 如何使用 Cloud Run 将应用部署到云端

所需条件

本研讨会完全可以在云端使用 Cloud Shell 完成，但如果您想使用本地机器，则需要满足以下条件：

  • Antigravity 2.0 和 Antigravity CLI。按照 antigravity.google 中的说明下载并安装该应用
  • Go 工具链（版本 1.26 或更高版本）。按照 go.dev 中的说明下载并安装该工具
  • 用于与 Google Cloud 交互的 gcloud CLI。按照 Google Cloud 文档中的说明下载并安装该工具
  • Google Cloud 结算账号（用于将游戏部署到云端）

关键技术

您可以在这里找到有关我们将使用的技术的更多信息：

2. 环境设置

选择以下选项之一：如果您想在自己的机器上运行此 Codelab，请选择自行设置环境；如果您想完全在云端运行此 Codelab，请选择启动 Cloud Shell。

自定进度的环境设置

  1. 登录 Google Cloud 控制台，然后创建一个新项目或重复使用现有项目。如果您还没有 Gmail 或 Google Workspace 账号，则必须创建一个。

295004821bab6a87.png

37d264871000675d.png

96d86d3d5655cdbe.png

  • 项目名称是此项目参与者的显示名称。它是 Google API 尚未使用的字符串。您可以随时对其进行更新。
  • 项目 ID 在所有 Google Cloud 项目中是唯一的，并且是不可变的（一经设置便无法更改）。Cloud 控制台会自动生成一个唯一字符串；通常情况下，您无需关注该字符串。在大多数 Codelab 中，您都需要引用项目 ID（通常用 PROJECT_ID 标识）。如果您不喜欢生成的 ID，可以再随机生成一个 ID。或者，您也可以尝试自己的项目 ID，看看是否可用。完成此步骤后便无法更改该 ID，并且此 ID 在项目期间会一直保留。
  • 此外，还有第三个值，即部分 API 使用的项目编号，供您参考。如需详细了解所有这三个值，请参阅文档。
  1. 接下来，您需要在 Cloud 控制台中启用结算功能，以便使用 Cloud 资源/API。运行此 Codelab 应该不会产生太多的费用（如果有的话）。若要关闭资源以避免产生超出本教程范围的结算费用，您可以删除自己创建的资源或删除项目。Google Cloud 新用户符合参与 300 美元免费试用计划的条件。

启动 Cloud Shell

虽然可以通过笔记本电脑对 Google Cloud 进行远程操作，但在此 Codelab 中，您将使用 Google Cloud Shell，这是一个在云端运行的命令行环境。

在 Google Cloud 控制台 中，点击右上角工具栏中的 Cloud Shell 图标：

激活 Cloud Shell

预配和连接到环境应该只需要片刻时间。完成后，您应该会看到如下内容：

Google Cloud Shell 终端的屏幕截图，显示环境已连接

这个虚拟机已加载了您需要的所有开发工具。它提供了一个持久的 5 GB 主目录，并且在 Google Cloud 中运行，大大增强了网络性能和身份验证功能。您在此 Codelab 中的所有工作都可以在浏览器中完成。您无需安装任何程序。

3. 项目设置

创建项目目录

首先，我们需要为您的项目创建一个新目录。在终端中，运行以下命令：

mkdir -p codelab-match3 && cd codelab-match3

启动 Antigravity CLI

首先，我们来检查 Antigravity CLI 是否已正确安装。在终端中运行：

agy --version

您应会看到类似下图的界面：

$ agy --version
1.0.2

现在，使用命令 agy 启动 Antigravity CLI：

agy

Antigravity 会询问您是否信任此项目。由于我们刚刚创建了一个空文件夹，因此可以放心地信任它，确认访问权限后，系统会显示 CLI 提示：

da47123c5404f93e.png

如果您看到 Antigravity CLI 提示，则说明一切就绪。否则，请仔细检查您是否遗漏了任何之前的设置步骤。

4. 在规划模式下创建基础游戏

我们先来构建核心的三消游戏逻辑。Antigravity 默认以规划模式启动，因此您无需发出任何特殊命令即可切换到规划模式。

不过，您应该知道，您可以在 Antigravity CLI 提示符中使用斜杠命令 /planning 随时启用规划模式：

/planning

如果您现在尝试运行此命令，Antigravity 会提醒您该功能已在规划中。

8b3d4586b1521c50.png

与规划模式相反的是快速模式，您可以使用 /fast 启用该模式：

/fast

c2a0e2a24ed682cb.png

在快速模式下，Antigravity 会立即开始处理任务，此模式适用于较简单的独立任务。规划模式专为复杂任务而设计，智能体将首先详细制定一个计划，您可以在执行之前查看并迭代该计划。

下载资源

我们需要下载将在游戏中使用的图片。由于这是一个小型独立任务，因此无需在规划模式下高效运转，我们可以利用快速模式立即执行此任务：

Create a folder named "assets" and download the images 
background.png, gcp_sprites.png, gemini.png and logo.png, 
from this GitHub repository to the "assets" folder:
https://github.com/GoogleCloudPlatform/devrel-demos/tree/main/codelabs/gemini-cli/gemini-cli-match3-golang

Antigravity 会请求运行一些 shell 命令来下载文件。完成后，您应该会看到如下内容：

de07f3310951c932.png

创建基础游戏

资源准备就绪后，现在可以构建基础游戏了。由于构建游戏是一项相当复杂的任务，因此在提供提示之前，我们先返回规划模式：

/planning

在规划模式下，将以下提示复制并粘贴到 Antigravity CLI 中：

Build a Match-3 game called 'Cloud Crush' in Go using Ebitengine v2.
The entire game screen should have background.png as background.
The play area should be an 8x8 grid with white background. 
On the right side of the play area include a side panel with UI elements 
like player score and how to play instructions.
The side panel should have a solid background colour to help with readability of the UI.

Use standard GCP product logos (e.g. Compute Engine, Cloud Storage, BigQuery, etc.)
as icons. These icons are provided in the gcp_sprites.png file.

The icons are saved as 64x64 sprites but scale them as necessary
based on the screen resolution. Implement swapping, clearing 3+ gems, and gravity.

Use ebitengine native font rendering (size 48 for titles and size
24 for normal text) for all text and not the debug print.

The font should be monospaced (golang.org/x/image/font/gofont/gomono).
Keep the UI tidy and harmonic, e.g. centered text should always be
adjusted based on text length, not just guess based on estimates.

在制定计划之前，它可能会进行一些探索，例如检查 PNG 文件以查看其尺寸。方案完成后，系统会提示您查看方案：

46096ce2fd4bf219.png

请密切注意右下角，其中显示了“1 个制品”，并提示使用 /artifact 进行检查。在 Antigravity 中，计划、任务列表和演练等支持文件称为“制品”，以区别于解决方案中的常规文件（例如源代码）。

在提示中输入命令 /artifact 后，您将能够查看计划并对其发表评论，以便在需要时进行调整。

/artifact

您应会看到类似下图的界面：

2b5d9881a172ac7c.png

请注意，有一个名为 implementation_plan.md 的文件，其中包含用于打开、批准或拒绝的选项。按 Enter 键即可打开。以下是我的系统上显示的方案示例：

dd8f330bc22acebe.png

您可以使用箭头键向上和向下滚动，并在任意行中按 C 键添加注释。在这种情况下，我不希望它使用旧版 Go，因此我将在第 16 行添加注释，以使用 Go 1.26（撰写本文时的最新版本）：

de728205ab017d1a.png

输入注释后，注释会以内嵌方式显示：

891588cf4488615a.png

需要检查的一个重要部分是“验证计划”。游戏很难自动测试，但 Go 是一种编译型语言，因此我们至少应确保模型向我们提供的代码可以编译。如果未包含用于构建二进制文件的自动化步骤，请以注释的形式添加该步骤：

需要检查的一个重要部分是“验证计划”。游戏很难进行自动化测试，但 Go 是一种编译型语言，因此我们至少应确保模型向我们提供的代码可以编译。如果未包含用于构建二进制文件的自动化步骤，请以注释的形式添加该步骤：

ba395927ab140f17.png

重复此过程，直到您对方案感到满意为止，然后按 ESC 键返回。然后按 Y 确认将评论发送给客服人员：

602addd55412527c.png

按 Y 后，代理会立即开始工作。您需要再按一次 Esc 键才能退出“制品”菜单。这样您就可以返回到提示模式了。与此同时，由于需要运行 shell 命令，智能体可能会要求进行更多工具调用确认。

在等待的同时，我们还可以通过将提示排队来继续处理设计。例如，我们可以借此机会添加原始提示中遗漏的新要求：

Add a 60-seconds countdown timer and an in-memory high-score tracker to enhance the arcade game experience. Combos should give a score bonus of 10% per combo number.

消息记录中会显示一个已排队的提示，前面有一个小箭头：

8093d9113e14792d.png

您可能还会注意到，制品的数量在不断增加。除了方案之外，Antigravity 还会创建一个任务列表 (task.md)，用于跟踪需要实现的每个项目或需要执行的任务。完成后，它会创建一个演练文件 (walkthrough.md)，其中包含对已实现目标的说明。您可以再次使用 /artifact 命令检查所有这些内容。

384ffba82817aa8d.png

以下是完成基本游戏实现后的 task.md 文件示例：

5bf1f31cfef8c725.png

您可以随时打开这些文件并向其中添加注释，这些注释在发送给代理后会像排队的提示一样排队等待执行。建议您在这些文件中添加注释，以便为代理提供有关您请求的更多背景信息。

成功构建二进制文件后，您应该会看到如下内容：

1215f6ba267d9933.png

尝试运行游戏，看看它是否按预期运行。最好在代理提示中高效运转。您可以通过输入感叹号“!”将提示切换为“shell 模式”：

3ed1f93c756154bc.png

您会在提示下方看到“已激活 bash 模式”消息。按 Enter 键运行该命令。在此模式下运行二进制文件的好处是，代理会“监视”终端的任何输出，因此，如果游戏运行失败或突然崩溃，您无需向代理说明发生的问题。它会立即从 shell 上下文中获取所需的所有信息。

761f3c71af5ad842.png

尝试玩游戏并微调游戏参数，直到您对体验感到满意为止（例如，加快或减慢动画速度、调整游戏对命令的响应方式等）。

例如，此提示将通过添加无障碍模式和新的键盘命令来提升体验：

Update the implementation to include: 'Q' to quit, 'F' for full-screen
and 'A' for Accessibility Mode: swap GCP logos for high-contrast coloured blocks.

Also enable Arrow Keys to move the selection cursor and Space to select the gem to 
swap (space is pressed once to select, then arrow key immediately makes 
the move - no need to press space again).

Use a golden square (4 px border, transparent fill) with a simple animation
to highlight where the cursor is at the moment.

完成润饰后，请前往下一部分，将该应用转换为 Web 应用。

5. 调整游戏以在网络浏览器中运行

Ebitengine 游戏目前是桌面应用。我们来让 Antigravity CLI 使用 WebAssembly (WASM) 对其进行调整，以便在 Web 浏览器中运行。这包括为浏览器目标平台编译 Go 代码，以及设置基本的网络服务器。

使用以下提示来引导智能体：

We need to enable this game to run on a web browser. Compile the game to WASM
and create a Go web server to serve the compiled WASM and the assets.

请注意，代理将尝试在文件系统中查找名为 wasm_exec.js 的文件。这是预期行为，您需要允许此操作，因为此文件是允许通过 JS 运行 Go 二进制文件的封装容器。例如：

b9fcf1089f9dce3e.png

当代理完成任务后，您可以指示代理在后台运行游戏服务器。

aa59ec12374a2712.png

现在，在浏览器中打开 http://localhost:8080，即可看到在 Web 上运行的游戏：

5503ee0226f585b5.png

现在，您已在 Web 上运行该应用，接下来只需在将其部署到云端之前进行最后润饰。

6. 创建标题界面和排行榜

游戏可以正常运行，但缺少一些关键功能，无法提供合适的街机体验。我们先来添加一个标题界面，然后添加排行榜，这样你就可以与好友一较高下了！使用以下提示：

Create a title screen that displays the game logo (logo.png) over the cloud background.
The logo should be centered and occupy no more than 75% of the screen area.
The title screen should display "Press ENTER to play" (black/bold) right below the logo,
with every letter animated in a slow wavy (cosine) pattern.
Once the player presses ENTER, it should be prompted to add their name, which 
will then be recorded to populate the leaderboard at the end of the round.

Once the game is over, play the animated leaderboard with the top 10 highest scores.
The animated leaderboard should render entries one by one up to 10 entries, 
using a fade in effect just like old school arcade games. The leaderboard
should fade out to the title screen after 15 seconds.

Please note that name entry should be processed independently of the play state
key handlers (e.g. pressing A during name entry should not toggle accessibility mode).

Leaderboard scores should be saved in-memory, server-side.

现在看起来更专业了！🙂

7. 将游戏部署到 Cloud Run

现在，终于可以与全世界分享我们的作品了！我们将整个应用部署到 Google Cloud Run，以便能够从任何位置访问该应用。

Use the gcloud CLI to provision and deploy the Go web server and its assets to 
Google Cloud Run. Provide the live URL when complete.

既然游戏已在云端上线，如果不允许其在移动设备上运行，那将错失良机。您可以使用以下提示来完成此操作：

Now enable this game to run on mobile devices. You need to update the input system to handle "taps" as well as key presses and clicks. Since mobile devices most likely won't have a keyboard, add a virtual keyboard to the name entry screen and a confirmation button to the name entry.

Finally, generate a QR code for the CloudRun link and display it on the screen so that people can scan it to access the mobile version and compete against their friends for the high score.

在浏览器中重新运行游戏。尝试从移动设备访问该网址（您可能需要生成二维码来简化此体验）。

8. 使用浏览器代理测试游戏

虽然游戏通常很难自动测试，因为它依赖于视觉反馈，但我们仍然可以利用一些自动化功能，至少确保部署正常运行，并且我们已准备好基本元素。

为此，我们将使用浏览器子代理。在 Antigravity 中，子代理是一个具有全新上下文的独立角色，非常适合以下任务：您不希望当前上下文影响结果，或者您希望防止任务“污染”主上下文窗口。

浏览器代理是一种特殊的内置代理，用于处理与浏览器相关的任务。请注意，仅在此步骤中，我们需要使用 Antigravity 桌面应用，因为浏览器代理目前无法在命令行中使用。

打开 Antigravity 桌面应用，然后在 Cloud Crush 项目中开始新的对话：

324c7b8633dc46d9.png

您可以输入 /browser，然后输入以下提示，以触发浏览器分代理：

Go to http://localhost:8080 and capture screenshots of the following game screens:
1. Title Screen (initial state: "PRESS ENTER TO PLAY")
2. Name Entry Screen (press Enter to reach this screen)
3. Main Gameplay Screen (type a name like "PLAYER" and press Enter to start)
4. Leaderboard Screen (let the game timer run out to view the high scores)

这种方法使我们能够使用屏幕截图来修复仅用文字难以描述的界面元素。

您可以使用“@”符号后跟文件名来引用文件。例如，以下是我要求代理增大标题画面上的徽标大小：

5c18bde16b58fc8.png

虽然此示例有些牵强，因为模型不一定需要“看到”图片才能应用 50% 的尺寸校正，但它是一种有用的技术，可用于进行界面调整，而以文本形式描述问题可能比较困难。它还允许代理通过拍摄前后的屏幕截图来验证自己的工作，因此请将此技巧添加到您的工具箱中。

9. 创建用于保护游戏的自定义代理

“氛围编码”应用的一个常见问题是如何从编码和安全角度保持高质量和最佳实践。虽然您可以尝试改进提示，使提示在这两个方面都非常严谨，但提示内容越多，代理的专注度就越低，这通常会导致结果欠佳。

对于此类场景，使用子代理非常理想，因为它们可以专注于您分配给它们的任务。我们来创建一个自定义代理，对这段代码进行安全审核，确保我们在部署这款游戏时不会泄露任何凭据，也不会让自己面临不必要的风险。

此提示为代理提供了一个良好的基准：

create a new subagent called "security_auditor" using the following instructions:

You are a ruthless Security Auditor. Your job is to analyze code for potential vulnerabilities.

Focus on:
1.  SQL Injection
2.  XSS (Cross-Site Scripting)
3.  Hardcoded credentials
4.  Unsafe file operations

When you find a vulnerability, explain it clearly and suggest a fix. Do not fix it yourself; just report it.

请注意，Antigravity 将使用“DefineSubagent”工具创建新代理：

63cde28b749d4e81.png

使用以下提示让代理对游戏代码执行安全检查：

Run the security auditor agent in this code

您应会看到类似下图的界面：

5563a8169e106701.png

智能体完成任务后，您应该会看到如下报告：

6df39e15635a7cd7.png

让我们让 Antigravity 为我们修复这些问题 🙂：

Fix these findings for me please!

大功告成：

93a3331df80a7d7f.png

请注意，以这种方式创建的代理仅在对话期间存在。如果您希望代理在会话之间“可重复使用”，可以使用配置文件来创建代理。如需了解详情，请参阅 /agents 命令。

10. 总结

恭喜！您已成功使用 Antigravity CLI 构建、部署、测试和审核了一款街机游戏，展示了从初始框架搭建到部署的高级代理工作流。

清理

为避免系统向您的 Google Cloud 账号持续收取费用，请删除本 Codelab 中创建的资源。

  1. 删除 Cloud Run 服务：
I'm finished with this project. Delete the cloud run deployment.
  1. 删除项目目录：
cd .. && rm -rf codelab-match3

或者，如果 Google Cloud 项目是专门为本 Codelab 创建的，您可以删除整个项目。

后续步骤

您可以继续探索此平台中的其他 Codelab，也可以自行改进 Cloud Crush，但请务必在完成操作后清理资源！

祝大家编码顺利！