Transport Fever 2 Mod.io Integration

The transition from localized, PC-exclusive modding to a unified, cross-platform ecosystem is the most significant technical hurdle modern Transport Fever 2 creators face. While the Steam Workshop allows for practically unregulated uploads, Mod.io serves as the official gateway to the Console Edition (PlayStation 5 and Xbox Series X/S). This gateway is guarded by a strict manual review process conducted by Urban Games. This is your Metruvia Content Creator Series Ultimate Guide to Transport Fever 2 Mod.io Integration.

This guide is the definitive, step-by-step engineering manual for passing that review process. Whether you are developing complex locomotives, custom railway stations, or massive logistical industry chains, this document contains every technical standard, file restriction, and formatting rule required to get your work approved, published, and in the hands of players worldwide.

Chapter 1: Establishing the Local Development Environment

Before a single line of Lua is written or a mesh is exported, your local development environment must be structured exactly as the game engine expects. The in-game Mod.io publisher reads directly from your local staging_area. If the folder hierarchy is incorrect, the mod will fail to compile or publish.

1.1 The staging_area Directory Path

All mods destined for Mod.io must be constructed within the specific staging folder generated by your Transport Fever 2installation.

• Standard Windows Path: C:\Program Files (x86)\Steam\userdata\[Your Steam ID]\1066780\local\staging_area\
• Creation: Inside staging_area, create a new folder for your mod. The naming convention of this specific folder does not dictate the mod’s final title, but using a standardized format (e.g., metruvia_creatorname_modname_1) is highly recommended for version control.

1.2 Required Root Architecture

Inside your mod’s root folder, the engine looks for three mandatory components:

1. mod.lua: The master metadata file.
2. modname_preview.jpg: The thumbnail image.
3. res/: The resource directory containing all game assets.

1.3 The res Folder Breakdown

The res (resource) folder must follow a strict internal hierarchy to ensure the game engine can correctly map your assets:

• res/audio/ (For custom sounds and effects)
• res/config/ (For UI icons, multiple units, and street definitions)
• res/models/ (The core folder)
  • res/models/model/ (The .mdl configuration files)
  • res/models/mesh/ (The 3D .msh geometry files)
  • res/models/material/ (The .mtl material definition files)
• res/textures/ (The actual image files, heavily scrutinized during console review)

Chapter 2: Metadata Engineering (The mod.lua Masterclass)

The mod.lua file is the brain of your creation. It dictates how the Mod.io API categorizes your mod, how the game loads it into memory, and what happens when a player inevitably uninstalls it. An improperly formatted mod.lua is an instant rejection.

2.1 Code Structure and Syntax

Below is the standard layout required for a robust, cross-platform release. Every parameter here is evaluated by the Mod.io indexing bot.

function data()
return {
info = {
minorVersion = 1,
severityAdd = “NONE”,
severityRemove = “WARNING”,
name = (“Metruvia Heavy Freight Expansion”), description = (“A highly optimized, console-compatible freight expansion introducing standardized intermodal well cars. De-branded for full platform compliance.”),
authors = {
{
name = “Metruvia Creator”,
role = “CREATOR”,
tfnetId = 12345,
},
},
tags = { “Vehicle”, “Wagon”, “Freight” },
visible = true,
},
options = {
— Configuration options can go here, but complex UI options may fail console checks
},
}
end

2.2 Deep Dive: severityAdd and severityRemove

These two parameters are paramount for console approval. They tell the game, the player, and the Urban Games QA team exactly how volatile your mod is to a save file.

severityAdd: Almost universally set to "NONE". Adding a mod mid-game rarely breaks the engine.

severityRemove: This is strictly monitored.

• "NONE": Removing the mod has no effect. (Example: A simple texture repaint of a vanilla train. If removed, the game just reverts to the default texture).
• "WARNING": Removing the mod will cause missing assets, causing placeholder boxes to appear, but the save will load. (Example: Custom vehicles. If the vehicle is on the map and the mod is removed, the vehicle disappears, but the logistics chain will eventually recover).
• "CRITICAL": Removing the mod will cause a fatal engine crash. (Example: Custom track types, new cargo types, or fundamental industry chain overhauls).
• Note for Console: “CRITICAL” mods face immense scrutiny. If you are developing a critical mod, your code must be flawless, as console players do not have access to backend debugging tools to rescue a corrupted save.

