Questa pagina è stata tradotta dall'API Cloud Translation.

Inizia a utilizzare GameActivity Parte di Android Game Development Kit.

Questa guida descrive come configurare e integrare GameActivity e gestire gli eventi nel tuo gioco per Android.

GameActivity ti aiuta a portare il tuo gioco C o C++ su Android semplificando il processo di utilizzo delle API critiche. In precedenza, NativeActivity era la classe consigliata per i giochi. GameActivity la sostituisce come classe consigliata per i giochi ed è compatibile con le versioni precedenti fino al livello API 19.

Per un esempio che integra GameActivity, consulta il repository games-samples.

Prima di iniziare

Consulta le versioni di GameActivity per ottenere una distribuzione.

Configurare la build

Su Android, un Activity funge da punto di ingresso per il tuo gioco e fornisce anche il Window in cui disegnare. Molti giochi estendono questo Activity con la propria classe Java o Kotlin per superare le limitazioni di NativeActivity durante l'utilizzo del codice JNI per collegarsi al codice di gioco C o C++.

GameActivity offre le seguenti funzionalità:

Eredita da AppCompatActivity, consentendoti di utilizzare i componenti dell'architettura Android Jetpack.
Esegue il rendering in un SurfaceView che ti consente di interagire con qualsiasi altro elemento UI di Android.
Gestisce gli eventi di attività Java. Ciò consente di integrare qualsiasi elemento UI Android (ad esempio un EditText, un WebView o un Ad) nel tuo gioco tramite un'interfaccia C.
Offre un'API C simile alle librerie NativeActivity e android_native_app_glue.

GameActivity viene distribuito come archivio Android (AAR). Questo AAR contiene la classe Java che utilizzi nel tuo AndroidManifest.xml, nonché il codice sorgente C e C++ che collega il lato Java di GameActivity all'implementazione C/C++ dell'app. Se utilizzi GameActivity 1.2.2 o versioni successive, viene fornita anche la libreria statica C/C++. Ove applicabile, ti consigliamo di utilizzare la libreria statica anziché il codice sorgente.

Includi questi file sorgente o la libreria statica nel processo di build tramite Prefab, che espone librerie native e codice sorgente al tuo progetto CMake o alla build NDK.

Segui le istruzioni riportate nella pagina Jetpack Android Games per aggiungere la dipendenza della libreria GameActivity al file build.gradle del tuo gioco.
Attiva Prefab procedendo nel seguente modo con Android Plugin Version (AGP) 4.1+:
- Aggiungi quanto segue al blocco android del file build.gradle del modulo:
```
buildFeatures {
    prefab true
}
```
- Scegli una versione predefinita e impostala sul file gradle.properties:
```
android.prefabVersion=2.0.0
```
Se utilizzi versioni precedenti di AGP, segui la documentazione di Prefab per le istruzioni di configurazione corrispondenti.
Importa la libreria statica C/C++ o il codice sorgente C/++ nel tuo progetto come segue.
Libreria statica
Nel file CMakeLists.txt del progetto, importa la libreria statica game-activity nel modulo game-activity_static prefab:
```
find_package(game-activity REQUIRED CONFIG)
target_link_libraries(${PROJECT_NAME} PUBLIC log android
game-activity::game-activity_static)
```
Codice sorgente
Nel file CMakeLists.txt del progetto, importa il pacchetto game-activity e aggiungilo al target. Il pacchetto game-activity richiede libandroid.so, quindi se non è presente, devi importarlo.
```
find_package(game-activity REQUIRED CONFIG)
...
target_link_libraries(... android game-activity::game-activity)
```
Includi anche i seguenti file in CmakeLists.txt del progetto: GameActivity.cpp, GameTextInput.cpp e android_native_app_glue.c.

Come Android avvia l'attività

Il sistema Android esegue il codice nell'istanza dell'attività richiamando i metodi di callback che corrispondono a fasi specifiche del ciclo di vita dell'attività. Affinché Android avvii l'attività e il gioco, devi dichiarare l'attività con gli attributi appropriati nel file manifest di Android. Per ulteriori informazioni, vedi Introduzione alle attività.

Manifest Android

Ogni progetto di app deve avere un file AndroidManifest.xml nella radice del set di origini del progetto. Il file manifest descrive le informazioni essenziali sulla tua app per gli strumenti di compilazione Android, il sistema operativo Android e Google Play. tra cui:

