Поддержка контроллеров в разных версиях Android

Если вы хотите добавить поддержку игровых контроллеров, убедитесь, что игра корректно реагирует на них на устройствах с разными версиями Android. Это позволит расширить аудиторию игры и обеспечить удобный геймплей с контроллерами, даже если пользователи сменят или обновят свои устройства Android.

В этом уроке показано, как использовать API, доступные в Android 4.1 и более поздних версиях, с обратной совместимостью, что позволяет вашей игре поддерживать следующие функции на устройствах под управлением Android 3.1 и более поздних версий:

  • Игра может определить, когда контроллер добавляется, меняется или удаляется.
  • Игра может запрашивать информацию о возможностях игрового контроллера.
  • Игра может распознавать входящие события движения от игрового контроллера.

Подготовка к абстрагированию API для поддержки игровых контроллеров

Предположим, вы хотите определить, изменился ли статус подключения игрового контроллера на устройствах с Android 3.1 (уровень API 12). Однако эти API доступны только в Android 4.1 (API уровня 16) и более поздних версиях. Поэтому вам нужно обеспечить поддержку Android 4.1 и более поздних версий, а также резервный механизм, поддерживающий Android 3.1–4.0.

Чтобы вам было проще определить, для каких функций требуется резервный механизм в более ранних версиях, в таблице 1 перечислены различия в поддержке игровых контроллеров между Android 3.1 (уровень API 12) и 4.1 (уровень API 16).

Таблица 1. API для поддержки игровых контроллеров в разных версиях Android.

Информация о контроллере Controller API Уровень API 12 Уровень API 16
Идентификация устройства getInputDeviceIds()   •
getInputDevice()   •
getVibrator()   •
SOURCE_JOYSTICK • •
SOURCE_GAMEPAD • •
Статус подключения onInputDeviceAdded()   •
onInputDeviceChanged()   •
onInputDeviceRemoved()   •
Идентификация событий ввода Нажатие кнопки на крестовине ( KEYCODE_DPAD_UP, KEYCODE_DPAD_DOWN, KEYCODE_DPAD_LEFT, KEYCODE_DPAD_RIGHT, KEYCODE_DPAD_CENTER) • •
Нажатие кнопки геймпада ( BUTTON_A, BUTTON_B, BUTTON_THUMBL, BUTTON_THUMBR, BUTTON_SELECT, BUTTON_START, BUTTON_R1, BUTTON_L1, BUTTON_R2, BUTTON_L2) • •
Движение джойстика и переключателя ( AXIS_X, AXIS_Y, AXIS_Z, AXIS_RZ, AXIS_HAT_X, AXIS_HAT_Y) • •
Нажатие аналогового триггера ( AXIS_LTRIGGER, AXIS_RTRIGGER) • •

Вы можете использовать абстракцию, чтобы создать поддержку игровых контроллеров с учетом версий, которая будет работать на разных платформах. Этот подход включает следующие шаги:

  1. Определите промежуточный интерфейс Java, который абстрагирует реализацию функций игрового контроллера, необходимых для вашей игры.
  2. Создайте прокси-реализацию интерфейса, в которой используются API из Android 4.1 и более поздних версий.
  3. Создайте собственную реализацию интерфейса, в которой используются API, доступные в Android 3.1–4.0.
  4. Создайте логику для переключения между этими реализациями во время выполнения и начните использовать интерфейс в игре.

О том, как с помощью абстракции проверить, что приложения могут работать в режиме обратной совместимости в разных версиях Android, рассказывается в статье Создание интерфейсов с обратной совместимостью.

Добавьте интерфейс для обратной совместимости

Чтобы обеспечить обратную совместимость, вы можете создать собственный интерфейс, а затем добавить реализации для конкретных версий. Преимущество такого подхода заключается в том, что вы можете дублировать общедоступные интерфейсы Android 4.1 (уровень API 16), которые поддерживают игровые контроллеры.

Kotlin

// The InputManagerCompat interface is a reference example.
// The full code is provided in the ControllerSample.zip sample.
interface InputManagerCompat {
    val inputDeviceIds: IntArray
    fun getInputDevice(id: Int): InputDevice

    fun registerInputDeviceListener(
            listener: InputManager.InputDeviceListener,
            handler: Handler?
    )

    fun unregisterInputDeviceListener(listener:InputManager.InputDeviceListener)

    fun onGenericMotionEvent(event: MotionEvent)

    fun onPause()
    fun onResume()

    interface InputDeviceListener {
        fun onInputDeviceAdded(deviceId: Int)
        fun onInputDeviceChanged(deviceId: Int)
        fun onInputDeviceRemoved(deviceId: Int)
    }
}

Java

// The InputManagerCompat interface is a reference example.
// The full code is provided in the ControllerSample.zip sample.
public interface InputManagerCompat {
    ...
    public InputDevice getInputDevice(int id);
    public int[] getInputDeviceIds();

    public void registerInputDeviceListener(
            InputManagerCompat.InputDeviceListener listener,
            Handler handler);
    public void unregisterInputDeviceListener(
            InputManagerCompat.InputDeviceListener listener);

    public void onGenericMotionEvent(MotionEvent event);

    public void onPause();
    public void onResume();

    public interface InputDeviceListener {
        void onInputDeviceAdded(int deviceId);
        void onInputDeviceChanged(int deviceId);
        void onInputDeviceRemoved(int deviceId);
    }
    ...
}

Интерфейс InputManagerCompat предоставляет следующие методы:

getInputDevice()
ЗеркалаgetInputDevice(). Получает объект InputDevice, представляющий возможности игрового контроллера.
getInputDeviceIds()
ЗеркалаgetInputDeviceIds(). Возвращает массив целых чисел, каждое из которых является идентификатором устройства ввода. Это полезно, если вы создаете многопользовательскую игру и хотите определить, сколько контроллеров подключено.
registerInputDeviceListener()
ЗеркалаregisterInputDeviceListener(). Позволяет зарегистрироваться, чтобы получать уведомления о добавлении, изменении или удалении устройства.
unregisterInputDeviceListener()
ЗеркалаunregisterInputDeviceListener(). Отменяет регистрацию прослушивателя устройства ввода.
onGenericMotionEvent()
ЗеркалаonGenericMotionEvent(). Позволяет игре перехватывать и обрабатывать объекты MotionEvent и значения осей, которые представляют события, например движения джойстика и нажатия аналоговых триггеров.
onPause()
Останавливает опрос событий игрового контроллера, когда основное действие приостановлено или игра больше не находится в фокусе.
onResume()
Начинает опрос событий игрового контроллера, когда возобновляется основное действие или когда игра запускается и работает на переднем плане.
InputDeviceListener
Дублирует интерфейс InputManager.InputDeviceListener. Сообщает игре, когда игровой контроллер был добавлен, изменен или удален.

Затем создайте реализации InputManagerCompat, которые будут работать на разных версиях платформы. Если игра запущена на устройстве с Android 4.1 или более поздней версии и вызывает метод InputManagerCompat, прокси-реализация вызывает эквивалентный метод в InputManager. Однако если игра работает на Android 3.1–4.0, то пользовательская реализация обрабатывает вызовы методов InputManagerCompat, используя только API, представленные не позднее Android 3.1. Независимо от того, какая реализация используется во время выполнения, результаты вызова передаются обратно в игру.

Диаграмма классов интерфейса и реализаций для конкретных версий.
Рисунок 1. Диаграмма классов интерфейса и реализаций для конкретных версий.

Реализация интерфейса на устройствах с Android 4.1 и более поздних версий

InputManagerCompatV16 – это реализация интерфейса InputManagerCompat, которая передает вызовы методов в InputManager и InputManager.InputDeviceListener. Значение InputManager берется из системного значения Context.

Kotlin

// The InputManagerCompatV16 class is a reference implementation.
// The full code is provided in the ControllerSample.zip sample.
public class InputManagerV16(
        context: Context,
        private val inputManager: InputManager =
            context.getSystemService(Context.INPUT_SERVICE) as InputManager,
        private val listeners:
            MutableMap<InputManager.InputDeviceListener, V16InputDeviceListener> = mutableMapOf()
) : InputManagerCompat {
    override val inputDeviceIds: IntArray = inputManager.inputDeviceIds

    override fun getInputDevice(id: Int): InputDevice = inputManager.getInputDevice(id)

    override fun registerInputDeviceListener(
            listener: InputManager.InputDeviceListener,
            handler: Handler?
    ) {
        V16InputDeviceListener(listener).also { v16listener ->
            inputManager.registerInputDeviceListener(v16listener, handler)
            listeners += listener to v16listener
        }
    }

    // Do the same for unregistering an input device listener
    ...

    override fun onGenericMotionEvent(event: MotionEvent) {
        // unused in V16
    }

    override fun onPause() {
        // unused in V16
    }

    override fun onResume() {
        // unused in V16
    }

}

class V16InputDeviceListener(
        private val idl: InputManager.InputDeviceListener
) : InputManager.InputDeviceListener {

    override fun onInputDeviceAdded(deviceId: Int) {
        idl.onInputDeviceAdded(deviceId)
    }
    // Do the same for device change and removal
    ...
}

Java

// The InputManagerCompatV16 class is a reference implementation.
// The full code is provided in the ControllerSample.zip sample.
public class InputManagerV16 implements InputManagerCompat {

    private final InputManager inputManager;
    private final Map<InputManagerCompat.InputDeviceListener,
            V16InputDeviceListener> listeners;

    public InputManagerV16(Context context) {
        inputManager = (InputManager)
                context.getSystemService(Context.INPUT_SERVICE);
        listeners = new HashMap<InputManagerCompat.InputDeviceListener,
                V16InputDeviceListener>();
    }

    @Override
    public InputDevice getInputDevice(int id) {
        return inputManager.getInputDevice(id);
    }

    @Override
    public int[] getInputDeviceIds() {
        return inputManager.getInputDeviceIds();
    }

    static class V16InputDeviceListener implements
            InputManager.InputDeviceListener {
        final InputManagerCompat.InputDeviceListener mIDL;

        public V16InputDeviceListener(InputDeviceListener idl) {
            mIDL = idl;
        }

        @Override
        public void onInputDeviceAdded(int deviceId) {
            mIDL.onInputDeviceAdded(deviceId);
        }

        // Do the same for device change and removal
        ...
    }

    @Override
    public void registerInputDeviceListener(InputDeviceListener listener,
            Handler handler) {
        V16InputDeviceListener v16Listener = new
                V16InputDeviceListener(listener);
        inputManager.registerInputDeviceListener(v16Listener, handler);
        listeners.put(listener, v16Listener);
    }

    // Do the same for unregistering an input device listener
    ...

    @Override
    public void onGenericMotionEvent(MotionEvent event) {
        // unused in V16
    }

    @Override
    public void onPause() {
        // unused in V16
    }

    @Override
    public void onResume() {
        // unused in V16
    }

}

Реализация интерфейса в Android 3.1–4.0

Чтобы создать реализацию InputManagerCompat, которая поддерживает Android 3.1–4.0, можно использовать следующие объекты:

  • SparseArray идентификаторов устройств, чтобы отслеживать игровые контроллеры, подключенные к устройству.
  • Handler для обработки событий на устройстве. При запуске или возобновлении работы приложения Handler получает сообщение о том, что нужно начать опрос на предмет отключения игрового контроллера. Handler запустит цикл, чтобы проверить каждый подключенный игровой контроллер и узнать, возвращается ли идентификатор устройства. Значение null указывает на то, что игровой контроллер отключен. Когда приложение приостановлено, Handler прекращает опрос.
  • Map объектов InputManagerCompat.InputDeviceListener. Вы будете использовать прослушиватели, чтобы обновлять статус подключения отслеживаемых игровых контроллеров.

Kotlin

// The InputManagerCompatV9 class is a reference implementation.
// The full code is provided in the ControllerSample.zip sample.
class InputManagerV9(
        val devices: SparseArray<Array<Long>> = SparseArray(),
        private val listeners:
        MutableMap<InputManager.InputDeviceListener, Handler> = mutableMapOf()
) : InputManagerCompat {
    private val defaultHandler: Handler = PollingMessageHandler(this)
    …
}

Java

// The InputManagerCompatV9 class is a reference implementation.
// The full code is provided in the ControllerSample.zip sample.
public class InputManagerV9 implements InputManagerCompat {
    private final SparseArray<long[]> devices;
    private final Map<InputDeviceListener, Handler> listeners;
    private final Handler defaultHandler;
    …

    public InputManagerV9() {
        devices = new SparseArray<long[]>();
        listeners = new HashMap<InputDeviceListener, Handler>();
        defaultHandler = new PollingMessageHandler(this);
    }
}

Реализуйте объект PollingMessageHandler, который расширяет Handler, и переопределите метод handleMessage(). Этот метод проверяет, был ли отключен подключенный игровой контроллер, и уведомляет зарегистрированных слушателей.

Kotlin

private class PollingMessageHandler(
        inputManager: InputManagerV9,
        private val mInputManager: WeakReference<InputManagerV9> = WeakReference(inputManager)
) : Handler() {

    override fun handleMessage(msg: Message) {
        super.handleMessage(msg)
        when (msg.what) {
            MESSAGE_TEST_FOR_DISCONNECT -> {
                mInputManager.get()?.also { imv ->
                    val time = SystemClock.elapsedRealtime()
                    val size = imv.devices.size()
                    for (i in 0 until size) {
                        imv.devices.valueAt(i)?.also { lastContact ->
                            if (time - lastContact[0] > CHECK_ELAPSED_TIME) {
                                // check to see if the device has been
                                // disconnected
                                val id = imv.devices.keyAt(i)
                                if (null == InputDevice.getDevice(id)) {
                                    // Notify the registered listeners
                                    // that the game controller is disconnected
                                    imv.devices.remove(id)
                                } else {
                                    lastContact[0] = time
                                }
                            }
                        }
                    }
                    sendEmptyMessageDelayed(MESSAGE_TEST_FOR_DISCONNECT, CHECK_ELAPSED_TIME)
                }
            }
        }
    }
}

Java

private static class PollingMessageHandler extends Handler {
    private final WeakReference<InputManagerV9> inputManager;

    PollingMessageHandler(InputManagerV9 im) {
        inputManager = new WeakReference<InputManagerV9>(im);
    }

    @Override
    public void handleMessage(Message msg) {
        super.handleMessage(msg);
        switch (msg.what) {
            case MESSAGE_TEST_FOR_DISCONNECT:
                InputManagerV9 imv = inputManager.get();
                if (null != imv) {
                    long time = SystemClock.elapsedRealtime();
                    int size = imv.devices.size();
                    for (int i = 0; i < size; i++) {
                        long[] lastContact = imv.devices.valueAt(i);
                        if (null != lastContact) {
                            if (time - lastContact[0] > CHECK_ELAPSED_TIME) {
                                // check to see if the device has been
                                // disconnected
                                int id = imv.devices.keyAt(i);
                                if (null == InputDevice.getDevice(id)) {
                                    // Notify the registered listeners
                                    // that the game controller is disconnected
                                    imv.devices.remove(id);
                                } else {
                                    lastContact[0] = time;
                                }
                            }
                        }
                    }
                    sendEmptyMessageDelayed(MESSAGE_TEST_FOR_DISCONNECT,
                            CHECK_ELAPSED_TIME);
                }
                break;
        }
    }
}

Чтобы запустить и остановить опрос на предмет отключения игрового контроллера, переопределите следующие методы:

Kotlin

private const val MESSAGE_TEST_FOR_DISCONNECT = 101
private const val CHECK_ELAPSED_TIME = 3000L

class InputManagerV9(
        val devices: SparseArray<Array<Long>> = SparseArray(),
        private val listeners:
        MutableMap<InputManager.InputDeviceListener, Handler> = mutableMapOf()
) : InputManagerCompat {
    ...
    override fun onPause() {
        defaultHandler.removeMessages(MESSAGE_TEST_FOR_DISCONNECT)
    }

    override fun onResume() {
        defaultHandler.sendEmptyMessageDelayed(MESSAGE_TEST_FOR_DISCONNECT, CHECK_ELAPSED_TIME)
    }
    ...
}

Java

private static final int MESSAGE_TEST_FOR_DISCONNECT = 101;
private static final long CHECK_ELAPSED_TIME = 3000L;

@Override
public void onPause() {
    defaultHandler.removeMessages(MESSAGE_TEST_FOR_DISCONNECT);
}

@Override
public void onResume() {
    defaultHandler.sendEmptyMessageDelayed(MESSAGE_TEST_FOR_DISCONNECT,
            CHECK_ELAPSED_TIME);
}

Чтобы определить, что устройство ввода было добавлено, переопределите метод onGenericMotionEvent(). Когда система сообщает о событии движения, проверьте, поступило ли это событие от идентификатора устройства, который уже отслеживается, или от нового идентификатора устройства. Если идентификатор устройства новый, уведомите зарегистрированных слушателей.

Kotlin

override fun onGenericMotionEvent(event: MotionEvent) {
    // detect new devices
    val id = event.deviceId
    val timeArray: Array<Long> = mDevices.get(id) ?: run {
        // Notify the registered listeners that a game controller is added
        ...
        arrayOf<Long>().also {
            mDevices.put(id, it)
        }
    }
    timeArray[0] = SystemClock.elapsedRealtime()
}

Java

@Override
public void onGenericMotionEvent(MotionEvent event) {
    // detect new devices
    int id = event.getDeviceId();
    long[] timeArray = mDevices.get(id);
    if (null == timeArray) {
        // Notify the registered listeners that a game controller is added
        ...
        timeArray = new long[1];
        mDevices.put(id, timeArray);
    }
    long time = SystemClock.elapsedRealtime();
    timeArray[0] = time;
}

Уведомление прослушивателей реализуется с помощью объекта Handler, который отправляет объект DeviceEvent Runnable в очередь сообщений. Объект DeviceEvent содержит ссылку на объект InputManagerCompat.InputDeviceListener. При запуске DeviceEvent вызывается соответствующий метод обратного вызова прослушивателя, чтобы сообщить, был ли добавлен, изменен или удален игровой контроллер.

Kotlin

class InputManagerV9(
        val devices: SparseArray<Array<Long>> = SparseArray(),
        private val listeners:
        MutableMap<InputManager.InputDeviceListener, Handler> = mutableMapOf()
) : InputManagerCompat {
    ...
    override fun registerInputDeviceListener(
            listener: InputManager.InputDeviceListener,
            handler: Handler?
    ) {
        listeners[listener] = handler ?: defaultHandler
    }

    override fun unregisterInputDeviceListener(listener: InputManager.InputDeviceListener) {
        listeners.remove(listener)
    }

    private fun notifyListeners(why: Int, deviceId: Int) {
        // the state of some device has changed
        listeners.forEach { listener, handler ->
            DeviceEvent.getDeviceEvent(why, deviceId, listener).also {
                handler?.post(it)
            }
        }
    }
    ...
}

private val sObjectQueue: Queue<DeviceEvent> = ArrayDeque<DeviceEvent>()

private class DeviceEvent(
        private var mMessageType: Int,
        private var mId: Int,
        private var mListener: InputManager.InputDeviceListener
) : Runnable {

    companion object {
        fun getDeviceEvent(messageType: Int, id: Int, listener: InputManager.InputDeviceListener) =
                sObjectQueue.poll()?.apply {
                    mMessageType = messageType
                    mId = id
                    mListener = listener
                } ?: DeviceEvent(messageType, id, listener)

    }

    override fun run() {
        when(mMessageType) {
            ON_DEVICE_ADDED -> mListener.onInputDeviceAdded(mId)
            ON_DEVICE_CHANGED -> mListener.onInputDeviceChanged(mId)
            ON_DEVICE_REMOVED -> mListener.onInputDeviceChanged(mId)
            else -> {
                // Handle unknown message type
            }
        }
    }

}

Java

@Override
public void registerInputDeviceListener(InputDeviceListener listener,
        Handler handler) {
    listeners.remove(listener);
    if (handler == null) {
        handler = defaultHandler;
    }
    listeners.put(listener, handler);
}

@Override
public void unregisterInputDeviceListener(InputDeviceListener listener) {
    listeners.remove(listener);
}

private void notifyListeners(int why, int deviceId) {
    // the state of some device has changed
    if (!listeners.isEmpty()) {
        for (InputDeviceListener listener : listeners.keySet()) {
            Handler handler = listeners.get(listener);
            DeviceEvent odc = DeviceEvent.getDeviceEvent(why, deviceId,
                    listener);
            handler.post(odc);
        }
    }
}

private static class DeviceEvent implements Runnable {
    private int mMessageType;
    private int mId;
    private InputDeviceListener mListener;
    private static Queue<DeviceEvent> sObjectQueue =
            new ArrayDeque<DeviceEvent>();
    ...

    static DeviceEvent getDeviceEvent(int messageType, int id,
            InputDeviceListener listener) {
        DeviceEvent curChanged = sObjectQueue.poll();
        if (null == curChanged) {
            curChanged = new DeviceEvent();
        }
        curChanged.mMessageType = messageType;
        curChanged.mId = id;
        curChanged.mListener = listener;
        return curChanged;
    }

    @Override
    public void run() {
        switch (mMessageType) {
            case ON_DEVICE_ADDED:
                mListener.onInputDeviceAdded(mId);
                break;
            case ON_DEVICE_CHANGED:
                mListener.onInputDeviceChanged(mId);
                break;
            case ON_DEVICE_REMOVED:
                mListener.onInputDeviceRemoved(mId);
                break;
            default:
                // Handle unknown message type
                ...
                break;
        }
        // Put this runnable back in the queue
        sObjectQueue.offer(this);
    }
}

Теперь у вас есть две реализации InputManagerCompat: одна работает на устройствах с Android 4.1 и более поздними версиями, а другая – на устройствах с Android 3.1–4.0.

Используйте реализацию для конкретной версии

Логика переключения между версиями реализована в классе, который действует как фабрика.

Kotlin

object Factory {
    fun getInputManager(context: Context): InputManagerCompat =
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.JELLY_BEAN) {
                InputManagerV16(context)
            } else {
                InputManagerV9()
            }
}

Java

public static class Factory {
    public static InputManagerCompat getInputManager(Context context) {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.JELLY_BEAN) {
            return new InputManagerV16(context);
        } else {
            return new InputManagerV9();
        }
    }
}

Теперь вы можете создать экземпляр объекта InputManagerCompat и зарегистрировать InputManagerCompat.InputDeviceListener в основном файле View. Благодаря логике переключения версий, которую вы настроили, игра автоматически использует реализацию, подходящую для версии Android, установленной на устройстве.

Kotlin

class GameView(context: Context) : View(context), InputManager.InputDeviceListener {
    private val inputManager: InputManagerCompat = Factory.getInputManager(context).apply {
        registerInputDeviceListener(this@GameView, null)
        ...
    }
    ...
}

Java

public class GameView extends View implements InputDeviceListener {
    private InputManagerCompat inputManager;
    ...

    public GameView(Context context, AttributeSet attrs) {
        inputManager =
                InputManagerCompat.Factory.getInputManager(this.getContext());
        inputManager.registerInputDeviceListener(this, null);
        ...
    }
}

Затем переопределите метод onGenericMotionEvent() в основном представлении, как описано в разделе Обработка MotionEvent от игрового контроллера. Теперь ваша игра должна стабильно обрабатывать события игрового контроллера на устройствах с Android 3.1 (уровень API).

Kotlin

override fun onGenericMotionEvent(event: MotionEvent): Boolean {
    inputManager.onGenericMotionEvent(event)

    // Handle analog input from the controller as normal
    ...
    return super.onGenericMotionEvent(event)
}

Java

@Override
public boolean onGenericMotionEvent(MotionEvent event) {
    inputManager.onGenericMotionEvent(event);

    // Handle analog input from the controller as normal
    ...
    return super.onGenericMotionEvent(event);
}

Полную реализацию этого кода совместимости можно найти в классе GameView, который предоставляется в примере ControllerSample.zip, доступном для скачивания.