שדרוג קלט SDK עבור Java ו-Kotlin לגרסה 1.1

במדריך הזה מוסבר איך לשדרג את המשחק מגרסת הבטא 1.0.0 קלט SDK עבור Java ו-Kotlin לגרסת בטא 1.1.0. לצפייה מדריך לשדרוג Unity ל-Unity הוראות ספציפיות.

נתוני גרסה

ב-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.

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

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

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

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

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

שדרוג

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

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

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

תלות בשדרוג

אם משתמשים ב-Gradle כדי לייבא את ה-SDK של קלט, צריך לשדרג לגרסה החדשה ביותר:

// build.gradle
dependencies {
   ...
   implementation 'com.google.android.libraries.play.games:inputmapping:1.1.0-beta'
   ...
}

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

עבור גרסה 1.1.0-beta מומלץ להגדיר את InputAction, InputGroup, InputContext ו-InputMap אובייקטים כשדות סטטיים של הכיתה InputMappingProvider כי ניתן לגשת לשדות האלה מחלקים אחרים של האפליקציה:

class InputSDKProvider : InputMappingProvider {
    override fun onProvideInputMap(): InputMap { return gameInputMap }

    companion object {
        const val INPUTMAP_VERSION = "1.0.0"

        private val moveUpInputAction = InputAction.create(...)
        private val movementInputGroup = InputGroup.create(...)
        val menuContext = InputContext.create(...)
        val gameInputMap = InputMap.create(...)
    }
}

public class MyInputMappingProvider implements InputMappingProvider {
    private static final String INPUTMAP_VERSION = "1.0.0";

    private static final InputAction moveUpInputAction =
        InputAction.create(...);
    private static final InputGroup movementInputGroup = InputGroup.create(...);
    public static final InputContext menuContext = InputContext.create(...);
    public static final InputMap gameInputMap = InputMap.create(...);

    @Override
    public InputMap onProvideInputMap() {
        return gameInputMap;
    }
}

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

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

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

val jumpInputAction = InputAction.create(
    "Jump",
    InputEventIds.JUMP.id,
    InputControls.create(
        listOf(KeyEvent.KEYCODE_SPACE),
        emptyList()
    )
)

InputAction moveUpInputAction = InputAction.create(
    "Move Up",
    InputEventIds.MOVE_UP.ordinal(),
    InputControls.create(
        Collections.singletonList(KeyEvent.KEYCODE_W),
        Collections.emptyList()
    )
);

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

companion object {
  private val moveUpInputAction = InputAction.create(
    "Move Up",
    InputActionsIds.DRIVE.ordinal.toLong(),
    InputControls.create(listOf(KeyEvent.KEYCODE_W), emptyList()),
    InputEnums.REMAP_OPTION_ENABLED) // This action is remappable
}

private static final InputAction moveUpInputAction = InputAction.create(
    "Move Up",
    InputEventIds.MOVE_UP.ordinal(),
    InputControls.create(
            Collections.singletonList(KeyEvent.KEYCODE_W),
            Collections.emptyList()),
    InputEnums.REMAP_OPTION_ENABLED // this action is remappable
);

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

private val enterMenuInputAction = InputAction.create(
    "Enter menu",
    InputControls.create(listOf(KeyEvent.KEYCODE_ENTER), emptyList()),
    InputIdentifier.create(
    INPUTMAP_VERSION, InputActionsIds.ENTER_MENU.ordinal.toLong()),
    InputEnums.REMAP_OPTION_ENABLED
)

private static final InputAction moveUpInputAction = InputAction.create(
    "Move Up",
    InputControls.create(
            Collections.singletonList(KeyEvent.KEYCODE_W),
            Collections.emptyList()),
    InputIdentifier.create(
            INPUTMAP_VERSION,
            InputEventIds.MOVE_UP.ordinal()),
    InputEnums.REMAP_OPTION_ENABLED // this action is remappable
);

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

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

ב-input SDK 1.1.0-beta צריך לזהות באופן ייחודי כל אחד מהם InputGroup. כל InputAction שייך ל-InputGroup – אוסף של פעולות קשורות. כך ניתן לשפר את הניווט ואת יכולת הגילוי של אמצעי הבקרה במהלך המשחק. באותו אופן, ל-InputAction חייב להיות מזהה ייחודי מבין כל הפעולות ב-InputContext יחיד, InputGroup חייב לכלול מזהה ייחודי בכל הקבוצות הקיימות.

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

enum class 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
}

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-בטא