Nome del pacchetto e ID app per identificare in modo univoco il tuo gioco su Google Play.
Componenti dell'app, ad esempio attività, servizi, ricevitori di trasmissione e fornitori di contenuti.
Autorizzazioni per accedere a parti protette del sistema o ad altre app.
Compatibilità del dispositivo per specificare i requisiti hardware e software del tuo gioco.
Nome della libreria nativa per GameActivity e NativeActivity(il valore predefinito è libmain.so).

Implementare GameActivity nel gioco

Crea o identifica la classe Java dell'attività principale (quella specificata nell'elemento activity all'interno del file AndroidManifest.xml). Modifica questa classe per estendere GameActivity dal pacchetto com.google.androidgamesdk:
```
import com.google.androidgamesdk.GameActivity;

public class YourGameActivity extends GameActivity { ... }
```

Assicurati che la libreria nativa venga caricata all'inizio utilizzando un blocco statico:

public class EndlessTunnelActivity extends GameActivity {
  static {
    // Load the native library.
    // The name "android-game" depends on your CMake configuration, must be
    // consistent here and inside AndroidManifect.xml
    System.loadLibrary("android-game");
  }
  ...
}

Aggiungi la tua libreria nativa a AndroidManifest.xml se il nome della libreria non è quello predefinito (libmain.so):
```
<meta-data android:name="android.app.lib_name"
 android:value="android-game" />
```

Implementare android_main

La libreria android_native_app_glue è una libreria di codice sorgente che il tuo gioco utilizza per gestire gli eventi del ciclo di vita di GameActivity in un thread separato per evitare blocchi nel thread principale. Quando utilizzi la libreria, registri il callback per gestire gli eventi del ciclo di vita, come gli eventi di input tocco. L'archivio GameActivity include la propria versione della libreria android_native_app_glue, pertanto non puoi utilizzare la versione inclusa nelle release NDK. Se i tuoi giochi utilizzano la libreria android_native_app_glue inclusa nell'NDK, passa alla versione GameActivity.

Dopo aver aggiunto il codice sorgente della libreria android_native_app_glue al tuo progetto, questo interagisce con GameActivity. Implementa una funzione denominata android_main, chiamata dalla libreria e utilizzata come punto di ingresso per il gioco. Viene passata una struttura chiamata android_app. Questi valori possono variare a seconda del gioco e del motore. Ecco un esempio:
```
#include <game-activity/native_app_glue/android_native_app_glue.h>

extern "C" {
    void android_main(struct android_app* state);
};

void android_main(struct android_app* app) {
    NativeEngine *engine = new NativeEngine(app);
    engine->GameLoop();
    delete engine;
}
```

Elabora android_app nel ciclo di gioco principale, ad esempio il polling e la gestione degli eventi del ciclo di vita dell'app definiti in NativeAppGlueAppCmd. Ad esempio, il seguente snippet registra la funzione _hand_cmd_proxy come gestore NativeAppGlueAppCmd, quindi esegue il polling degli eventi del ciclo di vita dell'app e li invia al gestore registrato(in android_app::onAppCmd) per l'elaborazione:

void NativeEngine::GameLoop() {
  mApp->userData = this;
  mApp->onAppCmd = _handle_cmd_proxy;  // register your command handler.
  mApp->textInputState = 0;

  while (1) {
    int events;
    struct android_poll_source* source;

    // If not animating, block until we get an event;
    // If animating, don't block.
    while ((ALooper_pollOnce(IsAnimating() ? 0 : -1, NULL, &events,
      (void **) &source)) >= 0) {
        if (source != NULL) {
            // process events, native_app_glue internally sends the outstanding
            // application lifecycle events to mApp->onAppCmd.
            source->process(source->app, source);
        }
        if (mApp->destroyRequested) {
            return;
        }
    }
    if (IsAnimating()) {
        DoFrame();
    }
  }
}

Per ulteriori informazioni, studia l'implementazione dell'esempio NDK Endless Tunnel. La differenza principale riguarda la gestione degli eventi, come mostrato nella sezione successiva.

Gestire gli eventi

Per consentire agli eventi di input di raggiungere la tua app, crea e registra i filtri degli eventi con android_app_set_motion_event_filter e android_app_set_key_event_filter. Per impostazione predefinita, la libreria native_app_glue consente solo eventi di movimento dall'input SOURCE_TOUCHSCREEN. Per i dettagli, assicurati di consultare il documento di riferimento e il codice di implementazione android_native_app_glue.

