1. Wprowadzenie
W tym ćwiczeniu utworzysz CloudCrush, czyli grę zręcznościową typu „dopasuj 3”, przy użyciu Gemini 3 i agenta do kodowania Antigravity. Gra zostanie napisana w języku Go i wdrożona w Google Cloud za pomocą Cloud Run.
Pamiętaj, że chociaż znajomość języka Go jest zalecana, nie jest wymagana, ponieważ agent będzie wykonywać całe kodowanie. Głównym celem tego ćwiczenia jest zdobycie umiejętności koordynowania pracy agenta, aby tworzył aplikacje za Ciebie, zamiast ręcznie pisać kod.
To ćwiczenie jest przeznaczone dla średnio zaawansowanych programistów, którzy chcą poznać zaawansowane przepływy pracy agentów. Szacowany łączny czas trwania tego modułu to 60 minut. Zasoby utworzone w tym ćwiczeniu korzystają z modelu cenowego opartego na wykorzystaniu.
Jakie zadania wykonasz
- Stwórz podstawową logikę gry typu „match 3” za pomocą języka Go i platformy Ebitengine.
- Dostosuj grę do uruchamiania w przeglądarce za pomocą WebAssembly (WASM).
- Wdróż grę i jej interfejs API wyników w Cloud Run.
- Orkiestracja wyspecjalizowanych sub-agentów i rozszerzeń na potrzeby testowania i inspekcji kodu
Wymagania wstępne
- Podstawowa znajomość języków programowania
- Podstawowa wiedza o infrastrukturze w chmurze
- Podstawowa znajomość konsoli Google Cloud
Czego się nauczysz
- Jak współpracować z agentem do kodowania przy tworzeniu złożonych aplikacji
- Jak korzystać z Gemini w kontekście multimodalnym
- Jak wdrażać aplikacje w chmurze za pomocą Cloud Run
Czego potrzebujesz
Te warsztaty można w całości przeprowadzić w chmurze za pomocą Cloud Shell, ale jeśli wolisz używać komputera lokalnego, potrzebujesz tych elementów:
- Antigravity 2.0 i interfejs wiersza poleceń Antigravity. Pobierz i zainstaluj go, postępując zgodnie z instrukcjami na stronie antigravity.google.
- Łańcuch narzędzi Go (wersja 1.26 lub nowsza). Pobierz i zainstaluj go, postępując zgodnie z instrukcjami na stronie go.dev.
- gcloud CLI do interakcji z Google Cloud; Pobierz i zainstaluj go, postępując zgodnie z instrukcjami w dokumentacji Google Cloud.
- Konto rozliczeniowe Google Cloud (do wdrożenia gry w chmurze).
Kluczowe technologie
Więcej informacji o technologiach, z których będziemy korzystać, znajdziesz tutaj:
- Interfejs wiersza poleceń Antigravity: agent programistyczny
- Gemini 3: najnowsza wersja naszego zaawansowanego dużego modelu językowego
2. Konfiguracja środowiska
Wybierz jedną z tych opcji: Self-paced environment setup (Konfiguracja środowiska we własnym tempie), jeśli chcesz uruchomić ten przewodnik na własnym komputerze, lub Start Cloud Shell (Uruchom Cloud Shell), jeśli chcesz uruchomić go w chmurze.
Samodzielne konfigurowanie środowiska
- Zaloguj się w konsoli Google Cloud i utwórz nowy projekt lub użyj istniejącego. Jeśli nie masz jeszcze konta Gmail ani Google Workspace, musisz je utworzyć.
- Nazwa projektu to wyświetlana nazwa uczestników tego projektu. Jest to ciąg znaków, który nie jest używany przez interfejsy API Google. Zawsze możesz ją zaktualizować.
- Identyfikator projektu jest unikalny we wszystkich projektach Google Cloud i nie można go zmienić po ustawieniu. Konsola Cloud automatycznie generuje unikalny ciąg znaków. Zwykle nie musisz się tym przejmować. W większości ćwiczeń z programowania musisz odwoływać się do identyfikatora projektu (zwykle oznaczanego jako
PROJECT_ID). Jeśli wygenerowany identyfikator Ci się nie podoba, możesz wygenerować inny losowy identyfikator. Możesz też spróbować własnej nazwy i sprawdzić, czy jest dostępna. Po tym kroku nie można go zmienić i pozostaje on taki przez cały czas trwania projektu. - Warto wiedzieć, że istnieje też trzecia wartość, numer projektu, której używają niektóre interfejsy API. Więcej informacji o tych 3 wartościach znajdziesz w dokumentacji.
- Następnie musisz włączyć płatności w konsoli Cloud, aby korzystać z zasobów i interfejsów API Google Cloud. Wykonanie tego laboratorium nie będzie kosztować dużo, a może nawet nic. Aby wyłączyć zasoby i uniknąć naliczania opłat po zakończeniu tego samouczka, możesz usunąć utworzone zasoby lub projekt. Nowi użytkownicy Google Cloud mogą skorzystać z programu bezpłatnego okresu próbnego o wartości 300 USD.
Uruchamianie Cloud Shell
Z Google Cloud można korzystać zdalnie na laptopie, ale w tym ćwiczeniu użyjesz Google Cloud Shell, czyli środowiska wiersza poleceń działającego w chmurze.
W konsoli Google Cloud kliknij ikonę Cloud Shell na pasku narzędzi w prawym górnym rogu:
Uzyskanie dostępu do środowiska i połączenie się z nim powinno zająć tylko kilka chwil. Po zakończeniu powinno wyświetlić się coś takiego:
Ta maszyna wirtualna zawiera wszystkie potrzebne narzędzia dla programistów. Zawiera również stały katalog domowy o pojemności 5 GB i działa w Google Cloud, co znacznie zwiększa wydajność sieci i usprawnia proces uwierzytelniania. Wszystkie zadania w tym laboratorium możesz wykonać w przeglądarce. Nie musisz niczego instalować.
3. Konfiguracja projektu
Tworzenie katalogu projektu
Najpierw musimy utworzyć nowy katalog dla Twojego projektu. W terminalu uruchom te polecenia:
mkdir -p codelab-match3 && cd codelab-match3
Uruchamianie interfejsu wiersza poleceń Antigravity
Najpierw sprawdźmy, czy interfejs wiersza poleceń Antigravity został prawidłowo zainstalowany. Uruchom w terminalu:
agy --version
Powinien pojawić się ekran podobny do tego:
$ agy --version 1.0.2
Teraz uruchom interfejs wiersza poleceń Antigravity za pomocą polecenia agy:
agy
Antigravity zapyta, czy ufasz temu projektowi. Właśnie utworzyliśmy pusty folder, więc możemy mu zaufać. Potwierdź dostęp, a zostanie wyświetlony wiersz poleceń interfejsu CLI:
Jeśli widzisz wiersz poleceń Antigravity CLI, możesz przejść dalej. Jeśli nie, sprawdź, czy nie pominięto żadnego z poprzednich kroków konfiguracji.
4. Tworzenie gry podstawowej w trybie planowania
Zacznijmy od utworzenia podstawowej logiki gry typu „dopasuj 3 elementy”. Antygrawitacja domyślnie włącza się w trybie planowania, więc nie musisz wydawać żadnych specjalnych poleceń, aby przełączyć się na planowanie.
Warto jednak wiedzieć, że w każdej chwili możesz włączyć tryb planowania za pomocą polecenia po ukośniku /planning w wierszu poleceń Antigravity CLI:
/planning
Jeśli spróbujesz teraz uruchomić to polecenie, Antigravity przypomni Ci, że jest ono już w fazie planowania.
Przeciwieństwem trybu planowania jest tryb szybki, który możesz włączyć za pomocą tego symbolu: /fast.
/fast
W trybie szybkim Antigravity od razu zacznie pracować nad zadaniem. Jest on przeznaczony do prostszych, samodzielnych zadań. Tryb planowania jest przeznaczony do złożonych zadań, w przypadku których agent najpierw opracowuje plan, który możesz sprawdzić i ulepszyć przed wykonaniem.
Pobieranie komponentów
Musimy pobrać obrazy, które będą używane w grze. Jest to małe, samodzielne zadanie, więc nie musisz uruchamiać go w trybie planowania. Wykorzystaj tryb szybki, aby wykonać je od razu:
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 poprosi o uprawnienia do wykonania kilku poleceń powłoki w celu pobrania plików. Po zakończeniu zobaczysz coś takiego:
Tworzenie gry podstawowej
Gdy masz już gotowe komponenty, możesz zacząć tworzyć podstawową wersję gry. Tworzenie gry jest dość złożonym zadaniem, więc zanim podamy prompt, wróćmy do trybu planowania:
/planning
W trybie planowania skopiuj i wklej ten prompt w interfejsie 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.
Zanim zaproponuje plan, może przeprowadzić pewne działania, np. sprawdzić wymiary plików PNG. Po zakończeniu planu pojawi się prośba o jego sprawdzenie:
Zwróć szczególną uwagę na prawy dolny róg, w którym widnieje napis 1 artefakt i wskazówka, aby użyć klawisza /artifact do sprawdzenia. W Antigravity pliki pomocnicze, takie jak plany, listy zadań i przewodniki, są nazywane „artefaktami”, aby odróżnić je od zwykłych plików, które są częścią rozwiązania (np. kodu źródłowego).
Wpisanie w prompcie polecenia /artifact umożliwi Ci wyświetlenie planu i dodanie do niego komentarzy, jeśli zajdzie potrzeba wprowadzenia zmian.
/artifact
Powinien pojawić się ekran podobny do tego:
Zwróć uwagę, że jest tam plik o nazwie implementation_plan.md z opcjami otwierania, zatwierdzania i odrzucania. Aby go otworzyć, naciśnij Enter. Oto przykład, jak wygląda pakiet w moim systemie:
Możesz przewijać w górę i w dół za pomocą klawiszy strzałek, a w dowolnym wierszu możesz dodać komentarz, naciskając klawisz C. W tym przypadku nie podoba mi się, że używana jest starsza wersja Go, więc w wierszu 16 dodam komentarz, aby używać Go 1.26 (najnowszej wersji w momencie pisania tego artykułu):
Po wpisaniu komentarza pojawi się on w tekście:
Ważną sekcją, którą należy sprawdzić, jest „Plan weryfikacji”. Gry są trudne do automatycznego testowania, ale Go to język kompilowany, więc powinniśmy przynajmniej upewnić się, że model przekazuje nam kod, który się kompiluje. Jeśli automatyczny krok tworzenia pliku binarnego nie jest uwzględniony, dodaj go jako komentarz:
Ważną sekcją, którą należy sprawdzić, jest „Plan weryfikacji”. Gry są szczególnie trudne do automatycznego testowania, ale Go to język kompilowany, więc powinniśmy przynajmniej upewnić się, że model przekazuje nam kod, który się kompiluje. Jeśli automatyczny krok tworzenia pliku binarnego nie jest uwzględniony, dodaj go jako komentarz:
Powtarzaj ten proces, aż będziesz zadowolony(-a) z planu, a następnie naciśnij ESC, aby wrócić. Następnie naciśnij Y, aby potwierdzić wysłanie komentarzy do agenta:
Po naciśnięciu klawisza Y agent natychmiast rozpocznie pracę. Aby wyjść z menu „Artefakt”, musisz jeszcze raz nacisnąć ESC. Spowoduje to powrót do trybu promptu. W tym czasie agent może poprosić o wiele potwierdzeń wywołania narzędzia, ponieważ musi uruchamiać polecenia powłoki.
W międzyczasie możemy kontynuować pracę nad projektem, dodając kolejne prompty do kolejki. Możemy na przykład wykorzystać tę okazję, aby dodać nowe wymaganie, które zostało pominięte w pierwotnym promcie:
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.
W historii wiadomości pojawi się prompt w kolejce z małą strzałką przed nim:
Możesz też zauważyć, że liczba artefaktów rośnie. Oprócz planu Antigravity utworzy też listę zadań (task.md), aby śledzić każdy element, który musi wdrożyć, lub działanie, które musi wykonać. Po zakończeniu pracy utworzy plik z instrukcjami (walkthrough.md) z wyjaśnieniem osiągniętych celów. Możesz je wszystkie sprawdzić, ponownie używając polecenia /artifact.
Oto przykład pliku task.md po zakończeniu implementacji podstawowej wersji gry:
W każdej chwili możesz otworzyć te pliki i dodać do nich komentarze, które po wysłaniu do agenta zostaną umieszczone w kolejce do wykonania, tak jak umieszczone w niej prompty. Warto dodać komentarz do tych plików, aby przekazać agentowi dodatkowe informacje o swojej prośbie.
Po pomyślnym utworzeniu pliku binarnego powinien wyświetlić się komunikat podobny do tego:
Uruchom grę i sprawdź, czy działa zgodnie z oczekiwaniami. Warto uruchomić go w prompcie agenta. Aby przełączyć prompt na „tryb powłoki”, wpisz wykrzyknik „!”:
Pod promptem zobaczysz komunikat „activated bash mode” (włączono tryb bash). Aby uruchomić polecenie, naciśnij Enter. Uruchomienie pliku binarnego w tym trybie daje tę korzyść, że agent „obserwuje” wszystkie dane wyjściowe w terminalu, więc w przypadku niepowodzenia lub nagłego zamknięcia gry nie musisz wyjaśniać agentowi, co się stało. Od razu będzie mieć wszystkie potrzebne informacje z kontekstu powłoki.
Zagraj w grę i dostosuj jej parametry, aż będziesz zadowolony(-a) z wyniku (np.przyspiesz lub spowolnij animację, dostosuj reakcję na polecenia itp.).
Na przykład ten prompt ulepszy działanie aplikacji, dodając tryb ułatwień dostępu i nowe polecenia klawiaturowe:
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.
Po zakończeniu dopracowywania przejdź do następnej sekcji, aby przekonwertować go na aplikację internetową.
5. dostosować grę do działania w przeglądarce,
Gra Ebitengine jest obecnie aplikacją na komputery. Poprośmy interfejs wiersza poleceń Antigravity o dostosowanie go do uruchamiania w przeglądarce za pomocą WebAssembly (WASM). Obejmuje to skompilowanie kodu Go dla przeglądarki docelowej i skonfigurowanie podstawowego serwera WWW.
Aby poprowadzić agenta, użyj tego promptu:
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.
Pamiętaj, że agent spróbuje znaleźć w systemie plików plik o nazwie wasm_exec.js. Jest to oczekiwane i musisz na to zezwolić, ponieważ ten plik jest otoczką, która umożliwia uruchamianie plików binarnych Go za pomocą JS. Na przykład:
Gdy agent wykona zadanie, możesz polecić mu uruchomienie serwera gry w tle.
Teraz otwórz http://localhost:8080 w przeglądarce, aby zobaczyć grę działającą w internecie:
Teraz, gdy działa w internecie, dopracujmy ją przed wdrożeniem w chmurze.
6. Tworzenie ekranu tytułowego i tabeli wyników
Gra działa, ale brakuje w niej kilku kluczowych funkcji, które zapewniają odpowiednie wrażenia z gry na automatach. Najpierw dodaj ekran tytułowy, a potem tabelę wyników, aby móc rywalizować ze znajomymi. Użyj tego prompta:
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.
Zaczyna to wyglądać bardziej profesjonalnie. 🙂
7. Wdrażanie gry w Cloud Run
Nadszedł wreszcie czas, aby podzielić się naszym dziełem ze światem. Wdrożymy całą aplikację w Google Cloud Run, aby można było uzyskać do niej dostęp z dowolnego miejsca.
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.
Skoro gra jest już dostępna w chmurze, byłoby szkoda nie umożliwić jej uruchamiania na urządzeniach mobilnych. Możesz to zrobić za pomocą tego prompta:
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.
Uruchom grę ponownie w przeglądarce. Spróbuj też otworzyć adres URL na urządzeniu mobilnym (możesz wygenerować kod QR, aby ułatwić sobie to zadanie).
8. Testowanie gry za pomocą agenta przeglądarki
Gry często trudno jest testować automatycznie, ponieważ opierają się na informacjach wizualnych. Możemy jednak wykorzystać pewną automatyzację, aby przynajmniej upewnić się, że wdrożenie działa prawidłowo i mamy podstawowe elementy.
Aby to zrobić, użyjemy subagenta przeglądarki. W Antigravity subagent to odizolowana persona z nowym kontekstem, idealna do zadań, w których nie chcesz, aby bieżący kontekst wpływał na wyniki, lub gdy chcesz zapobiec „zanieczyszczeniu” głównego okna kontekstu.
Agent przeglądarki to specjalny wbudowany agent do zadań związanych z przeglądarką. Pamiętaj, że w tym kroku musimy użyć aplikacji na komputery Antigravity, ponieważ agent przeglądarki nie jest obecnie dostępny w wierszu poleceń.
Otwórz aplikację Antigravity na komputer i rozpocznij nową rozmowę w projekcie Cloud Crush:
Możesz wywołać sub-agenta przeglądarki, wpisując /browser, a następnie ten 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)
Dzięki temu możemy używać zrzutów ekranu do poprawiania elementów interfejsu, które trudno byłoby opisać tylko za pomocą tekstu.
Możesz odwołać się do plików, używając symbolu „@” i nazwy pliku. Na przykład proszę agenta o zwiększenie rozmiaru logo na ekranie tytułowym:
Ten przykład jest nieco naciągany, ponieważ model nie musi „widzieć” obrazu, aby zastosować 50-procentową korektę rozmiaru. Jest to jednak przydatna technika wprowadzania zmian w interfejsie, w przypadku których trudniej byłoby opisać problem w formie tekstowej. Umożliwia to też agentowi weryfikowanie własnej pracy przez robienie zrzutów ekranu przed i po wykonaniu zadania. Warto więc mieć tę sztuczkę w swoim arsenale.
9. Tworzenie agenta niestandardowego do zabezpieczania gry
Jednym z częstych problemów związanych z aplikacjami „zakodowanymi w określonym stylu” jest utrzymanie wysokiej jakości i najlepszych praktyk zarówno z perspektywy kodowania, jak i bezpieczeństwa. Możesz spróbować ulepszyć prompty, aby były bardzo rygorystyczne pod względem obu tych aspektów, ale im więcej dodasz do promptu, tym mniej skoncentrowany będzie agent, co często prowadzi do suboptymalnych wyników.
W takim przypadku idealne jest użycie subagentów, ponieważ mogą się oni skupić na powierzonym im zadaniu. Utwórzmy niestandardowego agenta, który przeprowadzi audyt bezpieczeństwa tego kodu i sprawdzi, czy nie wyciekają żadne dane logowania ani czy podczas wdrażania tej gry nie narażamy się na niepotrzebne ryzyko.
Ten prompt stanowi dobrą podstawę dla agenta:
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.
Pamiętaj, że Antigravity użyje narzędzia „DefineSubagent” do utworzenia nowego agenta:
Poproś agenta o sprawdzenie kodu gry pod kątem bezpieczeństwa, używając tego prompta:
Run the security auditor agent in this code
Powinien pojawić się ekran podobny do tego:
Gdy agent wykona zadanie, zobaczysz raport podobny do tego:
Poprośmy Antigravity o ich naprawienie 🙂:
Fix these findings for me please!
I gotowe:
Pamiętaj, że agenty utworzone w ten sposób istnieją tylko przez czas trwania rozmowy. Jeśli chcesz mieć agenta, którego można „ponownie wykorzystać” w różnych sesjach, możesz go utworzyć za pomocą pliku konfiguracyjnego. Więcej informacji znajdziesz w /agents.
10. Podsumowanie
Gratulacje! Udało Ci się użyć interfejsu wiersza poleceń Antigravity do utworzenia, wdrożenia, przetestowania i sprawdzenia gry zręcznościowej. Pokazuje to zaawansowane przepływy pracy oparte na agentach, od początkowej struktury po wdrożenie.
Czyszczenie
Aby uniknąć obciążenia konta Google Cloud bieżącymi opłatami, usuń zasoby utworzone podczas tego ćwiczenia.
- Usuń usługę Cloud Run:
I'm finished with this project. Delete the cloud run deployment.
- Usuń katalog projektu:
cd .. && rm -rf codelab-match3
Możesz też usunąć cały projekt w chmurze Google, jeśli został utworzony wyłącznie na potrzeby tego ćwiczenia.
Dalsze kroki
Możesz kontynuować naukę, przeglądając inne ćwiczenia w Codelabs na tej platformie lub samodzielnie ulepszając Cloud Crush. Nie zapomnij tylko zwolnić miejsca, gdy skończysz z nimi pracę.
Pozdrawiamy