1. Einführung
In diesem Codelab erstellen Sie CloudCrush, ein Match-3-Arcadespiel, mit Gemini 3 und der Gemini CLI, unserem Befehlszeilen-Coding-Agenten. Das Spiel wird in Go geschrieben und mit Cloud Run in Google Cloud bereitgestellt.
Das Hauptziel dieses Codelabs besteht darin, die Fähigkeiten zu entwickeln, den Agenten so zu steuern, dass er Anwendungen für Sie erstellt, anstatt Code manuell zu schreiben. Sie delegieren alle Entwicklungsaufgaben an die Gemini CLI, auch wenn Sie diese Technologien noch nicht verwendet haben.
Dieses Codelab richtet sich an fortgeschrittene Entwickler, die agentengestützte Programmier-Workflows kennenlernen möchten. Die geschätzte Gesamtdauer für dieses Lab beträgt 60 Minuten. Für die in diesem Codelab erstellten Ressourcen gilt die nutzungsabhängige Abrechnung.
Aufgaben
- Erstellen Sie die grundlegende Match-3-Spiellogik mit Go und dem Ebitengine-Framework.
- Spiel für die Ausführung in einem Webbrowser mit WebAssembly (WASM) anpassen
- Stellen Sie das Spiel und die Highscore-API in Cloud Run bereit.
- Spezialisierte Unter-Agents und Erweiterungen für Tests und Code-Reviews orchestrieren
Vorbereitung
- Grundlegende Kenntnisse von Programmiersprachen
- Grundkenntnisse der Cloud-Infrastruktur
- Grundkenntnisse der Google Cloud Console
Lerninhalte
- So erstellen Sie komplexe Anwendungen mit einem Coding-Agent
- Mit Gemini in einem multimodalen Kontext arbeiten
- Anwendungen mit Cloud Run in der Cloud bereitstellen
Voraussetzungen
Dieser Workshop kann vollständig in der Cloud mit Cloud Shell durchgeführt werden. Wenn Sie jedoch lieber Ihren lokalen Computer verwenden möchten, benötigen Sie Folgendes:
- Gemini CLI. Laden Sie es herunter und installieren Sie es gemäß der Anleitung unter geminicli.com.
- Die Go-Toolchain (Version 1.26 oder höher). Laden Sie es herunter und installieren Sie es gemäß der Anleitung auf go.dev.
- Die gcloud CLI für die Interaktion mit Google Cloud. Laden Sie es herunter und installieren Sie es gemäß der Anleitung in der Google Cloud-Dokumentation.
- Ein Google Cloud-Rechnungskonto (zum Bereitstellen des Spiels in der Cloud)
Wichtige Technologien
Hier finden Sie weitere Informationen zu den Technologien, die wir verwenden:
- Gemini CLI: der Entwicklungsagent
- Gemini 3: die aktuelle Version unseres führenden großen Sprachmodells
2. Umgebung einrichten
Projekt einrichten
Google Cloud-Projekt erstellen
- Wählen Sie in der Google Cloud Console auf der Seite zur Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.
- Die Abrechnung für das Cloud-Projekt muss aktiviert sein. So prüfen Sie, ob die Abrechnung für ein Projekt aktiviert ist.
Cloud Shell starten
Cloud Shell ist eine Befehlszeilenumgebung, die in Google Cloud ausgeführt wird und mit den erforderlichen Tools vorinstalliert ist.
- Klicken Sie oben in der Google Cloud Console auf Cloud Shell aktivieren.
- Prüfen Sie nach der Verbindung mit Cloud Shell Ihre Authentifizierung:
gcloud auth list - Prüfen Sie, ob Ihr Projekt konfiguriert ist:
gcloud config get project - Wenn Ihr Projekt nicht wie erwartet festgelegt ist, legen Sie es fest:
export PROJECT_ID=<YOUR_PROJECT_ID> gcloud config set project $PROJECT_ID
3. Projekt einrichten
Projektverzeichnis erstellen
Zuerst müssen wir ein neues Verzeichnis für Ihr Projekt erstellen. Führen Sie im Terminal die folgenden Befehle aus:
mkdir -p codelab-match3 && cd codelab-match3
Gemini CLI starten
Prüfen wir zuerst, ob die Gemini CLI richtig installiert wurde. Führen Sie im Terminal folgenden Befehl aus:
gemini --version
Auf dem Bildschirm sollte Folgendes zu sehen sein:
$ gemini --version 0.37.1
Starten Sie die Gemini CLI jetzt mit dem Befehl gemini:
gemini
Der Gemini CLI-Prompt sollte angezeigt werden:
Wenn Sie den Gemini CLI-Prompt sehen, sind Sie bereit. Andernfalls prüfen Sie noch einmal, ob Sie einen der vorherigen Einrichtungsschritte übersehen haben.
Model Steering aktivieren
Mit der Modellsteuerung können Sie dem Agent zusätzlichen Kontext hinzufügen, während er noch an einer bestimmten Aufgabe arbeitet. Sie können damit den Agenten korrigieren, wenn er in die falsche Richtung geht, klärende Informationen hinzufügen, um die Antwort des Agenten zu verbessern, oder kleinere Funktionen einfügen, die im ursprünglichen Prompt nicht berücksichtigt wurden.
Wenn Sie die Modellsteuerung aktivieren möchten, öffnen Sie das Einstellungsmenü mit dem Befehl /settings und geben Sie „steering“ in das Suchfeld ein. Setzen Sie dann die Option „Enable Model Steering“ auf „true“.
Möglicherweise müssen Sie die CLI neu starten, damit die Änderung wirksam wird (drücken Sie die Taste „r“).
Assets herunterladen
Wir müssen die Bilder herunterladen, die im Spiel verwendet werden sollen. Die Dateien werden auf GitHub im Repository gespeichert. Sie können sie manuell herunterladen oder Gemini mit dem folgenden Prompt darum bitten:
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
4. Spiel mit Planmodus und Modellsteuerung erstellen
Beginnen Sie mit der Entwicklung der grundlegenden Match‑3-Spiellogik. Da dies eine komplexe Aufgabe ist, empfiehlt es sich, die Entwicklung mit der Gemini CLI im Plan-Modus zu koordinieren.
Mit dem Slash-Befehl /plan im Gemini CLI-Prompt können Sie den Plan-Modus aktivieren oder deaktivieren:
/plan
Kopieren Sie den folgenden Prompt und fügen Sie ihn in die Gemini CLI ein, wenn der Plan-Modus aktiviert ist:
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.
Gemini CLI stellt Ihnen möglicherweise einige Fragen zur Klärung, bevor der Plan generiert wird.
Hier wird beispielsweise gefragt, ob Sie eine Anwendung mit einer oder mehreren Dateien bevorzugen:
Hier werden wir nach unseren Einstellungen für Animationen gefragt:
Bei der letzten Frage geht es darum, die Assets mit „go:embed“ in die Binärdatei selbst einzubetten:
Nachdem Sie alle Fragen beantwortet haben, können Sie Ihre Antworten noch einmal überprüfen, bevor Sie sie mit der Eingabetaste senden.
Sobald der Plan fertig ist, werden Sie aufgefordert, ihn zu überprüfen:
Unten im Rezensionsfeld haben Sie die Möglichkeit, den Plan so zu akzeptieren oder unser Feedback hinzuzufügen.
Nutzen Sie diese Gelegenheit, um eine neue Anforderung hinzuzufügen, die im ursprünglichen Prompt nicht berücksichtigt wurde:
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.
Sie werden ein letztes Mal aufgefordert, den Implementierungsplan zu bestätigen:
Drücken Sie die Eingabetaste, damit der Agent mit der Arbeit beginnt. Der Agent verlässt nun den Planmodus und beginnt mit dem Schreiben des Codes.
Normalerweise müssten wir jetzt warten, bis der Vorgang abgeschlossen ist, oder ihn mit der ESC-Taste unterbrechen, wenn wir Änderungen an der Implementierung vornehmen möchten. Da wir jedoch die Modellsteuerung aktiviert haben, können wir Anweisungen in die Warteschlange stellen, um das Modell zu korrigieren.
Während der Agent arbeitet, fügen Sie Folgendes in das Chatfenster des Agents ein, um die Funktion „Modellsteuerung“ zu demonstrieren. So können Sie Befehle in die Warteschlange stellen, um die Implementierung zu ändern:
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.
Die Eingabeaufforderung wird als „Steering Hint“ (Steuerungshinweis) in die Warteschlange gestellt:
Akzeptieren Sie den Plan und sehen Sie zu, wie der KI-Agent alle Ihre Anforderungen umsetzt.
Wenn der Agent mit der Implementierung fertig ist, führen Sie go run main.go im Projektordner aus, um die Desktopversion zu testen. Sie müssen die Gemini CLI nicht verlassen, um diesen Befehl auszuführen. Geben Sie „!“ ein. (Ausrufezeichen), um in den Shell-Modus zu wechseln und den Befehl dort auszuführen:
Der Vorteil des Shell-Modus besteht darin, dass alle Probleme, die auftreten können, sofort im Agentenkontext erfasst werden. In diesem Fall hat der Agent beispielsweise vergessen, einige Abhängigkeiten herunterzuladen:
Sie können den Shell-Modus beenden, indem Sie die Esc-Taste drücken, und den Agenten dann bitten, den Fehler zu untersuchen und zu beheben:
Das Ergebnis sollte in etwa so aussehen:
Spielen Sie das Spiel und passen Sie die Spielparameter an, bis Sie zufrieden sind (z. B. die Animation schneller oder langsamer machen, anpassen, wie das Spiel auf Befehle reagiert usw.).
5. Spiel für die Ausführung in einem Webbrowser anpassen
Das Ebitengine-Spiel, das Sie gerade erstellt haben, ist eine Desktopanwendung. Damit es im Web ausgeführt werden kann, können wir es in WebAssembly konvertieren.
Verwenden Sie den folgenden Prompt, um den Agent zu steuern:
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.
Sobald der Agent die Aufgabe abgeschlossen hat, können Sie ihn anweisen, den Spieleserver im Hintergrund auszuführen.
Sie können Hintergrundprozesse mit der Tastenkombination Strg+B verwalten:
Drücken Sie noch einmal Strg + B, um dieses Fenster zu schließen.
Öffnen Sie jetzt http://localhost:8080 in Ihrem Browser, um das Spiel im Web zu sehen:
Nachdem Sie die App im Web ausgeführt haben, ist es an der Zeit, sie vor der Bereitstellung in der Cloud noch einmal zu optimieren.
6. Titelbildschirm und Bestenliste erstellen
Das Spiel funktioniert, aber es fehlen einige wichtige Funktionen für ein echtes Arcade-Erlebnis. Fügen wir zuerst einen Titelbildschirm und dann eine Bestenliste hinzu, damit du dich mit deinen Freunden messen kannst.
Beheben Sie beide Probleme mit dem folgenden Prompt:
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).
Hier ist ein Beispiel für den Titelbildschirm:
Es sieht schon etwas professioneller aus. 🙂
7. Spiel in Cloud Run bereitstellen
Es ist endlich an der Zeit, unsere Kreation mit der Welt zu teilen. Stellen Sie das Spiel in Google Cloud Run bereit, damit Sie von überall darauf zugreifen können.
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.
Da das Spiel jetzt in der Cloud verfügbar ist, wäre es eine verpasste Gelegenheit, es nicht auf Mobilgeräten auszuführen. Dazu können Sie den folgenden Prompt verwenden:
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 button to generate a random name and
a confirmation button to the name entry.
Also 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.
Führen Sie das Spiel noch einmal in Ihrem Browser aus. Versuche, über den QR‑Code auch auf einem Mobilgerät auf das Spiel zuzugreifen.
8. Browser-Agent zum Testen des Spiels verwenden
In der Gemini CLI ist ein untergeordneter Agent eine isolierte Persona mit einem neuen Kontext. Das ist ideal für zeitaufwendige und/oder hochpräzise Aufgaben, bei denen der aktuelle Kontext die Ergebnisse nicht beeinflussen soll.
Spiele lassen sich mit herkömmlichen Testtools (z. B. Einheitentests und Integrationstests) nur schwer testen. Wir können jedoch den Browser-Agent verwenden, um einige Tests für uns durchzuführen. Der Browser-Agent kann einen eigenen Chrome-Browser starten und durch DOM-Befehle durch die Spielbildschirme navigieren. Außerdem kann es Screenshots erstellen, die wir verwenden können, um den Test zu dokumentieren und dem Agenten zur Verfügung zu stellen, damit er später kleinere Anpassungen an der Benutzeroberfläche vornehmen kann.
Der Browser-Agent ist derzeit experimentell. Wir müssen ihn also zuerst aktivieren. Geben Sie diesen Prompt in die Gemini CLI ein, um den Agenten auf Projektebene zu aktivieren.
Create a .gemini/settings.json file with the following content to
configure the browser sub agent:
{
"agents": {
"overrides": {
"browser_agent": {
"enabled": true
}
}
}
}
Sie müssen den Agenten neu starten, damit diese Änderung wirksam wird. Speichern Sie die aktuelle Unterhaltung mit dem Befehl /chat save:
Beenden Sie die Gemini CLI, indem Sie zweimal Strg + D drücken, und starten Sie sie dann neu. Stellen Sie die Unterhaltung mit /chat resume cloud-crush wieder her.
Sie sollten jetzt Zugriff auf den Browser-Agent haben. Wenn Sie eine Aufgabe an den Browser-Agenten delegieren möchten, können Sie ihn mit @browser_agent erwähnen:
Verwenden Sie nun den Browser-Agent, um eine Bewertung unseres bereitgestellten Spiels vorzunehmen:
@browser_agent perform an end-to-end test of the Cloud Run deployment URL.
Navigate the homepage, start a game, submit a score, and verify the new score
appears correctly on the leaderboard. Take screenshots to show each step of the
investigation and save to ./screenshots.
Sie sollten den Bestätigungsbildschirm sehen:
Nachdem Sie dem Agenten und den erforderlichen Tools die Einwilligung erteilt haben, sollte sich ein neues Chrome-Browserfenster öffnen. Dies ist der Browser, der vom Agent gesteuert wird. Der visuelle Hinweis ist der blaue Rahmen auf dem Bildschirm und die Meldung unten: „Gemini CLI steuert diesen Browser“:
Wenn der Vorgang abgeschlossen ist, wird eine Meldung wie die folgende angezeigt:
Hier sind einige der Screenshots, die vom Browser-Agent erstellt wurden:
title_screen.png:
game_board.png:
Jetzt ist es an der Zeit, eines der vom Agenten aufgenommenen Bilder zu verwenden, um die Benutzeroberfläche des Spiels zu optimieren. Sagen Sie zum Beispiel:
Analyse the screenshot @screenshots/game_board.png and adjust the side panel to
have better contrast and be more harmonic with the rest of UI elements. Focus
on readability and color theory to achieve the best possible visuals.
9. Benutzerdefinierten Agenten zum Sichern des Spiels erstellen
Ein häufiges Problem bei „Vibe-coded“-Anwendungen ist, wie man sowohl aus Programmier- als auch aus Sicherheitssicht eine hohe Qualität und Best Practices aufrechterhält. Sie können zwar versuchen, Ihre Prompts in Bezug auf diese beiden Aspekte zu optimieren, aber je mehr Sie einem Prompt hinzufügen, desto weniger fokussiert ist der Agent, was oft zu suboptimalen Ergebnissen führt. Für diese Art von Szenario ist die Verwendung von untergeordneten Agents ideal, da sie in einem separaten Kontext vom Haupt-Agenten arbeiten und sich genau auf die Aufgabe konzentrieren können, die Sie ihnen zuweisen. Erstellen wir einen benutzerdefinierten Agenten, um eine Sicherheitsprüfung für diesen Code durchzuführen und sicherzustellen, dass wir keine Anmeldedaten preisgeben oder uns unnötigen Risiken aussetzen, wenn wir dieses Spiel in Cloud Run bereitstellen.
Create a new custom agent in .gemini/agents/security_auditor.md using the following content:
---
name: security_auditor
description: Specialized in finding security vulnerabilities in code.
kind: local
tools:
- read_file
- grep_search
model: gemini-3-flash-preview
temperature: 0.2
max_turns: 10
---
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.
Sie müssen die CLI neu starten, damit die Änderung wirksam wird. Speichern Sie die Chatsitzung mit /chat save und setzen Sie sie mit /chat resume fort, wie wir es bereits getan haben.
Wenn die CLI fortgesetzt wird, erkennt sie den neuen Agent beim Start automatisch:
Klicken Sie auf Acknowledge and Enable und bitten Sie den Kundenservicemitarbeiter dann mit dem folgenden Prompt, eine Sicherheitsüberprüfung des Spielcodes durchzuführen:
@security-auditor please run a security audit on this code and cloud run
deployment to make sure it is safe against common attack patterns and that it is
not leaking any credentials
Auf dem Bildschirm sollte Folgendes zu sehen sein:
Nach Abschluss des Audits werden Empfehlungen ausgesprochen. In diesem Beispiel wurden einige wichtige Dinge gefunden, die behoben werden müssen:
Wenn Sie Fehler finden, können Sie die Gemini CLI einfach bitten, sie für Sie zu beheben. 🙂
10. Fazit
Glückwunsch! Sie haben die Gemini CLI erfolgreich verwendet, um ein Arcade-Spiel zu entwickeln, bereitzustellen, zu testen und zu prüfen. Dabei haben Sie fortschrittliche Agenten-Workflows von der ersten Gerüstentwicklung bis zur Bereitstellung demonstriert.
Bereinigen
Wenn Sie dieses Codelab nicht noch einmal durcharbeiten möchten, sollten Sie die Ressourcen löschen, die Sie während dieses Codelabs erstellt haben.
- Löschen Sie den Cloud Run-Dienst:
Bitten Sie Gemini CLI, sie für Sie zu löschen:
I'm finished with this project. Delete the cloud run deployment.
- Löschen Sie das Projektverzeichnis:
cd .. && rm -rf codelab-match3
Alternativ können Sie das gesamte Google Cloud-Projekt löschen, wenn es nur für dieses Codelab erstellt wurde.
Nächste Schritte
Sie können Ihre Lernreise fortsetzen, indem Sie sich andere Codelabs auf dieser Plattform ansehen oder Cloud Crush selbst verbessern.
Hier sind einige Vorschläge zur Verbesserung des Spiels:
- Füge ein spezielles „Gemini“-Gem (mit gemini.png) hinzu, das angezeigt wird, wenn 4 oder mehr Gems übereinstimmen. Wenn der Spieler mindestens drei Gemini-Juwelen kombiniert, erhält er Bonuszeit.
- Musik hinzufügen Sie können mit Lyria 3 auf der Gemini-Startseite Musik generieren.
- Soundeffekte hinzufügen
- Andere Spielmodi hinzufügen
Viel Spaß beim Programmieren!