The Model Editor is an assisting tool that can be used to import, view and test models.

The tool allows playing animations, changing the age (dirt and rust overlay) and the color of a vehicle as well as showing different label configurations. Also, passenger seats and cargo loads can be tested.

The Model Editor also includes an option to create screenshots and GUI icons.

The model editor ships with the game itself. To function properly, it is required to put a model_editor_settings.lua file into:

• %APPDATA%/Transport Fever 2/ for Windows
• ~/.local/share/Transport Fever 2 for Linux
• /Users/<username>/Library/Application Support/Transport Fever 2/ for MacOS (Steam/GOG/Epic)
• /Users/<username>/Library/Containers/com.gambitious.transportfever2/Data/Library/Application Support/Transport Fever 2/ for MacOS (App Store)

function data()
return {
  importFbxPath = "C:/Users/<Name>/AppData/Roaming/Transport Fever 2/fbx_import/",
  installPath = "",
  userDataPath = "D:/Steam/userdata/<steamID>/1066780/local/",
}
end

It contains several references to directories:

• importFbxPath is the directory from where the .fbx files can be imported.
• installPath usually is left empty as the Model Editor executable is in the install directory of Transport Fever 2.
• userDataPath is the directory where the userData is located. It is used to find the staging area and screenshot folders. You can find your userdata folder over the game's main menu > SETTINGS > ADVANCED > OPEN USERDATA FOLDER.

To start the Model Editor, execute the ModelEditor.bat in the installation directory of Transport Fever 2 on Windows, ModelEditor.sh in the installation directory of Linux or ModelEditor.command in the installation directory of MacOS. This will open two windows, a console window with debug output and the actual user interface window. It has a toolbar at the top and the viewport where the models are rendered below.

The toolbar is split into 5 different groups of interactive elements:

As long as no mod is selected and no model is loaded, most buttons are deactivated.

To select a mod, click on the dropdown in the top left corner of the first group 1. There you can select all mods that are located in the staging_area folder that lays within the userDataPath specified above.

After a mod was selected, you may use the OPEN button to select the model that should be loaded. The list corresponds to the folder structure within the model/ folder in the mod. To import .fbx files or open models of the base game, use the IMPORT button.

To close a model without saving, use the CLOSE button.

If you want to save a model, use the SAVE button. It will save the currently loaded model to the mod that is selected in the dropdown above. Please be aware that there is no extra confirmation in case you overwrite existing files. To only save certain file types, you may deselect the options provided in the dropdown next to the save button:

• MODEL will save the .mdl file
• MESH will save the .msh and .msh.blob files if they were just imported from fbx.
• MATERIAL will save the .mtl files
• ANIMATION will save the .ani files if they were just imported from fbx.

The model rendering in the viewport can be influenced by the second group of buttons in the toolbar 2. The three one letter buttons are:

• M for the model with the materials as it looks in the game.
• S for the model in plain white.
• W for the model as a wire mesh.

The Lod spinner below can be used to select the level of detail that should be shown. With -1 the used level of detail depends on the zoom level like in the game. 0 and above select specific levels of detail independend of the zoom level.

The Color config spinner is used only for car model that have a color configuration. It allows to cycle through all defined configurations.

The third button group 3 is relevant for animations. If the model has any animation, it can be selected in the dropdown. Then it can be started with the PLAY button. To loop the animation, activate the LOOP toggle next to it.

In the fourth group 4, there are some buttons that open additional windows for model, metadata and material details.

A click on the MODEL button opens the model window.

It has a tab for each level of detail 1. Below is a tree that shows the node hierarchy of the model with the file references and names if the nodes have names. If you activate a checkbox on the left 2, the node will be highlighted in the viewport. This helps with identifying model parts. To find out the id of a node to use it in some metadata, you can have a look on the numbers in the column next to the checkboxes 3. If you want to manually transform a mesh, e.g. to correct its position, you can open a popup with transformation parameters by clicking on the right buttons 4.

