Thành tích

Tài liệu này mô tả cách sử dụng thành tích của Dịch vụ trò chơi của Google Play trong các trò chơi C++. Tài liệu này giả định rằng bạn đã thiết lập dự án của mình như mô tả trong phần Thiết lập Dịch vụ Google Play Games. Bạn có thể tìm thấy API thành tích trong PgsAchievementsClient.

Trước khi bắt đầu

Nếu chưa từng có kinh nghiệm, bạn có thể xem lại các khái niệm về thành tích của trò chơi.

Trước khi bạn bắt đầu mã hóa bằng cách sử dụng API thành tích:

Tải ứng dụng thành tích

Để bắt đầu sử dụng API thành tích, trước tiên trò chơi của bạn phải có được một đối tượng PgsAchievementsClient. Bạn có thể thực hiện việc này bằng cách gọi phương thức PgsAchievementsClient_create và truyền vào hoạt động.

Mở khóa thành tích

Để mở khoá một thành tích, hãy gọi phương thức PgsAchievementsClient_unlock rồi truyền PgsAchievementsClient và mã thành tích vào.

Đoạn mã sau đây cho thấy cách ứng dụng của bạn có thể mở khóa các thành tích:

// 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);
}

Nếu thành tích thuộc loại tăng dần (nghĩa là bạn phải thực hiện một số bước để mở khoá thành tích), hãy gọi PgsAchievementsClient_increment.

Đoạn mã sau đây cho thấy cách ứng dụng của bạn có thể tăng thành tích của người chơi:

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);
}

Bạn không cần phải viết thêm mã để mở khoá thành tích; Dịch vụ trò chơi của Google Play sẽ tự động mở khoá thành tích sau khi đạt đến số bước cần thiết.

Bạn nên xác định mã thành tích trong tệp strings.xml để trò chơi của bạn có thể tham chiếu thành tích theo mã tài nguyên. Khi thực hiện lệnh gọi để cập nhật và tải các thành tích, bạn phải nhớ làm theo các phương pháp hay nhất này để tránh vượt quá định mức API.

Hiển thị thành tích

Để hiển thị thành tích của người chơi, hãy gọi PgsAchievementsClient_showAchievementsUI.

Đoạn mã sau đây cho thấy cách ứng dụng của bạn có thể hiển thị giao diện người dùng của bảng thành tích mặc định.

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
    );
}

Hình ảnh sau đây minh hoạ một ví dụ về giao diện người dùng của bảng thành tích mặc định:

Ví dụ về giao diện người dùng thành tích mặc định
Ví dụ về giao diện người dùng của bảng thành tích mặc định.