Guide 06

Keyboard settings

How to add Options › Keyboard: grouped actions, two keys each, a "press a key" prompt, conflict popups, Reset to Defaults, all saved to config.ini.

GoalAny key, any action, two per action, without a single hardcoded SDL_SCANCODE_KP_2 left in the input code.

Options &rsaquo; Keyboard: Ollie on Num 2 and F, key 2 highlighted. The hint bar follows the bindings: Flip is on Num 4, so Num 4 clears. — Options › Keyboard: Ollie on Num 2 and F, key 2 highlighted. The hint bar follows the bindings: Flip is on Num 4, so Num 4 clears.

1Share config.ini between modules

The Screen code used to rewrite the whole file. A tiny INI helper reads one section and rewrites only that section, keeping the rest, so [Screen] and [Keyboard] can coexist.

new fileWn32/Code/Plat/Sys/File/p_inifile.h · 72de709

+namespace File
+{
+	// Key / value pairs of a section, in file order (both trimmed)
+	typedef std::vector<std::pair<std::string, std::string>> IniSection;
+
+	// Reads a section of config.ini (the name is not case sensitive). False if the file or the section is missing.
+	bool ReadConfigSection(const char *p_section, IniSection &values);
+
+	// Replaces a section of config.ini with the given lines ("Key=Value" or "; comment"), or adds it at the end
+	bool WriteConfigSection(const char *p_section, const std::vector<std::string> &lines);
+}

diffWn32/Code/Plat/Gfx/nx/display.cpp · 72de709

 static void SaveDisplaySettings()
 {
-	// config.ini only holds the screen settings, so it's simply rewritten
-	std::ofstream file(ConfigPath(), std::ios::trunc);
-	file << "[Screen]\n";
-	file << "Fullscreen=" << (s_settings.fullscreen ? 1 : 0) << "\n";
-	...
+	File::WriteConfigSection("Screen", {
+		"Fullscreen=" + std::to_string(s_settings.fullscreen ? 1 : 0),
+		"Width=" + std::to_string(s_settings.width),
+		"Height=" + std::to_string(s_settings.height),
+		"MaxFPS=" + std::to_string(s_settings.max_fps),
+	});
 }

2Describe actions as data

One table: the name in config.ini, the text in the menu, the group, and up to two default keys. The retail layout lives here now, not in ifs.

new fileWn32/Code/Plat/Sys/SIO/p_bindings.cpp · 72de709, later p_bindings

+// The retail THUG1 PC keyboard layout. The keys work everywhere, with a meaning that depends on what's on
+// screen (see p_siodev.cpp), so a key is only ever used by one action.
+static const sBindingAction s_key_actions[vNUM_KEY_ACTIONS] = {
+	{ "Forward",			"Forward",				vKG_SKATER,	mBIND_ANYWHERE,	{ SDL_SCANCODE_W } },
+	{ "Ollie",				"Ollie",				vKG_SKATER,	mBIND_ANYWHERE,	{ SDL_SCANCODE_KP_2 } },
+	{ "NollieSpinLeft",		"Nollie/Spin Left",		vKG_SKATER,	mBIND_ANYWHERE,	{ SDL_SCANCODE_KP_7 } },
+	...
+	{ "CameraView",			"Change View",			vKG_CAMERA,	mBIND_ANYWHERE,	{ SDL_SCANCODE_RETURN, SDL_SCANCODE_KP_ENTER } },
+	{ "MenuUp",				"Up",					vKG_MENUS,	mBIND_ANYWHERE,	{ SDL_SCANCODE_UP } },
+	{ "ParkUp",				"Selection Up",			vKG_PARK_EDITOR,	mBIND_ANYWHERE,	{ SDL_SCANCODE_HOME } },
+};

SDL calls the numpad keys "Keypad 2". The menu box is 265 units wide. Meet "Num 2", born of a layout emergency.

3Read actions, not keys

Every scancode is tracked with the context it went down in; an action is held when one of its keys is. Enter and Space are skipped in menus, where the front end already treats them as "choose".

diffWn32/Code/Plat/Sys/SIO/p_siodev.cpp · 72de709