To access the metadata editor, press the METADATA button. It presents all the data that is set in the metadata block of a model 1.

To add new properties, you can press on the button in the top right corner 2. There you can select new property types and add them to the metadata of the currently loaded model. To delete all metadata, use Delete all. If you want to reset to the initial loaded values, press Reset.

The properties are collapsed by default. Press the arrow markers on the left to unfold the hierarchy levels of properties. To unfold the complete hierarchy inside of a property, you can click on the button on the right 3.

To reset a single property or only a value of the property, you can use the arrow on the right side 4. To completely remove it, press the button instead 5.

Some properties contain lists, e.g. the labels. You can add a new entry by clicking on button 6. If you want to add a duplicate of an existing list element, use the button next to it 7.

To check if there are major issues with the configured metadata, you can use the VALIDATE button in the top bar. It will run a check and informs you as soon as it finds an issue. Run it again after you fixed the issue to check if there are further issues.

Currently the following issues are covered by the validation tool:

The MATERIALS button leads you to the materials editor. It provides access to all material files that are used in the model 1.

The type of a material can be converted to any other material type by pressing the button on the right side 2. There you can reset a material file to the initially loaded values too by clicking Reset.

Below is a list of all material properties depending on the material type 3. To unfold properties, you can press the button and to reset a single property, you can click on the arrow on the right side.

You can edit the properties in a similar way as the properties in the metadata editor. Please be aware that some texture related properties are critical and might result in a crash when set to a wrong value, e.g. the compresssion or Red-green properties.

To change file references, click on the … on the right side of the reference. Then you can browse through available texture files and choose the right one.

The options window can be opened by a click on the OPTIONS button in the top right. It contains several tabs with different settings. All settings are persisted and loaded when the model editor is opened. Most of the tabs have a RESET TO DEFAULT button to revert them to their default values.

The OVERVIEW tab provides several general options:

• Enable Auto Update decides whether the model should be reloaded whenever one of the source files changes. Be aware that unsaved changes to the model are lost if the model is reloaded. If you encounter black textures or crashes while exporting textures from your graphic program, this might be caused by the Model Editor reloading the texture files before they are completely written by the program. In this case, deactivate the auto update feature before exporting the textures.
• Render Axes renders the three orientation axis that meet at the origin in the 3D space. These mark the global positive directions of the x (red), y (green) and z (blue) dimension.
• Render Debug Info renders the hierarchy of nodes in the model node tree as well as their individual orientation.
• Render Collider Info renders the collider shape as it is specified in the .mdl file.
• Render Transport Network Info renders the nodes and lanes as they are specified in the transport network provider metadata in the .mdl file.
• Render Normals renders the normals of vertices.
• Render Tangents renders the tangents of vertices.
• Render Bounding Box renders the bounding box as it is specified in the .mdl file. Models without bounding box may not load in the Model Editor.
• Enable SSAO enables the smooth ambient occlusion that is computed by the engine.
• Enable Shadows enables shadows that are computed depending on the direction of the sun.
• Enable HDR enables the higher dynamic lighting range.
• Speed scale is the speed factor that is used for animations. The default value 10 is the normal game speed.

The ENVIRONMENT tab provides several environment related options:

• Render Environment activates a gray ground face at height 0 and a simple blue skybox as the background. If set to false, no ground face is shown.
• FOV is a dropdown that lets you chose the field of view. The larger the chosen value is, the wider is the camera angle.
• Environment is another dropdown. You can choose the environment that should be used in the model editor.
• Background can be used to set the rgb values for the background color that should be used when the environment is not rendered (see above). A colorpicker is opened on click to select the color by numbers, hex code or visually.

The CONFIG tab provides options to test various features of vehicles:

