使用 Gemini 和 Antigravity 建構三消街機遊戲

1. 簡介

在本程式碼研究室中，您將使用 Gemini 3 和 Antigravity 編碼代理程式，建構配對 3 街機遊戲 CloudCrush。遊戲會以 Go 語言編寫，並使用 Cloud Run 部署至 Google Cloud。

請注意，雖然建議具備 Go 語言知識，但由於代理程式會完成所有程式碼編寫作業，因此不一定要有相關知識才能參加本研討會。本程式碼研究室的主要目標是培養代理程式的協調技能，讓代理程式為您建構應用程式，而不必手動編寫程式碼。

本程式碼研究室適用於想瞭解進階代理程式工作流程的中階開發人員。本實驗室的預估總時長為 60 分鐘。本程式碼研究室建立的資源會採用根據用量計費的模式。

學習內容

  • 使用 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. 環境設定

請選擇下列其中一個選項：如要在自己的電腦上執行本程式碼研究室，請選取「Self-paced environment setup」(自訂進度的環境設定)；如要完全在雲端執行本程式碼研究室，請選取「Start Cloud Shell」(啟動 Cloud Shell)。

自修實驗室環境設定

  1. 登入 Google Cloud 控制台，然後建立新專案或重複使用現有專案。如果沒有 Gmail 或 Google Workspace 帳戶，請先建立帳戶。

295004821bab6a87.png

37d264871000675d.png

96d86d3d5655cdbe.png

  • 專案名稱是這個專案參與者的顯示名稱。這是 Google API 未使用的字元字串。你隨時可以更新。
  • 專案 ID 在所有 Google Cloud 專案中都是不重複的，而且設定後即無法變更。Cloud 控制台會自動產生專屬字串，通常您不需要在意該字串為何。在大多數程式碼研究室中，您需要參照專案 ID (通常標示為 PROJECT_ID)。如果您不喜歡產生的 ID，可以產生另一個隨機 ID。你也可以嘗試使用自己的名稱，看看是否可用。完成這個步驟後就無法變更，且專案期間會維持不變。
  • 請注意，有些 API 會使用第三個值，也就是「專案編號」。如要進一步瞭解這三種值，請參閱說明文件。
  1. 接著，您需要在 Cloud 控制台中啟用帳單，才能使用 Cloud 資源/API。完成這個程式碼研究室的費用不高，甚至可能完全免費。如要關閉資源，避免在本教學課程結束後繼續產生費用，請刪除您建立的資源或專案。Google Cloud 新使用者可參加價值$300 美元的免費試用計畫。

啟動 Cloud Shell

雖然可以透過筆電遠端操作 Google Cloud，但在本程式碼研究室中，您將使用 Google Cloud Shell，這是可在雲端執行的指令列環境。

在 Google Cloud 控制台中，點選右上角工具列的 Cloud Shell 圖示：

啟用 Cloud Shell

佈建並連線至環境的作業需要一些時間才能完成。完成後，您應該會看到如下的內容：

Google Cloud Shell 終端機的螢幕截圖，顯示環境已連線

這部虛擬機器搭載各種您需要的開發工具，並提供永久的 5GB 主目錄，而且可在 Google Cloud 運作，大幅提升網路效能並強化驗證功能。您可以在瀏覽器中完成本程式碼研究室的所有作業。您不需要安裝任何軟體。

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. 在規劃模式中建立基礎遊戲

首先，我們來建構核心的 Match-3 遊戲邏輯。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)，追蹤需要實作的每個項目或需要執行的動作。完成後，Antigravity 會建立導覽檔案 (walkthrough.md)，說明達成的目標。您可以再次使用 /artifact 指令檢查所有這些項目。

384ffba82817aa8d.png

以下範例顯示完成基本遊戲實作後，task.md 檔案的內容：

5bf1f31cfef8c725.png

您隨時可以開啟這些檔案並新增註解，傳送給服務專員後，系統會將這些檔案排入執行佇列，就像排入佇列的提示一樣。建議您在這些檔案中加上註解，為服務專員提供有關要求的其他背景資訊。

成功建構二進位檔後，您應該會看到類似以下的內容：

1215f6ba267d9933.png

嘗試執行遊戲，看看是否正常運作。建議您從代理程式提示中運作執行這項操作。輸入驚嘆號「!」即可將提示切換為「殼層模式」：

3ed1f93c756154bc.png

提示下方會顯示「已啟用 Bash 模式」訊息。按下 Enter 鍵執行指令。以這種模式執行二進位檔的好處是，代理程式會「監看」終端機的任何輸出內容，因此如果遊戲無法執行或突然當機，您不需要向代理程式說明發生的問題。這樣一來，殼層環境中的所有必要資訊都會立即提供給該函式。

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.

完成潤飾後，請前往下一節，將其轉換為網頁應用程式。

5. 調整遊戲，使其可在網路瀏覽器上執行

Ebitengine 遊戲目前是電腦應用程式。我們請 Antigravity CLI 採用 WebAssembly (WASM) 技術，讓這段程式碼能在網頁瀏覽器中執行。這包括編譯瀏覽器目標的 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，查看在網路上執行的遊戲：

5503ee0226f585b5.png

現在您已在網路上執行，在部署至雲端之前，請先進行最後潤飾。

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.

在瀏覽器中再次執行遊戲。請嘗試從行動裝置存取網址 (建議產生 QR code，簡化這項操作)。

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)

這樣一來，我們就能使用螢幕截圖修正 UI 元素，否則這些元素可能難以僅用文字描述。

如要參照檔案，請輸入「@」符號，然後輸入檔案名稱。舉例來說，我要求代理程式放大標題畫面上的標誌：

5c18bde16b58fc8.png

雖然這個範例有點牽強，因為模型不一定需要「看到」圖片才能套用 50% 的大小修正，但如果難以用文字描述問題，這項技術就很有用，可協助調整 UI。代理程式也能透過前後螢幕截圖驗證自己的工作，因此請將這項技巧納入工具箱。

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 帳戶收費，請刪除本程式碼研究室建立的資源。

  1. 刪除 Cloud Run 服務：
I'm finished with this project. Delete the cloud run deployment.
  1. 刪除專案目錄：
cd .. && rm -rf codelab-match3

或者，如果您專為本程式碼研究室建立了 Google Cloud 專案，可以刪除整個專案。

後續步驟

您可以探索這個平台上的其他程式碼研究室，繼續學習之旅，也可以自行改良 Cloud Crush，但別忘了在完成後清理資源！

祝您編寫程式一切順利！