Controller modding guide / FAQ

[raiguard]

Factorio 1.1.83 has added support for game controllers to the PC version of the game. Naturally, this new control scheme may cause issues with mods, so this guide is intended to help ease the process of adapting mods to support controllers if needed.

I'm a mod author, what does this mean for me?

For the vast majority of mods, nothing! Controller support is written in such a way that it works with most mods out of the box. However, while mods may function, they may not be very convenient to use, especially if they have custom GUIs.

How does this affect existing input bindings?

Game controller input bindings are kept separately from keyboard/mouse bindings, so existing bindings will not be affected. Furthermore, changes made to one input method's bindings will not affect the other. Mods with custom-inputs will need to define defaults for each input method separately.

How do I assign default controller bindings to custom-inputs?

custom-input has gained two new properties: controller_key_sequence and controller_alt_key_sequence. Formatting-wise these work identically to key_sequence and alt_key_sequence.

Controllers use different button names from keyboard/mouse. For convenience, here is a diagram of controller buttons to their respective internal names. Binding a custom-input to a button is as simple as using that button's internal name:

Code: Select all

controller_key_sequence = "controller-y"

A note about setting default bindings

Due to the severely limited number of buttons and possible combos on a game controller, it is highly recommended that most custom-inputs do not receive default controller bindings. If there is functionality that is only accessible via custom-input, it is recommended to add an alternate way to invoke that functionality, i.e. with a shortcut in the quick panel.

If a custom-input is contextual and/or is replicating an existing binding (i.e. mouse-button-1) for specific circumstances, then giving it a default binding is OK.

Face buttons

The game includes two settings related to the four "face buttons" on a controller:

• Icons: Choose how the buttons are represented in the GUI.
• Button layout: Choose which buttons are interpreted as controller-a and controller-b.

Binding a custom-input to controller-x will always bind it to the left face button regardless of the chosen button layout, and controller-y to the top button. However, a custom input bound to controller-a or controller-b will depend on which button layout is selected:

• Western: controller-a on bottom, controller-b on right.
• Eastern: controller-a on right, controller-b on bottom.

The icons are entirely a visual setting and do not change how the buttons are interpreted. The game will attempt to choose the correct icons and button layout for the controller that is connected. However, either setting may be overridden at any time.

Combo bindings

controller-lefttrigger and controller-righttrigger may be used as modifiers to form combo bindings. These are the only two buttons that can be used as modifiers - for example, it is impossible to make a combo using multiple face buttons. To create a combo, use the button + button syntax as normal:

Code: Select all

controller_key_sequence = "controller-lefttrigger + controller-righttrigger + controller-y"

Localisation

The game's locale system provides a handful of macros to display control inputs. You can find a list of these macros on the wiki. Using these macros in locale will automatically choose the correct representation for the input method that you are using.

For example, this stone furnace description:

Code: Select all

[entity-description]
stone-furnace=__CONTROL__open-gui__ to open, __CONTROL_mine__ to remove.

will show in-game as

stone-furnace.png (11.11 KiB) Viewed 4538 times

Reading and reacting to changes in input method

The LuaPlayer::input_method read contains the player's current input method, as a variant of defines.input_method. The on_player_input_method_changed event will be called whenever a player changes their input method.

LuaPlayer::input_method will only be accurate during and after on_player_input_method_changed; reading LuaPlayer::input_method during on_player_created or on_player_joined_game is unreliable. When a player is created, their input method will always initially be keyboard_and_mouse, and if they are using a controller, on_player_input_method_changed will be called later. Always assume that a new player is using a keyboard and mouse, and only activate controller-specific behavior during on_player_input_method_changed.

Quick panel - shortcut bar

When using a controller, the standard hotbar and shortcut bar are replaced by the quick panel. The "tools" tab of the quick panel contains the shortcut bar buttons:

quick-panel.png (16.91 KiB) Viewed 4538 times

The shortcuts in this quick panel are not able to be rearranged by the user. The quick panel logic will arrange the shortcuts based on their prototype order. It is very strongly recommended that mods order their shortcuts to be after all of the vanilla shortcuts, as to not hurt muscle memory for vanilla tools.

