SDK ورودی جاوا و کاتلین را به نسخه 1.1 ارتقا دهید

این راهنما نحوه‌ی ارتقاء بازی شما از نسخه بتای ۱.۰.۰ Input SDK برای جاوا و کاتلین به نسخه بتای ۱.۱.۱ را توضیح می‌دهد. برای دستورالعمل‌های خاص یونیتی، به راهنمای ارتقاء یونیتی مراجعه کنید.

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

گوگل پلی گیمز روی کامپیوتر از تغییر نقشه کنترل‌های کیبورد بر اساس کلیدهای اتصالی که بازی شما با استفاده از Input SDK ارائه می‌دهد، پشتیبانی می‌کند.

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

بازی‌های گوگل پلی روی کامپیوتر، هر ورودی تغییر یافته توسط کاربر را به ورودی پیش‌فرض بازی شما نگاشت می‌کند. به این ترتیب، بازی شما نیازی به آگاهی از تغییر نگاشت توسط بازیکن ندارد. اگر برای یک اقدام درون بازی، مانند نمایش کنترل‌های صفحه کلید در بازی خود، نیاز به دانستن ورودی جدید دارید، می‌توانید به صورت اختیاری یک فراخوانی ثبت کنید تا از رویدادهای تغییر نگاشت مطلع شوید.

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

برای فعال کردن تغییر نقشه کلید در بازی خود، نیازی به ارتقاء Input SDK ندارید، اما در صورت شناسایی پیکربندی پشتیبانی نشده ، می‌توان تغییر نقشه را برای بازی شما غیرفعال کرد.

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

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

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

  • به Input SDK 1.1.1-beta ارتقا دهید.
  • InputMap خود را به‌روزرسانی کنید تا ویژگی نگاشت مجدد غیرفعال شود.

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

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

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

اگر شرایط زیر برقرار نباشد، نگاشت مجدد ورودی غیرفعال است:

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

  • دو یا چند شیء 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 را مطالعه کنید.

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

وابستگی به ارتقا

اگر از 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 تعریف کنید، زیرا این فیلدها از سایر بخش‌های برنامه شما قابل دسترسی هستند:

کاتلین

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() از Input SDK 1.0.0-beta منسوخ شده است. یک InputAction اکنون دارای یک شناسه نسخه است و می‌تواند به عنوان قابل تغییر یا غیر قابل تغییر علامت‌گذاری شود. یک InputAction که با استفاده از متد create() در Input SDK 1.0.0-beta تعریف شده است، به طور پیش‌فرض قابل تغییر است و فاقد اطلاعات نسخه‌بندی است:

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-beta

کاتلین

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

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

گروه‌های ورودی خود را به‌روزرسانی کنید

در Input SDK 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() از Input SDK 1.0.0-beta منسوخ شده است. شما باید InputGroup خود را در بازی خود با یک شناسه نسخه و مقدار بولی که نشان می‌دهد آیا اشیاء InputAction در گروه‌های شما قابل تغییر هستند یا خیر، به‌روزرسانی کنید. گروه‌هایی که با متد منسوخ‌شده Input SDK 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 در Input SDK 1.1.1-beta

کاتلین

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 در Input SDK 1.1.1-beta (همراه با رشته نسخه)

کاتلین

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() از Input SDK 1.0.0-beta منسوخ شده است. InputMap خود را به‌روزرسانی کنید تا یک شناسه نسخه اختصاص دهید، از ویژگی نگاشت مجدد به‌طور کامل انصراف دهید یا لیستی از کلیدهای رزرو شده برای بازی خود که نمی‌خواهید توسط کاربر برای نگاشت مجدد استفاده شود، اختصاص دهید. هر InputMap تعریف شده با استفاده از متد Input SDK 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 ، ارتقاء خود را به نسخه ۱.۱.۱-بتا ادامه دهید.

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