Configuration File Intro

This document highlights example config file entries by giving them a gray background and a different font. Italicised text in an example config file entry means to use some appropriate value for what the italicised term represents, not the literal words which are italicised. A pipe character, |, between terms in a field definition means to use only one of the terms which are separated by the pipe(s).

NoQuarter.cfg is the main config file. No quarter works by creating file associations. When working in most parts of the config file, it might help to remember that the whole point is to define that a certain file extension should be opened with a certain program.

Spaces: leading and trailing spaces get stripped as much as possible: they get stripped from beginning of lines, and from the values of fields, so use as many spaces as you like to line up and format your data.

Comments: Create a comment line (that is, a line to make notes for yourself and which will be ignored by the No Quarter program as it reads the config file), by starting it with a pound sign.

Directories: Wherever a directory may be part of the value for a field, you may use an absolute path or a path relative to where nq.exe is sitting on your hard drive. You do not have to enclose space-containing file or directory names with quotes, unless such a space-containing name is in the options field in the [emulator config] section.

User-Defined Variables and Conditional Blocks

This section might be confusing if you aren't already familiar with the concepts involved, and nothing in here is necessary for modifying your config files, so if you aren't right now on a mission to understand how the config file uses variables and conditional blocks, you might want to jump down to the next section.

To make the config file easier to manage, you can define your own variables. These variables will cause nq.exe to perform text substitutions when it processes the configuration file. The format is the variable name enclosed in dollar signs, an equal sign, and then the value to assign to the variable. For example, the line:

$ROMSDIR$ = C:\users\zanzibarbuckbuckmcfate\roms

...creates a variable named $ROMSDIR$, and any subsequent instance of the string $ROMSDIR$ in the config file will be replaced with the text on the right side of the equals sign. So later in the file, when it comes time to load roms from your arcade, genesis, and snes subfolders, instead of typing:
C:\users\zanzibarbuckbuckmcfate\roms\arcade
C:\users\zanzibarbuckbuckmcfate\roms\genesis
C:\users\zanzibarbuckbuckmcfate\roms\snes

You could type:
$ROMSDIR$\arcade
$ROMSDIR$\genesis
$ROMSDIR$\snes

And if you change the location of your roms, you just need to edit the variable assignment line instead of editing the three other lines.

The other convenience I have for working with the config file is the support of conditional blocks, similar to the c preprocessor directive #ifdef, except NQ uses an ampersand instead of the pound sign.

The line:
&ifdef WINDOWS
...means that unless the WINDOWS trigger was defined, then all subsequent lines will be ignored until the line
&endif
- or -
&else
...is encountered.

If an &else line is encountered between a &ifdef something and a &endif, then the lines between the &else and &endif will be processed if and only if the trigger in the most recent &ifdef was not defined.

To define a trigger, use &define triggername anywhere in the file before the trigger is referenced in a &ifdef triggername line.
Here is a full example of using condidional blocks:

&define WINDOWS
&ifdef WINDOWS
<20 lines of configuration>
&else
<15 lines of configuration>
&endif

In this case, the 20 lines of configuration will be processed, but the next 15 lines will not. If we comment out the WINDOWS trigger definition by changing the first line to:
#&define WINDOWS
...then the first 20 lines of configuration will be ignored, and the next 15 will be processed.

I have found the conditional blocks to be mostly useful for hardware changes: I use one block defined for CRT screen geometry vs another block defined for LCD widescreen geometry, and then I use one block defined for a certain game controller mapping versus a different block defined for when a different controller is plugged in, and I use one block defined for Windows folder locations and another block defined for Linux folder locations.

NQ Variables

There is another kind of variable, and these are configuration variables for the program. These variables take the form ?variablename value. Click here to learn about the configuration variables. Any variable not defined will receive a default value, so it's not imperative to define these variables immediately. If you're still on the fence about using NQ, then I would skip that page for now, and instead keep reading on here to learn about setting up your emulators and roms.

Images

All images will be resized to fit the maximum area available to them, while maintaining their width:height ratio (they will not be skewed). So nearly all images will end being letter-boxed or pillar-boxed within their alotted screen space, unless they happen to match the aspect ratio of their designated screen space.

Directories

• ahk
  If you want a certain AHK script to run every time a certain emulator is run, then compile your AHK script, name it with the emulator's reference name, and put it in this folder. If you want an AHK script to run when a certain rom is run, then compile your ahk script and name it the same as the rom, swapping out the rom's extension for the .exe of the compiled script.
• banners
  Volumes may be represented by an image file instead of their name. I only created this functionality because I liked having an image of five stars to represent my "favorites" volume. But any volume may use this functionality. Place an image file with the same base name as the name of the volume in this folder to have it be used as a banner image for that volume.
