เริ่มต้นใช้งาน GameActivity   เป็นส่วนหนึ่งของชุดเครื่องมือพัฒนาเกม Android

คู่มือนี้อธิบายวิธีตั้งค่าและผสานรวมGameActivity รวมถึงจัดการเหตุการณ์ในเกม Android

GameActivity ช่วยให้คุณนำเกม C หรือ C++ มายัง Android ได้โดยลดความซับซ้อนของกระบวนการใช้ API ที่สำคัญ ก่อนหน้านี้ NativeActivity เป็นคลาสที่แนะนำสำหรับเกม GameActivity จะมาแทนที่ในฐานะคลาสที่แนะนำสำหรับเกม และเข้ากันได้แบบย้อนหลังกับ API ระดับ 19

ดูตัวอย่างที่ผสานรวม GameActivity ได้ที่ที่เก็บ games-samples

ก่อนจะเริ่มต้น

ดูรุ่น GameActivity เพื่อรับการเผยแพร่

ตั้งค่าบิลด์

ใน Android นั้น Activity จะทำหน้าที่เป็นจุดแรกเข้าสำหรับเกมของคุณ และยังมี Window สำหรับวาดภาพภายในด้วย เกมจำนวนมากขยาย Activity นี้ด้วยคลาส Java หรือ Kotlin ของตนเองเพื่อเอาชนะข้อจำกัดใน NativeActivity ขณะใช้โค้ด JNI เพื่อเชื่อมโยงกับโค้ดเกม C หรือ C++

GameActivity มีความสามารถดังต่อไปนี้

  • รับค่าจาก AppCompatActivity ซึ่งช่วยให้คุณใช้คอมโพเนนต์สถาปัตยกรรม Android Jetpack ได้

  • แสดงผลเป็น SurfaceView ที่ช่วยให้คุณเชื่อมต่อกับองค์ประกอบ UI อื่นๆ ของ Android ได้

  • จัดการเหตุการณ์กิจกรรม Java ซึ่งช่วยให้คุณผสานรวมองค์ประกอบ UI ของ Android (เช่น EditText, WebView หรือ Ad) เข้ากับเกมโดยใช้อินเทอร์เฟซ C ได้

  • มี C API ที่คล้ายกับไลบรารี NativeActivity และ android_native_app_glue

GameActivity มีการเผยแพร่เป็น Android Archive (AAR) AAR นี้มีคลาส Java ที่คุณใช้ใน AndroidManifest.xml รวมถึงซอร์สโค้ด C และ C++ ที่เชื่อมต่อฝั่ง Java ของ GameActivity กับการใช้งาน C/C++ ของแอป หากคุณใช้ GameActivity 1.2.2 ขึ้นไป ระบบจะจัดเตรียมไลบรารีแบบคงที่ C/C++ ไว้ให้ด้วย เราขอแนะนำให้คุณใช้ไลบรารีแบบคงที่แทนซอร์สโค้ดเมื่อทำได้

รวมไฟล์ต้นฉบับหรือไลบรารีแบบคงที่เหล่านี้เป็นส่วนหนึ่งของกระบวนการบิลด์ผ่าน Prefab ซึ่งจะแสดงไลบรารีแบบเนทีฟและซอร์สโค้ดต่อโปรเจ็กต์ CMake หรือบิลด์ NDK

  1. ทำตามวิธีการในหน้าเกม Android ของ Jetpack เพื่อเพิ่มทรัพยากร Dependency ของไลบรารี GameActivity ลงในไฟล์ build.gradle ของเกม

  2. เปิดใช้ Prefab โดยทำตามขั้นตอนต่อไปนี้ด้วย ปลั๊กอิน Android เวอร์ชัน (AGP) 4.1 ขึ้นไป

    • เพิ่มโค้ดต่อไปนี้ลงในบล็อก android ของไฟล์ build.gradle ของโมดูล
    buildFeatures {
        prefab true
    }
    
    android.prefabVersion=2.0.0
    

    หากคุณใช้ AGP เวอร์ชันก่อนหน้า ให้ทำตามเอกสารประกอบของ Prefab เพื่อดูวิธีการกำหนดค่าที่เกี่ยวข้อง

  3. นำเข้าไลบรารีแบบคงที่ 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)
    

    นอกจากนี้ ให้รวมไฟล์ต่อไปนี้ไว้ใน CmakeLists.txt ของโปรเจ็กต์ด้วย GameActivity.cpp, GameTextInput.cpp และ android_native_app_glue.c

วิธีที่ Android เปิดใช้งานกิจกรรมของคุณ

ระบบ Android จะเรียกใช้โค้ดในอินสแตนซ์กิจกรรมโดยเรียกใช้เมธอด Callback ที่สอดคล้องกับระยะที่เฉพาะเจาะจงของวงจรกิจกรรม เพื่อให้ Android เปิดกิจกรรมและเริ่มเกมได้ คุณต้องประกาศกิจกรรมด้วยแอตทริบิวต์ที่เหมาะสมในไฟล์ Manifest ของ Android ดูข้อมูลเพิ่มเติมได้ที่ข้อมูลเบื้องต้นเกี่ยวกับกิจกรรม

ไฟล์ Manifest ของ Android

โปรเจ็กต์แอปทุกโปรเจ็กต์ต้องมีไฟล์ AndroidManifest.xml ที่รูทของชุดซอร์สโปรเจ็กต์ ไฟล์ Manifest อธิบายข้อมูลสำคัญเกี่ยวกับแอปของคุณให้เครื่องมือสร้าง Android, ระบบปฏิบัติการ Android และ Google Play ทราบ ซึ่งรวมถึงเนื้อหาต่อไปนี้

