מעבר מ-NativeActivity חלק מ-Android Game Development Kit.
בדף הזה מוסבר איך לעבור מ-NativeActivity ל-GameActivity בפרויקט המשחק ל-Android.
GameActivity מבוסס על NativeActivity מ-Android Framework, עם שיפורים ותכונות חדשות:
- תמיכה ב-
Fragmentמ-Jetpack. - הוספת תמיכה ב-
TextInputכדי לאפשר שילוב של מקלדת וירטואלית. - מטפל באירועי מגע ומקשים במחלקת Java של
GameActivityבמקום בממשקNativeActivityonInputEvent.
לפני המעבר, מומלץ לקרוא את המדריך לתחילת העבודה, שבו מוסבר איך להגדיר ולשלב את GameActivity בפרויקט.
עדכונים לסקריפט ה-build של Java
GameActivity מופץ כספריית Jetpack. חשוב להקפיד לבצע את השלבים לעדכון הסקריפט של Gradle, כפי שמתואר במדריך לתחילת העבודה:
מפעילים את ספריית Jetpack בקובץ
gradle.propertiesשל הפרויקט:android.useAndroidX=trueאפשר גם לציין גרסת Prefab באותו קובץ
gradle.properties, לדוגמה:android.prefabVersion=2.0.0מפעילים את התכונה Prefab בקובץ
build.gradleשל האפליקציה:android { ... // other configurations buildFeatures.prefab true }מוסיפים את התלות
GameActivityלאפליקציה:- מוסיפים את הספריות
coreו-games-activity. - אם רמת ה-API המינימלית שנתמכת כרגע נמוכה מ-16, צריך לעדכן אותה ל-16 לפחות.
- מעדכנים את גרסת ה-SDK המקומפלת לגרסה שנדרשת על ידי הספרייה
games-activity. בדרך כלל, כדי להשתמש ב-Jetpack צריך את גרסת ה-SDK העדכנית ביותר בזמן יצירת ה-build להפצה.
קובץ
build.gradleהמעודכן אמור להיראות כך:android { compiledSdkVersion 33 ... // other configurations. defaultConfig { minSdkVersion 16 } ... // other configurations. buildFeatures.prefab true } dependencies { implementation 'androidx.core:core:1.9.0' implementation 'androidx.games:games-activity:1.2.2' }- מוסיפים את הספריות
עדכונים בקוד Kotlin או Java
אפשר להשתמש ב-NativeActivity כפעילות אתחול וליצור אפליקציה במסך מלא. כרגע אי אפשר להשתמש ב-GameActivity כ-activity להפעלה. האפליקציות צריכות להפיק מחלקה מ-GameActivity ולהשתמש בה כפעילות ההפעלה. כדי ליצור אפליקציה במסך מלא, צריך לבצע שינויים נוספים בהגדרות.
בשלבים הבאים, נניח שהאפליקציה משתמשת ב-NativeActivity כפעילות ההפעלה. אם זה לא המצב, אפשר לדלג על רוב השלבים.
יוצרים קובץ Kotlin או Java כדי לארח את פעילות ההפעלה החדשה. לדוגמה, הקוד הבא יוצר את
MainActivityכפעילות ההפעלה וטוען את ספריית ה-Native הראשית של האפליקציה,libAndroidGame.so:Kotlin
class MainActivity : GameActivity() { override fun onResume() { super.onResume() // Use the function recommended from the following page: // https://d.android.com/training/system-ui/immersive hideSystemBars() } companion object { init { System.loadLibrary("AndroidGame") } } }Java
public class MainActivity extends GameActivity { protected void onResume() { super.onResume(); // Use the function recommended from // https://d.android.com/training/system-ui/immersive hideSystemBars(); } static { System.loadLibrary("AndroidGame"); } }יוצרים עיצוב לאפליקציה במסך מלא בקובץ
res\values\themes.xml:<resources xmlns:tools="http://schemas.android.com/tools"> <!-- Base application theme. --> <style name="Application.Fullscreen" parent="Theme.AppCompat.Light.NoActionBar"> <item name="android:windowFullscreen">true</item> <item name="android:windowContentOverlay">@null</item>" </style> </resources>מחילים את העיצוב על האפליקציה בקובץ
AndroidManifest.xml:<application android:theme="@style/Application.Fullscreen"> <!-- other configurations not listed here. --> </application>הוראות מפורטות למצב מסך מלא זמינות במדריך למצב אימרסיבי, ודוגמה להטמעה זמינה במאגר games-samples.
המדריך הזה להעברת נתונים (מיגרציה) לא משנה את השם של ספריית ה-Native. אם משנים אותו, צריך לוודא ששמות ספריית ה-Native זהים בשלושת המקומות הבאים:
קוד Kotlin או Java:
System.loadLibrary("AndroidGame")AndroidManifest.xml:<meta-data android:name="android.app.lib_name" android:value="AndroidGame" />בתוך קובץ הסקריפט של ה-build ב-C/C++, לדוגמה
CMakeLists.txt:add_library(AndroidGame ...)
עדכונים לסקריפט ה-build של C/C++
ההוראות בקטע הזה משתמשות ב-cmake כדוגמה. אם האפליקציה שלכם משתמשת ב-ndk-build, אתם צריכים למפות אותם לפקודות המקבילות שמתוארות בדף התיעוד של ndk-build.
הטמעת C/C++ של GameActivity מספקת גרסת קוד מקור. בגרסה 1.2.2 ואילך, יש גרסה של ספרייה סטטית. הספרייה הסטטית היא סוג הגרסה המומלץ.
הגרסה ארוזה בתוך ה-AAR עם הכלי prefab. קוד ה-Native כולל את מקורות ה-C/C++ של GameActivity ואת קוד ה-native_app_glue. צריך ליצור אותם יחד עם קוד ה-C/C++ של האפליקציה.
NativeActivity אפליקציות כבר משתמשות בקוד native_app_glue שנשלח בתוך NDK. צריך להחליף אותו בגרסה של GameActivity של native_app_glue. חוץ מזה, כל cmake השלבים שמתוארים במדריך לתחילת העבודה רלוונטיים:
מייבאים לפרויקט את הספרייה הסטטית של C/C++ או את קוד המקור של C/C++, באופן הבא:
ספרייה סטטית
בקובץ
CMakeLists.txtשל הפרויקט, מייבאים את הספרייה הסטטיתgame-activityלמודול ה-prefabgame-activity_static:find_package(game-activity REQUIRED CONFIG) target_link_libraries(${PROJECT_NAME} PUBLIC log android game-activity::game-activity_static)קוד מקור
בקובץ
CMakeLists.txtשל הפרויקט, מייבאים את החבילהgame-activityומוסיפים אותה ליעד. החבילהgame-activityדורשת אתlibandroid.so, אז אם היא חסרה, צריך לייבא גם אותה.find_package(game-activity REQUIRED CONFIG) ... target_link_libraries(... android game-activity::game-activity)מסירים את כל ההפניות לקוד
native_app_glueשל NDK, למשל:${ANDROID_NDK}/sources/android/native_app_glue/android_native_app_glue.c ... set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -u ANativeActivity_onCreate")אם אתם משתמשים בגרסת קוד המקור, צריך לכלול את קובצי המקור של
GameActivity. אם לא, דלגו על השלב הזה.get_target_property(game-activity-include game-activity::game-activity INTERFACE_INCLUDE_DIRECTORIES) add_library(${PROJECT_NAME} SHARED main.cpp ${game-activity-include}/game-activity/native_app_glue/android_native_app_glue.c ${game-activity-include}/game-activity/GameActivity.cpp ${game-activity-include}/game-text-input/gametextinput.cpp)
פתרון הבעיה UnsatisfiedLinkError
אם נתקלים ב-UnsatsifiedLinkError עבור הפונקציה com.google.androidgamesdk.GameActivity.initializeNativeCode(), מוסיפים את הקוד הזה לקובץ CMakeLists.txt:
set(CMAKE_SHARED_LINKER_FLAGS
"${CMAKE_SHARED_LINKER_FLAGS} -u \
Java_com_google_androidgamesdk_GameActivity_initializeNativeCode")
עדכונים בקוד המקור של C/C++
כדי להחליף את ההפניות ל-NativeActivity באפליקציה ב-GameActivity:
משתמשים ב-
native_app_glueשפורסם עםGameActivity. מחפשים את כל המקומות שבהם מופיעandroid_native_app_glue.hומחליפים אותם ב:#include <game-activity/native_app_glue/android_native_app_glue.h>מגדירים גם את מסנן אירועי התנועה וגם את מסנן אירועי המקשים לערך
NULLכדי שהאפליקציה תוכל לקבל אירועי קלט מכל מכשירי לקליטת נתונים. בדרך כלל עושים את זה בתוך הפונקציהandroid_main():void android_main(android_app* app) { ... // other init code. android_app_set_key_event_filter(app, NULL); android_app_set_motion_event_filter(app, NULL); ... // additional init code, and game loop code. }מסירים את הקוד שקשור ל-
AInputEventומחליפים אותו בהטמעה שלInputBufferב-GameActivity:while (true) { // Read all pending events. int events; struct android_poll_source* source; // If not animating, block forever waiting for events. // If animating, loop until all events are read, then continue // to draw the next frame of animation. while ((ALooper_pollOnce(engine.animating ? 0 : -1, nullptr, &events, (void**)&source)) >= 0) { // Process this app cycle or inset change event. if (source) { source->process(source->app, source); } ... // Other processing. // Check if app is exiting. if (state->destroyRequested) { engine_term_display(&engine); return; } } // Process input events if there are any. engine_handle_input(state); if (engine.animating) { // Draw a game frame. } } // Implement input event handling function. static int32_t engine_handle_input(struct android_app* app) { auto* engine = (struct engine*)app->userData; auto ib = android_app_swap_input_buffers(app); if (ib && ib->motionEventsCount) { for (int i = 0; i < ib->motionEventsCount; i++) { auto *event = &ib->motionEvents[i]; int32_t ptrIdx = 0; switch (event->action & AMOTION_EVENT_ACTION_MASK) { case AMOTION_EVENT_ACTION_POINTER_DOWN: case AMOTION_EVENT_ACTION_POINTER_UP: // Retrieve the index for the starting and the ending of any secondary pointers ptrIdx = (event->action & AMOTION_EVENT_ACTION_POINTER_INDEX_MASK) >> AMOTION_EVENT_ACTION_POINTER_INDEX_SHIFT; case AMOTION_EVENT_ACTION_DOWN: case AMOTION_EVENT_ACTION_UP: engine->state.x = GameActivityPointerAxes_getAxisValue( &event->pointers[ptrIdx], AMOTION_EVENT_AXIS_X); engine->state.y = GameActivityPointerAxes_getAxisValue( &event->pointers[ptrIdx], AMOTION_EVENT_AXIS_Y); break; case AMOTION_EVENT_ACTION_MOVE: // Process the move action: the new coordinates for all active touch pointers // are inside the event->pointers[]. Compare with our internally saved // coordinates to find out which pointers are actually moved. Note that there is // no index embedded inside event->action for AMOTION_EVENT_ACTION_MOVE (there // might be multiple pointers moved at the same time). ... break; } } android_app_clear_motion_events(ib); } // Process the KeyEvent in a similar way. ... return 0; }צריך לבדוק ולעדכן את הלוגיקה שמצורפת ל
AInputEventשלNativeActivity. כפי שמוצג בשלב הקודם, העיבוד שלInputBufferב-GameActivity נמצא מחוץ ללולאהALooper_pollOnce.מחליפים את השימוש ב-
android_app::activity->clazzב-android_app:: activity->javaGameActivity. GameActivity משנה את השם של המכונה של JavaGameActivity.
שלבים נוספים
השלבים הקודמים עוסקים בפונקציונליות של NativeActivity, אבל ל-GameActivity יש תכונות נוספות שאולי תרצו להשתמש בהן:
- TextInput.
- שלט משחק.
- Fragment.
- פקודות InSets חדשות לחלונות שמוגדרות ב-NativeAppGlueAppCmd.
מומלץ לבדוק את התכונות האלה ולהשתמש בהן בהתאם למשחקים שלכם.
אם יש לכם שאלות או המלצות לגבי GameActivity או ספריות אחרות של AGDK, אתם יכולים ליצור באג כדי לעדכן אותנו.