פיתוח משחק ארקייד מסוג Match 3 באמצעות Gemini CLI

1. מבוא

ב-Codelab הזה, תיצרו את CloudCrush, משחק ארקייד מסוג Match 3, באמצעות Gemini 3 ו-Gemini CLI, סוכן הקידוד שלנו בשורת הפקודה. המשחק ייכתב ב-Go וייפרס ב-Google Cloud באמצעות Cloud Run.

המטרה העיקרית של שיעור Codelab הזה היא לפתח את הכישורים הדרושים כדי לתת לסוכן הוראות לבניית אפליקציות במקום לכתוב קוד באופן ידני. תקבלו את כל משימות הפיתוח מ-Gemini CLI, גם אם לא השתמשתם בטכנולוגיות האלה בעבר.

ה-Codelab הזה מיועד למפתחים ברמת ביניים שרוצים ללמוד על תהליכי עבודה של כתיבת קוד באמצעות סוכנים. משך הזמן הכולל המשוער לשיעור ה-Lab הזה הוא 60 דקות. המשאבים שנוצרו בשיעור Codelab הזה משתמשים בתמחור לפי צריכה.

הפעולות שתבצעו:

פיתוח הלוגיקה הבסיסית של משחק התאמה באמצעות Go ו-Ebitengine.
התאמת המשחק להרצה בדפדפן אינטרנט באמצעות WebAssembly‏ (WASM)
פורסים את המשחק ואת ה-API של התוצאות הגבוהות ב-Cloud Run.
תיאום בין סוכני משנה ותוספים מיוחדים לבדיקה ולבדיקת קוד

דרישות מוקדמות

ידע בסיסי בשפות תכנות
ידע בסיסי בתשתית ענן
ידע בסיסי במסוף Google Cloud

מה תלמדו

איך עובדים עם סוכן תכנות כדי לבנות אפליקציות מורכבות
איך עובדים עם Gemini בהקשר מולטימודאלי
איך פורסים אפליקציות בענן באמצעות Cloud Run

הדרישות

אפשר להשתתף בסדנה הזו באופן מלא בענן באמצעות Cloud Shell, אבל אם אתם מעדיפים להשתמש במחשב המקומי, תצטרכו את הדברים הבאים:

‫Gemini CLI. מורידים ומתקינים אותו לפי ההוראות בכתובת geminicli.com.
ערכת הכלים של Go (גרסה 1.26 ואילך). מורידים ומתקינים אותו לפי ההוראות בכתובת go.dev
‫ה-CLI של gcloud לאינטראקציה עם Google Cloud. מורידים ומתקינים אותו לפי ההוראות במסמכי Google Cloud
חשבון לחיוב ב-Google Cloud (כדי לפרוס את המשחק בענן)

טכנולוגיות מרכזיות

כאן אפשר למצוא מידע נוסף על הטכנולוגיות שבהן נשתמש:

‫Gemini CLI: סוכן הפיתוח
‫Gemini 3: הגרסה הכי עדכנית של מודל שפה גדול ומתקדם

2. הגדרת הסביבה

הגדרת הפרויקט

יצירת פרויקט ב-Google Cloud

במסוף Google Cloud, בדף לבחירת הפרויקט, בוחרים פרויקט ב-Google Cloud או יוצרים פרויקט.
הקפידו לוודא שהחיוב מופעל בפרויקט שלכם ב-Cloud. כך בודקים אם החיוב מופעל בפרויקט

הפעלת Cloud Shell

‫Cloud Shell היא סביבת שורת פקודה שפועלת ב-Google Cloud, וכוללת מראש את הכלים הדרושים.

לוחצים על Activate Cloud Shell בחלק העליון של מסוף Google Cloud.
אחרי שמתחברים ל-Cloud Shell, מאמתים את האימות:
```
gcloud auth list
```
מוודאים שהפרויקט מוגדר:
```
gcloud config get project
```
אם הפרויקט לא מוגדר כמו שציפיתם, מגדירים אותו:
```
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID
```

3. הגדרת הפרויקט

יצירת ספריית הפרויקט

קודם צריך ליצור ספרייה חדשה לפרויקט. בטרמינל, מריצים את הפקודות הבאות:

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

הפעלת Gemini CLI

קודם כול, נבדוק שהתקנתם את Gemini CLI בצורה נכונה. מריצים בטרמינל:

gemini --version

אתם אמורים לראות משהו כזה:

$ gemini --version
0.37.1

עכשיו מפעילים את Gemini CLI באמצעות הפקודה gemini:

