Controller Support Expansion for Ren'Py

Overview

If you've ever found controller support in Ren'Py lacking, this set of plugins adds much-needed features to Ren'Py to make controller use practical and intuitive. Designed to be dropped on top of existing projects - controller-friendly variants like the viewport and bar can be used anywhere their default variants are, many features can automatically hide themselves unless a controller is being used. Boost your game's playability on Steam Deck, with keyboard controls, or for a console port!

Features

Note: click ➤ to expand for more information on each feature

Controller-friendly input with an in-engine customizable keyboard. Style the appearance however you like

• Includes shortcuts for shift/space/backspace and navigating left/right in the input.
• Comes with both a QWERTY layout (+ optional number row + optional symbols tab) and also as a numpad-only version.
• Includes variants for renpy.input and on-screen InputValues so the on-screen keyboard is only shown when a controller is being used (and the normal version with mouse & keyboard)
• Only shows the letters/numbers/symbols that are allowed in the input
• Customizable - feel free to add your own layout, symbols, accent characters, and more!

A controller-friendly viewport variant controller_viewport: instead of viewport:

• 5 different scrolling styles for navigating without a mouse which keep the currently focused item in view
• Options for wrapping focus to the next item in a row/column or loop it to the first/last item, and also to loop between the start and end
• Assign the left, right, or both controller sticks to adjust scrolling. Also has shortcuts for jumping to the start/end of the viewport.
• The control sticks are tilt-sensitive and will scroll faster when tilted farther
• Operates like a regular viewport for non-controller/keyboard setups

A controller-friendly bar variant controller_bar/controller_vbar instead of bar/vbar

• Automatically focuses bars when they are highlighted so you can adjust them right away. Avoids having to "click in/out" of the bars
• Operates like a regular bar for non-controller/keyboard setups

A controller stick- or keyboard-controlled virtual mouse which acts as a regular mouse for focusing buttons and navigation

• Works with drag & drop and edgescrolling viewports
• Just pretends to be a mouse and doesn't actually require mouse hardware
• Optionally snap to the center of a focus on release, with fields to adjust the warper and snap delay
• Taps into the existing mouse property of buttons and interactions to pick out the correct mouse, and can be provided a dictionary to choose the right image
• Has a version where the mouse moves, and another where the mouse position is fixed and other items move around it. Both can be provided an area where the mouse is restricted to as opposed to the entire screen.
• The fixed mouse position variant can be attached to an existing viewport to navigate it (including my parallax and zoom viewports)
• Useful for point-and-click investigation, flowcharts, map navigation, and more

A KeyController class which lets you easily set up actions to execute when a key is pressed while a particular displayable is focused

• Allows for complex tabbing layouts, and improved custom support for where focus should move to when the layout isn't grid-shaped (e.g. for point-and-click investigation sections, free-roam maps, and more)
• Basically it's a dictionary of instructions like "if the player is focused on the button with the ID 'dresser', when they focus_up, change focus to the button with the ID 'mirror'." The action performed can be whatever you like, not just setting focus.
• Also supports a screen language version similar to key called focused_on e.g. focused_on "pick_icons" key "focus_right" action CycleControllerLayout()

A FocusDisplayable class which allows you to add a special displayable to the screen which will follow the currently focused screen element

• This allows you to have a pointer cursor or a dynamic background frame which follows the focus to make it obvious what is currently selected. Particularly helpful for UI where the hover state does not differ significantly from the idle state.
• The displayable can be automatically hidden when keyboard/controller input is not used and reappear as appropriate, allowing it to be unobtrusively included on multiple platforms
• Includes several features like animation warpers, area of effect, and more

Multiple controller icon sets and callbacks

• Automatically detect the type of controller used when it is plugged in and automatically select an appropriate set of UI icons
• Players can toggle a different UI icon set manually, which will be remembered. Supports PlayStation, Switch, XBox, and Steam layouts, and a generic one.
• Callbacks for when controllers are connected or disconnected. Useful for Steam-compliant pause screens when a controller is disconnected.
• Includes an IconButton class and icon_button screen language statement for easily adding button prompts (icon or icon + text) that switch seamlessly based on the input type and handle the right events automatically

Other QoL Features

• Adds the gamepad calibration screens directly to the project for easy customization
• Support for player-controlled button remapping. Developers can add their own custom actions to be remapped as well.
• Support for saving/restoring focus when entering and leaving screens (e.g. on the main menu, if you navigate to Preferences and return, the Preferences button will be focused on the main menu)
• Includes a listener and related functions to check the last used input type (mouse, keyboard, or controller), with an optional callback when the input type changes. This allows you to refresh the screen to switch between a controller-friendly layout and a mouse & keyboard one in real-time
• Includes a default project demonstrating most of the included features
• Over 25k of documentation on my website with many examples and gifs

Instructions

Download controller_support_expansion.zip and unzip it to get a backend.zip folder which should be unzipped and put inside your project's game/ folder. There is also RenPyControllerGui.zip which has a template project that demonstrates how to use most of the features contained within the pack to make a functional UI for controllers. My website has an extensive tool section with documentation on the pack and all its features, with examples and plenty of images and gifs.

I recommend you unzip RenPyControllerGui into your projects folder and run it to get a feel for the features available in the pack.

Compatibility

The controller addons have been tested for compatibility with Ren'Py 7.7-7.8 and 8.2-8.3, and may be compatible with some earlier Ren'Py versions but has not been tested. A bug in 8.2/7.7 can result in jumpy movement if the virtual cursor is used on a zoom viewport while zoom in/out is mapped to the other controller stick and performed simultaneously. Viewport movement with FocusDisplayable isn't as smooth in 8.2/7.7. This issue does not occur in 8.3. I recommend using 8.3 or above if possible. Leave a message in the stickied thread if you run into any bugs.

Terms of Use

You may:

• Use this code in commercial and noncommercial projects.
• Modify and edit this code to suit your needs.

You may not:

• Resell all or part of this code as-is or sell it with modifications
• Release any projects created using this code without providing attribution

Attribution must be credited as Feniks, with a link to either the page with this code or to https://feniksdev.com.

Credits

svg icons for controller, keyboard, and mouse prompts slightly modified from Mr. Breakfast's Free Prompts (included in the files)

Controller image with button labels from LambdaLighthouse (not included in the files).

Pixel art forest modified from Eder Muniz (not included in files).

Final Notes

This tool pack, more than any tool I have put out thus far, has been a huge labour of love, with dozens if not hundreds of hours put into both the code and the documentation. If you are able to, tipping a bit extra to support my work would be greatly appreciated so I can continue to make these resources for the community.

This pack is also a living work; when possible, I will be working behind the scenes to get as many of these changes into Ren'Py as I can (though this is likely to take quite some time given the scale of things like the needed focus overhaul). I intend to continue to update the documentation with examples and FAQs to point people to the right tools for the job, so if you have questions about how to use a part of this tool or how to accomplish something with it, feel free to ask in the forums below or leave a comment on my website, feniksdev.com. This is also a giant pack of tools, so expect a few updates with fixes and tweaks in the near future.

If you use this pack, I want to hear about it! Leave a comment here or tag me on Bluesky (@feniksdev.com).

Lastly, if you're so inclined, I designed the virtual cursor to work with some of my other tools, such as the Zoom and Parallax Viewports: