שדרוג קלט 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 כדי להגדיר את התכונה של מיפוי מחדש כמושבתת.

אפשר לשדרג את הגרסה של Input 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 בתפריטים, ואת מקש הרווח למקש החץ למעלה במהלך המשחק.

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

שדרוג

משחקים שמשתמשים בהטמעות קודמות של 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

עדכון של פעולות הקלט

השימוש ב-method‏ InputAction.create() של Input SDK‏ 1.0.0-beta הוצא משימוש. ל-InputAction יש מזהה גרסה ואפשר לסמן אותו כניתן למיפוי מחדש או לא. InputAction שמוגדר באמצעות ה-method‏ 1.0.0-beta create() של Input SDK ניתן למיפוי מחדש כברירת מחדל ואין לו מידע על גרסאות:

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

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