2.3 Official Categorization Tags

To be searchable on Mod.io, your tags array must use the exact strings defined by Urban Games. Do not invent your own tags (e.g., do not use "Train"; use "Locomotive" or "Wagon").

Rail: "Locomotive", "Wagon", "Multiple Unit"

Road: "Bus", "Truck", "Tram", "Car"

Air/Sea: "Plane", "Ship"

Infrastructure: "Train Station", "Cargo Station", "Bus Station", "Track", "Street", "Bridge", "Tunnel"

Other: "Industry", "Town Building", "Map", "Script Mod"

Chapter 3: Asset Optimization and the 200MB Limit

When transitioning from PC to Mod.io, the most frequent cause of rejection is hardware incompatibility. Modern gaming PCs feature dedicated GPUs with 12GB to 24GB of VRAM. Consoles utilize unified memory architecture (RAM and VRAM are shared). To prevent out-of-memory crashes on the PS5 and Xbox Series X/S, Urban Games strictly enforces a 200MB unpacked maximum file size limit per mod.

3.1 Polycount and Geometry Guidelines

While Transport Fever 2 can handle high-fidelity models, sheer vertex density will bloat your file size and throttle the game’s draw calls.

Locomotives: Aim for 30,000 to 50,000 triangles for the primary exterior shell.

Rolling Stock (Wagons): Aim for 15,000 to 25,000 triangles. Remember, a player might have a train with 40 of these wagons on screen at once.

Static Buildings: Aim for 5,000 to 15,000 triangles, depending on scale.

3.2 The Mandatory LOD (Level of Detail) Framework

LODs are non-negotiable for console approval. If you submit a mod with only one high-poly mesh that renders at all distances, it will be rejected instantly. You must supply at least three, preferably four, LOD states.

LOD 0 (Close-up, 0m – 150m): Your full-detail model.

LOD 1 (Mid-range, 150m – 500m): Eliminate small details (rivets, handrails, interior cab details). Reduce polycount by 50%.

LOD 2 (Distant, 500m – 1000m): Reduce polycount by an additional 50-75%. Wheels can become simple cylinders.

LOD 3 (The “Blob”, 1000m+): This is the ultimate console test. The final LOD mesh file must be under 1MB. It should be a bare-minimum silhouette of your asset, often under 500 triangles. When a player zooms out to the map view, the engine renders hundreds of these simultaneously. If they are heavier than 1MB, the console will crash.

3.3 The .mdl Bounding Box

Inside your model configuration file (res/models/model/your_model.mdl), you must define the boundingInfo. The game uses this bounding box to determine when to render the object and when to apply frustum culling (hiding it when it’s off-camera). If your bounding box is incorrectly sized, the game will render the object even when the player isn’t looking at it, wasting precious console memory.

boundingInfo = {
bbMax = { 10.5, 1.6, 4.2, }, — X (Length), Y (Width), Z (Height)
bbMin = { -10.5, -1.6, -0.5, },
},

Chapter 4: Texture Mastery and DDS Compression

Textures are the single largest contributor to file bloat. Unoptimized 4K PNG files will consume your 200MB limit instantly. To pass the console audit, you must use highly compressed, engine-native formats.

4.1 The DirectDraw Surface (DDS) Requirement

Do not upload .png or .tga files to Mod.io. The game engine must convert these formats to a readable format in real-time, which spikes load times and degrades console performance. All textures must be compiled into .dds format before publishing.

4.2 BC Compression Standards

When exporting your textures (via tools like the NVIDIA Texture Tools exporter for Photoshop, or specialized Mod.io compiler tools), you must select the correct Block Compression (BC) algorithms:

Albedo (Color) Maps: Use BC7 (Linear). BC7 offers the highest quality compression for color maps with or without an alpha channel, completely eliminating the severe color banding seen in older DXT formats.

