ย้ายข้อมูลจาก NativeActivity   เป็นส่วนหนึ่งของชุดเครื่องมือพัฒนาเกม Android

หน้านี้อธิบายวิธีย้ายข้อมูลจาก NativeActivity ไปยัง GameActivity ในโปรเจ็กต์เกม Android

GameActivity อิงตาม NativeActivity จากเฟรมเวิร์ก Android โดยมีการเพิ่มประสิทธิภาพและฟีเจอร์ใหม่ๆ ดังนี้

  • รองรับ Fragment จาก Jetpack
  • เพิ่มการรองรับ TextInput เพื่ออำนวยความสะดวกในการผสานรวมแป้นพิมพ์เสมือน
  • จัดการเหตุการณ์การแตะและเหตุการณ์สำคัญในคลาส GameActivity Java แทนอินเทอร์เฟซ NativeActivity onInputEvent

ก่อนย้ายข้อมูล เราขอแนะนำให้อ่านคู่มือเริ่มต้นใช้งาน ซึ่งอธิบายวิธีตั้งค่าและผสานรวม GameActivity ในโปรเจ็กต์

การอัปเดตสคริปต์บิลด์ Java

GameActivity เผยแพร่เป็นไลบรารี Jetpack อย่าลืมทำตามขั้นตอนการอัปเดตสคริปต์ Gradle ที่อธิบายไว้ในคู่มือเริ่มต้นใช้งาน ดังนี้

  1. เปิดใช้ไลบรารี Jetpack ในไฟล์ gradle.properties ของโปรเจ็กต์โดยทำดังนี้

    android.useAndroidX=true
    
  2. ระบุเวอร์ชัน Prefab ในไฟล์ gradle.properties เดียวกัน (ไม่บังคับ) เช่น

    android.prefabVersion=2.0.0
    
  3. เปิดใช้ฟีเจอร์ Prefab ในไฟล์ build.gradle ของแอป

    android {
        ... // other configurations
        buildFeatures.prefab true
    }
    
  4. เพิ่มทรัพยากร Dependency GameActivity ลงในแอปพลิเคชัน

    1. เพิ่มไลบรารี core และ games-activity
    2. หากระดับ API ขั้นต่ำที่รองรับในปัจจุบันต่ำกว่า 16 ให้อัปเดตเป็นอย่างน้อย 16
    3. อัปเดตเวอร์ชัน 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 เป็นกิจกรรมเริ่มต้น หากไม่ใช่กรณีนี้ คุณสามารถข้ามขั้นตอนส่วนใหญ่ได้

  1. สร้างไฟล์ Kotlin หรือ Java เพื่อโฮสต์กิจกรรมการเริ่มต้นใหม่ ตัวอย่างเช่น โค้ดต่อไปนี้จะสร้าง MainActivity เป็นกิจกรรมเริ่มต้นและโหลดไลบรารีแบบเนทีฟหลักของแอปพลิเคชัน 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");
        }
    }
    
  2. สร้างธีมแอปแบบเต็มหน้าจอในไฟล์ 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>
    
  3. ใช้ธีมกับแอปพลิเคชันในไฟล์ 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->javaGameActivity GameActivity จะเปลี่ยนชื่ออินสแตนซ์ GameActivity ของ Java

ขั้นตอนเพิ่มเติม

ขั้นตอนก่อนหน้านี้ครอบคลุมฟังก์ชันการทำงานของ NativeActivity แต่ GameActivity มีฟีเจอร์เพิ่มเติมที่คุณอาจต้องการใช้ ดังนี้

เราขอแนะนำให้สำรวจฟีเจอร์เหล่านี้และนำไปใช้ตามความเหมาะสมสำหรับเกมของคุณ

หากมีคำถามหรือคำแนะนำสำหรับ GameActivity หรือไลบรารี AGDK อื่นๆ โปรดสร้างข้อบกพร่องเพื่อแจ้งให้เราทราบ