Classifiche

Questa guida mostra come utilizzare le API delle classifiche dell'SDK Play Games Services C++ per creare classifiche visive, registrare il punteggio di un giocatore e confrontarlo con il punteggio del giocatore delle sessioni di gioco precedenti. Le API sono disponibili in LeaderboardsClient.

Prima di iniziare

Se non l'hai ancora fatto, potrebbe esserti utile rivedere i concetti di gioco delle classifiche.

Prima di iniziare a scrivere codice utilizzando le API delle classifiche:

Ottieni il client delle classifiche

Per iniziare a utilizzare l'API delle classifiche, il tuo gioco deve prima ottenere un oggetto LeaderboardsClient. Per farlo, chiama il metodo PgsLeaderboardsClient_create() e passa l'attività.

Aggiorna il punteggio del giocatore

Quando il punteggio del giocatore cambia (ad esempio, quando completa il gioco), il tuo gioco può aggiornare il suo punteggio nella classifica chiamando PgsLeaderboardsClient_submitScoreImmediate. Devi passare l'ID classifica, il valore del punteggio grezzo, un tag del punteggio facoltativo e una funzione di callback.

// Callback function to handle the result of submitting the score
void OnScoreSubmitted(PgsStatusCode status_code,
                      PgsScoreSubmissionData* score_submission_data,
                      void* user_data) {
  if (status_code == PGS_STATUS_SUCCESS) {
    // Score submitted successfully
    // You can inspect score_submission_data for details
    // Remember to release the data when done:
    PgsScoreSubmissionData_Release(score_submission_data);
  } else {
    // Handle error
  }
}

// Function to submit the score
void SubmitScore(PgsLeaderboardsClient* client, const char* leaderboard_id, int64_t score) {
  const char* score_tag = NULL; // Optional tag

  PgsLeaderboardsClient_submitScoreImmediate(
      client,
      leaderboard_id,
      score,
      score_tag,
      OnScoreSubmitted,
      NULL // user_data - optional context pointer
  );
}

// Example usage:
// Assuming 'my_leaderboard_id' is defined elsewhere, e.g., fetched from resources
// SubmitScore(leaderboards_client, my_leaderboard_id, 1337);

Una buona pratica è gestire gli ID classifica come costanti o risorse all'interno del codice C++.

Visualizza una classifica

Per visualizzare l'interfaccia utente della classifica predefinita per una classifica specifica, chiama PgsLeaderboardsClient_showLeaderboardUI. Questa funzione richiede l'handle del client, l'attività, l'ID classifica, l'intervallo di tempo e la raccolta, nonché un callback.

// Callback function to handle the result of showing the UI
void OnShowLeaderboardUI(PgsStatusCode status_code, bool success, void* user_data) {
  if (status_code == PGS_STATUS_SUCCESS && success) {
    // UI was shown successfully
  } else {
    // Handle error or failure to show UI
  }
}

// Function to show a specific leaderboard UI
void ShowLeaderboard(PgsLeaderboardsClient* client, jobject activity, const char* leaderboard_id) {
  PgsLeaderboardsClient_showLeaderboardUI(
      client,
      activity,
      leaderboard_id,
      PGS_LEADERBOARD_TIME_SPAN_ALL_TIME, // Or PGS_LEADERBOARD_TIME_SPAN_DAILY, PGS_LEADERBOARD_TIME_SPAN_WEEKLY
      PGS_LEADERBOARD_COLLECTION_PUBLIC,  // Or PGS_LEADERBOARD_COLLECTION_FRIENDS
      OnShowLeaderboardUI,
      NULL // user_data - optional context pointer
  );
}

// Example usage:
// ShowLeaderboard(leaderboards_client, android_activity, my_leaderboard_id);

Questa funzione mostra la UI. L'oggetto activity fornisce il contesto per la visualizzazione della UI.