Gemini CLI ile 3'lü Eşleştirme Arcade Oyunu Oluşturma

1. Giriş

Bu codelab'de, komut satırı kodlama aracımız Gemini 3 ve Gemini CLI'ı kullanarak CloudCrush adlı 3'lü eşleştirme arcade oyununu oluşturacaksınız. Oyun, Go dilinde yazılacak ve Cloud Run kullanılarak Google Cloud'a dağıtılacak.

Bu codelab'in temel amacı, kodu manuel olarak yazmak yerine sizin için uygulama oluşturması amacıyla aracıyı düzenleme becerilerini geliştirmektir. Bu teknolojileri daha önce kullanmamış olsanız bile tüm geliştirme görevlerini Gemini CLI'a devredeceksiniz.

Bu codelab, ajan tabanlı kodlama iş akışlarını öğrenmek isteyen orta düzey geliştiriciler içindir. Bu laboratuvarın tahmini toplam süresi 60 dakikadır. Bu codelab'de oluşturulan kaynaklar, kullanıma dayalı fiyatlandırma kullanır.

Yapacaklarınız

Go ve Ebitengine çerçevesini kullanarak temel üçlü eşleştirme oyunu mantığını oluşturun.
WebAssembly (WASM) kullanarak oyunu web tarayıcısında çalışacak şekilde uyarlayın.
Oyunu ve yüksek skor API'sini Cloud Run'a dağıtın.
Test ve kod incelemesi için özel alt aracıları ve uzantıları düzenleme

Ön koşullar

Programlama dilleriyle ilgili temel bilgiler
Bulut altyapısı hakkında temel bilgiler
Google Cloud Console hakkında temel bilgiler

Neler öğreneceksiniz?

Karmaşık uygulamalar oluşturmak için kodlama aracısıyla çalışma
Çok formatlı bağlamda Gemini ile çalışma
Cloud Run'ı kullanarak uygulamaları buluta dağıtma

İhtiyacınız olanlar

Bu atölye çalışması Cloud Shell kullanılarak tamamen bulutta yapılabilir. Ancak yerel makinenizi kullanmayı tercih ederseniz aşağıdakilere ihtiyacınız olacaktır:

Gemini CLI. geminicli.com adresindeki talimatları uygulayarak indirip yükleyin.
Go araç zinciri (1.26 veya sonraki sürüm) go.dev adresindeki talimatları kullanarak indirip yükleyin.
Google Cloud ile etkileşim kurmak için gcloud CLI. Google Cloud belgelerindeki talimatları kullanarak indirin ve yükleyin.
Google Cloud faturalandırma hesabı (oyunu buluta dağıtmak için)

Önemli Teknolojiler

Kullanacağımız teknolojiler hakkında daha fazla bilgiyi burada bulabilirsiniz:

Gemini CLI: Geliştirme temsilcisi
Gemini 3: Sınırları zorlayan büyük dil modelimizin en yeni sürümü

2. Ortam Kurulumu

Proje ayarlama

Google Cloud projesi oluşturma

Google Cloud Console'daki proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.
Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun. Bir projede faturalandırmanın etkin olup olmadığını kontrol etmeyi öğrenin.

Cloud Shell'i Başlatma

Cloud Shell, Google Cloud'da çalışan ve gerekli araçların önceden yüklendiği bir komut satırı ortamıdır.

Google Cloud Console'un üst kısmından Cloud Shell'i etkinleştir'i tıklayın.
Cloud Shell'e bağlandıktan sonra kimlik doğrulamanızı onaylayın:
```
gcloud auth list
```
Projenizin yapılandırıldığını onaylayın:
```
gcloud config get project
```

Projeniz beklendiği gibi ayarlanmamışsa şu şekilde ayarlayın:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

3. Proje Ayarları

Proje dizinini oluşturma

Öncelikle projeniz için yeni bir dizin oluşturmamız gerekiyor. Terminalinizde aşağıdaki komutları çalıştırın:

mkdir -p codelab-match3 && cd codelab-match3

Gemini CLI'yı başlatma

Öncelikle, Gemini KSA'nın doğru şekilde yüklendiğinden emin olalım. Terminalinizde şunu çalıştırın:

gemini --version

Aşağıdakine benzer bir tablo görürsünüz:

$ gemini --version
0.37.1

Şimdi gemini komutuyla Gemini CLI'yi başlatın:

gemini

