بدء استخدام GameActivity جزء من حزمة تطوير ألعاب Android
يوضّح هذا الدليل كيفية إعداد GameActivity ودمجها والتعامل مع الأحداث في لعبة Android.
تساعدك حزمة GameActivity في نقل لعبتك المكتوبة بلغة C أو C++ إلى نظام Android من خلال تبسيط عملية استخدام واجهات برمجة التطبيقات المهمة.
في السابق، كانت الفئة NativeActivity هي الفئة المقترَحة للألعاب. ويحلّ محلّه GameActivity كفئة يُنصح بها للألعاب، وهو متوافق مع الأنظمة القديمة حتى المستوى 19 من واجهة برمجة التطبيقات.
للحصول على نموذج يدمج GameActivity، يُرجى الاطّلاع على مستودع نماذج الألعاب.
قبل البدء
يمكنك الاطّلاع على إصدارات GameActivity للحصول على توزيع.
إعداد الإصدار
على Android، يُعدّ Activity نقطة الدخول
للعبتك، كما يوفّر Window
للرسم بداخله. توسّع العديد من الألعاب
Activity هذه باستخدام فئة Java أو Kotlin الخاصة بها لتجاوز القيود في
NativeActivity أثناء استخدام رمز JNI للربط
برمز لعبة C أو C++.
يوفّر GameActivity الإمكانات التالية:
يتم اكتسابها من
AppCompatActivity، مما يسمح لك باستخدام مكوّنات بنية Android Jetpack.يتم عرضه في
SurfaceViewيتيح لك التفاعل مع أي عنصر في واجهة مستخدم Android آخر.يعالج هذا الإذن أحداث النشاط في Java. يتيح ذلك دمج أي عنصر في واجهة مستخدم Android (مثل
EditTextأوWebViewأوAd) في لعبتك باستخدام واجهة C.توفّر واجهة برمجة تطبيقات C مشابهة لمكتبة
NativeActivityوandroid_native_app_glue.
يتم توزيع "GameActivity" كـ أرشيف Android (AAR). يحتوي ملف AAR هذا على فئة Java التي تستخدمها في AndroidManifest.xml، بالإضافة إلى الرمز المصدر C وC++ الذي يربط جانب Java من GameActivity بتنفيذ C/C++ في التطبيق. إذا كنت تستخدم الإصدار 1.2.2 من GameActivity أو إصدارًا أحدث، يتم أيضًا توفير مكتبة C/C++ الثابتة. ننصحك باستخدام المكتبة الثابتة بدلاً من الرمز المصدر، متى أمكن ذلك.
يمكنك تضمين ملفات المصدر هذه أو المكتبة الثابتة كجزء من عملية الإنشاء من خلال Prefab، ما يؤدي إلى عرض المكتبات المجمّعة من رموز برمجية أصلية والرمز المصدر في مشروع CMake أو إصدار NDK.
اتّبِع التعليمات الواردة في صفحة ألعاب Jetpack Android لإضافة تبعية مكتبة
GameActivityإلى ملفbuild.gradleالخاص بلعبتك.يمكنك تفعيل Prefab من خلال تنفيذ ما يلي باستخدام الإصدار 4.1 من المكوّن الإضافي المتوافق مع Android أو الإصدارات الأحدث:
- أضِف ما يلي إلى قسم
androidفي ملفbuild.gradleالخاص بالوحدة:
buildFeatures { prefab true }- اختَر إصدار Prefab،
واضبطه على ملف
gradle.properties:
android.prefabVersion=2.0.0إذا كنت تستخدم إصدارات أقدم من "مكوّن Android الإضافي لبرنامج Gradle"، اتّبِع مستندات prefab للحصول على تعليمات الإعداد المتوافقة.
- أضِف ما يلي إلى قسم
استورِد مكتبة 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)أدرِج أيضًا الملفات التالية في ملف
CmakeLists.txtالخاص بمشروعك:GameActivity.cppوGameTextInput.cppوandroid_native_app_glue.c.
كيفية تشغيل Android لنشاطك
ينفّذ نظام Android الرمز البرمجي في مثيل النشاط من خلال استدعاء طرق رد الاتصال التي تتوافق مع مراحل معيّنة من مراحل النشاط. لكي يتمكّن Android من تشغيل نشاطك وبدء لعبتك، عليك الإعلان عن نشاطك باستخدام السمات المناسبة في ملف بيان Android. لمزيد من المعلومات، يُرجى الاطّلاع على مقدمة عن الأنشطة.
ملف بيان Android
يجب أن يتضمّن كل مشروع تطبيق ملف AndroidManifest.xml في جذر مجموعة رموز المصدر للمشروع. يصف ملف البيان معلومات أساسية عن تطبيقك لأدوات إصدار Android ونظام التشغيل Android وGoogle Play. ويشمل ذلك ما يلي:
اسم الحزمة ومعرّف التطبيق لتحديد لعبتك بشكل فريد على Google Play
مكوّنات التطبيق، مثل الأنشطة والخدمات وأجهزة استقبال البث وأدوات توفير المحتوى
الأذونات للوصول إلى الأجزاء المحمية من النظام أو التطبيقات الأخرى
توافق الأجهزة لتحديد متطلبات الأجهزة والبرامج للعبتك
اسم المكتبة المجمّعة من رموز برمجية أصلية لـ
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في سلسلة تعليمات منفصلة لمنع حظر سلسلة التعليمات الرئيسية. عند استخدام المكتبة، يتم تسجيل دالة الاستدعاء لمعالجة الأحداث التي تتم في مراحل النشاط، مثل أحداث الإدخال باللمس. يتضمّن أرشيف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في حلقة الألعاب الرئيسية، مثل الاستطلاع والتعامل مع أحداث دورة التطبيق المحدّدة في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() في حلقة الألعاب. وتحتوي هذه على
أحداث الحركة والأحداث الرئيسية التي حدثت منذ آخر مرة
تم فيها الاستطلاع. يتم تخزين عدد الأحداث المضمّنة في motionEventsCount وkeyEventsCount على التوالي.
كرِّر كل حدث في حلقة الألعاب وتعامل معه. في هذا المثال، يُكرّر الرمز التالي
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()والدوال الأخرى ذات الصلة.عند الانتهاء، تذكر مسح قائمة انتظار الأحداث التي تعاملت معها للتو:
android_app_clear_motion_events(mApp);
مراجع إضافية
لمزيد من المعلومات حول "GameActivity"، يُرجى الاطّلاع على ما يلي:
- ملاحظات إصدار GameActivity وAGDK
- استخدام GameTextInput في GameActivity
- دليل نقل بيانات NativeActivity
- المستندات المرجعية لـ GameActivity
- تنفيذ GameActivity:
للإبلاغ عن الأخطاء أو طلب ميزات جديدة في GameActivity، استخدِم أداة تتبُّع مشاكل GameActivity.