ความสำเร็จ

เอกสารนี้อธิบายวิธีใช้รางวัลพิเศษของบริการเกมของ Google Play ในเกม C++ เอกสารนี้ถือว่าคุณได้ตั้งค่าโปรเจ็กต์ตามที่อธิบายไว้ในตั้งค่าบริการเกมของ Google Play คุณจะพบ API รางวัลพิเศษได้ใน PgsAchievementsClient

ก่อนเริ่มต้น

หากยังไม่ได้ดำเนินการ คุณอาจดูแนวคิดเกี่ยวกับเกมความสำเร็จเพื่อเป็นข้อมูลเพิ่มเติม

ก่อนเริ่มเขียนโค้ดโดยใช้ API ความสำเร็จ ให้ทำดังนี้

ทำตามวิธีการติดตั้งและตั้งค่าแอปเพื่อใช้ บริการเกมของ Play ในคำแนะนำตั้งค่าบริการเกมของ Google Play
กำหนดรางวัลพิเศษที่ต้องการให้เกมปลดล็อกหรือแสดงโดยทำตามวิธีการในคู่มือ Google Play Console
ทำความคุ้นเคยกับคำแนะนำที่อธิบายไว้ในรายการตรวจสอบคุณภาพ

ดาวน์โหลดไคลเอ็นต์รางวัลพิเศษ

หากต้องการเริ่มใช้ 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 เพื่อให้เกมอ้างอิงรางวัลพิเศษตามรหัสทรัพยากรได้ เมื่อทำการเรียกเพื่ออัปเดตและโหลดความสำเร็จ โปรดทำตามแนวทางปฏิบัติแนะนำเหล่านี้ด้วยเพื่อหลีกเลี่ยงไม่ให้เกินโควต้า 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
    );
}

รูปภาพต่อไปนี้แสดงตัวอย่าง UI ของความสำเร็จเริ่มต้น

ตัวอย่าง UI ความสำเร็จเริ่มต้น — ตัวอย่าง UI ของความสำเร็จเริ่มต้น