Gemini CLI istemini görmeniz gerekir:

Gemini CLI istemini görüyorsanız kullanmaya hazırsınız demektir. Aksi takdirde, önceki kurulum adımlarından herhangi birini atlayıp atlamadığınızı tekrar kontrol edin.

Model yönlendirmeyi etkinleştirme

Model yönlendirme, aracı belirli bir görev üzerinde çalışırken araca ek bağlam bilgisi eklemenizi sağlayan bir özelliktir. Bu özelliği, yanlış yöne gittiğini gördüğünüzde aracıya yol göstermek, aracı yanıtını iyileştirmek için açıklayıcı bilgiler eklemek veya orijinal istemde atlanan küçük özellikleri dahil etmek için kullanabilirsiniz.

Model yönlendirmeyi etkinleştirmek için /settings komutunu kullanarak ayarlar menüsünü açın ve arama kutusuna "steering" (yönlendirme) yazın. Ardından, Model Yönlendirmeyi Etkinleştir seçeneğini doğru olarak ayarlayın.

Değişikliğin geçerli olması için CLI'yı yeniden başlatmanız gerekebilir ("r" tuşuna basarak).

Öğeleri indirme

Oyunda kullanılacak resimleri indirmemiz gerekiyor. Dosyalar, GitHub'da buradaki depoda saklanır. Bu dosyaları manuel olarak indirebilir veya aşağıdaki istemi kullanarak Gemini'dan sizin için indirmesini isteyebilirsiniz:

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. Plan modu ve model yönlendirme ile oyunu oluşturma

Öncelikle temel 3'lü eşleştirme oyunu mantığını oluşturun. Bu karmaşık bir görev olduğundan geliştirmeyi düzenlemek için plan modunda Gemini CLI'ı kullanmak en iyisidir.

Gemini CLI isteminde eğik çizgi komutu /plan ile plan modunu açıp kapatın:

/plan

Plan modu etkin durumdayken aşağıdaki istemi kopyalayıp Gemini CLI'ye yapıştırın:

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 KSA, planı oluşturmadan önce sizden birkaç açıklama sorusu isteyebilir.

Örneğin, burada tek dosya mı yoksa çok dosyalı uygulama mı tercih ettiğiniz soruluyor:

Burada animasyonlarla ilgili tercihlerimiz soruluyor:

Son soru, öğeleri go:embed ile ikili dosyanın içine yerleştirme hakkındadır:

Tüm soruları yanıtladıktan sonra, göndermek için Enter tuşuna basmadan önce yanıtlarınızı son bir kez daha inceleyebilirsiniz.

Plan tamamlandıktan sonra incelemeniz istenir:

Yorum kutusunun alt kısmında planı olduğu gibi kabul etme veya geri bildirimimizi ekleme seçenekleri bulunur.

Bu fırsatı kullanarak orijinal istemde unutulan yeni bir koşul ekleyin:

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.

Uygulama planını onaylamanız için son bir kez daha istem gösterilir:

Aracının çalışmaya başlaması için Enter tuşuna basın. Temsilci, plan modundan çıkarak kodu yazmaya başlar.

Bu noktada, normalde işlemin tamamlanmasını beklememiz veya uygulamada değişiklik yapmak istiyorsak ESC tuşuyla işlemi kesintiye uğratmamız gerekirdi. Ancak model yönlendirme etkin olduğundan modeli düzeltmek için talimatları sıraya alabiliriz.

Aracı çalışırken "model yönlendirme" özelliğini göstermek için aşağıdaki kodu aracı sohbet penceresine yapıştırın. Bu kod, komutları uygulamayı değiştirecek şekilde nasıl sıraya alabileceğinizi gösterir:

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.

Bu istemin "yönlendirme ipucu" olarak sıraya alındığını görürsünüz:

Planı kabul edin ve temsilcinin tüm şartlarınızı uygulamasını izleyin.

Temsilci uygulama işlemini tamamladığında masaüstü sürümünü göstermek için proje klasöründe go run main.go komutunu çalıştırın. Bu komutu çalıştırmak için Gemini CLI'dan çıkmanız gerekmez. Yazın. (ünlem işareti) ile kabuk moduna girip komutu buradan çalıştırın:

Kabuk modunda çalıştırmanın avantajı, oluşabilecek sorunların hemen aracı bağlamında yakalanmasıdır. Örneğin, bu durumda temsilci bazı bağımlılıkları indirmeyi unutmuş:

