Welcome to the Metruvia Content Creator Series Mod Validator and Diagnostic Guide. You have modeled the geometry, engineered the textures, and configured the economic logic. However, the gap between “it works on my machine” and “it is certified for global cross-platform release” is a minefield of potential crashes.

In the PC-only modding days, players were highly tolerant of bugs. If a mod caused a stutter or a missing texture, the community would simply post a comment on the Workshop and wait for a patch. In the Mod.io ecosystem, console QA teams have zero tolerance. A single memory leak, a missing file reference, or a syntax error will result in an immediate rejection, locking your content out of the PlayStation and Xbox ecosystems.

This masterclass will deconstruct the diagnostic pipeline. We will explore how to establish a sterile testing environment, decode the engine’s internal crash logs, utilize the hidden developer debug tools, and simulate the exact automated validation checks your mod will face when it hits the Mod.io API.

1. The Sterile Environment: The Baseline Test

The most catastrophic mistake a creator can make is testing their new mod on their personal, 200-hour save file that already has 150 other mods active. If the game crashes, you cannot mathematically prove your mod caused it; it could be a conflict with another creator’s code.

Before diagnostic testing begins, you must create a sterile environment.

1.1 The “Vanilla-Only” Sandbox

Navigate to the Transport Fever 2 main menu.

Select “Free Game” and generate a Small, 1:1 map with no towns and no industries.

In the Mod Selection screen, disable every single mod except the one you are testing.

Save this map as Diagnostic_Bed_01.

This is your laboratory. If the game crashes while loading this sterile save, you know with absolute certainty that the fatal error exists entirely within your local mod folder.

2. The Oracle: Decoding stdout.txt

When Transport Fever 2 encounters a fatal error, it abruptly closes to the desktop. It does not provide a helpful pop-up window explaining why. Instead, it silently writes the cause of death to a hidden text file called stdout.txt.

2.1 Locating the Crash Dump

You must know where to find this file. On Windows, it is typically located in the user data directory:

C:\Program Files (x86)\Steam\userdata\

[YOUR_STEAM_ID]\1066780\local\crash_dump\stdout.txt

2.2 Reading the Stack Trace

Open stdout.txt with a code editor (like Notepad++ or VS Code). Ignore the top 90% of the file, which simply logs your system specs and the mods loading. Scroll to the very bottom.

You are looking for the word Exception, Error, or c++ stack trace.

The engine reads dependencies hierarchically. If a train .mdl asks for a wheel .msh, and the wheel .msh asks for a metal .mtl, and the metal .mtl has a typo in it, the engine will crash.

The stdout.txt will tell you exactly which line of which file broke the chain.

3. The Lexicon of Failure: Common Fatal Errors

Over years of modding, distinct patterns emerge in the crash logs. Here is the diagnostic dictionary for the most common Mod.io rejections and engine crashes.

stdout.txt Error Output	Root Cause & Solution
file not found: res/models/mesh/...	You renamed a file in your OS, but forgot to update the .mdl or .grp script that calls it. Check your spelling.
Syntax error near ',' or unexpected symbol	A Lua syntax crash. You missed a comma, forgot a closing bracket }, or used a restricted character in your mod.lua or .mdl configuration tables.
Allocation failed / Out of Memory	VRAM exhaustion. You forgot to convert massive .tga files to compressed .dds, or you spawned too many high-poly assets simultaneously.
Invalid texture format	You used an unsupported compression (like trying to use BC5 on an Albedo map instead of a Normal map). Re-export the specific .dds.
Assertion failed: visibleFrom <= visibleTo	Your LOD (Level of Detail) distances overlap or have gaps. Ensure LOD 0 ends at exactly the same meter mark that LOD 1 begins.

4. In-Game Diagnostics: The Developer Debug Tools

You do not need to wait for a crash to diagnose your mod. Urban Games built a suite of visual debug tools directly into the engine, but they are disabled by default.

