Aggiungere partite salvate al tuo gioco

Questa guida mostra come salvare e caricare i dati sui progressi di un giocatore utilizzando il servizio Partite salvate in un'applicazione C++. Puoi utilizzare questo servizio per caricare e salvare automaticamente i progressi del giocatore in qualsiasi momento durante il gameplay. Questo servizio può anche consentire ai giocatori di attivare un'interfaccia utente per aggiornare o ripristinare un salvataggio esistente o crearne uno nuovo.

Prima di iniziare

Se non l'hai ancora fatto, ti consigliamo di consultare i concetti di gioco di Salvati.

Prima di iniziare a scrivere codice utilizzando l'API Saved Games:

Formati dei dati e compatibilità multipiattaforma

I dati di Saved Games salvati sui server di Google devono essere in formato std::vector<uint8_t>. Il servizio Saved Games si occupa di codificare i tuoi dati per la compatibilità multipiattaforma. Le applicazioni Android possono leggere questi stessi dati come array di byte senza problemi di compatibilità multipiattaforma.

Evita di utilizzare formati specifici della piattaforma quando scegli un formato per i dati di salvataggio dei giochi. Ti consigliamo vivamente di utilizzare un formato di dati, come XML o JSON, che abbia un'ampia gamma di librerie supportate su più piattaforme.

Attivare il servizio Partite salvate

Prima di poter utilizzare il servizio Saved Games, devi attivarne l'accesso. Per farlo, chiama EnableSnapshots() quando crei il servizio con gpg::GameServices::Builder. In questo modo verranno attivati gli ambiti di autorizzazione aggiuntivi richiesti da Giochi salvati al successivo evento di autenticazione.

Mostrare le partite salvate

Nel tuo gioco puoi fornire un'opzione che i giocatori possono attivare per salvare o recuperare le partite salvate. Quando i giocatori selezionano questa opzione, il gioco dovrebbe visualizzare una schermata che mostra gli slot di salvataggio esistenti e consentire ai giocatori di salvare in uno di questi slot, caricare da uno di questi slot o creare un nuovo salvataggio. Per farlo, utilizza il seguente metodo:

  SnapshotManager::ShowSelectUIOperation(...)

L'interfaccia utente di selezione dei salvataggi consente ai giocatori di creare un nuovo salvataggio, visualizzare i dettagli dei salvataggi esistenti e caricare i salvataggi precedenti.

  SnapshotManager::SnapshotSelectUIResponse response;
  if (IsSuccess(response.status)) {
  if (response.data.Valid()) {
    LogI("Description: %s", response.data.Description().c_str());
    LogI("FileName %s", response.data.FileName().c_str());
    //Opening the snapshot data
    …
  } else {
    LogI("Creating new snapshot");
    …
  }
} else {
  LogI("ShowSelectUIOperation returns an error %d", response.status);
}

