Configurable USB Loader's options explained
This page provides a list of all Configurable USB Loader's options with notes about how to use them. Each entry will be given with the definition from README-CFG.txt which can be found in every .zip version of the loader. This page starts by describing the file types used, then describes the options and finally shows the options used in the sample GAF config. You will also find the Configurable USB Loader Configurator which is a Windows application which helps you set all these values in a GUI and creates the config.txt and theme.txt files needed to configure the loader.
This page was most recently updated with the release of version 57 of Configurable USB Loader.
Description of Files
Global Options (config.txt)
Config.txt is a file which lets you configure many aspects of the Loader. It is generally located in sd:/usb-loader/ and/or sd:/apps/USBLoader/. Wherever it is first found is the base directory used for all other paths. Both config.txt files will be read if you have one in each of the mentioned folders. The rest of this page assumes you have both and thus will use sd:/usb-loader as the base directory.
Theme Options (theme.txt)
Configurable USB Loader allows you to provide separate themes which you can switch between while running the Loader. This is performed via the Global Options Menu. A theme.txt file for each theme is stored in sd:/usb-loader/themes/theme-name/ containing options that describe the given theme. The startup theme is chosen in config.txt with the theme option.
Theme overrides (config.txt)
While all options can appear in config.txt, including theme options, some of them behave differently. If the same option appears in both theme.txt and config.txt, then the file with priority depends on the option. The following options use the value in config.txt as their value:
The other theme options will use the value in theme.txt.
Game Settings (settings.cfg)
Settings.cfg is where all the options saved within the loader itself are stored. This is predominantly the favorites and hidden games, along with all the per-game settings. In addition, several options may be saved here when you perform the action to save all settings at the Global Options screen (by pushing 2). If these options are located in settings.cfg, they override the same settings in config.txt. The options that may appear in settings.cfg are:
- theme - Theme to load at startup
- profile - Default profile to load at startup
- device - Default device where games are stored (SD/USB)
- partition - Default partition where games are stored
- gui_style - Initial GUI style at startup
- gui_rows - Inital number of rows for gridflow GUI styles
Meta Arguments (meta.xml)
The meta.xml file included in the sd:/app/usbloader/ directory can be used to house any of the above global options and global theme override options. In addition, there are a few special options (not yet listed on this page) that work differently or which can only appear within meta.xml. The most important of these is the ios option. For instructions to edit meta.xml, see the USB Loader page, which provides some examples for setting the ios option, but other options can be specified the same way if desired.
There are four default background images: background.png, background_wide.png, bg_gui.png and bg_gui_wide.png. The loader will first look in the chosen theme directory and then the base directory for these files. The names of these images can be changed using the background_base and background_gui options. Note that if the wide versions are not present, the values of the 4:3 options will be checked as well.
There are four default background images: bg_overlay.png, bg_overlay_w.png, bg_gui_over.png and bg_gui_over_w.png. The loader will only look in the chosen theme directory (or the base directory when no theme is chosen) for these files. Overlay files are an image that is placed over the background image, typically with transparency. This can be used to add the same set of buttons to every background image used, or to automatically add console fading when a transparent console is desired.
The GUI has several other images that can be changed by adding files to either the theme or base directories. See the full zip of Configurable USB Loader for examples. The following files are allowed:
|favorite.png||icon that appears on favourites|
|pointer.png||mouse pointer, the point should be at the centre|
|hourglass.png||picture displayed while covers load|
|font.png||allow changes of characters within the font for GUI text|
|font_uni.png||adds latin Unicode characters to the font set for GUI text|
|font_clock.png||allow changes of characters within the font for clock text|
Language Files (*.lang)
Translation capabilities were added in v52 of Cfg. The translation files made by other users are available in this thread and are also packed into the releases of Cfg. Translation files are of the form LANGUAGE.lang where LANGUAGE is typically a two-character code for the language, but may be any string. Language files should be placed in the languages subdirectory of the base directory (e.g., sd:/usb-loader/languages/IT.lang).
The Configurable USB Loader Configurator allows you to set all options and write theme.txt and config.txt out to files. Use the information below to work out which values you want and simply set them in the Configurator. Here's a look at the main interface and console wizard for theme generation from v50:
Just unzip the zip and run CfgLoaderConfigurator.exe to use the app.
Sample button images can be found here.
Configurator is now mostly convertible into other languages. You can change the tooltips for all controls and text for buttons and so on. This simply needs the inclusion of five files in the same directory as the executable. Sample versions of those files, including instructions within the files themselves, can be found here.
A Spanish translation has been created by PabloACZ of GBAtemp and Emudesc, the latest version of which can be found here.
If you are using a Mac or Linux, you should be able to run the same application using Mono (v2.4.2 or later). Please use the discuss link at the bottom of this page if you have problems
Options will be described by particular statements upon what you would like to do. The options handled by each section are listed in parentheses for ease of searching. Expand statements that you want to find out more about. For a list of all available options, see the README-CFG.txt file from the latest version of Configurable USB Loader. Options are separated between theme and global options to let you know where you can use them. Each option appears in a box and is shown as the name of the option, followed by an equals sign, followed by a comma separated list of values the option can take. The default value shown in bold is the value that will be used if the option does not appear in the config.txt/theme.txt files. If you don't want to edit the files yourself, we have created a tool for you (see the Configurator section above).
Theme Options (theme.txt and/or config.txt)
Tweaking the look of the menu mode
Tweaking the look of the GUI mode
Global Options (config.txt only)
General look and feel
Tweaking the menu mode
Tweaking the GUI mode
Titles and database info
GAF's config.txt and theme .txt
The config.txt provided in the sample GAF config is listed below:
theme = GAF
device = usb
gui = start
gui_style = coverflow3d
This simply sets the device to default to the USB drive and starts in GUI mode with the GAF theme selected using the coverflow3d layout as default.
The theme.txt provided in the sample GAF config is listed below:
background = backgroundGAF.png
wbackground = backgroundGAF_wide.png
layout = large3
covers = 1
cover_style = 3d
console_transparent = 1
This sets a default large3 template layout with transparent custom background and 3d covers.
The locations of files contained in the sample GAF config and their descriptions are listed below:
|apps/USBLoader/config.txt||Global options file|
|USB-Loader/config.txt||Copy of global options file|
|USB-Loader/themes/GAF/theme.txt||Theme options file|
|USB-Loader/themes/GAF/backgroundGAF.png||Menu background image for 4:3|
|USB-Loader/themes/GAF/backgroundGAF_wide.png||Menu background image for 16:9|
|USB-Loader/themes/GAF/bg_gui.png||GUI background image for 4:3|
|USB-Loader/themes/GAF/bg_gui_wide.png||GUI background image for 16:9|
|USB-Loader/themes/GAF/pointer.png||Change mouse pointer in GUI mode|