Improving Controller Support in the BGE

BGE Standard Controller Platform Proposal
Let’s Improve Controller support in the Blender Game Engine!

Warning, gigantic post follows:

Why Controllers?

The keyboard vs. controller debate has been going on for ages, and there’s no need to rehash it here (PLEASE don’t, I really want this thread to be productive - this thread is for BGE users and developers wishing to improve controller support in Blender- not for keyboard vs controller, console vs console or any other type of irrelevant debate or flamewar.) Each input method has its advantages and disadvantages for certain genres of games. Plus, sometimes, you just want to lay back on your couch with a controller!

Advantages of Improving and Standardizing Controller Support in the BGE

  • Controllers offer analog control for movement and camera orientation

  • The possibility for controller specific in-game prompts for faster explanation of the game’s interface to the player (this can be done with keyboard and mouse as well, albeit with a key-hunting safari)

  • A unique advantage for the BGE to offer developers and players making development and enjoyment of controller – centric Blender games fast, fluid, and predictable. As far as I know, no commercial or free game development platform has, or has even attempted to streamline support for controllers in this manner outside of dedicated gaming consoles (and they typically force you to use their proprietary or licensed solutions) - this is a (relatively) simple project that would give Blender a distinct edge over other platforms.

The Problem:

The Blender Game Engine currently has support for gamepads and joysticks, but barring extensive user configuration, no clearly communicable way for users to “plug and play” currently exists. While many controllers feature a similar array of controls, those controls can map to any number of “buttons” from the perspective of the game engine. For this reason, it isn’t practical to develop a BGE game, even one designed specifically with a controller or gamepad as the primary means of input, and expect users at home to be able to use his or her own controller without digging into the logic bricks or a configuration file of the game.

Even if a developer owns a large number of controllers from different manufacturers and tests them all extensively, (which I imagine would be a huge timesink and hassle not to mention expensive) when future controllers become common, or a player owns a “compatible” (in terms of numbers of buttons, joysticks, etc.) device that hasn’t been accounted for by that particular developer, that player will have to consult a (possibly nonexistent) manual for that game, learn how it is played and about all possible actions, then painstakingly map those actions (possibly in a very unintuitive poorly laid out way) to his or her controller. Anyone who’s tried to play a Games For Windows title that’s designed to work with ONLY the wired Xbox 360 controller with one’s own pad of a different make knows how frustrating this is. This BGE game better be amazing because the player is probably already really frustrated before even starting to play.

Proposed Solution(s):

There are probably as many controller configurations out there as there are flavors of ice cream, but in the last decade a de facto standard has emerged. Not only is this format familiar to millions of gamers around the world, a large number of us probably already have these lying around. For those who don’t, there are both high quality (Sony, Microsoft, etc.) and cheap, but functional and compatible knockoffs that can be easily obtained at your local gaming store or big box retailer.

This is the type of controller I will discuss in my initial proposal here, but there’s no reason we couldn’t define subsets of this configuration to support devices with similar, but leaner controls. (For example, a Super Nintendo controller shares 4 Face Buttons, Start and Select, a D-Pad, and two Shoulder Buttons with its current-generation counterparts – this type of device could be supported “automagically” if the developer uses only these functions.)

What does a modern input device designed for gaming look like? Naming conventions for controls may vary from letters to shapes, to primary colors, but strip away the branding and they’re mostly the same. Thus, if we look at these controllers with a common naming convention, players and developers can talk about button layout transparently, regardless of the manufacturer of the controller. Below is an operationalization of this class of gamepad’s functions and one or more example terminology for labeling these functions for demonstration purposes, but I’d love to hear others’ suggestions- this is a community effort!

Format: Descriptive name (Abbreviated name or symbol for graphical or colloquial representation)

Two Analog Sticks each with a Vertical and Horizonal Axis

LS Left Stick (or Left Horizontal, Left Vertical)
RS Right Stick (or Right Horizontal, Right Vertical)

Two “Stick Clicks”

