دستاوردها

این سند نحوه استفاده از دستاوردهای خدمات بازی‌های گوگل پلی در بازی‌های ++C را شرح می‌دهد. این سند فرض می‌کند که شما پروژه خود را مطابق آنچه در «راه‌اندازی خدمات بازی‌های گوگل پلی» توضیح داده شده است، راه‌اندازی کرده‌اید. می‌توانید API دستاوردها را در PgsAchievementsClient پیدا کنید.

قبل از اینکه شروع کنی

اگر هنوز این کار را نکرده‌اید، شاید مرور مفاهیم بازی دستاوردها برایتان مفید باشد.

قبل از شروع کدنویسی با استفاده از API دستاوردها:

یک کلاینت دستاورد دریافت کنید

برای شروع استفاده از API دستاوردها، بازی شما ابتدا باید یک شیء PgsAchievementsClient دریافت کند. می‌توانید این کار را با فراخوانی متد PgsAchievementsClient_create و ارسال activity انجام دهید.

دستاوردها را باز کنید

برای باز کردن قفل یک دستاورد، متد 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);
}

برای باز کردن قفل اچیومنت نیازی به نوشتن کد اضافی ندارید؛ سرویس‌های بازی‌های گوگل پلی به طور خودکار اچیومنت را پس از رسیدن به تعداد مراحل مورد نیاز، باز می‌کنند.

یک روش خوب این است که شناسه‌های دستاورد را در فایل strings.xml تعریف کنید، تا بازی شما بتواند دستاوردها را بر اساس شناسه منبع ارجاع دهد. هنگام فراخوانی برای به‌روزرسانی و بارگذاری دستاوردها، حتماً از این بهترین شیوه‌ها نیز پیروی کنید تا از سهمیه API خود فراتر نروید.

نمایش دستاوردها

برای نمایش دستاوردهای یک بازیکن، 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
    );
}

تصویر زیر نمونه‌ای از رابط کاربری پیش‌فرض دستاوردها را نشان می‌دهد:

نمونه‌ای از رابط کاربری پیش‌فرض دستاوردها
نمونه‌ای از رابط کاربری پیش‌فرض دستاوردها.