Guide 09

Controllers

How SDL game controllers became the game's pads: hotplugging into free ports, the macOS "same controller twice" quirk, the Xbox layout, and rumble.

GoalPlug in a controller any time: the first one plays with the keyboard as player 1, a second one is player 2, and it vibrates.

1Hotplug into the first free port

Each frame, port 0's device closes unplugged controllers and opens new ones into the first free port.

new fileWn32/Code/Plat/Sys/SIO/p_siodev.cpp · a4cac21

+// Game controllers (SDL), one per port. Port 0 is shared with the keyboard.
+static SDL_GameController *s_game_controllers[vMAX_PORT];
+
+static void update_game_controllers( void )
+{
+	// Close the ones that were unplugged
+	for( int port = 0; port < vMAX_PORT; port++ )
+	{
+		SDL_GameController *&p_controller = s_game_controllers[port];
+		if( p_controller && !SDL_GameControllerGetAttached( p_controller ))
+		{
+			SDL_GameControllerClose( p_controller );
+			p_controller = nullptr;
+		}
+	}
+	// Give newly plugged in ones the first free port
+	...
+}

2Dodge the macOS double

A controller connected at launch shows up twice: via the IOKit driver (has a device path, gets no input) and the GameController framework (no path, works). Keep the one that works.

new fileWn32/Code/Plat/Sys/SIO/p_siodev.cpp · a4cac21

+// On macOS a controller connected at launch is listed twice: by the IOKit driver, which has a
+// device path, and by the GameController framework, which doesn't (SDL's IOKit driver only skips
+// controllers the framework has already seen). The IOKit one gets no input then, so use the other.
+static bool is_same_controller( SDL_GameController *p_controller, int index )
+{
+	SDL_Joystick *p_joystick = SDL_GameControllerGetJoystick( p_controller );
+	return SDL_JoystickGetVendor( p_joystick ) == SDL_JoystickGetDeviceVendor( index ) &&
+		SDL_GameControllerGetType( p_controller ) == SDL_GameControllerTypeForIndex( index ) &&
+		( SDL_JoystickPath( p_joystick ) == nullptr ) != ( SDL_JoystickPathForIndex( index ) == nullptr );
+}

Symptom: controller connected, LED on, game connected to it, zero input. The game was talking to the evil twin.

3Speak Xbox to a PS2 engine

The game runs its Xbox controls on PS2-shaped data. Triggers use the Xbox thresholds (pressed at 0x20, "full" at 128 of 255); sticks map from ±32767 to 0–255 with 0x80 centred.

excerptWn32/Code/Plat/Sys/SIO/p_siodev.cpp

// Triggers return [0, 32767], Xbox analog buttons [0, 255]; same thresholds as the Xbox version
const int trigger_pressed = 0x20 * 32767 / 255;
const int trigger_full = 128 * 32767 / 255;

// Sticks return [-32768, 32767], down/right positive like the PS2
auto stick = [&axis]( SDL_GameControllerAxis a ) { return (unsigned char)(( axis( a ) + 32768 ) >> 8 ); };
pad.left_x = stick( SDL_CONTROLLER_AXIS_LEFTX );

Button	Skating	Menus	Create-A-Park
A / X / B / Y	ollie / flip / grab, talk / grind	accept / delete letter / back / space	place / rotate / rotate / delete
LT / RT	nollie, spin left / switch, spin right (pull fully for both)	L1 / R1	lower / raise
LB / RB	get off / back on board (caveman)	–	zoom in / out
Back / Start	retry goal / pause	back / –	– / pause

All but Start, the D-pad and the sticks are rebindable: Gamepad settings.

A PS4 one (Sony's vendor ID): ○ = Back, ✕ = Accept.

4Rumble

Two actuators, like the Xbox pad. The strength is re-sent every frame with a short duration, so loading screens (when the game stops updating) don't leave the controller buzzing forever.

diffWn32/Code/Plat/Sys/SIO/p_siodev.cpp · a4cac21

+	if( p_controller )
+	{
+		// Vibration: actuator 0 is the left (low frequency) motor, 1 the right one.
+		// Sent every frame with a short duration, so it stops if the game stops updating (loading).
+		SDL_GameControllerRumble( p_controller, m_data.m_actuator_direct[0] * 257, m_data.m_actuator_direct[1] * 257, 250 );
+	}
@@ void Device::ActivateActuator( int act_num, int percent ) @@
+	// The strength is sent to the game controller by read_data
+	if(( act_num >= 0 ) && ( act_num < m_data.m_num_actuators ))
+	{
+		percent = ( percent < 0 ) ? 0 : ( percent > 100 ) ? 100 : percent;
+		m_data.m_actuator_direct[act_num] = (unsigned char)( percent * m_data.m_actuator_max[act_num] / 100 );
+	}

* 257: 255 × 257 = 65535. The cheapest exact 8-to-16-bit scale there is.

5Say which joysticks don't count

diffWn32/Code/Plat/Sys/SIO/p_sioman.cpp · a4cac21

-	// Print SDL all connected game controllers
-	printf("VVV SDL GAME CONTROLLERS VVV\n");
+	// Game controllers are opened (and reopened when plugged in) by the devices, see p_siodev.cpp.
+	// Print joysticks SDL doesn't know as game controllers, since those can't be used.
 	for (int i = 0; i < SDL_NumJoysticks(); i++)
 	{
-		if (SDL_IsGameController(i))
-			printf("Found game controller: %s (player index %d)\n", ...SDL_GameControllerOpen(i)));
-		else
-			printf("Found joystick: %s\n", SDL_JoystickNameForIndex(i));
+		if (!SDL_IsGameController(i))
+			printf("Joystick not supported as a game controller: %s\n", SDL_JoystickNameForIndex(i));
 	}

The old log line also opened every controller just to print its player index. A leak dressed as a debug print.

FOR EDUCATION PURPOSES ONLY. Screenshots are captured from the port running the reader's own copy of the game. The diffs are trimmed to the interesting lines (unchanged context is cut, marked ⋯); the repository has the full changes. Paths are relative to the THUG/ folder.