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

استخدِم الوظائف التالية لإضافة دعم وحدة التحكّم في الألعاب إلى لعبتك باستخدام مكتبة وحدة تحكم الألعاب.

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

استخدام Paddleboat_init لتهيئة مكتبة وحدة التحكم في الألعاب.

Paddleboat_ErrorCode Paddleboat_init(JNIEnv *env, jobject jcontext)

تأخذ Paddleboat_init معلمتين:

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

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

يمكنك استخدام Paddleboat_isInitialized للتحقّق مما إذا كانت اللعبة تم إعداد مكتبة وحدة التحكم بنجاح. يُرجع قيمة منطقية إذا كانت القيمة هي true، تكون واجهة برمجة التطبيقات متاحة للاستخدام.

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	مؤشر اختياري (قد يكون "خالٍ") للمستخدم بيانات محددة محددة في آخر طلب Paddleboat_setControllerStatusCallback

طلب وظيفة تحديث مكتبة "وحدة تحكّم الألعاب"

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

void Paddleboat_update(JNIEnv *env)

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

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

تتوافق مكتبة "وحدة التحكّم في الألعاب" مع نوعَين من أحداث الإدخال: 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 تسترد الدالة اسم جهاز وحدة التحكم.
• Paddleboat_getControllerInfo بيانات حول جهاز وحدة التحكم نفسه.
• Paddleboat_getControllerData تسترد الدالة الحالة الحالية لمدخلات وحدة التحكم.

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

Paddleboat_getControllerName function تأخذ معلمتين للإدخال: فهرس وحدة التحكم، وحجم المخزن المؤقت، ومؤشر إلى مخزن مؤقت لتخزين سلسلة اسم وحدة التحكم. يتم تنسيق سلسلة الاسم سلسلة 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 function مَعلمتَي إدخال: a فهرس وحدة التحكم ومؤشر إلى بنية 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 معلمتي إدخال: a فهرس وحدة التحكم ومؤشر إلى بنية Paddleboat_Controller_Data. في حال حذف تمت تعبئة Paddleboat_Controller_Data بالبيانات بنجاح، تعرض Paddleboat_getControllerInfo القيمة 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 إلى عرض/ارتفاع النافذة (بالبكسل)

ملاحظة: تدعم معظم وحدات التحكم، وليس جميعها، النطاقات التناظرية للزر L2/R2. بعض الإشعارات تحتوي وحدات التحكّم على أزرار رقمية من النوع L2/R2، وتعرض إما 0.0 أو 1.0. تشير رسالة الأشكال البيانية تكون المشغلات L1/R1 رقمية بشكل عام وتبلّغ إما عن 0.0 أو 1.0، على الرغم من أن يتم الإبلاغ عن النطاقات التناظرية إذا كانت معتمدة من قبل وحدة التحكم. ستستخدم المشغلات أيضًا اضبط أقنعة بت للزر عند الضغط عليه (بعبارة أخرى، PADDLEBOAT_BUTTON_L1).

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

عضو في الهيكل	الوصف
buttonsDown	مصفوفة حقل بت لكل زر Bit-per-button. قناع بت للزر يتم تحديد الثوابت في paddlebucket.h. ملف الرأس وتبدأ PADDLEBOAT_BUTTON_
timestamp.	الطابع الزمني لأحدث إدخال لعناصر التحكّم فعالية. يبلغ الطابع الزمني بالميكرو ثانية منذ حقبة الساعة.
virtualPointer	موقع المؤشر الافتراضي لا يكون صالحًا إلا إذا كانت علم واحد (PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE) تم ضبطها في controllerFlags، وإلا سيتم 0.0, 0.0