Zapisane gry na Androida

Z tego przewodnika dowiesz się, jak zaimplementować zapisane gry za pomocą Interfejs API zrzutów ekranu dostępny w usługach gier Google Play. Interfejsy API można znaleźć w com.google.android.gms.games.snapshot oraz com.google.android.gms.games przesyłek.

Zanim zaczniesz

Więcej informacji o tej funkcji znajdziesz w Przegląd zapisanych gier

Pobieranie klienta zrzutów

Aby zacząć korzystać z interfejsu API zrzutów, Twoja gra musi najpierw uzyskać SnapshotsClient. Aby to zrobić, wywołaj metodę Games.getSnapshotsClient() i przekazywanie funkcji działania.

Określanie zakresu dysku

Interfejs API zrzutów korzysta z interfejsu Google Drive API. . Aby uzyskać dostęp do interfejsu Drive API, aplikacja musi określić Drive.SCOPE_APPFOLDER podczas tworzenia klienta logowania Google.

Oto przykład, jak to zrobić w onResume() metody logowania:

@Override
protected void onResume() {
  super.onResume();
  signInSilently();
}

private void signInSilently() {
  GoogleSignInOptions signInOption =
      new GoogleSignInOptions.Builder(GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN)
          // Add the APPFOLDER scope for Snapshot support.
          .requestScopes(Drive.SCOPE_APPFOLDER)
          .build();

  GoogleSignInClient signInClient = GoogleSignIn.getClient(this, signInOption);
  signInClient.silentSignIn().addOnCompleteListener(this,
      new OnCompleteListenerG<oogleSignInAccount(>) {
        @Override
        public void onComplete(@NonNull TaskG<oogleSignInAccount >task) {
          if (task.isSuccessful()) {
            onConnected(task.getResult());
          } else {
            // Player will need to sign-in explicitly using via UI
          }
        }
      });
}

Wyświetl zapisane gry

Interfejs API zrzutów można zintegrować wszędzie tam, gdzie Twoja gra zapewnia graczom zapisać lub przywrócić postępy. Twoja gra może wyświetlać takie w wyznaczonych punktach zapisu/przywracania lub umożliwiać graczom w dowolnym momencie.

Gdy gracze wybiorą w grze opcję zapisywania/przywracania gry, gra może opcjonalnie wyświetlić ekran z prośbą o podanie informacji dla nowego zapisanego grę lub wybierz zapisaną grę, którą chcesz przywrócić.

Aby uprościć programowanie, interfejs Snaps API umożliwia domyślne wybieranie zapisanych gier interfejsu (UI), z którego można korzystać od razu. Interfejs wyboru zapisanych gier pozwala graczom: tworzyć nowe zapisane gry, wyświetlać szczegółowe informacje o istniejących grach i wczytywać wcześniej zapisane gry.

Aby uruchomić domyślny interfejs Zapisane gry:

  1. Zadzwoń pod numer SnapshotsClient.getSelectSnapshotIntent(), aby otrzymać Intent za uruchomienie domyślnego interfejsu wyboru zapisanych gier.
  2. Zadzwoń do nas startActivityForResult() i przekaże go Intent Jeśli wywołanie się powiedzie, gra wyświetli interfejs wyboru zapisanej gry, wybierając określone opcje.

Ten przykład pokazuje, jak uruchomić domyślny interfejs wyboru zapisanych gier:

private static final int RC_SAVED_GAMES = 9009;

private void showSavedGamesUI() {
  SnapshotsClient snapshotsClient =
      PlayGames.getSnapshotsClient(this);
  int maxNumberOfSavedGamesToShow = 5;

  Task<Intent> intentTask = snapshotsClient.getSelectSnapshotIntent(
      "See My Saves", true, true, maxNumberOfSavedGamesToShow);

  intentTask.addOnSuccessListener(new OnSuccessListener<Intent>() {
    @Override
    public void onSuccess(Intent intent) {
      startActivityForResult(intent, RC_SAVED_GAMES);
    }
  });
}

