استخدام مكتبة وحدة تحكّم الألعاب

استخدِم الدوال التالية لإضافة ميزة التوافق مع ذراع التحكّم في الألعاب إلى لعبتك باستخدام مكتبة Game Controller.

إعداد مكتبة ذراع التحكّم في الألعاب ومحوها

استخدِم الدالة Paddleboat_init لتهيئة مكتبة ذراع التحكّم في الألعاب.

Paddleboat_ErrorCode Paddleboat_init(JNIEnv *env, jobject jcontext)

تتطلّب الدالة Paddleboat_init مَعلمتَين:

  • مؤشر إلى JNIEnv مرفق بسلسلة المحادثات الحالية
  • مرجع عنصر jobject JNI إلى فئة مشتقة من Context. أي عنصر فئة مشتق من Context يكون صالحًا، بما في ذلك على سبيل المثال لا الحصر Activity أو NativeActivity أو GameActivity.

تعرض الدالة Paddleboat_init القيمة PADDLEBOAT_NO_ERROR إذا نجحت عملية الإعداد، وإلا يتم عرض رمز خطأ مناسب.

يمكنك استخدام Paddleboat_isInitialized للتحقّق مما إذا تم إعداد مكتبة Game Controller بنجاح. وتعرض قيمة منطقية. إذا كانت القيمة "صحيح"، تكون واجهة برمجة التطبيقات متاحة للاستخدام.

bool Paddleboat_isInitialized()

قبل إنهاء التطبيق، استخدِم الدالة Paddleboat_destroy لإيقاف مكتبة ذراع التحكّم في الألعاب. تتطلب الدالة معلَمة واحدة، وهي مؤشر إلى JNIEnv مرتبط بسلسلة المحادثات الحالية. يمكن الاتصال بـ "Paddleboat_init" مرة أخرى بعد ‎Paddleboat_destroy.

void Paddleboat_destroy(JNIEnv *env)

إعلام المكتبة بحدث يتم في مراحل النشاط

يجب إبلاغ ذراع التحكّم في الألعاب بأحداث مراحل النشاط onStop وonStart. استدعِ الدالتَين Paddleboat_onStop وPaddleboat_onStart من رمز معالجة حدثَي الإيقاف والبدء. تأخذ كلتا الدالتين مَعلمة واحدة: مؤشر إلى JNIEnv مرتبط بسلسلة المحادثات الحالية.

void Paddleboat_onStop(JNIEnv *env)
void Paddleboat_onStart(JNIEnv *env)

تسجيل دالة رد اتصال لحالة وحدة التحكّم أو إزالتها

تستخدم مكتبة ذراع التحكّم في الألعاب دالة استدعاء لحالة وحدة التحكّم لإعلام اللعبة عند توصيل وحدة تحكّم أو فصلها. وتتيح استخدام دالة استدعاء واحدة فقط لحالة وحدة التحكّم في كل مرة.

  • لتسجيل دالة رد اتصال لحالة وحدة التحكّم أو استبدال أي دالة رد اتصال مسجّلة سابقًا بدالة رد اتصال جديدة، يمكنك استدعاء الدالة Paddleboat_setControllerStatusCallback.
  • لإزالة أي دالة استدعاء مسجَّلة حاليًا، مرِّر NULL أو nullptr.
  • المَعلمة userData هي مؤشر اختياري للبيانات التي يحدّدها المستخدم. سيتم تمرير المَعلمة userData إلى دالّة رد الاتصال. يتم الاحتفاظ بهذا المؤشر داخليًا إلى أن يتم تغييره من خلال استدعاء لاحق إلى Paddleboat_setControllerStatusCallback.
void Paddleboat_setControllerStatusCallback(Paddleboat_ControllerStatusCallback
  statusCallback, void *userData)

توقيع دالة رد الاتصال هو:

typedef void (*Paddleboat_ControllerStatusCallback)(
  const int32_t controllerIndex,
  const Paddleboat_ControllerStatus controllerStatus,
  void *userData)
المَعلمة الوصف
controllerIndex فهرس وحدة التحكّم التي بدأت عملية الاستدعاء ستكون القيمة بين 0 و
PADDLEBOAT_MAX_CONTROLLERS - 1
controllerStatus قيمة التعداد PADDLEBOAT_CONTROLLER_JUST_CONNECTED أو
PADDLEBOAT_CONTROLLER_JUST_DISCONNECTED.
userData مؤشر اختياري (قد يكون NULL) إلى بيانات محدّدة من قِبل المستخدم تم تحديدها من خلال آخر استدعاء لـ Paddleboat_setControllerStatusCallback.