• _ref_obj.mdl is a placeholder for a model reference relative to the model/ directory in the currently loaded mod or base game. If a model is referenced, it is visible as static asset. It won't be used in the screenshots. Click on the … and navigate through the file picker to select a model. With the button you can transform the reference model and with the SHOW button you can toggle its visibility.
• Color lets you choose a color for models that have color blending materials in use. Please note that the rendered colors on vehicles are less saturated than the ones in the gui.
• Age is a slider that can be used to simulate the aging of the vehicle. Depending on the age, the dirt and rust layers have different intensities.
• Render Seat Locators renders small indicators at the positions of defined passenger seats.
• Render Cargo Slot Locators renders small indicators at the positions of defined cargo slots.
• Render Cargo Bay BBox renders the bounding boxes of defined cargo bays.
• Passengers is a slider that lets you choose the amount of passengers that should be displayed.
• Cargo indicators is a list of compartments where you can select the cargo type that should be used as well as the amount that can be adjusted with the slider below.
• Random Seed is a spinner that can be used to select a seed for the randomisation of cargo slots and configurations.
• Render Label Outlines enables small markers and rectangles where text labels are placed in the model. The text boxes below can be used to define some demo texts to test the display. Be aware that custom labels currently are not compatible to the Model Editor and will likely lead to a crash.
• Render Particle Systems renders small indicators where particle emitters are located.
• Render Bogies renders small indicators where bogies are located.
• Render Fake Bogies renders small indicators where fake bogies are located.
• Render Water Line renders a line that indicates the position of the water line definition of ships.

To generate vehicle icons and take representative screenshots of the vehicle models, you can use the SCREENSHOT button on the right side of the top bar. This will generate the neccessary ui icons and moves them at the correct position in the mod. Additionally, larger renderings from all sides as well as a perspective view will be generated and saved in the screenshots/ folder in the specified userDataPath.

The ICONS tab provides options for the creation of ui icons and other screenshots:

• Screenshot extension lets you choose the file extension that is used for the generation. The game requires the .tga format, while .png might be useful for websites.
• Stage file (bus, tram, truck) is the model reference that is used as street segment for screenshots of road vehicles. Click on the … and navigate through the file picker to select a model.
• Stage file (train, wagon) is the model reference that is used as track segment for screenshots of rail vehicles. Click on the … and navigate through the file picker to select a model.
• Top screenshot button is a list of checkboxes where you can select the types of screenshots which are generated when the screenshot button in the top right corner is pressed. See the listing below for information about the different types.
• Disable Screenshot Button disables the screenshot button in the top bar so it can't be triggered accidentially.
• Bulk Generate UI/cblend Icons will generate the ui icons for all vehicle models in the mod.
• Bulk Generate 3D/ortho Screenshots will generate the other renderings for all vehicle models in the mod.

• UI icons generates icons which are used for the vehicle lists and stores. It generates icons in two different sizes. as well as the masks for color blending.
• cblend mask generates the matching color blending masks for the icons above.
• 3D screenshots generates two large screenshots from different angles.
• ortho screenshots generates screenshots from side, front and top angle.
• viewport screenshots generates a screenshot with the current perspective in the model editor. This works for models other than vehicles as well.

The GRAPHICS tab provides the possibility to adjust the major graphics settings for the model editor display:

• Graphics API selects the used graphic library, this is either OpenGL or Vulkan.
• Textures sets the texture quality used for the display of the model.
• Anti-aliasing reduces the artifacts along sharp shapes.
• Bloom controls the blooming effect around emissive faces.
• VSync adjusts the framerate to 30/60fps if possible, otherwise it is not limited.

In order for changed graphic settings to take effect, the Model Editor needs to be restarted.

The camera in the model viewer is controlled with the mouse:

• Scroll the mouse wheel to zoom in and out.
• Press the left mouse button to rotate around the center of the viewport.
• Press the right mouse button to move the camera sideways or up and down.

To rotate the direction from where the sun shines, press CTRL and the left mouse button while moving the mouse.

The Model Editor supports the import of .fbx files. However it is likely that not all .fbx files can be imported without problems as software from different vendors may have some differences in their .fbx file exporters. So far, the best results were received with files from Modo. See the information about external tools to find out more about the available modelling software.