• font
  Font files for menu entries and tier labels need to go in this directory.
• logos
  Hardware logo images need to go in here.
• posters-master
  Posters are the main images used to represent games. Posters need to go in this directory, or in a subdirectory of this directory (but only up to one level deep). Posters may be .jpg or .png files.
• posters
  You don't put anything in this directory directly. No Quarter will create subdirectories under this folder as you create different poster dimensions for the different layouts you might create, and NQ copies the images from the "posters-master" directory into the subdirectories in here, resized to the named dimensions. If you create poster dimensions that you decide you will ultimately not be using, then you can delete the subdirectory under this directory which matches those dimensions.
• slideshow
  Create folders under this directory named after the base name of your roms, put the screenshots for the games under these folders, and now you've got the slideshows.
• sprites
  Place the sprite sheets for rascal animations here.

Starting Fresh

To remove the demo data to make way for your data:

To start with a fresh noquarter.cfg file, you can either remove the lines of demo data under the various sections of the noquarter.cfg file which came with the download, or just copy or rename the file skeleton.cfg to "noquarter.cfg".

If you don't want any of the slideshow screenshots, posters, banners, hardware logos, or sprites which came with the download (I included them for the demo), then delete the files under the directories "slideshow", "posters-master", "banners", "logos", and "sprites", and delete the directories under the "posters" folder.

Remove all of the data from favorites.txt.

---

---

The sections of noquarter.cfg:

A section begins with an opening tag, which is the name of the section enclosed in braces. NQ does not use closing tags - the opening tag of a new section will close the section preceding it.

[emulator config]

Configure your emulators. You can find many examples here. Format:
reference name, directory, executable, options, argument type, input config FSO [, minimize]

• reference name: Assign a name to the emulator configuration defined on this line.
• emulator directory: This is the directory where the emulator which you want associated with the extension/file is sitting. No Quarter will change to this directory right before running the emulator. If the emulator is on your OS's path environmental variable and so it doesn't matter where it is called from, then you can use @ as the value for this field, and No Quarter will stay in its own home directory when calling the emulator.
• emulator executable: Self-explanatory, I hope.
• options: Put in whatever command-line arguments and switches (other than the rom name) you need for the emulator. By default, a space and then the rom name will automatically be added to the end of the list of arguments when a rom is selected to run. If the rom name needs to appear on the command line somewhere other than after a space at the end of the list of arguments, then place the @ symbol at the position in this field to represent where the rom name should go. You will also need to do this if your rom names have spaces in them, so you would have to put this: "@" somewhere in this options field.
• argument type: This is how much of the rom's path/name should be passed to the emulator. There are four valid values:
  • base: The base name of the rom file, meaning the file extension should not be included.
  • file: The full file name, including the extension.
  • full: The full path and file name.
  • noarg: The rom name is not required to be passed as an argument. Use this when the emulator is only used for one game and is configured to always run that one game when it is launched. Also use for games which are OS native executables.
  Be aware that if you use either base or file here, then that very likely means that your emulator has its own list of paths to search. This must be configured separately in your emulators.
