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

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

הערות מוצר

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

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

ב-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, כדאי לקרוא את מדריך השדרוג מגרסה 0.0.4 לגרסה 1.0.0-beta.

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

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

התקנה

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

‫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, הוצא משימוש ה-Method ‏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.

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