Questa pagina è stata tradotta dall'API Cloud Translation.

Aggiunta di giochi salvati al tuo gioco

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

Prima di iniziare

Se non l'hai già fatto, potresti trovare utile rileggere i concetti dei giochi salvati.

Prima di iniziare a programmare utilizzando l'API Save Games:

Formati di dati e compatibilità multipiattaforma

I dati dei giochi salvati sui server di Google devono essere in formato std::vector<uint8_t>. Il servizio Giochi salvati si occupa della codifica dei tuoi dati per garantire la compatibilità multipiattaforma. Le applicazioni Android possono leggere negli stessi dati un array di byte senza problemi di compatibilità multipiattaforma.

Evita di utilizzare formati specifici della piattaforma quando scegli un formato dei dati per i dati dei giochi salvati. Ti consigliamo vivamente di utilizzare un formato dati, come XML o JSON, che supporti la libreria in modo efficace su più piattaforme.

Attivazione del servizio Giochi salvati

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

Visualizzazione dei giochi salvati

Nel tuo gioco puoi fornire un'opzione che i giocatori possono attivare per salvare o ripristinare i giochi salvati. Quando i giocatori selezionano questa opzione, il gioco dovrebbe visualizzare una schermata che mostra gli slot esistenti salvati e consentire ai giocatori di salvare o caricare contenuti da uno di questi slot o di creare un nuovo gioco salvato. Utilizza il seguente metodo:

  SnapshotManager::ShowSelectUIOperation(...)

L'UI di selezione dei giochi salvati consente ai giocatori di creare un nuovo gioco salvato, visualizzare i dettagli dei giochi salvati esistenti e caricare giochi salvati 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 di Giochi salvati e gestire la selezione dell'interfaccia utente del player:

  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'UI di snapshot predefinita fornisce ai giocatori un pulsante per creare un nuovo gioco di salvataggio, anziché selezionarne uno esistente. (se visualizzato, il pulsante si trova nella parte inferiore dell'interfaccia utente). Quando un player fa clic su questo pulsante, la risposta SnapshotSelectUIResponse è valida, ma non contiene dati.

Apertura e lettura dei giochi salvati

Per accedere a un gioco salvato e leggerne o modificarne i contenuti, devi prima aprire l'oggetto SnapshotMetadata che rappresenta il gioco salvato. Successivamente, chiama il metodo SnapshotManager::Read*().

L'esempio seguente mostra come aprire un gioco salvato:

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

Rilevamento e risoluzione dei conflitti di dati

Quando apri un oggetto SnapshotMetadata, il servizio Giochi salvati rileva se esiste un gioco salvato in conflitto. Potrebbero verificarsi conflitti di dati quando il gioco salvato archiviato sul dispositivo locale del player non è sincronizzato con la versione remota archiviata nei server di Google.

Il criterio di conflitto specificato quando apri un gioco salvato indica al servizio Giochi salvati come risolvere automaticamente un conflitto di dati. Il criterio può essere uno dei seguenti:

Politica sui conflitti	Descrizione
`SnapshotConflictPolicy::MANUAL`	Indica che il servizio Giochi salvati non deve eseguire alcuna azione di risoluzione. Invece, il gioco eseguirà un'unione personalizzata.
`SnapshotConflictPolicy::LONGEST_PLAYTIME`	Indica che il servizio Giochi salvati deve scegliere il gioco salvato con il valore di tempo di gioco più alto.
`SnapshotConflictPolicy::BASE_WINS`	Indica che il servizio Giochi salvati deve scegliere il gioco base salvato.
`SnapshotConflictPolicy::REMOTE_WINS`	Indica che il servizio Giochi salvati deve scegliere il gioco salvato da remoto. La versione remota è una versione del gioco salvata che viene rilevata su uno dei dispositivi del player e ha un timestamp più recente rispetto alla versione di base.

Se hai specificato un criterio di conflitto diverso da GPGSnapshotConflictPolicyManual, il servizio Giochi salvati unirà il gioco salvato e restituirà la versione aggiornata tramite il valore SnapshotManager::OpenResponse risultante. Il gioco può aprire il gioco salvato, scriverci, quindi chiamare il metodo SnapshotManager::Commit(...) per eseguire il commit del gioco salvato sui server di Google.

Eseguire un'unione personalizzata

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

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 del gioco salvato);
La versione base in conflitto del gioco salvato; e
La versione remota del gioco salvato in conflitto.

È necessario che il gioco decida quali dati salvare, quindi chiama 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);

Scrittura di giochi salvati

Per scrivere un gioco salvato, innanzitutto apri l'oggetto SnapshotMetadata che rappresenta il gioco salvato, risolvi i conflitti di dati rilevati, quindi chiama il metodo SnapshotManager::Commit() per eseguire il commit delle modifiche al gioco salvate.

L'esempio seguente mostra come creare una modifica ed eseguire il commit di un gioco salvato.

Per prima cosa, apri lo snapshot che vogliamo modificare e assicurati che tutti i conflitti siano 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
        }
      });

A questo punto, crea una modifica del gioco salvata che includa i dati dell'immagine di copertina:

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

Infine, esegui il commit delle modifiche al gioco salvate.
```
gpg::SnapshotManager::CommitResponse commitResponse =
    service_->Snapshots().CommitBlocking(metadata, metadata_change, SetupSnapshotData());
```
Il parametro dati contiene tutti i dati del gioco salvati che stai memorizzando. La modifica contiene anche altri metadati del gioco salvati, come il tempo di gioco e una descrizione del gioco salvato.

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