Controller Support Expansion for Ren’Py has several functions and classes which may be of use to you when improving controller support for your game.

If you haven’t picked up the tool yet, you can do so here:

Classes

pad_config.EventListener(callbacks=None, on_changed=True)

EventListener is a class which listens for controller, keyboard, and mouse events to know which was last used. It can be provided callbacks to call when the input type changes, or when any controller/keyboard/mouse event occurs. This class is used internally as part of pad_config.INPUT_TYPE_CALLBACKS (see Configuration Variables for more).

callbacks

This is a list of callables which are run when the input type changes. The possible input types are mouse, keyboard, and controller. The callback receives three arguments: the previous input type, the new input type, and the pygame event. The input types are denoted with the special values pad_config.EventListener.MOUSE, pad_config.EventListener.KEYBOARD, and pad_config.EventListener.CONTROLLER. The previous input type may also be None when the game first starts, before any input has been detected.

on_changed

If True, the default, the callbacks will only be called when the input type changes. Otherwise, the callbacks are called every time an event is received.

There is one other special EventListener which is already defined:

define pad_config.PRESS_ANYTHING = EventListener(callbacks=[pad_config.wait_for_event], on_changed=False)

pad_config.PRESS_ANYTHING can be added to a screen to await any kind of input. In the default template, it is included in a screen that’s called as part of the splash screen, to set the initial input type for the game.

screen press_any_button():
    add BLUE
    label _("Press any button") at gentle_flash style 'press_any'
    ## This a special version of the EventListener class which will
    ## end the interaction when a button is pressed.
    add pad_config.PRESS_ANYTHING

pad_config.FocusManager(screen, layer=None)

The FocusManager class manages the focus of the provided screen, saving and restoring focus when the screen is revisited. This class is used internally as part of pad_config.RESTORE_FOCUS_SCREENS (see Configuration Variables for more).

screen

This is a string with the name of the screen this object manages focus for.

layer

Optional. The layer to manage focus on. Default is None, which will automatically choose the layer the screen is on.

Functions

There are several helper functions which are used across the tool.

pad_config.is_using_mouse()

This function returns True if the last input type was the mouse, and False if not.

pad_config.is_using_keyboard()

This function returns True if the last input type was the keyboard, and False if not.

pad_config.is_using_controller()

This function returns True if the last input type was a game controller, and False if not.

pad_config.get_event(event, kind=”all”, *)

Returns the event name(s) for a given gamepad event as a list.

event

A string. The event name to get the internal events for (e.g. “button_select” becomes ["pad_a_press"]).

kind

Optional. One of “all”, “press”, “release”, “release_replace”, “repeat”, or “repeat_replace”. Default is “all”. Filters the events to return only those of the given kind. “release_replace” will return all the events from “press”, replaced to their release counterparts. “repeat_replace” does the same but for repeat events.

pad_config.map_event(ev, event, kind=”all”)

Like renpy.map_event (see docs) but for gamepad events using the remapping + custom events system. Uses the output of pad_config.get_event to run renpy.map_event. See above for the arguments. ev is the event passed into renpy.map_event.

pad_config.get_icons(event, suffix=””, zip_alt_text=False)

Returns the icon image(s) for a given gamepad event. Returns a list like ["pad_a", "pad_b"].

event

A string. The event name to get the icon for e.g. "button_select"

suffix

A string. Optional. A suffix to add to the end of the icon name, such as “small”. This would result in a list like ["pad_a_small", "pad_b_small"]. Default is "".

zip_alt_text

Optional. If True, returns a list of tuples with the icon name and the alt text for that icon. Default is False. So, for example, it will return a list like [("pad_a", "A button"), ("pad_b", "B button")]. The alt text is layout-dependent, so for example an Xbox controller’s alt text will read "A button" but the PlayStation layout will read "Cross Button".

pad_config.get_alt_text(event, as_list=False, is_event=True, alt_tag=True)

Returns human-readable alt text for controller icons, based on the icon set in use.

event

A string. The event name to get the alt text for e.g. "button_select"

as_list

Optional. If True, returns a list of alt text strings. Default is False, and it returns a single string joined with commas.

is_event

Optional. If True, the event is an event name. If False, the event name has already been passed through pad_config.get_event to get a list like ["pad_x_press"].

alt_tag

Optional. If True, wraps the alt text in an {alt} tag. Default is True. Irrelevant if as_list is True.

pad_config.get_inline_icons(event, suffix=”small”, joiner=””)

Returns a string with {image=some_image} for the buttons which can be used to activate the provided event.

event

A string. The event name to get the icon for e.g. "button_select"

suffix

Optional. A suffix to add to the end of the icon name. Default is “small”.

joiner

Optional. A string to join the icon images together with. Default is "" so the icons come out like "{image=pad_x_small}{image=pad_y_small}. If the joiner was ", " then it would come out like "{image=pad_x_small}, {image=pad_y_small}"

pad_config.register_redrawable(disp)

A function which registers the given displayable to be redrawn when the focus type changes. Used internally as part of the FocusTypeDisplayable class.

pad_config.refresh_controller_ui(old_type, new_type, event)

A function which refreshes the screen if the player switches to controller from mouse or keyboard, or vice versa. It also refreshes some special displayables (to avoid having to refresh the whole screen). It is the default callback for pad_config.INPUT_TYPE_CALLBACKS (see Configuration Variables for more).

pad_config.manage_focus()

A function which triggers all focus managers to check if they’re showing and, if so, to restore focus. By default, this is used on the on "hide" actions of the controller remap screen and confirm screens to make sure focus is restored to the correct button when they are hidden.

pad_config.clear_managed_focus(screen=None)

A function which clears either all focus manager focuses (if screen=None) or the one from a specific screen.

pad_config.wait_for_event(old_type, new_type, event)

A callback for an event listener which returns on button down or a key press event. Used internally for the PRESS_ANYTHING EventListener (see the section on the EventListener class for more above).

pad_config.get_stick_dead_zone(id=None, stick=”left”)

Returns the dead zone for the provided controller, or the default if it hasn’t been calibrated.

id

The ID of a plugged in controller. If None, tries to get the first ID from the known controllers list.

stick

One of “left” or “right”. The stick to get the dead zone for.

pad_config.get_stick_max(id=None, stick=”left”)

Returns the maximum value for the provided controller, or the default if it hasn’t been calibrated.

id

The ID of a plugged in controller. If None, tries to get the first ID from the known controllers list.

stick

One of “left” or “right”. The stick to get the maximum value for.

pad_config.choose_icon_set(index)

This is a function used as part of pad_config.CONTROLLER_CONNECT_CALLBACKS (see Configuration Variables). It takes the index of a recently added controller and looks up what icon set to use.