• input config FSO: (FSO = file system object) This is either a directory or a file (a directory for the on-controller-change-only version, a file for the per-game version). No Quarter can manage per-game controller configuration for any emulator which does not already natively support per-game controller configuration. It similarly allows you to manage emulator controller configuration when switching between input devices. This is a labor-intensive feature, so I advise skipping over this section until you've decided you will be using NQ and you are going to make use of this feature. Whether or not you use this feature, the least you need to know about it is that a valid FSO is required in this field, so I recommend using the emulator's directory as a dummy value for this field, and then you can skip down to reading about the minimize field.
  
  
  • Emulator input device swapping management:
    You would use this feature in the case where an emulator natively supports per-game configuration, but you want to use NQ to manage changing those per-game configurations when you change input devices. For example, I use it for Mame and Mednafen when I switch between different input devices. On the variables page, you see there is a variable ?input, in which you create whatever name you want for an input device. NQ keeps track of the last value of this variable in the file lastcontroller. This is a text file which contains the value of ?input from the last time NQ was run. To allow the use of different input mappings based on switching between different physical input devices, repeat this process for each input device (this will only fully work if the emulator stores its per-game configs in a seperate file for each game, and if the default config file is in the same directory as the per-game config files):
    
    
    1. Create a folder named _nqinputcfg under the folder which holds the emulator's per-game configuration files.
    2. For each device, decide on a name for the device, and create a folder for the device under _nqinputcfg, and name the folder the name of the input device. Using mame for an example (mame stores its per-game config files under the directory cfg), under the main mame folder, I have the folders cfg\_nqinputcfg\keyboard , cfg\_nqinputcfg\gamepad1 , and cfg\_nqinputcfg\ultratsik
    3. Plug in the device and configure the emulator for it, and do so for each game if you have different game configurations. Make sure each configuration is saved.
    4. The emulator also likely has a default configuration file, which you should configure with the defaults for the controller.
    5. Copy all of the per-game configuration files and the default config file to the folder you created in the second step.
    
    After this is done, then you can change emulator input configurations by changing the value of ?input in noquarter.cfg. The next time NQ is run, it will see that the value of ?input is different, and will copy the config files out of the directory _nqinputcfg\input device over the existing configuration files one level up for every emulator which has such a named directory. A downside to this technique is that if you decide to change any other type of configuration for your emulator(s) which happen to be stored in the same files as input configuration, then you will lose those changes the next time you change the value of ?input, unless you make that change in all of the copies you made in the subdirectories you created.
    
    
  • Per-game input configuration management:
    Use this for emulators which do not natively support per-game configuration.
    
    
    1. If you have not already configured per-controller configuration, then you need to do some of it now. Even if you do not plan to ever change your input device, you still need to create one folder per emulator named after your permanent input device. Create a folder at the same level as the configuration file for the emulator which stores the emulator's input config, and name it _nqinputcfg. Decide on a name for the device, create a folder for the device under _nqinputcfg, and name the new folder the name of the input device.
    2. Configure the emulator for default key bindings.
    3. Copy the configuration file to the folder you created in the first step.
    4. For each game:
       1. Configure input for the game, and make sure the config gets saved to file.
       2. Copy the configuration file to a file named with the rom's name, and with the same extension as the original file.
       3. Move the copy to the folder you created in the first step.
• minimize: For now, When NQ launches a game, most emulators will be missing the video, or have some other issue, if NQ does not first minimize itself. So far, I think only Mame does not require NQ to minimize itself. This field is optional, but if you add it, then NQ will minimize itself before running an emulator. The value you use for this field does not matter, but you do have to put in some kind of dummy value. Just a comma and then nothing after it will not count as this field existing. I hope to have the need for this field eliminated eventually.

[associations]

This section creates an association between a file extension (roms) and a program (emulator). There are two other types of associations other than file extension associations: a unique association, which associates a full file name with a program, and a folder + extension combination association, which is a file extension association applicable only to the files in a certain folder. The format is:
extension | name | folder + extension, emulator reference name

• extension | name | folder + extension: This field takes one of three forms:
  • universal extension association: associates a file extension with a configured emulator. Include the leading dot, so typical example values for this field would be .7z and .sfc.
  • unique association: associates a specific file with a configured emulator. Use the whole file name (but not including the path) instead of just the extension.
  • directory-specific extension association: associates the files of a directory which have the indicated extension with a configured emulator. This is used to over-ride a universal extension association for a specific directory. Create this type of association by providing a path name followed by the extension, including the dot. There is no wildcard character used to represent the base name of the roms. An example of this form is \some\path\.7z Keep in mind that even though you indicate a directory here, this will not load roms from that directory into any rom list. Using this form is only saying that if the named directory is loaded into a rom list (in the [load roms] section), then use this association for those roms. So any directory named here should also appear in the [load roms] section.
• emulator reference name: A reference name you defined in the emulator config section.

[aliases]

The roms in rom lists are sorted alphabetically. Mame requires that roms have specific names. If you want a Mame rom to sort in the list as though it had a different name, then create an alias for it in this section. This alias will also become the display name, unless you also create an entry for the rom in displaynames.txt, in which case the name in displaynames.txt will be the display name, but it will still sort based on the alias created here. Format: rom base name, alias

• rom base name The name of the rom, without the file extension.
• alias The name of the rom for alphabetical sorting purposes. Will also be the display name if there is no entry for it in displaynames.txt

[shared configs]

Documentation to come later.

[ignore]

The next section, [load roms], is where you load files from directories into rom lists. Before we get there, you can exclude certain files in those directories from being loaded by naming them in this section. Separate file names by any mix of new lines or commas. Use the full file name without the path, or you can use a directory and extension combo. I use this mostly for bios roms, and for parent/clones when you only want either the parent or the clone to be loaded into the menu. Format:

file name | directory and extension combo

The directory and extension combo works the same here as it does for the associations section. For example, I use this: roms\psx\.bin because I load this directory in the [load roms] section, but I only want the cue files. There are also .bin files in this directory, but since .bin is associated with a Genesis emulator, those .bin files would get loaded too if I did not have this "ignore" entry for them.