Normal Maps: Use BC5 (Linear). BC5 is specifically designed for two-channel tangent-space normal maps. It discards the blue channel (which the game engine mathematically reconstructs) to save massive amounts of space.

MRA Maps (Metalness/Roughness/Ambient Occlusion): Use BC7. Transport Fever 2 packs these three grayscale maps into the Red, Green, and Blue channels of a single texture file.

4.3 Mip-Mapping: The Golden Rule

You must generate Mip-Maps when exporting your DDS files. A mip-map is a sequence of pre-calculated, progressively lower-resolution versions of your texture.

Why consoles require it: If a 4K texture does not have mip-maps, the console GPU is forced to load the massive 4K texture into VRAM even when the object is three miles away on the screen. This causes extreme aliasing (shimmering) and immediate VRAM overflow. Mip-maps allow the engine to seamlessly downscale the texture based on camera distance.

4.4 Texture Atlasing and Material Sharing

To keep file sizes low, avoid giving every tiny object its own unique texture sheet. If you are building a train station, map the ticket machines, benches, and trash cans to a single shared “Prop Atlas” texture. The fewer .mtl (material) calls the engine has to make, the higher the frame rate.

Chapter 5: Audio, Scripting, and Engine Restrictions

Consoles are locked environments. Unlike a PC, where arbitrary code execution is a risk the user accepts, Sony and Microsoft require strict sandboxing. Mods that attempt to break out of this sandbox will be permanently banned from the Mod.io console pool.

5.1 The Sony/Microsoft Audio Standard

Custom audio adds immense immersion, but improperly formatted audio will break the console’s sound engine buffer.

Format: All custom audio must be in .wav format (PCM).

Bit Depth: Must be strictly 16-bit. 24-bit or 32-bit float audio is unsupported.

Sample Rate: Must be strictly 48,000 Hz (48kHz). Using CD-quality 44.1kHz will result in audio pitching errors or outright silence.

Channels: Must be Mono for any sound that exists in 3D space (engine sounds, horn blasts, factory noises). The game engine requires mono files to correctly apply spatialization (panning the sound left or right based on the camera position). Stereo files can only be used for UI clicks or background music.

5.2 Scripting Restrictions (Forbidden Lua)

Transport Fever 2 has a robust modding API, but the Mod.io console environment restricts certain low-level Lua functions for security.

No loadfile or dofile: You cannot use these commands to execute external scripts outside of the game’s designated API hooks.

No OS Library calls: Any attempt to read or write directly to the host operating system’s file directories will result in an immediate rejection.

UI Alterations: Mods cannot arbitrarily add new, interactable UI menus to the screen. Console players navigate the game using controllers and a heavily modified radial UI. Custom UI elements designed for a mouse cursor do not map to the controller, resulting in soft-locks for console players.

5.3 The Ban on Custom Shaders

PC modders occasionally include custom .msh parameters that call for unique rendering shaders (like complex dynamic water effects or custom reflections). This is strictly forbidden on console. You must use the vanilla rendering pipeline and materials provided by the base game engine (PHYSICAL_NRML_MAP, REFLECTIVE, TRANSPARENT, etc.).

Chapter 6: Legal Compliance and the “De-Branding” Protocol

Technical perfection is only half the battle. The most common reason high-quality mods are rejected from the console ecosystem is Copyright and Trademark Infringement. Mod.io, Urban Games, Sony, and Microsoft are corporate entities; they cannot legally distribute intellectual property they do not own.

6.1 The “Zero Real-World Logo” Mandate

If your mod features a recognizable, real-world corporate identity, it will be flagged.

Prohibited Entities: You cannot use logos, exact brand names, or registered trademarks for rail companies (Union Pacific, DB, SNCF), airlines (Delta, Lufthansa), shipping companies (Maersk, DHL), or automotive brands (Ford, Mercedes).

The Trade Dress Rule: Even if you remove the word “FedEx,” leaving the exact purple and orange color blocking on a generic step-van can still trigger a trade dress violation.

6.2 The “Lore-Friendly” Solution

To pass QA while maintaining realism, creators must embrace fictionalization.

Instead of “British Rail,” create a high-quality logo for “National Rail Transit.”

