1. Introducción
En este codelab, compilarás CloudCrush, un juego de arcade de unir 3, con Gemini 3 y el agente de programación Antigravity. El juego se escribirá en Go y se implementará en Google Cloud con Cloud Run.
Ten en cuenta que, si bien se recomienda tener conocimientos del lenguaje Go, no es necesario para realizar este taller, ya que el agente hará toda la codificación. El objetivo principal de este codelab es desarrollar las habilidades para orquestar el agente y que cree aplicaciones por ti en lugar de escribir código de forma manual.
Este codelab es para desarrolladores intermedios que desean aprender flujos de trabajo avanzados basados en agentes. La duración total estimada de este lab es de 60 minutos. Los recursos creados en este codelab usan precios basados en el consumo.
Actividades
- Crea la lógica principal del juego de unir 3 elementos con Go y el framework de Ebitengine.
- Adapta el juego para que se ejecute en un navegador web con WebAssembly (WASM)
- Implementa el juego y su API de puntuación alta en Cloud Run.
- Orquesta subagentes y extensiones especializados para pruebas y revisión de código
Requisitos previos
- Conocimientos básicos de lenguajes de programación
- Conocimientos básicos de la infraestructura de nube
- Conocimientos básicos de la consola de Google Cloud
Qué aprenderás
- Cómo trabajar con un agente de programación para compilar aplicaciones complejas
- Cómo trabajar con Gemini en un contexto multimodal
- Cómo implementar aplicaciones en la nube con Cloud Run
Requisitos
Este taller se puede realizar por completo en la nube con Cloud Shell, pero, si prefieres usar tu máquina local, necesitarás lo siguiente:
- Antigravity 2.0 y la CLI de Antigravity Descárgalo e instálalo siguiendo las instrucciones en antigravity.google.
- La cadena de herramientas de Go (versión 1.26 o posterior) Descárgalo e instálalo siguiendo las instrucciones en go.dev.
- La CLI de gcloud para interactuar con Google Cloud Descarga e instala el SDK siguiendo las instrucciones de la documentación de Google Cloud.
- Una cuenta de facturación de Google Cloud (para implementar el juego en la nube)
Tecnologías clave
Aquí puedes encontrar más información sobre las tecnologías que utilizaremos:
- CLI de Antigravity: El agente de desarrollo
- Gemini 3: La versión más reciente de nuestro modelo de lenguaje grande de vanguardia
2. Configuración del entorno
Elige una de las siguientes opciones: Configuración del entorno a tu propio ritmo si deseas ejecutar este codelab en tu propia máquina o Iniciar Cloud Shell si deseas ejecutar este codelab por completo en la nube.
Configuración del entorno de autoaprendizaje
- Accede a consola de Google Cloud y crea un proyecto nuevo o reutiliza uno existente. Si aún no tienes una cuenta de Gmail o de Google Workspace, debes crear una.
- El Nombre del proyecto es el nombre visible de los participantes de este proyecto. Es una cadena de caracteres que no se utiliza en las APIs de Google. Puedes actualizarla cuando quieras.
- El ID del proyecto es único en todos los proyectos de Google Cloud y es inmutable (no se puede cambiar después de configurarlo). La consola de Cloud genera automáticamente una cadena única. Por lo general, no importa cuál sea. En la mayoría de los codelabs, deberás hacer referencia al ID de tu proyecto (suele identificarse como
PROJECT_ID). Si no te gusta el ID que se generó, podrías generar otro aleatorio. También puedes probar uno propio y ver si está disponible. No se puede cambiar después de este paso y se usa el mismo durante todo el proyecto. - Recuerda que hay un tercer valor, un número de proyecto, que usan algunas APIs. Obtén más información sobre estos tres valores en la documentación.
- A continuación, deberás habilitar la facturación en la consola de Cloud para usar las APIs o los recursos de Cloud. Ejecutar este codelab no costará mucho, tal vez nada. Para cerrar recursos y evitar que se generen cobros más allá de este instructivo, puedes borrar los recursos que creaste o borrar el proyecto. Los usuarios nuevos de Google Cloud son aptos para participar en el programa Prueba gratuita de $300.
Inicie Cloud Shell
Si bien Google Cloud y Spanner se pueden operar de manera remota desde tu laptop, en este codelab usarás Google Cloud Shell, un entorno de línea de comandos que se ejecuta en la nube.
En Google Cloud Console, haz clic en el ícono de Cloud Shell en la barra de herramientas en la parte superior derecha:
El aprovisionamiento y la conexión al entorno deberían tomar solo unos minutos. Cuando termine el proceso, debería ver algo como lo siguiente:
Esta máquina virtual está cargada con todas las herramientas de desarrollo que necesitarás. Ofrece un directorio principal persistente de 5 GB y se ejecuta en Google Cloud, lo que permite mejorar considerablemente el rendimiento de la red y la autenticación. Todo tu trabajo en este codelab se puede hacer en un navegador. No es necesario que instales nada.
3. Configuración del proyecto
Crea el directorio del proyecto
Primero, debemos crear un directorio nuevo para tu proyecto. En tu terminal, ejecuta los siguientes comandos:
mkdir -p codelab-match3 && cd codelab-match3
Inicia la CLI de Antigravity
Primero, verifiquemos que la CLI de Antigravity se haya instalado correctamente. Ejecuta el siguiente comando en tu terminal:
agy --version
Deberías ver algo como esto:
$ agy --version 1.0.2
Ahora, inicia la CLI de Antigravity con el comando agy:
agy
Antigravity te preguntará si confías en este proyecto. Como acabamos de crear una carpeta vacía, es seguro confiar en ella. Por lo tanto, confirma el acceso y se te dirigirá al símbolo del sistema de la CLI:
Si ves el mensaje de la CLI de Antigravity, todo está bien. De lo contrario, verifica si te salteaste alguno de los pasos de configuración anteriores.
4. Crea el juego base en el modo de planificación
Comencemos por crear la lógica principal del juego de unir 3 elementos. La función Antigravity se inicia de forma predeterminada en el modo de planificación, por lo que no es necesario que emitas ningún comando especial para cambiar a la planificación.
Sin embargo, es útil saber que puedes habilitar el modo de planificación en cualquier momento con el comando de barra /planning en la solicitud de la CLI de Antigravity:
/planning
Si intentas ejecutar este comando ahora, Antigravity te recordará que ya está en planificación.
El modo rápido es lo opuesto al modo de planificación, y puedes habilitarlo con /fast:
/fast
En el modo rápido, Antigravity comenzará a trabajar en la tarea de inmediato, y está diseñado para tareas más simples y autónomas. El modo de planificación está diseñado para tareas complejas, en las que el agente primero elaborará un plan que podrás revisar y repetir antes de la ejecución.
Descarga los recursos
Necesitamos descargar las imágenes que se usarán en el juego. Dado que se trata de una tarea pequeña y autónoma, no es necesario ejecutarla en el modo de planificación, por lo que aprovecharemos que estamos en el modo rápido para hacerlo de inmediato:
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 te pedirá permiso para ejecutar algunos comandos de shell para descargar los archivos. Cuando termine, deberías ver algo como lo siguiente:
Crea el juego base
Con los recursos listos, ahora es el momento de crear el juego base. Dado que crear un juego es una tarea bastante compleja, volvamos al modo de planificación antes de darle nuestra instrucción:
/planning
En el modo de planificación, copia y pega la siguiente instrucción en la CLI de 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.
Es posible que realice una exploración antes de elaborar el plan, por ejemplo, inspeccionar los archivos PNG para ver sus dimensiones. Una vez que el plan esté listo, se te pedirá que lo revises:
Presta atención a la esquina inferior derecha, donde escribiste 1 artefacto y la sugerencia para usar /artifact para revisar. En Antigravity, los archivos de asistencia, como planes, listas de tareas y explicaciones, se denominan "artefactos" para diferenciarlos de los archivos normales que forman parte de la solución (p.ej., código fuente).
Si ingresas el comando /artifact en la instrucción, podrás ver el plan y hacer comentarios sobre él en caso de que necesites realizar ajustes.
/artifact
Deberías ver algo como esto:
Ten en cuenta que hay un archivo llamado implementation_plan.md con las opciones para abrir, aprobar o rechazar. Presiona Intro para abrirlo. Este es un ejemplo de cómo se ve el plan en mi sistema:
Puedes desplazarte hacia arriba y hacia abajo con las teclas de flecha y, en cualquier línea, puedes agregar un comentario presionando la tecla C. En este caso, no me gusta que se use una versión anterior de Go, por lo que agregaré un comentario para usar Go 1.26 (la versión más reciente en el momento de escribir este artículo) en la línea 16:
Una vez que ingreses el comentario, aparecerá intercalado:
Una sección importante que debes revisar es la del "Plan de verificación". Los juegos son notablemente difíciles de probar de forma automática, pero Go es un lenguaje compilado, por lo que al menos debemos asegurarnos de que el modelo nos entregue código que se compile. Si no se incluye un paso automatizado para compilar el objeto binario, agrégalo como comentario:
Una sección importante que debes revisar es la del "Plan de verificación". Los juegos son notablemente difíciles de probar de forma automática, pero Go es un lenguaje compilado, por lo que al menos debemos asegurarnos de que el modelo nos entregue código que se compile. Si no se incluye un paso automatizado para compilar el objeto binario, agrégalo como comentario:
Repite este proceso hasta que estés conforme con el plan y presiona ESC para volver. Luego, presiona Y para confirmar el envío de los comentarios al agente:
Después de presionar Y, el agente comenzará a trabajar de inmediato. Deberás presionar ESC una vez más para salir del menú "Artifact". Esto te llevará de nuevo al modo de instrucciones. Mientras tanto, es posible que el agente solicite muchas más confirmaciones de llamadas a herramientas, ya que necesita ejecutar comandos de shell.
Mientras esperamos, también podemos seguir trabajando en el diseño agregando indicaciones a la cola. Por ejemplo, podemos aprovechar esta oportunidad para agregar un requisito nuevo que se omitió en la instrucción original:
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.
En el historial de mensajes, aparecerá un mensaje en cola con una pequeña punta de flecha delante:
También es posible que notes que la cantidad de artefactos aumenta. Además del plan, Antigravity también creará una lista de tareas (task.md) para hacer un seguimiento de cada elemento que debe implementar o acción que debe realizar. Una vez que termine, creará un archivo de instrucciones (walkthrough.md) con una explicación de los objetivos alcanzados. Puedes inspeccionar todos estos elementos con el comando /artifact nuevamente.
A continuación, se muestra un ejemplo del archivo task.md después de completar la implementación del juego base:
En cualquier momento, puedes abrir estos archivos y agregarles comentarios que, cuando se envíen al agente, se pondrán en cola para su ejecución, al igual que una instrucción en cola. Se recomienda agregar comentarios a estos archivos para brindarle al agente contexto adicional sobre tu solicitud.
Una vez que se compile el binario correctamente, deberías ver algo como lo siguiente:
Intenta ejecutar el juego y comprueba si funciona según lo esperado. Es recomendable ejecutarlo desde la instrucción del agente. Puedes cambiar la instrucción al "modo de shell" escribiendo un signo de exclamación "!":
Verás el mensaje "activated bash mode" debajo de la instrucción. Presiona Intro para ejecutar el comando. Ejecutar el archivo binario en este modo te brinda el beneficio de que el agente "observa" cualquier resultado en la terminal, por lo que, en caso de que el juego no se ejecute o falle de forma abrupta, no necesitas explicarle al agente el problema que ocurrió. Inmediatamente tendrá toda la información que necesita del contexto del shell.
Intenta jugar y ajustar los parámetros del juego hasta que estés conforme con la experiencia (p.ej., acelerar o ralentizar la animación, ajustar la forma en que responde a los comandos, etcétera).
Por ejemplo, esta instrucción mejorará la experiencia, ya que agregará un modo de accesibilidad y nuevos comandos de teclado:
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.
Cuando termines de pulir el código, ve a la siguiente sección para convertirlo en una app web.
5. Adaptar el juego para que se ejecute en un navegador web
Actualmente, el juego de Ebitengine es una aplicación para computadoras. Pidámosle a la CLI de Antigravity que la adapte para que se ejecute en un navegador web con WebAssembly (WASM). Esto implicará compilar el código de Go para el destino del navegador y configurar un servidor web básico.
Usa la siguiente instrucción para guiar al 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.
Ten en cuenta que el agente intentará buscar un archivo llamado wasm_exec.js en tu sistema de archivos. Esto es normal y debes permitirlo, ya que este archivo es el wrapper que permite ejecutar archivos binarios de Go a través de JS. Por ejemplo:
Una vez que el agente complete la tarea, puedes indicarle que ejecute el servidor del juego en segundo plano.
Ahora abre http://localhost:8080 en tu navegador para ver el juego en la Web:
Ahora que lo tienes en la Web, solo le daremos un toque final antes de implementarlo en la nube.
6. Crea la pantalla de título y la tabla de clasificación
El juego funciona, pero le faltan algunas funciones clave para brindar una experiencia de arcade adecuada. Primero, agreguemos una pantalla de título y, luego, una tabla de clasificación para que puedas competir con tus amigos. Usa la siguiente instrucción:
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.
¡Ya se ve un poco más profesional! 🙂
7. Implementa el juego en Cloud Run
Finalmente, llegó el momento de compartir nuestra creación con el mundo. Implementaremos toda la aplicación en Google Cloud Run para poder acceder a ella desde cualquier lugar.
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.
Dado que el juego ahora está disponible en la nube, sería una oportunidad perdida no permitir que se ejecute en dispositivos móviles. Puedes hacerlo con la siguiente instrucción:
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.
Vuelve a ejecutar el juego en tu navegador. Intenta acceder a la URL desde un dispositivo móvil también (quizás quieras generar un código QR para simplificar esta experiencia).
8. Usa el agente del navegador para probar el juego
Si bien un juego suele ser difícil de probar automáticamente, ya que depende de la retroalimentación visual, podemos aprovechar la automatización para, al menos, garantizar que la implementación funcione correctamente y que tengamos los elementos básicos en su lugar.
Para ello, usaremos el subagente del navegador. En Antigravity, un subagente es un personaje aislado con un contexto nuevo, perfecto para tareas en las que no quieres que el contexto actual influya en los resultados o cuando quieres evitar que la tarea "contamine" tu ventana de contexto principal.
El agente del navegador es un agente integrado especial para tareas relacionadas con el navegador. Ten en cuenta que, solo para este paso, debemos usar la app de escritorio de Antigravity, ya que el agente del navegador no está disponible en la línea de comandos.
Abre la app de escritorio de Antigravity y comienza una conversación nueva en el proyecto Cloud Crush:
Puedes activar el agente secundario del navegador escribiendo /browser seguido de esta instrucción:
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)
Este enfoque nos permite usar las capturas de pantalla para corregir elementos de la IU que, de otro modo, podrían ser difíciles de describir solo con texto.
Puedes hacer referencia a archivos con el símbolo “@” seguido del nombre del archivo. Por ejemplo, aquí le pido al agente que aumente el tamaño del logotipo en la pantalla de título:
Si bien este ejemplo es un poco artificial, ya que el modelo no necesariamente necesita "ver" la imagen para aplicar una corrección del 50% en el tamaño, es una técnica útil para realizar ajustes en la IU en los que podría ser más difícil describir el problema en formato de texto. También permite que el agente valide su propio trabajo tomando capturas de pantalla antes y después, así que ten este truco a mano.
9. Crea un agente personalizado para proteger el juego
Una preocupación común con las aplicaciones "vibe-coded" es cómo mantener la alta calidad y las prácticas recomendadas desde las perspectivas de codificación y seguridad. Si bien puedes intentar mejorar tus instrucciones para que sean muy rigurosas en ambos aspectos, cuanto más agregues a una instrucción, menos enfocado estará el agente, lo que a menudo genera resultados subóptimos.
Para este tipo de situaciones, lo ideal es usar subagentes, ya que pueden enfocarse con precisión en la tarea que les asignes. Creemos un agente personalizado para realizar una auditoría de seguridad en este código y asegurarnos de que no se filtren credenciales ni nos expongamos a riesgos innecesarios durante la implementación de este juego.
Esta instrucción proporciona una buena línea de base para el 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.
Ten en cuenta que Antigravity usará la herramienta "DefineSubagent" para crear el agente nuevo:
Pídele al agente que realice una verificación de seguridad en el código del juego con la siguiente instrucción:
Run the security auditor agent in this code
Deberías ver algo como esto:
Una vez que el agente complete su tarea, deberías ver un informe como este:
Pidámosle a Antigravity que los corrija por nosotros 🙂:
Fix these findings for me please!
Y listo:
Ten en cuenta que los agentes creados de esta manera solo existen durante la conversación. Si quieres tener un agente que se pueda "reutilizar" entre sesiones, puedes crearlo con un archivo de configuración. Para obtener más información, consulta el comando /agents.
10. Conclusión
¡Felicitaciones! Usaste correctamente la CLI de Antigravity para compilar, implementar, probar y auditar un juego de arcade, lo que demuestra flujos de trabajo avanzados basados en agentes, desde el andamiaje inicial hasta la implementación.
Limpieza
Para evitar que se apliquen cargos a tu cuenta de Google Cloud, borra los recursos que creaste durante este codelab.
- Borra el servicio de Cloud Run:
I'm finished with this project. Delete the cloud run deployment.
- Borra el directorio del proyecto:
cd .. && rm -rf codelab-match3
Como alternativa, puedes borrar todo el proyecto de Google Cloud si se creó solo para este codelab.
Próximos pasos
Puedes continuar tu recorrido de aprendizaje explorando otros codelabs en esta plataforma o mejorando Cloud Crush por tu cuenta. Solo no olvides limpiar los recursos cuando termines de usarlos.
¡Suerte con la programación!