طلب دالة تحديث مكتبة ذراع التحكّم في الألعاب

يجب استدعاء دالة تحديث مكتبة ذراع التحكّم في الألعاب، Paddleboat_update ، مرة واحدة لكل إطار في اللعبة، ويُفضَّل أن يكون ذلك بالقرب من بداية الإطار. تتطلب الدالة مَعلمة واحدة، وهي مؤشر إلى JNIEnv مرتبط بسلسلة المحادثات الحالية.

void Paddleboat_update(JNIEnv *env)

معالجة الأحداث

عند تلقّي أحداث الإدخال، يجب أن تعيد لعبتك توجيهها إلى مكتبة ذراع التحكّم في الألعاب لفحصها. تُقيّم مكتبة Game Controller ما إذا كان حدث الإدخال مرتبطًا بأحد الأجهزة المُدارة. تتم معالجة الأحداث من الأجهزة المُدارة واستخدامها.

تتيح مكتبة ذراع التحكّم في الألعاب نوعَين من أحداث الإدخال: أحداث الإدخال AInputEvents وGameActivity.

معالجة AInputEvent

يجب أن تعيد لعبتك توجيه AInputEvents من خلال استدعاء Paddleboat_processInputEvent من رمز معالجة الأحداث.

int32_t Paddleboat_processInputEvent(const AInputEvent *event)

ستعرض الدالة Paddleboat_processInputEvent القيمة 0 إذا تم تجاهل الحدث، والقيمة 1 إذا تمت معالجة الحدث واستهلاكه من خلال مكتبة ذراع التحكّم في الألعاب.

معالجة أحداث GameActivity

إذا كانت لعبتك تستخدم GameActivity، عليك إعادة توجيه الحدثَين GameActivityKeyEvent وGameActivityMotionEvent من خلال استدعاء Paddleboat_processGameActivityKeyInputEvent أو Paddleboat_processGameActivityMotionInputEvent من رمز معالجة الأحداث.

int32_t Paddleboat_processGameActivityKeyInputEvent(const void *event,
                                                    const size_t eventSize)
int32_t Paddleboat_processGameActivityMotionInputEvent(const void *event,
                                                       const size_t eventSize)
المَعلمة الوصف
event مؤشر إلى بنية GameActivityKeyEvent أو GameActivityMotionEvent، حسب الدالة التي يتم استدعاؤها
eventSize حجم بنية الحدث بالبايت التي تم تمريرها في المَعلمة event.

ستُرجع كلتا الدالتين 0 إذا تم تجاهل الحدث و1 إذا تمت معالجة الحدث واستهلاكه من خلال مكتبة ذراع التحكّم في الألعاب.

تتطلّب السمة GameActivity تحديد محور الحركة النشط باستخدام الدالة GameActivityPointerAxes_enableAxis. تعرض الدالة Paddleboat_getActiveAxisMask قناع بت لمحور الحركة النشط حاليًا والذي تستخدمه وحدات التحكّم المتصلة.

uint64_t Paddleboat_getActiveAxisMask()

للاطّلاع على مثال حول كيفية التعامل مع هذا الأمر، يمكنك مراجعة نموذج مكتبة ذراع التحكّم في الألعاب الذي يستخدم GameActivity. يستطلع النموذج قناع المحور النشط ويُعلم GameActivity عند استخدام محور جديد. يتم تنفيذ ذلك في الدالة NativeEngine::CheckForNewAxis().

void NativeEngine::CheckForNewAxis() {
    // Tell GameActivity about any new axis ids so it reports
    // their events
    const uint64_t activeAxisIds = Paddleboat_getActiveAxisMask();
    uint64_t newAxisIds = activeAxisIds ^ mActiveAxisIds;
    if (newAxisIds != 0) {
        mActiveAxisIds = activeAxisIds;
        int32_t currentAxisId = 0;
        while(newAxisIds != 0) {
            if ((newAxisIds & 1) != 0) {
                LOGD("Enable Axis: %d", currentAxisId);
                GameActivityPointerAxes_enableAxis(currentAxisId);
            }
            ++currentAxisId;
            newAxisIds >>= 1;
        }
    }
}

قراءة بيانات وحدات التحكّم

تستخدم مكتبة ذراع التحكّم في الألعاب قيمة فهرس للإشارة إلى ذراع تحكّم معيّنة. تتراوح قيم الفهرس الصالحة بين 0 وPADDLEBOAT_MAX_CONTROLLERS - 1. تحدّد الدالة Paddleboat_getControllerStatus حالة فهرس وحدة تحكّم معيّنة.