Left Click, Right Click (LC, RC)
Left 3, Right 3 (L3, R3)

Four Face Buttons
Alpha, Beta, Gamma, Delta (A, B, gamma, delta – don’t know if these characters would display properly)
North, South, East, West (N, S, E, W)

Four Shoulder Buttons, two on the right, two on the left
Left 1, Right 1, Left 2, Right 2. (L1, R1, L2, R2)

One Directional Pad with four Directions
Up, Down, Left, Right (Up Arrow, Down Arrow, etc.)

Two System Buttons
Start and Select (ST, SE)

One Meta Button
Meta (Blender Logo? :slight_smile: )
Note: Could possibly be used as default button to terminate the game (ESC Key equivalent) or to bring up configuration options for the game.

Now that we have a common terminology for controller functions and the user can easily see (feel) which button this is on the controller he or she is holding, how does the game engine know which button is which? Again, not the only solution, but here’s my idea:

We (the BGE community) compile a list of common (as well as not-so-common) controllers and which of their buttons map to the previously defined standard. These values would be stored in a standard configuration file (probably just ASCII) multiple configurations in each device’s file for each particular platform supported by the BGE. Configuration files for all currently supported controllers would come packaged with this module and the user’s device would be automatically behave as expected as soon as he or she provides his or her A) Platform (OS, OS version) and B) Controller Type. If a configuration file appropriate for the player’s device is not present, that player can edit and existing configuration file to get it working locally, then submit this information to the maintainer(s) of this module and from then on, every subsequent version of the module would support that controller (on that platform). Or, alternatively, share the file on the forums for other users with the same controller until a new version of this module is released.

Initially, this would just be a Python script and configuration files passed around on the forum or in someone’s git, SVN or personal website, but if it becomes robust and comprehensive enough, maybe someday it could be included with Blender. In the future, we could think about things like rough calibration files for each controller, or even some standard scripts to make it easy for a user to calibrate his or her controller and send in configuration and calibration data.

What we can start doing immediately, however, is post information about controllers we own and what the BGE Joystick Sensor identifies those buttons/ axes as on Linux, Mac, Windows.

Possible Questions/ Concerns

Sounds like a lot of trouble. Shouldn’t the Blender developers do this?
No, I don’t think so. Developers are too busy working on more difficult, and frankly more important problems. This is not only something the community can do, but probably more effective at managing. There are exponentially more users than Blender coders, thus the community is in possession of more makes of controllers. The only coding required would be in Python, which most of us already know at least a little of. Hell, I think a lot of the code required for things like calibration is already floating around BA, but wouldn’t be that tough to write in the first place.

Why don’t you do it yourself if you love controllers so much?
I’m not a developer by any stretch, but I’ve fiddled with a lot of scripting languages over the years (Python lately) and I could definitely contribute some code. However, I wanted to present this proposal to the community first though, to see if there’s any interest in the first place, and because I know a lot of people on Blender Artists are a lot smarter than me and might have a better solution to the problem. (Weeks of coding can save you hours of planning!)

I’m a mod and I want you hanged for writing such an enormous post.
Sorry! I have a lot of time on my hands between semesters!

Whew, I guess that’s about all I have to say for now. I apologize again for the lengthy post, but I’ve been thinking about this for a while, and I’m just that big of a dork. I have a plethora of USB controllers myself and can provide data for them on both Linux and Windows, assuming anyone else cares about this.

What do you guys think?

This seems like an awesome idea! I’m not usually a computer gamer, so I hate keyboard controls. I think you have a very well thought out and presented idea, and it would be awesome to have a universal controller scheme. Anyway, I have the mapping for the Xbox 360 controller here:

Xbox 360 Controller Setup for Blender

Right Thumbstick:
Up = Index 0, number 2, axis, up axis
Down = Index 0, number 2, axis, down axis
Left = Index 0, number 3, axis, left axis
Right = Index 0, number 3, axis, right axis

