Welcome to the definitive Metruvia Content Creator Zero Rejection Guide to the structural integrity of Transport Fever 2 modifications. As we navigate the modding landscape in 2026, the barrier to entry has shifted. It is no longer enough to simply make a cool train. With the integration of Mod.io as the primary bridge to PlayStation 5 and Xbox Series X|S, your technical foundation must be surgical.
In this supporting article, we are moving beyond the “what” and “why” of the Pillar Hub and into the absolute “how.” We will dissect the Transport Fever 2 Virtual File System (VFS), master the mathematics of coordinate matrices, and enforce the “Lowercase Law” with religious fervor. If you follow this guide, your mod will not only pass Mod.io certification on the first attempt but will also be optimized enough to run on a toaster (or, more importantly, a base-model console).
1. The Virtual File System (VFS) and the Staging Area
To understand structure, you must understand how the game “sees” your files. Transport Fever 2 uses a Virtual File System. When the game initializes, it creates a digital map of all available assets. It looks at the vanilla game files first, then it “overlays” your mod’s files on top.
If your mod has a file path that perfectly matches a vanilla file (e.g., res/audio/effects/ui/click.wav), the game will prioritize your file over the original. This is the mechanism for “Replacement Mods.” However, for 99% of creators, the goal is to add content without breaking the base game. This requires a unique and isolated folder structure.
1.1 Locating the Staging Area
Your development work must happen in the Staging Area. Do not develop in the mods folder where you download Steam Workshop content.
Windows Path: C:\Program Files (x86)\Steam\userdata\[YourSteamID]\1066780\local\staging_area\
Mac Path: ~/Library/Application Support/Steam/userdata/[YourSteamID]/1066780/local/staging_area/
1.2 The Root Folder Naming Convention
Every mod folder within the staging area must follow a specific identity syntax. If you deviate from this, the game’s internal publisher will fail to link your local files to the Mod.io API.
The Mandatory Syntax: [author-handle]_[mod-name]_[version-integer]
The Author Handle: Your Mod.io username (e.g., transit_pro).
The Mod Name: A short, alphanumeric identifier (e.g., electric_tram).
The Version Integer: This must be an underscore followed by a number (usually _1).
Correct: transit_pro_electric_tram_1
Incorrect: Transit Pro's Electric Tram (v1.2) (Spaces and special characters will break the console file-pathing string).
2. The Lowercase Law: Why Your Mod Crashes on PS5
If there is a “Golden Rule” of Transport Fever 2 modding, it is this: Everything must be lowercase.
Windows is a “case-insensitive” operating system. If you write a script that looks for My_Texture.dds but the file is named my_texture.dds, Windows will say “close enough” and load it. Consoles and macOS are case-sensitive. To a PlayStation 5, those are two different files.
If you have a single capital letter in a file name or a folder path, the console will return a “File Not Found” error, resulting in:
The Purple Box of Doom: The model loads, but the texture is a glowing neon purple.
The Invisible Asset: The code runs, but the mesh cannot be found.
The Crash to Dashboard: A critical script or material file fails to load, and the game closes instantly.
Actionable Tip: Before uploading to Mod.io, use a “Bulk Rename” tool to force every folder and file in your mod directory to lowercase. No exceptions.
3. Anatomy of the res/ Directory
Every mod is contained within a folder named res (short for Resources). The game expects a very specific hierarchy inside this folder. If you place a texture in the root of res, the game will never find it.
3.1 res/audio/
This is where your custom sound sets live.
Standard: Use .wav files.
Hygiene: Sound files are memory-intensive. For Mod.io approval, ensure your audio is mono (not stereo) and 44,100Hz or 48,000Hz. Stereo files for localized sounds (like a train horn) waste 50% of the memory for no audible benefit in a 3D space.
3.2 res/config/
Used for global game logic. This includes:
base_config.lua overrides (highly dangerous for console stability).
Street and track definitions.
Bridge and tunnel types.
3.3 res/models/
The “Brain” of your mod. This folder is subdivided into:
material/: Contains .mtl files. These are text files that tell the game which textures to apply to a mesh and how reflective/transparent they should be.
mesh/: Contains .msh files and .msh.blob files. These are the 3D shapes.
model/: Contains .mdl files. This is the “Master Blueprint” that links meshes, materials, and game logic (speed, weight, year of availability) together.
3.4 res/textures/
This is where your .dds images are stored. We will cover the technical specs for these in Section 5.
4. The Geometry Pipeline: MDL, MSH, and MTL
To build a vehicle, you aren’t just making one file; you are building a chain of dependencies. Understanding this chain is vital for debugging.
The .mdl (The Manager): It doesn’t have “shape.” It has a list of coordinates. It tells the game: “Place Mesh A at coordinate X,Y,Z and use Material B on it.”
The .msh (The Skeleton): This is the raw geometry exported from your 3D software (Blender).
The .mtl (The Skin): This file contains the shader settings. It points to your textures and defines “Physical Based Rendering” (PBR) values.
4.1 The Coordinate Matrix
In the .mdl file, you will see 4×4 transformation matrices. They look like this:
100x010y001z0001
The first three rows handle rotation and scale, while the bottom-left three values (x,y,z) handle the position. If your wheels are floating 2 meters above the track, you need to adjust the z value in this matrix.
5. Texture Engineering for Consoles (DDS & Mipmaps)
This is the most common point of failure for Mod.io submissions. If you upload a .png or .tga file, your mod will be rejected. Consoles require DDS (DirectDraw Surface) textures.
5.1 Why DDS?
Unlike a PNG, which must be “unpacked” by the CPU, a DDS file is pre-compressed in a format the GPU can read directly. This saves massive amounts of processing power.
5.2 Mipmaps: The Non-Negotiable Requirement
When a train is 2 kilometers away, the game shouldn’t be trying to render a 4K texture. Mipmaps are smaller versions of your texture bundled into the same file.
LOD 0: 2048×2048 (Close up)
LOD 1: 1024×1024 (Medium distance)
LOD 2: 512×512 (Far away)
If your textures do not have mipmaps, they will “shimmer” and “flicker” on a console screen, leading to an immediate rejection.
5.3 Compression Formats
Albedo (Color): Use BC1 (DXT1) for no transparency, or BC3 (DXT5) if you have an alpha channel (transparency).
Metal/Gloss/AO (MGA): Use BC1.
Normal Maps: Use BC5. This preserves the “depth” of your model without the file size of an uncompressed image.
6. The mod.lua File: Your Identity Card
The mod.lua is the only file that sits outside the res folder in your root directory. It is the “Metadata” file.
6.1 Critical Parameters for Mod.io
function data()
return {
info = {
minorVersion = 0,
severityAdd = “NONE”,
severityRemove = “WARNING”,
name = (“My Mod Name”), description = (“A detailed description for Mod.io users.”),
tags = { “vehicle”, “train”, “freight” },
authors = {
{
name = “YourName”,
role = “CREATOR”,
}
}
},
}
end
severityAdd: Set to "NONE" for most mods.
severityRemove: This is critical. If your mod adds a vehicle, set this to "WARNING". If your mod adds a script that permanently alters the economy, set it to "CRITICAL". This tells the game whether a player can safely remove the mod from a save file.
7. Hygiene: Taking Out the Digital Trash
Before you hit Publish, you must clean your room. Mod.io has a strict 200MB limit for console mods. You cannot afford to waste space on “ghost” files.
7.1 Files to Delete
.DS_Store: Hidden files created by Macs. Delete them.
.bak / ~: Backup files created by text editors.
Source Assets: Delete your .blend files, .psd files, and raw .fbx exports. The game only needs the res folder.
The .tga Cache: Some exporters leave raw TGA files in the texture folder after converting to DDS. Remove them.
7.2 The “Blob” Limit
When you export a mesh, the game creates a .msh.blob file. For your lowest Level of Detail (LOD), this blob file must be under 1MB. If it’s larger, it means your “far away” model is too complex for the console’s memory to handle in bulk.
8. Summary Checklist for Technical Approval
Case Check: Is every single file and folder name in lowercase?
Version Check: Does the root folder end in _1?
Texture Check: Are all textures DDS format with mipmaps?
Encoding Check: Is your mod.lua and all .mdl files saved in UTF-8 (without BOM) encoding?
Size Check: Is the total uncompressed size under 200MB?
By adhering to this rigid structural hygiene, you are respecting the platform and the players. A clean mod is a stable mod, and a stable mod is one that stays on the Mod.io Featured list for years.