GameActivity هي مكتبة Jetpack مصمَّمة لمساعدة ألعاب Android في معالجة أوامر دورة حياة التطبيق وأحداث الإدخال وإدخال النصوص في رمز C/C++ الخاص بالتطبيق. GameActivity هو عنصر فرعي مباشر من
NativeActivity ويشترك معه في بنية مشابهة:
كما هو موضّح في الرسم البياني أعلاه، تنفّذ GameActivity الوظائف التالية:
التفاعل مع إطار عمل Android من خلال المكوّن من جهة Java
تمرير أوامر دورة حياة التطبيق وأحداث الإدخال والنص المُدخَل إلى الجانب الأصلي
تصميم رمز المصدر C/C++ في ثلاثة مكونات منطقية:
وظائف JNI في GameActivity التي تتيح مباشرةً وظائف Java في GameActivity وتضيف الأحداث إلى قائمة الانتظار في native_app_glue.
native_app_glue، الذي يتم تشغيله في الغالب في سلسلة التعليمات الأصلية الخاصة به
(تختلف عن سلسلة التعليمات الرئيسية للتطبيق)، وينفّذ المهام باستخدام
حلقة الرسائل الخاصة به.
رمز اللعبة الخاص بالتطبيق، والذي يستطلع الأحداث التي تم وضعها في قائمة الانتظار داخل native_app_glue ويعالجها، وينفّذ رمز اللعبة ضمن سلسلة المحادثات native_app_glue
باستخدام GameActivity، يمكنك التركيز على تطوير الألعاب الأساسية وتجنُّب إضاعة الكثير من الوقت في التعامل مع رمز JNI.
إذا كنت معتادًا على استخدام NativeActivity، إليك الاختلافات الرئيسية بين GameActivity وNativeActivity:
يتم عرض GameActivity في SurfaceView، ما يسهّل على الألعاب التفاعل مع عناصر واجهة المستخدم الأخرى.
بالنسبة إلى أحداث إدخال اللمس والمفاتيح، تتضمّن GameActivity عملية تنفيذ جديدة تمامًا باستخدام واجهة android_input_buffer، منفصلة عن InputQueue التي تستخدمها NativeActivity.
GameActivity هي فئة مشتقة من AppCompatActivity، ما يتيح لك استخدام مكوّنات Jetpack الأخرى بسلاسة.
ActionBar وFragment وغيرهما
كلها متاحة.
من المتوقّع أن تنشئ التطبيقات المشتقة من GameActivity جميع أجزاء رمز C/C++ في مكتبة واحدة. من ناحية أخرى، تشكّل دوال JNI الخاصة بـ NativeActivity جزءًا من إطار العمل (يتم تحميلها دائمًا بواسطة نظام التشغيل). وبالتالي، من المتوقّع أن يتم إنشاء native_app_glue ورمز C/C++ للتطبيق في مكتبة واحدة فقط.
NativeActivity هو جزء من إطار عمل Android ويتبع دورة الإصدار (عادةً ما تكون سنوية). GameActivity هو جزء من مكتبة Jetpack، التي تتضمّن دورة إصدار أكثر تكرارًا (عادةً كل أسبوعين)، ويمكن أن تصل الميزات الجديدة وإصلاحات الأخطاء بشكل أسرع.
يتم توفير رمز C/C++ البرمجي كرمز مصدر في جميع قنوات الإصدار، وذلك باستخدام تنسيق
Prefab. يضيف الإصدار 1.2.2 من GameActivity مكتبة ثابتة إلى التوزيع.
اعتبارًا من هذا الإصدار والإصدارات الأحدث، ننصحك باستخدام المكتبة الثابتة بدلاً من رمز المصدر.
محتويات حزمة ZIP الخاصة بمكتبة Jetpack وAGDK
يتم إصدار GameActivity مع ملف AAR باستخدام مكتبة Jetpack وقنوات حزمة AGDK المضغوطة. يحتوي هذا التقرير على المكوّنات الرئيسية التالية:
ملف JAR لرمز Java
يتم تضمين مكتبة C/C++ الثابتة game-activity_static مع الإصدار 1.2.2 والإصدارات الأحدث من GameActivity.
رمز المصدر C/C++ (ضمن المجلد /prefab)
تفترض تعليمات الدمج المرتبطة بهذه الصفحة أنّه يمكنك استخدام Prefab في نظام الإصدار، وإلا يمكنك نسخ الرمز المصدري المعبأ ضمن المجلد prefab/modules/game-activity/include إلى نظام الإصدار واتّخاذ خطوات الدمج اللازمة. تتوفّر بنية ملفات مشابهة للإصدارات ضمن androidx لمكتبة Android Jetpack، وبشكل تلقائي، يفك Gradle حِزم AAR في دليل ذاكرة التخزين المؤقت (~/.gradle/caches/...). يمكنك العثور على رمز المصدر C/C++ من خلال البحث عن prefab/modules/game-activity/include
واختيار الموقع الجغرافي ضمن إصدارك المستهدف.
للحصول على تعليمات حول الدمج باستخدام مكتبة Jetpack، يُرجى الاطّلاع على بدء استخدام GameActivity.
محتوى رمز المصدر لنظام التشغيل AOSP
يتضمّن AOSP دائمًا أحدث رمز مصدر. اتّبِع تعليمات الإنشاء لإنشاء إصداراتك الخاصة أو دمج المصدر مباشرةً في بيئة الإنشاء. يتم حفظ رمز المصدر C/C++ في بنية ملفات مشابهة لتلك الخاصة بمكتبة Jetpack وحزمة AGDK المضغوطة.
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-08-26 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-08-26 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["GameActivity\nPart of [Android Game Development Kit](/games/agdk/overview).\n\n[`GameActivity`](/reference/games/game-activity) is a Jetpack library designed\nto assist Android games in processing app cycle commands, input events, and text\ninput in the application's C/C++ code. `GameActivity` is a direct descendant of\n[`NativeActivity`](/reference/android/app/NativeActivity) and shares a similar\narchitecture:\n\nAs illustrated in the above diagram, `GameActivity` performs the following\nfunctions:\n\n- Interacting with Android framework through the Java-side component.\n- Passing app cycle commands, input events, and input text to the native side.\n- Modelling C/C++ source code into three logical components:\n - GameActivity's JNI functions, which directly support GameActivity's Java functionality and enqueue the events to `native_app_glue`.\n - `native_app_glue`, which runs mostly in its own native thread (different from the application's main thread), and executes tasks with its looper.\n - The application's game code, which polls and processes the events queued inside `native_app_glue` and executes game code within the `native_app_glue` thread.\n\nWith `GameActivity`, you can focus on your core game development and avoid\nspending excessive time dealing with the JNI code.\n\nIf you are already familiar with `NativeActivity`, the major differences\nbetween `GameActivity` and `NativeActivity` are as follows:\n\n- `GameActivity` renders into a [`SurfaceView`](/reference/android/view/SurfaceView), making it much easier for games to interact with other UI components.\n- For touch and key input events, `GameActivity` has a completely new implementation with the [`android_input_buffer`](/reference/games/game-activity/structandroid/input-buffer) interface, separate from the [`InputQueue`](/reference/android/view/InputQueue) that `NativeActivity` uses.\n- `GameActivity` is a derived class of `AppCompatActivity`, which lets you seamlessly use other Jetpack components. [`ActionBar`](/reference/android/app/ActionBar), [`Fragment`](/guide/fragments), and others are all available.\n- `GameActivity` adds text input functionality by integrating [the\n GameTextInput library](/games/agdk/add-support-for-text-input).\n- Apps derived from `GameActivity` are expected to build all three parts of C/C++ code into one library. On the other hand, `NativeActivity`'s JNI functions are a part of the framework (always loaded by OS). Hence, only the `native_app_glue` and application's C/C++ code are expected to be built into one library.\n- `NativeActivity` is a part of Android framework and follows its release cycle (typically yearly). `GameActivity` is a part of the Jetpack library, which has a much more frequent release cycle (typically biweekly); new features and bug fixes can arrive much more quickly.\n\n| **Note:** We strongly recommend using `GameActivity` for new games and other C/C++ intensive applications. If you have an existing `NativeActivity` application, we recommend migrating to `GameActivity`.\n\nRelease locations\n\nThe `GameActivity` library is available in the following channels:\n\n- As a part of the [Android Jetpack library](/jetpack/androidx/releases/games) (recommended)\n- As [AOSP](https://android.googlesource.com/platform/frameworks/opt/gamesdk/) source code\n\nThe C/C++ code is provided as source code in all release channels, using the\n[Prefab](/studio/build/dependencies?agpversion=4.0#native-dependencies-aars)\nformat. GameActivity version 1.2.2 adds a static library to the distribution.\nStarting with this version and later, we recommend you use the static library\ninstead of the source code.\n| **Note:** Most of the documentation on this site is written from the perspective of AndroidX.\n\nContents of Jetpack library and AGDK zip package\n\nWith the Jetpack library and AGDK zip package channels, GameActivity is released\nwith an AAR. This AAR contains the following major components:\n\n- A JAR file for Java code\n- The C/C++static library `game-activity_static` is included with GameActivity version 1.2.2 and later.\n- C/C++ source code (under the `/prefab` folder)\n\nThe integration instructions linked to from this page assume that you can use\nPrefab in your build system; otherwise, you can copy the source code packed\nunder the `prefab/modules/game-activity/include` folder into your build system\nand perform the necessary integration steps. A similar file structure exists for\nthe releases under `androidx` for the Android Jetpack library; by default,\ngradle unpacks AARs in its cache directory (\\~/.gradle/caches/...). You can find\nthe C/C++ source code by searching for `prefab/modules/game-activity/include`\nand picking up the location under your intended release version.\n\nFor instructions on integrating using the Jetpack library, see\n[Get started with GameActivity](/games/agdk/game-activity/get-started).\n\nContent of AOSP source code\n\nAOSP always contains the most recent source code. Follow [the build\ninstructions](https://android.googlesource.com/platform/frameworks/opt/gamesdk/+/refs/heads/master/GameActivity/) to create your own releases or directly integrate the source into\nyour build environment. The C/C++ source code is saved in a file structure\nsimilar to the ones for the Jetpack library and AGDK zip package.\n\nIntegration guides\n\nFollow those guides to integrate `GameActivity` into your applications:\n\n- [Get started](/games/agdk/game-activity/get-started)\n- [Use game text input](/games/agdk/game-activity/use-text-input)\n- [NativeActivity migration guide](/games/agdk/game-activity/migrate-native-activity)\n\nAdditional resources\n\nTo learn more about `GameActivity`, see the following:\n\n- [GameActivity and AGDK release notes](/games/agdk/release-notes).\n- [Use GameTextInput in GameActivity](/games/agdk/game-activity/use-text-input).\n- [NativeActivity migration guide](/games/agdk/game-activity/migrate-native-activity).\n- [GameActivity reference documentation](/reference/games/game-activity/group/game-activity).\n- [GameActivity implementation](https://android.googlesource.com/platform/frameworks/opt/gamesdk/+/refs/heads/master/game-activity/).\n\nFeedback\n\nTo report bugs or request new features to GameActivity, use\n[the GameActivity issue tracker](https://issuetracker.google.com/issues/new?component=897320&template=1456805)."]]
