إنشاء لعبة أركيد من النوع "ثلاثة متطابقة" باستخدام Gemini CLI

1. مقدمة

في هذا الدرس التطبيقي حول الترميز، ستنشئ لعبة الأركيد CloudCrush التي تتضمّن 3 مستويات، وذلك باستخدام Gemini 3 وGemini CLI، وهو وكيل الترميز المستنِد إلى سطر الأوامر. سيتم إنشاء اللعبة بلغة Go ونشرها على Google Cloud باستخدام Cloud Run.

الهدف الرئيسي من هذا الدرس التطبيقي حول الترميز هو تطوير المهارات اللازمة لتنظيم الوكيل من أجل إنشاء تطبيقات لك بدلاً من كتابة الرموز يدويًا. ستفوّض جميع مهام التطوير إلى Gemini CLI، حتى إذا لم يسبق لك استخدام هذه التكنولوجيات.

هذا الدرس التطبيقي حول الترميز مخصّص للمطوّرين المتوسطي الخبرة الذين يتطلّعون إلى تعلُّم مهام سير العمل البرمجية المستندة إلى الذكاء الاصطناعي الوكيل. يبلغ إجمالي المدة المقدَّرة لهذا الدرس التطبيقي 60 دقيقة. تستخدم الموارد التي تم إنشاؤها في هذا الدرس التطبيقي حول الترميز التسعير وفق الاستخدام.

الإجراءات التي ستنفذّها

إنشاء منطق لعبة مطابقة ثلاثة عناصر الأساسي باستخدام Go وإطار عمل Ebitengine
تعديل اللعبة لتشغيلها على متصفّح ويب باستخدام WebAssembly (WASM)
انشر اللعبة وواجهة برمجة التطبيقات الخاصة بأعلى نتيجة على 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 Console، في صفحة اختيار المشروع، اختَر مشروعًا على Google Cloud أو أنشِئ مشروعًا.
تأكَّد من تفعيل الفوترة لمشروعك على السحابة الإلكترونية. كيفية التحقّق مما إذا كانت الفوترة مفعَّلة في مشروع

بدء Cloud Shell

Cloud Shell هي بيئة سطر أوامر تعمل في Google Cloud ومحمّلة مسبقًا بالأدوات اللازمة.

انقر على تفعيل 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، واكتب "توجيه" في مربّع البحث. بعد ذلك، اضبط خيار "تفعيل توجيه النموذج" على "صحيح".

قد تحتاج إلى إعادة تشغيل واجهة سطر الأوامر لكي يسري مفعول التغيير (عن طريق الضغط على المفتاح "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:

بعد الإجابة عن جميع الأسئلة، يمكنك مراجعتها لآخر مرة قبل الضغط على مفتاح الإدخال لإرسالها.

بعد الانتهاء من الخطة، سيُطلب منك مراجعتها:

في أسفل مربّع المراجعة، يمكنك قبول الخطة كما هي أو إضافة ملاحظاتك.

استفِد من هذه الفرصة لإضافة شرط جديد لم يتم تضمينه في الطلب الأصلي:

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 في أنّه يتم رصد أي مشاكل قد تحدث على الفور في سياق الوكيل. على سبيل المثال، في هذه الحالة، نسي الوكيل تنزيل بعض التبعيات:

يمكنك الخروج من وضع الصدفة من خلال الضغط على مفتاح الخروج (Esc)، ثم الطلب من الوكيل فحص الخطأ وإصلاحه:

يجب أن تبدو النتيجة الناجحة على النحو التالي:

جرِّب لعب اللعبة وضبط مَعلمات اللعبة إلى أن تشعر بالرضا عن التجربة (مثل تسريع الرسوم المتحركة أو إبطائها، وتعديل طريقة استجابتها للأوامر، وما إلى ذلك).

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.

أعِد تشغيل اللعبة على المتصفّح. جرِّب الوصول إلى اللعبة من جهاز جوّال أيضًا باستخدام رمز الاستجابة السريعة.

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 في هذا المتصفّح":

عند الانتهاء، ستظهر رسالة على النحو التالي:

في ما يلي بعض لقطات الشاشة التي التقطها وكيل المتصفّح:

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- إنشاء وكيل مخصّص لتأمين اللعبة

أحد المخاوف الشائعة بشأن التطبيقات التي تستخدم الترميز المستند إلى المشاعر هو كيفية الحفاظ على الجودة العالية وأفضل الممارسات من منظورَي الترميز والأمان. يمكنك محاولة تحسين طلباتك لتكون دقيقة جدًا في كلا الجانبين، ولكن كلما أضفت المزيد إلى الطلب، قلّ تركيز الوكيل، ما يؤدي غالبًا إلى نتائج غير مثالية. في هذا النوع من السيناريوهات، يكون استخدام الوكلاء الفرعيين مثاليًا، لأنّهم يعملون في سياق منفصل عن الوكيل الرئيسي، ويمكنهم التركيز بشكل كبير على المهمة التي تسندها إليهم. لنبدأ بإنشاء وكيل مخصّص لإجراء تدقيق أمني على هذا الرمز والتأكّد من أنّنا لا نسرّب أي بيانات اعتماد أو نعرض أنفسنا لأي مخاطر غير ضرورية أثناء نشر هذه اللعبة على 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.

يجب إعادة تشغيل واجهة سطر الأوامر لكي يصبح التغيير ساريًا. احفظ جلسة الدردشة باستخدام /chat save واستأنِفها باستخدام /chat resume كما فعلنا سابقًا.

عند استئناف واجهة سطر الأوامر، سيتم تلقائيًا رصد الوكيل الجديد عند بدء التشغيل:

انقر على 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 بنجاح لإنشاء لعبة أركيد ونشرها واختبارها وتدقيقها، ما يوضّح مهام سير العمل المتقدّمة المستندة إلى الوكلاء من مرحلة الإنشاء الأوّلي إلى مرحلة النشر.

تنظيف

إذا كنت لا تخطّط للعودة إلى هذا الدرس التطبيقي حول الترميز لاحقًا، من الأفضل حذف الموارد التي تم إنشاؤها أثناء هذا الدرس.

احذف خدمة Cloud Run:

اطلب من Gemini CLI حذفها نيابةً عنك:

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

احذف دليل المشروع:

cd .. && rm -rf codelab-match3

بدلاً من ذلك، يمكنك حذف مشروع Google Cloud بأكمله إذا تم إنشاؤه لهذا الدرس البرمجي فقط.

الخطوات التالية

يمكنك مواصلة رحلة التعلّم من خلال استكشاف دروس تطبيقية حول الترميز أخرى في هذه المنصة، أو من خلال تحسين لعبة Cloud Crush بنفسك.

في ما يلي بعض الاقتراحات لتحسين اللعبة:

أضِف جوهرة خاصة باسم "Gemini" (باستخدام gemini.png) تظهر عند مطابقة 4 جواهر أو أكثر. تمنح مطابقة 3 جواهر Gemini أو أكثر اللاعب وقتًا إضافيًا.
أضِف موسيقى. يمكنك إنشاء موسيقى باستخدام Lyria 3 على الصفحة الرئيسية في Gemini.
إضافة مؤثرات صوتية
إضافة أوضاع لعب أخرى

نتمنّى لك التوفيق في الترميز.