gemini

אמורה להופיע ההנחיה של Gemini CLI:

אם מופיעה ההנחיה של Gemini CLI, אתם יכולים להמשיך. אם לא, צריך לבדוק שוב שלא פספסתם אף אחד משלבי ההגדרה הקודמים.

הפעלת הכוונה של מודל

התכונה 'הכוונת מודל' מאפשרת להוסיף הקשר נוסף לסוכן בזמן שהוא עדיין עובד על משימה מסוימת. אתם יכולים להשתמש בו כדי לתקן את הטעויות של הסוכן אם הוא מתחיל לסטות מהנושא, כדי להוסיף מידע להבהרה ולשפר את התשובה של הסוכן, או כדי לכלול תכונות משניות שלא נכללו בהנחיה המקורית.

כדי להפעיל את ההיגוי של המודל, פותחים את תפריט ההגדרות באמצעות הפקודה ‎ /settings ומקלידים 'היגוי' בתיבת החיפוש. אחר כך מגדירים את האפשרות Enable Model Steering (הפעלת ניהול מודלים) לערך true.

יכול להיות שיהיה צורך להפעיל מחדש את ה-CLI כדי שהשינוי ייכנס לתוקף (על ידי לחיצה על המקש r).

הורדת הנכסים

אנחנו צריכים להוריד את התמונות שישמשו במשחק. הקבצים מאוחסנים ב-GitHub במאגר כאן. אתם יכולים להוריד אותם באופן ידני או לבקש מ-Gemini לעשות זאת בשבילכם באמצעות ההנחיה הבאה:

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. יצירת המשחק באמצעות מצב התכנון והכוונת המודל

מתחילים בבניית הלוגיקה המרכזית של משחק התאמת שלשות. מכיוון שמדובר במשימה מורכבת, מומלץ להשתמש ב-Gemini CLI במצב תכנון כדי לתאם את הפיתוח.

מחליפים את מצב התוכנית באמצעות פקודה דרך שורת הפקודות /plan בהנחיה של Gemini CLI:

/plan

כשהמצב 'תכנון' מופעל, מעתיקים את ההנחיה הבאה ומדביקים אותה ב-Gemini 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.

יכול להיות שממשק Gemini CLI ישאל אתכם כמה שאלות כדי להבין טוב יותר את התוכנית לפני שהוא ייצור אותה.

לדוגמה, כאן מוצגת שאלה לגבי העדפה של קובץ יחיד או אפליקציה עם כמה קבצים:

והנה היא שואלת על ההעדפות שלנו לגבי אנימציות:

השאלה האחרונה היא לגבי הטמעת הנכסים בקובץ הבינארי עצמו באמצעות go:embed:

אחרי שעונים על כל השאלות, אפשר לבדוק אותן בפעם האחרונה לפני שלוחצים על Enter כדי לשלוח.

אחרי שהתוכנית תהיה מוכנה, תתבקשו לבדוק אותה:

בתחתית תיבת הביקורת יש אפשרויות לאישור התוכנית כמו שהיא או להוספת משוב.

זו הזדמנות להוסיף דרישה חדשה שלא נכללה בהנחיה המקורית:

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.

תתבקשו לאשר את תוכנית ההטמעה בפעם האחרונה:

מקישים על Enter כדי שהנציג יתחיל את העבודה. הסוכן יצא ממצב התכנון ויתחיל לכתוב את הקוד.

בשלב הזה, בדרך כלל נצטרך לחכות לסיום ההטמעה או להפריע לה באמצעות מקש ESC אם נרצה לבצע שינויים בהטמעה, אבל מכיוון שהפעלנו את התכונה 'הכוונת מודל', אנחנו יכולים להוסיף הוראות לתור כדי לבצע תיקון של המודל.

בזמן שהסוכן פועל, מדביקים את הטקסט הבא בחלון הצ'אט עם הסוכן כדי להדגים את היכולת 'הכוונת המודל', וכך להראות איך אפשר להוסיף פקודות לתור כדי לשנות את אופן ההטמעה:

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.

ההנחיה הזו תופיע בתור 'הצעה להכוונה':

מאשרים את התוכנית וצופים בסוכן מיישם את כל הדרישות.

כשהסוכן יסיים את ההטמעה, מריצים את הפקודה go run main.go בתיקיית הפרויקט כדי להציג את גרסת המחשב. לא צריך לצאת מ-Gemini CLI כדי להריץ את הפקודה הזו. מקלידים ! (סימן קריאה) כדי להיכנס למצב מעטפת ולהריץ את הפקודה משם:

