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

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

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

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

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

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

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

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

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

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

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

• يجب الترقية إلى الإصدار 1.1.1-beta من حزمة تطوير البرامج (SDK) Input.
• يُرجى تعديل 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 التجريبي.

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

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

التثبيت

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

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

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

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

إدخال Action في الإصدار 1.1.1 من حزمة SDK للإدخال

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

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

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

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

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

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

EnterGroup في الإصدار التجريبي من حزمة تطوير البرامج (SDK) للإدخال

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

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

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

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

InputMap في حزمة Input SDK الإصدار 1.0.0 الإصدار التجريبي

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

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

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.

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