LouveSystems' TrackMasters Modding Wiki

2. The virtual file system

Table of contents

โ”Œ>Data
โ”œ>Mounting
โ””>Example
โ”œ>Modding state (LEVEL)
โ””>Custom content

Data

All the data loaded by TrackMasters can be divided in two categories:

  • Hard data, usually compiled in scrambled or obfuscated archives and that cannot be modified or should not be tampered with
  • Soft data, which is clear data stored in common formats, and that can be modified by mounting ModPacks in the** Virtual File System**.
Hard data Soft data
Game code (C#) AI Code (Lua)
Existing textures Sound registers (XML)
Existing models Sound banks
Existing track elements Additional track elements
Existing vehicles Additional vehicles
Hosts configuration file (XML)
Localization files (YML)

The Soft data of TrackMasters can be more closely inspected by taking a look at the SOFTDATA folder, in the game's root directory. The game's root directory location depends on your installation, but you will usually find it in C:\Program Files(x86)\Steam\steamapps\common\LS_TrackMasters\.

The Soft data directory contains data that you can override with a mod to change the game's behaviour. However, you can also add files to your modpack that aren't present in the Soft data directory to add entirely new content to the game.

⚠️ Warning

You can copy the soft data from TrackMasters to your Work Directory for further inspection and/or modification. It is on the other hand strongly advised against modifying the softdata from the base game directly.
Modifying the soft data from TrackMasters directly without using modpacks will lead to compatibility issues, gameplay issues, and is likely to corrupt your new tracks.
All game modification should be done via the use of Modpacks, and never by modifying the game files directly

Mounting

When loading game data, TrackMasters does not use absolute disk paths (like C:/Program Files/TrackMasters...) but rather uses virtual paths (SOUND/BANK/bgm_frontend.ogg for example).
A virtual path is the path to a resource inside the Soft data folder, considering the Soft data directory as the root of the path.

If the game wants to load the file situated in <Soft data folder>/SOUND/BANK/bgm_frontend.ogg, it queries the virtual path (SOUND/BANK/bgm_frontend.ogg) and then a script inside TrackMasters is tasked with converting that path to an actual, physical disk path (C:\Program Files\...\LS_TrackMaster\SOFTDATA\SOUND\REGISTERS).

To have a physical file or folder used by the game, it must be assigned a virtual path by the game - this processed is called Mounting.
The contents of the soft data directory are mounted at the start of the game, which means that every file under the soft data folder can be accessed by the game with virtual paths.
Once the soft data mounted, the game then mounts every modpack in order (alphabetical filename order).

As a virtual path can only correspond to one physical file on disk, if a modpack contains a file that would be located at the same virtual path than a previously loaded file, the previous file is overriden with this one. When resolving a virtual path to a physical path, the game will only account for the last loaded asset with the corresponding virtual path.

Example

  • No mods are loaded. The soft data directory is mounted at the start of the game.
  • The game wants to access the sound for the main menu. This sound is located at the virtual path SOUND/BANK/bgm_frontend.ogg
  • The game resolves SOUND/BANK/bgm_frontend.ogg to the file located at the same path under the soft data directory
  • The game therefore opens the file C:\Program Files\...\LS_TrackMaster\SOFTDATA\SOUND\BANK\bgm_frontend.ogg for reading and plays the music.

Now let's say you have a modpack which is supposed to replace that file. Your modpack contains a different music, named bgm_frontend.ogg aswell, and located in SOUND\BANK inside your PAK.

  • The soft data directory is mounted at the start of the game.
  • Your modpack is mounted right after, and overwrites the path that SOUND/BANK/bgm_frontend.ogg was pointing to (C:/Program Files/...)) with its own (<Mods directory>/My Mod.pak/SOUND/BANK/bgm_frontend.ogg).
  • The game resolves SOUND/BANK/bgm_frontend.ogg to the last file loaded with that path, which is the one inside your mod
  • The game therefore opens the file C:/Users/.../Documents/My games/TrackMasters/Mods/My mod.pak/SOUND/BANK/bgm_frontend.ogg for reading and plays the music

Modding state (LEVEL)

The game keeps an internal "modding state" internally named the LEVEL, which is used to determine what kind of games you can join or host. With it, the game knows if you can join someone with different (or none) modpacks as you, for example.

Depending on what data you add to the virtual file system, the game will alter its LEVEL to then allow or disallow certain network functionalities.
Four levels exist:

LEVEL Description
VANILLA (0) The player can play with anyone who has the VANILLA or AUTONOMY level
AUTONOMY (1) Same as vanilla. The game detected that modpacks are loaded, but they do not affect gameplay.
ADDITIONAL_CONTENT (2) Modpacks with additional content are mounted. The player can only join VANILLA/AUTONOMY games, or ADDITIONAL_CONTENT games that have at least the same additional content that the player has. They can host games that only other ADDITIONAL_CONTENT-level players can join, and only if they have at least the same additional content as the host.
ALTERED_CONTENT (3) The player can only play with other ALTERED_CONTENT-level players that have exactly the same modpacks loaded.

Custom content

Even though you can add all kind of data to your modpack, it's not because it's present in the modpack that it will be used by the game.
Here is a short summary of the virtual paths in used by the game, by default, and how adding them to your modpack will elevate your modding state.

Virtual path Level Description
AI/<The first file found>.LUA AUTONOMY The first .LUA file found in this folder will be read and used to play the AI-controlled cars in the game (CPU opponents). More at Create AIs
LOCALZTN/<Any folder> AUTONOMY Each folder found in LOCALZTN will be loaded as a valid, selectable language ingame. More at Create localizations
LOCALZTN/SOUND/REGISTERS/<Any file>.XML AUTONOMY Each file found in this folder will be read as a soundbank register and interpreted further to load sounds. More at Add or change sounds
LOCALZTN/SOUND/BANK/... AUTONOMY This folder is used by the default soundbank register to read sounds from, but has nothing special to it. You can point the soundbank register to point at anything else.
HOSTS.XML AUTONOMY This XML file contains information about which network addresses to connect to fetch the list of games (BROADCAST), the tracks (API) or to connect to other players via relay (RELAY)
KEYS.XML AUTONOMY This XML file contains public cryptographic keys used to communicate securely with the server
TRACKPCS ADDITIONAL_CONTENT Track parts added to this folder will be loaded by the game automatically, and added to the track editor's catalog. More at Create track elements
VEHICLES ALTERED_CONTENT Vehicles added to this folder will be loaded by the game automatically, and added to the car selection menu. More at Create track elements

Continue to 3. Packing...