View source for Gamepad UI in mods

{{Source topicon}}
<div style="float:right">[[File:HL2_GamepadUI_menu.png|340px|thumb|Screenshot of the Gamepad UI from {{hl2|4}}.]]
[[File:Portal_GamepadUI_menu.png|340px|thumb|Screenshot of the Gamepad UI from {{portal|4}}.]]
</div>
This page details how to make your Portal or Half-Life 2 mod compatible with the controller-oriented UI added in early 2022. This will ensure that your mod is properly playable on [[Steam Deck]], and it's menu can be navigate using controllers.
{{toc-right}}
{{note|Only [[Half-Life 2]], [[Half-Life 2: Episode One|its]] [[Half-Life 2: Episode Two|episodes]], and [[Portal]] currently implement the gamepad UI.}}
{{note|The gamepad UI code doesn't come with SDK 2013, but Joshua Ashton (the Valve contractor who built the UI) has separately released a [https://github.com/Joshua-Ashton/HL2-GamepadUI version] which is compatible with the SDK. If you want to support gamepad UI in your SDK 2013 based mod, you will need to add this to your codebase.}}
{{bug|hidetested=1|The right side of the Gamepad UI will be cut off if you run the game at 4:3 aspect ratio (this issue is not affected on 16:9/16:10 aspect ratio).
:{{Confirm|Is this fixed in the SDK 2013 version of gamepad UI?}}
}}
{{bug|hidetested=1|If the menu background map fails to load, the game will softlock on the loading screen on startup. This means mods that want to support gamepad UI '''must''' include proper background maps.
:{{note|This appears to not happen in the SDK 2013 version of the gamepad UI, so it is only an issue for mods based directly on HL2/Portal.}}
}}
{{bug|hidetested=1|The game will also freeze on startup if <code>sound/ui/gamestartup*.mp3</code> files are present. If menu music is desired, you can play it through entity logic in background maps instead.
:{{note|This was fixed in the public SDK 2013 version of the gamepad UI.}}
}}


{{todo|Page should perhaps include images for some things, or template files}}

==Games and mods that uses Gamepad UI==
*{{hl2|4}}, {{hl2lc|4}} and Episodes
*{{portal|4}}
*{{ez2|4}}
{{todo|Add more games to this list.}}

== Basics ==

The gamepad UI is enabled by default on Steam Deck, and can also be enabled on any platform by passing <code>-gamepadui</code>, or running Steam in Big Picture mode (since {{hl2}} 20th anniversary update) in the launch options.

By default, enabling {{code|-gamepadui}} (without using {{code|-dx9}}) will also enable the [[Vulkan]] renderer, which can cause the game to crash if the GPU does not support Vulkan.{{cite|1}} However, latest version of {{hl2}} (20th Anniversary) and {{portal}} (since May 20, 2025 update) changed this, so enabling Gamepad UI no longer enables Vulkan renderer automatically.

Additionally, on {{portalrtx|1}} (or RTX Remix games), you must use {{code|-dx9}}, otherwise the game would try to load up the original DXVK instead of RTX Remix's DXVK and completely breaks the renderer. Going to Video Options on Portal with RTX while also having Gamepad UI enabled will cause the new PBR-capable/RTX materials to be disabled.

The UI layout files are placed in a <code>gamepadui</code> folder within a search path, though ''which'' search path they're in by default depends on the game:

* Half-Life 2: <code>hl2/gamepadui/</code> (fonts), <code>hl2/hl2_pak_dir.vpk/gamepadui/</code> (layouts)
** Episode One: <code>episodic/ep1_pak_dir.vpk/gamepadui/</code>, plus the above
** Episode Two: <code>ep2/ep2_pak_dir.vpk/gamepadui/</code>, plus the above
* Portal: <code>hl2/gamepadui/</code>, <code>portal/portal_pak_dir.vpk/gamepadui/</code>

The graphics for the gamepad UI are located at <code>materials/gamepadui/</code>. These are always packed into the games' VPKs, though you don't need to do this for your mod.

Now that you know what files you'll be working with, you can get started adapting them for your mod.

== Before compiling ==
First, you have to remove the {{code|<nowiki>#if</nowiki>}} and {{code|<nowiki>#endif</nowiki>}} for "0" on {{code|preset=0|Panel.h}} on the vgui_controls project

The code was supposed to be like around ln 952 to 975 on {{code|Panel.h}}

If you don't do this, you might get errors about gamepadui_buttons.obj and gamepadui.dll while compiling

== Layout changes ==

=== Removing the achievements button ===

As with the desktop UI, the list of achievements is hardcoded and can't be changed in non-code mods, so the achievements button should be removed from the menu. Copy <code>mainmenu.res</code> into your mod's <code>gamepadui</code> folder, open it, and find the following entry:

<pre>
	"Achievements"
	{
		"text"			"#GameUI_GameMenu_Achievements"
		"command"		"cmd gamepadui_openachievementsdialog"
		"priority"		"2"
		"family"		"all"
	}
</pre>

Simply remove it from the file. This will get rid of the achievements button.

=== Removing the post-game radios toggle ===

{{only|{{portal}}}}

The gamepad UI includes an option to disable the ARG radios that appear after completing the game. While this is a useful quality-of-life feature in base Portal, it doesn't do much in mods, as the ARG radios only get added to the original Portal maps. As such, you may wish to remove it in your mod. To do so, copy <code>options.res</code> into your mod's <code>gamepadui</code> folder, open it, and find the following entry under the Portals category:

<pre>
			"Radios"
			{
				"text"			"#Deck_Radios"
				"type"			"wheelywheel"
				"convar"		"portal_disable_radios"

				"options"
				{
					"1"	"#gameui_disabled"
					"0"	"#gameui_enabled"
				}
			}
</pre>

As with the achievements button, you can simply remove it.

== Graphics ==

=== High resolution chapter images ===

The gamepad UI uses new high-resolution versions of the chapter images, so by default your mod's chapters will appear using the original images, even if you provided custom ones for the desktop UI. The new chapter images should be taken at 16:9 aspect ratio, resized to 1024x512 (or 2048x1024), and placed at <code>materials/gamepadui/chapter#.vtf</code>, with <code>#</code> being replaced by the chapter number.

If your mod has fewer chapters than the base game, don't bother including VMTs, as these will automatically be reused from the base game. If you do need more chapters than this, the VMTs should be set up as follows:

<pre>

"UnlitGeneric"
{
	"$basetexture" "gamepadui/chapter#"
	"$vertexcolor" 1
	"$vertexalpha" 1
	"$ignorez" 1
	"$no_fullbright" "1"
}
</pre>

Replace <code>#</code> in the basetexture line with the chapter number.

=== Logo ===

You can choose to make your logo an image or text. By default, Half-Life 2 and its episodes use a text logo, while Portal uses an image logo.

==== Image ====

Create an image with a 3:1 aspect ratio, and place your logo in it as desired. Resize the resulting image to 1024x512, then place it in <code>materials/gamepadui/</code> with any name.

For Portal mods, naming it <code>portal_logo.vtf</code> is all you need to do to get it to appear. If you want to change the name of the image or are modding Half-Life 2, there's a bit of extra setup involved.

First, an accompanying VMT is needed to load the texture. It should be set up as such:

<pre>
"UnlitGeneric"
{
	"$basetexture" "gamepadui/logo"
	"$vertexcolor" 1
	"$vertexalpha" 1
	"$translucent" 1
	"$ignorez" 1
	"$no_fullbright" "1"
}
</pre>

(Replace <code>logo</code> in the basetexture line with the name of the texture.)

Now you need to configure the main menu to actually display your logo. Copy <code>schememainmenu.res</code> into your mod's <code>gamepadui</code> folder and open it. Under <code>BaseSettings</code>, add the following line:

<pre>
		"Logo.Image"							"gamepadui/logo"
</pre>

(Again, you should replace <code>logo</code> in the material path with whatever you named your VMT.)

This will make your logo image appear in-game.

==== Text ====

Copy <code>schememainmenu.res</code> into your mod's <code>gamepadui</code> folder and open it. This contains all of the configuration you'll need, although what you need to do from here depends on whether you're modding Portal or Half-Life 2.

For Portal, under <code>BaseSettings</code>, remove the <code>Logo.Image</code> line. This will disable the logo image that Portal normally uses and fallback to text. This is all you need to do, unless you want to change the font, in which case continue reading.

Half-Life 2 defaults to a text logo, but it uses the HL2 icons font which appears nonsensical with other text. To fix this, or to change the font in a Portal mod, locate the following entry under <code>Fonts</code> near the bottom of the file:

<pre>
		"Logo.Font"
		{
			"settings"
			{
				"name"			"HalfLife2"
				"tall"			"34"
				"weight"		"400"
				"antialias"		"1"
			}
		}
</pre>

Change the settings as desired. In addition to these, <code>blur</code> can also be used to blur the text by a certain amount.

Portal uses Trebuchet MS as the font with a tall value of 72 and a blur of 2, so you may wish to simply copy that, but you can also configure this in any way you want. If you're using a custom font, you'll want to place the font file in either <code>resource/</code> or <code>gamepadui/fonts/</code>, and add an entry for it to <code>CustomFontFiles</code> at the bottom of the file.

Like in the desktop UI, the game title is pulled from {{ent|gameinfo.txt}} automatically, and does not need to be separately specified anywhere.

=== Loading screen icon ===

The icon in the center of the loading screen spinner defaults to a lambda or portal icon. You may wish to change this to match your mod's logo. The texture should be 256x256 and located at <code>materials/gamepadui/game_logo.vtf</code>. There are no special considerations in regards to the aspect ratio, but the icon should ideally fit within a circle about 200 pixels in diameter to avoid overlapping the spinner.

== Bonus maps and commentary ==

Unlike the desktop UI, the gamepad UI has the bonus maps and developer commentary buttons placed in the bottom right of the New Game menu, with the former opening a submenu while the latter will directly load the highlighted chapter in commentary mode. Unfortunately however, these extra buttons are hardcoded to only appear when specific <code>-game</code> parameters are passed on the command line. As such, it's currently impossible for these buttons to appear in mods.

=== Bonus maps ===

For bonus maps, a workaround is to add the button directly to the main menu, like in the desktop UI. Open the <code>mainmenu.res</code> file from earlier, and add the following entry anywhere between two of the buttons:

<pre>
	"BonusMaps"
	{
		"text"			"#GameUI_GameMenu_BonusMaps"
		"command"		"cmd gamepadui_openbonusmapsdialog"
		"priority"		"3"
		"family"		"all"
	}
</pre>

(Depending on where you put it, you may need to adjust the <code>Priority</code> values for all of the buttons - they should be in descending order. Not doing this can result in the buttons randomly changing order after the menu is reloaded.)

The bonus maps menu will load your existing bonus map definitions and icons, so no specific changes need to be made to those. However, the menu currently has two limitations:
* Scrolling is not properly supported, so folders with more than 6 maps will have them stick off the bottom of the screen (though they can still be selected)
* The "description" line that can be set for a map or folder is not shown anywhere in gamepad UI

=== Commentary ===

Unfortunately, the above workaround doesn't work for developer commentary due to it being entirely integrated into the New Game menu. It may be possible to add commentary as a bonus maps entry, but this would also appear in the desktop UI.

== Additional customization ==

{{todo|Fully document how to customize fonts/colors, main menu items, and options. A work in progress page is [[Customizing Gamepad UI|available here]].}}

{{references|1=
{{ref2|cite id=1|Verified by [[User:Kr0tchet|kr0tchet]] ([[User talk:Kr0tchet|talk]]) on February 27, 2024:<br>'''''Tested on first-party ([[Valve]]) games only, third-party games not tested as it's unknown whether those mods have Vulkan support added or not.'''''}}
}}

[[Category:HUD]]
[[Category:VGUI]]