เริ่มต้นใช้งาน 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
ทำตามวิธีการในหน้าเกม Android ของ Jetpack เพื่อเพิ่มทรัพยากร Dependency ของไลบรารี
GameActivityลงในไฟล์build.gradleของเกมเปิดใช้ Prefab โดยทำตามขั้นตอนต่อไปนี้ด้วย ปลั๊กอิน Android เวอร์ชัน (AGP) 4.1 ขึ้นไป
- เพิ่มโค้ดต่อไปนี้ลงในบล็อก
androidของไฟล์build.gradleของโมดูล
buildFeatures { prefab true }- เลือกเวอร์ชัน Prefab
และตั้งค่าเป็นไฟล์
gradle.propertiesดังนี้
android.prefabVersion=2.0.0หากคุณใช้ AGP เวอร์ชันก่อนหน้า ให้ทำตามเอกสารประกอบของ Prefab เพื่อดูวิธีการกำหนดค่าที่เกี่ยวข้อง
- เพิ่มโค้ดต่อไปนี้ลงในบล็อก
นำเข้าไลบรารีแบบคงที่ 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 ทราบ ซึ่งรวมถึงเนื้อหาต่อไปนี้
ชื่อแพ็กเกจและรหัสแอปเพื่อระบุเกมของคุณใน Google Play โดยไม่ซ้ำกัน
คอมโพเนนต์ของแอป เช่น กิจกรรม บริการ Broadcast Receiver และ Content Provider
สิทธิ์ในการเข้าถึงส่วนที่มีการป้องกันของระบบหรือแอปอื่นๆ
ความเข้ากันได้ของอุปกรณ์เพื่อระบุข้อกำหนดด้านฮาร์ดแวร์และซอฟต์แวร์สำหรับเกม
ชื่อไลบรารีแบบเนทีฟสำหรับ
GameActivityและNativeActivity(ค่าเริ่มต้นคือ libmain.so)
ใช้ GameActivity ในเกม
สร้างหรือระบุคลาส Java ของกิจกรรมหลัก (คลาสที่ระบุในองค์ประกอบ
activityภายในไฟล์AndroidManifest.xml) เปลี่ยนคลาสนี้เพื่อขยายGameActivityจากแพ็กเกจcom.google.androidgamesdk:import com.google.androidgamesdk.GameActivity; public class YourGameActivity extends GameActivity { ... }ตรวจสอบว่าได้โหลดไลบรารีแบบเนทีฟเมื่อเริ่มต้นโดยใช้บล็อกแบบคงที่
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"); } ... }เพิ่มไลบรารีแบบเนทีฟลงใน
AndroidManifest.xmlหากชื่อไลบรารีไม่ใช่ชื่อเริ่มต้น (libmain.so)<meta-data android:name="android.app.lib_name" android:value="android-game" />
ติดตั้งใช้งาน android_main
ไลบรารี
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; }ประมวลผล
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(); } } }หากต้องการอ่านเพิ่มเติม โปรดศึกษาการใช้งานตัวอย่าง 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 ตามลำดับ
ทำซ้ำและจัดการแต่ละเหตุการณ์ใน Game Loop ในตัวอย่างนี้ โค้ดต่อไปนี้จะทำซ้ำ
motionEventsและจัดการโดยใช้handle_eventandroid_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()และฟังก์ชันอื่นๆ ที่เกี่ยวข้องเมื่อเสร็จแล้ว อย่าลืมล้างคิวของเหตุการณ์ที่คุณเพิ่งจัดการไป ดังนี้
android_app_clear_motion_events(mApp);
แหล่งข้อมูลเพิ่มเติม
ดูข้อมูลเพิ่มเติมเกี่ยวกับ GameActivity ได้ที่หัวข้อต่อไปนี้
- บันทึกประจำรุ่นของ GameActivity และ AGDK
- ใช้ GameTextInput ใน GameActivity
- คำแนะนำในการย้ายข้อมูล NativeActivity
- เอกสารอ้างอิง GameActivity
- การติดตั้งใช้งาน GameActivity
หากต้องการรายงานข้อบกพร่องหรือขอฟีเจอร์ใหม่สำหรับ GameActivity ให้ใช้เครื่องมือติดตามปัญหาของ GameActivity