Jeśli gracz zdecyduje się utworzyć nową zapisaną grę lub wczytać istniejącą, interfejs wysyła żądanie do usług gier Play. Jeśli żądanie zostanie zrealizowane, Usługi gier Play zwracają informacje potrzebne do utworzenia lub przywrócenia zapisanej gry. onActivityResult() oddzwanianie. Gra może zastąpić to wywołanie zwrotne, by sprawdzić, czy podczas żądania nie wystąpiły jakieś błędy.

Fragment kodu poniżej zawiera przykładową implementację onActivityResult():

private String mCurrentSaveName = "snapshotTemp";

/**
 * This callback will be triggered after you call startActivityForResult from the
 * showSavedGamesUI method.
 */
@Override
protected void onActivityResult(int requestCode, int resultCode,
                                Intent intent) {
  if (intent != null) {
    if (intent.hasExtra(SnapshotsClient.EXTRA_SNAPSHOT_METADATA)) {
      // Load a snapshot.
      SnapshotMetadata snapshotMetadata =
          intent.getParcelableExtra(SnapshotsClient.EXTRA_SNAPSHOT_METADATA);
      mCurrentSaveName = snapshotMetadata.getUniqueName();

      // Load the game data from the Snapshot
      // ...
    } else if (intent.hasExtra(SnapshotsClient.EXTRA_SNAPSHOT_NEW)) {
      // Create a new snapshot named with a unique string
      String unique = new BigInteger(281, new Random()).toString(13);
      mCurrentSaveName = "snapshotTemp-" + unique;

      // Create the new snapshot
      // ...
    }
  }
}

Zapisywanie zapisanych gier

Aby zapisać treści w zapisanej grze:

  1. Asynchronicznie otwórz zrzut za pomocą SnapshotsClient.open()

  2. Pobierz Snapshot obiekt z wyniku zadania przez wywołanie SnapshotsClient.DataOrConflict.getData()

  3. Pobierz SnapshotContents instancja z SnapshotsClient.SnapshotConflict

  4. Zadzwoń do nas SnapshotContents.writeBytes() do przechowywania danych odtwarzacza w formacie bajtowym.

  5. Po zapisaniu wszystkich zmian wywołaj polecenie SnapshotsClient.commitAndClose() wysyłanie zmian na serwery Google. W wywołaniu metody gra może opcjonalnie podać dodatkowe informacje, które wskażą Usługom gier Play, jak pokazać graczom tę zapisaną grę. Informacje te są przedstawione w SnapshotMetaDataChange który jest tworzony przez grę za pomocą SnapshotMetadataChange.Builder

Ten fragment kodu pokazuje, w jaki sposób Twoja gra może wprowadzać zmiany w zapisanej grze:

private Task<SnapshotMetadata> writeSnapshot(Snapshot snapshot,
                                             byte[] data, Bitmap coverImage, String desc) {

  // Set the data payload for the snapshot
  snapshot.getSnapshotContents().writeBytes(data);

  // Create the change operation
  SnapshotMetadataChange metadataChange = new SnapshotMetadataChange.Builder()
      .setCoverImage(coverImage)
      .setDescription(desc)
      .build();

  SnapshotsClient snapshotsClient =
      PlayGames.getSnapshotsClient(this);

  // Commit the operation
  return snapshotsClient.commitAndClose(snapshot, metadataChange);
}

Jeśli urządzenie odtwarzacza nie jest połączone z siecią, gdy aplikacja wywołuje SnapshotsClient.commitAndClose() Usługi gier Play przechowują zapisane dane gier lokalnie na urządzeniu. Na urządzeniu ponowne połączenie, Usługi gier Play synchronizują zmiany w grach zapisane lokalnie w pamięci podręcznej Serwery Google.

Wczytaj zapisane gry

Aby pobrać zapisane gry dla aktualnie zalogowanego gracza:

  1. Asynchronicznie otwórz zrzut w SnapshotsClient.open()

  2. Pobierz Snapshot obiektu z wyniku zadania przez wywołanie SnapshotsClient.DataOrConflict.getData() Gra może też pobrać określone za pomocą interfejsu wyboru zapisanych gier, tak jak to opisano w Wyświetlanie zapisanych gier

  3. Pobierz SnapshotContents instancja z SnapshotsClient.SnapshotConflict

  4. Zadzwoń do nas SnapshotContents.readFully() odczytuje zawartość zrzutu.

Ten fragment kodu pokazuje, jak możesz wczytać konkretną zapisaną grę:

Task<byte[]> loadSnapshot() {
  // Display a progress dialog
  // ...

  // Get the SnapshotsClient from the signed in account.
  SnapshotsClient snapshotsClient =
      PlayGames.getSnapshotsClient(this);

  // In the case of a conflict, the most recently modified version of this snapshot will be used.
  int conflictResolutionPolicy = SnapshotsClient.RESOLUTION_POLICY_MOST_RECENTLY_MODIFIED;

  // Open the saved game using its name.
  return snapshotsClient.open(mCurrentSaveName, true, conflictResolutionPolicy)
      .addOnFailureListener(new OnFailureListener() {
        @Override
        public void onFailure(@NonNull Exception e) {
          Log.e(TAG, "Error while opening Snapshot.", e);
        }
      }).continueWith(new Continuation<SnapshotsClient.DataOrConflict<Snapshot>, byte[]>() {
        @Override
        public byte[] then(@NonNull Task<SnapshotsClient.DataOrConflict<Snapshot>> task) throws Exception {
          Snapshot snapshot = task.getResult().getData();

          // Opening the snapshot was a success and any conflicts have been resolved.
          try {
            // Extract the raw data from the snapshot.
            return snapshot.getSnapshotContents().readFully();
          } catch (IOException e) {
            Log.e(TAG, "Error while reading Snapshot.", e);
          }

          return null;
        }
      }).addOnCompleteListener(new OnCompleteListener<byte[]>() {
        @Override
        public void onComplete(@NonNull Task<byte[]> task) {
          // Dismiss progress dialog and reflect the changes in the UI when complete.
          // ...
        }
      });
}

Radzenie sobie z zapisanymi konfliktami gier

Podczas korzystania z interfejsu zrzutów ekranu w grze może się zdarzyć, urządzeń do wykonywania i odczytywania i zapisów w tej samej zapisanej grze. W przypadku, gdy urządzenie tymczasowo utraci połączenie z siecią, a następnie ponownie się połączy, powodują konflikty danych, gdy zapisana gra jest przechowywana na lokalnym urządzeniu gracza nie jest zsynchronizowany ze zdalną wersją zapisaną na serwerach Google.

Interfejs API zrzutów oferuje mechanizm rozwiązywania konfliktów, który przedstawia zestawy zapisanych gier będących w konflikcie w czasie odczytu i pozwala na wdrożenie rozwiązania; która najlepiej pasuje do Twojej gry.

Gdy Usługi gier Play wykryją konflikt danych, SnapshotsClient.DataOrConflict.isConflict() zwraca wartość true. W tym przypadku funkcja SnapshotsClient.SnapshotConflict klasa udostępnia 2 wersje zapisanej gry:

  • Wersja serwera: najnowsza wersja znana usług gier Play muszą być dokładne dla urządzenia odtwarzacza.

  • Wersja lokalna: zmodyfikowana wersja wykryta na jednym z urządzeń gracza. który zawiera sprzeczne treści lub metadane. Może się różnić od którą wersję próbujesz zapisać.

Gra musi zdecydować, jak rozwiązać konflikt, wybierając jedną z przesłane wersje lub scalanie danych dwóch zapisanych wersji gry.

Aby wykrywać i rozwiązywać zapisane konflikty gier:

  1. Zadzwoń do nas SnapshotsClient.open() Wynik zadania zawiera klasę SnapshotsClient.DataOrConflict.

  2. Wywołaj funkcję SnapshotsClient.DataOrConflict.isConflict(). Jeśli wynik jest prawdziwy, masz konflikt do rozwiązania.

  3. Zadzwoń do nas SnapshotsClient.DataOrConflict.getConflict() aby pobrać SnaphotsClient.snapshotConflict instancji.

  4. Zadzwoń do nas SnapshotsClient.SnapshotConflict.getConflictId() aby pobrać identyfikator, który jednoznacznie identyfikuje wykryty konflikt. Twoje gra potrzebuje tej wartości, aby później wysłać żądanie rozwiązania konfliktu.

  5. Zadzwoń do nas SnapshotsClient.SnapshotConflict.getConflictingSnapshot() , aby uzyskać wersję lokalną.

  6. Zadzwoń do nas SnapshotsClient.SnapshotConflict.getSnapshot() aby pobrać wersję serwera.

  7. Aby rozwiązać konflikt zapisanych gier, wybierz wersję, w której chcesz ją zapisać serwer jako ostateczną wersję i przekazać ją SnapshotsClient.resolveConflict() .