Instead of the distinct “Amtrak” arrow, design a bespoke, era-appropriate logo for an in-game passenger service.

This approach ensures your mod passes the legal audit instantly while providing players with a cohesive, immersive world that doesn’t feel like a cheap knock-off.

6.3 Thumbnail Compliance

The legal rules apply heavily to your modname_preview.jpg and your Mod.io gallery screenshots.

The thumbnail must strictly adhere to a 16:9 aspect ratio (e.g., 1920×1080, or 1280×720).

The file size must be under 8MB.

Crucially: You cannot use real-world photographs as your thumbnail. You cannot slap a real-world company logo on the thumbnail to attract clicks. The images must be in-game screenshots of your de-branded assets.

Chapter 7: The Publishing Pipeline and QA Testing

Once your staging_area is perfectly formatted, your file size is under 200MB, your LODs are optimized, and your branding is fictionalized, you are ready to face the Urban Games manual review queue.

7.1 The In-Game Publisher

Launch Transport Fever 2 and navigate to the Mod Browser via the main menu.

Click the Publish tab. (If this tab is empty, the game does not recognize your mod.lua or staging_area structure).

Select your mod from the list.

Target Platform: Select Mod.io.

The Critical Checkbox: You must check the box labeled Console Compatible. If you do not check this, your mod will only upload to the PC side of Mod.io, completely bypassing the console player base.

7.2 The Review Queue

Once you click publish, the mod goes live immediately for PC players using the Mod.io client. However, for console players, the mod enters a “Pending Approval” state on the Urban Games backend.

The Audit: An Urban Games staff member will manually download your mod, verify the file size, launch it on a console dev-kit, check the LOD rendering, and inspect the textures for copyright violations.

Mod Drops: Urban Games typically approves mods in batches, releasing them to the console ecosystem in scheduled updates (often tied to a weekly or bi-weekly cycle).

7.3 Deciphering Rejections

If your mod fails the audit, you will receive a notification via your Mod.io dashboard. The feedback is usually brief but points to the exact violation:

• “Mod exceeds memory limits.” -> Your LOD 2/3 is too heavy, or your textures lack mip-maps and BC compression.
• “Contains restricted branding.” -> You missed a logo, or your fictional livery is too similar to a real-world counterpart.
• “Stability issues detected.” -> Check your audio sample rates and ensure you aren’t using forbidden Lua scripts.

When rejected, return to your staging_area, fix the issue, increment the minorVersion number in your mod.lua, and utilize the in-game publisher to push an update. The mod will re-enter the queue.

Chapter 8: Lifecycle Management and Version Control

Getting approved is a milestone, but maintaining a top-tier mod requires ongoing lifecycle management. When a game update drops or you wish to expand your mod’s features, you must execute patches without destroying the player’s logistics networks.

8.1 Safe Updating Practices

If you plan to update a mod that is already live on Mod.io:

Never delete existing .mdl files. If version 1.0 of your mod included a truck named truck_v1.mdl, and version 2.0 replaces it with a better model, do not delete truck_v1.mdl from your files. If you delete it, any player who had that truck driving on their map will experience a fatal crash when loading their save. Instead, hide truck_v1.mdl from the purchase menu by altering its availability dates in the configuration, and add the new truck_v2.mdl alongside it.

Maintain naming conventions. Do not rename your core res/models/ directories.

8.2 Communicating with the Player Base

Use the Mod.io description field to clearly state your mod’s console compatibility status, its safe removal parameters (severityRemove), and a clear changelog. A well-documented mod drastically reduces user error reports and builds a reputation for reliability.

Conclusion

Creating content for the Transport Fever 2 Mod.io ecosystem is a masterclass in digital engineering. It requires the artistic vision to design compelling logistics networks, paired with the technical discipline to optimize those designs for the rigid constraints of console hardware.

By strictly adhering to the 200MB limit, mastering LOD meshes, compressing DDS textures, stripping away copyrighted material, and formatting clean Lua metadata, you bypass the common pitfalls that trap novice creators. Follow this technical blueprint, and your creations will seamlessly bridge the gap between PC complexity and console accessibility, enriching the simulation experience for the entire global player base.