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 বিল্ড-এ
নেটিভ লাইব্রেরি ও সোর্স কোড দেখায়।
আপনার গেমের
build.gradleফাইলেGameActivityলাইব্রেরি ডিপেন্ডেন্সি যোগ করতে Jetpack Android Games পৃষ্ঠায় দেওয়া নির্দেশাবলী অনুসরণ করুন।Android প্লাগ-ইন ভার্সন (AGP) 4.1+-এর সাথে নিম্নলিখিত কাজগুলি করে প্রিফ্যাব চালু করুন:
- আপনার মডিউলের
build.gradleফাইলেরandroidব্লকে নিম্নলিখিতগুলি যোগ করুন:
buildFeatures { prefab true }- একটি Prefab ভার্সন বেছে নিন,
এবং এটি
gradle.propertiesফাইলে সেট করুন:
android.prefabVersion=2.0.0আপনি AGP-এর আগের ভার্সন ব্যবহার করলে, প্রিফ্যাব ডকুমেন্টেশন থেকে সংশ্লিষ্ট কনফিগারেশন সংক্রান্ত নির্দেশাবলী অনুসরণ করুন।
- আপনার মডিউলের
আপনার প্রোজেক্টে 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-এর জন্য আপনার অ্যাপ সম্পর্কে প্রয়োজনীয় তথ্য বর্ণনা করে। এর মধ্যে রয়েছে:
Google Play-তে আপনার গেম অনন্যভাবে শনাক্ত করতে প্যাকেজের নাম ও অ্যাপ আইডি।
অ্যাপ কম্পোনেন্ট যেমন অ্যাক্টিভিটি, পরিষেবা, ব্রডকাস্ট রিসিভার ও কন্টেন্ট প্রোভাইডার।
সিস্টেমের সুরক্ষিত অংশ বা অন্যান্য অ্যাপ অ্যাক্সেস করার জন্য অনুমতি।
ডিভাইসের মানানসইতা আপনার গেমের জন্য হার্ডওয়্যার এবং সফ্টওয়্যার সংক্রান্ত প্রয়োজনীয়তা নির্দিষ্ট করতে।
GameActivityএবংNativeActivity-এর জন্য নেটিভ লাইব্রেরির নাম (ডিফল্ট হল libmain.so)।
আপনার গেমে GameActivity প্রয়োগ করুন
আপনার প্রধান অ্যাক্টিভিটি জাভা ক্লাস (আপনার
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লাইব্রেরির নিজস্ব ভার্সন অন্তর্ভুক্ত থাকে, তাই আপনি 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; }আপনার প্রধান গেম লুপে
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(); } } }আরও জানতে, 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-এ
যথাক্রমে স্টোর করা আছে।
আপনার গেম লুপে প্রতিটি ইভেন্ট ইটারেট ও ম্যানেজ করুন। এই উদাহরণে, নিম্নলিখিত কোড
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 ইস্যু ট্র্যাকার ব্যবহার করুন।