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

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

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

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

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

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

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

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

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

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

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

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

يمكنك ترقية إصدار حزمة تطوير البرامج (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 للعبة باستخدام المفتاح نفسه لتنفيذ إجراءات مختلفة في لعبتك بدون حدوث تعارضات. بهذه الطريقة، إذا كانت إحدى الألعاب تستخدم مفتاح المسافة للقفز أثناء اللعب ولتأكيد اختيار أحد الخيارات في القائمة، سيتمكّن اللاعبون من إعادة تعيين مفتاح المسافة بشكل فردي إلى مفتاح Enter في القوائم و إلى مفتاح السهم المتّجه للأعلى أثناء اللعب.

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

ترقية

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

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

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

التثبيت

يتوفّر الإصدار التجريبي 1.1.1 من إضافة Unity لاستخدامك. عليك حذف أي إصدارات سابقة من حزمة Input SDK مثبَّتة في لعبتك والترقية إلى الإصدار الحالي.

لإضافة حزمة Input SDK الإصدار 1.1.1-beta إلى لعبتك، اطّلِع على مقالة إضافة حزمة SDK.

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

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

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

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

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

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

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