Welcome to the Metruvia Content Creator Series Vehicle, Scripts, and Skeletal Guide. A beautifully textured, perfectly optimized 3D model is useless if it slides across the rails like a rigid plastic block. Animation—the rotation of wheels, the pivoting of bogeys, the opening of passenger doors, and the rhythmic pumping of steam pistons—is what anchors your vehicle to the physics engine of Transport Fever 2.

For a PC modder, a poorly constructed animation hierarchy might simply cause a slight dip in framerate. However, when deploying to the Mod.io ecosystem for PlayStation 5 and Xbox Series X|S, animation is scrutinized heavily by both the hardware and the QA team. Every single moving part on your vehicle generates an independent Draw Call and requires real-time matrix math from the CPU. If your animation script is bloated, a yard test with fifty trains will lock up the console processor instantly.

This masterclass will deconstruct the mathematics of mechanical motion. We will explore the rigid parent-child node architecture, the kinematic formulas for wheel rotation, the event-driven scripts for doors and pantographs, and the strict skeletal optimization required to pass console certification.

1. The Skeletal Hierarchy: Nodes and Draw Calls

Before writing an animation script, you must structure your 3D model correctly in your modeling software (like Blender) and map it accurately in your .mdl (Model) file.

Transport Fever 2 does not use traditional “bone” armatures for vehicles. Instead, it uses a Node Hierarchy (Parent-Child relationships).

1.1 The Draw Call Penalty

As established in earlier optimization articles, merging your meshes is critical to saving Draw Calls. You should combine the roof, the walls, and the chassis into one single .msh file.

However, you cannot merge moving parts.

If a wheel spins, it must be exported as a separate .msh. If a door opens, it must be a separate .msh.

The Console Danger: If you build a passenger train with 24 individual, separately animated doors, that single train generates 24 additional Draw Calls every frame. Multiply that by 50 trains in a station, and you have crashed the console’s rendering thread.

The Solution: Group mechanical actions. Instead of animating 12 left-side doors independently, merge the geometry of all 12 left-side doors into a single doors_left.msh file. You then animate that single mesh to slide outward simultaneously, reducing 12 Draw Calls down to 1.

1.2 The Parent-Child Matrix

In your .mdl file, nodes define the hierarchy. The main body is the parent. The bogeys are children of the body. The wheels are children of the bogeys. When a train rounds a corner, the engine calculates the turn, pivots the bogey, and the wheels automatically follow because of this hierarchy.

2. Axle Mathematics & Wheel Rotation

Transport Fever 2 handles wheel rotation automatically based on the speed of the vehicle, provided you give the engine the correct mathematical data. If your math is wrong, the wheels will appear to “ice skate” or spin wildly out of sync with the track speed.

2.1 The axles Array

Inside your vehicle’s metadata, you must define the axles table. You list the specific mesh node of the wheel, and you must declare its radius in meters.

metadata = {
railVehicle = {
axles = {
“vehicle/train/my_front_wheels.msh”,
“vehicle/train/my_rear_wheels.msh”
},
— …
}
}

2.2 Calculating the Radius

The game engine calculates the required rotation speed (angular velocity) by analyzing the circumference of the wheel. The underlying physics engine utilizes standard geometry:

$$Circumference = 2 \times \pi \times Radius$$

If you model a wheel with a 1.0-meter diameter, the radius you input into the .mdl bounding box must be exactly 0.5. If you guess this number, or if you scale the wheel in Blender without applying the scale transformation before exporting, the math breaks. The engine will rotate a 1.0-meter wheel as if it were a 0.5-meter wheel, destroying the illusion of physical mass.

3. Event-Driven Animations: Doors and Pantographs

Wheels rotate constantly based on physics, but doors and electrical pantographs move based on game events. These require explicit keyframe scripting.

3.1 The events Table

Animations are triggered by specific state changes. The standard events for a passenger vehicle are open_doors_left, open_doors_right, close_doors_left, and close_doors_right.

3.2 Keyframe Transformations

To script the movement, you define a timeline using time (in milliseconds) and a transformation matrix (rot for rotation, transl for sliding translation).

events = {
open_doors_left = {
[1] = { — Targeting the mesh node of the doors
forward = true,
name = “openddoors”,
}
}
},
animations = {
openddoors = {
type = “KEYFRAME”,
params = {
keyframes = {
{
time = 0,
rot = { 0, 0, 0 },
transl = { 0, 0, 0 }
},
{
time = 1000, — 1 second later
rot = { 0, 0, 0 },
transl = { 0, 0.8, 0 } — Slide outward 0.8 meters on the Y axis
}
}
}
}
}

3.3 The Clipping QA Failure

Console testers will aggressively check your door animations. If your door translates 0.8 meters but the physical wall of the train is 0.9 meters thick, the door will clip into the mesh. Visual clipping on mechanical parts is an immediate QA failure for “Console Compatible” certification. You must ensure your translation vectors precisely match the modeled door recesses.

4. Complex Kinematics: The Steam Piston Dilemma

Steam locomotives represent the absolute pinnacle of animation complexity. You have pistons driving connecting rods, which drive wheels, which drive valve gears.

4.1 The fake_bogies Solution

Historically, modders tried to script every single rod using massive mathematical arrays. This is devastating to CPU performance. Transport Fever 2 solves this elegantly with fake_bogies.

You group your connecting rods into a node and declare it as a “fake bogey” in the .mdl metadata. You assign it an offset from the center of the wheel. As the main wheel rotates via the standard axle mathematics, the engine automatically calculates the inverse kinematic pulling motion of the rods without requiring you to manually script thousands of keyframes.

4.2 Synchronization

For steam engines, visual and audio synchronization is critical. The chuff audio event is tied directly to the rotation of the driving wheels. If your fake bogey configuration is misaligned, the connecting rod will reach the end of the piston stroke, but the audio chuff will trigger half a second later. You must tune the axle radius and the fake bogey offset until the visual strike and the audio strike align to the millisecond.

5. Consolidating the Animation Budget

When targeting unified memory architecture, every keyframe costs memory.

5.1 Delete Interior Animations

If your train has animated interior compartment doors that open when passengers walk through them, delete them for the console build.

Console players primarily play zoomed out, managing macro-logistics. The VRAM and CPU cost of calculating interior kinematic data for 500 individual passengers opening tiny doors across the map is a total waste of the hardware budget.

5.2 The 30-Frame Limit

When using complex exported animations (where you baked the keyframes in Blender rather than scripting them in Lua), strictly limit your baked animations to 30 frames per second. Exporting a 60 FPS or 120 FPS animation curve doubles or quadruples the size of the .ani file for a visual smoothness that the game engine’s internal tick-rate will largely ignore anyway.

6. Summary: The Pre-Publish Animation Audit

Before compiling your vehicle payload for the Mod.io upload API, run your skeletal structure through this strict mechanical audit:

Draw Call Consolidation: Are identical moving parts (like all left-side doors) merged into a single mesh node to save Draw Calls?

Radius Precision: Do the axles radius variables perfectly match the actual geometric radius of the wheel meshes to prevent sliding?

Keyframe Clipping: Do your event translations move cleanly without clipping through adjacent geometry?

Kinematic Efficiency: Are you utilizing fake_bogies for steam rods rather than heavy, manual keyframe arrays?

Audio Sync: Does the visual culmination of the moving parts match the audio triggers in the soundset?

Mastering animation scripts transforms your 3D models from static statues into heavy, roaring machines. By optimizing your node hierarchies and respecting the CPU math limits, your vehicles will bring living, breathing infrastructure to console networks without ever dropping a frame.