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 release di GameActivity per ottenere una distribuzione.
Configura la build
Su Android, un'Activity funge da punto di accesso per il tuo gioco e fornisce anche la Window in cui disegnare. Molti giochi estendono questa Activity con la propria classe Java o Kotlin per superare le limitazioni in NativeActivity utilizzando il 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.Viene visualizzato in un
SurfaceViewche ti consente di interfacciarti con qualsiasi altro elemento UI di Android.Gestisce gli eventi di attività Java. In questo modo, qualsiasi elemento UI Android (ad esempio un
EditText, unWebViewo unAd) può essere integrato nel tuo gioco utilizzando un'interfaccia C.Offre un'API C simile alla libreria
NativeActivityeandroid_native_app_glue.
GameActivity viene distribuito come Android ARchive (AAR). Questo file 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++. Se possibile, ti consigliamo di utilizzare la libreria statica anziché il codice sorgente.
Includi questi file di codice sorgente o la libreria statica nel tuo processo di build tramite Prefab, che espone le librerie native e il 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
GameActivityal filebuild.gradledel tuo gioco.Attiva Prefab eseguendo le seguenti operazioni con plug-in Android Version (AGP) 4.1 o versioni successive:
- Aggiungi quanto segue al blocco
androiddel filebuild.gradledel modulo:
buildFeatures { prefab true }- Scegli una versione di Prefab e impostala sul file
gradle.properties:
android.prefabVersion=2.0.0Se utilizzi versioni precedenti di AGP, segui la documentazione di Prefab per le istruzioni di configurazione corrispondenti.
- Aggiungi quanto segue al blocco
Importa la libreria statica C/C++ o il codice sorgente C/C++ nel tuo progetto come segue.
Libreria statica
Nel file
CMakeLists.txtdel progetto, importa la libreria staticagame-activitynel modulo prefabbricatogame-activity_static:find_package(game-activity REQUIRED CONFIG) target_link_libraries(${PROJECT_NAME} PUBLIC log android game-activity::game-activity_static)Codice sorgente
Nel file
CMakeLists.txtdel progetto, importa il pacchettogame-activitye aggiungilo alla destinazione. Il pacchettogame-activityrichiedelibandroid.so, quindi se non è presente, devi importare anche questo.find_package(game-activity REQUIRED CONFIG) ... target_link_libraries(... android game-activity::game-activity)Inoltre, includi i seguenti file nel
CmakeLists.txtdel tuo progetto:GameActivity.cpp,GameTextInput.cppeandroid_native_app_glue.c.
In che modo Android avvia l'attività
Il sistema Android esegue il codice nell'istanza Activity richiamando i metodi di callback che corrispondono a fasi specifiche del ciclo di vita dell'attività. Affinché Android possa avviare l'attività e il gioco, devi dichiarare l'attività con gli attributi appropriati nel file manifest Android. Per saperne di più, consulta Introduzione alle attività.
Manifest Android
Ogni progetto di app deve avere un file AndroidManifest.xml nella directory principale del set di risorse del progetto. Il file manifest descrive informazioni essenziali sulla tua app per gli strumenti di build di Android, il sistema operativo Android e Google Play. È incluso quanto segue:
Nome del pacchetto e ID app per identificare in modo univoco il tuo gioco su Google Play.
Componenti dell'app come attività, servizi, broadcast receiver e provider di contenuti.
Autorizzazioni per accedere a parti protette del sistema o ad altre app.
Compatibilità dei dispositivi per specificare i requisiti hardware e software del tuo gioco.
Nome della libreria nativa per
GameActivityeNativeActivity(il valore predefinito è libmain.so).
Implementa GameActivity nel tuo gioco
Crea o identifica la classe Java dell'attività principale (quella specificata nell'elemento
activityall'interno del fileAndroidManifest.xml). Modifica questa classe per estendereGameActivitydal pacchettocom.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.xmlse il nome della libreria non è quello predefinito (libmain.so):<meta-data android:name="android.app.lib_name" android:value="android-game" />
Implementa android_main
La libreria
android_native_app_glueè una libreria di codice sorgente utilizzata dal tuo gioco per gestire gli eventi del ciclo di vita diGameActivityin un thread separato, in modo da evitare il blocco nel thread principale. Quando utilizzi la libreria, registri il callback per gestire gli eventi del ciclo di vita, ad esempio gli eventi di input tocco. L'archivioGameActivityinclude la propria versione della libreriaandroid_native_app_glue, quindi non puoi utilizzare la versione inclusa nelle release NDK. Se i tuoi giochi utilizzano la libreriaandroid_native_app_glueinclusa nell'NDK, passa alla versioneGameActivity.Dopo aver aggiunto il codice sorgente della libreria
android_native_app_glueal tuo progetto, questo si interfaccia conGameActivity. Implementa una funzione denominataandroid_main, che viene chiamata dalla libreria e utilizzata come punto di ingresso per il tuo gioco. Viene passata una struttura chiamataandroid_app. Questo potrebbe variare per il tuo gioco e il tuo 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_appnel loop di gioco principale, ad esempio il polling e la gestione degli eventi del ciclo dell'app definiti inNativeAppGlueAppCmd. Ad esempio, il seguente snippet registra la funzione_hand_cmd_proxycome gestoreNativeAppGlueAppCmd, quindi esegue il polling degli eventi del ciclo dell'app e li invia al gestore registrato (inandroid_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 approfondimenti, studia l'implementazione dell'esempio NDK Endless Tunnel. La differenza principale sarà il modo in cui gestire gli eventi, come mostrato nella sezione successiva.
Gestisci 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 gli eventi di movimento dall'input
SOURCE_TOUCHSCREEN. Assicurati di consultare il documento di riferimento e il codice di implementazione di android_native_app_glue per i dettagli.
Per gestire gli eventi di input, ottieni un riferimento a android_input_buffer con android_app_swap_input_buffers() nel loop di gioco. Questi contengono eventi di movimento ed eventi chiave che si sono verificati dall'ultimo polling. Il numero di eventi contenuti viene memorizzato rispettivamente in motionEventsCount e keyEventsCount.
Esegui l'iterazione e gestisci ogni evento nel loop di gioco. In questo esempio, il codice seguente esegue l'iterazione di
motionEventse li gestisce utilizzandohandle_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); }Consulta l'esempio di GitHub per l'implementazione di
_cookEventForPointerIndex()e di altre funzioni correlate.Al termine, ricordati di cancellare la coda di eventi che hai appena gestito:
android_app_clear_motion_events(mApp);
Risorse aggiuntive
Per scoprire di più su GameActivity, consulta le seguenti risorse:
- Note di rilascio di GameActivity e AGDK.
- Utilizza GameTextInput in GameActivity.
- Guida alla migrazione di NativeActivity.
- Documentazione di riferimento di GameActivity.
- Implementazione di GameActivity.
Per segnalare bug o richiedere nuove funzionalità per GameActivity, utilizza l'Issue Tracker di GameActivity.