4.1 Enabling Debug Mode

Navigate to Steam\userdata\[YOUR_STEAM_ID]\1066780\local\.

Open settings.lua.

Find the line debugMode = false and change it to debugMode = true.

4.2 The AltGr + D HUD

Once in-game, press AltGr + D (Right-Alt + D). This brings up the developer overlay.

Bounding Boxes (Show Bounding Boxes): Visually confirms if your collision meshes are correct. If a box is clipping through a station platform, AI pathfinding will break.

Draw Calls (Show Statistics): The ultimate console performance metric. Spawn your vehicle and watch the draw call counter. If spawning one train jumps the counter by 50, your texture atlasing failed. You must return to Blender and merge your materials.

Wireframe Mode: Instantly exposes unoptimized geometry. If a tiny bolt on your engine block renders as a dense black blob of thousands of triangles, it will fail the Mod.io polygon budget test.

5. The Mod.io Automated Pipeline (API Validation)

When you click “Publish” in the in-game UI, your mod does not go straight to players. It hits the Mod.io API and undergoes an automated scripting check. If it fails this check, it is immediately stripped of its “Console Compatible” tag.

5.1 The File Size Gate

The API checks the unpacked size of your directory. If the raw contents exceed 200MB, it is instantly rejected. Use the Windows File Explorer “Properties” menu on your mod folder to verify the unpacked size before clicking publish.

5.2 The Linux Case-Sensitivity Trap

Consoles operate on Unix-like file systems. Windows does not care about capital letters; Linux does.

If your Lua script calls for train_wheels.msh, but the file is actually named Train_Wheels.msh, the mod will work perfectly on your PC, but will instantly hard-crash on a PlayStation 5.

The Mandate: Use strictly lowercase letters and underscores for every single folder, texture, mesh, and script in your mod.

5.3 The Mipmap Scanner

The Mod.io API physically opens every .dds file in your payload to check for a mipmap chain. If it finds a single texture lacking mipmaps, the console certification fails to prevent GPU texture-aliasing.

6. Simulating Console QA: The “Stress Test”

If your mod passes the automated API checks, it enters the manual queue where Urban Games employees test it on physical dev-kits. You can simulate their exact testing methodology on your PC to guarantee a pass.

6.1 The “Yard Test” (Memory Leak Check)

Load your sterile Diagnostic_Bed_01 save.

Build a massive rail yard with 20 parallel tracks.

Pause the game.

Spawn 100 instances of your custom vehicle.

Unpause and rapidly zoom the camera in and out.

If your framerate drops to single digits, or if the game crashes entirely, your LODs are broken or your textures are uncompressed. If it remains smooth, you have successfully met the console VRAM budget.

6.2 The Save-State Integrity Test

Buy your vehicle and assign it to a line.

Save the game as Diagnostic_Bed_02.

Exit to the desktop.

Re-launch the game and load Diagnostic_Bed_02.

If the game crashes upon loading, your initialization scripts (runFn or custom .con logic) are failing to serialize correctly, or you have renamed an internal .mdl file between saves.

7. Summary: The Pre-Flight Validation Checklist

Do not treat the Mod.io publish button as a save button. Treat it as a final deployment. Before uploading, run your project through this uncompromising workflow:

[ ] Sterile Boot: Does the mod load flawlessly in a Vanilla-Only environment?

[ ] Case Check: Are all file and folder names strictly lowercase to survive the Linux filesystem transition?

[ ] Error Log Zero: Is the stdout.txt completely free of any missing file warnings or syntax exceptions?

[ ] Debug Audit: Does the wireframe and draw-call count match your optimized VRAM budgets?

[ ] The Yard Test: Can the engine render 100 instances of the asset simultaneously without stuttering?

By adopting the mindset of a QA engineer rather than just a 3D artist, you ensure your Metruvia content moves through the Mod.io certification pipeline flawlessly, arriving on hundreds of thousands of consoles securely and beautifully.