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

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

נתוני גרסה

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

היכרות עם קלטContext

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

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

שדרוג

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

שדרוג לגרסת בטא 1.1.0 בטא מפעיל תכונות חדשות, כולל:

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

התקנה

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

כדי להוסיף למשחק את גרסה 1.1.0-בטא של ה-SDK: הוספת ה-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

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

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

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

קלט פעולה ב-input SDK 1.0.0-בטא

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

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

קלט פעולה ב-input SDK 1.1.0-בטא (עם מחרוזת גרסה)

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

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

עדכון קבוצות הקלט

ב-input 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
}

כמו InputAction, גם שיטת ה-InputGroup.create() של קלט SDK 1.0.0-beta הוצא משימוש. עליך לעדכן את InputGroup במשחק שלך במזהה גרסה ובוליאני שמציין אם InputAction אובייקטים בקבוצות שלך ניתנים לעדכון. ניתן לשנות קבוצות שנוצרו באמצעות שיטת קלט SDK 1.0.0-beta create() שהוצאה משימוש, והמזהה שלהן הוא 0, ומזהה הגרסה הוא מחרוזת ריקה (""):

CredentialsGroup בקלט SDK 1.0.0-בטא

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

קלטGroup ב-input SDK 1.1.0-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
);

קלטGroup ב-input SDK 1.1.0-בטא (עם מחרוזת גרסה)

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 ואין לו שמורים.

InfoMap ב-Ininput SDK 1.0.0-beta

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

InsertMap ב-input SDK 1.1.0-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.0 עד הקצאת פקדים שונים לסצנות שונות באמצעות InputContexts או מעדכנים את ממשק המשתמש של המשחק על ידי קבלת התראות על מיפוי מחדש של אירועים באמצעות InputRemappingListeners.

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