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

يوضّح هذا الدليل كيفية ترقية لعبتك من الإصدار 1.0 إلى الإصدار 1.1 من حزمة Input SDK لنظام التشغيل Unity. انقر هنا للاطّلاع على تعليمات Java وKotlin.

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

تتيح "ألعاب 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.

عند الترقية، يجب مراعاة الاستثناءات التالية:

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

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

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

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

مقدّمة عن InputContext

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

يوضّح مخطط التسلسل التالي طريقة عمل واجهة برمجة التطبيقات setInputContext() في وقت التشغيل:

ترقية

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

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

• تفعيل تغييرات السياق
• تلقّي إشعارات بأحداث ربط المفاتيح
• إيقاف إعادة الربط لكل إجراء أو مجموعة أو سياق أو خريطة

التثبيت

يتوفّر المكوّن الإضافي Unity v1.1.1-beta لاستخدامه. عليك حذف أي إصدارات سابقة من حزمة تطوير البرامج (SDK) الخاصة بأداة الإدخال مثبّتة في لعبتك والترقية إلى الإصدار الحالي.

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

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

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

#if PLAY_GAMES_PC
using Java.Lang;
using Java.Util;
using Google.Android.Libraries.Play.Games.Inputmapping;
using Google.Android.Libraries.Play.Games.Inputmapping.Datamodel;

public class InputSDKMappingProvider : InputMappingProviderCallbackHelper
{
    public static readonly string INPUT_MAP_VERSION = "1.0.0";

    private static readonly InputAction driveInputAction =
            InputAction.Create(...);
    private static readonly InputGroup roadInputGroup = InputGroup.Create(...);
    public static readonly InputContext roadControlsContext =
            InputContext.Create(...);
    public static readonly InputMap inputMap = InputMap.Create(...);

    public override InputMap OnProvideInputMap()
    {
        return inputMap;
    }
}
#endif

تعديل InputActions

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

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

var driveAction = PlayInputAction.Create(
    "Drive",
    (long)InputEventIds.DRIVE,
    PlayInputControls.Create(
        new[] { AndroidKeyCode.KEYCODE_SPACE },
        new List<PlayMouseAction>()
    )
);

‫InputAction في حزمة Input SDK الإصدار 1.1.1 التجريبي

private static readonly InputAction driveInputAction = InputAction.Create(
    "Drive",
    (long)InputEventIds.DRIVE,
    InputControls.Create(
        new[] { new Integer(AndroidKeyCode.KEYCODE_SPACE) }.ToJavaList(),
        new ArrayList<Integer>()),
    InputEnums.REMAP_OPTION_ENABLED
);

‫InputAction في Input SDK 1.1.1-beta (مع سلسلة الإصدار)

private static readonly InputAction driveInputAction = InputAction.Create(
    "Drive",
    InputControls.Create(
        new[] { new Integer(AndroidKeyCode.KEYCODE_SPACE) }.ToJavaList(),
        new ArrayList<Integer>()),
    InputIdentifier.Create(
        INPUT_MAP_VERSION, (long)InputEventIds.DRIVE),
    InputEnums.REMAP_OPTION_ENABLED
);

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

تعديل InputGroups

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

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

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

var gameInputGroup = PlayInputGroup.Create(
    "Road controls",
    new List<PlayInputAction>
    {
        driveAction,
        turboAction,
        openGarageAction,
        openPgsAction,
        openStoreAction
    }
);

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

private static readonly InputGroup roadInputGroup = InputGroup.Create(
    "Road controls",
    new[]
    {
        driveInputAction,
        turboInputAction,
        openGarageInputAction,
        openPgsInputAction,
        openStoreInputAction,
    }.ToJavaList(),
    (long)InputGroupsIds.ROAD_CONTROLS,
    // All input actions of this group will be remappable unless specified
    // the contrary by the individual input actions.
    InputEnums.REMAP_OPTION_ENABLED
);

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

private static readonly InputGroup roadInputGroup = InputGroup.Create(
    "Road controls",
    new[]
    {
        driveInputAction,
        turboInputAction,
        openGarageInputAction,
        openPgsInputAction,
        openStoreInputAction,
    }.ToJavaList(),
    InputIdentifier.Create(
        INPUT_MAP_VERSION, (long)InputGroupsIds.ROAD_CONTROLS),
    // All input actions of this group will be remappable unless specified
    // the contrary by the individual input actions.
    InputEnums.REMAP_OPTION_ENABLED
);

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

تعديل InputMap

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

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

var gameInputMap = PlayInputMap.Create(
    new List<PlayInputGroup>
    {
        gameInputGroup,
        menuInputGroup
    },
    PlayMouseSettings.Create(false, false)
);

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

public static readonly string INPUT_MAP_VERSION = "1.0.0";
public static readonly long INPUT_MAP_ID = 0;

public static readonly InputMap inputMap = InputMap.Create(
    new[] { roadInputGroup, menuInputGroup }.ToJavaList(),
    MouseSettings.Create(false, false),
    InputIdentifier.Create(INPUT_MAP_VERSION, INPUT_MAP_ID),
    // Use ESC as reserved key
    InputEnums.REMAP_OPTION_ENABLED,
    new[]
    {
        InputControls.Create(new[]
        {
            new Integer(AndroidKeyCode.KEYCODE_ESCAPE)
        }.ToJavaList(),
        new ArrayList<Integer>())
    }.ToJavaList()
);

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

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

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