Input Manager Finalization - Docs and Cleanup (#2822)

* Start work on input docs for 4.0

* Initial write-up of InputManager programming guide

* small fix

* some docstrings and cleanup

* Handle input imports in top level package

* Add helper method for combined positive/negative inputs to InputManager

* Add basic sprite move example for InputManager

* Fix __all__

* More docstrings for InputManager

* InputManager updates for Pyglet 3.0 compatibility

* Update sprite_move_input_manager example

* Fix line lengths in example

* More example formatting

Author: Cleptomania

arcade/__init__.py

@@ -145,6 +145,17 @@ def configure_logging(level: int | None = None):
     from .controller import ControllerManager
     from .controller import get_controllers
 
+from .input import ActionState
+from .input import ControllerButtons
+from .input import ControllerSticks
+from .input import ControllerTriggers
+from .input import InputManager
+from .input import Keys
+from .input import MouseAxes
+from .input import MouseButtons
+from .input import PSControllerButtons
+from .input import XBoxControllerButtons
+
 from .sound import Sound
 from .sound import load_sound
 from .sound import play_sound
@@ -249,6 +260,16 @@ def configure_logging(level: int | None = None):
 )
 
 __all__ = [
+    "ActionState",
+    "ControllerButtons",
+    "ControllerSticks",
+    "ControllerTriggers",
+    "InputManager",
+    "Keys",
+    "MouseAxes",
+    "MouseButtons",
+    "PSControllerButtons",
+    "XBoxControllerButtons",
     "AStarBarrierList",
     "AnimatedWalkingSprite",
     "TextureAnimationSprite",

arcade/application.py

@@ -680,7 +680,7 @@ def on_mouse_press(self, x: int, y: int, button: int, modifiers: int) -> EVENT_H
 
             modifiers:
                 Bitwise 'and' of all modifiers (shift, ctrl, num lock)
-                active during this event. See :ref:`keyboard_modifiers`.
+                active during this event. See :ref:`pg_simple_input_keyboard_modifiers`.
         """
         pass
 
@@ -705,7 +705,7 @@ def on_mouse_drag(
                 Which button is pressed
             modifiers:
                 Bitwise 'and' of all modifiers (shift, ctrl, num lock)
-                active during this event. See :ref:`keyboard_modifiers`.
+                active during this event. See :ref:`pg_simple_input_keyboard_modifiers`.
         """
         return self.on_mouse_motion(x, y, dx, dy)
 
@@ -730,7 +730,7 @@ def on_mouse_release(self, x: int, y: int, button: int, modifiers: int) -> EVENT
                 - ``arcade.MOUSE_BUTTON_MIDDLE``
             modifiers:
                 Bitwise 'and' of all modifiers (shift, ctrl, num lock)
-                active during this event. See :ref:`keyboard_modifiers`.
+                active during this event. See :ref:`pg_simple_input_keyboard_modifiers`.
         """
         return EVENT_UNHANDLED
 
@@ -831,7 +831,7 @@ def on_key_press(self, symbol: int, modifiers: int) -> EVENT_HANDLE_STATE:
                 Key that was just pushed down
             modifiers:
                 Bitwise 'and' of all modifiers (shift, ctrl, num lock)
-                active during this event. See :ref:`keyboard_modifiers`.
+                active during this event. See :ref:`pg_simple_input_keyboard_modifiers`.
         """
         return EVENT_UNHANDLED
 
@@ -853,7 +853,7 @@ def on_key_release(self, symbol: int, modifiers: int) -> EVENT_HANDLE_STATE:
             symbol (int): Key that was released
             modifiers (int): Bitwise 'and' of all modifiers (shift,
                       ctrl, num lock) active during this event.
-                      See :ref:`keyboard_modifiers`.
+                      See :ref:`pg_simple_input_keyboard_modifiers`.
         """
         return EVENT_UNHANDLED
 
@@ -1440,7 +1440,7 @@ def on_mouse_press(self, x: int, y: int, button: int, modifiers: int) -> bool |
 
             modifiers:
                 Bitwise 'and' of all modifiers (shift, ctrl, num lock)
-                active during this event. See :ref:`keyboard_modifiers`.
+                active during this event. See :ref:`pg_simple_input_keyboard_modifiers`.
         """
         pass
 
@@ -1465,7 +1465,7 @@ def on_mouse_drag(
                 Which button is pressed
             _modifiers:
                 Bitwise 'and' of all modifiers (shift, ctrl, num lock)
-                active during this event. See :ref:`keyboard_modifiers`.
+                active during this event. See :ref:`pg_simple_input_keyboard_modifiers`.
         """
         self.on_mouse_motion(x, y, dx, dy)
         return False
@@ -1492,7 +1492,7 @@ def on_mouse_release(self, x: int, y: int, button: int, modifiers: int) -> bool
 
             modifiers:
                 Bitwise 'and' of all modifiers (shift, ctrl, num lock)
-                active during this event. See :ref:`keyboard_modifiers`.
+                active during this event. See :ref:`pg_simple_input_keyboard_modifiers`.
         """
         pass
 
@@ -1547,7 +1547,7 @@ def on_key_press(self, symbol: int, modifiers: int) -> bool | None:
                 Key that was just pushed down
             modifiers:
                 Bitwise 'and' of all modifiers (shift, ctrl, num lock) active
-                during this event. See :ref:`keyboard_modifiers`.
+                during this event. See :ref:`pg_simple_input_keyboard_modifiers`.
         """
         return False
 
@@ -1570,7 +1570,7 @@ def on_key_release(self, symbol: int, modifiers: int) -> bool | None:
                 Key that was released
             modifiers:
                 Bitwise 'and' of all modifiers (shift, ctrl, num lock) active
-                during this event. See :ref:`keyboard_modifiers`.
+                during this event. See :ref:`pg_simple_input_keyboard_modifiers`.
         """
         return False
 

arcade/examples/sprite_move_input_manager.py

@@ -0,0 +1,156 @@
+"""
+Move Sprite With Keyboard or Controller using InputManager
+
+Simple program to show moving a sprite with the keyboard or controller via InputManager.
+This is similar to the behavior in sprite_move_controller and sprite_move_keyboard
+but combining the devices using Arcade's advanced input system.
+
+Artwork from https://kenney.nl
+
+If Python and Arcade are installed, this example can be run from the command line with:
+python -m arcade.examples.sprite_move_input_manager
+"""
+
+import arcade
+
+SPRITE_SCALING = 0.5
+
+WINDOW_WIDTH = 1280
+WINDOW_HEIGHT = 720
+WINDOW_TITLE = "Move Sprite with InputManager Example"
+
+MOVEMENT_SPEED = 5
+
+
+class Player(arcade.Sprite):
+
+    def update(self, delta_time: float = 1/60):
+        """ Move the player """
+        # Move player.
+        # Remove these lines if physics engine is moving player.
+        self.center_x += self.change_x
+        self.center_y += self.change_y
+
+        # Check for out-of-bounds
+        if self.left < 0:
+            self.left = 0
+        elif self.right > WINDOW_WIDTH - 1:
+            self.right = WINDOW_WIDTH - 1
+
+        if self.bottom < 0:
+            self.bottom = 0
+        elif self.top > WINDOW_HEIGHT - 1:
+            self.top = WINDOW_HEIGHT - 1
+
+
+class GameView(arcade.View):
+    """
+    Main application class.
+    """
+
+    def __init__(self):
+        """
+        Initializer
+        """
+
+        # Call the parent class initializer
+        super().__init__()
+
+        # Set our controller to None, this will get changed if we find a connected controller
+        controller = None
+
+        # Ask arcade for a list of connected controllers
+        controllers = arcade.get_controllers()
+        if controllers:
+            # Just use the first one in the list for now
+            controller = controllers[0]
+
+        # Create a new InputManager, and assign our controller to it(if we have one)
+        self.input_manager = arcade.InputManager(controller)
+
+        # Add a new horizontal movement axis to the input manager.
+        # Also assign the LEFT/RIGHT arrow keys and left thumbstick to it
+        self.input_manager.new_axis("MoveHorizontal")
+        self.input_manager.add_axis_input_combined(
+            "MoveHorizontal",
+            arcade.Keys.RIGHT,
+            arcade.Keys.LEFT
+        )
+        self.input_manager.add_axis_input("MoveHorizontal", arcade.ControllerSticks.LEFT_STICK_X)
+
+        # Same thing for vertical movement axis
+        self.input_manager.new_axis("MoveVertical")
+        self.input_manager.add_axis_input_combined(
+            "MoveVertical",
+            arcade.Keys.UP,
+            arcade.Keys.DOWN
+        )
+        self.input_manager.add_axis_input("MoveVertical", arcade.ControllerSticks.LEFT_STICK_Y)
+
+        # Variables that will hold sprite lists
+        self.player_list = None
+
+        # Set up the player info
+        self.player_sprite = None
+
+        # Set the background color
+        self.background_color = arcade.color.AMAZON
+
+    def setup(self):
+        """ Set up the game and initialize the variables. """
+
+        # Sprite lists
+        self.player_list = arcade.SpriteList()
+
+        # Set up the player
+        self.player_sprite = Player(
+            ":resources:images/animated_characters/female_person/femalePerson_idle.png",
+            scale=SPRITE_SCALING,
+        )
+        self.player_sprite.center_x = 50
+        self.player_sprite.center_y = 50
+        self.player_list.append(self.player_sprite)
+
+    def on_draw(self):
+        """ Render the screen. """
+
+        # Clear the screen
+        self.clear()
+
+        # Draw all the sprites.
+        self.player_list.draw()
+
+    def on_update(self, delta_time):
+        """ Movement and game logic """
+
+        # Update the input manager so it has the latest values from our devices
+        self.input_manager.update()
+
+        # Apply the input axes to the player
+        self.player_sprite.change_x = self.input_manager.axis("MoveHorizontal") * MOVEMENT_SPEED
+        self.player_sprite.change_y = self.input_manager.axis("MoveVertical") * MOVEMENT_SPEED
+
+        # Call update to move the sprite
+        # If using a physics engine, call update player to rely on physics engine
+        # for movement, and call physics engine here.
+        self.player_list.update(delta_time)
+
+
+def main():
+    """ Main function """
+    # Create a window class. This is what actually shows up on screen
+    window = arcade.Window(WINDOW_WIDTH, WINDOW_HEIGHT, WINDOW_TITLE)
+
+    # Create and setup the GameView
+    game = GameView()
+    game.setup()
+
+    # Show GameView on screen
+    window.show_view(game)
+
+    # Start the arcade game loop
+    arcade.run()
+
+
+if __name__ == "__main__":
+    main()

arcade/input/__init__.py

@@ -2,8 +2,9 @@
 #  type: ignore
 
 from .inputs import (
-    ControllerAxes,
     ControllerButtons,
+    ControllerSticks,
+    ControllerTriggers,
     XBoxControllerButtons,
     PSControllerButtons,
     Keys,
@@ -14,8 +15,9 @@
 from .input_mapping import Action, ActionMapping, Axis, AxisMapping
 
 __all__ = [
-    "ControllerAxes",
     "ControllerButtons",
+    "ControllerSticks",
+    "ControllerTriggers",
     "XBoxControllerButtons",
     "PSControllerButtons",
     "Keys",

arcade/input/inputs.py

@@ -16,7 +16,8 @@ class InputType(Enum):
     MOUSE_BUTTON = 1
     MOUSE_AXIS = 2
     CONTROLLER_BUTTON = 3
-    CONTROLLER_AXIS = 4
+    CONTROLLER_AXIS_SINGLE = 4
+    CONTROLLER_AXIS_DOUBLE = 5
 
 
 class InputEnum(Enum):
@@ -39,19 +40,14 @@ def _generate_next_value_(name, *_):
         return name
 
 
-class ControllerAxes(StrEnum):
-    LEFT_STICK_X = "leftx"
-    LEFT_STICK_POSITIVE_X = "leftxpositive"
-    LEFT_STICK_NEGATIVE_X = "leftxnegative"
-    LEFT_STICK_Y = "lefty"
-    LEFT_STICK_POSITIVE_Y = "leftypositive"
-    LEFT_STICK_NEGATIVE_Y = "leftynegative"
-    RIGHT_STICK_X = "rightx"
-    RIGHT_STICK_POSITIVE_X = "rightxpositive"
-    RIGHT_STICK_NEGATIVE_X = "rightxnegative"
-    RIGHT_STICK_Y = "righty"
-    RIGHT_STICK_POSITIVE_Y = "rightypositive"
-    RIGHT_STICK_NEGATIVE_Y = "rightynegative"
+class ControllerSticks(StrEnum):
+    LEFT_STICK_X = "leftstickx"
+    LEFT_STICK_Y = "leftsticky"
+    RIGHT_STICK_X = "rightstickx"
+    RIGHT_STICK_Y = "rightsticky"
+
+
+class ControllerTriggers(StrEnum):
     LEFT_TRIGGER = "lefttrigger"
     RIGHT_TRIGGER = "righttrigger"
 
@@ -366,15 +362,17 @@ class MouseButtons(InputEnum):
     MouseButtons: InputType.MOUSE_BUTTON,
     MouseAxes: InputType.MOUSE_AXIS,
     ControllerButtons: InputType.CONTROLLER_BUTTON,
-    ControllerAxes: InputType.CONTROLLER_AXIS,
+    ControllerTriggers: InputType.CONTROLLER_AXIS_SINGLE,
+    ControllerSticks: InputType.CONTROLLER_AXIS_DOUBLE,
 }
 
 INPUT_TYPE_TO_CLASS: dict[InputType, type[InputEnum]] = {
     InputType.KEYBOARD: Keys,
     InputType.MOUSE_BUTTON: MouseButtons,
     InputType.MOUSE_AXIS: MouseAxes,
     InputType.CONTROLLER_BUTTON: ControllerButtons,
-    InputType.CONTROLLER_AXIS: ControllerAxes,
+    InputType.CONTROLLER_AXIS_SINGLE: ControllerTriggers,
+    InputType.CONTROLLER_AXIS_DOUBLE: ControllerSticks,
 }