برنامج تضمين Godot التجريبي لميزة "هيّا نلعب على YouTube"

باستخدام هذا الغلاف، يمكنك الوصول إلى حزمة تطوير البرامج (SDK) لميزة "هيّا نلعب" في YouTube في Godot باستخدام .gd المقدَّمة. يحتوي الغلاف على محوِّل حزمة تطوير البرامج (SDK) بتنسيق ‎ .js وملف .gd لمساعدة في تسريع عملية التطوير. يتوفّر أيضًا نموذج مشروع يشرح كيفية استخدام هذه النصوص البرمجية في مشروعك.

يمكن تنزيل حِزم Godot بتنسيق zip من مستودع نماذج "هيّا نلعب".

الاستخدام

1. استخرِج GoogleYTGameWrapper-godot.zip في مجلد المشروع الذي تريد أن تُحفظ فيه هذه النصوص البرمجية. يحتوي ملف ZIP هذا على ملفين:
   • ‫YTGameWrapper.gd: تُستخدَم كجسر إلى حزمة تطوير البرامج (SDK) لتطبيقات YT Playables المستندة إلى JavaScript، ما يتيح إمكانية طلب حزمة SDK من داخل اللعبة.
   • ‫YTGameSDK.js: تُستخدَم للربط بحزمة SDK الخاصة بتطبيق "هيّا نلعب" على YouTube. في هذا المثال، سنضع هذا الملف في جذر مشروعك. يمكنك تغيير ذلك، ولكن يتطلّب ذلك تعديل موقع تضمين العنوان.
   • يتوفّر أيضًا إصدار كامل من نموذج المشروع للتنزيل من مستودع نماذج ميزة "هيّا نلعب". لهذا الإصدار، استخدِم ملف zip المُسمى GoogleYTGameWrapper-godot-with-sample.zip.
2. أضِف عنصر Autoload Global جديدًا لملف YTGameWrapper.gd النصي الذي تم فك ضغطه. يمكن ضبط هذا الخيار ضمن Project -> Project Settings... -> Globals. اختَر ملف YTGameWrapper.gd في مربّع إدخال Path وأضِف YTGameWrapper في مربّع إدخال Node Name. أخيرًا، انقر على + Add.
   • سيؤدي ذلك إلى إتاحة النص البرمجي على مستوى العالم في الرمز البرمجي، ما يتيح لك استدعاء YTGameWrapper حسب الحاجة.
3. تأكَّد من ضبط منصة مشروع Godot على التصدير لنظام التشغيل Web. يمكن العثور على هذا الإعداد في علامة التبويب "تصدير"، ما عليك سوى النقر على Project ثم Export....
4. في لوحة "التصدير"، أضِف إعدادًا مُسبَقًا جديدًا من خلال النقر على Add... ثم على Web. بعد إنشاء هذا الرمز، أضِفه إلى مربّع إعدادات Head Include.

<script src="https://www.youtube.com/game_api/v1">// Load YT Game API code</script>
<script src="YTGameSDK.js"></script>

1. يمكنك تصدير مشروع الويب في لوحة Export من خلال النقر على Export Project... واختيار موقع الإنشاء.
2. بعد إنشاء مشروعك، انتقِل إلى مجلد الإنشاء وانسخ ملف YTGameSDK.js إلى هذا المجلد وتأكَّد من تضمينه عند إرسال الإصدار.
3. تأكَّد من اتّباع المتطلبات الفنية لمشروعك، واحرص على استخدام مجموعة اختبارات "التجارب القابلة للتشغيل".

أمثلة

يتضمّن هذا القسم بعض الأمثلة على كيفية استخدام حزمة .gd، وليس هو القائمة الكاملة لواجهات برمجة التطبيقات المتاحة. للاطّلاع على القائمة الكاملة لواجهات برمجة التطبيقات المتاحة، يُرجى الرجوع إلى حزمة تطوير البرامج (SDK) لميزة "الألعاب القابلة للتشغيل" في YouTube. يفترض ذلك أيضًا أنّه تم إعداد مشروعك على النحو الموضّح في قسم "الاستخدام".

sendScore

يوضّح هذا المثال عملية تنفيذ sendScore(int points) في .gd:

var current_game_score: int = 0

...

func add_score(scoreAdded: int):
    current_game_score += scoreAdded
    YTGameWrapper.send_score(current_game_score)

onPause

في ما يلي مثال على كيفية استماع اللعبة إلى أحداث Pause الواردة من YT Playables لإيقاف محرّكها مؤقتًا عند الحاجة:

func _ready() -> void:
    # hook up on game paused
    YTGameWrapper.game_paused.connect(self._on_game_paused)
    # hook up on game resumed and game save data received events
    YTGameWrapper.game_resumed.connect(self._on_game_resumed)

func _on_game_paused():
    # Pause your game logic, audio, etc.
    get_tree().paused = true
    
func _on_game_resumed():
    # Resume your game logic, audio, etc.
    get_tree().paused = false

saveData

في ما يلي مثال على كيفية استخدام saveData وإرساله إلى حزمة تطوير البرامج (SDK) لميزة "الألعاب القابلة للتشغيل" في YouTube:

var current_game_score: int = 0
var time_elapsed: float = 0.0

...

func save_game_data():
    YTGameWrapper.save_data('{"BestScore": "' + str(current_game_score) + '","BestTime": "' +str(time_elapsed)+ '"}')

loadData

في ما يلي مثال على كيفية استخدام loadData وإرساله إلى حزمة تطوير البرامج (SDK) لميزة "الألعاب القابلة للتشغيل" في YouTube:

func _ready() -> void:
    # hook up game load data received event
    YTGameWrapper.load_data_received.connect(self._on_load_data)
    # Request to load data when the game starts
    YTGameWrapper.load_data()

func _on_load_data(save_data_string: String):
    if not save_data_string.is_empty():
        # Add logic to parse the save_data_string and restore game state
        print("Loaded data: ", save_data_string)

requestInterstitialAd

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

func set_game_over(didWin: bool):
    YTGameWrapper.request_interstitial_ad()

    # logic for game over

كيفية تقسيم مواد العرض في مشروع Godot (التحميل البطيء)

من المشاكل الرئيسية التي أبرزها المطوّرون عند استخدام Godot هي الالتزام بمتطلبات حجم الملف الفردي ومتطلبات حجم الحزمة الإجمالية.

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

للمساعدة في التحميل الصحيح، يوفّر Godot ميزة تصدير الحِزم والتعديلات والتعديلات المخصّصة (رابط باللغة الإنجليزية). ننصحك بإنشاء ملفات .pck يتم تحميلها حسب الحاجة.

اطّلِع على مرجع YT Playables API الكامل.