Per gestire gli eventi di input, ottieni un riferimento a android_input_buffer con android_app_swap_input_buffers() nel ciclo di gioco. Questi contengono eventi di movimento ed eventi chiave che si sono verificati dall'ultima volta che è stato interrogato. Il numero di eventi contenuti è memorizzato rispettivamente in motionEventsCount e keyEventsCount.

Esegui l'iterazione e gestisci ogni evento nel ciclo di gioco. In questo esempio, il seguente codice itera motionEvents e li gestisce tramite handle_event:

android_input_buffer* inputBuffer = android_app_swap_input_buffers(app);
if (inputBuffer && inputBuffer->motionEventsCount) {
    for (uint64_t i = 0; i < inputBuffer->motionEventsCount; ++i) {
        GameActivityMotionEvent* motionEvent = &inputBuffer->motionEvents[i];

        if (motionEvent->pointerCount > 0) {
            const int action = motionEvent->action;
            const int actionMasked = action & AMOTION_EVENT_ACTION_MASK;
            // Initialize pointerIndex to the max size, we only cook an
            // event at the end of the function if pointerIndex is set to a valid index range
            uint32_t pointerIndex = GAMEACTIVITY_MAX_NUM_POINTERS_IN_MOTION_EVENT;
            struct CookedEvent ev;
            memset(&ev, 0, sizeof(ev));
            ev.motionIsOnScreen = motionEvent->source == AINPUT_SOURCE_TOUCHSCREEN;
            if (ev.motionIsOnScreen) {
                // use screen size as the motion range
                ev.motionMinX = 0.0f;
                ev.motionMaxX = SceneManager::GetInstance()->GetScreenWidth();
                ev.motionMinY = 0.0f;
                ev.motionMaxY = SceneManager::GetInstance()->GetScreenHeight();
            }

            switch (actionMasked) {
                case AMOTION_EVENT_ACTION_DOWN:
                    pointerIndex = 0;
                    ev.type = COOKED_EVENT_TYPE_POINTER_DOWN;
                    break;
                case AMOTION_EVENT_ACTION_POINTER_DOWN:
                    pointerIndex = ((action & AMOTION_EVENT_ACTION_POINTER_INDEX_MASK)
                                   >> AMOTION_EVENT_ACTION_POINTER_INDEX_SHIFT);
                    ev.type = COOKED_EVENT_TYPE_POINTER_DOWN;
                    break;
                case AMOTION_EVENT_ACTION_UP:
                    pointerIndex = 0;
                    ev.type = COOKED_EVENT_TYPE_POINTER_UP;
                    break;
                case AMOTION_EVENT_ACTION_POINTER_UP:
                    pointerIndex = ((action & AMOTION_EVENT_ACTION_POINTER_INDEX_MASK)
                                   >> AMOTION_EVENT_ACTION_POINTER_INDEX_SHIFT);
                    ev.type = COOKED_EVENT_TYPE_POINTER_UP;
                    break;
                case AMOTION_EVENT_ACTION_MOVE: {
                    // Move includes all active pointers, so loop and process them here,
                    // we do not set pointerIndex since we are cooking the events in
                    // this loop rather than at the bottom of the function
                    ev.type = COOKED_EVENT_TYPE_POINTER_MOVE;
                    for (uint32_t i = 0; i < motionEvent->pointerCount; ++i) {
                        _cookEventForPointerIndex(motionEvent, callback, ev, i);
                    }
                    break;
                }
                default:
                    break;
            }

            // Only cook an event if we set the pointerIndex to a valid range, note that
            // move events cook above in the switch statement.
            if (pointerIndex != GAMEACTIVITY_MAX_NUM_POINTERS_IN_MOTION_EVENT) {
                _cookEventForPointerIndex(motionEvent, callback,
                                          ev, pointerIndex);
            }
        }
    }
    android_app_clear_motion_events(inputBuffer);
}

Per l'implementazione di _cookEventForPointerIndex() e di altre funzioni correlate, consulta l'esempio di GitHub.

Al termine, ricordati di svuotare la coda degli eventi che hai appena gestito:
```
android_app_clear_motion_events(mApp);
```

Risorse aggiuntive

Per scoprire di più su GameActivity, consulta quanto segue:

Per segnalare bug o richiedere nuove funzionalità per GameActivity, utilizza lo strumento di monitoraggio dei problemi di GameActivity.