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

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

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

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

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

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

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

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

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

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

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

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

يمكنك ترقية إصدار حزم SDK للإدخال إلى 1.1.0-beta للاستفادة من الميزات المتقدّمة لإعادة التعيين في برنامج "ألعاب Google Play على الكمبيوتر" من خلال استخدام InputContexts لتحديد عناصر التحكّم لمشاهد مختلفة من لعبتك، وإضافة استدعاءات للاستماع إلى أحداث إعادة التعيين، وتحديد مجموعة من المفاتيح المحجوزة التي لا يمكن للمستخدم إعادة تخصيصها، وإيقاف ميزة إعادة التعيين لكل InputAction، InputGroup أو InputMap.

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

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

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

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

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

لمحة عن InContext

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

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

ترقية

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

تعمل الترقية إلى الإصدار 1.1.0 على تفعيل ميزات جديدة، من بينها:

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

التثبيت

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

لإضافة الإصدار التجريبي من إدخال SDK الإصدار 1.1.0 إلى لعبتك، يمكنك الاطّلاع على إضافة حزمة SDK.

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

بالنسبة إلى الإصدار 1.1.0 من الإصدار التجريبي، ننصح بتحديد 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

تعديل InActions (إجراءات الإدخال)

ملاحظة: ننصحك باتّباع أفضل الممارسات المتعلّقة بعناصر التحكّم في لوحة المفاتيح والماوس في ألعاب Android عند تصميم InputAction، وتجنُّب تنفيذ عمليات ضبط غير متوافقة.

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

EnterAction في الإصدار 1.0.0 من حزمة SDK للإدخال التجريبي

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

EnterAction في الإصدار 1.1.0 من حزمة الإصدار التجريبي للإدخال

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

الإصدار التجريبي من نظام الإدخال (إدخال) الإصدار 1.1.0 من حزمة "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.0-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
}

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

الإصدار التجريبي من In تقسيم SDK للإدخال 1.0.0

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

الإصدار 1.1.0 من واجهة برمجة التطبيقات للإدخال في الإصدار التجريبي

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

الإصدار 1.1.0 من واجهة InSDK للإدخال (مع سلسلة الإصدار)

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

EnterMap في إصدار SDK للإدخال 1.0.0-التجريبي

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

EnterMap في إصدار SDK للإدخال 1.1.0 - الإصدار التجريبي

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

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