Blender Import/Export Add-on

Note: This is a translation of the [url='https://www.transportfever.net/lexikon/index.php/Entry/38-Blender-Import-Export-Addon/']Blender Import/Export Addon[/url] manual created by Merk.

1 Introduction

Due to various import/export options of the Blender add-on several settings are available which will be explained in this document. In addition to plain mesh exports the add-on offers a couple of functions to facilitate producing complete vehicle mods. To be able to use these functions the objects in Blender need to adhere to a certain structure which will be described as well.

2 Installation

The most current version can be downloaded from [url]http://www.train-fever.net/filebase/index.php/Entry/2-Blender-Import-Export-Addon/[/url] After downloading the file open "User Preferences" in Blender, switch to the tab "Add-ons", click on "Install from File" and select the complete .zip archive. Another way is to copy the contents of the zip archive into the addons folder of Blender ([tt]Blender//scripts/addons[/tt]). In any case the add-on has to be activated and the settings saved afterwards.

3 Settings

3.1 General

(starting with version 0.4.15) Can be found in User Preferences (tab "Add-ons", category "Import-Export", detail view of "Train Fever (.mdl)"). [img='https://www.transportfever.net/index.php/Attachment/36046-Blender-addon-settings-png/',none,288][/img] [url='https://www.transportfever.net/index.php/Attachment/36046-Blender-addon-settings-png/']Blender add-on settings[/url] [table] [tr] [td][b][u]Option[/u][/b][/td] [td][b][u]Function[/u][/b][/td] [td][u][b]Type[/b][/u][/td] [td][u][b]Version[/b][/u][/td] [/tr] [tr] [td][b]Train Fever path[/b][/td] [td]The location of the executable file of Train Fever is required to load additional scripts, e.g. [tt]laneutil[/tt] for stations and [tt]vehicleutil[/tt] for vehicles. In case of the the Steam version on Windows it should be detected automatically but it can be edited manually as well any time. If you use another version which does not support automatic detection feel free to contact me via private message.[/td] [td]String[/td] [td][/td] [/tr] [tr] [td][b]Error-Level[/b][/td] [td]Specifies which types of error messages will be shown directly in the application window after import/export (0: Only those which will prevent the model from being imported/exported correctly or which probably will cause the game to crash. 1: Errors which can be corrected by the game or the add-on and hints regarding illogical data will be displayed too).[/td] [td]Integer[/td] [td][/td] [/tr] [tr] [td][b]Debug-Mode[/b][/td] [td]If this is active the add-on will display a lot of status messages to aid in determining the exact time/cause of an error.[/td] [td]Boolean (yes/no)[/td] [td][/td] [/tr] [/table]

3.2 Import

The importer offers the following [url='https://www.transportfever.net/index.php/Attachment/36048-blender-import-options-png/']settings[/url]: [table] [tr] [td][b][u]Option[/u][/b][/td] [td][u][b]File Type[/b][/u][/td] [td][u][b]Function[/b][/u][/td] [td][b][u]Type[/u][/b][/td] [td][b][u]Version[/u][/b][/td] [/tr] [tr] [td][b]Lod distance[/b][/td] [td].mdl[/td] [td]Denotes the distance for which the lod model should be loaded (0 = all lods)[/td] [td]Integer[/td] [td][/td] [/tr] [tr] [td][b]UI-only[/b][/td] [td].mdl[/td] [td]Allows rendering of the UI icon for the model only without having to import and export it separately[/td] [td]Boolean[/td] [td]0.4.9[/td] [/tr] [tr] [td][b]Material-Config[/b][/td] [td].grp, .msh[/td] [td]Specifies the index of the MatConfig to load. In case the value is not in the supported range of array indices the matConfig used previously will be loaded.[/td] [td]Integer[/td] [td]0.4.9[/td] [/tr] [tr] [td][b]Flat-Faces[/b][/td] [td][/td] [td]Specifies if faces with Shading:Flat should be generated too. This allows for pooling of more vertices and edges.[/td] [td]Boolean[/td] [td]0.4.12[/td] [/tr] [/table]

3.3 Export

The exporter offers the following [url='https://www.transportfever.net/index.php/Attachment/36047-blender-export-options-png/']settings[/url]: [table] [tr] [td][b][u]Option[/u][/b][/td] [td][b][u]File Type[/u][/b][/td] [td][u][b]Function[/b][/u][/td] [td][u][b]Type[/b][/u][/td] [td][u][b]Version[/b][/u][/td] [/tr] [tr] [td][b]Hidden Face[/b][/td] [td][/td] [td]Hidden faces will be exported[/td] [td]Boolean[/td] [td][/td] [/tr] [tr] [td][b]Unselected Faces[/b][/td] [td][/td] [td]Unselected faces will be exported[/td] [td]Boolean[/td] [td][/td] [/tr] [tr] [td][b]Select Ngons[/b][/td] [td][/td] [td]Faces with more than four vertices which prevent an export will be selected after the attempted export[/td] [td]Boolean[/td] [td][/td] [/tr] [tr] [td][b]Override Files[/b][/td] [td][/td] [td]Existing files will be overwritten during export, the core file (.mdl, .grp or .msh) is overwritten by default if necessary.[/td] [td]Boolean[/td] [td][/td] [/tr] [tr] [td][b]Subfiles[/b][/td] [td][/td] [td]Create all files required for the object (e.g. .grp and .msh for models)[/td] [td]Boolean[/td] [td][/td] [/tr] [tr] [td][b]Directory structure[/b][/td] [td][/td] [td]Save files in a folder structure which is the same as the on in the game folder "res" (No: all files are saved in the same folder)[/td] [td]Boolean[/td] [td][/td] [/tr] [tr] [td][b]Material files[/b][/td] [td][/td] [td]Create texture and .mtl files[/td] [td]Boolean[/td] [td][/td] [/tr] [tr] [td][b]UI files[/b][/td] [td].mdl[/td] [td]Create UI views for the model (only side views so far)[/td] [td]Boolean[/td] [td][/td] [/tr] [tr] [td][b]Bounding Box[/b][/td] [td]-mdl[/td] [td]The bounding box for the model is calculated based on the mesh data (No: the value of the corresponding custom properties will be used)[/td] [td]Boolean[/td] [td][/td] [/tr] [tr] [td][b]UI only[/b][/td] [td].mdl[/td] [td]create the UI icon only (version 0.4.9 or higher)[/td] [td]Boolean[/td] [td]0.4.9 and higher[/td] [/tr] [tr] [td][b]Mesh dir[/b][/td] [td][/td] [td]Name of the subfolder for .msh files (if this input field isn't populated then all files will be put into the direcory defined in "Model type".[/td] [td]String[/td] [td][/td] [/tr] [tr] [td][b]Model type[/b][/td] [td][/td] [td]Type of the object to be exported, specifies the path to the sub folders (e.g. "vehicle/train", "vehicle/waggon, and so on). In case of "Other" the path specified in "Custom model type" will be used.[/td] [td]predefined strings[/td] [td][/td] [/tr] [/table] Additionally the input field for file names supports a couple of options: [list][*][b]empty[/b]: the file name will be generated automatically (name of the object selected + appropriate file extension) and the directory currently selected will be used as "res" directory. [*][b]name.extension[/b]: the file name matches "name", the exporter searches for a "res" directory in PATH; if the directory is not found the directory currently selected will be used again. [list][*]extension = .mdl, .grp or .msh: The file extension matches "extension" [*]other: the file extension is generated automatically [/list][/list]The default values for file names are determined based on the following logic: [list][*][b]Model:[/b] object Name [*][b]Group:[/b] the part of the object name before the first period (if the name doesn't contain any periods the full object name will be used) [*][b]Mesh:[/b] Name of the mesh, not the name of the mesh object! [*][b]Material:[/b] material Name [*][b]Texture:[/b] Name of the graphics without file Extension [/list]

4 Object structures in Blender

The addon adds new object types (Model, Lod, Group) which actually are Empties with certain custom properties. These objects can be created using one of the following two options: [list=1][*]Using the Add menu in the 3D View (Object Mode), record: Create TF Object. [*]Simply by creating an Empty and specifying the corresponding subtype in the panel "Train Fever Object" ("Metadata", "Particle Emitter", "Capacity" and "Engine" are still listed there for compatibility reasons only and shouldn't be used anymore). [/list]To enable the use of all functions most objects require other object types as a parent. For creating such a parent-child-relationship two options are available again: [list=1][*]In the 3D view (Object mode): First select the child object, then select the parent object additionally. Afterwards press Ctrl-P and select one of the options (typically [tt]Object (Keep Transform)[/tt] is the more logical choice). [*]Select the child object, then select the corresponding parent object in the dropdown list in the properties window. [/list] [table] [tr] [td][b]Object[/b][/td] [td][b]valid parent objects[/b][/td] [td][b]location of settings panel[/b][/td] [/tr] [tr] [td][b]Model[/b][/td] [td]none[/td] [td]object view of the properties window[/td] [/tr] [tr] [td][b]Lod[/b][/td] [td]Model[/td] [td]object view of the properties window[/td] [/tr] [tr] [td][b]Group[/b][/td] [td]Model, Lod, Group[/td] [td]object view of the properties window[/td] [/tr] [tr] [td][b]Mesh[/b][/td] [td]Model, Lod, Group[/td] [td]data view of the properties window[/td] [/tr] [tr] [td][b]Transport Network Provider[/b][/td] [td]Model[/td] [td]object view of the properties window[/td] [/tr] [tr] [td][b]Transport Network Group[/b][/td] [td]Transport Network Provider[/td] [td]object view of the properties window[/td] [/tr] [/table]

5 Materials and textures

Starting with version 0.4.12 The texture slots don't have to be named subject to a certain scheme. Instead a new panel (in the texture view of the properties window) can be used to specify the type of texture: [url='https://www.transportfever.net/index.php/Attachment/36049-Blender-Texture-png/']Link to screenshot[/url] If the texture slot is named according to the previously required scheme the type of texture will be selected automatically.

6 Plugins

6.1 Animations and events

[table] [tr] [td][b]File[/b][/td] [td][b]Creator[/b][/td] [td][b]Panel[/b][/td] [/tr] [tr] [td]rf_anims.py[/td] [td]Merk[/td] [td]Train Fever Object[/td] [/tr] [/table] Enables export of animations and events. [u]Animations:[/u] This field is only available for meshes, groups and lods and serves to assign more than one animation to an object: [url]https://www.transportfever.net/index.php/Attachment/36023-Blender-animations-png/[/url] [u]Events:[/u] This field is only availabe for groups and lods. [url]https://www.transportfever.net/index.php/Attachment/36024-Blender-events-png/[/url] The individual events are listed in this field. They consist of a name (can be chosen freely with regards to groups, same goes for lods basically but Train Fever will recognize and use only certain names) and a list containing an arbitrary amount of records. Each record in this list contains a choice box for a child object and a choice box which is used to specify the event or animation that will be executed for this child object. In case [tt]forward[/tt] is not ticked then the animation/event will be executed in reverse. In the choice box for the child object the current object can be selected which will cause its animation to be executed during the event. [b]Example:[/b] A group is created for a folding door (*) which contains both door parts. An animation is added to this group used to rotate it around the z-axis. The second door wing gets an additional animation which rotates it in the opposite direction. Now create an event to open the door, choose a name, e.g. "open_doors" and add two records in the corresponding list: [*]child: door group; name: name of the animation of the Group [*]child: 2nd door wing; name of the door Animation (*) Note: The exact German expression for this type of door is "Drehfalttür". I'm not sure how to translate this. My favorite translation sites came up blank for this; Google translate (which I avoid usually) suggested "folding door" so I'll go with that for now. Check out the pictures on this [url='https://de.wikipedia.org/wiki/Drehfaltt%C3%BCr']German Wiki page[/url] to get an idea what this is about.

6.2 Transport Network Provider (Paths)

[table] [tr] [td][b]File[/b][/td] [td][b]Creator[/b][/td] [td][b]Panel[/b][/td] [/tr] [tr] [td]tf_transportNetwork.py[/td] [td]eis_os[/td] [td]Train Fever TransportNetwork[/td] [/tr] [/table] To be honest I'm not an expert on this matter but I think eis_os designed it in a quite intuitive manner. First of all a "Transport Network Provider" object needs to be created (3D view: "Add" -> "Create TF Object") the parent of which needs to be set to model object (properties window: "Object" -> "Relations" -> "Parent"). After that "Transport Networks Groups" can be added at will the parent of which has to be the Transport Network Provider. Once a Transport Network Group is selected it's possible to specify the vehicle types (persons, trucks, trams, and so on) which are eligible to use the paths in the group. This is done in the object tab of the properties window in the panel "Train Fever TransportNetwork" (rightmost item). Paths are constructed from Bezier curves (standard Blender object: "Add" -> "Curve" -> "Bezier", Parent: Transport Network Group). An additional panel is available for this one too which allows for additional settings: [list][*]Track width: Width of path, only relevant for paths which designate the waiting area for persons and cargo items as far as I know) [*]vehicleNodeGroupA/B: specifies for which terminal the start (A) or end (B) point of the path serves as a vehicleNode (position at which the center point of a vehicle stops; -1 = no terminal) [*]personNodeGroupA/B: specifies for which terminal the start (A) or end (B) point of the path serves as a personNode (not sure about this one myself; -1 = no terminal) [*]personEdgeGroup: specicifies for which terminal this path serves as a personEdge (area in which persons or cargo items wait; -1 = no terminal) [/list]

