ترقية حزمة تطوير البرامج (SDK) لإدخالات Java وKotlin إلى الإصدار 1.1

يوضّح هذا الدليل كيفية ترقية لعبتك من الإصدار 1.0.0-beta Input SDK لJava وKotlin إلى الإصدار 1.1.1-beta. اطّلِع على دليل ترقية Unity للحصول على تعليمات محدّدة حول Unity.

ملاحظات الإصدار

تتيح ميزة "ألعاب Google Play على الكمبيوتر" إعادة ربط عناصر التحكّم في لوحة المفاتيح استنادًا إلى عمليات ربط المفاتيح التي تقدّمها لعبتك باستخدام حزمة تطوير البرامج (SDK) Input.

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

يربط تطبيق "ألعاب Google Play على الكمبيوتر" كل إدخال يعيد المستخدم ربطه بالإعدادات التلقائية لإدخال اللعبة. بهذه الطريقة، لن تحتاج لعبتك إلى معرفة أنّ اللاعب قد أعاد ربط عناصر التحكم. إذا كنت بحاجة إلى معرفة الإدخال الجديد لإجراء داخل اللعبة، مثل عرض عناصر التحكّم في لوحة المفاتيح في لعبتك، يمكنك اختياريًا تسجيل دالة استدعاء لتلقّي إشعارات بشأن أحداث إعادة الربط.

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

لست بحاجة إلى ترقية حزمة تطوير البرامج (SDK) الخاصة بإدخال البيانات لتفعيل إعادة تعيين المفاتيح في لعبتك، ولكن يمكن إيقاف إعادة التعيين في لعبتك إذا تم رصد إعداد غير متوافق.

إذا كنت تريد التحكّم في تجربة إعادة ربط الإدخال، أو إذا كانت ميزة إعادة الربط متوقفة في لعبتك، اتّبِع الخطوات التالية لحلّ المشكلة:

  • يجب الترقية إلى الإصدار 1.1.1-beta من حزمة تطوير البرامج (SDK) Input.
  • عدِّل أي عمليات ربط مفاتيح لتجنُّب استخدام الإعدادات غير المتوافقة.
  • عليك تحديث InputMap لتفعيل ميزة إعادة الربط .

إذا كنت تريد إيقاف ميزة إعادة الربط في لعبتك مع مواصلة عرض الإصدار للقراءة فقط من عمليات ربط المفاتيح، اتّبِع الخطوات التالية:

  • يجب الترقية إلى الإصدار 1.1.1-beta من حزمة تطوير البرامج (SDK) Input.
  • عدِّل InputMap لضبط ميزة إعادة الربط على متوقف.

يمكنك ترقية إصدار حزمة تطوير البرامج (SDK) الخاصة بإدخال البيانات إلى 1.1.1-beta للاستفادة من ميزات إعادة الربط المتقدّمة في "ألعاب Google Play" على الكمبيوتر الشخصي باستخدام InputContexts لتحديد عناصر التحكّم في مختلف مَشاهد لعبتك، وإضافة طلبات استدعاء للاستماع إلى أحداث إعادة الربط، وتحديد مجموعة من المفاتيح المحجوزة التي لا يمكن للمستخدم إعادة ربطها، وإيقاف ميزة إعادة الربط لكل من InputAction أو InputGroup أو InputMap.

يُرجى مراعاة الاستثناءات التالية أثناء الترقية إلى إصدار حزمة SDK الجديد:

الإعدادات غير المتوافقة

تكون ميزة إعادة ربط الإدخال غير مفعَّلة في حال عدم استيفاء الشروط التالية:

  • يجب أن يتألّف InputAction الذي يستخدم مفاتيح متعددة من مفتاح تعديل ومفتاح غير مفتاح تعديل. على سبيل المثال، Shift + A صالح، ولكن A + B وCtrl + Alt وShift + A + Tab غير صالحة.

  • لا يمكن أن يتشارك عنصران أو أكثر من InputAction أو InputGroup الرقم التعريفي الفردي نفسه.

ترقية

إنّ الإصدار التجريبي من حزمة Input SDK 1.1.1 متوافق مع الإصدارات القديمة من حزمة Input SDK 1.0.0-beta. إنّ الألعاب التي تستخدم عمليات التنفيذ السابقة من حزمة تطوير البرامج (SDK) لعناصر التحكم في الأجهزة لا تزال تتيح إعادة الربط الأساسية، ما لم تستخدم إعدادًا غير متوافق. إذا كانت لعبتك تستخدم إصدارًا سابقًا من حزمة تطوير البرامج (SDK) Input، ننصحك بقراءة دليل الترقية من الإصدار 0.0.4 إلى الإصدار التجريبي 1.0.0.