Escape tuşuna basarak kabuk modundan çıkabilir ve ardından aracıdan hatayı inceleyip düzeltmesini isteyebilirsiniz:

Başarılı sonuç şu şekilde görünmelidir:

Oyunu oynayarak ve oyun parametrelerini deneyimden memnun kalana kadar ince ayar yaparak (ör.animasyonu hızlandırma veya yavaşlatma, komutlara yanıt verme şeklini ayarlama vb.) deneyin.

5. Oyunu web tarayıcısında çalışacak şekilde uyarlayın

Yeni oluşturduğunuz Ebitengine oyunu bir masaüstü uygulamasıdır. Web'de çalışmasını sağlamak için WebAssembly'ye dönüştürebiliriz.

Aşağıdaki istemi kullanarak temsilciye yol gösterin:

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.

Aracı görevi tamamladıktan sonra oyun sunucusunu arka planda çalıştırmasını isteyebilirsiniz.

Ctrl+B tuş kombinasyonunu kullanarak arka plan işlemlerini yönetebilirsiniz:

Bu pencereyi kapatmak için tekrar Ctrl+B tuşlarına basın.

Web'de çalışan oyunu görmek için tarayıcınızda http://localhost:8080 adresini açın:

Web'de çalışır duruma getirdiğinize göre artık buluta dağıtmadan önce son bir rötuş yapmanın zamanı geldi.

6. Başlık ekranı ve skor tablosunu oluşturma

Oyun çalışıyor ancak uygun arcade deneyimi için birkaç temel özellik eksik. Önce bir başlık ekranı ekleyelim, ardından arkadaşlarınızla yarışabilmeniz için bir skor tablosu ekleyelim.

Aşağıdaki istemi kullanarak her iki sorunu da düzeltin:

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).

Aşağıda başlık ekranına bir örnek verilmiştir:

Artık biraz daha profesyonel görünüyor. 🙂

7. Oyunu Cloud Run'a dağıtma

Sonunda, oluşturduğumuz içeriği dünyayla paylaşma zamanı geldi. Oyuna her yerden erişebilmek için oyunu Google Cloud Run'a dağıtın.

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.

Oyun artık bulutta canlı olarak yayınlandığı için mobil cihazlarda çalışmasına izin vermemek kaçırılmış bir fırsat olurdu. Bunu aşağıdaki istemle yapabilirsiniz:

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.

Oyunu tarayıcınızda tekrar çalıştırın. QR kodunu kullanarak oyuna mobil cihazdan da erişmeyi deneyin.

8. Oyunu test etmek için tarayıcı aracısını kullanma

Gemini CLI'da alt temsilci, mevcut bağlamın sonuçları etkilemesini istemediğiniz, uzun süren ve/veya yüksek hassasiyetli görevler için ideal olan, yeni bir bağlama sahip izole bir karakterdir.

Oyunları geleneksel test araçlarıyla (ör. birim ve entegrasyon testleri) test etmek doğal olarak zordur ancak bazı testleri bizim için yapması amacıyla tarayıcı aracısını kullanabiliriz. Tarayıcı aracısı, kendi Chrome tarayıcısını başlatabilir ve DOM komutları vererek oyun ekranlarında gezinebilir. Ayrıca ekran görüntüsü alma özelliği de vardır. Bu özelliği, testi belgelemek ve daha sonra kullanıcı arayüzünde küçük ayarlamalar yapması için temsilciye geri göndermek üzere kullanabiliriz.

Tarayıcı temsilcisi şu anda deneysel olduğundan önce etkinleştirmemiz gerekiyor. Aracı proje düzeyinde etkinleştirmek için bu istemi Gemini CLI'ye verin.

Create a .gemini/settings.json file with the following content to
configure the browser sub agent:

{
  "agents": {
    "overrides": {
      "browser_agent": {
        "enabled": true
      }
    }
  }
}

Bu değişikliğin geçerli olması için aracı yeniden başlatmanız gerekir. /chat save komutuyla mevcut görüşmeyi kaydedin:

Ctrl+D tuşlarına iki kez basarak Gemini CLI'dan çıkın ve tekrar başlatın. /chat resume cloud-crush ile olan görüşmeyi geri yükleyin.

Artık tarayıcı aracısına erişebilirsiniz. Bir görevi tarayıcı aracısına devretmek istediğinizde @browser_agent ile bahsedebilirsiniz:

Şimdi, dağıtılan oyunumuzu değerlendirmek için tarayıcı aracısını kullanın:

@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.

Onay ekranını görmeniz gerekir:

Aracıya ve gerekli araçlara izin verdikten sonra yeni bir Chrome tarayıcı penceresi açılır. Bu, aracı tarafından kontrol edilen tarayıcıdır. Görsel ipucu, ekrandaki mavi kenarlık ve alttaki "Gemini KSA bu tarayıcıyı kontrol ediyor" mesajı olacaktır:

İşlem tamamlandığında şu gibi bir mesaj gösterilir:

Tarayıcı aracısı tarafından alınan ekran görüntülerinden bazıları aşağıda verilmiştir:

title_screen.png:

game_board.png:

Şimdi, oyunun kullanıcı arayüzünü optimize etmek için temsilci tarafından çekilen resimlerden birini kullanmanın tam zamanı. Örneğin, şöyle diyebilirsiniz:

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. Oyunu güvenli hale getirmek için özel bir aracı oluşturma

"Vibe-coded" uygulamalarla ilgili yaygın bir endişe, hem kodlama hem de güvenlik açısından yüksek kaliteyi ve en iyi uygulamaları nasıl koruyacağınızdır. İstemlerinizi bu iki açıdan da çok titiz olacak şekilde iyileştirmeyi deneyebilirsiniz. Ancak bir isteme ne kadar çok şey eklerseniz aracı o kadar az odaklanır. Bu da genellikle idealin altında sonuçlar verir. Bu tür senaryolarda, ana aracının bağlamından ayrı bir bağlamda çalıştıkları ve kendilerine verdiğiniz göreve odaklanabildikleri için alt aracıları kullanmak idealdir. Bu kodda güvenlik denetimi yapmak ve bu oyunu Cloud Run'a dağıtırken herhangi bir kimlik bilgisini sızdırmadığımızdan veya kendimizi gereksiz risklere maruz bırakmadığımızdan emin olmak için özel bir aracı oluşturalım.

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.

Değişikliğin geçerli olması için KSA'yı yeniden başlatmanız gerekir. /chat save ile sohbet oturumunu kaydedin ve daha önce yaptığımız gibi /chat resume ile devam ettirin.

CLI devam ettiğinde, başlangıçta yeni aracı otomatik olarak algılar:

Acknowledge and Enable simgesini tıklayın ve ardından temsilciden aşağıdaki istemi kullanarak oyun kodunda güvenlik kontrolü yapmasını isteyin:

@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

Aşağıdakine benzer bir tablo görürsünüz:

Denetimi tamamladıktan sonra önerilerde bulunur. Bu örnekte, düzeltilmesi gereken birkaç önemli nokta bulundu:

Bulgularınız varsa Gemini CLI'dan bunları sizin için düzeltmesini isteyin. 🙂

10. Sonuç

Tebrikler! Gemini CLI'ı kullanarak bir arcade oyunu oluşturma, dağıtma, test etme ve denetleme işlemlerini başarıyla tamamladınız. Bu süreçte, ilk iskeleden dağıtıma kadar gelişmiş aracı iş akışlarını gösterdiniz.

Temizleme

Bu codelab'e daha sonra geri dönmeyi planlamıyorsanız bu codelab sırasında oluşturulan kaynakları silmeniz önerilir.

Cloud Run hizmetini silin:

Gemini KSA'dan sizin için silmesini isteyin:

I'm finished with this project. Delete the cloud run deployment.

Proje dizinini silin:

cd .. && rm -rf codelab-match3

Alternatif olarak, yalnızca bu codelab için oluşturulduysa Google Cloud projesinin tamamını silebilirsiniz.

Sonraki adımlar

Bu platformdaki diğer codelab'leri inceleyerek veya Cloud Crush'ı kendi başınıza geliştirerek öğrenme yolculuğunuza devam edebilirsiniz.

Oyunu geliştirmek için birkaç öneri:

4 veya daha fazla Gem eşleştirildiğinde görünen özel bir "Gemini" Gem'i (gemini.png kullanılarak) ekleyin. 3 veya daha fazla Gemini mücevherini eşleştiren oyuncular bonus süre kazanır.
Müzik ekleyin. Gemini ana sayfasında Lyria 3'ü kullanarak müzik üretebilirsiniz.
Ses efektleri ekleme
Başka oyun modları ekleme

Keyifli kodlamalar!