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.

TDF is based on the following awesome projects:

• Wine, for Windows emulation, more specifically it includes two custom builds made with 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 6-7 emulation, as an optional 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
• ...and a handful of other useful things

TDF's main goals are 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.
• Sandboxing: by default, network and file system access are blocked to games running inside a TDF instance (note that this will not protect against malware that specifically targets Wine or the Linux kernel)
• Being as lightweight and portable as possible: virtually any modern GNU/Linux distro with a GUI can run TDF instances out of the box
• Being able to easly 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

If you're happy with Lutris, you probably don't need TDF.

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
• Linux kernel 5.16 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 AMD graphics card with the Mesa 23.1 driver or newer is recommended, but it will also work on nVidia and Intel cards. For best compatibility, use the latest driver.
• 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, we'll use this in a moment
    • vars.conf: TDF's main configuration file for this instance, you'll 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: we'll talk about folder this 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 zzprefix, this is your "fake Windows", inside it 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, like zzhome and fontcache
  • If you're not familiar with the Windows command prompt, just type explorer and press enter to have a more familiar file manager interface, but don't close the command prompt until you're finished
• Use the command prompt to install the game like you would on Windows but without launching it
  • 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
• 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 85% 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)

Here's a video showing how to install a game from GOG that requires no additional configuration: Basic usage - Installing a game from GOG

You can find more video examples at the end of this document.

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

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

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

game_args
Arguments to be passed to the game.

Example: game_args='-iwad doom2.wad -file mymod.wad'

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'

TDF variables

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

TDF_DETAILED_PROGRESS
Whether to show the details of what's happening above the progress bar in the TDF window.

Possible values:

• 1 (default): show details like "Starting wine", "Registering DLLs", etc.
• 0: show a generic message like "Launching..." or "Creating a new wineprefix, this will take a while..."

TDF_MULTIPLE_INSTANCES
What to do if the user tries to launch run.sh while it's already running.

Possible values:

• deny: do nothing, just exit without an error message
• error: show an error message and exit
• askcmd (default): don't launch the game but ask the user if they want to launch a command prompt in the running instance
• cmd: same as askcmd but without asking first
• allow: allow multiple instances of the game to be running at the same time (generally a bad idea)
• kill: terminate previous instance and start a new one
• askkill : ask the user if they want to terminate the previous instance and start a new one or exit

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_HIDE_GAME_RUNNING_DIALOG
Whether to hide the TDF window that says "Game running". By default, TDF shows it so you can know if the process has stalled.

Possible values:

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

TDF_SHOW_PLAY_TIME
Whether to show a message when you close the game that tells you how long you've been playing.

Possible values:

• 0 (default): don't show it
• 1: show it

TDF_DND
Enables Do Not Disturb mode (on supported DEs) while the game is running.

Possible values:

• 1 (default): mute notifications while the game is running
• 0: don't mute them

Note: some games launch a separate process and terminate immediately. This setting won't work on these games.

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

Wine variables

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, with the GE and tkg patches and is very similar to Wine-GE-Proton. Some functionalities have been disabled: anticheat bridges (you can't convince me they're not malware), dbus (automounting of external drives),