Paddleboat_ControllerStatus Paddleboat_getControllerStatus(
  const int32_t controllerIndex)

هناك ثلاث دوال لقراءة المعلومات من وحدة تحكّم متصلة.

اسم وحدة التحكّم

تتطلّب الدالة Paddleboat_getControllerName ثلاث مَعلمات إدخال: فهرس وحدة التحكّم وحجم ذاكرة التخزين المؤقت ومؤشر إلى مخزن مؤقت لتخزين سلسلة اسم وحدة التحكّم. يتم تنسيق سلسلة الاسم كسلسلة C باستخدام ترميز UTF-8. يتم الحصول على اسم الجهاز داخليًا باستخدام InputDevice.getName().

إذا نجحت الدالة Paddleboat_getControllerName في استرداد الاسم، ستعرض PADDLEBOAT_NO_ERROR، وإلا سيتم عرض رمز خطأ مناسب.

Paddleboat_ErrorCode Paddleboat_getControllerName(const int32_t controllerIndex,
                                                  const size_t bufferSize,
                                                  char *controllerName);
المَعلمة الوصف
controllerIndex فهرس وحدة التحكّم التي بدأت عملية الاستدعاء ستكون القيمة بين 0 و
PADDLEBOAT_MAX_CONTROLLERS - 1
bufferSize حجم المخزن المؤقت الذي تم تمريره بواسطة controllerName بالبايت، وسيتم اقتطاع سلسلة الاسم إذا لزم الأمر لتناسب المخزن المؤقت.
controllerName مؤشر إلى مخزن مؤقت بسعة bufferSize بايت لتخزين اسم وحدة التحكّم فيه سيتم تخزين الاسم كسلسلة C باستخدام ترميز UTF-8.

معلومات جهاز التحكّم

تتطلب الدالة Paddleboat_getControllerInfo معلَمتَي إدخال: فهرس وحدة التحكّم ومؤشر إلى بنية Paddleboat_Controller_Info.

إذا تمت تعبئة Paddleboat_Controller_Info بالبيانات بنجاح، تعرض Paddleboat_getControllerInfo القيمة PADDLEBOAT_NO_ERROR، وإلا يتم عرض رمز خطأ مناسب.

Paddleboat_ErrorCode Paddleboat_getControllerInfo(const int32_t controllerIndex,
  Paddleboat_Controller_Info *controllerInfo)

تحتوي بنية Paddleboat_Controller_Info على معلومات خاصة بالجهاز حول وحدة التحكّم.

typedef struct Paddleboat_Controller_Info {
    uint32_t controllerFlags;
    int32_t controllerNumber;
    int32_t vendorId;
    int32_t productId;
    int32_t deviceId;
    Paddleboat_Controller_Thumbstick_Precision leftStickPrecision;
    Paddleboat_Controller_Thumbstick_Precision rightStickPrecision;
} Paddleboat_Controller_Info;

typedef struct Paddleboat_Controller_Thumbstick_Precision {
    float stickFlatX;
    float stickFlatY;
    float stickFuzzX;
    float stickFuzzY;
} Paddleboat_Controller_Thumbstick_Precision;

تتم تعبئة العديد من أعضاء البنية بقيم مأخوذة من InputDevice المرتبط بوحدة التحكّم:

controllerNumber    -   InputDevice.getControllerNumber()
vendorId              - InputDevice.getVendorId()
productId             - InputDevice.getProductId()
deviceId              - InputDevice.getId()
  • تمثّل قيمة stickFlat مدى وضعية الاستلقاء في الوسط. هذه القيمة مفيدة بشكل أساسي لحساب "المنطقة الميتة" التلقائية في المنتصف على الأجهزة التي تتمركز تلقائيًا.
  • تمثّل قيمة stickFuzz نسبة الخطأ المسموح بها، أو مدى انحراف القيمة الحالية عن القيمة الفعلية بسبب الضوضاء والقيود المفروضة على حساسية الجهاز.

يتم تسوية القيمتَين إلى قيمة قصوى للمحور تبلغ 1.0 في أيّ من البُعدَين.

يحتوي العضو controllerFlags على مجموعة من علامات قناع البت الفردية وقيم مجموعة البتات المتعددة.

