نقل البيانات من NativeActivity   جزء من حزمة تطوير ألعاب Android.

توضّح هذه الصفحة كيفية نقل البيانات من NativeActivity إلى GameActivity في مشروع لعبة Android.

تستند GameActivity إلى NativeActivity من إطار عمل Android، مع تحسينات وميزات جديدة:

  • يتيح استخدام Fragment من Jetpack.
  • إضافة دعم TextInput لتسهيل دمج لوحة المفاتيح الافتراضية
  • يتعامل مع أحداث اللمس والمفاتيح في فئة Java GameActivity بدلاً من واجهة 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. أضِف تبعية GameActivity إلى تطبيقك:

    1. أضِف المكتبتَين core وgames-activity.
    2. إذا كان الحد الأدنى الحالي لمستوى واجهة برمجة التطبيقات المتوافق أقل من 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>
    

    للحصول على تعليمات مفصّلة حول وضع ملء الشاشة، يُرجى الاطّلاع على دليل وضع ملء الشاشة ومثال على التنفيذ في مستودع نماذج الألعاب.

لا يغيّر دليل نقل البيانات هذا اسم المكتبة المجمّعة من رموز برمجية أصلية. إذا غيّرت الاسم، تأكَّد من أنّ أسماء المكتبات المجمّعة من رموز برمجية أصلية متّسقة في المواقع الثلاثة التالية:

  • رمز 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.

يوفّر تنفيذ GameActivity بلغة C/C++‎ إصدارًا من الرمز المصدري. بالنسبة إلى الإصدار 1.2.2 والإصدارات الأحدث، يتم توفير إصدار مكتبة ثابت. تُعدّ المكتبة الثابتة نوع الإصدار المقترَح.

يتم تجميع الإصدار داخل ملف AAR باستخدام الأداة المساعدة prefab. وتتضمّن الرموز البرمجية الأصلية مصادر C/C++‎ في GameActivity ورمز native_app_glue. ويجب إنشاؤها مع رمز C/C++‎ الخاص بتطبيقك.

يستخدم تطبيقان (NativeActivity) رمز native_app_glue المُضمَّن في NDK. يجب استبدالها بإصدار GameActivity من native_app_glue. بخلاف ذلك، تنطبق جميع خطوات cmake الموثَّقة في دليل البدء:

  • استورِد مكتبة 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)
    
  • أزِل جميع الإشارات إلى رمز 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 تسمية مثيل Java GameActivity.

خطوات إضافية

تغطي الخطوات السابقة وظائف NativeActivity، ولكن يتضمن GameActivity ميزات إضافية قد ترغب في استخدامها:

ننصحك باستكشاف هذه الميزات واستخدامها بما يتناسب مع ألعابك.

إذا كانت لديك أي أسئلة أو اقتراحات بشأن GameActivity أو مكتبات AGDK الأخرى، يُرجى إنشاء خطأ لإعلامنا بذلك.