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

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

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

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

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

يربط تطبيق "ألعاب 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) للإدخال، يُرجى الترقية إلى أحدث إصدار:

// 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 الذي تم تحديده باستخدام طريقة Input SDK 1.0.0-beta create() يمكن إعادة ربطه تلقائيًا ولا يتضمّن معلومات عن الإصدار:

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
);

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

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

تعديل مجموعات الإدخال

في حزمة 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 SDK 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
);

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

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