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

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

הערות מוצר

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

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

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

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

אין צורך לשדרג את ה-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.

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

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

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

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

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

שדרוג

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

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

שדרוג של יחסי תלות

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

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

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

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

Kotlin

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(...)
    }
}

Java

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

עדכון של 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

Kotlin

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

Java

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

‫InputAction ב-Input SDK 1.1.1-beta

Kotlin

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
}

Java

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

‫InputAction ב-Input SDK 1.1.1-beta (עם מחרוזת גרסה)

Kotlin

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
)

Java

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

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

עדכון של InputGroups

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

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

Kotlin

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
}

Java

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

Kotlin

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

Java

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

‫InputGroup ב-Input SDK 1.1.1-beta

Kotlin

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

Java

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

‫InputGroup ב-Input SDK 1.1.1-beta (עם מחרוזת גרסה)

Kotlin

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

Java

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

הוצאה משימוש של שיטת 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

Kotlin

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

Java

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

‫InputMap ב-Input SDK 1.1.1-beta

Kotlin

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()))
  )
}

Java


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

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