«کیت توسعه نرم‌افزار ورودی» برای Java و Kotlin را به نسخه ۱.۱ ارتقا دهید

این راهنما توضیح می‌دهد چگونه بازی‌تان را از نسخه 1.0.0-beta کیت توسعه نرم‌افزار ورودی برای Java و Kotlin به نسخه 1.1.1-beta ارتقا دهید. برای دستورالعمل‌های ویژه Unity، راهنمای ارتقا Unity را ببینید.

یادداشت‌های انتشار

«بازی‌های Google Play در رایانه» از تخصیص مجدد کنترل‌های صفحه‌کلید براساس کلیدهای تخصیص‌یافته‌ای که بازی شما بااستفاده از «کیت توسعه نرم‌افزار ورودی» ارائه می‌دهد پشتیبانی می‌کند.

کاربران با باز کردن روپوش، انتخاب کنترل‌ها، و سپس کلیک کردن روی کنشی که می‌خواهند دوباره نگاشت کنند به این ویژگی دسترسی پیدا می‌کنند.

«بازی‌های Google Play در رایانه» هر ورودی دوباره تخصیص‌یافته کاربر را به ورودی پیش‌فرض بازی‌تان تخصیص می‌دهد. به این ترتیب، بازی شما نیازی ندارد از تخصیص مجدد بازیکن مطلع باشد. اگر باید ورودی جدید کنش درون‌بازی را بدانید، مثلاً کنترل‌های صفحه‌کلید را در بازی‌تان نمایش دهید، می‌توانید به‌صورت اختیاری یک بازخوان ثبت کنید تا برای رویدادهای تخصیص مجدد مطلع شوید.

«بازی‌های Google Play در رایانه» کنترل‌های دوباره تخصیص‌داده‌شده هر کاربر را به‌صورت محلی ذخیره می‌کند تا در جلسات بازی پایدار باشند. ازآنجایی‌که این اطلاعات به‌صورت محلی ذخیره می‌شود، بر تجربه تلفن همراه تأثیر نمی‌گذارد و با حذف نصب «بازی‌های Google Play در رایانه» حذف می‌شود. تنظیمات کنترل در چندین دستگاه رایانه شخصی حفظ نمی‌شود.

برای فعال کردن تخصیص مجدد کلید در بازی‌تان، نیازی به ارتقا دادن «کیت توسعه نرم‌افزار ورودی» ندارید، اما اگر پیکربندی پشتیبانی‌نشده‌ای شناسایی شود، تخصیص مجدد می‌تواند برای بازی‌تان غیرفعال شود.

اگر می‌خواهید تجربه تخصیص مجدد ورودی را کنترل کنید، یا اگر ویژگی تخصیص مجدد برای بازی شما غیرفعال است، مراحل زیر را برای حل مشکل انجام دهید:

  • به «کیت توسعه نرم‌افزار ورودی» 1.1.1-beta ارتقا دهید.
  • برای جلوگیری از پیکربندی‌های پشتیبانی‌نشده، همه کلیدهای میان‌بر را به‌روز کنید.
  • برای تنظیم ویژگی تخصیص مجدد که فعال است، InputMap را به‌روز کنید.

اگر می‌خواهید از ویژگی تخصیص مجدد برای بازی‌تان انصراف دهید و درعین‌حال همچنان نسخه فقط‌خواندنی تخصیص‌های کلید را نمایش دهید، این مراحل را دنبال کنید:

  • به «کیت توسعه نرم‌افزار ورودی» 1.1.1-beta ارتقا دهید.
  • برای تنظیم ویژگی تخصیص مجدد به غیرفعال، InputMap خود را به‌روز کنید.

می‌توانید نسخه «کیت توسعه نرم‌افزار ورودی» را به 1.1.1-beta ارتقا دهید تا از ویژگی‌های پیشرفته تخصیص مجدد در «بازی‌های Google Play در رایانه» بهره‌مند شوید. برای این کار، از InputContexts برای تعریف کنترل‌های صحنه‌های مختلف بازی‌تان استفاده کنید، کارکردهای برگشتی را برای گوش دادن به رویدادهای تخصیص مجدد اضافه کنید، مجموعه‌ای از کلیدهای رزروشده را که کاربر نمی‌تواند به آن‌ها تخصیص مجدد دهد تعریف کنید، و ویژگی تخصیص مجدد را برای هر InputAction، InputGroup، یا InputMap غیرفعال کنید.

هنگام ارتقا دادن به نسخه جدید کیت توسعه نرم‌افزار، استثناهای زیر را درنظر بگیرید:

پیکربندی‌های پشتیبانی‌نشده

اگر شرایط زیر برآورده نشود، تخصیص مجدد ورودی غیرفعال می‌شود:

  • InputAction که از چندین کلید استفاده می‌کند باید از یک کلید اصلاح‌گر و یک کلید غیر اصلاح‌گر تشکیل شده باشد. برای مثال، تبدیل + A معتبر است اما A + B، Ctrl + Alt، و تبدیل + A + جهش معتبر نیستند.

  • دو یا چند شیء InputAction یا InputGroup نمی‌توانند شناسه یکتای یکسانی داشته باشند.

ارتقا

«کیت توسعه نرم‌افزار ورودی ۱.۱.۱-بتا» با «کیت توسعه نرم‌افزار ورودی ۱.۰.۰-بتا» سازگاری پس‌رونده دارد. بازی‌هایی که از پیاده‌سازی‌های قبلی «کیت توسعه نرم‌افزار ورودی» استفاده می‌کنند، همچنان از تخصیص مجدد پایه پشتیبانی می‌کنند، مگراینکه از پیکربندی پشتیبانی‌نشده استفاده کنند. اگر بازی شما از نسخه قدیمی‌تر «کیت توسعه نرم‌افزار ورودی» استفاده می‌کند، راهنمای ارتقا از 0.0.4 به 1.0.0-بتا را بخوانید.

ارتقا به نسخه 1.1.1-beta ویژگی‌های جدیدی را فعال می‌کند، ازجمله:

ارتقا دادن وابستگی

اگر از Gradle برای وارد کردن «کیت توسعه نرم‌افزار ورودی» استفاده می‌کنید، به جدیدترین نسخه ارتقا دهید:

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

تعریف فیلدهای ایستا

برای نسخه 1.1.1-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;
    }
}

به‌روزرسانی InputActions

روش InputAction.create() از «کیت توسعه نرم‌افزار ورودی» 1.0.0-beta منسوخ شده است. InputAction اکنون شناسه نسخه دارد و می‌تواند به‌عنوان قابل‌تغییر یا غیرقابل‌تغییر علامت‌گذاری شود. InputAction تعریف‌شده بااستفاده از روش Input SDK 1.0.0-beta create() به‌طور پیش‌فرض قابل‌تغییر است و اطلاعات نسخه ندارد:

‫InputAction در Input SDK نسخه 1.0.0-beta

کاتلین

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

‫InputAction در Input SDK نسخه 1.1.1-بتا

کاتلین

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

‫InputAction در Input SDK نسخه 1.1.1-beta (با رشته نسخه)

کاتلین

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

برای اطلاعات بیشتر درباره نسخه‌بندی کلیدهای تخصیص‌یافته، به ردیابی شناسه‌های کلید مراجعه کنید.

به‌روزرسانی InputGroups

در «کیت توسعه نرم‌افزار ورودی» 1.1.1-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() در «کیت توسعه نرم‌افزار ورودی» 1.0.0-beta منسوخ شده است. باید InputGroup را در بازی‌تان با یک شناسه نسخه و مقدار بولی که نشان می‌دهد آیا InputAction اشیاء در گروه‌هایتان قابل‌تغییر هستند یا نه به‌روز کنید. گروه‌های ایجادشده با روش منسوخ‌شده «کیت توسعه نرم‌افزار ورودی» 1.0.0-beta create() قابل تخصیص مجدد هستند، شناسه 0 دارند، و شناسه نسخه رشته‌ای خالی است (""):

‫InputGroup در Input SDK نسخه 1.0.0-beta

کاتلین

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

‫InputGroup در «کیت توسعه نرم‌افزار ورودی» نسخه ۱.۱.۱-بتا

کاتلین

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

‫InputGroup در «کیت توسعه نرم‌افزار ورودی» نسخه ۱.۱.۱-بتا (با رشته نسخه)

کاتلین

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

متد InputMap.create() از «کیت توسعه نرم‌افزار ورودی» 1.0.0-beta منسوخ شده است. برای اختصاص دادن شناسه نسخه، انصراف کامل از ویژگی تغییر کلید، یا اختصاص دادن فهرستی از کلیدهای رزروشده برای بازی‌تان که نمی‌خواهید کاربر از آن‌ها برای تغییر کلید استفاده کند، InputMap را به‌روز کنید. هر InputMap تعریف‌شده بااستفاده از «کیت توسعه نرم‌افزار ورودی» 1.0.0-beta روش create() به‌طور پیش‌فرض قابل تخصیص مجدد است، با شناسه 0 شناسایی می‌شود، و هیچ کلید رزروشده‌ای ندارد.

‫InputMap در Input 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)
);

‫InputMap در Input SDK 1.1.1-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()
                )
        )
);

قدم بعدی چیست

با اختصاص دادن کنترل‌های مختلف برای صحنه‌های مختلف بااستفاده از InputContexts یا به‌روزرسانی واسط کاربر بازی‌تان با دریافت اعلان درباره رویدادهای تخصیص مجدد بااستفاده از InputRemappingListeners، ارتقا به نسخه 1.1.1-beta را ادامه دهید.

هنگام به‌روزرسانی کلیدهای اختصاصی، به روال‌های مطلوب برای طراحی کلیدهای اختصاصی نگاهی بیندازید و محدودیت‌ها و محدودیت‌های ویژگی تخصیص مجدد را درنظر بگیرید.