تتيح الترقية إلى الإصدار التجريبي 1.1.1 ميزات جديدة، بما في ذلك:

التبعية للترقية

إذا كنت تستخدِم Gradle لاستيراد حزمة تطوير البرامج (SDK) Input، عليك الترقية إلى أحدث إصدار:

// build.gradle
dependencies {
   ...
   implementation 'com.google.android.libraries.play.games:inputmapping:1.1.1-beta'
   ...
}

تحديد الحقول الثابتة

بالنسبة إلى الإصدار 1.1.1-beta، من الممارسات الجيدة تعريف عناصر InputAction وInputGroup وInputContext وInputMap على أنّها حقول static في فئة InputMappingProvider لأنّه يمكن الوصول إلى هذه الحقول من أجزاء أخرى من تطبيقك:

Kotlin

class InputSDKProvider : InputMappingProvider {
    override fun onProvideInputMap(): InputMap { return gameInputMap }

    companion object {
        const val INPUTMAP_VERSION = "1.0.0"

        private val moveUpInputAction = InputAction.create(...)
        private val movementInputGroup = InputGroup.create(...)
        val menuContext = InputContext.create(...)
        val gameInputMap = InputMap.create(...)
    }
}

Java

public class MyInputMappingProvider implements InputMappingProvider {
    private static final String INPUTMAP_VERSION = "1.0.0";

    private static final InputAction moveUpInputAction =
        InputAction.create(...);
    private static final InputGroup movementInputGroup = InputGroup.create(...);
    public static final InputContext menuContext = InputContext.create(...);
    public static final InputMap gameInputMap = InputMap.create(...);

    @Override
    public InputMap onProvideInputMap() {
        return gameInputMap;
    }
}

تعديل InputActions

تم إيقاف استخدام الطريقة InputAction.create() لحزمة تطوير البرامج (SDK) 1.0.0-beta. يحتوي InputAction الآن على معرّف إصدار ويمكن وضع علامة عليه تفيد بأنّه قابل للإعادة التعيين أو لا. إنّ InputAction التي تم تحديدها باستخدام 1.0.0-beta create() في حزمة تطوير البرامج (SDK) لنظام الإدخال يمكن إعادة تعيينها تلقائيًا ولا تتضمّن معلومات تتعلّق بالإصدار:

InputAction في حزمة تطوير البرامج (SDK) Input SDK 1.0.0-beta

Kotlin

val jumpInputAction = InputAction.create(
    "Jump",
    InputEventIds.JUMP.id,
    InputControls.create(
        listOf(KeyEvent.KEYCODE_SPACE),
        emptyList()
    )
)

Java

InputAction moveUpInputAction = InputAction.create(
    "Move Up",
    InputEventIds.MOVE_UP.ordinal(),
    InputControls.create(
        Collections.singletonList(KeyEvent.KEYCODE_W),
        Collections.emptyList()
    )
);

InputAction في الإصدار التجريبي من حزمة تطوير البرامج (SDK) Input SDK 1.1.1

Kotlin

companion object {
  private val moveUpInputAction = InputAction.create(
    "Move Up",
    InputActionsIds.DRIVE.ordinal.toLong(),
    InputControls.create(listOf(KeyEvent.KEYCODE_W), emptyList()),
    InputEnums.REMAP_OPTION_ENABLED) // This action is remappable
}

Java

private static final InputAction moveUpInputAction = InputAction.create(
    "Move Up",
    InputEventIds.MOVE_UP.ordinal(),
    InputControls.create(
            Collections.singletonList(KeyEvent.KEYCODE_W),
            Collections.emptyList()),
    InputEnums.REMAP_OPTION_ENABLED // this action is remappable
);

InputAction في الإصدار التجريبي من حزمة تطوير البرامج (SDK) Input SDK 1.1.1 (مع سلسلة الإصدار)

Kotlin

private val enterMenuInputAction = InputAction.create(
    "Enter menu",
    InputControls.create(listOf(KeyEvent.KEYCODE_ENTER), emptyList()),
    InputIdentifier.create(
    INPUTMAP_VERSION, InputActionsIds.ENTER_MENU.ordinal.toLong()),
    InputEnums.REMAP_OPTION_ENABLED
)

Java

private static final InputAction moveUpInputAction = InputAction.create(
    "Move Up",
    InputControls.create(
            Collections.singletonList(KeyEvent.KEYCODE_W),
            Collections.emptyList()),
    InputIdentifier.create(
            INPUTMAP_VERSION,
            InputEventIds.MOVE_UP.ordinal()),
    InputEnums.REMAP_OPTION_ENABLED // this action is remappable
);

