ย้ายข้อมูลจาก NativeActivity เป็นส่วนหนึ่งของชุดเครื่องมือพัฒนาเกม Android
หน้านี้อธิบายวิธีย้ายข้อมูลจาก NativeActivity ไปยัง GameActivity ในโปรเจ็กต์เกม Android
GameActivity อิงตาม NativeActivity จากเฟรมเวิร์ก Android โดยมีการเพิ่มประสิทธิภาพและฟีเจอร์ใหม่ๆ ดังนี้
- รองรับ
Fragmentจาก Jetpack - เพิ่มการรองรับ
TextInputเพื่ออำนวยความสะดวกในการผสานรวมแป้นพิมพ์เสมือน - จัดการเหตุการณ์การแตะและเหตุการณ์สำคัญในคลาส
GameActivityJava แทนอินเทอร์เฟซNativeActivityonInputEvent
ก่อนย้ายข้อมูล เราขอแนะนำให้อ่านคู่มือเริ่มต้นใช้งาน ซึ่งอธิบายวิธีตั้งค่าและผสานรวม GameActivity ในโปรเจ็กต์
การอัปเดตสคริปต์บิลด์ 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 }เพิ่มทรัพยากร Dependency
GameActivityลงในแอปพลิเคชัน- เพิ่มไลบรารี
coreและgames-activity - หากระดับ API ขั้นต่ำที่รองรับในปัจจุบันต่ำกว่า 16 ให้อัปเดตเป็นอย่างน้อย 16
- อัปเดตเวอร์ชัน SDK ที่คอมไพล์แล้วเป็นเวอร์ชันที่ไลบรารี
games-activityต้องใช้ โดยทั่วไป Jetpack ต้องใช้ SDK เวอร์ชันล่าสุด ณ เวลาที่สร้างบิลด์ที่เผยแพร่
ไฟล์
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 ไม่สามารถใช้เป็นกิจกรรมเริ่มต้นได้ แอปต้องรับคลาสจาก GameActivity และใช้คลาสนั้นเป็นกิจกรรมเริ่มต้น นอกจากนี้ คุณยังต้องทำการเปลี่ยนแปลงการกำหนดค่าเพิ่มเติมเพื่อสร้างแอปแบบเต็มหน้าจอด้วย
ขั้นตอนต่อไปนี้ถือว่าแอปพลิเคชันของคุณใช้ NativeActivity เป็นกิจกรรมเริ่มต้น หากไม่ใช่กรณีนี้ คุณสามารถข้ามขั้นตอนส่วนใหญ่ได้
สร้างไฟล์ Kotlin หรือ Java เพื่อโฮสต์กิจกรรมการเริ่มต้นใหม่ ตัวอย่างเช่น โค้ดต่อไปนี้จะสร้าง
MainActivityเป็นกิจกรรมเริ่มต้นและโหลดไลบรารีแบบเนทีฟหลักของแอปพลิเคชันlibAndroidGame.soKotlin
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
คำแนะนำในการย้ายข้อมูลนี้จะไม่เปลี่ยนชื่อไลบรารีแบบเนทีฟ หากคุณเปลี่ยนชื่อ โปรดตรวจสอบว่าชื่อไลบรารีแบบเนทีฟสอดคล้องกันใน 3 ตำแหน่งต่อไปนี้
โค้ด Kotlin หรือ Java:
System.loadLibrary("AndroidGame")AndroidManifest.xml:<meta-data android:name="android.app.lib_name" android:value="AndroidGame" />ภายในไฟล์สคริปต์บิลด์ C/C++ เช่น
CMakeLists.txtให้ทำดังนี้add_library(AndroidGame ...)
การอัปเดตสคริปต์บิลด์ C/C++
วิธีการในส่วนนี้ใช้ cmake เป็นตัวอย่าง หากแอปพลิเคชันของคุณใช้ ndk-build คุณต้องแมปแอปพลิเคชันกับคำสั่งที่เทียบเท่าซึ่งอธิบายไว้ในหน้าเอกสารประกอบของ ndk-build
การใช้งาน C/C++ ของ GameActivity มีการเผยแพร่ซอร์สโค้ด สำหรับเวอร์ชัน 1.2.2 ขึ้นไป จะมีการเผยแพร่ไลบรารีแบบคงที่ เราขอแนะนำให้ใช้ไลบรารีแบบคงที่เป็นประเภทการเผยแพร่
รุ่นนี้จะรวมอยู่ใน AAR พร้อมกับยูทิลิตี prefab โค้ดแบบเนทีฟประกอบด้วยแหล่งที่มา C/C++ ของ GameActivity และโค้ด native_app_glue โดยต้องสร้างร่วมกับโค้ด C/C++ ของแอปพลิเคชัน
แอปพลิเคชัน NativeActivity รายการใช้โค้ด native_app_glue ที่จัดส่งภายใน NDK อยู่แล้ว คุณต้องแทนที่ด้วย native_app_glue เวอร์ชันของ GameActivity นอกเหนือจากนั้น ขั้นตอนทั้ง cmake ขั้นตอนที่ระบุไว้ในคู่มือเริ่มต้นใช้งานจะมีผลบังคับใช้ ดังนี้
นำเข้าไลบรารีแบบคงที่ C/C++ หรือซอร์สโค้ด C/++ ไปยังโปรเจ็กต์ของคุณดังนี้
ไลบรารีแบบคงที่
ในไฟล์
CMakeLists.txtของโปรเจ็กต์ ให้นำเข้าไลบรารีแบบคงที่game-activityไปยังโมดูลสำเร็จรูปgame-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->javaGameActivityGameActivity จะเปลี่ยนชื่ออินสแตนซ์GameActivityของ Java
ขั้นตอนเพิ่มเติม
ขั้นตอนก่อนหน้านี้ครอบคลุมฟังก์ชันการทำงานของ NativeActivity แต่ GameActivity มีฟีเจอร์เพิ่มเติมที่คุณอาจต้องการใช้ ดังนี้
- TextInput
- เกมคอนโทรลเลอร์
- Fragment
- คำสั่ง InSets ของหน้าต่างใหม่ที่กำหนดไว้ใน NativeAppGlueAppCmd
เราขอแนะนำให้สำรวจฟีเจอร์เหล่านี้และนำไปใช้ตามความเหมาะสมสำหรับเกมของคุณ
หากมีคำถามหรือคำแนะนำสำหรับ GameActivity หรือไลบรารี AGDK อื่นๆ โปรดสร้างข้อบกพร่องเพื่อแจ้งให้เราทราบ