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

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

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

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

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

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

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

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

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

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

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

• رقِّ إلى الإصدار 1.1.1-beta من حزمة Input SDK.
• عدِّل 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 تتيح ميزة إعادة الضبط الأساسية، ما لم تستخدم إعدادًا غير متوافق. إذا كانت لعبتك تستخدم إصدارًا أقدم من حزمة Input SDK، ننصحك بقراءة دليل الترقية من الإصدار 0.0.4 إلى الإصدار 1.0.0-beta.

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

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

التثبيت

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

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

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

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

InputAction في الإصدار 1.1.1-beta من حزمة Input 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
);

InputAction في الإصدار 1.1.1-beta من حزمة Input 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
);

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

تعديل InputGroups

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

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

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

InputGroup في الإصدار 1.1.1-beta من حزمة Input SDK

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

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

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

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

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

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