Left Thumbstick:
Up = Index 0, number 1, axis, up axis
Down = Index 0, number 1, axis, down axis
Left = Index 0, number 1, axis, left axis
Right = Index 0, number 1, axis, right axis

Left Trigger = Index 0, number 2, axis, right axis
Right Trigger = Index 0, number 2, axis, left axis
The problem here is that you can't hold both triggers at once, because one will cancel the other out.

A = Index 0, Button, number 0
B = Index 0, Button, number 1
X = Index 0, Button, number 2
Y = Index 0, Button, number 3

Left Shoulder = Index 0, Button, number 4
Right Shoulder = Index 0, Button, number 5

Back = Index 0, Button, number 6
Start = Index 0, Button, number 7

I hope this is what you were looking for. Keep in mind though, pressing both triggers at the same time cancels them out. It’s also missing the stick clicks and the Xbox logo button. I don’t know much about messing with Blender’s source code to add this on, but I’d really like to help improve functionality in this area. Good Luck!

Well I don’t know much C/C++ beyond hello world either! The idea is to implement this in Python. Thanks for the data! I had my doubts aout the “meta” button myself, but I’m away from my blending machine for the next couple days so I couldn’t test it.

Edit: Make sure to state which OS you’re on and version.

Alright, I’m running Windows XP with SP3. I guess I have 64 bit processor, but all of my software is 32 bit. I’m using the latest version of Blender, 2.57. As for testing purposes, I do have very limited access to a Mac, but I don’t know the exact specs.

Would you want this in the form of an addon? I’d think that would be the most flexible, but I’m not sure if you can code addons with Python or not. Even then I only know a little about Python, but this is a project I would love to help out with.

I was thinking a python implementation would be best. ( And if I’m coding, that’s what it would have to be). But like I said earlier, the possibilities are endless- if someone with c coding skills steps up and wants to work on a patch that would be an option too. I’ve got to get up early tomorrow, so I’ll be hitting the sack soon, but I wanted to go ahead and post my idea to get the discussion going.

Maybe I should anhance my EventManager by Joystick support. It is a Python solution.

Currently it supports Keyboard and Mouse in any combination. The mapping from button to custom events (like AKEY=“move forward”, RMB=“jump”, SHIGHTKEY=“crouch”) can be setup in a file, which can be shared.

The implementation of the events (move forward, jump, crouch) is up to the user. This is game dependent and can’t be standardized. The game developer needs to use exectly this events (by property sensors), rather than the keyboard or mouse sensors.

Creating a GUI to setup the configuation file should’n be that difficult. But it does not exist yet.

An example how to use this concept is FreeViewControl.

The problem is I do not have any joystick. So it is impossible for me to test.
The next problem is, that the joystick sensor does not (like the keyboard sensor) support one sensor for all buttons. So it needs one sensor for each possible button (which can be a lot). As there can be multiple joysticks it needs to be done for all possible configurations.

I like this. And it go beyond controls. Having a standard set of events make it possible to build emulators For keyboard, touchscreen, video recognition… And the player can shoose the emulator they like instead of learning a new set of control methods for each and every game.

But I suggest JSON for config data.

Advantage over ASCII text:

  • Python have a good parser module thats dead simple to use.
  • A standard format instead of yet another self invented.
  • A format thats much a subset of Python literals so all BGE scripters should read it easy.

Advantage over pickle:

  • Human readable and editable
  • Designed to be robust against corrupted input.

Advantage over importing pure Python literals:

  • Can’t contain code so it’s safe to try out from untrusted sources.

Great idea, could we also do something with rumble support ?(maybe an actuator)

And do you want to generalize joystick input as well or only focus on gamepads?

Sounds interesting, but I don’t think that a ‘standard’ really has emerged as of yet - I have two different controllers that I hook up to my PC. One is a genuine PS2 controller with an adapter, and the other is a PS2 USB controller. I believe that the face buttons are digitally switched on the USB controller for whatever reason (i.e. Triangle is 4, not 1, Circle is 3, not 2, etc).