[load roms]

NQ uses two levels of grouping (referred to as tiers). The top level (or tier) is called volumes, and the bottom level is called rom lists. This section defines volumes and the rom lists they contain, and populates your rom lists with roms from your directories. You can load multiple directories into a list, and you can have one directory loaded into multiple lists. Only files with extensions which have an association defined will be loaded. Keep in mind any file you want put into a rom list from favorites.txt must first be loaded into some other rom list from this section. Format:

volume, rom list, directory [, hardware logo]
- or -
volume, rom list

Use the second format for rom lists which will only be populated by the favorites.txt file. Such rom lists do still need to be defined in this section.

• volume: The name of the volume which the rom list (the next field) belongs to. Naming the volume here defines/creates it. When you cycle through volumes as you use NQ, they will cycle in the order that they first appear on lines in this section of the config file. The only invalid characters for volume names are the comma and the semicolon, and the first character cannot be a pound sign.
• rom list: The name of the rom list which the roms will be loaded into. Naming the rom list here defines/creates it. When you cycle through rom lists as you use NQ, they will cycle in the order that they first appear on lines in this section of the config file. The only invalid characters for rom list names are the comma and the semicolon.
• directory: The directory to load roms from. This may be an absolute path, or a path relative to where NQ is installed. Only files which have extensions for which you created an association will be loaded.
• hardware logo: A .png or .jpg file which you have placed under the logos/ directory to represent the hardware which these roms run on (or any other image which you want associated with all of the files in this directory). This field is optional.

[key config]

Configure keyboard controls to navigate NQ. Format:

nq function, character | SDL decimal keycode

Navigation functions:

• prev rom Go up one rom in the list
• next rom Go down one rom in the list
• beginning Jump to the beginning of the rom list (the list scrolls circularly, so this also puts you one rom away from the end of the list)
• middle Jump to the middle of the rom list
• 1/3 Jump 1/3 of the way through the rom list. This also looks at the list circularly, so if the jump would put you X number of games past the end, you will end up X number of games from the beginning. For the sake of simplifying using NQ on your cabinet, I suggest either assigning buttons to both the "beginning" and "middle" functions and leave this function unassigned, or leave those two functions unassigned and assign a button to this function.
• prev list Go to the next rom list in the volume
• next list Go to the previous rom list in the volume
• tier shift while this button is being held down, the "prev list" and "next list" inputs will instead function as "prev volume" and "next volume". I recommend using this functionality over using the next two functions, but they're here anyway (not because the next two functions are buggy - they aren't - but because I thnk it's more intuitive to scroll through volumes with shifted arrow functions than with a pair of buttons):
• prev volume Go to the previous volume
• next volume Go to the next volume
• run Run the currently-selected rom
• cycle layout Cycle to the next layout
• exit exit NQ

GUI functions:

The first three functions are used to populate favorites-style rom lists. These functions make changes to the file favorites.txt, which you can just as easily edit manually if you want. The last function is for changing the menu's display names of your roms, and will edit the file displaynames.txt, which may also be edited manually as an alternative to using this in-program function.