Ten fragment kodu i przykład pokazuje, jak Twoja gra może poradzić sobie z zapisanym konfliktem gry przez wybierając ostatnio zmodyfikowaną zapisaną grę jako ostateczną wersję do zapisania:

private static final int MAX_SNAPSHOT_RESOLVE_RETRIES = 10;

TaskS<napshot >processSnapshotOpenResult(SnapshotsClient.DataOrConflictS<napshot >result,
                                         final int retryCount) {

  if (!result.isConflict()) {
    // There was no conflict, so return the result of the source.
    TaskCompletionSourceS<napshot >source = new TaskCompletionSource(<>);
    source.setResult(result.getData());
    return source.getTask();
  }

  // There was a conflict.  Try resolving it by selecting the newest of the conflicting snapshots.
  // This is the same as using RESOLUTION_POLICY_MOST_RECENTLY_MODIFIED as a conflict resolution
  // policy, but we are implementing it as an example of a manual resolution.
  // One option is to present a UI to the user to choose which snapshot to resolve.
  SnapshotsClient.SnapshotConflict conflict = result.getConflict();

  Snapshot snapshot = conflict.getSnapshot();
  Snapshot conflictSnapshot = conflict.getConflictingSnapshot();

  // Resolve between conflicts by selecting the newest of the conflicting snapshots.
  Snapshot resolvedSnapshot = snapshot;

  if (snapshot.getMetadata().getLastModifiedTimestamp() 
<      conflictSnapshot.getMetadata().getLastModifiedTimestamp()) {
    resolvedSnapshot = conflictSnapshot;
  }

  return PlayGames.getSnapshotsClient(theActivity)
      .resolveConflict(conflict.getConflictId(), resolvedSnapshot)
      .continueWithTask(
          new Continuation
<              SnapshotsClient.DataOrConflictS<napshot,>
              TaskS<napshot(>>) {
            @Override
            public TaskS<napshot >then(
                @NonNull TaskS<napshotsClient.DataOrConflictS<napshot >>task)
                throws Exception {
              // Resolving the conflict may cause another conflict,
              // so recurse and try another resolution.
              if (retryCount  <MAX_SNAPSHOT_RESOLVE_RETRIES) {
                return processSnapshotOpenResult(task.getResult(), retryCount + 1);
              } else {
                throw new Exception(C"ould not resolve snapshot conflicts)";
              }
            }
          });
}

Zmień zapisane gry

Jeśli chcesz scalić dane z kilku zapisanych gier lub zmodyfikować istniejącą Snapshot, aby zapisać na serwerze jako ostateczną wersję, postępuj zgodnie z tymi instrukcjami kroki:

  1. Zadzwoń do nas SnapshotsClient.open()

  2. Zadzwoń do nas SnapshotsClient.SnapshotConflict.getResolutionSnapshotsContent(), aby uzyskać nowy SnapshotContents.

  3. Scal dane z: SnapshotsClient.SnapshotConflict.getConflictingSnapshot() oraz SnapshotsClient.SnapshotConflict.getSnapshot() w sekcji SnapshotContents obiekt z poprzedniego kroku.

  4. Opcjonalnie możesz utworzyć SnapshotMetadataChange w przypadku jakichkolwiek zmian w polach metadanych.

  5. Zadzwoń do nas SnapshotsClient.resolveConflict() W wywołaniu metody przekaż SnapshotsClient.SnapshotConflict.getConflictId() jako pierwszy argument, a SnapshotMetadataChange oraz SnapshotContents obiekty zmodyfikowane wcześniej jako drugi i odpowiednio trzeciego argumentu.

  6. Jeśli SnapshotsClient.resolveConflict() zostanie wywołany, interfejs API zapisze obiekt Snapshot na serwerze, próbuje otworzyć obiekt zrzutu na urządzeniu lokalnym.