L'esempio seguente illustra come visualizzare l'interfaccia utente predefinita delle partite salvate e gestire la selezione dell'interfaccia utente del giocatore:

  service_->Snapshots().ShowSelectUIOperation(
  ALLOW_CREATE_SNAPSHOT,
  ALLOW_DELETE_SNAPSHOT,
  MAX_SNAPSHOTS,
  SNAPSHOT_UI_TITLE,
  [this](gpg::SnapshotManager::SnapshotSelectUIResponse const & response) {
  …
      }

Se nell'esempio precedente ALLOW_CREATE_SNAPSHOT è true e MAX_SNAPSHOTS è maggiore del numero effettivo di snapshot attualmente creati dall'utente, l'interfaccia utente di Snapshot predefinita offre ai giocatori un pulsante per creare un nuovo salvataggio anziché selezionarne uno esistente. Se visualizzato, il pulsante si trova nella parte inferiore dell'interfaccia utente. Quando un utente fa clic su questo pulsante, la risposta SnapshotSelectUIResponse è valida, ma non contiene dati.

Aprire e leggere le partite salvate

Per accedere a una partita salvata e leggere o modificarne i contenuti, apri prima l'oggetto SnapshotMetadata che la rappresenta. Quindi, chiama il metodo SnapshotManager::Read*().

L'esempio seguente mostra come aprire una partita salvata:

  LogI("Opening file");
  service_->Snapshots()
  .Open(current_snapshot_.FileName(),
               gpg::SnapshotConflictPolicy::BASE_WINS,
        [this](gpg::SnapshotManager::OpenResponse const & response) {
           LogI("Reading file");
           gpg::SnapshotManager::ReadResponse responseRead =
           service_->Snapshots().ReadBlocking(response.data);
          …
        }

Rileva e risolvi i conflitti di dati

Quando apri un oggetto SnapshotMetadata, il servizio Giochi salvati rileva se esiste un gioco salvato in conflitto. I conflitti di dati possono verificarsi quando la partita salvata sul dispositivo locale di un giocatore non è sincronizzata con la versione remota memorizzata sui server di Google.

Il criterio di conflitto specificato quando apri una partita salvata indica al servizio Partite salvate come risolvere automaticamente un conflitto di dati. Il criterio può essere uno dei seguenti:

Norme relative ai conflitti Descrizione
SnapshotConflictPolicy::MANUAL Indica che il servizio Saved Games non deve eseguire alcuna azione di risoluzione. Il gioco eseguirà invece un'unione personalizzata.
SnapshotConflictPolicy::LONGEST_PLAYTIME Indica che il servizio Saved Games deve scegliere la partita salvata con il valore di tempo di gioco più elevato.
SnapshotConflictPolicy::BASE_WINS Indica che il servizio Partite salvate deve scegliere la partita salvata di base.
SnapshotConflictPolicy::REMOTE_WINS Indica che il servizio Giochi salvati deve scegliere la partita salvata remota. La versione remota è una versione del gioco salvata che viene rilevata su uno dei dispositivi del giocatore e ha un timestamp più recente rispetto alla versione di base.

Se hai specificato una norma di conflitto diversa da GPGSnapshotConflictPolicyManual, il servizio Partite salvate unirà la partita salvata e restituirà la versione aggiornata tramite il valore SnapshotManager::OpenResponse risultante. Il gioco può aprire la partita salvata, scrivere al suo interno e chiamare il metodo SnapshotManager::Commit(...) per eseguire il commit della partita salvata sui server di Google.

Eseguire un'unione personalizzata

Se hai specificato SnapshotConflictPolicy::MANUAL come criterio di conflitto, il gioco deve risolvere eventuali conflitti di dati rilevati prima di eseguire ulteriori operazioni di lettura o scrittura sul salvataggio.

In questo caso, quando viene rilevato un conflitto di dati, il servizio restituisce i seguenti parametri tramite SnapshotManager::OpenResponse:

  • Un conflict_id per identificare in modo univoco questo conflitto (utilizzerai questo valore quando esegui il commit della versione finale della partita salvata);
  • La versione base in conflitto della partita salvata.
  • La versione remota in conflitto della partita salvata.

Il gioco deve decidere quali dati salvare, quindi chiamare il metodo SnapshotManager::ResolveConflictBlocking() per eseguire il commit/la risoluzione della versione finale sui server di Google.

    //Resolve conflict
    gpg::SnapshotManager::OpenResponse resolveResponse =
        manager.ResolveConflictBlocking(openResponse.conflict_base, metadata_change,
                                  openResponse.conflict_id);

Scrivere le partite salvate

Per scrivere una partita salvata, apri prima l'oggetto SnapshotMetadata che la rappresenta, risolvi eventuali conflitti di dati rilevati, quindi chiama il metodo SnapshotManager::Commit() per applicare le modifiche alla partita salvata.

L'esempio seguente mostra come creare una modifica e eseguire il commit di un salvataggio.

  1. Innanzitutto, apri lo snapshot che vuoi modificare e assicurati che tutti i conflitti siano stati risolti scegliendo la base.

    service_->Snapshots().Open(
      file_name,
      gpg::SnapshotConflictPolicy::BASE_WINS,
      [this](gpg::SnapshotManager::OpenResponse const &response) {
        if (IsSuccess(response.status)) {
          // metadata : gpg::SnapshotMetadata
          metadata = response.data;
        } else {
          // Handle snapshot open error here
        }
      });

  2. A questo punto, crea una modifica della partita salvata che includa i dati delle immagini utilizzati per l'immagine di copertina:

    gpg::SnapshotMetadataChange::Builder builder;
gpg::SnapshotMetadataChange metadata_change =
    builder.SetDescription("CollectAllTheStar savedata")
             .SetCoverImageFromPngData(pngData).Create();

  3. Infine, esegui il commit delle modifiche apportate alla partita salvata.

    gpg::SnapshotManager::CommitResponse commitResponse =
    service_->Snapshots().CommitBlocking(metadata, metadata_change, SetupSnapshotData());

    Il parametro data contiene tutti i dati di salvataggio dei giochi che stai archiviando. La modifica contiene anche metadati aggiuntivi delle partite salvate, come il tempo di gioco e una descrizione della partita salvata.

Se l'operazione di commit è stata completata correttamente, i giocatori possono vedere la partita salvata nell'interfaccia utente di selezione Giochi salvati.