• collect Adds the current rom to a buffer of collected roms.
• paste Pastes all collected roms into the current rom list. The roms in a list are sorted alphabetically, and all pasted roms will be inserted alphabetically, so it doesn't matter where in the list you are when you hit the button which calls this function. Pasting clears the buffer.
• delete Deletes the current rom from the current rom list. This will only work if the rom is in the list because it was added as a favorite (which happens when you add it with the collect & paste features described just above, or if you manually added it in the file favorites.txt. If the rom is in the list because it was loaded into this list because of a line in the [load roms] section, then it will not be deleted. The only way to remove such roms from rom lists is to delete the rom file from the directory it was loaded from.
• display name Create or change the display name for the current rom. This only changes what you see in the menu list, it does not rename the rom file. The display name is not used for alphabetical sorting - only the file name is used for sorting (or the optional sorting alias). You will see two vertical lines on the input field. These lines represent the width of the area used to display rom names in the menu. If the name you type expands beyond these guides, then the name will exceed the allowed area for game names in the menu. Changes made with this function are saved in the file displaynames.txt.

Character or SDL decimal keycode

• You can find SDL keycodes here. If you are going to identify a key by the SDL keycode, then you need to use the decimal value (the left-most column). You can figure out the key name by looking at the right-most column...
• ...but for most keys (keys which map to printable characters), you can just put the character for that key in this field.

[joy config]

Configure a joystick to navigate NQ. Format:

nq function, joystick button

NQ function: Use the list from the previous section.

Joystick button: The button number on the joystick. There is a helper program in the same directory as nq.exe named joytest.exe. Run this program and press a button on your joystick to see which number you should enter for the value of this field. You cannot map the analog up/down and left/right axes. They are hardcoded to prevrom/nextrom/prevlist/nextlist. If you have more than one joystick plugged in, NQ does not differentiate between which device sent a joystick button. So if you have multiple joysticks of different types, then input from any of them will be processed, but only the one you configured NQ for will be guaranteed to have the correct functions mapped to the correct buttons.

[layout]

Layouts define the geometry of the various screen objects. You may have more than one layout section (they all need to start exactly with the tag [layout] - don't add a number or anything to the tags for multiple layouts). Your different layouts can be cycled through when No Quarter is running by hitting the cycle layout button.

I have this section on the bottom of this documentation page because creating your own layouts is probably one of the last things you're going to do, but in the file noquarter.cfg, the layout section(s) need to be the first section(s) in that file.

The width of the No Quarter screen = padding * 2 + max slide width + divide + max poster width
The height of the No Quarter screen = padding * 2 + tier height * 2 + max poster height

Format:
property, value

These are the properties you should define for each layout:

• padding
  The number of pixels to pad on the outside of all four sides.
• divide
  The number of pixels to space between the menu/slideshow left half of the screen and the poster/tiers right side of the screen.
• menu items
  The number of roms in your list to be displayed at one time. This number should be odd. If it is even, then the actual value used when the program runs will be one less than the value you indicate here. This value should be tweaked in conjunction with max slide height and menu item height in order to get the maximum number of items on the screen as possible. In other words, the larger are max slide height and menu item height, the smaller this number will have to be. I will some day have NQ calculate this value for you.
• max slide width
  The width for the left half of the screen. This is not only the maximum width for slides, but will also be the width of the game menu list.
• max slide height
  in pixels
• max poster width
  in pixels
• max poster height
  in pixels
• menu font size
  Font size of game list menu items.
• menu item height
  The greater the difference is between this value and menu font size, the greater the spacing between menu items.
• tier height
  The vertical pixels allotted for each of the two tier labels. The tier frames are also squeezed into this area, and there is also the padding variable on the next line which takes pixels out of this allotment, so this shouldn't just match the font size of the tier font - it needs to be larger than that.
• tier frame padding
  in pixels
• tier font size
  Font size of tier labels.
• square def
  Logo image files are resized so that they they fit as much of the the area on the screen reserved for the slideshow as possible while maintaining their ratio of width:height. Hardware logos tend to have banner-style dimensions. That is, their length is significantly greater than their height. But some are square or square-ish. If you have a mix of square and banner logos, the square logos end up looking much bigger (because the slideshow area is square-ish). I do not like the way this makes square-ish logos seem more important than banner-shaped logos. So the squaredef variable, and the one below (squareshrink) shrink square-ish logos. This variable is how close to 1:1 the width:height ratio should be before a logo is considered square, and needs to be a floating point number close to 0.0. The closer this number is to 0.0, the closer the banner image needs to be to a perfect square before it kicks in the next variable:
• square shrink
  The percentage of its full size a square image should be shrunk to. So, for example, a value of 80 here means that the logo image would only be 80% of the width and height it would have been had it been fully resized to fully occupy the available on-screen area.
• posters on
  This is an optional line, and it is a single field. "posters on" is a flag all by itself, and so does not require any more data on the line. If a layout does not contain a "posters on" line, then the default placeholder image will be used as the poster for every game. Why am I forcing you to explicitly indicate that you want the posters you spent hours selecting/downloading/creating to be used to represent your games? Because when posters are turned on for the first time for any new poster dimension (that is, a layout contains a max poster width * max poster height which you have never used in your NQ install before), then No Quarter will make resized copies of all your posters to match the new dimensions. This could take a minute or two if you have lots of posters. You might be tweaking a layout, and not be sure if you're going to stick with this new max poster width * max poster height, and so you could be wasting time waiting for the copies to be made. Once you have settled on new poster dimensions, then you should add a "posters on" line to the layout, and then the next time NQ runs, the copies will be made. This batch copying will just be a one-time occurrence, but NQ does check for additional or updated images under posters-master/ every time it runs, and makes more or updated copies as needed.
• rotation
  This is an optional line, and it will consist of a single field, and the two allowable values are "clockwise" and "widdershins". In other words, the whole line should consist of just one of those two words, without the quotations (but any number of leading spaces is still allowed, as with all lines in the config file.)

Configuration File page 2 - variables