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

يشرح هذا الدليل كيفية ترقية لعبتك من الإصدار 1.0.0-beta من Input SDK للغتَي Java وKotlin إلى الإصدار 1.1.1-beta. للحصول على تعليمات خاصة بـ Unity، يُرجى الاطّلاع على دليل ترقية Unity.

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

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

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

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

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

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

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

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

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

  • الترقية إلى Input SDK 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 في المعرّف الفريد نفسه.

ترقية

يتوافق الإصدار 1.1.1-beta من Input SDK مع الإصدار 1.0.0-beta من Input SDK. تظل الألعاب التي تستخدم عمليات التنفيذ السابقة من 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() في الإصدار 1.0.0-beta من Input SDK. يحتوي InputAction الآن على معرّف إصدار ويمكن وضع علامة عليه للإشارة إلى إمكانية إعادة تعيينه أو عدم إمكانية ذلك. يمكن إعادة تعيين InputAction الذي تم تحديده باستخدام طريقة create() في الإصدار 1.0.0-beta من Input SDK بشكلٍ تلقائي ولا يحتوي على معلومات تحديد الإصدار:

InputAction في الإصدار 1.0.0-beta من Input SDK

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 في الإصدار 1.1.1-beta من Input SDK

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 في الإصدار 1.1.1-beta من Input SDK (مع سلسلة الإصدار)

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

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

InputGroup في الإصدار 1.0.0-beta من Input SDK

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 في الإصدار 1.1.1-beta من Input SDK

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 في الإصدار 1.1.1-beta من Input SDK (مع سلسلة الإصدار)

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

InputMap في الإصدار 1.0.0-beta من Input SDK

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 في الإصدار 1.1.1-beta من Input SDK

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-beta من خلال تعيين عناصر تحكّم مختلفة لمشاهد مختلفة باستخدام InputContexts أو تعديل واجهة مستخدِم لعبتك من خلال تلقّي إشعارات بشأن أحداث إعادة التعيين باستخدام InputRemappingListeners.

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