The Controller Support Expansion for Ren’Py has several configuration variables which can be used to customize the various features of the pack. These features generally exist in the pad_config namespace, so they are in the format with pad_config.NAME. Most configuration variables are easily set with a define statement (see The Definitive Default Define Ren’Py Article for more on define vs default and init python!).

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

Icons

The following configuration variables are related to the gamepad icons.

define pad_config.ICON_FOLDER = "backend/controller_support/controller_ui/"

This is the folder where the button icons can be found. In the default template, it is set to the above path. This should end with a / such that the name of the icons can be added to the end of this string along with the extension.

define pad_config.ICON_EXTENSION = "svg"

The file extension used by the icons. The default provided icons are svg vector icons. This extension should not include the period.

define pad_config.DEFAULT_DPI = 150

The DPI of the icons you are using for the gamepad icons.

define pad_config.DEFAULT_ICON_SIZE = 75

The max dimension of the icons at the provided DPI.

define pad_config.ICON_COLOR_TYPE = 2

In the provided icon set, the PS and Xbox buttons can be coloured in different ways. 1 is no colour, 2 is full colour, and 3 is text/symbol colour only. You can also set this to "" if you don’t have numbering for colours in your icons. If you look at the provided icon set, this corresponds to the numbers for file names like button_x1.svg, button_x2.svg and button_x3.svg.

define pad_config.XBOX_CONTROLLER_NAMES = ["xbox", "microsoft"]
define pad_config.PLAYSTATION_CONTROLLER_NAMES = ["ps3", "dualshock", "ps4", "playstation",
    "ps5", "dualsense", "ps2", "ps1", "sony", "ds4", "ds5"]
define pad_config.NINTENDO_CONTROLLER_NAMES = ["nintendo", "joycon", "pro controller",
    "switch", "gamecube", "wii"]
define pad_config.STEAM_CONTROLLER_NAMES = ["steam", "valve"]

These values are used to try to identify the type of controller being used when a controller is plugged in, to pick out the right icon set. If a string provided in the list is present in the controller name, the corresponding layout will be used. These strings should be all in lowercase.

Icon Text colours

The following variables are used with the get_button_text function to return coloured text names of buttons.

define pad_config.XBOX_A_COLOR = "#BAE236"
define pad_config.XBOX_B_COLOR = "#FC551D"
define pad_config.XBOX_X_COLOR = "#23C3F6"
define pad_config.XBOX_Y_COLOR = "#FEB21B"

define pad_config.PS_X_COLOR = "#5FD3F8"
define pad_config.PS_O_COLOR = "#FD6248"
define pad_config.PS_SQUARE_COLOR = "#F450A5"
define pad_config.PS_TRIANGLE_COLOR = "#36E2A7"

Input

The following configuration values are used to customize aspects of the on-screen keyboard used by the controller.

define pad_config.KEYBOARD_ROW1 = _("qwertyuiop")

The letters used on the first row of the on-screen keyboard.

define pad_config.KEYBOARD_ROW2 = _("asdfghjkl;")

The letters used on the second row of the on-screen keyboard.

define pad_config.KEYBOARD_ROW3 = _("zxcvbnm,.?")

The letters used on the third row of the on-screen keyboard.

define pad_config.SHIFT_DICT = { "," : "-", "." : "_", "'" : '"', "?" : "/"}

A dictionary of characters to change a given special character to while shift is held down. Regular capitalization like a -> A is automatically handled.

define pad_config.KEYBOARD_BUTTON_WIDTH = 120

How wide the keys on the virtual keyboard are.

define pad_config.KEYBOARD_BUTTON_HEIGHT = 90

How tall the keys on the virtual keyboard are.

define pad_config.KEYBOARD_BUTTON_SPACING = 5

How much space is between the keys on the virtual keyboard.

Virtual Cursor

define pad_config.DEFAULT_VIRTUAL_CURSORS = { }

A dictionary of event : (displayable, xoffset, yoffset) pairs equivalent to https://www.renpy.org/doc/html/mouse.html#hardware-mouse-cursor which will be used for the virtual cursor.

Controller Sticks

The following configuration values are related to the controller sticks.

define pad_config.STICK_MAX = 32767

The maximum value of the stick’s x- and y-axes. This is as provided by pygame and generally should not be changed.

define pad_config.STICK_MIN = -32768

The minimum value of the stick’s x- and y-axes. This is as provided by pygame and generally should not be changed.

define pad_config.MINIMUM_DEADZONE = 1024

The minimum value of a stick’s axis before it’s considered to be in the “dead zone” aka not moving. Most sticks will pick up on some minuscule movements and won’t be perfectly at 0 while at rest, so a small range of numbers are considered to be in the dead zone. This is the smallest number the player can set the dead zone to via the bar in the preferences section.

define pad_config.MAXIMUM_DEADZONE = 16384

The maximum value of a stick’s axis before it’s considered to be out of the “dead zone” aka not moving. Allowing the player to set the dead zone to larger values helps them correct for things like stick drift.

define pad_config.DEFAULT_DEADZONE = 4096

