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

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

הערות מוצר

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

הצגת InputContext

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

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

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

שדרוג

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

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

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

התקנה

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

כדי להוסיף את Input SDK v1.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() של Input SDK 1.0.0-beta הוצאה משימוש. ל-InputAction יש מזהה גרסה ואפשר לסמן אותו כניתן למיפוי מחדש או לא. InputAction מוגדר באמצעות שיטת Input 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>()
    )
);

‫InputAction ב-Input SDK 1.1.1-beta

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

‫InputMap ב-Input SDK 1.0.0-beta

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

‫InputMap ב-Input 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-beta, צריך להקצות אמצעי בקרה שונים לסצנות שונות באמצעות InputContexts או לעדכן את ממשק המשתמש של המשחק על ידי קבלת התראה על מיפוי מחדש של אירועים באמצעות InputRemappingListeners.

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