-	// Face buttons: Numpad 2 ollie/accept, 4 flip, 6 grab/talk, 8 grind/back
-	pad.cross |= key( SDL_SCANCODE_KP_2 ) || enter_editor;
-	pad.square |= key( SDL_SCANCODE_KP_4 );
-	pad.circle |= key( SDL_SCANCODE_KP_6 );
-	pad.triangle |= key( SDL_SCANCODE_KP_8 );
+	// Face buttons: ollie/accept, flip, grab/talk, grind/back.
+	// Change View (Enter) is "choose" in the park editor, toggles the camera while skating; menus handle Enter themselves.
+	pad.cross |= s_action_held( vKA_OLLIE ) || s_action_held( vKA_CAMERA_VIEW, mCTX_PARK_EDITOR );
+	pad.square |= s_action_held( vKA_FLIP );
+	pad.circle |= s_action_held( vKA_GRAB );
+	pad.triangle |= s_action_held( vKA_GRIND );
@@
+// Whether one of the action's keys is held (or went down this frame), having gone down in one of the contexts
+static bool s_action_key( int action, unsigned int contexts, bool pressed )
+{
+	for( int slot = 0; slot < vKEYS_PER_ACTION; slot++ )
+	{
+		SDL_Scancode scancode = GetKeyBinding( action, slot );
+		const sContextKey &key = s_keys[scancode];
+		if( !( pressed ? key.pressed : key.held ))
+			continue;
+		if( key.context == vCTX_MENU && s_is_menu_choose_key( scancode ))
+			continue;
+		if( contexts & ( 1 << key.context ))
+			return true;
+	}
+	return false;
+}

4Steal the next key press

While the prompt waits, the keyboard belongs to it: key-downs and the text they type are swallowed, Escape cancels, Backspace clears. Keys still held when it ends stay blocked until released, so the Enter you just bound doesn't immediately "choose" the menu item again.

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

case SDL_KEYDOWN:
	if (capturing || s_blocked_keys[key])
	{
		if (capturing && s_capture_state == vBIND_CAPTURE_WAITING && !event.key.repeat)
		{
			if (key == SDL_SCANCODE_ESCAPE)
				s_capture_state = vBIND_CAPTURE_CANCEL;
			else if (key == SDL_SCANCODE_BACKSPACE)
				s_capture_state = vBIND_CAPTURE_CLEAR;
			else if (IsBindableKey(key))
			{
				s_capture_state = vBIND_CAPTURE_INPUT;
				s_captured_input = key;
			}
		}
		s_eat_text_input = true;	// SDL sends the typed text right after the key
		return true;
	}

Waiting for the key. The dialog's buttons are for controllers; the keyboard is busy being captured.

Without s_eat_text_input, binding Space also typed a space, which the menu read as "accept", which opened the prompt again. Infinite skate park.

5Save, with the defaults written out

On first start the whole section is written, defaults included, so you can edit keys in a text editor too. Missing actions get their defaults and the file is rewritten.

configGame/config.ini

[Keyboard]
; Two keys per action: Action=key and Action2=second key, empty for none
; Skater
Forward=W
Forward2=
Ollie=Num 2
Ollie2=Space
...
; Camera
CameraView=Enter
CameraView2=Num Enter

6Build the menu

Each row is a theme menu item: the action's text right-aligned, key 1 as the item's "extra text", key 2 as an extra child. Left/Right picks the column, a spawned script polls for the captured key, and a conflict gets a dialog.

excerptScripts/patches/levels/mainmenu/mainmenu_scripts.q

SCRIPT binding_options_wait_for_input
	BEGIN
		IF GetBindingCapture device = binding_menu_device
			BREAK
		ENDIF
		wait 1 gameframe
	REPEAT
	StopBindingCapture
	...
	IF GetBindingConflict device = binding_menu_device action = <action> input = <input>
		FormatText TextName = conflict_prompt "%k is used by %c.\\nUse it for %a instead?" k = <input_text> c = <conflict_text> a = <action_text>
		create_dialog_box { title = <title>
			no_bg
			text = <conflict_prompt>
			buttons = [ { text = "Accept" pad_choose_script = binding_options_set_input pad_choose_params = { action = <action> input = <input> } }
				{ text = "Cancel" pad_choose_script = binding_options_close_dialog }
			]
		}
	ELSE
		binding_options_set_input action = <action> input = <input>
	ENDIF
ENDSCRIPT

W is taken. Accept moves it from Forward to Flip; Cancel leaves both alone.

no_bg on the dialog, or it rebuilds the main menu backdrop with the same id and takes yours with it when it closes. The sky went grey. Twice.

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.