Guide 04

Screen settings

How to add Options › Screen: window or fullscreen, a render resolution, and a 60 / 120 fps limit, saved to config.ini. Also: how to patch the game's menus at all.

GoalPick a mode and resolution in a native-looking THUG menu, hit Apply, and have it stick.

Options: Screen, Keyboard and Gamepad added after Load Game.

Options &rsaquo; Screen: check marks show the current choice; Apply is at the bottom. — Options › Screen: check marks show the current choice; Apply is at the bottom.

1Read config.ini before the window exists

diffWn32/Code/Plat/Gfx/nx/nx_init.cpp · 5660c56

@@ -48,6 +49,14 @@ void WaitForNextFrame(void)
 void InitialiseEngine( void )
 {
+	// Read the screen settings from config.ini
+	LoadDisplaySettings();
+
+#ifdef __APPLE__
+	// Fullscreen as a borderless window covering the screen, instead of a separate Space with a transition animation
+	SDL_SetHint(SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES, "0");
+#endif
@@ -73,13 +82,13 @@ void InitialiseEngine( void )
-	// Create window
-	int width = 720 * 16 / 9;
-	int height = 720;
+	// Create window (in window mode it's sized to the render resolution)
+	int width = GetDisplaySettings().width;
+	int height = GetDisplaySettings().height;

-	Uint32 window_flags = SDL_WINDOW_SHOWN | SDL_WINDOW_OPENGL | SDL_WINDOW_RESIZABLE;
+	Uint32 window_flags = SDL_WINDOW_SHOWN | SDL_WINDOW_OPENGL | SDL_WINDOW_RESIZABLE | GetDisplayWindowFlags();

No Spaces, no swoosh animation. Fullscreen is just a borderless window that happens to be very large.

2Render at the chosen size, letterbox the rest

The render resolution no longer follows the window. The present pass fits the backbuffer into the drawable, keeping its aspect ratio, and clears the bars to black.

diffWn32/Code/Plat/Gfx/p_nx.cpp · 5660c56

@@ -68,20 +69,6 @@ namespace Nx
-				case SDL_WINDOWEVENT:
-					switch (event.window.event)
-					{
-						case SDL_WINDOWEVENT_SIZE_CHANGED:
-						{
-							// Set viewport (use drawable size, which differs from window size on HiDPI displays)
-							...
-							NxWn32::set_dimensions(width, height);
@@ -127,19 +114,22 @@ namespace Nx
-		glClear(GL_DEPTH_BUFFER_BIT);
+		glClearColor(0.0f, 0.0f, 0.0f, 1.0f);
+		glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);

-		// Draw backbuffer quad
+		// Draw backbuffer quad, scaled to fit the window
+		NxWn32::SetPresentViewport();
 		NxWn32::EngineGlobals.fullscreen_quad->Bind();
 		glDrawElements(GL_TRIANGLES, 6, GL_UNSIGNED_SHORT, nullptr);
+		glViewport(0, 0, NxWn32::EngineGlobals.backbuffer_width, NxWn32::EngineGlobals.backbuffer_height);

new fileWn32/Code/Plat/Gfx/nx/display.cpp

void SetPresentViewport()
{
	int drawable_w, drawable_h;
	SDL_GL_GetDrawableSize(EngineGlobals.window, &drawable_w, &drawable_h);

	float scale_x = (float)drawable_w / (float)EngineGlobals.backbuffer_width;
	float scale_y = (float)drawable_h / (float)EngineGlobals.backbuffer_height;
	float scale = std::min(scale_x, scale_y);

	int width = (int)((float)EngineGlobals.backbuffer_width * scale + 0.5f);
	int height = (int)((float)EngineGlobals.backbuffer_height * scale + 0.5f);

	glViewport((drawable_w - width) / 2, (drawable_h - height) / 2, width, height);
}

3Patch the retail scripts (the trick behind every menu here)

The retail qb.pre takes priority over compiled scripts, so editing Scripts/*.q does nothing. Instead, after any .qb loads, a matching scripts/patches/<path> is parsed on top. Its symbols are registered under the original file name, so level unloads take the patch with them and reloads re-apply it.

diffCode/Gel/Scripting/file.cpp · 5660c56

@@ -98,6 +99,30 @@ void LoadQBFromMemory(const char* p_fileName, uint8* p_qb, EBoolAssertIfDuplicat
+bool LoadQBPatch(const char *p_fileName)
+{
+	char p_patch_name[256];
+	snprintf(p_patch_name, sizeof(p_patch_name), "scripts\\patches\\%s", p_fileName);
+	if (!File::Exist(p_patch_name))
+	{
+		return false;
+	}
+
+	uint8 *p_qb = (uint8*)Pip::Load(p_patch_name);
+	ParseQB(p_fileName,p_qb,NO_ASSERT_IF_DUPLICATE_SYMBOLS,false);
+	Pip::Unload(p_patch_name);
+
+	restart_dirty_scripts();
+	return true;
+}

diffCode/Sk/Scripting/gs_file.cpp · 5660c56

@@ -223,6 +223,10 @@ void LoadQB(const char *p_fileName, EBoolAssertIfDuplic
 	RemoveChecksumNameLookupHashTable();
+
+	// Apply the PC port's changes to this qb, if any (done last, since it replaces the checksum
+	// name lookup table that the node array processing above uses)
+	Script::LoadQBPatch(p_fileName);
 }

Patches compile like any script, from a list in CMake:

diffCMakeLists.txt · 5660c56 + 28ef9a3

+# Script patches: parsed on top of the retail qb with the same path (see Script::LoadQBPatch),
+# so they're not listed in qdir.txt
+set(SCRIPT_PATCHES
+	"levels/mainmenu/mainmenu_scripts"
+	"scripts/game/skater/skater_sfx"
+)

4Expose C++ to the menu

Three script functions: read the settings, list resolutions that fit the screen, apply. Registered in ftables.cpp like the retail ones.

diffCode/Sk/Scripting/cfuncs.cpp · 5660c56 + c46ec33

+// @script | ApplyScreenSettings | Switches window / fullscreen mode, resolution and frame rate limit, and saves them to config.ini
+bool ScriptApplyScreenSettings(Script::CStruct *pParams, Script::CScript *pScript)
+{
+	NxWn32::sDisplaySettings settings = NxWn32::GetDisplaySettings();
+
+	int fullscreen = settings.fullscreen ? 1 : 0;
+	pParams->GetInteger("fullscreen", &fullscreen);
+	pParams->GetInteger("width", &settings.width);
+	pParams->GetInteger("height", &settings.height);
+	pParams->GetInteger("max_fps", &settings.max_fps);
+	settings.fullscreen = (fullscreen != 0);
+
+	NxWn32::ApplyDisplaySettings(settings);
+	return true;
+}

diffCode/Sk/Scripting/ftables.cpp · 5660c56

+	{ "GetScreenSettings", CFuncs::ScriptGetScreenSettings },
+	{ "GetScreenResolutions", CFuncs::ScriptGetScreenResolutions },
+	{ "ApplyScreenSettings", CFuncs::ScriptApplyScreenSettings },

5Build the menu in QScript

The options menu is copied whole into the patch with one more item; the Screen menu reuses the theme's scrolling menu and adds a check mark sprite as each item's 5th child.

diffScripts/patches/levels/mainmenu/mainmenu_scripts.q · 5660c56

+	theme_menu_add_item { text = "Screen"
+		id = options_screen
+		pad_choose_script = options_menu_exit
+		pad_choose_params = { new_menu_script = create_screen_options_menu }
+		centered
+		no_bg
+	}
@@ SCRIPT screen_options_apply @@
+SCRIPT screen_options_apply
+	ApplyScreenSettings fullscreen = screen_menu_fullscreen width = screen_menu_width height = screen_menu_height max_fps = screen_menu_max_fps
+ENDSCRIPT

fullscreen = screen_menu_fullscreen passes a global by name, and CStruct::GetInteger quietly resolves it. QScript is weird. QScript is wonderful.

660 or 120 fps without breaking the physics

The limiter uses the high-resolution counter, sleeps while there's time and spins for the last 2 ms. Game logic already scales by frame time, except for two spots that assumed 60.

diffWn32/Code/Plat/Gfx/nx/nx_init.cpp · c46ec33

@@ -25,25 +25,33 @@ sEngineGlobals	EngineGlobals;
-static constexpr double c_frame_time = 1000.0 / 60.0;
 void WaitForNextFrame(void)
 {
+	// Frame rate limit from the screen settings (60 or 120 fps)
+	const double frame_time = 1000.0 / (double)GetDisplaySettings().max_fps;
+
 	while (1)
 	{
-		double now = (double)SDL_GetTicks64();
+		double now = GetTimeMs();
 		if (now >= s_next_frame)
 		{
-			s_next_frame += c_frame_time;
+			// Fell behind (or the limit was raised): start counting from now, instead of rushing to catch up
+			if (now >= s_next_frame + (frame_time * 5.0))
+				s_next_frame = now;
+			s_next_frame += frame_time;
 			break;
 		}
-		SDL_Delay(1);
+
+		// Sleep while there's time to spare (SDL_Delay can oversleep a bit), then spin for the rest
+		if (s_next_frame - now > 2.0)
+			SDL_Delay(1);
 	}
 }

diffCode/Sk/Objects/manual.cpp · c46ec33

@@ -514,7 +514,8 @@ void CManual::DoManualPhysics()
 			// always add some randomness to it, to make sure we don't ever get stuck
-			mManualLeanDir += (Mth::Rnd(50))/100.0f * Mth::Sgn(mManualLeanDir);
+			// (scaled with the frame length, so the drift doesn't speed up above 60 fps)
+			mManualLeanDir += scale_with_frame_length(frame_length, (Mth::Rnd(50))/100.0f) * Mth::Sgn(mManualLeanDir);

diffWn32/Code/Plat/Gfx/p_nx.cpp · c46ec33

@@ -93,8 +93,13 @@ namespace Nx
-				// Get alpha to blur at
-				glUniform4f(glGetUniformLocation(shader->program, "u_col"), 1.0f, 1.0f, 1.0f, NxWn32::EngineGlobals.screen_blur);
+				// Get alpha to blur at (the amount is per 60th of a second, so above 60 fps less of the
+				// previous frame is kept per frame, to make the trail fade at the same speed)
+				float blur_alpha = NxWn32::EngineGlobals.screen_blur;
+				int max_fps = NxWn32::GetDisplaySettings().max_fps;
+				if (max_fps > 60)
+					blur_alpha = 1.0f - powf(1.0f - blur_alpha, 60.0f / (float)max_fps);

At 120 fps the manual balance drifted twice as fast. The skater was fine. My thumbs were not.

7The result

configGame/config.ini

[Screen]
Fullscreen=0
Width=1280
Height=720
MaxFPS=60

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.