1. Introduzione
In questo codelab creerai CloudCrush, un gioco arcade match 3, utilizzando Gemini 3 e l'agente di codifica Antigravity. Il gioco verrà scritto in Go e deployment su Google Cloud utilizzando Cloud Run.
Tieni presente che, sebbene sia consigliata la conoscenza del linguaggio Go, non è necessaria per partecipare a questo workshop, in quanto l'agente si occuperà di tutta la programmazione. L'obiettivo principale di questo codelab è sviluppare le competenze per orchestrare l'agente in modo che crei applicazioni per te anziché scrivere codice manualmente.
Questo codelab è destinato a sviluppatori di livello intermedio che vogliono imparare i workflow agentici avanzati. La durata totale stimata per questo lab è di 60 minuti. Le risorse create in questo codelab utilizzano prezzi basati sul consumo.
In questo lab proverai a:
- Crea la logica di base del gioco abbinamento a tre utilizzando Go e il framework Ebitengine.
- Adattare il gioco per l'esecuzione su un browser web utilizzando WebAssembly (WASM)
- Esegui il deployment del gioco e della relativa API per i punteggi migliori in Cloud Run.
- Orchestra sub-agenti ed estensioni specializzati per test e revisione del codice
Prerequisiti
- Conoscenza di base dei linguaggi di programmazione
- Conoscenza di base dell'infrastruttura cloud
- Conoscenza di base della console Google Cloud
Obiettivi didattici
- Come lavorare con un agente di programmazione per creare applicazioni complesse
- Come lavorare con Gemini in un contesto multimodale
- Come eseguire il deployment di applicazioni nel cloud utilizzando Cloud Run
Che cosa ti serve
Questo workshop può essere svolto interamente sul cloud utilizzando Cloud Shell, ma se preferisci utilizzare la tua macchina locale, avrai bisogno di quanto segue:
- Antigravity 2.0 e Antigravity CLI. Scaricalo e installalo seguendo le istruzioni riportate in antigravity.google.
- La toolchain Go (versione 1.26 o successive). Scaricalo e installalo seguendo le istruzioni riportate in go.dev.
- L'interfaccia a riga di comando gcloud per interagire con Google Cloud. Scaricalo e installalo seguendo le istruzioni riportate nella documentazione di Google Cloud.
- Un account di fatturazione Google Cloud (per il deployment del gioco sul cloud)
Tecnologie chiave
Qui puoi trovare maggiori informazioni sulle tecnologie che utilizzeremo:
- Antigravity CLI: l'agente di sviluppo
- Gemini 3: l'ultima versione del nostro modello linguistico di grandi dimensioni all'avanguardia
2. Configurazione dell'ambiente
Scegli una delle seguenti opzioni: Configurazione dell'ambiente autonomo se vuoi eseguire questo codelab sulla tua macchina oppure Avvia Cloud Shell se vuoi eseguire questo codelab interamente nel cloud.
Configurazione dell'ambiente autonomo
- Accedi alla console Google Cloud e crea un nuovo progetto o riutilizzane uno esistente. Se non hai ancora un account Gmail o Google Workspace, devi crearne uno.
- Il nome del progetto è il nome visualizzato per i partecipanti a questo progetto. È una stringa di caratteri non utilizzata dalle API di Google. Puoi sempre aggiornarlo.
- L'ID progetto è univoco in tutti i progetti Google Cloud ed è immutabile (non può essere modificato dopo l'impostazione). La console Cloud genera automaticamente una stringa univoca, di solito non ti interessa di cosa si tratta. Nella maggior parte dei codelab, dovrai fare riferimento all'ID progetto (in genere identificato come
PROJECT_ID). Se l'ID generato non ti piace, puoi generarne un altro casuale. In alternativa, puoi provare a crearne uno e vedere se è disponibile. Non può essere modificato dopo questo passaggio e rimane per tutta la durata del progetto. - Per tua informazione, esiste un terzo valore, un numero di progetto, utilizzato da alcune API. Scopri di più su tutti e tre questi valori nella documentazione.
- Successivamente, devi abilitare la fatturazione in Cloud Console per utilizzare le risorse/API Cloud. Completare questo codelab non costa molto, se non nulla. Per arrestare le risorse ed evitare addebiti oltre a quelli previsti in questo tutorial, puoi eliminare le risorse che hai creato o il progetto. I nuovi utenti di Google Cloud possono beneficiare del programma prova senza costi di 300$.
Avvia Cloud Shell
Sebbene Google Cloud possa essere gestito da remoto dal tuo laptop, in questo codelab utilizzerai Google Cloud Shell, un ambiente a riga di comando in esecuzione nel cloud.
Nella console Google Cloud, fai clic sull'icona di Cloud Shell nella barra degli strumenti in alto a destra:
Bastano pochi istanti per eseguire il provisioning e connettersi all'ambiente. Al termine, dovresti vedere un risultato simile a questo:
Questa macchina virtuale è caricata con tutti gli strumenti per sviluppatori di cui avrai bisogno. Offre una home directory permanente da 5 GB e viene eseguita su Google Cloud, migliorando notevolmente le prestazioni e l'autenticazione della rete. Tutto il lavoro in questo codelab può essere svolto all'interno di un browser. Non devi installare nulla.
3. Configurazione del progetto
Crea la directory del progetto
Innanzitutto, dobbiamo creare una nuova directory per il tuo progetto. Nel terminale, esegui questi comandi:
mkdir -p codelab-match3 && cd codelab-match3
Avviare Antigravity CLI
Innanzitutto, verifichiamo che l'interfaccia a riga di comando Antigravity sia stata installata correttamente. Esegui questo comando nel terminale:
agy --version
Il risultato dovrebbe essere simile a questo:
$ agy --version 1.0.2
Ora avvia Antigravity CLI con il comando agy:
agy
Antigravity ti chiederà se consideri attendibile questo progetto. Poiché abbiamo appena creato una cartella vuota, è sicuro considerarla attendibile. Conferma l'accesso e verrà visualizzato il prompt della CLI:
Se visualizzi il prompt della CLI Antigravity, puoi procedere. In caso contrario, controlla di non aver saltato nessuno dei passaggi di configurazione precedenti.
4. Crea il gioco base in modalità di pianificazione
Iniziamo creando la logica di base del gioco abbinamento a tre. Antigravity viene avviato per impostazione predefinita in modalità di pianificazione, quindi non è necessario emettere comandi speciali per passare alla pianificazione.
Tuttavia, è utile sapere che puoi attivare la modalità di pianificazione in qualsiasi momento con il comando slash /planning nel prompt della CLI Antigravity:
/planning
Se provi a eseguire questo comando ora, Antigravity ti ricorderà che è già in fase di pianificazione.
La modalità opposta alla modalità di pianificazione è la modalità rapida, che puoi attivare con /fast:
/fast
In modalità rapida, Antigravity inizierà subito a lavorare sull'attività ed è pensata per attività autonome più semplici. La modalità di pianificazione è pensata per attività complesse, in cui l'agente elabora prima un piano che puoi rivedere e perfezionare prima dell'esecuzione.
Scaricare gli asset
Dobbiamo scaricare le immagini che verranno utilizzate nel gioco. Poiché si tratta di un'attività piccola e autonoma, non è necessario eseguirla in modalità di pianificazione, quindi sfruttiamo la modalità veloce per eseguirla immediatamente:
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 chiederà l'autorizzazione per eseguire alcuni comandi shell per scaricare i file. Al termine, dovresti vedere qualcosa di simile a questo:
Crea il gioco base
Ora che gli asset sono pronti, è il momento di creare il gioco base. Poiché la creazione di un gioco è un'attività piuttosto complessa, torniamo alla modalità di pianificazione prima di dare il prompt:
/planning
In modalità di pianificazione, copia e incolla il seguente prompt nell'interfaccia a riga di comando Antigravity:
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.
Potrebbe eseguire alcune esplorazioni prima di elaborare il piano, ad esempio ispezionare i file PNG per visualizzarne le dimensioni. Una volta completato il piano, ti verrà chiesto di esaminarlo:
Presta attenzione all'angolo in basso a destra, dove hai scritto 1 artefatto e al suggerimento di utilizzare /artifact per la revisione. In Antigravity, i file di supporto come piani, elenchi di attività e procedure dettagliate sono chiamati "artefatti" per distinguerli dai normali file che fanno parte della soluzione (ad es. il codice sorgente).
Se inserisci il comando /artifact nel prompt, puoi visualizzare il piano e commentarlo nel caso in cui tu debba apportare modifiche.
/artifact
Il risultato dovrebbe essere simile a questo:
Tieni presente che è presente un file denominato implementation_plan.md con le opzioni per aprire, approvare o rifiutare. Premi Invio per aprirlo. Ecco un esempio di come appare il piano sul mio sistema:
Puoi scorrere verso l'alto e verso il basso con i tasti freccia e, in qualsiasi riga, puoi aggiungere un commento premendo il tasto C. In questo caso, non mi piace che venga utilizzata una versione precedente di Go, quindi aggiungerò un commento per utilizzare Go 1.26 (la versione più recente al momento della stesura) alla riga 16:
Una volta inserito, il commento verrà visualizzato in linea:
Una sezione importante da controllare è "Piano di verifica". I giochi sono notoriamente difficili da testare automaticamente, ma Go è un linguaggio compilato, quindi dobbiamo almeno assicurarci che il modello ci fornisca codice che venga compilato. Se un passaggio automatizzato per la creazione del binario non è incluso, aggiungilo come commento:
Una sezione importante da controllare è "Piano di verifica". I giochi sono particolarmente difficili da testare automaticamente, ma go è un linguaggio compilato, quindi dobbiamo almeno assicurarci che il modello ci fornisca codice che venga compilato. Se non è incluso un passaggio automatico per la creazione del binario, aggiungilo come commento:
Ripeti questa procedura finché non sei soddisfatto del piano e premi ESC per tornare indietro. Poi premi Y per confermare l'invio dei commenti all'agente:
Dopo aver premuto Y, l'agente inizierà immediatamente a lavorare. Devi premere ESC un'altra volta per uscire dal menu "Artefatto". In questo modo tornerai alla modalità prompt. Nel frattempo, l'agente potrebbe richiedere molte più conferme di chiamate di strumenti perché deve eseguire comandi shell.
Mentre aspettiamo, possiamo anche continuare a lavorare sul design mettendo in coda i prompt. Ad esempio, possiamo utilizzare questa opportunità per aggiungere un nuovo requisito che non era stato incluso nel prompt originale:
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.
Nella cronologia dei messaggi viene visualizzato un prompt in coda con una piccola freccia davanti:
Potresti anche notare che il numero di artefatti sta aumentando. Oltre al piano, Antigravity creerà anche un elenco di attività (task.md) per tenere traccia di ogni elemento da implementare o azione da eseguire. Al termine, creerà un file di procedura dettagliata (walkthrough.md) con una spiegazione degli obiettivi raggiunti. Puoi esaminarli tutti utilizzando di nuovo il comando /artifact.
Ecco un esempio del file task.md dopo aver completato l'implementazione del gioco base:
In qualsiasi momento puoi aprire questi file e aggiungere commenti, che, una volta inviati all'agente, verranno messi in coda per l'esecuzione proprio come un prompt in coda. È buona norma commentare questi file per fornire all'agente un contesto aggiuntivo sulla tua richiesta.
Una volta creato correttamente il binario, dovresti visualizzare un messaggio simile al seguente:
Prova a eseguire il gioco e verifica se funziona come previsto. È consigliabile eseguirlo dal prompt dell'agente. Puoi passare il prompt alla "modalità shell" digitando un punto esclamativo "!":
Sotto il prompt vedrai il messaggio "activated bash mode" (modalità bash attivata). Premi Invio per eseguire il comando. L'esecuzione del file binario in questa modalità offre il vantaggio che l'agente "controlla" l'output del terminale, quindi nel caso in cui il gioco non venga eseguito o si arresti in modo anomalo, non è necessario spiegare all'agente il problema che si è verificato. Avrà immediatamente tutte le informazioni necessarie dal contesto della shell.
Prova a giocare e a perfezionare i parametri del gioco finché non sei soddisfatto dell'esperienza (ad esempio, rendendo l'animazione più veloce o più lenta, regolando la risposta ai comandi e così via).
Ad esempio, questo prompt migliorerà l'esperienza aggiungendo una modalità di accessibilità e nuovi comandi da tastiera:
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.
Una volta terminata la rifinitura, passa alla sezione successiva per convertirla in un'app web.
5. Adattare il gioco per l'esecuzione su un browser web
Il gioco Ebitengine è attualmente un'applicazione desktop. Chiediamo ad Antigravity CLI di adattarlo per l'esecuzione in un browser web utilizzando WebAssembly (WASM). Ciò comporterà la compilazione del codice Go per la destinazione del browser e la configurazione di un server web di base.
Utilizza il seguente prompt per guidare l'agente:
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.
Tieni presente che l'agente tenterà di cercare un file denominato wasm_exec.js nel tuo file system. Questo comportamento è previsto e devi consentirlo, in quanto questo file è il wrapper che consente di eseguire i binari Go tramite JS. Ad esempio:
Una volta completata l'attività, puoi chiedere all'agente di eseguire il server di gioco in background.
Ora apri http://localhost:8080 nel browser per vedere il gioco in esecuzione sul web:
Ora che è in esecuzione sul web, diamogli un'ultima rifinitura prima di eseguirne il deployment sul cloud.
6. Creare la schermata del titolo e la classifica
Il gioco funziona, ma mancano alcune funzionalità chiave per un'esperienza arcade adeguata. Innanzitutto aggiungiamo una schermata del titolo e poi una classifica per poter competere con i tuoi amici. Utilizza il seguente 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).
Leaderboard scores should be saved in-memory, server-side.
Inizia ad avere un aspetto un po' più professionale. 🙂
7. Esegui il deployment del gioco in Cloud Run
È finalmente arrivato il momento di condividere la nostra creazione con il mondo. Eseguiremo il deployment dell'intera applicazione su Google Cloud Run per poterla accedere da qualsiasi luogo.
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.
Poiché il gioco è ora disponibile nel cloud, sarebbe un'occasione mancata non consentirne l'esecuzione sui dispositivi mobili. Puoi farlo con il seguente prompt:
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.
Esegui di nuovo il gioco sul browser. Prova ad accedere all'URL anche da un dispositivo mobile (potresti generare un codice QR per semplificare l'esperienza).
8. Utilizzare l'agente del browser per testare il gioco
Anche se un gioco è spesso difficile da testare automaticamente perché si basa sul feedback visivo, possiamo comunque sfruttare l'automazione per assicurarci almeno che il deployment funzioni correttamente e che gli elementi di base siano presenti.
Per farlo, utilizzeremo il subagente del browser. In Antigravity, un subagente è una persona isolata con un contesto nuovo, perfetta per le attività in cui non vuoi che il contesto attuale influenzi i risultati o quando vuoi impedire che l'attività "contamini" la finestra contestuale principale.
L'agente del browser è un agente speciale integrato per le attività correlate al browser. Tieni presente che solo per questo passaggio dobbiamo utilizzare l'app desktop Antigravity, in quanto l'agente del browser non è attualmente disponibile nella riga di comando.
Apri l'app desktop Antigravity e avvia una nuova conversazione nel progetto Cloud Crush:
Puoi attivare il sub-agente del browser digitando /browser seguito da questo prompt:
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)
Questo approccio ci consente di utilizzare gli screenshot per correggere elementi dell'interfaccia utente che altrimenti potrebbero essere difficili da descrivere solo con il testo.
Puoi fare riferimento ai file utilizzando il simbolo "@" seguito dal nome del file. Ad esempio, qui chiedo all'agente di aumentare le dimensioni del logo nella schermata del titolo:
Sebbene questo esempio sia un po' forzato, in quanto il modello non ha necessariamente bisogno di "vedere" l'immagine per applicare una correzione delle dimensioni del 50%, è una tecnica utile per apportare modifiche alla UI nei casi in cui potrebbe essere più difficile descrivere il problema in formato di testo. Inoltre, l'agente può convalidare il proprio lavoro scattando screenshot prima e dopo, quindi tieni questo trucco a portata di mano.
9. Crea un agente personalizzato per proteggere la partita
Un problema comune con le applicazioni "vibe-coded" è come mantenere alta qualità e best practice sia dal punto di vista della codifica che della sicurezza. Anche se puoi provare a migliorare i prompt per renderli molto rigorosi su entrambi gli aspetti, più aggiungi a un prompt, meno l'agente sarà concentrato, il che spesso si traduce in risultati non ottimali.
Per questo tipo di scenario, l'utilizzo di subagenti è ideale, in quanto possono concentrarsi con precisione sull'attività che gli assegni. Creiamo un agente personalizzato per eseguire un controllo di sicurezza su questo codice e assicurarci di non divulgare credenziali o esporci a rischi inutili durante il deployment di questo gioco.
Questo prompt fornisce una buona base per l'agente:
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.
Tieni presente che Antigravity utilizzerà lo strumento "DefineSubagent" per creare il nuovo agente:
Chiedi all'agente di eseguire un controllo di sicurezza sul codice del gioco con il seguente prompt:
Run the security auditor agent in this code
Il risultato dovrebbe essere simile a questo:
Una volta completata l'attività, l'agente dovrebbe visualizzare un report simile a questo:
Chiediamo ad Antigravity di risolverli per noi 🙂:
Fix these findings for me please!
Et voilà:
Tieni presente che gli agenti creati in questo modo esistono solo per la durata della conversazione. Se vuoi un agente "riutilizzabile" tra le sessioni, puoi crearlo utilizzando un file di configurazione. Per ulteriori informazioni, consulta il comando /agents.
10. Conclusione
Complimenti! Hai utilizzato correttamente Antigravity CLI per creare, eseguire il deployment, testare e controllare un gioco arcade, dimostrando workflow basati su agenti avanzati dallo scaffolding iniziale al deployment.
Elimina
Per evitare addebiti continui al tuo account Google Cloud, elimina le risorse create durante questo codelab.
- Elimina il servizio Cloud Run:
I'm finished with this project. Delete the cloud run deployment.
- Elimina la directory del progetto:
cd .. && rm -rf codelab-match3
In alternativa, puoi eliminare l'intero progetto Google Cloud se è stato creato esclusivamente per questo codelab.
Passaggi successivi
Puoi continuare il tuo percorso di apprendimento esplorando altre codelab in questa piattaforma o migliorando Cloud Crush in autonomia. Non dimenticare di liberare spazio dalle risorse una volta terminate.
Buona programmazione!