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

يوضّح هذا الدليل كيفية ترقية لعبتك من الإصدار 1.0.0-beta من حزمة تطوير البرامج (SDK) الخاصة بأدوات الإدخال للغة Java وKotlin إلى الإصدار 1.1.1-beta. راجِع دليل ترقية Unity للحصول على تعليمات خاصة بـ Unity.

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

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

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

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

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

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

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

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

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

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

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

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

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

يتم إيقاف ميزة إعادة تعيين الإدخال في حال عدم استيفاء الشروط التالية:

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

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

ترقية

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

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

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

إذا كنت تستخدم Gradle لاستيراد حزمة Input SDK، عليك الترقية إلى أحدث إصدار:

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

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

بالنسبة إلى الإصدار 1.1.1-beta، من أفضل الممارسات تحديد عناصر InputAction وInputGroup وInputContext وInputMap كحقول ثابتة لفئة 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 تم تعريفه باستخدام طريقة create() في حزمة Input SDK تلقائيًا، ولا يتضمّن معلومات حول الإصدار:1.0.0-beta

‫InputAction في حزمة تطوير البرامج (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 في حزمة 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 في Input SDK 1.1.1-beta (مع سلسلة الإصدار)

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 في مجموعاتك قابلة لإعادة الربط. يمكن إعادة ربط المجموعات التي تم إنشاؤها باستخدام الطريقة 1.0.0-beta create() المتوقّفة نهائيًا في حزمة Input SDK، ويكون رقم تعريفها 0، ويكون رقم تعريف الإصدار سلسلة فارغة (""):

InputGroup في حزمة تطوير البرامج (SDK) الخاصة بأداة الإدخال 1.0.0-beta

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) للإدخال 1.1.1-beta

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) الخاصة بأدوات الإدخال 1.1.1-beta (مع سلسلة الإصدار)

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 يتم تحديده باستخدام طريقة 1.0.0-beta create() في حزمة Input SDK تلقائيًا، ويتم تعريفه باستخدام المعرّف 0، ولا يتضمّن أي مفاتيح محجوزة.

InputMap في حزمة تطوير البرامج (SDK) للإدخال 1.0.0-beta

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 في حزمة تطوير البرامج (SDK) للإدخال 1.1.1-beta

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.

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