ใช้ GameActivity ในเกม

  1. สร้างหรือระบุคลาส Java ของกิจกรรมหลัก (คลาสที่ระบุในองค์ประกอบ activity ภายในไฟล์ AndroidManifest.xml) เปลี่ยนคลาสนี้เพื่อขยาย GameActivity จากแพ็กเกจ com.google.androidgamesdk:

    import com.google.androidgamesdk.GameActivity;
    
    public class YourGameActivity extends GameActivity { ... }
    
  2. ตรวจสอบว่าได้โหลดไลบรารีแบบเนทีฟเมื่อเริ่มต้นโดยใช้บล็อกแบบคงที่

    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");
      }
      ...
    }
    
  3. เพิ่มไลบรารีแบบเนทีฟลงใน AndroidManifest.xml หากชื่อไลบรารีไม่ใช่ชื่อเริ่มต้น (libmain.so)

    <meta-data android:name="android.app.lib_name"
     android:value="android-game" />
    

ติดตั้งใช้งาน android_main

  1. ไลบรารี android_native_app_glue เป็นไลบรารีซอร์สโค้ดที่เกมของคุณใช้เพื่อจัดการเหตุการณ์ในวงจร GameActivity ในเทรดแยกต่างหากเพื่อป้องกันการบล็อกในเทรดหลัก เมื่อใช้ไลบรารี คุณจะลงทะเบียน Callback เพื่อจัดการเหตุการณ์ในวงจร เช่น เหตุการณ์การป้อนข้อมูลด้วยการสัมผัส ที่เก็บถาวร GameActivity มีไลบรารี android_native_app_glue เวอร์ชันของตัวเอง คุณจึงใช้เวอร์ชันที่รวมอยู่ในรุ่น NDK ไม่ได้ หากเกมของคุณใช้ไลบรารี android_native_app_glue ที่รวมอยู่ใน NDK ให้เปลี่ยนไปใช้เวอร์ชัน GameActivity

    หลังจากเพิ่มซอร์สโค้ดของไลบรารี android_native_app_glue ลงในโปรเจ็กต์แล้ว ซอร์สโค้ดจะเชื่อมต่อกับ GameActivity ใช้ฟังก์ชันชื่อ android_main ซึ่งไลบรารีจะเรียกใช้และใช้เป็นจุดแรกเข้าสำหรับเกมของคุณ โดยจะส่งโครงสร้างที่เรียกว่า android_app ซึ่งอาจแตกต่างกันไปตามเกมและเครื่องมือ ตัวอย่าง

    #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;
    }
    
  2. ประมวลผล android_app ใน Game Loop หลัก เช่น การโพลและการจัดการเหตุการณ์วงจรของแอปที่กำหนดไว้ใน NativeAppGlueAppCmd ตัวอย่างเช่น ข้อมูลโค้ดต่อไปนี้จะลงทะเบียนฟังก์ชัน _hand_cmd_proxy เป็นแฮนเดิล NativeAppGlueAppCmd จากนั้นจะโพลเหตุการณ์วงจรของแอป และส่งเหตุการณ์เหล่านั้นไปยังแฮนเดิลที่ลงทะเบียนไว้ (ใน android_app::onAppCmd) เพื่อประมวลผล

    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();
        }
      }
    }
    
  3. หากต้องการอ่านเพิ่มเติม โปรดศึกษาการใช้งานตัวอย่าง NDK ของ Endless Tunnel ความแตกต่างหลักคือวิธีจัดการเหตุการณ์ตามที่แสดงในส่วนถัดไป

จัดการเหตุการณ์

หากต้องการเปิดใช้เหตุการณ์อินพุตเพื่อเข้าถึงแอป ให้สร้างและลงทะเบียนตัวกรองเหตุการณ์ด้วย android_app_set_motion_event_filter และ android_app_set_key_event_filter โดยค่าเริ่มต้น ไลบรารี native_app_glue จะอนุญาตเฉพาะเหตุการณ์การเคลื่อนไหวจากอินพุต SOURCE_TOUCHSCREEN เท่านั้น โปรดดูรายละเอียดในเอกสารอ้างอิงและโค้ดการติดตั้งใช้งาน android_native_app_glue

หากต้องการจัดการเหตุการณ์อินพุต ให้รับข้อมูลอ้างอิงไปยัง android_input_buffer ด้วย android_app_swap_input_buffers() ใน Game Loop ซึ่งประกอบด้วยเหตุการณ์การเคลื่อนไหวและเหตุการณ์สำคัญที่เกิดขึ้นตั้งแต่การสำรวจครั้งล่าสุด จำนวนเหตุการณ์ที่รวมอยู่จะจัดเก็บไว้ใน motionEventsCount และ keyEventsCount ตามลำดับ

  1. ทำซ้ำและจัดการแต่ละเหตุการณ์ใน Game Loop ในตัวอย่างนี้ โค้ดต่อไปนี้จะทำซ้ำ motionEvents และจัดการโดยใช้ 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);
    }
    

    ดูตัวอย่าง GitHub สำหรับการใช้งาน _cookEventForPointerIndex() และฟังก์ชันอื่นๆ ที่เกี่ยวข้อง

  2. เมื่อเสร็จแล้ว อย่าลืมล้างคิวของเหตุการณ์ที่คุณเพิ่งจัดการไป ดังนี้

    android_app_clear_motion_events(mApp);
    

แหล่งข้อมูลเพิ่มเติม

ดูข้อมูลเพิ่มเติมเกี่ยวกับ GameActivity ได้ที่หัวข้อต่อไปนี้

หากต้องการรายงานข้อบกพร่องหรือขอฟีเจอร์ใหม่สำหรับ GameActivity ให้ใช้เครื่องมือติดตามปัญหาของ GameActivity