UPDATED 5/25/2006
- Updated to be compatible with the 04/26/06 build of Sauerbraten.
- Fixed typo in keymap.cfg that was causing binding errors.

UPDATED 4/05/2006
- Added menu-driven joystick configuration. See below for details.

UPDATED 3/29/2006
- Added the joyshowevents property. See below for details.
- Also, verified that the mod works with non-analog sticks.

UPDATED 3/25/2006
This mod now contains executables for both Sauerbraten and Cube.

Why would you do this?
Just for kicks I thought I would see if I could set up game controller support for sauerbraten. I know most serious PC gamers would never dream of giving up the mouse. Personally, I sometimes get tired of being hunched over the computer and find it relaxing to sit back on the couch and play console-style. So if you've got a laptop with support for TV-output and a pc game controller with at least one stick (preferably analog) on it you might give this a shot.

How it works:
Basically, I took the approach that I would intercept joystick events and translate them into sauerbraten keypress events. This allows joystick events to be "bound" to actions like you would any other keyboard or mouse event.

Config File Settings
I added the following variables to the config.cfg to configure the joystick:

joyfovxaxis / joyfovyaxis
This setting specifies which stick should control the field of view (what the mouse does for you now). Each stick has a horizontal and a vertical axis. Each axis is numbered starting with 1. So, for example, on my controller, which is very similar to the one pictured above, if I wanted the use the left stick the settings would be:

joyfovxaxis 1
joyfovyaxis 2

or

joyfovxaxis 2
joyfovyaxis 1

depending on how your controller numbers the axes.

If you wanted to use the right one (recommended) the settings would be:

joyfovxaxis 3
joyfovyaxis 4

or

joyfovxaxis 3
joyfovyaxis 4


joyfovinvert
Specifies how the stick controls your field of view. If set to 0 you will look in the direction you press on the stick. If set to 1 (inverted) the control works like a flight simulator: pull back on the stick to nose up, push forward to nose down. This is the default.

joyaxisminmove
This property sets up the minimum amount of movement that is required to trigger an event when binding axis movements to actions. The range for this setting is 1-30. If set to 1 you basically just have to breath hard on the stick and it will trigger the event. If set to 30 you'll have to push it practically to the edge. The default is 8.

joysensitivity
This is the property you'll probably end up tweaking the most. On certain maps where you're getting really low fps you might need to bump this up a bit. The range for this setting is 1-10 where 1 is the least sensitive and 10 is the most. Remember, these values can be set from within the game. Just type /joysensitivity n at the console to bump the sensitivity up or down, or better yet, create an alias and map this to a couple of your joystick buttons. (See the response below titled "Joystick Sensitivity Script" for an example of how to do this.)

joyshowevents
This property is meant to be used when configuring your game controller. When joyshowevents is set to 1, all joystick events will be displayed in the console. This will help you determine which button to use when binding actions to the joystick, as well as which axis to use for movement and field of view control.

For example, if you want to use a certain button to fire your gun, press that button and you will see something like this displayed in the console:

JOYBUTTON7: DOWN
JOYBUTTON7: UP

You can then bind that button from within the game by typing:

/bind JOYBUTTON7 [attack]

(Binding joystick events is discussed further in the next section.)

This is also useful for configuring the field of view axis. In this case you just move the axis to the left and right and then up and down. This will display which axes are being moved which you can use to set the joyfovxaxis and joyfovyaxis values.

Binding Joystick Events
There are currently three types of joystick events you can bind to actions:

Binding Buttons
I've left space for up to 20 joystick buttons that can be bound to the action of your choice. For example, I wanted to map "attack/shoot" to my right trigger finger button, and "jump" to the trigger finger on the left. On my controller the right trigger button is button 8 and the left trigger button is button 7, so I added the following lines to my config.cfg file:

bind "JOYBUTTON8" [attack]
bind "JOYBUTTON7" [jump]


Binding Stick Movements
I've left space for up to 5 sticks (10 total axes) that can be bound to actions. Like in the picture above I wanted to use the left stick to control my movement: push forward on the stick to move forward, back to move backward, right and left to strafe. So, I added the following lines:

bind "JOYAXIS1MIN" [left]
bind "JOYAXIS1MAX" [right]
bind "JOYAXIS2MIN" [forward]
bind "JOYAXIS2MAX" [backward]


Binding Pad Movements
Some controllers, like the one in the picture above, have those little up/down/left/right "pad" or "hat" controls. In the picture above I have up mapped to zoom-in and down mapped to zoom-out. The binding for that would look like this:

bind "JOYHAT1NORTH" [fov 15; crosshairsize 50]
bind "JOYHAT1SOUTH" [fov 110; crosshairsize 22]

You could also use that pad for controlling your movement. That would look like this:

bind "JOYHAT1NORTH" [forward]
bind "JOYHAT1NE" [forward; right]
bind "JOYHAT1EAST" [right]
bind "JOYHAT1SE" [backward; right]
bind "JOYHAT1SOUTH" [backward]
bind "JOYHAT1SW" [backward; left]
bind "JOYHAT1WEST" [left]
bind "JOYHAT1NW" [forward; left]


Menu Configuration
Sauerbraten users can now configure joysticks using the much more intuitive menu-driven interface. Simply navigate to the joystick menu under options->joystick (If you do not see the images below go here):

The following screen will be displayed:

From this menu you can configure all of the joystick settings. The example above shows the user changing the joystick axis used for looking left and right. The example below shows the user selecting an action for a button:

I recommend that you first set "show events" to "yes" before setting the other properties. This will cause the joystick events to be displayed in the console as buttons are pressed or axes are moved. This should help when deciding which button, pad or axis to use with each setting or action.

Disclaimers:

• This is built from the 4/26/06 release for Sauerbraten and the 8/29/2005 release for Cube.
• This works for all(2) of my controllers. I do not know if it will work for you. (Please try it out and let me know.)
• If your game controller does not have at least one stick, this will not work.
• This supports only one game controller. If you have more than one connected, I'm just going to take the first one I find.
• If no game controller is recognized, or the game controller cannot be initialized for whatever reason there will be no notification, sauerbraten will just load as normal.
• I have not tried this on linux yet.
• Note to Cube Players: Because of cheat protection built into Cube, modified clients cannot connect to official release servers. So if you want to play online with others you'll have to start up a server using the executable included.
• Note to Cube Players: The menu-driven configuration is currently only available for Sauerbraten. If there is enough interest I can back-port this feature to Cube.

Let me know what you think.

- dbox