Configuration

Global configuration file

Settings for Boxtron can be found in ~/.config/boxtron.conf (or wherever XDG_CONFIG_HOME points to). Most of the settings from that file can be overridden using environment variables.

If you want to edit DOSBox configuration for a specific game instead, you can edit user configuration file in game's installation directory.

confgen.force

Set this value to true if you want Boxtron to re-create DOSBox user configuration on every run. This option is useful mostly for development purposes. Defaults to: false

midi.enable

This option is used to control the start of software MIDI synthesiser for all games. You can override value for specific game with BOXTRON_NO_MIDI. Defaults to: true

midi.soundfont

The filename of a soundfont file used by software MIDI synthesiser. Boxtron will search for a soundfont in ~/.local/share/soundfonts/, ~/.local/share/sounds/sf2/ and in default system-wide locations.

Defaults to: FluidR3_GM.sf2. If not found, then default.sf2.

midi.use_sequencer

You can name your preferred MIDI synthesiser here to override the one picked by default. If not found then software synthesiser will be started as a fallback.

Value is treated as a regular expression using Python syntax, matched against the name of a MIDI client (case-insensitive); to list MIDI clients connected, use: $ aconnect -l.

For example, to match a client named "CASIO USB-MIDI", you can use value "casio".

You can override this per-game with BOXTRON_USE_MIDI_SEQ environment variable.

Defaults to an empty string; Boxtron will look for known hardware and software synthesisers first - if not found, then software synthesiser (midi.synthesiser) will be started.

midi.synthesiser

Select the preferred software synthesiser. Can be either timidity or fluidsynth (you need to install it separately; if missing, Boxtron will fall-back to using Timidity).

Defaults to: timidity

dosbox.fullscreenmode

• screen <num>, where <num> is the number of the display you want to use. Run $ xrandr --listmonitors to learn what numbers you can use. You can override value for specific game with BOXTRON_SCREEN. Defaults to screen 0, which is your primary display.
• desktop The whole desktop area will be used (all displays) with the game centred, the native resolution of your displays will be preserved. This is a fallback value in case screen detection won't work.
• disabled DOSBox will start in windowed mode.

dosbox.scaler

Pick the default scaler, that you want to use for all games. You can override selection per-game by changing option render.scaler in user .conf file in game's installation dir. You can see the full list of available options with visualisation on DOSBox wiki.

By default, DOSBox scalers do not work for games using resolution 640x480 or higher. You can force it anyway by adding forced after the scaler name, e.g. rgb3x forced.

Defaults to: normal3x

dosbox.cmd

Change the command that you use to run DOSBox. For example:

To run DOSBox, that you compiled yourself:

cmd = ~/path_to_dosbox/src/dosbox

To run DOSBox-X fork installed from snap store:

cmd = snap run dosbox-x

You can override value for specific game with BOXTRON_DOSBOX_CMD. Defaults to: dosbox

DOSBox configuration

DOSBox configuration files are incompatible between different operating systems. Boxtron interprets Windows-specific .conf files supplied by the game publisher and translates them for Linux compatibility. It also improves them by introducing runtime-specific values, environment variables and game tweaks to work around some DOSBox and game limitations.

To accomplish this, a configuration is split into two files: automatic conf file (generated anew with every start of the game) and user conf file (created on the first run only).

Configuration files are generated in the current working directory - for Steam games, this is usually (but not always) game's top-level installation directory.

Global DOSBox configuration files (stored, e.g. in ~/.dosbox) do NOT affect any game started through Boxtron.

Automatic .conf file

These files are named boxtron_auto.conf and reflect Boxtron user settings and runtime state of the machine when the game is starting.

Values in this file can be overriden by editing user .conf file:

User .conf file

These files are named boxtron_<appid>_<hash>.conf, user can override any DOSBox configuration value here (but take note, that future DOSBox versions might use incompatible configuration values).

Games that provide more than one launcher option through the Steam launcher will generate several user conf files, each with a different value of <hash>.

Environment and configuration variables

These variables can be set in Steam client. For example, to force game to use your secondary screen, right-click your game in Steam Library, select Properties → Set Launch Options… and set: BOXTRON_SCREEN=1 %command%.

Name	Values	Description
BOXTRON_DOSBOX_CMD	command	Use this command to run the game. Overrides value in dosbox.cmd setting.
BOXTRON_NO_MIDI	0 or 1	Set 1 to turn off software MIDI synthesiser.
BOXTRON_NO_MIDI_PRESET	0 or 1	Set 1 to prevent patching of game files.
BOXTRON_USE_MIDI_SEQ	regex	Specify name of the MIDI sequencer you want to use.
BOXTRON_RUN_EXE	path to file	Set path to executable file to be launched instead of Steam-selected one. Example: BOXTRON_RUN_EXE="GAME/SETUP.EXE" %command%
BOXTRON_SCREEN	number	Set to the number of the screen, that you want the game to use.
BOXTRON_SIERRA_GAME	number	Set to the number of the game in Sierra Launcher, that you want to start. Check SierraLauncher.ini file in the game's installation dir to learn which number corresponds to which game. Defaults to 1.