توضّح هذه المستندات كيفية استخدام إنجازات "خدمات ألعاب Google Play" في ألعاب C++. يفترض هذا المستند أنّك أعددت مشروعك كما هو موضّح في مقالة إعداد
"خدمات ألعاب Google Play". يمكنك العثور على واجهة برمجة التطبيقات للإنجازات في الـ
PgsAchievementsClient.
قبل البدء
إذا لم يسبق لك إجراء ذلك، قد يكون من المفيد مراجعة مفاهيم الألعاب المتعلقة بـ الإنجازات.
قبل البدء في كتابة الرموز البرمجية باستخدام واجهة برمجة التطبيقات للإنجازات، يجب:
اتّباع تعليمات تثبيت تطبيقك وإعداده لاستخدام "خدمات ألعاب Play" في دليل إعداد "خدمات ألعاب Google Play"
التعرّف على الاقتراحات الموضّحة في قائمة التحقّق من الجودة.
الحصول على عميل للإنجازات
لبدء استخدام واجهة برمجة التطبيقات للإنجازات، يجب أن تحصل لعبتك أولاً على
PgsAchievementsClient
كائن. يمكنك إجراء ذلك من خلال استدعاء طريقة
PgsAchievementsClient_create
وتمرير النشاط.
فتح الإنجازات
لفتح إنجاز، استدعِ طريقة
PgsAchievementsClient_unlock
ومرِّر PgsAchievementsClient ورقم تعريف الإنجاز.
يوضّح مقتطف الرمز التالي كيف يمكن لتطبيقك فتح الإنجازات:
// Example Usage void TriggerUnlock(PgsGamesClient* gamesClient) { // You must obtain the achievements client from the main games client PgsAchievementsClient* achievementsClient = PgsGamesClient_getAchievementsClient(gamesClient); // Replace with your actual Achievement ID from the Play Console const char* MY_ACHIEVEMENT_ID = "CgkI...sQw"; UnlockAchievement(achievementsClient, MY_ACHIEVEMENT_ID); }
إذا كان الإنجاز من النوع التدريجي (أي يتطلب عدة خطوات لفتحه)، استدعِ PgsAchievementsClient_incrementبدلاً من ذلك.
يوضّح مقتطف الرمز التالي كيف يمكن لتطبيقك زيادة إنجاز اللاعب:
void IncrementMyAchievement(PgsAchievementsClient* client, const char* achievementId, uint32_t steps) { if (client == nullptr) { return; } // Call the API // Parameters typically include: // 1. Client handle // 2. Achievement ID (string) // 3. Number of steps to increment by (For example, 1) // 4. Callback function // 5. User context (passed to callback) PgsAchievementsClient_increment( client, achievementId, steps, OnIncrementCallback, (void*)achievementId // Pass ID as context so the callback knows which one finished ); } // Example Usage in Game Loop void OnEnemyDefeated(PgsGamesClient* gamesClient) { // Get the achievements client handle PgsAchievementsClient* achievementsClient = PgsGamesClient_getAchievementsClient(gamesClient); // ID from Google Play Console const char* ACH_ENEMY_KILLER = "CgkI...xyz"; // Increment by 1 step IncrementMyAchievement(achievementsClient, ACH_ENEMY_KILLER, 1); }
ليس عليك كتابة رمز إضافي لفتح الإنجاز، إذ تفتح "خدمات ألعاب Google Play" الإنجاز تلقائيًا عند الوصول إلى العدد المطلوب من الخطوات.
من أفضل الممارسات تحديد أرقام تعريف الإنجازات في ملف strings.xml، حتى تتمكّن لعبتك من الإشارة إلى الإنجازات حسب رقم تعريف المورد. عند إجراء مكالمات لتعديل الإنجازات وتحميلها، احرص أيضًا على اتّباع أفضل الممارسات هذه لتجنُّب تجاوز حصة واجهة برمجة التطبيقات.
عرض الإنجازات
لعرض إنجازات اللاعب، استدعِ
PgsAchievementsClient_showAchievementsUI.
يوضّح مقتطف الرمز التالي كيف يمكن لتطبيقك عرض واجهة مستخدم الإنجازات التلقائية.
void OnShowAchievementsUICallback(void* context, PgsError error) { if (error == PgsError_Success) { // The UI was displayed and closed successfully by the user. // You might resume your game loop here if it was paused. } else { // Handle error (For example,, user not signed in, UI failed to load). } } // Function to trigger the Achievements UI void ShowMyAchievements(PgsAchievementsClient* achievementsClient) { if (achievementsClient == nullptr) { // Log error: Client not initialized return; } // Call the API // Note: The specific arguments often include the client, a callback, and user_data. // Some versions might require the Android Activity or a Request Code as well. PgsAchievementsClient_showAchievementsUI( achievementsClient, OnShowAchievementsUICallback, // Callback function nullptr // Optional user data (context) passed to callback ); }
تعرض الصورة التالية مثالاً على واجهة مستخدم الإنجازات التلقائية: