Si admites controles para juegos en tu juego, es tu responsabilidad asegurarte de que este responda a los controles de manera coherente en todos los dispositivos que se ejecuten en diferentes versiones de Android. Esto permite que tu juego llegue a un público más amplio, y que los jugadores puedan disfrutar de una experiencia de juego sin interrupciones con sus controles, incluso cuando cambian o actualizan sus dispositivos Android.
En esta lección, se muestra cómo usar las APIs disponibles en Android 4.1 y versiones posteriores de manera retrocompatible, lo que permite que tu juego sea compatible con las siguientes funciones en dispositivos que ejecutan Android 3.1 y versiones posteriores:
- El juego puede detectar si se agrega, cambia o quita un nuevo control para videojuegos.
- El juego puede consultar las capacidades de un control para videojuegos.
- El juego puede reconocer eventos de movimiento entrantes de un control para videojuegos.
Los ejemplos de esta lección se basan en la implementación de referencia que proporciona el archivo ControllerSample.zip
de muestra disponible para descargar en la parte superior de la página. En este ejemplo, se muestra cómo implementar la interfaz InputManagerCompat
para admitir diferentes versiones de Android. Para compilar la muestra, debes usar Android 4.1 (nivel de API 16) o una versión posterior. Una vez compilada, la app de ejemplo se ejecuta en cualquier dispositivo que ejecute Android 3.1 (nivel de API 12) o una versión posterior como objetivo de compilación.
Cómo prepararse para abstraer las API a fin de agregar compatibilidad con controles para videojuegos
Supongamos que quieres poder determinar si cambió el estado de conexión de un control para videojuegos en dispositivos con Android 3.1 (nivel de API 12). Sin embargo, las APIs solo están disponibles en Android 4.1 (nivel de API 16) y versiones posteriores, por lo que debes proporcionar una implementación que admita Android 4.1 y versiones posteriores, y, al mismo tiempo, brindar un mecanismo de resguardo que admita desde Android 3.1 hasta Android 4.0.
Para ayudarte a determinar qué funciones requieren este mecanismo de resguardo para versiones anteriores, en la tabla 1, se enumeran las diferencias en la compatibilidad de los controles para juegos entre Android 3.1 (nivel de API 12) y 4.1 (nivel de API 16).
Información del control | API del control | API nivel 12 | API nivel 16 |
---|---|---|---|
Identificación del dispositivo | getInputDeviceIds() |
• | |
getInputDevice() |
• | ||
getVibrator() |
• | ||
SOURCE_JOYSTICK |
• | • | |
SOURCE_GAMEPAD |
• | • | |
Estado de la conexión | onInputDeviceAdded() |
• | |
onInputDeviceChanged() |
• | ||
onInputDeviceRemoved() |
• | ||
Identificación del evento de entrada | Pulsación en el pad direccional (KEYCODE_DPAD_UP , KEYCODE_DPAD_DOWN , KEYCODE_DPAD_LEFT , KEYCODE_DPAD_RIGHT , KEYCODE_DPAD_CENTER ) |
• | • |
Presión del botón del control de juegos (BUTTON_A , BUTTON_B , BUTTON_THUMBL , BUTTON_THUMBR , BUTTON_SELECT , BUTTON_START , BUTTON_R1 , BUTTON_L1 , BUTTON_R2 , BUTTON_L2 ) |
• | • | |
Movimiento del joystick y del interruptor de sombrero (AXIS_X , AXIS_Y , AXIS_Z , AXIS_RZ , AXIS_HAT_X y AXIS_HAT_Y ) |
• | • | |
Pulsación del gatillo analógico (AXIS_LTRIGGER , AXIS_RTRIGGER ) |
• | • |
Puedes usar la abstracción para compilar una compatibilidad con controles de juegos con reconocimiento de versiones que funcione en todas las plataformas. Este enfoque requiere los siguientes pasos:
- Define una interfaz Java intermediaria que abstraiga la implementación de las funciones de controles para juegos que requiere tu juego.
- Crea una implementación de proxy de tu interfaz que use las APIs en Android 4.1 y versiones posteriores.
- Crea una implementación personalizada de tu interfaz que use las APIs disponibles entre Android 3.1 y Android 4.0.
- Crea la lógica para alternar entre estas implementaciones durante el tiempo de ejecución y comienza a usar la interfaz en tu juego.
Para obtener una descripción general de cómo se puede usar la abstracción para garantizar que las aplicaciones puedan funcionar con versiones anteriores de Android, consulta Cómo crear IU retrocompatibles.
Cómo agregar una interfaz para lograr la compatibilidad con versiones anteriores
Para brindar retrocompatibilidad, puedes crear una interfaz personalizada y, luego, agregar implementaciones específicas de la versión. Una ventaja de este enfoque es que te permite duplicar las interfaces públicas de Android 4.1 (nivel de API 16) que son compatibles con los controles de juegos.
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); } ... }
La interfaz InputManagerCompat
proporciona los siguientes métodos:
getInputDevice()
-
Duplica
getInputDevice()
. Obtiene el objetoInputDevice
que representa las capacidades de un control para videojuegos. getInputDeviceIds()
-
Duplica
getInputDeviceIds()
. Muestra un array de números enteros, cada uno de los cuales es un ID para un dispositivo de entrada diferente. Esto es útil si estás compilando un juego que admite varios jugadores y quieres detectar cuántos controles están conectados. registerInputDeviceListener()
-
Duplica
registerInputDeviceListener()
. Te permite registrarte para recibir una notificación cuando se agrega, cambia o quita un dispositivo nuevo. unregisterInputDeviceListener()
-
Duplica
unregisterInputDeviceListener()
. Cancela el registro de un objeto de escucha de dispositivos de entrada. onGenericMotionEvent()
-
Duplica
onGenericMotionEvent()
. Te permite interceptar y controlar objetosMotionEvent
y valores de ejes que representan eventos como movimientos de joysticks y pulsaciones de gatillos analógicos. onPause()
- Deja de realizar el sondeo de eventos de controles para juegos cuando se pausa la actividad principal o cuando el juego ya no está enfocado.
onResume()
- Inicia el sondeo de eventos de controles para juegos cuando se reanuda la actividad principal o cuando el juego se inicia y se ejecuta en primer plano.
InputDeviceListener
- Duplica la interfaz
InputManager.InputDeviceListener
. Le permite a tu juego saber cuándo se agregó, cambió o quitó un control para videojuegos.
A continuación, crea implementaciones para InputManagerCompat
que funcionen en diferentes versiones de la plataforma. Si tu juego se ejecuta en Android 4.1 o versiones posteriores y llama a un método InputManagerCompat
, la implementación de proxy llama al método equivalente en InputManager
.
Sin embargo, si tu juego se ejecuta en Android 3.1 hasta Android 4.0, la implementación personalizada procesa las llamadas a los métodos InputManagerCompat
solo mediante el uso de APIs introducidas antes de Android 3.1. Independientemente de la implementación específica de la versión que se use durante el tiempo de ejecución, la implementación pasa los resultados de la llamada al juego de manera transparente.
Cómo implementar la interfaz en Android 4.1 y versiones posteriores
InputManagerCompatV16
es una implementación de la interfaz InputManagerCompat
que utiliza un proxy en las llamadas de método a un InputManager
y un InputManager.InputDeviceListener
reales. El InputManager
se obtiene del sistema 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 } }
Cómo implementar la interfaz desde Android 3.1 hasta Android 4.0
Para crear una implementación de InputManagerCompat
que admita desde Android 3.1 hasta Android 4.0, puedes usar los siguientes objetos:
- Un
SparseArray
de IDs de dispositivos a fin de hacer un seguimiento de los controles para juegos que se conectan al dispositivo. - Un
Handler
para procesar eventos de dispositivos. Cuando se inicia o reanuda una app,Handler
recibe un mensaje a fin de comenzar a sondear la desconexión del control para juegos.Handler
iniciará un bucle a fin de verificar cada control para videojuegos conocido conectado y ver si se muestra un ID de dispositivo. Un valor que se muestranull
indica que el control para videojuegos está desconectado. ElHandler
deja de sondear cuando se pausa la app. - Una
Map
de objetosInputManagerCompat.InputDeviceListener
. Usarás los objetos de escucha a fin de actualizar el estado de conexión de los controles para videojuegos registrados.
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); } }
Implementa un objeto PollingMessageHandler
que extienda Handler
y anula el método handleMessage()
. Este método verifica si se desconectó un control para videojuegos y notifica a los objetos de escucha registrados.
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; } } }
Si quieres iniciar y detener el sondeo de desconexión de controles para juegos, anula estos métodos:
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); }
Para detectar si se agregó un dispositivo de entrada, anula el método onGenericMotionEvent()
. Cuando el sistema informe un evento de movimiento, comprueba si el evento provino de un ID de dispositivo que ya esté registrado o de un ID de dispositivo nuevo. Si es nuevo, infórmalo a los objetos de escucha registrados.
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; }
Las notificaciones de los objetos de escucha se implementan mediante el objeto Handler
para enviar un objeto DeviceEvent
Runnable
a la cola de mensajes. El DeviceEvent
contiene una referencia a un InputManagerCompat.InputDeviceListener
. Cuando se ejecuta el DeviceEvent
, se llama al método de devolución de llamada apropiado del objeto de escucha para indicar si se agregó, cambió o quitó el control para videojuegos.
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); } }
Ahora tienes dos implementaciones de InputManagerCompat
: una que funciona en dispositivos que ejecutan Android 4.1 y versiones posteriores, y otra que funciona en dispositivos que ejecutan desde Android 3.1 hasta Android 4.0.
Cómo usar la implementación específica de la versión
La lógica de cambio específica de la versión se implementa en una clase que actúa como fábrica.
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(); } } }
Ahora, simplemente puedes crear una instancia de un objeto InputManagerCompat
y registrar un InputManagerCompat.InputDeviceListener
en tu View
principal. Debido a la lógica de cambio de versión que configuras, tu juego usa automáticamente la implementación adecuada para la versión de Android que ejecuta el dispositivo.
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); ... } }
Luego, anula el método onGenericMotionEvent()
en tu vista principal, como se describe en Cómo controlar un MotionEvent desde un controlador de juego. Ahora tu juego debería poder procesar eventos de controles para videojuegos de manera coherente en dispositivos que ejecuten Android 3.1 (nivel de API 12) y versiones posteriores.
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); }
Puedes encontrar una implementación completa de este código de compatibilidad en la clase GameView
proporcionada en el ControllerSample.zip
de muestra, disponible para descargar en la parte superior de la página.