الإنجازات

يوضّح هذا المستند كيفية استخدام إنجازات "خدمات ألعاب Google Play" في ألعاب C++. يفترض هذا المستند أنّك قد أعددت مشروعك كما هو موضّح في إعداد "خدمات ألعاب Google Play". يمكنك العثور على واجهة برمجة التطبيقات الخاصة بالإنجازات في PgsAchievementsClient.

قبل البدء

إذا لم يسبق لك إجراء ذلك، قد يكون من المفيد مراجعة مفاهيم الإنجازات في الألعاب.

قبل البدء في كتابة الرموز البرمجية باستخدام Achievements API، يجب:

الحصول على عميل إنجازات

لبدء استخدام واجهة برمجة التطبيقات الخاصة بالإنجازات، يجب أن تحصل لعبتك أولاً على عنصر 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
    );
}

تعرض الصورة التالية مثالاً على واجهة المستخدم التلقائية للإنجازات:

مثال على واجهة المستخدم التلقائية للإنجازات
مثال على واجهة المستخدم التلقائية للإنجازات