--- title: Configuration Variables description: "This page provides an overview of the various configuration variables and preferences included in the controller support expansion for Ren'Py" url: "https://feniksdev.com/tool/configuration-variables/" updated: "2025-02-09" category: Controller Support Expansion --- # Configuration Variables 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](https://feniksdev.com/the-definitive-default-define-renpy-article/) for more on `define` vs `default` and `init python`!). If you haven't picked up the tool yet, you can do so here: [https://itch.io/embed/2766391?bg_color=21212d&fg_color=f7f7ed&link_color=f93c3e&border_color=ff8335](https://itch.io/embed/2766391?bg_color=21212d&fg_color=f7f7ed&link_color=f93c3e&border_color=ff8335) **Contents** [hide](#) [Icons](#Icons) [Icon Text colours](#Icon_Text_colours) [Input](#Input) [Virtual Cursor](#Virtual_Cursor) [Controller Sticks](#Controller_Sticks) [Callbacks](#Callbacks) [Focus Management](#Focus_Management) [Persistent Variables](#Persistent_Variables) ## Icons The following configuration variables are related to the gamepad icons. ```renpy 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. ```renpy 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. ```renpy define pad_config.DEFAULT_DPI = 150 ``` The DPI of the icons you are using for the gamepad icons. ```renpy define pad_config.DEFAULT_ICON_SIZE = 75 ``` The max dimension of the icons at the provided DPI. ```renpy 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`. ```renpy 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. ```renpy 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. ```renpy define pad_config.KEYBOARD_ROW1 = _("qwertyuiop") ``` The letters used on the first row of the on-screen keyboard. ```renpy define pad_config.KEYBOARD_ROW2 = _("asdfghjkl;") ``` The letters used on the second row of the on-screen keyboard. ```renpy define pad_config.KEYBOARD_ROW3 = _("zxcvbnm,.?") ``` The letters used on the third row of the on-screen keyboard. ```renpy 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. ```renpy define pad_config.KEYBOARD_BUTTON_WIDTH = 120 ``` How wide the keys on the virtual keyboard are. ```renpy define pad_config.KEYBOARD_BUTTON_HEIGHT = 90 ``` How tall the keys on the virtual keyboard are. ```renpy define pad_config.KEYBOARD_BUTTON_SPACING = 5 ``` How much space is between the keys on the virtual keyboard. ## Virtual Cursor ```renpy 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](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. ```renpy 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. ```renpy 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. ```renpy 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. ```renpy 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. ```renpy 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. ```renpy 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). ```renpy 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). ```renpy 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. ```renpy 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. ```renpy 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. ```renpy 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](https://feniksdev.com/tool/helper-functions-and-classes/#pad_configclear_managed_focusscreenNone) 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). ```renpy define pad_config.INPUT_CHANGE_REDRAWABLES = [ ] ``` This is a list of displayables which should be redrawn when the input type changes. The special [FocusTypeDisplayable](https://feniksdev.com/tool/controller-and-keyboard-icons/#FocusTypeDisplayable) automatically appends displayables to this list. This is helpful to update icons or other UI elements without refreshing the whole screen. ```renpy define pad_config.INPUT_TYPE_CALLBACKS = [ pad_config.refresh_controller_ui, pad_config.refresh_redrawables ] ``` 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. ```renpy 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](https://feniksdev.com/tool/focusdisplayable/) for more on what this displayable is. ```renpy 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. ```renpy 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. ```renpy 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](https://feniksdev.com/tool/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. ```renpy 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. ```renpy 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](https://feniksdev.com/tool/screen-actions-and-values/#CycleControllerLayoutreverseFalse) and [SetControllerLayout](https://feniksdev.com/tool/screen-actions-and-values/#SetControllerLayoutlayout) actions can help you set this in screens. ```renpy default persistent.hold_to_skip = False ``` If True, a button that is mapped to the `toggle_skip` action (see [Remapping Controls](https://feniksdev.com/tool/remapping-controls/)) will be mapped such that holding down that button will begin skipping, and releasing the button will end skipping. If False, the default, pressing and releasing the button will toggle skipping on, and pressing and releasing again will toggle skipping off. ```renpy default persistent.hold_to_drag = True ``` Similar to the previous value, if `persistent.hold_to_drag` is True, the `drag_activate` and `drag_deactivate` actions will be mapped in such a way that the drag button must be held down to move a drag (only possible using the [Virtual Cursor](https://feniksdev.com/tool/virtual-cursor/)). If False, the drag button can be pressed once to "pick up" the drag, and pressed again to release it. See [Remapping Controls](https://feniksdev.com/tool/remapping-controls/) for more.