The default value of a stick’s axis before it is considered to be moving. Players can use a bar with the StickDeadzoneAdjustment value to adjust the deadzone from this value to the minimum or maximum values declared above.

define pad_config.MINIMUM_SENSITIVITY = 0.2

The minimum sensitivity multiplier the player can set a stick’s sensitivity to. This must be greater than 0. Small numbers mean the stick will adjust values very slowly (e.g. the virtual cursor will move slowly, and scroll bars will scroll slowly).

define pad_config.MAXIMUM_SENSITIVITY = 3.0

The maximum sensitivity multiplier the player can set a stick’s sensitivity to. Larger numbers mean the stick will adjust values very quickly (e.g. the virtual cursor will move quickly, and scroll bars will scroll quickly).

define pad_config.DEFAULT_SENSITIVITY = 1.0

The default sensitivity multiplier for the controller sticks. The player can adjust this multiplier using a bar with the StickSensitivityAdjustment value. Individual displayables which receive stick input can also use the speed property to adjust stick sensitivity; this number will be multiplied with the stick’s sensitivity value to get the final speed.

Callbacks

The following configuration values are related to callbacks.

define pad_config.CONTROLLER_CONNECT_CALLBACKS = [ pad_config.choose_icon_set, reconnect_controller ]

This list of callbacks is called when a controller is connected. It is passed one argument, the index of the controller which was connected. The default callback uses this to dismiss the controller disconnected prompt, if it is showing. The pad_config.choose_icon_set function will select an icon set to use when a new controller is plugged in.

define pad_config.CONTROLLER_DISCONNECT_CALLBACKS = [ pause_on_controller_disconnect ]

This list of callbacks is called when a controller is disconnected. It is passed one argument, the index of the controller which was disconnected. The default callback uses this to show a prompt to the player that the controller was disconnected.

Focus Management

The following configuration values are related to focus management.

define pad_config.RESTORE_FOCUS_SCREENS = [ "main_menu", "game_menu", "controller_remap" ]

This is a list of screen names that should have their focus saved and restored when entering and leaving them. Basically this means for something like the main menu, if the player presses the Preferences button and opens the Preferences screen, then closes it to return to the main menu, the Preferences button will be refocused.

You may want to use the ((clear_managed_focus)) method to clear the saved focus in some circumstances (e.g. by default the main_menu focus is cleared upon restarting the game, and the game_menu is reset when the in-game menu screen is dismissed).

define pad_config.INPUT_CHANGE_REDRAWABLES = [ ]

This is a list of displayables which should be redrawn when the input type changes. The special ((FocusTypeDisplayable)) automatically appends displayables to this list. This is helpful to update icons or other UI elements without refreshing the whole screen.

define pad_config.INPUT_TYPE_CALLBACKS = [ pad_config.refresh_controller_ui ]

These callbacks 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.

The default callback will call renpy.restart_interaction() when the input type changes to or from controllers. It also redraws displayables in the special pad_config.INPUT_CHANGE_REDRAWABLES list.

Persistent Variables

There are also several persistent variables declared so they can be adjusted as preferences in-game.

default persistent.ALWAYS_SHOWN_FOCUS_DISPLAYABLE = None

This can be provided a FocusDisplayable which will be used for every screen in the game. See ((FocusDisplayable)) for more on what this displayable is.

default persistent.left_stick_dead_zone = dict()
default persistent.right_stick_dead_zone = dict()

These dictionaries are populated with guid : int pairs where the key is the guid of the controller (a semi-unique identifier for it) and the value is the maximum axis value where the stick is still considered to be in the dead zone. See the section on Controller Sticks earlier for more on dead zones. This is auto populated with the various stick calibration preferences.

default persistent.left_stick_max = dict()
default persistent.right_stick_max = dict()

These dictionaries are populated with guid : int pairs where the key is the guid of the controller (a semi-unique identifier for it) and the value is the maximum axis value the stick can be pushed to. See the section on Controller Sticks for more on dead zones and movement areas. This is auto populated with the various stick calibration preferences.

default persistent.left_stick_invert_x = False
default persistent.left_stick_invert_y = False
default persistent.right_stick_invert_x = False
default persistent.right_stick_invert_y = False

If a given stick axis is inverted, that means the directions are reversed. This is handled automatically for any displayable which inherits from the ((StickEvent)) class. By default these are not inverted, so, for example, pressing up on the controller stick will scroll a viewport up. If inverted, pressing up would scroll the viewport down and vice versa.

default persistent.left_stick_sensitivity = 1.0
default persistent.right_stick_sensitivity = 1.0

The default sensitivity multipliers for the left and right sticks. See the section on Controller Sticks earlier for more on stick sensitivity.

default persistent.controller_layout = "generic"

By default, the expansion will automatically select a controller layout when a controller is plugged in, based on its name. However, this value can also be changed to select a different controller layout. The recognized layout strings are “xbox”, “playstation”, “nintendo”, “steam”, and “generic”. The provided CycleControllerLayout and SetControllerLayout actions can help you set this in screens.