A brief overview of the general concepts and terms used throughout this document.
Steam Controller Configurator
The Steam Controller Configurator (SCC) is built into the Steam Client and sits between the player and their game/application. The SCC receives input from your input device, and translates that data appropriately depending on the player's settings before passing it along to the game.
The SCC can be used in two main ways: Legacy
mode and Native
Legacy mode is a compatibility mode designed for games that have not implemented the Steam Controller API. In this case, the SCC just serves as a really fancy input mapper that any
player can use for any
game on Steam.
The player can remap any physical input to any other physical input -- such as making the "A" button simulate the keyboard "Enter" key, make a full pull of the left analog trigger simulate a mouse click, etc. This mode works with any
supported input device, not just the Valve Steam Controller.
Legacy Mode is great for working with games that never supported the API, but there are limitations to it. For one, games programmed in such a way to assume that gamepad and mouse controls will never both be active simultaneously have been known to suffer from all manner of glitches when your configuration violates those assumptions. Also, the game will have no idea you're even using the Configurator (it's just receiving low-level hardware inputs that the configurator is spoofing) so the on-screen glyphs for controller inputs will probably not match up.
In Native mode, the game receives input data directly from the Configurator in the form of "actions." The idea here is that the game itself has no knowledge of what actual inputs are driving said actions, simply that the actions are happening. All configuration and control settings are relegated to the Steam Controller Configurator. That said, the game can request information via a special API call about which physical controls are bound to which actions purely for the purpose of displaying appropriate on-screen glyphs.
Steam Controller API
The Steam Controller API is the application programming interface developers use to talk directly to the Steam Controller Configurator in Native mode. The API is not necessary in order to support Legacy mode.
You can find full documentation for that here: ISteamController
Players can set up fully customized input mappings for any game in their library, using native mode, legacy mode, or even a mix of both. These input mappings are called "controller configurations" and a player can make many different ones for a single game, as well as share them with other players online.
A "physical input" is an actual physical mechanism on any input device that the user interacts with to generate input data for their computer. These come in both digital and analog forms and examples include buttons, joysticks, DPADs, bumpers, triggers, switches, hats, trackballs, touchpads, gyroscopes, etc.
We're going to get into more abstract concepts soon so just remember that "physical inputs" are the little bits on the controller you actually wiggle around with your fingers (or toes, if you're so inclined).
An "input source" is a region of the controller that can be thought of as a larger modular unit that can have any one of various different modes applied to it to change how it outputs data.
See, I told you we were going to get all abstract!
Let's bring it down to earth: what's the difference between a DPAD and four face buttons laid out in a diamond pattern?
They both have four digital "buttons", but most DPADs are physically engineered in such a way that it's impossible to press Up+Down or Left+Right at the same time, whereas each face button can be pressed independently. However, the Steam Controller can let you impose the restrictions of a DPAD on your face buttons.
So although both the DPAD and the face button group are each composed of four individual "physical inputs," its convenient to think of the "DPAD" and the "face buttons" as their own units, so that we can change how the whole thing behaves.
The full list of recognized "Input Sources" is:
- Left Trackpad
- Right Trackpad
- Center Trackpad
- Left Joystick
- Right Joystick
- Left Trigger
- Right Trigger
NOTE: The "Switch" input source is a catch-all for all the physical inputs that don't belong to another group, such as back & start buttons, left & right shoulder buttons, and back paddle grips.
Input Source Modes
Input sources can have different modes imposed on them that change how they behave. These are called "input source modes." Although these are useful for digital inputs, the most frequent place you'll find yourself using Input Source Modes is on analog controls, especially with touchpads, which can be configured in many different ways.
The full list of recognized "Input Source Modes" is:
- Four Buttons
- Absolute Mouse
- Relative Mouse
- Joystick Move
- Joystick Mouse
- Joystick Camera
- Mouse Joystick
- Mouse Region
- Radial Menu
Just to quickly summarize:Physical Inputs
The actual physical things you interact with on the device. Ex: the A button, the "up" input on the DPAD, etc.Input Sources
A larger grouping of individual physical inputs that can be grouped into a modular unit. The entire DPAD, the four face buttons, the entire left joystick assembly, etc.Input Source Modes
A specific behavior that you're forcing on an input source. Ex: "Make the face buttons act like a DPAD", "Make the left joystick act like four face buttons", etc.
Actions are the events that the Steam Controller API uses to orchestrate everything. In Native mode, your game doesn't get a "Button A pressed" event, it simply gets a "Jump" event (or whatever), and what kind of input causes "Jump" is entirely in the hands of the player.
Digital actions are the simplest and most common kind of action. They are simply on or off, so the game simply polls repeatedly and listens for the state of these actions.
Analog actions have one or more axes of data and are used for things like smoothly moving characters, steering cars, controlling cameras, etc. Standard joystick- and mouse- driven actions will usually have two axes, X and Y, but single-axis analog actions are possible too (such as those commonly bound to analog triggers); in this case the action data will still report two axes, but the Y axis will always be zero.
All actions require identifying names such as "jump" or "punch". These string values are separate from the text the player sees (those are "Action Labels", and can be localized).
Polling for actions based on string names is costly and inefficient, so when your game bootstraps the API it must register all the actions by name, receiving corresponding integer action handles in return.
An "action origin" is a string that identifies what sort of input is bound to a given action in the player's controller configuration.
An action set is a logical grouping of associated actions. Only one action set can be active for any given controller at a given time. For instance, you can create a "menu" action set that is only active during menu sequences, as well as "driving", "walking", and "flying" action sets for a game like GTAV that features multiple vehicle and movement modes. Action Sets exist both in native and legacy mode. In native mode, they are explicitly defined by the developer and the game will make API calls to designate which action set is currently active. In legacy mode, action set changes must be manually triggered by the player themselves. In both cases, action sets are a way to free up space on the controller by removing the need to permanently bind every action that could ever happen anywhere in the game and always leaving it on.
Beyond what happens on screen, some controllers have the ability to give feedback to the player through vibration and light.
As of this writing, only the VSC supports haptic feedback. This allows for fine-grained physical sensations that help the player to orient where their hands and fingers are positioned on large touch surfaces, as well as to convey e.g. the virtual momentum of an emulated trackball. Unsupported devices will ignore API calls for haptics.
A more traditional form of physical feedback, rumble is caused by vibrating internal motors that shake the controller. This feature is supported on the DS4, the XB1, and the X360 controllers (as well as many XInput compatible generic devices). The VSC does not have true rumble, but does emulates an approximation using its haptics (and will therefore respond to the API calls for rumble).
The VSC and the DS4 both have a built in LED light on the controller. The VSC's light is always white, but the DS4 features a fully programmable colored LED. Both of these devices will respond to API calls for changing the light color, but the VSC will cast the color to monochrome and simply use it to control brightness, whereas on the DS4 it can be used to control both the color and the brightness. Unsupported devices will ignore API calls for the LED.