היתרון בהרצה ממצב מעטפת הוא שכל בעיה שעלולה להתרחש מתועדת באופן מיידי בהקשר של הסוכן. לדוגמה, במקרה הזה הנציג שכח להוריד כמה תלויות:

אפשר לצאת ממצב Shell בלחיצה על מקש Escape, ואז לבקש מהנציג לבדוק ולתקן את השגיאה:

התוצאה המוצלחת אמורה להיראות כך:

נסו לשחק במשחק ולשנות את הפרמטרים שלו עד שתהיו מרוצים מהחוויה (למשל, להגביר או להנמיך את מהירות האנימציה, לשנות את אופן התגובה לפקודות וכו').

5. התאמת המשחק להפעלה בדפדפן אינטרנט

המשחק Ebitengine שיצרתם הוא אפליקציה למחשב. כדי לאפשר לו לפעול באינטרנט, אפשר להמיר אותו ל-WebAssembly.

כדי להנחות את הסוכן, משתמשים בהנחיה הבאה:

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.

אחרי שהסוכן מסיים את המשימה, אפשר להנחות אותו להריץ את שרת גיימינג ברקע.

אפשר לנהל תהליכים שפועלים ברקע באמצעות שילוב המקשים Ctrl+B:

כדי לסגור את החלון הזה, מקישים שוב על Ctrl+B.

עכשיו פותחים את הכתובת http://localhost:8080 בדפדפן כדי לראות את המשחק פועל באינטרנט:

עכשיו, אחרי שהאפליקציה פועלת באינטרנט, הגיע הזמן לבצע ליטוש סופי לפני הפריסה שלה בענן.

6. יצירת מסך הכותרת והלידרבורד

המשחק פועל, אבל חסרות בו כמה תכונות חשובות שנדרשות לחוויית משחק ארקייד מלאה. קודם נוסיף מסך כותרת ואז נוסיף טבלת הישגים כדי שתוכלו להתחרות עם החברים שלכם!

כדי לפתור את שתי הבעיות, משתמשים בהנחיה הבאה:

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

דוגמה למסך הכותרת:

הוא מתחיל להיראות קצת יותר מקצועי! 🙂

7. פריסת המשחק ב-Cloud Run

הגיע הזמן לשתף את היצירה שלנו עם העולם! פורסים את המשחק ב-Google Cloud Run כדי שתוכלו לגשת אליו מכל מקום.

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.

המשחק זמין עכשיו בענן, ולכן כדאי לאפשר הפעלה שלו במכשירים ניידים. אפשר לעשות את זה באמצעות ההנחיה הבאה:

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.

מפעילים את המשחק שוב בדפדפן. נסו לגשת למשחק גם ממכשיר נייד באמצעות קוד ה-QR.

8. שימוש בסוכן הדפדפן כדי לבדוק את המשחק

ב-Gemini CLI, סוכן משנה הוא פרסונה מבודדת עם הקשר חדש, שמתאימה במיוחד למשימות ארוכות או למשימות שדורשות דיוק גבוה, שבהן לא רוצים שההקשר הנוכחי ישפיע על התוצאות.

קשה לבדוק משחקים באמצעות כלי בדיקה רגילים (למשל בדיקות יחידה ובדיקות שילוב), אבל אפשר להשתמש בסוכן הדפדפן כדי לבצע חלק מהבדיקות בשבילנו. הסוכן בדפדפן יכול להפעיל דפדפן Chrome משלו, והוא ינווט במסכי המשחק באמצעות פקודות DOM. יש לו גם יכולת לצלם צילומי מסך, שבהם נוכל להשתמש כדי לתעד את הבדיקה וגם להעביר אותם לסוכן כדי לבצע התאמות קלות בממשק המשתמש בהמשך.

הסוכן לדפדפן הוא כרגע ניסיוני, ולכן צריך להפעיל אותו קודם. נותנים את ההנחיה הזו ל-Gemini CLI כדי להפעיל את הסוכן ברמת הפרויקט.

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

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

כדי שהשינוי ייכנס לתוקף, צריך להפעיל מחדש את הסוכן. שומרים את השיחה הנוכחית באמצעות הפקודה /chat save:

יוצאים מ-Gemini CLI על ידי הקשה פעמיים על Ctrl+D, ומפעילים אותו מחדש. שחזור השיחה עם /chat resume cloud-crush.

עכשיו אמורה להיות לכם גישה לסוכן הדפדפן. אם רוצים להעביר משימה לסוכן הדפדפן, אפשר לתייג אותו באמצעות @browser_agent:

עכשיו משתמשים בסוכן הדפדפן כדי לבצע הערכה של המשחק שפרסנו:

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

אמור להופיע מסך האישור:

אחרי שתתנו את ההסכמה לסוכן ולכלים הנדרשים, אמור להיפתח חלון חדש בדפדפן Chrome. זה הדפדפן שהסוכן שולט בו. הרמז החזותי יהיה הגבול הכחול במסך וההודעה בתחתית 'Gemini CLI שולט בדפדפן הזה':

בסיום, תוצג הודעה כמו זו:

ריכזנו כאן כמה צילומי מסך שנוצרו על ידי סוכן הדפדפן:

title_screen.png:

game_board.png:

עכשיו כדאי להשתמש באחת התמונות שצולמו על ידי הסוכן כדי לבצע אופטימיזציה של ממשק המשתמש של המשחק. לדוגמה, אפשר לומר:

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. יצירת סוכן בהתאמה אישית לאבטחת המשחק

אחת הבעיות הנפוצות ביישומים עם קוד שנוצר על ידי AI היא איך לשמור על איכות גבוהה ועל שיטות מומלצות גם מבחינת קידוד וגם מבחינת אבטחה. אפשר לנסות לשפר את ההנחיות כדי שיהיו מדויקות מאוד בשני ההיבטים האלה, אבל ככל שמוסיפים יותר פרטים להנחיה, הסוכן מתמקד פחות, ולכן התוצאות לרוב לא אופטימליות. במקרים כאלה, הכי טוב להשתמש בסוכנים משניים, כי הם פועלים בהקשר נפרד מהסוכן הראשי ויכולים להתמקד במשימה שנותנים להם. ניצור סוכן בהתאמה אישית כדי לבצע ביקורת אבטחה על הקוד הזה ולוודא שלא נחשפים פרטי כניסה או סיכונים מיותרים בזמן פריסת המשחק הזה ב-Cloud Run.

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.

כדי שהשינוי ייכנס לתוקף, צריך להפעיל מחדש את ה-CLI. שומרים את סשן הצ'אט עם /chat save וממשיכים אותו עם /chat resume כמו שעשינו קודם.

כשמפעילים מחדש את ה-CLI, הוא מזהה אוטומטית את הסוכן החדש בהפעלה:

לוחצים על Acknowledge and Enable ומבקשים מהנציג לבצע בדיקת אבטחה בקוד המשחק באמצעות ההנחיה הבאה:

@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

אתם אמורים לראות משהו כזה:

אחרי שהכלי יסיים את הביקורת, הוא יציג המלצות. בדוגמה הזו, הכלי מצא כמה דברים חשובים שצריך לתקן:

אם מצאתם ממצאים, אתם יכולים לבקש מ-Gemini CLI לתקן אותם בשבילכם. 🙂

10. סיכום

מעולה! השתמשתם בהצלחה ב-Gemini CLI כדי ליצור, לפרוס, לבדוק ולבצע ביקורת במשחק ארקייד, והדגמתם תהליכי עבודה מתקדמים של סוכנים, החל מהמסגרת הראשונית ועד לפריסה.

הסרת המשאבים

אם אתם לא מתכננים לחזור ל-Codelab הזה בהמשך, מומלץ למחוק את המשאבים שנוצרו במהלך ה-Codelab.

מוחקים את שירות Cloud Run:

מבקשים מ-Gemini CLI למחוק אותו:

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

מחיקת ספריית הפרויקט:

cd .. && rm -rf codelab-match3

לחלופין, אפשר למחוק את כל פרויקט הענן ב-Google Cloud אם הוא נוצר רק בשביל ה-Codelab הזה.

השלבים הבאים

אתם יכולים להמשיך את מסע הלמידה שלכם ולעיין בשיעורי Codelab נוספים בפלטפורמה הזו, או לשפר את Cloud Crush בעצמכם.

כמה הצעות לשיפור המשחק:

מוסיפים Gem מיוחד בשם Gemini (באמצעות gemini.png) שמופיע כשמצמידים 4 או יותר Gems. התאמה של 3 אבני חן או יותר של Gemini מעניקה לשחקן תוספת זמן כבונוס!
להוסיף מוזיקה. אתם יכולים ליצור מוזיקה באמצעות Lyria 3 בדף הבית של Gemini.
הוספת אפקטים קוליים
הוספת מצבי משחק אחרים

שיהיה בהצלחה!