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 बिल्ड में नेटिव लाइब्रेरी और सोर्स कोड दिखते हैं.

  1. अपने गेम की build.gradle फ़ाइल में GameActivity लाइब्रेरी डिपेंडेंसी जोड़ने के लिए, Jetpack Android Games पेज पर दिए गए निर्देशों का पालन करें.

  2. Android प्लगिन वर्शन (एजीपी) 4.1 और इसके बाद के वर्शन के साथ, प्रीफ़ैब को चालू करने के लिए यह तरीका अपनाएं:

    • अपने मॉड्यूल की build.gradle फ़ाइल के android ब्लॉक में यह कोड जोड़ें:
    buildFeatures {
        prefab true
    }
    
    android.prefabVersion=2.0.0
    

    अगर एजीपी के पुराने वर्शन इस्तेमाल किए जा रहे हैं, तो कॉन्फ़िगरेशन से जुड़े निर्देशों के लिए, प्रीफ़ैब दस्तावेज़ देखें.

  3. 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 के लिए आपके ऐप्लिकेशन की ज़रूरी जानकारी होती है. इसमें इस तरह का कॉन्टेंट शामिल है:

अपने गेम में GameActivity को लागू करना

  1. अपनी मुख्य गतिविधि वाली Java क्लास बनाएं या उसकी पहचान करें. यह क्लास, आपकी AndroidManifest.xml फ़ाइल में मौजूद activity एलिमेंट में बताई गई क्लास होती है. इस क्लास को बदलें, ताकि com.google.androidgamesdk पैकेज से GameActivity को एक्सटेंड किया जा सके:

    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. अगर आपकी लाइब्रेरी का नाम डिफ़ॉल्ट नाम (libmain.so) नहीं है, तो अपनी नेटिव लाइब्रेरी को AndroidManifest.xml में जोड़ें:

    <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 लाइब्रेरी का अपना वर्शन शामिल होता है. इसलिए, एनडीके रिलीज़ में शामिल वर्शन का इस्तेमाल नहीं किया जा सकता. अगर आपके गेम में एनडीके में शामिल 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;
    }
    
  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. इस बारे में ज़्यादा जानने के लिए, एंडलेस टनल एनडीके के उदाहरण को लागू करने का तरीका देखें. इनमें सबसे बड़ा अंतर यह होगा कि इवेंट को कैसे मैनेज किया जाए. इसके बारे में अगले सेक्शन में बताया गया है.

इवेंट मैनेज करना

इनपुट इवेंट को अपने ऐप्लिकेशन तक पहुंचने की अनुमति देने के लिए, 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 में सेव किया जाता है.

  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);
    }
    

    _cookEventForPointerIndex() और इससे जुड़े अन्य फ़ंक्शन लागू करने के लिए, GitHub सैंपल देखें.

  2. काम पूरा होने के बाद, उन इवेंट की सूची को मिटाना न भूलें जिन्हें आपने अभी-अभी मैनेज किया है:

    android_app_clear_motion_events(mApp);
    

अन्य संसाधन

GameActivity के बारे में ज़्यादा जानने के लिए, यह लेख पढ़ें:

GameActivity में गड़बड़ियों की शिकायत करने या नई सुविधाओं का अनुरोध करने के लिए, GameActivity से जुड़ी समस्या को ट्रैक करने वाले टूल का इस्तेमाल करें.