To import a single file, drag and drop it into the model editor window. To import multiple files at once, do the same with a folder. Alternatively you may select an .fbx file from the IMPORT button menu.

Each .fbx file may contain the 3D model of one level of detail. To import several files together in a model, they should be placed in a folder. The name of the folder will be used to determine the subfolder of res/models/model/ where the model should be located, use hyphens to define the folder hierarchy: <folder>-<folder>-<mdlname>/. If $ is used, it will be replaced by the mod path.

The .fbx files for the different levels of detail are distinguished by the _lodX.fbx ending, where X=0 is mandatory and higher levels of detail are optional.

The names of nodes are structured as following:

[#]<elementname>[|<metadatatype>][#<comment>]

If the first character in the name is a #, then the whole element and all its children are ignored for export. It can be used to comment out elements

This is the name of the element that is used for the mesh by default. The element name may not contain |, % or #! Usually, the element names consist of lowercase words seperated with _.

By default, the meshes are located relative to models/mesh/<Model-Path>/. If the node should reference a shared mesh from elsewhere, the element name uses a path with '/' relative to the models root directory, e.g.: /vehicle/train/twindexx_front/front_b2. If the importer can find the mesh at this specified location, it will only be referenced, otherwise the mesh at that position in the folder hierarchy will be generated.

Elements used for the specification of metadata information start with a | character followed by the key of the metadata type. Recognized types are:

• bounding_box
• label
• emitter_smoke
• seat_<anim>
• seat_crew_<anim>

A mesh named with |bounding_box will be used to define the size of the bounding box for the model. The mesh itself will be removed on import, it’s bounding box will be used for the whole model though.

A label is defined by two locators with |label of which one is the child of the other. The parent defines the bottom left corner, the offset to the nested child at the top right corner defines the size of the label. They

1. need to be rotated in the same way
2. need to lay in the same plane along their x/y axis
3. need to have the z axis to look forward

A locator with |emitter_smoke is used to define the smoke emitter position and rotation. The scale along z axis sets the velocity.

A locator with |seat_<anim> or |seat_crew_<anim> is used to define the position, rotation and scaling of **seat** positions. <anim> needs to be replaced by the name of the character animation. If there are meshes attached to the node, they will be removed and not be present in the imported model.

If there is a # not at the first position of the name, then everything behind it is ignored.

middle_interior
middle_interior#borrowed_from_middle

will both create a node with mesh “…/middle_interior_lodX.msh” and name “middle_interior”.

#middle_interior
#middle_interior#borrowed_from_middle

will both be ignored.

front_driver_seat|seat_crew_driving_upright

will be converted to a seat locator for the driver.

cylinder_steam|emitter_smoke#left_cylinder

will be converted to a smoke emitter.

If the name of the material starts with a /, the path is evaluated as absolute. Otherwise, the materials are located relative to models/material/<Model-Path>/.

The material types that should be used by the importer are determined based on the material names and texture files. The material name ending _transparent forces the use of a transparent file type.

Depending on the provided texture names, the exact material type will be chosen:

• _albedo.dds will use a non transparent material
• _albedo_opacity.dds will use a transparent material (this requires an alpha channel in the texture)
• _metal_gloss_ao.dds will use a physical based material
• _normal.dds will use a material with a normal map
• _cblend_dirt_rust.dds will use a material with dirt and rust blending

To reference existing materials, use absolute paths starting with / like /street/new_medium_tram_track. If the importer can find the material at this specified location, it will only be referenced, otherwise the material at that position in the folder hierarchy will be generated with the assigned textures.

Imported models will generate .ani files from the key frames that are defined in the first level of detail. Animations defined in other levels of detail are ignored. The names of animations in the .fbx file are used to determine where the .ani files should be located:

• man/walk will result in .ani files in models/animation/MODEL_PATH/man/walk/
• /man/walk will result in .ani files in models/animation/man/walk/
• walk will result in .ani files in models/animation/MODEL_PATH/walk/head.ani