Vanilla shortcut order strings

• toggle-alt-mode: a[alt-mode]
• undo: b[blueprints]-a[undo]
• copy: b[blueprints]-b[copy]
• cut: b[blueprints]-c[cut]
• paste: b[blueprints]-c[paste]
• import-string: b[blueprints]-d[import]
• give-blueprint: b[blueprints]-e[blueprint]
• give-blueprint-book: b[blueprints]-f[book]
• give-deconstruction-planner: b[blueprints]-g[deconstruction-planner]
• give-upgrade-planner: b[blueprints]-h[upgrade-planner]
• toggle-personal-roboport: c[toggles]-a[roboport]
• toggle-equipment-movement-bonus: c[toggles]-b[exoskeleton]

Mod GUIs

The game includes a heuristic to select GUI elements in the currently opened GUI. For modded GUIs, this heuristic will only apply to a window if it is currently contained in LuaPlayer::opened. If a mod GUI is not set to opened, the player has to use free-cursor mode to interact with it. It is recommended that this be avoided whenever is reasonable.

Click modifiers and mouse buttons

For the purposes of GUI events, the following mappings are made:

• controller-a: Left-click
• controller-x: Right-click
• controller-lefttrigger: CONTROL modifier
• controller-righttrigger: SHIFT modifier

There is no way to middle-click or use the ALT modifier on a controller, so if a mod's GUI relies on either of those, it will need to adjust when a controller is connected.

As a potential workaround for the reduced capabilities, 1.1.83 has also added cursor_display_location to on_gui_click and custom input events. This property gives the current location of the mouse cursor on the user's screen. This can be used to create a context menu where the various actions can be contained. Keep in mind that for the controller heuristic to focus the context menu, it needs to be set as LuaPlayer::opened.

Game controller interaction modes

The game's heuristic uses the element type and a combination of other factors to determine if it should be selected by a controller. However, the heuristic may not perform as expected on modded GUIs, especially if a lot of GUI tricks or hacks are in use. Writing LuaGuiElement::game_controller_interaction will modify the heuristic's behavior for the given element.

Convenience bindings

It is notably more cumbersome to navigate a GUI with a controller than with a mouse. Because of this, it is recommended to add optional custom-inputs to speed up GUI interaction. For example, if a GUI has multiple tabs, adding optional bindings to switch tabs without having to navigate to and click them would be beneficial. Take care to only listen for these bindings if the GUI is actively opened, to avoid conflicts with other mods.

[Deadlock989]

Quick panel - shortcut bar

When using a controller, the standard hotbar and shortcut bar are replaced by the quick panel. The "tools" tab of the quick panel contains the shortcut bar buttons:

quick-panel.png

The shortcuts in this quick panel are not able to be rearranged by the user. The quick panel logic will arrange the shortcuts based on their prototype order. It is very strongly recommended that mods order their shortcuts to be after all of the vanilla shortcuts, as to not hurt muscle memory for vanilla tools.

This is quite annoying.

Shortcuts were introduced in 0.17 if I recall correctly. The "order" property was listed as optional property then; at the time of writing it is still listed as an optional property - none of the controller-related treatments of shortcuts described above is documented outside of this obscure FAQ post here on the forum. I only found out about this when I got a bug report saying that my shortcuts were "badly ordered" in the controller "quick panel".

I've written a few mods which have used custom shortcuts. None of them ever defined the "order" property because until 1.1.83 it had no tangible effect on the game. I'm not very clear on how quickbar shortcut order works but I gather (from related complaints) that it is kept in per-player data, so setting the prototype order property never really mattered until now. But suddenly it matters. It's now "very strongly recommended" by this semi-hidden FAQ that every mod explicitly specifies shortcut order, and we have to do it by choosing a value after all of the vanilla shortcuts, a value that isn't given here and isn't documented anywhere outside of base mod code as far as I can tell.

