GameActivity का इस्तेमाल शुरू करना यह Android Game Development Kit का हिस्सा है.
इस गाइड में, अपने Android गेम में GameActivity को सेट अप और इंटिग्रेट करने के साथ-साथ, इवेंट मैनेज करने का तरीका बताया गया है.
GameActivity की मदद से, C या C++ गेम को Android पर लाया जा सकता है. इसके लिए, ज़रूरी एपीआई इस्तेमाल करने की प्रोसेस को आसान बनाया जाता है.
पहले, गेम के लिए NativeActivity क्लास का सुझाव दिया जाता था. गेम के लिए, GameActivity को सुझाए गए क्लास के तौर पर इस्तेमाल किया जाता है और यह एपीआई लेवल 19 के साथ पुराने सिस्टम के साथ काम करने की सुविधा देता है.
GameActivity को इंटिग्रेट करने वाले सैंपल के लिए, games-samples रिपॉज़िटरी देखें.
शुरू करने से पहले
डिस्ट्रिब्यूशन पाने के लिए, GameActivity रिलीज़ देखें.
अपना बिल्ड सेट अप करना
Android पर, Activity आपके गेम के लिए एंट्री पॉइंट के तौर पर काम करता है. साथ ही, यह ड्रॉ करने के लिए Window भी उपलब्ध कराता है. कई गेम, इस Activity को अपनी Java या Kotlin क्लास के साथ बढ़ाते हैं, ताकि JNI कोड का इस्तेमाल करके NativeActivity की सीमाओं को पार किया जा सके. इससे, वे अपने C या C++ गेम कोड को जोड़ पाते हैं.
GameActivity में ये सुविधाएं मिलती हैं:
यह
AppCompatActivityसे इनहेरिट करता है. इससे आपको Android Jetpack आर्किटेक्चर कॉम्पोनेंट इस्तेमाल करने की सुविधा मिलती है.यह
SurfaceViewमें रेंडर होता है. इससे आपको Android के किसी भी अन्य यूज़र इंटरफ़ेस (यूआई) एलिमेंट के साथ इंटरफ़ेस करने की सुविधा मिलती है.इससे Java गतिविधि के इवेंट मैनेज किए जाते हैं. इससे किसी भी Android यूज़र इंटरफ़ेस (यूआई) एलिमेंट (जैसे,
EditText,WebViewयाAd) को C इंटरफ़ेस का इस्तेमाल करके, आपके गेम में इंटिग्रेट किया जा सकता है.यह
NativeActivityऔरandroid_native_app_glueलाइब्रेरी की तरह C API उपलब्ध कराता है.
GameActivity को Android Archive (AAR) के तौर पर डिस्ट्रिब्यूट किया जाता है. इस एएआर में वह Java क्लास शामिल है जिसका इस्तेमाल AndroidManifest.xml में किया जाता है. साथ ही, इसमें C और C++ सोर्स कोड भी शामिल है, जो GameActivity के Java साइड को ऐप्लिकेशन के C/C++ इंप्लिमेंटेशन से कनेक्ट करता है. अगर GameActivity 1.2.2 या इसके बाद के वर्शन का इस्तेमाल किया जा रहा है, तो C/C++ स्टैटिक लाइब्रेरी भी उपलब्ध कराई जाती है. हमारा सुझाव है कि जब भी लागू हो, सोर्स कोड के बजाय स्टैटिक लाइब्रेरी का इस्तेमाल करें.
Prefab की मदद से, इन सोर्स फ़ाइलों या स्टैटिक लाइब्रेरी को अपने बिल्ड प्रोसेस के हिस्से के तौर पर शामिल करें. इससे आपके CMake प्रोजेक्ट या NDK बिल्ड में नेटिव लाइब्रेरी और सोर्स कोड दिखते हैं.
अपने गेम की
build.gradleफ़ाइल मेंGameActivityलाइब्रेरी डिपेंडेंसी जोड़ने के लिए, Jetpack Android Games पेज पर दिए गए निर्देशों का पालन करें.Android प्लगिन वर्शन (एजीपी) 4.1 और इसके बाद के वर्शन के साथ, प्रीफ़ैब को चालू करने के लिए यह तरीका अपनाएं:
- अपने मॉड्यूल की
build.gradleफ़ाइल केandroidब्लॉक में यह कोड जोड़ें:
buildFeatures { prefab true }- Prefab का कोई वर्शन चुनें और उसे
gradle.propertiesफ़ाइल पर सेट करें:
android.prefabVersion=2.0.0अगर एजीपी के पुराने वर्शन इस्तेमाल किए जा रहे हैं, तो कॉन्फ़िगरेशन से जुड़े निर्देशों के लिए, प्रीफ़ैब दस्तावेज़ देखें.
- अपने मॉड्यूल की
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 सिस्टम, आपकी गतिविधि के इंस्टेंस में कोड को एक्ज़ीक्यूट करता है. इसके लिए, वह कॉलबैक के उन तरीकों को कॉल करता है जो गतिविधि पूरी होने की प्रोसेस के खास चरणों से जुड़े होते हैं. Android आपकी गतिविधि को लॉन्च कर सके और आपका गेम शुरू कर सके, इसके लिए आपको Android मेनिफ़ेस्ट में सही एट्रिब्यूट के साथ अपनी गतिविधि का एलान करना होगा. ज़्यादा जानकारी के लिए, गतिविधियों के बारे में जानकारी देखें.
Android मेनिफ़ेस्ट
हर ऐप्लिकेशन प्रोजेक्ट के सोर्स सेट के रूट में, AndroidManifest.xml फ़ाइल होनी चाहिए. मेनिफ़ेस्ट फ़ाइल में, Android बिल्ड टूल, Android ऑपरेटिंग सिस्टम, और Google Play के लिए आपके ऐप्लिकेशन की ज़रूरी जानकारी होती है. इसमें इस तरह का कॉन्टेंट शामिल है:
पैकेज का नाम और ऐप्लिकेशन आईडी, ताकि Google Play पर आपके गेम की पहचान की जा सके.
ऐप्लिकेशन के कॉम्पोनेंट, जैसे कि गतिविधियां, सेवाएं, ब्रॉडकास्ट रिसीवर, और कॉन्टेंट देने वाले.
सिस्टम या अन्य ऐप्लिकेशन के सुरक्षित हिस्सों को ऐक्सेस करने की अनुमतियां.
डिवाइस के साथ काम करने की सुविधा का इस्तेमाल करके, अपने गेम के लिए हार्डवेयर और सॉफ़्टवेयर से जुड़ी ज़रूरी शर्तें तय करें.
GameActivityऔरNativeActivityके लिए नेटिव लाइब्रेरी का नाम (डिफ़ॉल्ट रूप से libmain.so).
अपने गेम में GameActivity को लागू करना
अपनी मुख्य गतिविधि वाली Java क्लास बनाएं या उसकी पहचान करें. यह क्लास, आपकी
AndroidManifest.xmlफ़ाइल में मौजूदactivityएलिमेंट में बताई गई क्लास होती है. इस क्लास को बदलें, ताकिcom.google.androidgamesdkपैकेज सेGameActivityको एक्सटेंड किया जा सके: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"); } ... }अगर आपकी लाइब्रेरी का नाम डिफ़ॉल्ट नाम (
libmain.so) नहीं है, तो अपनी नेटिव लाइब्रेरी कोAndroidManifest.xmlमें जोड़ें:<meta-data android:name="android.app.lib_name" android:value="android-game" />
android_main को लागू करना
android_native_app_glueलाइब्रेरी, एक सोर्स कोड लाइब्रेरी है. इसका इस्तेमाल करके, आपका गेमGameActivityलाइफ़साइकल इवेंट को एक अलग थ्रेड में मैनेज करता है, ताकि आपके मुख्य थ्रेड में रुकावट न आए. लाइब्रेरी का इस्तेमाल करते समय, आपको लाइफ़साइकल इवेंट को मैनेज करने के लिए कॉलबैक को रजिस्टर करना होगा. जैसे, टच इनपुट इवेंट.GameActivityसंग्रह मेंandroid_native_app_glueलाइब्रेरी का अपना वर्शन शामिल होता है. इसलिए, एनडीके रिलीज़ में शामिल वर्शन का इस्तेमाल नहीं किया जा सकता. अगर आपके गेम में एनडीके में शामिलandroid_native_app_glueलाइब्रेरी का इस्तेमाल किया जा रहा है, तो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(); } } }इस बारे में ज़्यादा जानने के लिए, एंडलेस टनल एनडीके के उदाहरण को लागू करने का तरीका देखें. इनमें सबसे बड़ा अंतर यह होगा कि इवेंट को कैसे मैनेज किया जाए. इसके बारे में अगले सेक्शन में बताया गया है.
इवेंट मैनेज करना
इनपुट इवेंट को अपने ऐप्लिकेशन तक पहुंचने की अनुमति देने के लिए, android_app_set_motion_event_filter और android_app_set_key_event_filter का इस्तेमाल करके, इवेंट फ़िल्टर बनाएं और उन्हें रजिस्टर करें.
डिफ़ॉल्ट रूप से, native_app_glue लाइब्रेरी सिर्फ़ SOURCE_TOUCHSCREEN इनपुट से मोशन इवेंट की अनुमति देती है. ज़्यादा जानकारी के लिए, रेफ़रंस दस्तावेज़ और android_native_app_glue को लागू करने का कोड देखें.
इनपुट इवेंट को मैनेज करने के लिए, अपने गेम लूप में android_app_swap_input_buffers() की मदद से android_input_buffer का रेफ़रंस पाएं. इनमें मोशन इवेंट और मुख्य इवेंट शामिल होते हैं. ये इवेंट, पिछली बार पोल किए जाने के बाद हुए होते हैं. इवेंट की संख्या को क्रमशः 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); }_cookEventForPointerIndex()और इससे जुड़े अन्य फ़ंक्शन लागू करने के लिए, GitHub सैंपल देखें.काम पूरा होने के बाद, उन इवेंट की सूची को मिटाना न भूलें जिन्हें आपने अभी-अभी मैनेज किया है:
android_app_clear_motion_events(mApp);
अन्य संसाधन
GameActivity के बारे में ज़्यादा जानने के लिए, यह लेख पढ़ें:
- GameActivity और AGDK के रिलीज़ नोट.
- GameActivity में GameTextInput का इस्तेमाल करें.
- NativeActivity माइग्रेट करने से जुड़ी गाइड.
- GameActivity से जुड़ा रेफ़रंस दस्तावेज़.
- GameActivity लागू करना.
GameActivity में गड़बड़ियों की शिकायत करने या नई सुविधाओं का अनुरोध करने के लिए, GameActivity से जुड़ी समस्या को ट्रैक करने वाले टूल का इस्तेमाल करें.