6.3 Custom Metadata Provider (meta data for models)

[table] [tr] [td][b]File[/b][/td] [td][b]Creator[/b][/td] [td][b]Panel[/b][/td] [/tr] [tr] [td]tf_metadata.py[/td] [td]eis_os & Merk[/td] [td]Train Fever Object[/td] [/tr] [/table] This plug-in inherits almost all functions which are related to the [tt]metadata[/tt] record in the .mdl. In case it's deactivated most of the information in it will neither be imported nor exported.Initially the following settings are available:[url]https://www.transportfever.net/index.php/Attachment/36031-Blender-model-metadata-png/[/url]In general the fields have the same (or at least similar) names as the corresponding fields in the .mdl. In the section "Description" the contents of the fields [tt]Name[/tt] and [tt]Description[/tt] will automatically be enclosed in [tt]_([tt] and [tt])[/tt] during export to ensure correct translation of the content with the help of strings.lua. In addition values for ParticleEmitter, Engines and Capacities can be adjusted directly in this panel rendering the additional objects obsolete starting with version 0.4.9. Existing data can be merged into the new system simply by creating corresponding number of records ("+" button) in the related lists => the add-on automatically populates them with the corresponding data. These objects can also be deleted. Unfortunately the [tt]Carrier[/tt] record has to be set again explicitly for all records as I was unable to determine it from the existing data.In case these options do not suffice and even more records are required then unmarking the check box "Hide custom entries". This will provide (wherever possible) additional sub items which can be used to create records with an individual name and content:[url]https://www.transportfever.net/index.php/Attachment/36030-Blender-model-custom-metadata-png/[/url]This example would generate the following lua code:[code]example_str = "test", example_int = 7, example_table = { example_bool = false, example_float = 2.35, example_array = {1, 2, 3}, },[/code]

6.4 Materials and MatConfigs

[table] [tr] [td][b]File[/b][/td] [td][b]Creator[/b][/td] [td][b]Panel[/b][/td] [/tr] [tr] [td]tf_materials.py[/td] [td]Merk[/td] [td]Train Fever Object[/td] [/tr] [/table] Probably only interesting for people who want to attribute several materials to a mesh in order to use it multiple times (e.g. for varying coatings of a vehicle). If you don't need it, simply ignore the settings. ;) [url]https://www.transportfever.net/index.php/Attachment/36027-Blender-matConfigs-png/[/url]Additional materials can be used with meshes only, therefore they're listed in that area only. Records can be created and deleted using the "+" and "-" buttons respectively on the right border. Records don't need to be created in a particular order but shouldn't share the same [tt]Slot Index[/tt]. This specifies which material slot/sub mesh the selected materials should be added to. A small hint displays the material currently active in this slot. In the rightmost field any number of records can be created which offer a choice box in which all materials available are listed. It is recommended to tick the option "save this datablock even if it has no users" for all materials which are not used by an object to prevent a scenario wherethey're not saved in the .blend file.MatConfigs can be set for meshes, groups and lods. Here too records are created/deleted using the buttons on the right, order doesn't matter either but is retained during Export. The field name is mostly optional as it's used only in the choice box of the parent object (in the screenshot above it is the position which says "ice1_mw") but with regards to the export it can exist only once within the object. In the field next to it a material/MatConfig can be selected for each submesh/child object; the number of list records is related to the number of submeshes/child objects and cannot be edited individually. In case the number of list records doesn't match the number of required records due to certain actions (e.g. deleting a child object) the add-on displays a hint and offers an option to add or delete records.