I don't have a controller for my PC, and don't want a controller, so I couldn't test any changes I make around supporting this "quick panel", even if I wanted to support controllers, which I don't. I recommend that the "quick panel" treats shortcuts with no order property defined as coming after all the vanilla shortcuts instead of your current choice of treating them as alphabetically first, if players' muscle memory is that important.

[aka13]

This is quite annoying.

It was obvious from the first second when there was talk about controller support that every gui will rotate around "CoNtRoLleR CoMfOrT".
Can't change hotbar location - 1A totally fine
Arbitrary armor and weapon movement - 1A totally fine
Can't see logistic and circuit network data - 1A totally fine

"But how do you know it is not in 1.2" - I don't, and it does not make anything better.
But shortcuts get a rework, and controls as well.

I also am willing to bet that any new content will revolve arount the idea, that it "has to work with controller, now that we have it".
Happens every time with every game that I know of.
At least there is hope, that no gyroscope minigames are coming.

[raiguard]

This is quite annoying.

Agreed, it could be better.

Shortcuts were introduced in 0.17 if I recall correctly. The "order" property was listed as optional property then; at the time of writing it is still listed as an optional property - none of the controller-related treatments of shortcuts described above is documented outside of this obscure FAQ post here on the forum. I only found out about this when I got a bug report saying that my shortcuts were "badly ordered" in the controller "quick panel".

I will ask Bilka to update the wiki's entry for the order to mention the quick panel.

I've written a few mods which have used custom shortcuts. None of them ever defined the "order" property because until 1.1.83 it had no tangible effect on the game. I'm not very clear on how quickbar shortcut order works but I gather (from related complaints) that it is kept in per-player data, so setting the prototype order property never really mattered until now. But suddenly it matters.

There have been attempts to improve the behavior of shortcuts in relation to mods, but fixing one issue makes another issue pop up. I hope to have it all fixed up in time for 1.2.

It's now "very strongly recommended" by this semi-hidden FAQ that every mod explicitly specifies shortcut order, and we have to do it by choosing a value after all of the vanilla shortcuts, a value that isn't given here and isn't documented anywhere outside of base mod code as far as I can tell.

The base shortcut order strings are listed in the very next sentence.

I recommend that the "quick panel" treats shortcuts with no order property defined as coming after all the vanilla shortcuts instead of your current choice of treating them as alphabetically first, if players' muscle memory is that important.

I considered doing this, but it is inconsistent with the rest of the game. Prototypes are ordered lexicographically, and making an exception in one very specific place doesn't make sense to me. If you remove all saved shortcut settings, then the keyboard/mouse shortcuts behave the same way, with unordered shortcuts appearing before ordered ones.

[raiguard]

It was obvious from the first second when there was talk about controller support that every gui will rotate around "CoNtRoLleR CoMfOrT".

I also am willing to bet that any new content will revolve arount the idea, that it "has to work with controller, now that we have it".

Mouse/keyboard will always be the primary way to interact with the game. Controller support exists, but will always be secondary to a good mouse/keyboard experience.

[Deadlock989]

I considered doing this, but it is inconsistent with the rest of the game. Prototypes are ordered lexicographically, and making an exception in one very specific place doesn't make sense to me. If you remove all saved shortcut settings, then the keyboard/mouse shortcuts behave the same way, with unordered shortcuts appearing before ordered ones.

No-one ever removes all saved shortcut settings.

I'm not going to support this. In the unlikely event that someone else reports it to me again (the previous person was Wube staff), I'll direct them here and they can take it up with Wube.

[raiguard]

To each their own, but in the time it took you to write these posts, you could have added an order string and called it a day.

[Deadlock989]

To each their own, but in the time it took you to write these posts, you could have added an order string and called it a day.

Or you could have decided not to retroactively shaft every single mod on the portal that didn't specify a completely optional property that had no effect on the game, but hey, to each their own.

[aka13]

Mouse/keyboard will always be the primary way to interact with the game. Controller support exists, but will always be secondary to a good mouse/keyboard experience.

Taking your word for it I'd really appreciate if it stays that way.