API Game Mode

L'API Game Mode consente di ottimizzare il gioco per ottenere le migliori prestazioni o la maggiore durata della batteria quando l'utente seleziona la modalità di gioco corrispondente.

In alternativa, puoi inviare richieste di interventi per la modalità di gioco per migliorare le prestazioni dei giochi che non vengono più aggiornati dagli sviluppatori.

L'API e gli interventi per la modalità di gioco sono disponibili su:

• Seleziona dispositivi Android 12
• Dispositivi con Android 13 o versioni successive

Ogni gioco può implementare il comportamento dell'API Game Mode, proporre agli OEM le impostazioni degli interventi per la Modalità di gioco o disattivare gli interventi per la modalità di gioco.

Avviso: gli OEM possono scegliere di implementare interventi per la modalità di gioco senza feedback dello sviluppatore.

Configura

Per utilizzare l'API Game Mode nel tuo gioco:

1. Scarica e installa l'SDK Android 13.

2. Nel file AndroidManifest.xml, dichiara la tua app come gioco impostando l'attributo appCategory nell'elemento <application>:

android:appCategory="game"

1. Esegui query sulla modalità di gioco corrente aggiungendo questo alla tua attività principale:

Java

// Only call this for Android 12 and higher devices
if ( Build.VERSION.SDK_INT >= Build.VERSION_CODES.S ) {
  // Get GameManager from SystemService
  GameManager gameManager = Context.getSystemService(GameManager.class);

  // Returns the selected GameMode
  int gameMode = gameManager.getGameMode();
}

Kotlin

// Only call this for Android 12 and higher devices
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
  // Get GameManager from SystemService
  val gameManager: GameManager? = context.getSystemService(Context.GAME_SERVICE) as GameManager?

  // Returns the selected GameMode
  val gameMode = gameManager?.gameMode
}

Modalità di gioco supportata	Descrizione
NON SUPPORTATI	Il gioco non dichiara il supporto per l'API Game Mode e non supporta interventi della Modalità di gioco.
STANDARD	L'utente non ha selezionato una modalità di gioco o l'utente ha selezionato la modalità standard.
ESECUZIONE	Offre le frequenze fotogrammi con la latenza più bassa in cambio di una riduzione della durata della batteria e della fedeltà.
BATTERIA	Offre la più lunga durata della batteria in cambio di una minore fedeltà o frequenza fotogrammi.

Importante: la modalità Risparmio energetico è specifica per il gioco e non influisce sul comportamento del Risparmio energetico di Android a livello di sistema.

1. Aggiungi codice per eseguire query sullo stato della modalità di gioco nella funzione onResume:

   

Importante: l'app deve sempre eseguire una query sul metodo getGameMode() quando riprendi un processo in pausa. Per i dettagli, vedi il diagramma qui sopra.

Best practice

Se il tuo gioco supporta già più target di fedeltà e frequenza fotogrammi, devi identificare le impostazioni appropriate per le modalità Prestazioni e Risparmio energetico:

• Per raggiungere costantemente le frequenze fotogrammi massime del dispositivo, considera delle leggere riduzioni della fedeltà per ottenere frequenze fotogrammi più elevate.

• Per aumentare la durata della batteria, valuta la possibilità di scegliere una frequenza di aggiornamento del display più bassa (ad es. 30 Hz o 60 Hz) e utilizza il pacing frame per scegliere come target la frequenza ridotta.

Per i giochi ad alta fedeltà come gli sparatutto in prima persona, le arene di battaglia online multiplayer (MOBA) e i giochi di ruolo (RPG), dovresti concentrarti sul raggiungimento di frequenze fotogrammi elevate e coerenti per massimizzare il coinvolgimento degli utenti.

Sia per i giochi ad alta fedeltà che per quelli casual, dovresti supportare la modalità di risparmio energetico per prolungare il tempo di riproduzione riducendo le frequenze fotogrammi di picco.

Dichiara il supporto delle modalità di gioco

Per dichiarare il supporto delle modalità di gioco e sostituire eventuali interventi della modalità di gioco da parte degli OEM, devi prima aggiungere la configurazione della modalità di gioco all'elemento <application> nel file AndroidManifest.xml:

<application>
    <meta-data android:name="android.game_mode_config"
               android:resource="@xml/game_mode_config" />
  ...
</application>

Quindi crea un file game_mode_config.xml nella directory res/xml/ del progetto con il seguente contenuto:

<?xml version="1.0" encoding="UTF-8"?>
<game-mode-config
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:supportsBatteryGameMode="true"
    android:supportsPerformanceGameMode="true"
/>

Importante: se il gioco dichiara il supporto per una modalità di gioco, deve implementare la propria ottimizzazione. Di conseguenza, la piattaforma reimposta tutti gli interventi per la modalità di gioco applicati in precedenza dagli OEM.

Cambia modalità di gioco

Per passare da una modalità di gioco all'altra, puoi usare il Pannello di gioco (disponibile sui dispositivi Pixel) o applicazioni simili fornite dagli OEM. In alternativa, puoi usare il comando shell della modalità di gioco durante lo sviluppo.

Se stai utilizzando il Pannello di gioco e l'icona di ottimizzazione non viene visualizzata al momento del lancio del gioco, potresti dover caricare l'app su Google Play Console e installarla tramite il Play Store. Per informazioni sui test delle app nel Play Store, consulta la sezione Condividere internamente app bundle e APK.

Figura 1. Pannello di gioco mostrato sovrapposto al gioco in esecuzione su un dispositivo Pixel.

Nella figura 1, la modalità di gioco del gioco in esecuzione può essere modificata dal widget di ottimizzazione. Come mostrato nel widget, il gioco è attualmente in esecuzione in modalità PERFORMANCE.

Durante lo sviluppo, se utilizzi un dispositivo senza Pannello di gioco e il produttore non offre alcun modo per impostare la modalità di gioco per ogni app, puoi modificare lo stato della modalità di gioco tramite adb:

adb shell cmd game mode [standard|performance|battery] <PACKAGE_NAME>

Applicazione di esempio

L'esempio di API Modalità di gioco evidenzia come ottimizzare i limiti di FPS e risoluzione del rendering per risparmiare circa il 25% di potenza nelle app.

Avanti

Leggi Interventi per la modalità di gioco per migliorare le prestazioni di un gioco quando non è possibile fornire aggiornamenti.