שדרוג קלט SDK ל-Unity לגרסה 1.1

במדריך הזה מוסבר איך לשדרג את המשחק מ-Input SDK 1.0 ל-Input SDK 1.1 ל-Unity. כאן תוכלו למצוא הוראות ל-Java ול-Kotlin.

נתוני גרסה

Google Play Games במחשב תומך במיפוי מחדש של אמצעי הבקרה במקלדת על סמך קישורי המקשים שהמשחק מספק באמצעות Input SDK.

כדי לגשת לתכונה הזו, המשתמשים צריכים לפתוח את השכבת-העל, לבחור באפשרות אמצעי בקרה ואז ללחוץ על הפעולה שרוצים למפות מחדש.

אפליקציית Google Play Games במחשב ממופה כל קלט שמופה מחדש על ידי משתמשים לקלט ברירת המחדל של המשחק. כך המשחק לא צריך להיות מודע למיפוי מחדש של השחקן. אם אתם צריכים לדעת מהו הקלט החדש של פעולה במשחק, למשל הצגת אמצעי הבקרה של המקלדת במשחק, תוכלו לרשום פונקציית חזרה (callback) כדי לקבל התראה על אירועי מיפוי מחדש.

Google Play Games במחשב שומר באופן מקומי את השינויים של המשתמש במיקומי הלחצנים, כדי שהם יישארו בתוקף במהלך סשנים של משחק. מאחר שההגדרות האלה נשמרות באופן מקומי, הן לא משפיעות על חוויית המשתמש בנייד ונמחקות אחרי הסרת Google Play Games מהמחשב. ההגדרות לא נשמרות במספר מחשבים.

אין צורך לשדרג את קלט ה-SDK כדי להפעיל מיפוי מחדש של מפתחות במשחק, אבל המיפוי מחדש יושבת במשחק אם תזוהה הגדרה שאינה נתמכת.

אם אתם רוצים לשלוט בחוויית המיפוי של הקלט או אם תכונת המיפוי מושבתת במשחק, תוכלו לפעול לפי השלבים הבאים:

אם רוצים להפסיק להשתמש במיפוי מחדש במשחק ועדיין להציג את הגרסה לקריאה בלבד של קישורי המפתחות, פועלים לפי השלבים הבאים:

  • משדרגים ל-Input SDK 1.1.1-beta.
  • מעדכנים את ה-InputMap כך שתכונת המיפוי מחדש תהיה מושבתת.

אפשר לשדרג את הגרסה של קלט SDK ל-1.1.1-beta כדי לנצל את תכונות המיפוי מחדש המתקדמות ב-Google Play Games במחשב באמצעות הפקודה InputContexts כדי להגדיר פקדים לסצנות שונות של המשחק, להוסיף קריאה חוזרת כדי להאזין לאירועים למיפוי מחדש, להגדיר קבוצה של מפתחות שמורים שהמשתמש לא יכול למפות אליהם מחדש ולהשבית את תכונת המיפוי מחדש לכל InputAction, InputGroup או InputMap.

כשמבצעים שדרוג, חשוב להביא בחשבון את החריגות הבאות:

הגדרות שלא נתמכות

מיפוי מחדש של הקלט מושבת אם התנאים הבאים לא מתקיימים:

  • InputAction שמשתמש במספר מפתחות חייב להיות מורכב ממקש צירוף ומקש שאינו מקש צירוף. לדוגמה, Shift + A תקין, אבל A + B, ‏ Ctrl + Alt ו-Shift + A + Tab לא תקינים.

  • שני אובייקטים מסוג InputAction או InputGroup או יותר לא יכולים לשתף את אותו מזהה ייחודי.

חדש: InputContext

InputContext מאפשר למשחק להשתמש באותו מפתח לפעולות שונות במשחק בלי התנגשויות. כך, אם במשחק נעשה שימוש במקש הרווח כדי לקפוץ במהלך המשחק ולאשר בחירה בתפריט, השחקנים יכולים למפות מחדש בנפרד את הרווח ל-Enter בתפריטים ואת הרווח ל-חץ למעלה במהלך המשחק.

בתרשים הרצף הבא אפשר לראות איך ה-API של setInputContext() פועל בזמן ריצה:

תרשים שבו מוצג התהליך של Input SDK כשממפים מחדש מפתחות.

שדרוג

משחקים שמשתמשים בהטמעות קודמות של Input SDK עדיין תומכים במיפוי מחדש בסיסי, אלא אם הם משתמשים בהגדרה שאינה נתמכת. אם במשחק שלכם נעשה שימוש בגרסה ישנה יותר של Input SDK, מומלץ לקרוא את מדריך השדרוג מגרסה 0.0.4 לגרסה 1.0.0-beta.

השדרוג לגרסה 1.1.1-beta מאפשר תכונות חדשות, כולל:

  • הפעלת שינויים בהקשר.
  • קבלת התראות על אירועי מיפוי מרכזיים
  • השבתת המיפוי מחדש לפי פעולה, קבוצה, הקשר או מפה.

התקנה

פלאגין Unity בגרסה 1.1.1-beta זמין לשימוש. צריך למחוק את כל הגרסאות הקודמות של Input SDK שמותקנות במשחק ולשדרג לגרסה הנוכחית.

במאמר הוספת ה-SDK מוסבר איך מוסיפים את Input SDK v1.1.1-beta למשחק.

הגדרת שדות סטטיים

בגרסה 1.1.1-בטא מומלץ להגדיר את 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 שמוגדר באמצעות שיטת קלט SDK 1.0.0-beta create() ואין בה מידע על ניהול גרסאות:

InputAction ב-Input SDK 1.0.0-beta

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

קלט פעולה ב-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

ב-Input 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 ב-Input SDK 1.0.0-beta

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

InputGroup ב-Input 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 ב-Input 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 שמוגדר באמצעות השיטה 1.0.0-beta create() של Input SDK ניתן למיפוי מחדש כברירת מחדל, הוא מזוהה באמצעות המזהה 0 ואין לו מפתחות שמורים.

InsertMap בקלט SDK 1.0.0-בטא

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

InsertMap ב-קלט SDK בגרסה 1.1.1-בטא


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.

כשמעדכנים את קיצורי הדרך, כדאי לעיין בשיטות המומלצות לעיצוב קיצורי הדרך ולקחת בחשבון את ההגבלות והמגבלות של תכונת המיפוי מחדש.