GameActivity ব্যবহার শুরু করুন   Android Game Development Kit-এর অংশ।

এই নির্দেশিকায় আপনার Android গেমে কীভাবে GameActivity সেট-আপ ও ইন্টিগ্রেট করতে এবং ইভেন্ট ম্যানেজ করতে হয় তা বর্ণনা করা হয়েছে।

GameActivity আপনাকে গুরুত্বপূর্ণ API ব্যবহার করার প্রসেস সহজ করে আপনার C বা C++ গেম Android-এ আনতে সাহায্য করে। আগে NativeActivity গেমের জন্য সাজেস্ট করা ক্লাস ছিল। গেমের জন্য সাজেস্ট করা ক্লাস হিসেবে GameActivity এটি পরিবর্তন করে এবং API লেভেল ১৯-এর ব্যাকওয়ার্ড কম্প্যাটিবল।

GameActivity ইন্টিগ্রেট করে এমন স্যাম্পেলের জন্য, games-samples রিপোজিটরি দেখুন।

শুরু করার আগে

ডিস্ট্রিবিউশন পেতে GameActivity রিলিজ দেখুন।

আপনার বিল্ড সেট-আপ করুন

Android-এ, Activity আপনার গেমের এন্ট্রি পয়েন্ট হিসেবে কাজ করে এবং এর মধ্যে ড্র করার জন্য Window প্রদান করে। অনেক গেম NativeActivity-এ সীমাবদ্ধতা দূর করতে JNI কোড ব্যবহার করে তাদের C বা C++ গেম কোডের সাথে ব্রিজ করার সময় তাদের নিজস্ব Java বা Kotlin ক্লাসের সাথে এই Activity বাড়ায়।

GameActivity নিম্নলিখিত ক্ষমতা অফার করে:

  • AppCompatActivity থেকে ইনহেরিট করে, যা আপনাকে Android Jetpack আর্কিটেকচার কম্পোনেন্ট ব্যবহার করতে দেয়।

  • এটি একটি SurfaceView-এ রেন্ডার করে যা আপনাকে অন্য যেকোনও Android UI এলিমেন্টের সাথে ইন্টারফেস করতে দেয়।

  • Java অ্যাক্টিভিটি ইভেন্ট ম্যানেজ করে। এটি যেকোনও Android UI এলিমেন্টকে (যেমন, EditText, WebView বা Ad) C ইন্টারফেস ব্যবহার করে আপনার গেমে ইন্টিগ্রেট করার অনুমতি দেয়।

  • NativeActivity-এর মতো C API অফার করে এবং android_native_app_glue লাইব্রেরি।

GameActivity Android Archive (AAR) হিসেবে ডিস্ট্রিবিউট করা হয়। এই 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 প্লাগ-ইন ভার্সন (AGP) 4.1+-এর সাথে নিম্নলিখিত কাজগুলি করে প্রিফ্যাব চালু করুন:

    • আপনার মডিউলের build.gradle ফাইলের android ব্লকে নিম্নলিখিতগুলি যোগ করুন:
    buildFeatures {
        prefab true
    }
    
    android.prefabVersion=2.0.0
    

    আপনি AGP-এর আগের ভার্সন ব্যবহার করলে, প্রিফ্যাব ডকুমেন্টেশন থেকে সংশ্লিষ্ট কনফিগারেশন সংক্রান্ত নির্দেশাবলী অনুসরণ করুন।

  3. আপনার প্রোজেক্টে C/C++ স্ট্যাটিক লাইব্রেরি অথবা C/++ সোর্স কোড ইমপোর্ট করতে নিচের ধাপগুলি অনুসরণ করুন।

    স্ট্যাটিক লাইব্রেরি

    আপনার প্রোজেক্টের CMakeLists.txt ফাইলে, game-activity_static প্রিফ্যাব মডিউলে game-activity স্ট্যাটিক লাইব্রেরি ইমপোর্ট করুন:

    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 Manifest

প্রতিটি অ্যাপ প্রোজেক্টের প্রোজেক্ট সোর্স সেটের রুটে AndroidManifest.xml ফাইল থাকতেই হবে। ম্যানিফেস্ট ফাইল Android বিল্ড টুল, Android অপারেটিং সিস্টেম এবং Google Play-এর জন্য আপনার অ্যাপ সম্পর্কে প্রয়োজনীয় তথ্য বর্ণনা করে। এর মধ্যে রয়েছে:

আপনার গেমে GameActivity প্রয়োগ করুন

  1. আপনার প্রধান অ্যাক্টিভিটি জাভা ক্লাস (আপনার 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 লাইব্রেরির নিজস্ব ভার্সন অন্তর্ভুক্ত থাকে, তাই আপনি NDK রিলিজে অন্তর্ভুক্ত ভার্সন ব্যবহার করতে পারবেন না। আপনার গেম যদি NDK-তে অন্তর্ভুক্ত 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-এ উল্লেখ করা অ্যাপ সাইকেল ইভেন্ট পোলিং ও ম্যানেজ করা। যেমন, নিম্নলিখিত স্নিপেট NativeAppGlueAppCmd হ্যান্ডলার হিসেবে _hand_cmd_proxy ফাংশন রেজিস্টার করে, তারপর অ্যাপ সাইকেল ইভেন্ট পোল করে এবং প্রসেস করার জন্য রেজিস্টার করা হ্যান্ডলারে (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. আরও জানতে, Endless Tunnel NDK উদাহরণের প্রয়োগ সম্পর্কে পড়ুন। মূল পার্থক্যটি হবে পরবর্তী বিভাগে দেখানো ইভেন্টগুলি কীভাবে পরিচালনা করা যায়।

ইভেন্ট ম্যানেজ করা

আপনার অ্যাপে ইনপুট ইভেন্ট পৌঁছানোর সুবিধা চালু করতে, 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 ইস্যু ট্র্যাকার ব্যবহার করুন।