val movementInputGroup = InputGroup.create(
    "Basic Movement",
    listOf(
        moveUpInputAction,
        moveLeftInputAction,
        moveDownInputAction,
        moveRightInputAction,
        jumpInputAction,
        runInputAction)
)

InputGroup movementInputGroup = InputGroup.create(
    "Basic movement",
    Arrays.asList(
        moveUpInputAction,
        moveLeftInputAction,
        moveDownInputAction,
        moveRightInputAction,
        jumpInputAction,
        runInputAction
    )
);

CredentialsGroup בקלט SDK 1.1.0-בטא

companion object {
    private val movementInputGroup = InputGroup.create(
        "Basic movement",
        listOf(
            moveUpInputAction,
            moveLeftInputAction,
            moveDownInputAction,
            moveRightInputAction,
            jumpInputAction,
            runInputAction),
        InputGroupsIds.BASIC_MOVEMENT.ordinal.toLong(),
        // All the actions in this groups can't be remapped
        InputEnums.REMAP_OPTION_DISABLED
    )
}

private static final InputGroup movementInputGroup = InputGroup.create(
    "Basic movement",
    Arrays.asList(
            moveUpInputAction,
            moveLeftInputAction,
            moveDownInputAction,
            moveRightInputAction,
            jumpInputAction,
            runInputAction
    ),
    InputGroupsIds.BASIC_MOVEMENT.ordinal(),
    // All the actions in this groups can't be remapped
    InputEnums.REMAP_OPTION_DISABLED
);

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

companion object {
    private val movementInputGroup  = InputGroup.create(
        "Basic movement",
        listOf(
            moveUpInputAction,
            moveLeftInputAction,
            moveDownInputAction,
            moveRightInputAction,
            jumpInputAction,
            runInputAction),
        InputIdentifier.create(
            INPUTMAP_VERSION, InputGroupsIds.BASIC_MOVEMENT.ordinal.toLong()),
        // All the actions in this groups can't be remapped
        InputEnums.REMAP_OPTION_DISABLED
    )
}

private static final InputGroup movementInputGroup = InputGroup.create(
    "Basic movement",
    Arrays.asList(
            moveUpInputAction,
            moveLeftInputAction,
            moveDownInputAction,
            moveRightInputAction,
            jumpInputAction,
            runInputAction
    ),
    InputIdentifier.create(
            INPUTMAP_VERSION,
            InputGroupsIds.BASIC_MOVEMENT.ordinal()),
    // All the actions in this groups can't be remapped
    InputEnums.REMAP_OPTION_DISABLED
);

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

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

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

InfoMap ב-Ininput SDK 1.0.0-beta

val gameInputMap = InputMap.create(
    listOf(movementInputGroup, mouseMovementInputGroup),
    MouseSettings.create(true, false)
)

InputMap gameInputMap = InputMap.create(
    Arrays.asList(movementInputGroup, mouseMovementInputGroup),
    MouseSettings.create(true, false)
);

InsertMap ב-input SDK 1.1.0-Beta

companion object {

  const val INPUTMAP_VERSION = "1.0.0"
  const val INPUT_MAP_ID = 0

  val gameInputMap = InputMap.create(
    listOf(movementInputGroup, mouseMovementInputGroup),
    MouseSettings.create(true, false),
    InputIdentifier.create(INPUTMAP_VERSION, INPUT_MAP_ID.toLong()),
    InputEnums.REMAP_OPTION_ENABLED,
    // Use ESCAPE as reserved key
    listof(InputControls.create(listOf(KeyEvent.KEYCODE_ESCAPE), emptyList()))
  )
}

public static final String INPUT_MAP_VERSION = "1.0.0-beta";
public static final long INPUT_MAP_ID = 0;

public static final InputMap gameInputMap = InputMap.create(
        Arrays.asList(movementInputGroup, mouseMovementInputGroup),
        MouseSettings.create(true, false),
        InputIdentifier.create(INPUTMAP_VERSION, INPUT_MAP_ID),
        InputEnums.REMAP_OPTION_ENABLED,
        // Use ESC key as reserved key
        Arrays.asList(
                InputControls.create(
                        Collections.singletonList(KeyEvent.KEYCODE_ESCAPE),
                        Collections.emptyList()
                )
        )
);

השלב הבא

עליך להמשיך בשדרוג לגרסת בטא 1.1.0 עד הקצאת פקדים שונים לסצנות שונות באמצעות InputContexts או מעדכנים את ממשק המשתמש של המשחק על ידי קבלת התראות על מיפוי מחדש של אירועים באמצעות InputRemappingListeners.

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