However, this would be useful for the community, as if you have a game controller connected to your PC, it’s probably going to be one of the ‘classic’ ones.

EDIT: It also would be easy to edit if the controls are switched.

I thought about using Python syntax (which is similar to JSON). But I desided against it, because:

  • you need additional control charaters ("{" “[”) which can be misconfigured
  • you could add bad Python code into the config (depending on the implementation)


My suggestion would be to regard each adapter as a “controller” with its own profile. In this case, the user would select the name of the particular adapter being used. I have a couple PS2 adapters myself- one is a GC PS2 Xbox combo, and the other is a dual port PS2 adapter.

We’d be creating the “standard” - the controller profiles are specifically intended to record which button is button 1, 2, hat, etc. This way, whatever Blender sees each button as is trivial, as long as it’s accounted for in a configuration profile.

Sure, there could be a standard for flightsticks as well- we’d have to develop terminology for common flightstick controls as well. Personally, I haven’t used my flightstick in about a decade (What happened to spaceflight games like Freespace 2?! Apparently the industry just decided to stop developing them :frowning: )

Regarding rumble support, this is something that would need to be done at a driver level in C or assembly. I don’t think rumble is very well supported for most controllers, on Linux anyway. Plus the BGE doesn’t have support for rumble to my knowledge- if a developer wanted to add it, that would be awesome, but its out of the scope of this project. (Until rumble is supported by the BGE through an actuator or something like you said- then I’d love to have support for it.)

This is something I forgot to mention! There would be mappings to the keyboard as well (user-configurable of course) so players without a controller would have just as easy of a time learning controls. The user would indicate that he or she was using the keyboard “controller” and when prompted by the game to press the “Alpha” (or “East” or whatever) button it would show up to the user as whatever key this button was mapped to instead.

I created some mockup svg graphics for my hypothetical controller layout a while back (I’ve been thinking about a standard like this for a year or so, just not in the context of the BGE) and I could produce more for each key on the keyboard, mouse gestures, etc. That’s also on my machine back home, I’ll post it here when I get back in a couple days.

I suppose the solution to this would be to check the “all events” (I think that’s what it’s called) box and handle whatever button was pressed in Python.

First, I think we need to compile a list of profiles for each controller and their relative buttons. I like the idea of Alpha, Beta, etc. buttons- but every controller is not the same, which will make this a little more difficult.

Also, was the idea to have Blender automatically detect the type of controller, or would the player specify the controller they are using upon the game starting up?

@Wraaah: I’m not sure if we can access the rumble function (as well as the Meta and stick click buttons), but I’d love to see it in Blender games.

EDIT: Oops, most of this stuff was answered before me. Sorry.

Good question about the autodetection. I’m not sure if there’s a good cross-platform way to detect specific controllers even in C/C++ and I’m almost sure Blender doesn’t currently support that. Worst case scenario, the user would have to select the device being used from a list of profiles, or if one didn’t exist, create one. If anyone is an expert in this area, though, your input would be valuable!

One way to reduce tedium would be to have a small Python utility distributed with the system for a user to select his or her controller once, then all games using the BCIP (or whatever we’ll call it) would check at startup which controller the player was using. This way, it would be “configure once, use everywhere.” This utility could also handle the user’s calibration settings, or anything else that players and developers shouldn’t have to bother with for every play session of every different game.

As far as getting started on creating profiles for different controllers, it would be awesome for anyone with a controller they would like supported to start recording which button the BGE identifies with each “standard” button; but let’s hold off on posting anything in this thread until we have the terminology firmly established (and maybe create a standard form for submission of data to ensure all pertinent information is covered) to avoid clutter and confusion.

But yeah, jotting it down on a notebook at home is something that you could start doing as soon as you like! That’s something I’m going to start doing as soon as I get back home.


I made sometime ago a draft for the controller / keyboard inputs to the game function assignment.

This example has a four game functions and user can assign any controllers analog axis, button or hat to those. Also the keyboard keys can assign as well.

User can also define a key modifier keys, if needed.

The sample .blend is a 2.49b version.

The pygame can get detect the controller names at least in windows. I don’t about other OS.

I think the best multi OS solution is a general setup script, which allow the users to loadup a specific controller setup file or just create a new file.


selection_10.blend (354 KB)

Another thought:

Isn’t that the task of the controllers/joysticks driver? As far as I remember a lot of driver’s support different setups. I can’t remeber how that works.


Yes, under the windows a serious flight controls, like a Thrustmaster and CH-products, the users can create with special application a very complex profiles with conditions & delays. This can include a different modes and sub-modes.

These drives upload the selected profile and then generates the mouse, axis, hats and key outputs accordingly.

These are used commonly with modern air combat simulations like a Falcon 4+, LOMAC, Flaming Cliffs, DCS: Black Shark, DCS: Warthog & etc.

Here is a DCS: Warthog and DCS: Black Shark startup procedure videos, performed with mouse clicks in clickable cockpit.
The startup procedure is also possible to do with key commands only… With a lot of key commands.

DCS: Warthog

DCS: Black Shark

I suggest focusing on the most common controller type, but add ‘class’ to the config so it is possible to later add more classes. Possibly a config can support more than on class (have a basic class with only the most basic function that almost all controllers have, one that fits most and more specific to take advantage of all functions on a few or even a single controller).

Monster: The drivers is responsible for getting the events to us - but this is more about identifying classes of similar controllers and standardizes the name of the events so a game can support one or a few classes and then work with a big variety of controllers + a set of emulators (like a set of keyboard binding). If I understand the intension right anyway.

Monster: (again) JSON avoid the embedded code problem and I can’t see any problem with [{}] characters. It’s not like people should edit the config files in game - If game should provide config it should be a proper gui.

all: I think the config should provide a description of the buttons (like “red button”, “square button” etc). It’s not for sure our ‘standard name’ intuitively translate to the actual button on a specific controller.

For controllers connected by USB auto detection should be easy cross platform (even if the code to get the info may be different on different os).

Slightly OT:
From messing around with a controller over the last couple of weeks in the BGE, I’ve noticed what I’m pretty sure is a bug. When dealing with the negative side of the axis the stick tends to max out (min out) before being fully extended in that direction. In other words, the value output by the controller reaches -32767 well before the physical stick reaches maximum extension.

In my tests this has led to my scripts not triggering when the stick has passed the point perceived as the minimum by the BGE. I’ve observed this behavior on multiple on multiple OSs with multiple controllers. Can anyone else confirm this? This would be a good bug to submit to Kupoman for his GSoC once we confirm its not just one of my stupid mistakes.

I like this idea - I think that instead of referring to buttons as Alpha, Beta, etc., though, a simple “A, B, C, D” configuration would probably be best.

The autodetection idea is a good one, though I wouldn’t recommend publishing pygame with it just to enable this feature. You could probably get the number of hats, axes, or buttons and figure out what kind of controller it is from there. For example, if there are no hats and are just two axes, you’re probably looking at an SNES style controller. If there are several axes, it’s probably a PS2 or XBOX controller. That kind of auto-detection would be very simple to implement.

EDIT: Starclopsofish - I doubt it’s a BGE problem. How far does the stick move on your controller before hitting the maximum value?

Letters would work too, I was just trying to stay away from commercial layouts, for example Sony has a trademark on the X [ ] O ^ thing- but I suppose just using letters, there shouldn’t be any problem. I also like the idea of making each face button a color- makes it easy to learn and pick up. I would suggest going with the convention of using ABXY though, as people are used to this. (To my knowledge the only time ‘C’ has been used was on 6 Face-Button controllers. (Which we might want to support as an extended profile later).

Maybe something like this?

EDIT: @ SolarLune about 70% - and only on the negative side of things. I’ve calibrated several times, and altered values in my scripts- nothing I’ve tried has any effect on the minimum values on axes. I can send you a .blend if you’d like.