הישגים

במאמר הזה מוסבר איך להשתמש בהישגים של Google Play Games Services במשחקי C++‎. במסמך הזה מניחים שהגדרתם את הפרויקט כמו שמתואר במאמר הגדרה של Google Play Games Services. אפשר למצוא את ממשק ה-API של ההישגים ב-PgsAchievementsClient.

לפני שמתחילים

אם עדיין לא עשיתם זאת, אנחנו ממליצים לכם להכיר את המושגים שקשורים להישגים במשחקים.

לפני שמתחילים לכתוב קוד שמשתמשים בו בממשק ה-API של ההישגים:

• מתקינים ומגדירים את האפליקציה לפי ההוראות לשימוש ב-Play Games Services שמופיעות במדריך להגדרת Play Games Services.

• מגדירים את ההישגים שרוצים שהמשחק יציג או יאפשר להשיג, לפי ההוראות שבמדריך Google Play Console.

• מעיינים בהמלצות שמופיעות ברשימת המשימות לאיכות.

קריאה לשיטה של ההישגים

כדי להתחיל להשתמש בממשק ה-API של ההישגים, המשחק שלכם צריך קודם לקבל אובייקט PgsAchievementsClient. כדי לעשות את זה, קוראים לשיטה PgsAchievementsClient_create ומעבירים את הפעילות.

איך להעניק הישגים

כדי להעניק הישגים, צריך לבצע קריאה ל-method‏ 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 Games Services מעניקה את ההישג באופן אוטומטי כשהשחקנים מגיעים למספר השלבים הנדרש.

מומלץ להגדיר את מזהי ההישגים בקובץ 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
    );
}

בתמונה הבאה מוצגת דוגמה לממשק המשתמש של ההישגים שמוגדר כברירת מחדל:

דוגמה לממשק המשתמש של ההישגים שמוגדר כברירת מחדל.