TDF - Manual

TDF is a small project aiming to make it easy to install, package and safely run Windows games on GNU/Linux. You can think of it as a portable (as in requiring no installation) version of Proton, based on most of the same technology, with better sandboxing.

TDF is based on the following awesome projects:

Wine, for Windows emulation, more specifically it includes two custom builds made with wine-tkg, one best suited for modern games, and one more suited for applications and older games
DXVK, for DirectX 8/9/10/11 emulation, and dxvk-nvapi for nvapi support on nVidia GPUs
VKD3D-Proton, for DirectX 12 emulation, built from source
D7VK, for DirectX 3-7 emulation, as an alternative to WineD3D
xdotool, a useful tool to handle games with problematic window/fullscreen behaviors
Zenity, a tool to display simple graphical interfaces such as loading bars, error messages, etc.
libstrangle, used to limit FPS in games that don't support it and don't use DXVK/VKD3D
Reaper, used to detect "stray" processes
bubblewrap, used to create a secure sandbox using Linux namespaces
...and a handful of other useful things

TDF's main goals are:

Being able to easily install and run games that you can't or don't want to play through Steam: things like GOG installers, ISOs, repacks, etc.
Strong sandboxing: give games only what they absolutely need to work and nothing more. By default, TDF doesn't let games access files on your computer and blocks all network traffic
Being as lightweight and portable as possible: virtually any modern GNU/Linux distro with a GUI can run a game packaged with TDF out of the box
Being able to easily update TDF instances as well as testing different versions of the main components, making it possible to help their respective developers
Being able to easily package and transfer a TDF instance to another computer or redistribute it (legally)
Focus on modern games, but a lot of older titles will work as well with some tinkering
Targeted at advanced users who want something safer than Lutris or Bottles

Usage

This section explains how to use TDF to install, play and optionally package a game.

Requirements

A relatively recent PC that's fast enough to run modern games. An x86_64 CPU is required, as well as a GPU with support for Vulkan 1.3 or newer
An AMD graphics card with the latest Mesa driver or newer is recommended, but it will also work on nVidia and Intel cards
Linux kernel 6.14 or newer is strongly recommended, but it will work on older versions. For best compatibility, use the latest kernel.
A modern-ish distro with basic stuff like the GNU coreutils, glibc, systemd, Wayland or X11, etc. installed. Arch-based distros will work best
An SSD is strongly recommended, with a file system like ext4 or btrfs. Do not use NTFS, FAT or exFAT
You must be able to use a Linux system, do file and folder management, know how to install games manually, know some basic shell scripting, etc.

Basic usage

