بدء استخدام GameActivity   جزء من حزمة تطوير ألعاب Android

يوضّح هذا الدليل كيفية إعداد GameActivity ودمجها والتعامل مع الأحداث في لعبة Android.

تساعدك حزمة GameActivity في نقل لعبتك المكتوبة بلغة C أو C++‎ إلى نظام Android من خلال تبسيط عملية استخدام واجهات برمجة التطبيقات المهمة. في السابق، كانت الفئة NativeActivity هي الفئة المقترَحة للألعاب. ويحلّ محلّه GameActivity كفئة يُنصح بها للألعاب، وهو متوافق مع الأنظمة القديمة حتى المستوى 19 من واجهة برمجة التطبيقات.

للحصول على نموذج يدمج GameActivity، يُرجى الاطّلاع على مستودع نماذج الألعاب.

قبل البدء

يمكنك الاطّلاع على إصدارات GameActivity للحصول على توزيع.

إعداد الإصدار

على Android، يُعدّ Activity نقطة الدخول للعبتك، كما يوفّر Window للرسم بداخله. توسّع العديد من الألعاب Activity هذه باستخدام فئة Java أو Kotlin الخاصة بها لتجاوز القيود في NativeActivity أثناء استخدام رمز JNI للربط برمز لعبة C أو C++‎.

يوفّر GameActivity الإمكانات التالية:

يتم توزيع "GameActivity" كـ أرشيف Android ‏(AAR). يحتوي ملف AAR هذا على فئة Java التي تستخدمها في AndroidManifest.xml، بالإضافة إلى الرمز المصدر C وC++‎ الذي يربط جانب Java من GameActivity بتنفيذ C/C++‎ في التطبيق. إذا كنت تستخدم الإصدار 1.2.2 من GameActivity أو إصدارًا أحدث، يتم أيضًا توفير مكتبة C/C++‎ الثابتة. ننصحك باستخدام المكتبة الثابتة بدلاً من الرمز المصدر، متى أمكن ذلك.

يمكنك تضمين ملفات المصدر هذه أو المكتبة الثابتة كجزء من عملية الإنشاء من خلال Prefab، ما يؤدي إلى عرض المكتبات المجمّعة من رموز برمجية أصلية والرمز المصدر في مشروع CMake أو إصدار NDK.

  1. اتّبِع التعليمات الواردة في صفحة ألعاب Jetpack Android لإضافة تبعية مكتبة GameActivity إلى ملف build.gradle الخاص بلعبتك.

  2. يمكنك تفعيل Prefab من خلال تنفيذ ما يلي باستخدام الإصدار 4.1 من المكوّن الإضافي المتوافق مع Android أو الإصدارات الأحدث:

    • أضِف ما يلي إلى قسم android في ملف build.gradle الخاص بالوحدة:
    buildFeatures {
        prefab true
    }
    
    android.prefabVersion=2.0.0
    

    إذا كنت تستخدم إصدارات أقدم من "مكوّن Android الإضافي لبرنامج Gradle"، اتّبِع مستندات prefab للحصول على تعليمات الإعداد المتوافقة.

  3. استورِد مكتبة C/C++‎ الثابتة أو الرمز المصدر C/++‎ إلى مشروعك على النحو التالي.

    مكتبة ثابتة

    في ملف CMakeLists.txt الخاص بمشروعك، استورِد مكتبة game-activity الثابتة إلى وحدة prefab 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 الرمز البرمجي في مثيل النشاط من خلال استدعاء طرق رد الاتصال التي تتوافق مع مراحل معيّنة من مراحل النشاط. لكي يتمكّن Android من تشغيل نشاطك وبدء لعبتك، عليك الإعلان عن نشاطك باستخدام السمات المناسبة في ملف بيان Android. لمزيد من المعلومات، يُرجى الاطّلاع على مقدمة عن الأنشطة.

ملف بيان Android

يجب أن يتضمّن كل مشروع تطبيق ملف AndroidManifest.xml في جذر مجموعة رموز المصدر للمشروع. يصف ملف البيان معلومات أساسية عن تطبيقك لأدوات إصدار 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 في سلسلة تعليمات منفصلة لمنع حظر سلسلة التعليمات الرئيسية. عند استخدام المكتبة، يتم تسجيل دالة الاستدعاء لمعالجة الأحداث التي تتم في مراحل النشاط، مثل أحداث الإدخال باللمس. يتضمّن أرشيف 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 في حلقة الألعاب الرئيسية، مثل الاستطلاع والتعامل مع أحداث دورة التطبيق المحدّدة في 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() في حلقة الألعاب. وتحتوي هذه على أحداث الحركة والأحداث الرئيسية التي حدثت منذ آخر مرة تم فيها الاستطلاع. يتم تخزين عدد الأحداث المضمّنة في motionEventsCount وkeyEventsCount على التوالي.

  1. كرِّر كل حدث في حلقة الألعاب وتعامل معه. في هذا المثال، يُكرّر الرمز التالي 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.