يؤدي إجراء عملية AND منطقية على controllerFlags باستخدام PADDLEBOAT_CONTROLLER_LAYOUT_MASK إلى الحصول على قيمة يمكن تحويلها إلى تعداد Paddleboat_ControllerButtonLayout. يحدّد هذا التعداد رموز الأزرار والتنسيق الذي تستخدمه وحدة التحكّم.

enum Paddleboat_ControllerButtonLayout {
    //  Y
    // X B
    //  A
    PADDLEBOAT_CONTROLLER_LAYOUT_STANDARD = 0,
    //  △
    // □ ○
    //  x
    PADDLEBOAT_CONTROLLER_LAYOUT_SHAPES = 1,
    //  X
    // Y A
    //  B
    PADDLEBOAT_CONTROLLER_LAYOUT_REVERSE = 2,
    // X Y R1 L1
    // A B R2 L2
    PADDLEBOAT_CONTROLLER_LAYOUT_ARCADE_STICK = 3,
    PADDLEBOAT_CONTROLLER_LAYOUT_MASK = 3
};

تحدّد الثوابت التالية وحدات بت الإمكانات. لتحديد ما إذا كانت وحدة التحكّم تتيح إمكانية معيّنة، يمكنك إجراء عملية AND منطقية للثابت المقابل مقابل controllerFlags. وتعني النتيجة غير الصفرية أنّ وحدة التحكّم تتيح هذه الإمكانية.

PADDLEBOAT_CONTROLLER_FLAG_TOUCHPAD

إذا تم ضبط وحدة البت هذه، يعني ذلك أنّ وحدة التحكّم تحتوي على لوحة لمس مدمجة. إذا تم الضغط على لوحة اللمس، تضبط وحدة التحكّم البت PADDLEBOAT_BUTTON_TOUCHPAD في الحقل Paddleboat_Controller_Data.buttonsDown.

PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE

إذا تم ضبط وحدة التحكّم على هذه العلامة، فإنّها تحاكي جهاز تأشير. يتم ملء العضو virtualPointer في بنية Paddleboat_Controller_Data بالإحداثيات الحالية للمؤشر الافتراضي.

بيانات مسؤول التحكّم بالبيانات

تتطلب الدالة Paddleboat_getControllerData معلَمتَي إدخال: فهرس وحدة التحكّم ومؤشر إلى بنية Paddleboat_Controller_Data. إذا تمت تعبئة Paddleboat_Controller_Data بالبيانات بنجاح، تعرض الدالة Paddleboat_getControllerData القيمة PADDLEBOAT_NO_ERROR، وإلا يتم عرض رمز خطأ مناسب.

Paddleboat_ErrorCode Paddleboat_getControllerData(const int32_t controllerIndex,
  Paddleboat_Controller_Data *controllerData)

تحتوي البنية Paddleboat_Controller_Data على قيم إدخال التحكّم الحالية لوحدة التحكّم.

typedef struct Paddleboat_Controller_Data {
    uint64_t timestamp;
    uint32_t buttonsDown;
    Paddleboat_Controller_Thumbstick leftStick;
    Paddleboat_Controller_Thumbstick rightStick;
    float triggerL1;
    float triggerL2;
    float triggerR1;
    float triggerR2;
    Paddleboat_Controller_Pointer virtualPointer;
} Paddleboat_Controller_Data;

typedef struct Paddleboat_Controller_Pointer {
    float pointerX;
    float pointerY;
} Paddleboat_Controller_Pointer;

typedef struct Paddleboat_Controller_Thumbstick {
    float stickX;
    float stickY;
} Paddleboat_Controller_Thumbstick;

نطاقات القيم

نوع الإدخال نطاق القيمة
محور عصا التحكّم بالإبهام من -1.0 إلى 1.0
العوامل التي تؤدي إلى الظهور من 0.0 إلى 1.0
المؤشرات الافتراضية ‫0.0 إلى عرض/ارتفاع النافذة (بالبكسل)

تفاصيل البنية

عضو في البنية الوصف
buttonsDown مصفوفة حقول بت لكل زر يتم تحديد ثوابت قناع البت للأزرار في ملف العنوان paddleboat.h وتبدأ بـ PADDLEBOAT_BUTTON_.
timestamp الطابع الزمني لآخر حدث إدخال لوحدة التحكّم الطابع الزمني هو ميكروثانية منذ حقبة الساعة.
virtualPointer الموقع الجغرافي للمؤشر الافتراضي لا تكون هذه السمة صالحة إلا إذا تم ضبط العلامة PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE في controllerFlags، وإلا ستكون 0.0, 0.0.