Download the latest build of TDF (or build it yourself)
Extract the archive somewhere, optionally renaming the folder from template-YYYYMMDD to something more descriptive. We'll call this folder a TDF instance, you can have as many instances as you want
- Inside this folder, you'll see 4 things:
  - run.sh: the script that starts all the TDF magic
  - vars.conf: the main configuration file for this instance, you use this to tell TDF where to find the game and to change emulation settings
  - system: a folder containing all the TDF files and scripts, leave it alone for now
  - confs: a folder for additional configuration files, so you can install multiple games in the same instance (we'll talk about it later)
Launch run.sh, it will automatically initialize everything for you and open a Windows command prompt
- Once everything is ready, the TDF instance folder will contain a new folder called data, inside it you'll find a folder called wineprefix, this is your "fake Windows". Inside wineprefix, you'll find among other things a folder called drive_c, this is the fake C drive, you can enter it to copy game files, mods, etc. at any time
- Depending on the system and the configuration, other folders may also be created inside data, like home
- If you're not familiar with the Windows command prompt, just type explorer and press enter to have a more familiar file manager interface. For convenience during installation, TDF will show you a read-only H drive that contains the files on your computer (this can be turned off later)
Use the command prompt or explorer to install the game like you would on Windows but don't launch it yet
- During the installation, you won't need to install things like DirectX, the Visual C++ Redistributables, etc. because TDF has already done it during the initialization
- If you need to copy or modify some files inside the fake C drive, do it through the Linux file manager, it's easier
- Once you're done, close the command prompt
Edit vars.conf and place the location of the game's exe file in the game_exe variable. The path must be Windows-style, like C:\Doom\doom.exe. It is also recommended to set the SteamGameId variable, as it will automatically enable fixes for some known problematic games (you can find the IDs here: https://steamdb.info/)
Launch run.sh again and hopefully the game will start
- From now on, you can just launch run.sh (or create links to it) to launch this game.
- About 90% of games will work out of the box, some will require some tinkering, usually in the form of changing some variables in vars.conf, which we'll discuss later
- Online games that require anticheat software will usually not work (and that's probably for the best)

Configuration variables

The following lists contain all the variables that can be added in vars.conf to configure emulation settings, work around issues, improve performance, etc.

Essential variables (where the game is installed)

game_exe
Specifies the Windows-style path to the game's exe file. If empty, the command prompt will be launched instead.

Example: game_exe='C:\GTAV\PlayGTAV.exe'

game_workingDir
The working directory of the game. By default this is set to the same folder where the game_exe resides. All paths must be Windows-style.

Example:

game_exe='bin\indy.exe'
game_workingDir='C:\Indy'

game_args
Arguments to be passed to the game.

Accepts a string or a bash array.

Examples: ('-iwad' 'doom2.wad') or '-iwad doom2.wad'

SteamGameId
Optional numeric Steam App ID for the game. Identifies a specific game on Steam, enabling game-specific workarounds in the wine-games build (e.g., known configuration tweaks, known fixes). This does NOT require Steam to be installed; it's purely a lookup key for internal game-specific optimizations.

Look up IDs here: https://steamdb.info/

Example: export SteamGameId="1174180"

Sandboxing / Isolation

TDF uses bubblewrap to create a secure sandbox using Linux namespaces. This provides very strong isolation giving games only the bare minimum that they need to work: access to the display, sound, input devices, and the GPU; a potential malware running inside the sandbox won't be able to touch your files, interact with other processes on your computer (or even see them), use the network, use dbus, etc. unless you explicitly allow it.

TDF_ALLOW_HOST_FILESYSTEM
Controls which host filesystem paths are exposed inside the sandbox.

Possible values:

0: Do not expose the real filesystem at all (most secure)
1: Expose the real filesystem as a read-only H: drive
2: Expose the real filesystem as a read-only H: drive only when running command prompt (game_exe is empty). This makes it easy to install games, but gives games no access to the files on your computer when you actually run them
3: Expose the real filesystem as a read-write H: drive

TDF_CUSTOM_MOUNTS
Additional custom mounts in the format "letter:access:hostPath" or "letter".

letter: single letter A-Z (except for C, which is reserved)
access: "ro" for read-only, "rw" for read-write
hostPath: absolute path on the host filesystem (~ is not allowed)
If access and hostPath are omitted, a directory named data/<letter> is created inside the TDF data folder and mounted read-write. This is useful for things like arcade games that save on a USB drive.

Example: TDF_CUSTOM_MOUNTS=("D:ro:$HOME/Desktop" "E:rw:/media/games" "F")

TDF_BLOCK_NETWORK
Network access blocking method.

Possible values:

0: Don't block network
1 (default): Block with bwrap --unshare-net
2: Block with unshare -nc (old method)

Note that unblocking networking will also allow the sandboxed app to communicate with some services on your computer that use sockets (like CUPS).

TDF_BLOCK_BROWSER
Block Wine from launching the system's native web browser.

Possible values:

1 (default): applications running in Wine won't be able to launch a browser
0: Allow Wine to launch browsers (RUNS OUTSIDE THE SANDBOX!)

TDF_BLOCK_SHM
Block access to /dev/shm (shared memory).

Possible values:

1 (default): Block /dev/shm access (recommended, stronger sandboxing)
0: Don't block (weaker sandboxing, but some apps may need it)

Note: Setting TDF_WINE_SYNC="fsync" requires TDF_BLOCK_SHM=0. Keep in mind that fsync is an obsolete Wine feature and not blocking shared memory is a security concern.

TDF_BLOCK_NATIVE_INPUT
Block direct access to native input devices (/dev/input) for better security.

Possible values:

0 (default): Allow access (default)
1: Block direct access to keyboard, mouse, gamepad, etc. (can break gamepad support)

Note: regardless of this setting, unless udev is misconfigured on your system, this won't allow games to log keypresses to other applications.

Wine

TDF_WINE_PREFERRED_VERSION
TDF comes with 2 different versions of Wine and can also use the one on your system (if installed). This variable lets you choose which one you prefer.

Possible values:

games (default): use the game-optimized build. This version is based on Valve's version of Wine (bleeding-edge branch), with additional patches applied
mainline: use a mostly regular version of Wine, useful for applications and old games that don't work with the game-optimized build
system: use the version of Wine that's installed in the system, if it's not installed mainline will be used instead
custom: use the version of Wine that you can put in a folder called wine-custom outside the system folder (next to run.sh). This is useful to keep TDF updates easy for the occasional game that requires a custom build of Wine
any other value: tries to use ./wine-<value> folder (where <value> is the value you set), falls back to system Wine if not found

TDF_WINE_ARCH
The architecture of the Wine installation. Can only be set before the initialization is performed, and can't be changed afterwards without deleting the wineprefix.

Possible values:

win64 (default): create a 64-bit Windows installation
wow64 (or win32): create a 32-on-64 prefix (useful for some old games)

TDF_WINEMONO
Whether to install Wine Mono in the prefix or not. Mostly useful for launchers and applications based on .NET, games don't usually need this.

Possible values:

0 (default): don't install Wine Mono
1: install Wine Mono

TDF_WINEGECKO
Whether to install Wine Gecko in the prefix or not. This provides the equivalent of a Webview, mostly useful for launchers and applications based on IE, games don't usually need this.

Possible values:

0 (default): don't install Wine Gecko
1: install Wine Gecko

TDF_VCREDIST
Whether to install the official Microsoft Visual C++ Redistributables (2015+) or not. This is useful for modern games but unnecessary for older ones.

Possible values:

1 (default): install the official MSVC redistributables
0: use Wine's built-in implementations

export WINEDLLOVERRIDES
Some game fixes and mods come in the form of DLLs that override one of Windows' DLL, usually winmm, dinput8, version, d3d9, etc.
Unlike Windows, which happily loads random DLLs from the game's folder, by default Wine prefers to use its own DLLs and overrides need to be specified manually.

This is not a TDF variable, but it's part of Wine. More about this here.

Example:

#load winmm.dll and dinput8 from the game's folder (if available)
export WINEDLLOVERRIDES="winmm,dinput8=n,b"

This can also be used to fix games that complain about outdated drivers on AMD cards or that don't detect the correct amount of VRAM, since they often obtain this information through a DLL called amd_ags_x64.dll:

Example:

#use wine's own fake amd_ags_x64 instead of the game's version
export WINEDLLOVERRIDES="amd_ags_x64=b"

Multiple overrides can be separated by a semicolon ;.

export WINE_PREFER_NATIVE_DLL
Sets the default DLL load order for DLLs that are not being overridden with WINEDLLOVERRIDES or registry entries.

By default, Wine uses the b,n load order for DLLs unless overridden, which may cause issues with some games and mods that override DLLs like winmm, dinput8, version, etc.; if this setting is enabled, it will change the default to n,b, meaning that Wine will try to load DLLs provided by the game first and only use its own as a fallback.

This improves compatibility with mods and cracks, but can cause issues such as outdated driver warnings or straight up crashes, so it is disabled by default.

Possible values:

0 (default): use b,n load order for DLLs that are not overridden (Wine default)
1: use n,b load order for DLLs that are not overridden

Notes:

WINEDLLOVERRIDES will still be applied, this setting only applies if a DLL is NOT overridden
This setting is only supported by the game-optimized build

export WINEDEBUG
Enables/disables some Wine debug channels.

By default, TDF sets this to -all to improve performance, but you might want to enable one or more of these for troubleshooting.

Don't add +relay to this variable, as it's controlled by the TDF_WINE_DEBUG_RELAY variable.

Example:

#log loaded DLLs to the terminal and show the pid of the process that generated each message
export WINEDEBUG=+loaddll,+pid

export DRI_PRIME
Sometimes on systems with multiple GPUs, a game might start using the wrong GPU, such as the integrated graphics on your laptop instead of the dedicated card.

By setting a value for DRI_PRIME you can tell the game which graphics card to use.

Example:

#use the second GPU
export DRI_PRIME=1

This is not a TDF variable and you can find more about it here.

TDF_WINE_HIDE_CRASHES
When a Wine application crashes, it normally shows a dialog similar to the "Stopped working" thing on Windows, but depending on the game and configuration, it may be impossible to interact with that window, leaving you stuck. By default, TDF disables this crash window, but it can be enabled for debugging and troubleshooting purposes.

Possible values:

1 (default): hide the crash window
0: show the crash window

TDF_WINE_AUDIO_DRIVER
Sets the preferred audio driver for Wine. This can be useful if you have crackling audio or if one of the drivers has a lower latency than the others. Default is usually fine.

Possible values:

pulse: use PulseAudio (you may also want to add export PULSE_LATENCY_MSEC=20 for lower latency in rhythm games or export PULSE_LATENCY_MSEC=120 if you have crackling/dropouts)
alsa: use ALSA
jack: use Jack
default (default): let Wine decide

Note: Choosing a driver that doesn't exist in Wine or is not installed in your system will result in no sound being played.

Note: Wine doesn't natively support PipeWire yet, it uses PulseAudio by default for compatibility if you're using PipeWire.

TDF_WINE_GRAPHICS_DRIVER
Sets the preferred graphics driver for Wine (as in how it outputs, not how it renders 3D graphics). This can be useful if you're messing around with Wayland and X11 and Wine doesn't work properly.

Possible values:

default (default): let Wine decide
x11: use X11, does not support HDR
wayland: use Wayland, supports HDR. Beware, it sucks.
auto: let TDF decide based on what you're using. If WAYLAND_DISPLAY is set, wayland will be used, otherwise if DISPLAY is set x11 will be used, otherwise default (let Wine decide)

Note: Choosing a driver that doesn't exist in Wine or in your system will result in no graphics being displayed.

Note: This setting is automatically forced to wayland when TDF_HDR is set to 1.

TDF_COREFONTS
Whether to install the Microsoft Corefonts or not. These are fonts like Arial, Comic Sans, etc. that are required by some games such as PC Building Simulator. This is generally harmless, but if some application has font rendering issues, try disabling it.

Possible values:

1 (default): install the Corefonts
0: don't install the Corefonts

TDF_WINE_WINVER
Sets the Windows version to emulate.

Possible values:

"" (empty string) (default): let Wine decide on prefix creation (at the moment it's win10). Can be changed through winecfg
Sensible values: win10, win11, win7, win8, win81, vista, winxp, winxp64
Other values: win2003, win2008, win2008r2, winme, win2k, win98, win95, nt40, nt351, win31, win30, win20

Note: If using an older Windows version, TDF_WINE_ARCH should also be set accordingly. It usually doesn't break anything, but applications may not expect to see 64-bit versions of legacy systems.

TDF_WINE_THEME
Sets the Wine theme.

Possible values:

"" (empty string) (default): let Wine decide on prefix creation (at the moment it's light). Can be changed through winecfg
classic: use the classic 9x style theme (can fix some old apps that have drawing issues with modern themes)
light: use the modern 11-ish style theme

Note: It's possible to install msstyles themes, in this case, leave this empty and install them through winecfg.

TDF_WINE_LANGUAGE
By default, TDF will pass the system language to Wine, which may be undesirable for some games and applications that just use the system language instead of showing a language selector. Here's a complete list of locales, obviously not all games will support them.

Example: TDF_WINE_LANGUAGE='it_IT.utf-8'

Limiting CPU cores (and setting CPU topology in general)

As CPUs get more and more cores and threads, problems such as crashes, inconsistent performance and general instability can occur in older games. For this reason, TDF implements several ways to limit which cores can be used.

Note: these settings apply to the game-optimized build only

Before we get into the settings, some terminology:

Logical CPU: A "core" as you see in task manager, also known as physical thread. For CPUs with HyperThreading/SMT, 2+ logical CPUs are present for each physical core. Some games work well with SMT, others hate it
Core: A physical core inside your CPU
Sockets (multi-CPU systems): refers to the number of CPU chips physically inside your system. For gaming PCs, this is usually 1, but if you're gaming on a harvested multi-CPU server, this is going to be 2+, and not all games react well to that

If a game doesn't support a high number of cores, TDF can limit the number of logical CPUs assigned to it and choose the best ones to maximize performance.

Note: These limits affect the performance of everything running inside Wine, including DXVK and VKD3D. Use them only if absolutely necessary.

Note: if WINE_CPU_TOPOLOGY is set, these settings will have no effect.

TDF_WINE_MAXLOGICALCPUS
The maximum number of logical CPUs that can be assigned to this game.

Possible values:

0 (default): unlimited
any other positive number: limit the number of logical CPUs to this value

If the number of logical CPUs exceeds this value, they are assigned intelligently in this way:

For CPUs with P-cores and E-cores, the first logical CPU of each P-core are assigned first, then E-cores, then the second logical CPU of each core, etc. until we either run out of logical CPUs to assign or the limit is reached
For CPUs with HyperThreading/SMT: the first logical CPU of each core is assigned first, then the second logical CPU of each core, etc. until we either run out of logical CPUs to assign or the limit is reached
For multi-CPU systems, see TDF_WINE_PREFER_SAMESOCKET below

Generally speaking, this is the only limit you should set. Let TDF do the rest for you.

Example 1: We're on an Intel Core i7 12900K (8 P-cores with 2 threads each, 8 E-cores with 1 thread each, 24 threads in total), the CPU topology is the following (obtained with lscpu --all --extended):

CPU NODE SOCKET CORE L1d:L1i:L2:L3 ONLINE    MAXMHZ   MINMHZ
  0    0      0    0 0:0:0:0          yes 6700.0000 800.0000
  1    0      0    0 0:0:0:0          yes 6700.0000 800.0000
  2    0      0    1 1:1:1:0          yes 6700.0000 800.0000
  3    0      0    1 1:1:1:0          yes 6700.0000 800.0000
  4    0      0    2 2:2:2:0          yes 6500.0000 800.0000
  5    0      0    2 2:2:2:0          yes 6500.0000 800.0000
  6    0      0    3 3:3:3:0          yes 6500.0000 800.0000
  7    0      0    3 3:3:3:0          yes 6500.0000 800.0000
  8    0      0    4 4:4:4:0          yes 6500.0000 800.0000
  9    0      0    4 4:4:4:0          yes 6500.0000 800.0000
 10    0      0    5 5:5:5:0          yes 6500.0000 800.0000
 11    0      0    5 5:5:5:0          yes 6500.0000 800.0000
 12    0      0    6 6:6:6:0          yes 6500.0000 800.0000
 13    0      0    6 6:6:6:0          yes 6500.0000 800.0000
 14    0      0    7 7:7:7:0          yes 6500.0000 800.0000
 15    0      0    7 7:7:7:0          yes 6500.0000 800.0000
 16    0      0    8 8:8:8:0          yes 3900.0000 800.0000
 17    0      0    9 9:9:8:0          yes 3900.0000 800.0000
 18    0      0   10 10:10:8:0        yes 3900.0000 800.0000
 19    0      0   11 11:11:8:0        yes 3900.0000 800.0000
 20    0      0   12 12:12:9:0        yes 3900.0000 800.0000
 21    0      0   13 13:13:9:0        yes 3900.0000 800.0000
 22    0      0   14 14:14:9:0        yes 3900.0000 800.0000
 23    0      0   15 15:15:9:0        yes 3900.0000 800.0000

If you want to play Colin McRae Dirt (2007), a game that supports 4 cores at most, you'll have to set TDF_WINE_MAXLOGICALCPUS=4, and with this CPU TDF will select logical CPUs 0,2,4,6, because they are the fastest cores available, one thread per core.

If you want to play Lara Croft and the Guardian of Light (2010), a game that supports 12 cores at most, you'll have to set TDF_WINE_MAXLOGICALCPUS=12, and with this CPU TDF will select logical CPUs 0,2,4,6,8,10,12,14,16,17,18,19. The first 8 are the P-cores, one thread per core, the last 4 are E-cores, one thread per core.

If you want to play The Witcher 2 (2010), a game that supports 31 cores at most, you'll have to set TDF_WINE_MAXLOGICALCPUS=31, and with this CPU TDF will not apply any special restriction because it only has 24 logical CPUs.

Example 2: We're on an AMD Ryzen 7 5800X (8 cores with 2 threads each, 16 threads in total), the CPU topology is the following:

CPU NODE SOCKET CORE L1d:L1i:L2:L3 ONLINE    MAXMHZ    MINMHZ
  0    0      0    0 0:0:0:0          yes 4850.1948 2200.0000
  1    0      0    1 1:1:1:0          yes 4850.1948 2200.0000
  2    0      0    2 2:2:2:0          yes 4850.1948 2200.0000
  3    0      0    3 3:3:3:0          yes 4850.1948 2200.0000
  4    0      0    4 4:4:4:0          yes 4850.1948 2200.0000
  5    0      0    5 5:5:5:0          yes 4850.1948 2200.0000
  6    0      0    6 6:6:6:0          yes 4850.1948 2200.0000
  7    0      0    7 7:7:7:0          yes 4850.1948 2200.0000
  8    0      0    0 0:0:0:0          yes 4850.1948 2200.0000
  9    0      0    1 1:1:1:0          yes 4850.1948 2200.0000
 10    0      0    2 2:2:2:0          yes 4850.1948 2200.0000
 11    0      0    3 3:3:3:0          yes 4850.1948 2200.0000
 12    0      0    4 4:4:4:0          yes 4850.1948 2200.0000
 13    0      0    5 5:5:5:0          yes 4850.1948 2200.0000
 14    0      0    6 6:6:6:0          yes 4850.1948 2200.0000
 15    0      0    7 7:7:7:0          yes 4850.1948 2200.0000

(Notice the different interleaving in the CORE column compared to the previous example).

If you want to play Colin McRae Dirt (2007), a game that supports 4 cores at most, you'll have to set TDF_WINE_MAXLOGICALCPUS=4, and with this CPU TDF will select logical CPUs 0,1,2,3, which are simply the first 4 logical CPUs, one per core.

If you want to play Lara Croft and the Guardian of Light (2010), a game that supports 12 cores at most, you'll have to set TDF_WINE_MAXLOGICALCPUS=12, and with this CPU TDF will select logical CPUs 0,1,2,3,4,5,6,7,8,9,10,11. The first 8 are the first logical CPU of each core, one thread per core, the last 4 are the second logical CPU of the first 4 cores.

If you want to play The Witcher 2 (2010), a game that supports 31 cores at most, you'll have to set TDF_WINE_MAXLOGICALCPUS=31, and with this CPU TDF will not apply any special restriction because it only has 16 logical CPUs.

TDF_WINE_NOSMT
Whether to hide the additional logical CPUs on CPUs that support HyperThreading/SMT.

Possible values:

0 (default): use SMT
1: do not use SMT. If this is set, only the first logical CPU of each core will be used, the others will be ignored. This can improve the performance of some older games.

TDF_WINE_NOECORES
Whether to hide E-cores on CPUs like Intel Alder Lake.

Possible values:

0 (default): use E-cores
1: do not use E-cores

Note: for compatibility reasons, these CPUs have no easy way to tell which cores are P-cores and which ones are E-cores, so TDF "guesses" that the E-cores are the ones with a maximum clock that's <75% of that of any other core. This may be improved in the future.

TDF_WINE_PREFER_SAMESOCKET
How to use multiple CPUs.

Possible values:

0 (default): let Wine decide
1: assign logical CPUs based on speed, but prioritize cores on the same physical CPU (first assign all the logical CPUs in the first socket, then the second, etc.). This is generally the best for games.
2: only show the first CPU/NUMA socket to the application. Useful for multi-CPU servers.

export WINE_CPU_TOPOLOGY
This is not a TDF variable, but it allows you to set Wine to use specific CPU cores, similar to the /AFFINITY option of the start command in Windows, but more fine grained. This should be used as a last resort or if you want to do dumb things like restrict a game to only use E-cores.

Example:

#limits wine to one CPU core
export WINE_CPU_TOPOLOGY="1:0"

Example:

#limits wine to use the first 4 CPU cores
export WINE_CPU_TOPOLOGY="4:0,1,2,3"

Note: if WINE_CPU_TOPOLOGY is set, the settings above will have no effect.

TDF_WINE_DPI
DPI value for display scaling of Wine applications.

Possible values:

0 (default): let Wine handle scaling
-1: use DPI from the main display (auto-detected via xrdb)
number: use this DPI value (96=100% scaling, 120=125% scaling, 144=150% scaling, etc.). 96 DPI will fix some older games

TDF_WINE_SYNC
The synchronization method to be used by Wine (game-optimized build only).

Possible values:

"" (empty string) (default): let Wine decide (ntsync if available, falls back to fsync/esync)
fsync: force futex-based fsync (not recommended)
esync: force Wine esync (not recommended)

Note: Using fsync requires TDF_BLOCK_SHM=0, which reduces sandbox security.

TDF_WINE_LAA
Enable Large Address Aware (LAA) support for 32-bit applications. Allows 32-bit games to address more than 2GB of memory.

Possible values:

1 (default): Enable LAA
0: Disable

TDF_WINE_HEAP_DELAY_FREE
Enable heap delay-free optimization. Delays freeing heap memory for better compatibility with games with use-after-free bugs and reduces overhead from system calls.

Possible values:

1 (default): Enable
0: Disable

TDF_WINE_SMOKETEST
Whether or not to perform a "smoke test" to make sure that Wine actually works before trying to run the game, that way you can tell if a crash is a Wine problem or a game problem. TDF does this by default but you can disable it if it takes too long at the "Starting Wine" screen.

Possible values:

1 (default): do the "smoke test"
0: skip the "smoke test" for faster startup

TDF_WINE_DEBUG_RELAY
Enables the Wine relay feature, which traces all interaction between the application and the rest of the system to a file. Extremely slow but can be useful to debug weird issues and crashes.

Possible values:

0 (default): disabled
1: when the game is launched, TDF will ask where you want to save the trace, then launch the game with relay enabled

TDF_WINE_DEBUG_GSTREAMER
Enables gstreamer debug output (to the terminal). This can be used to debug issues like games not playing videos or crashing when a video is supposed to play.

Possible values:

0 (default): disabled
1: enable gstreamer debug output

Graphics

TDF_DXVK
Whether to install DXVK or not, which provides Direct3D 8/9/10/11 to Vulkan translation and DXGI implementation. If this is disabled, WineD3D will be used instead, which may be better for some older games. If VKD3D or D7VK is enabled, DXVK is auto-enabled as a dependency.

Settings for DXVK can be changed by downloading the default configuration file, placing it into the game's folder and editing it.

Possible values:

1 (default): use DXVK
0: use WineD3D

TDF_DXVK_NVAPI
Enable dxvk-nvapi (Nvidia API layer for DXVK). Provides NVAPI support and some performance optimizations on NVIDIA cards. Requires DXVK.

Possible values:

0 (default): don't use dxvk-nvapi
1: use dxvk-nvapi

TDF_VKD3D
Whether to install VKD3D-Proton, which provides Direct3D 12 to Vulkan translation. If this is disabled, Wine's version of VKD3D is used instead, which has very poor game compatibility compared to this version. Requires DXVK.

Possible values:

1 (default): use VKD3D-Proton
0: use Wine's VKD3D implementation

VKD3D's config can be changed by using its environment variables.

TDF_D7VK
Whether to install D7VK or not, which provides DirectX 3-7 to Vulkan translation. If this is disabled, WineD3D will be used instead. Requires DXVK.

Settings for D7VK can be changed by downloading the default configuration file, placing it into the game's folder and editing it.

Possible values:

0 (default): use WineD3D
1: use D7VK

TDF_HDR
Whether to expose HDR support to the application or not. HDR must be enabled in the system settings for this to work and an HDR compatible display is required. This setting has no effect if HDR is disabled or unsupported.

Possible values:

0 (default): don't expose HDR (this is the default because HDR kinda sucks in most games)
1: expose HDR if available

Note: HDR only works on Wayland, enabling this setting will force Wine to use Wayland, which may break some games.

TDF_GL_MAXFPS
Enables an FPS limiter for OpenGL applications, based on libstrangle.

Possible values:

0 (default): disabled, and don't load libstrangle
number: limit FPS to this number

export FSR4_UPGRADE
Enable AMD FSR4 on supported GPUs and games. This installs a proprietary AMD DLL into the sandbox.

Possible values:

0 (default): don't enable FSR4
1: enable FSR4

Desktop integration

TDF_DND
Enable Do Not Disturb mode while the game is running. Works on supported desktop environments (GNOME, KDE, etc.).

Possible values:

1 (default): Enable DND
0: Don't enable DND

TDF_NOSLEEP
Inhibit system sleep while the game is running. Works on supported desktop environments (GNOME, KDE, etc.).

Possible values:

1 (default): Inhibit sleep
0: Don't inhibit sleep

Overlays and other tools

TDF_MANGOHUD
Whether to launch the game with the MangoHud performance overlay or not. If MangoHud is not installed in the system, it has no effect. Note that some games will crash when launched with MangoHud.

Possible values:

0 (default): don't use MangoHud
1: use MangoHud

Note: If MangoHud is enabled alongside Gamescope, MangoHud is automatically disabled and Gamescope's built-in mangoapp is used instead.

TDF_GAMESCOPE
Whether to enable Gamescope when running the game or not. This is generally not recommended when using the game-optimized version of Wine, since it integrates the fshack patches which make it mostly useless, but it can be useful when using the mainline version for games that change the screen resolution often, require low resolutions, integers scaling, etc. such as KOTOR or WinQuake. If Gamescope is not installed in the system, it has no effect.

Possible values:

0 (default): don't use Gamescope
1: use Gamescope when running games if available

TDF_GAMESCOPE_PARAMETERS
The command line arguments used to start Gamescope. You can see a complete list here. Can be a string or a bash array.

By default, TDF sets this variable to -f -r 60 -w $XRES -h $YRES, where XRES and YRES are two read-only variables provided by TDF for convenience that contain the horizontal and vertical resolution of the main display. This default value emulates a virtual screen with the same resolution as the real display, with a refresh rate of 60hz and sets Gamescope to run in fullscreen without any special scaling.

TDF UI settings

TDF_TITLE
The title to show on the title bar of the TDF windows. By default it's set to "Launcher".

TDF_UI_LANGUAGE
The language to use for the TDF user interface. Does not affect Wine or games (see TDF_WINE_LANGUAGE for that).

By default, TDF tries to obtain the language from the OS. If a translation is not available, it will fall back to English.

Currently implemented languages:

en: English
it: Italian

TDF_HIDE_GAME_RUNNING_DIALOG
Whether to hide the TDF window that says "Game running". By default, TDF shows it so you can stop the game at any time.

Possible values:

0 (default): show the window
1: hide it

TDF_IGNORE_EXIST_CHECKS
By default, TDF checks whether the executable specified in game_exe actually exists before trying to launch it, but this is not always desirable and can be disabled, which can be useful to run certain commands.

Possible values:

0 (default): check that the executable actually exists and show an error if it doesn't
1: don't check and don't show an error if it doesn't exist

TDF_SHOW_PLAY_TIME
Show playtime after the game closes.

Possible values:

0 (default): don't show playtime
1: show playtime for the current session
2: show playtime for the current session and total played hours

Callbacks

You can optionally define the following functions inside vars.conf and they will be called at specific moments during operation. This can be useful to fix games that have issues with window positioning, focusing, etc. or that have some special requirements. The language is just bash.

NEVER CALL WINE FROM THESE SCRIPTS

If you need to define some variables, do it inside the callback functions, as the configuration is loaded more than once during the initialization process.

Note: callbacks run inside a subshell outside the sandbox; therefore they cannot:

Run wine commands (they would launch system wine outside the sandbox)
Change any of the settings in this file
They have full access to the host system, including file system and network (the sandbox is in $PWD/data)

customChecks
This function will be called immediately after the configuration is loaded. It's useful to run some custom checks specific to the game or to change some settings depending on hardware/software configuration. The function returns 0 if the checks succeed, 1 to indicate that they failed and stop TDF. If the function has no return, it will be treated as a success.

Example:

customChecks(){
    if [ "$XDG_SESSION_TYPE" == "x11" ]; then
        return 0
    else
        zenity --error --text="Sorry, this game requires X11"
        return 1
    fi
}

Note that this function is blocking and TDF won't continue the initialization until it has finished running.

onGameStart
This function will be called right before the game is launched.

Example:

onGameStart(){
    echo "Pre-launch: copying mods..."
    cp -r mods/* "data/wineprefix/drive_c/Game/"
}

Note that this function is blocking and the game won't be launched until it has finished running.

onGameEnd
This function will be called when the game's main process finishes running.

Example:

onGameEnd(){
    echo "Post-game: cleaning up temp files..."
    rm -rf "data/home/wine/.cache"
}

Note that this function is blocking and TDF won't close until it has finished running.

whileGameRunning
This function will be called while the game is actively running. It runs in a background subshell and is automatically killed when the game exits. It can run indefinitely or perform periodic tasks.

Example:

whileGameRunning(){
    while true; do
        echo "Game is running..."
        sleep 30
    done
}

Note that the game process may not have been created yet when this function is called, make sure to check the game's process using isProcessRunning

onArchiveStart
This function will be called right before the packaging process begins when using ./run.sh archive (mentioned later). It can be used to remove or move some unnecessary files like DXVK/VKD3D caches, saved games, etc. The function receives the same arguments passed to run.sh and can return 1 to prevent the packaging process from starting if something's wrong.

Example:

onArchiveStart(){
    TEMPDIR="/tmp/requiem$RANDOM"
    mkdir "$TEMPDIR"
    mv "data/wineprefix/drive_c/APTRequiem/vkd3d-proton.cache" "$TEMPDIR"
    mv "data/wineprefix/drive_c/users/wine/AppData/Local/GOG.com" "$TEMPDIR"
}

Note that this function is blocking and the packaging process won't start until it has finished running.

onArchiveEnd
This function will be called at the end of the packaging process when using ./run.sh archive (mentioned later). It can be used to restore files modified or deleted by onArchiveStart. This function receives 0 in input if the packaging process has succeeded, 1 otherwise.
Example:

onArchiveEnd(){
    mv "$TEMPDIR/vkd3d-proton.cache" "data/wineprefix/drive_c/APTRequiem/"
    mv "$TEMPDIR/GOG.com" "data/wineprefix/drive_c/users/wine/AppData/Local/"
    rm -rf "$TEMPDIR"
}

Note that this function is blocking and TDF won't close until it has finished running.

Builtin functions

For convenience, TDF comes with some functions that can be used inside the callback functions mentioned before, in addition to everything provided by bash such as sleep, grep, etc..

waitForWindow exe title [timeout]
Scans windows to find one that matches the specified exe and contains title in the name. If no matching window is found, it will keep trying for timeout seconds (30 if not specified). If exe is an empty string, it will match any process with the specified title, if title is an empty string, it will match any window from the specified process.

The window IDs will be copied to a WINDOWS array, with the first matching window easily accessible with a WINDOW variable.

The function returns 0 if a match was found, 1 if the timeout was reached.

Examples:

waitForWindow "APlagueTaleRequiem_x64.exe" "A Plague Tale: Requiem" 10: waits up to 10 seconds for the process "APlagueTaleRequiem_x64.exe" to spawn a window that contains "A Plague Tale: Requiem" in the title
waitForWindow "APlagueTaleRequiem_x64.exe": waits up to 30 seconds for the process "APlagueTaleRequiem_x64.exe" to spawn a window
waitForWindow "" "A Plague Tale: Requiem": waits up to 30 seconds for any process to spawn a window that contains "A Plague Tale: Requiem" in the title
waitForWindow "APlagueTaleRequiem_x64.exe" "" 10: waits up to 10 seconds for the process "APlagueTaleRequiem_x64.exe" to spawn a window