---
title: How do I…? + Common Issues
description: "Learn how to fix common issues and improve controller support for your Ren'Py game with scrolling viewports, virtual cursors, and more."
url: "https://feniksdev.com/tool/how-do-i-common-issues/"
updated: "2025-02-10"
category: Controller Support Expansion
---

# How do I…? + Common Issues

With something as large as the Controller Support Expansion for Ren'Py, it can be difficult to find the right tool to do what you need in your game. This page is designed to help you find the right resources to solve whatever problem you have. Pick up the tool from itch.io if you haven't already:

[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](#)     [Navigation and Focus Problems](#Navigation_and_Focus_Problems)  [Issue: Skipping over buttons in a grid or hbox/vbox](#Issue_Skipping_over_buttons_in_a_grid_or_hboxvbox)  [Issue: Directions focusing the wrong thing](#Issue_Directions_focusing_the_wrong_thing)  [Issue: Focusing something I don't want focused](#Issue_Focusing_something_I_dont_want_focused)  [Issue: Viewport not scrolling](#Issue_Viewport_not_scrolling)  [Viewports](#Viewports)  [How do I make a viewport scroll with the controller sticks/How do I make a viewport scroll when I focus things inside it?](#How_do_I_make_a_viewport_scroll_with_the_controller_sticksHow_do_I_make_a_viewport_scroll_when_I_focus_things_inside_it)  [User Interface (UI)](#User_Interface_UI)  [How do I change the UI for controllers?](#How_do_I_change_the_UI_for_controllers)  [How do I show controller icons?](#How_do_I_show_controller_icons)  [How do I change controller icon sets?](#How_do_I_change_controller_icon_sets)  [Virtual Cursor](#Virtual_Cursor)  [How do I use a controller/the arrow keys to control a cursor?](#How_do_I_use_a_controllerthe_arrow_keys_to_control_a_cursor)  [How do I make the virtual cursor move to a particular location?](#How_do_I_make_the_virtual_cursor_move_to_a_particular_location)  [Other](#Other)  [How do pause the game when a controller is disconnected?](#How_do_pause_the_game_when_a_controller_is_disconnected)

## Navigation and Focus Problems

Sometimes Ren'Py will not co-operate when you want to focus a particular button. Maybe it's skipping over a button in a vbox, or it's hard to see which button is currently focused.

### Issue: Skipping over buttons in a grid or hbox/vbox

If you're having issues with focus skipping over buttons in a grid or an hbox/vbox, some of the following solutions may work:

- `spacing`

First and most basic: negative spacing usually has focus issues. If it's possible to set the spacing of your box or grid to a positive number, often focus skipping issues will go away.

- `keyboard_focus_insets`

A property found in v8.3+ of Ren'Py. [Documentation here](https://www.renpy.org/doc/html/style_properties.html#style-property-keyboard_focus_insets). This can be used like:

```renpy
vbox:
    textbutton _("Start") action Start():
        keyboard_focus_insets (0, 10, 0, 10)
    textbutton _("Load") action ShowMenu("load"):
        keyboard_focus_insets (0, 10, 0, 10)
```

It will reduce the "hitbox" of the button so they aren't overlapping in Ren'Py's internal focus calculations (overlapping buttons tend to be skipped when it comes to focusing another button). In the above example, it shrinks the hitbox by 10 pixels at the top and 10 pixels at the bottom (it goes `(left, top, right, bottom)` in clockwise order, like `Frame` or `padding`).

- `penalty` property of `controller_viewport`

If you're using a [Controller Viewport](https://feniksdev.com/tool/controller-viewport/), you can make the `penalty` property smaller to reduce how much items to the left/right of items in a column, or above/below items in a row, are penalized when Ren'Py is figuring out what to focus next. The default penalty value is `1024`, so try something smaller like `128`.

- Turn [cache_reverse](https://feniksdev.com/tool/controller-viewport/#cache_reverse) off

If your layout is not symmetrical, you may be having focus issues because of the `cache_reverse` property of [Controller Viewport](https://feniksdev.com/tool/controller-viewport/). Set `cache_reverse False` to turn this property off.

- [KeyController and focused_on](https://feniksdev.com/tool/keycontroller-and-focused_on/)

If you're having trouble with specific button relationships, you can use the KeyController class (and its screen language version, `focused_on`) to tell Ren'Py exactly which button should be focused when certain directions are pressed.

- [Virtual Cursor](https://feniksdev.com/tool/virtual-cursor/)

Depending on what's in your screen, a virtual cursor may work best for keyboard and controller users. This is especially helpful for unusual layouts like flow charts or point-and-click investigation.

### Issue: Directions focusing the wrong thing

Another common issue is something like "if I hit `left` while focused on the "Schedule" button, it should select the "Inventory" button". If these two buttons aren't exactly aligned in something like a grid or hbox, Ren'Py may have trouble figuring out the relationship between them.

In this case, you can use the `focused_on` screen element to declare these relationships (see [KeyController and focused_on](https://feniksdev.com/tool/keycontroller-and-focused_on/)). Otherwise, the [Virtual Cursor](https://feniksdev.com/tool/virtual-cursor/) may also be helpful. See the previous section on skipping over buttons if your buttons are in a container like a grid or vbox/hbox.

### Issue: Focusing something I don't want focused

If you've got a button or bar that the player shouldn't be able to navigate to with the keyboard or controller at all, use `keyboard_focus False` on that element ([see the docs here](https://www.renpy.org/doc/html/style_properties.html#style-property-keyboard_focus)). This is often the case for scrollbars, and sometimes for buttons that can be focused with the mouse but which have a controller or keyboard shortcut.

If you're using the [Controller Viewport](https://feniksdev.com/tool/controller-viewport/), you might need the [trap_focus](https://feniksdev.com/tool/controller-viewport/#trap_focus) property to prevent focus from leaving the viewport, or the [aborb_events](https://feniksdev.com/tool/controller-viewport/#eat_focus) property to make sure focus events aren't passed to the rest of the UI.

You can also use `focused_on` to specify focus relationships between buttons, or make sure that focus doesn't leave a button in a particular direction. See [KeyController and focused_on](https://feniksdev.com/tool/keycontroller-and-focused_on/). Note that you can also use `focused_on` to "absorb" an action e.g.

```renpy
focused_on "desk" key "focus_right" action NullAction()
```

This means that when `right` is pressed while focused on the button with the ID "desk", nothing will happen (NullAction).

### Issue: Viewport not scrolling

First, make sure you're using the [Controller Viewport](https://feniksdev.com/tool/controller-viewport/). Regular viewports don't scroll when focusing the children inside them, or scroll with the controller sticks.

Second, if your viewport has children inside them that you're trying to focus so that the viewport scrolls, make sure the `vscroll_style` and/or `hscroll_style` are set to something besides `None`. `None` is the default, which means the viewport **will not** scroll to reposition itself if a child is focused. `vscroll_style "center"` and `hscroll_style "center"` are usually a good value to start with.

Otherwise, if your viewport doesn't have anything in it but you want to use the controller sticks to scroll it, make sure to set `which_stick` to one of "left", "right", or "both". Otherwise the sticks will not move it! You can also set `arrowkeys` to `"not sticks"` or `"keyboard"` to make it scroll with the keyboard + dpad or just the keyboard, respectively. This is often helpful in combination with `which_stick` so keyboard users can scroll as well.

## Viewports

### How do I make a viewport scroll with the controller sticks/How do I make a viewport scroll when I focus things inside it?

To make a viewport scroll with the controller sticks, you'll use the [Controller Viewport](https://feniksdev.com/tool/controller-viewport/). If the viewport has buttons and other content in it that you can focus, you'll need to set the `vscroll_style` and/or `hscroll_style` properties to something besides None so the viewport will scroll while you navigate it. If the viewport doesn't have focusable content inside it (e.g. it's like the History Log viewport), then set `which_stick` to "left", "right", or "both" so that stick can scroll the viewport. You may also want to set `focus_scroll False`.

## User Interface (UI)

### How do I change the UI for controllers?

By default, the `pad_config.INPUT_TYPE_CALLBACKS` (see [Configuration Variables](https://feniksdev.com/tool/configuration-variables/#Focus_Management)) callbacks include a function which will refresh the screen when the input type changes to/from a controller. This means you can wrap parts of your screen with a check for [pad_config.is_using_controller()](https://feniksdev.com/tool/helper-functions-and-classes/#pad_configis_using_controller) e.g.

```renpy
screen quick_menu():
    ## Ensure this appears on top of other screens.
    zorder 100

    if pad_config.is_using_controller():
        if quick_menu:
            use quick_menu_controller()

    elif quick_menu:

        hbox:
            style_prefix "quick"

            textbutton _("Back") action Rollback()
            textbutton _("History") action ShowMenu('history')
            textbutton _("Skip") action Skip() alternate Skip(fast=True, confirm=True)
            textbutton _("Auto") action Preference("auto-forward", "toggle")
            textbutton _("Save") action ShowMenu('save')
            textbutton _("Prefs") action ShowMenu('pref_display')
```

Here, you can see that there's a check for `pad_config.is_using_controller()`, which then uses a different screen for the quick menu.

You might also consider taking advantage of Ren'Py's `variant` system - see [Screen Variants](https://www.renpy.org/doc/html/screens.html#screen-variants). Of particular note for controller layouts is the `"steam_deck"` variant.

You can also read up on [Controller and Keyboard Icons](https://feniksdev.com/tool/controller-and-keyboard-icons/), which are set up to respond to the currently used input type as well.

### How do I show controller icons?

To show controller icons, you'll usually use the `controller_icon` displayable, which you can read more about here: [Controller and Keyboard Icons](https://feniksdev.com/tool/controller-and-keyboard-icons/). You may also use the functions [pad_config.get_icons](https://feniksdev.com/tool/helper-functions-and-classes/#pad_configget_iconsevent_suffix_zip_alt_textFalse) or [pad_config.get_inline_icons](https://feniksdev.com/tool/helper-functions-and-classes/#pad_configget_inline_iconsevent_suffixsmall_joiner) to get the icons associated with a particular event.

### How do I change controller icon sets?

By default, all of the icons used for controllers will automatically change when the controller layout changes, so you don't have to write any kind of if/else statement for it. To change which layout is used, however, you'll typically use the [CycleControllerLayout](https://feniksdev.com/tool/screen-actions-and-values/#CycleControllerLayoutreverseFalse) or [SetControllerLayout](https://feniksdev.com/tool/screen-actions-and-values/#SetControllerLayoutlayout) actions.

## Virtual Cursor

### How do I use a controller/the arrow keys to control a cursor?

To move around a virtual cursor with the controller sticks or keyboard arrow keys, you'll use the [Virtual Cursor](https://feniksdev.com/tool/virtual-cursor/).

### How do I make the virtual cursor move to a particular location?

You'll use the [MoveVirtualCursor](https://feniksdev.com/tool/virtual-cursor/#MoveVirtualCursorid_x_y_duration0_warperNone) action. If you want the physical cursor to move somewhere too, you may want to use this in a list with [MouseMove](https://www.renpy.org/doc/html/screen_actions.html#MouseMove).

## Other

### How do pause the game when a controller is disconnected?

Some platforms like Steam want your game to pause when a controller is disconnected. To do this, you'll use the `pad_config.CONTROLLER_CONNECT_CALLBACKS` and `pad_config.CONTROLLER_DISCONNECT_CALLBACKS` (see [Callbacks on the Configuration Variables page](https://feniksdev.com/tool/configuration-variables/#Callbacks)). In the default template, these are set to functions which will temporarily pause the game with a message that the controller has been disconnected, and dismiss said message if the controller is reconnected.