لمزيد من المعلومات عن تحديد إصدارات عمليات ربط المفاتيح، يُرجى الاطّلاع على مقالة تتبُّع أرقام تعريف المفاتيح.

تعديل InputGroups

في حزمة SDK لنظام الإدخال 1.1.1-beta، عليك تحديد كل InputGroup بشكل فريد. ينتمي كل InputAction إلى InputGroup، وهو مجموعة من الإجراءات ذات الصلة. ويؤدي ذلك إلى تحسين التنقّل في عناصر التحكّم وقابلية العثور عليها أثناء اللعب. بالطريقة نفسها التي يجب أن يكون بهاInputAction معرّف فريد بين جميع الإجراءات فيInputContext واحد، يجب أن يكون InputGroup معرّفًا فريدًا في المجموعات الحالية.

في الأمثلة الواردة في هذا القسم، تحتوي اللعبة على عنصرَي InputContext يمثّلان القائمة الرئيسية وأسلوب اللعب. يتم تتبُّع المعرّفات المناسبة لكل InputGroup في هذه السياقات باستخدام التعداد التالي:

Kotlin

enum class InputGroupsIds {
    // Main menu scene
    BASIC_NAVIGATION, // WASD, Enter, Backspace
    MENU_ACTIONS, // C: chat, Space: quick game, S: store
    // Gameplay scene
    BASIC_MOVEMENT, // WASD, space: jump, Shift: run
    MOUSE_ACTIONS, // Left click: shoot, Right click: aim
    EMOJIS, // Emojis with keys 1,2,3,4 and 5
    GAME_ACTIONS, // M: map, P: pause, R: reload
}

Java

public enum InputGroupsIds {
    // Main menu scene
    BASIC_NAVIGATION, // WASD, Enter, Backspace
    MENU_ACTIONS, // C: chat, Space: quick game, S: store
    // Gameplay scene
    BASIC_MOVEMENT, // WASD, space: jump, Shift: run
    MOUSE_ACTIONS, // Left click: shoot, Right click: aim
    EMOJIS, // Emojis with keys 1,2,3,4 and 5
    GAME_ACTIONS, // M: map, P: pause, R: reload
}

مثل InputAction، تم إيقاف طريقة InputGroup.create() لواجهة برمجة التطبيقات Input SDK 1.0.0-beta نهائيًا. يجب تعديل InputGroup في لعبتك بإضافة معرّف إصدار وقيمة منطقية تشير إلى ما إذا كان يمكن إعادة ربط عناصر InputAction في مجموعاتك. يمكن إعادة ربط المجموعات التي تم إنشاؤها باستخدام طريقة حزمة تطوير البرامج (SDK) Input 1.0.0-beta create() التي سيتم إيقافها نهائيًا، وهي تحمل رقم التعريف 0، ويكون رقم تعريف الإصدار سلسلة فارغة (""):

InputGroup في الإصدار التجريبي من حزمة تطوير البرامج (SDK) Input 1.0.0

Kotlin

val movementInputGroup = InputGroup.create(
    "Basic Movement",
    listOf(
        moveUpInputAction,
        moveLeftInputAction,
        moveDownInputAction,
        moveRightInputAction,
        jumpInputAction,
        runInputAction)
)

Java

InputGroup movementInputGroup = InputGroup.create(
    "Basic movement",
    Arrays.asList(
        moveUpInputAction,
        moveLeftInputAction,
        moveDownInputAction,
        moveRightInputAction,
        jumpInputAction,
        runInputAction
    )
);

InputGroup في حزمة تطوير البرامج (SDK) Input 1.1.1 الإصدار التجريبي

Kotlin

companion object {
    private val movementInputGroup = InputGroup.create(
        "Basic movement",
        listOf(
            moveUpInputAction,
            moveLeftInputAction,
            moveDownInputAction,
            moveRightInputAction,
            jumpInputAction,
            runInputAction),
        InputGroupsIds.BASIC_MOVEMENT.ordinal.toLong(),
        // All the actions in this groups can't be remapped
        InputEnums.REMAP_OPTION_DISABLED
    )
}

Java

private static final InputGroup movementInputGroup = InputGroup.create(
    "Basic movement",
    Arrays.asList(
            moveUpInputAction,
            moveLeftInputAction,
            moveDownInputAction,
            moveRightInputAction,
            jumpInputAction,
            runInputAction
    ),
    InputGroupsIds.BASIC_MOVEMENT.ordinal(),
    // All the actions in this groups can't be remapped
    InputEnums.REMAP_OPTION_DISABLED
);

InputGroup في الإصدار التجريبي من حزمة تطوير البرامج (SDK) Input SDK 1.1.1 (مع سلسلة الإصدار)

Kotlin

companion object {
    private val movementInputGroup  = InputGroup.create(
        "Basic movement",
        listOf(
            moveUpInputAction,
            moveLeftInputAction,
            moveDownInputAction,
            moveRightInputAction,
            jumpInputAction,
            runInputAction),
        InputIdentifier.create(
            INPUTMAP_VERSION, InputGroupsIds.BASIC_MOVEMENT.ordinal.toLong()),
        // All the actions in this groups can't be remapped
        InputEnums.REMAP_OPTION_DISABLED
    )
}

Java

private static final InputGroup movementInputGroup = InputGroup.create(
    "Basic movement",
    Arrays.asList(
            moveUpInputAction,
            moveLeftInputAction,
            moveDownInputAction,
            moveRightInputAction,
            jumpInputAction,
            runInputAction
    ),
    InputIdentifier.create(
            INPUTMAP_VERSION,
            InputGroupsIds.BASIC_MOVEMENT.ordinal()),
    // All the actions in this groups can't be remapped
    InputEnums.REMAP_OPTION_DISABLED
);

لمزيد من المعلومات عن تحديد إصدارات عمليات ربط المفاتيح، يُرجى الاطّلاع على مقالة تتبُّع أرقام تعريف المفاتيح.

تعديل InputMap

تم إيقاف طريقة InputMap.create() في حزمة تطوير البرامج (SDK) 1.0.0-beta نهائيًا. عدِّل InputMap لتحديد معرّف إصدار أو إيقاف ميزة إعادة الربط نهائيًا أو تحديد قائمة بالمفاتيح المحجوزة للعبة التي لا تريد أن يستخدمها المستخدم لإعادة الربط. كل InputMap يتم تحديده باستخدام طريقة Input SDK 1.0.0-beta create() يمكن إعادة تعيينه تلقائيًا، ويتم تحديده باستخدام المعرّف 0، ولا يحتوي على أي مفاتيح محجوزة.

InputMap في حزمة Input SDK الإصدار 1.0.0 الإصدار التجريبي

Kotlin

val gameInputMap = InputMap.create(
    listOf(movementInputGroup, mouseMovementInputGroup),
    MouseSettings.create(true, false)
)

Java

InputMap gameInputMap = InputMap.create(
    Arrays.asList(movementInputGroup, mouseMovementInputGroup),
    MouseSettings.create(true, false)
);

InputMap في حزمة Input SDK 1.1.1 التجريبية

Kotlin

companion object {

  const val INPUTMAP_VERSION = "1.0.0"
  const val INPUT_MAP_ID = 0

  val gameInputMap = InputMap.create(
    listOf(movementInputGroup, mouseMovementInputGroup),
    MouseSettings.create(true, false),
    InputIdentifier.create(INPUTMAP_VERSION, INPUT_MAP_ID.toLong()),
    InputEnums.REMAP_OPTION_ENABLED,
    // Use ESCAPE as reserved key
    listof(InputControls.create(listOf(KeyEvent.KEYCODE_ESCAPE), emptyList()))
  )
}

Java


public static final String INPUT_MAP_VERSION = "1.0.0-beta";
public static final long INPUT_MAP_ID = 0;

public static final InputMap gameInputMap = InputMap.create(
        Arrays.asList(movementInputGroup, mouseMovementInputGroup),
        MouseSettings.create(true, false),
        InputIdentifier.create(INPUTMAP_VERSION, INPUT_MAP_ID),
        InputEnums.REMAP_OPTION_ENABLED,
        // Use ESC key as reserved key
        Arrays.asList(
                InputControls.create(
                        Collections.singletonList(KeyEvent.KEYCODE_ESCAPE),
                        Collections.emptyList()
                )
        )
);

الخطوات التالية

يمكنك مواصلة الترقية إلى الإصدار التجريبي 1.1.1 من خلال تخصيص عناصر تحكّم مختلفة للمشاهد المختلفة باستخدام InputContexts أو تعديل واجهة المستخدم في لعبتك من خلال تلقّي إشعارات عند إعادة ربط الأحداث باستخدام InputRemappingListeners.

عند تعديل عمليات ربط المفاتيح، اطّلِع على أفضل الممارسات لتصميم عمليات ربط المفاتيح، ومرِّر نظرة على القيود والحدود المفروضة على ميزة إعادة الربط.