Instructions for using the Blender import/export add-on 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 pure mesh export the add-on offers a couple of functions to facilitate producing complete vehicle mods. To be able to use these functions objects in Blender require certain properties which will be described as well. Installation ============ The most current version can be downloaded from http://www.train-fever.net/filebase/index.php/Entry/2-Blender-Import-Export-Addon/ After downloading the file open "User Preferences" in Blender, switch to the tab "Add-ons", click on "Install from File" und choose the complete .zip archive. Another way is to copy the contents of the zip archive into the addons folder of Blender (/scripts/addons>). In any case the add-on has to be activated and the settings saved. Settings ======== 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)"). https://www.transportfever.net/index.php/Attachment/36046-Blender-addon-settings-png/ Option Function Type Version ------------ ----------------------------------------------------------------------------------------------------------------------------------------------- ------- ------- Train Fever The location of the executable file of Train Fever is required to load additional scripts, e.g. for stations and for String path 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. Error-Level Specifies which types of error messages will be shown directly in the application window after import/export (0: Only those which will prevent Integer 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). Debug-Mode 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. Boolean Import ------ The importer offers the following settings: https://www.transportfever.net/index.php/Attachment/36048-blender-import-options-png/ Option File Tye Function Type Version ----------------------- --------------- ----------------------------------------------------------------------------------------------------------------------- ------- ------- Lod distance .mdl Denotes the distance for which the lod model should be loaded (0 = all lods) Integer UI-only .mdl Allows rendering of the UI icon for the model only without having to import and export it separately Boolean 0.4.9 Material-Config .grp, .msh Specifies the index of the MatConfig to load. In case the value is not in the supported range of array indices Integer 0.4.9 the matConfig used previously will be loaded. Flat-Faces Specifies if faces with Shading:Flat should be generated too. This allows for pooling of more vertices and edges. Boolean 0.4.9 Export ------ The exporter offers the following settings: https://www.transportfever.net/index.php/Attachment/36047-blender-export-options-png/ Option File Tye Function Type Version ----------------------- --------------- ----------------------------------------------------------------------------------------------------------------------- ------- ------- Hidden Faces Hidden faces will be exported Boolean Unselected Faces Unselected faces will be exported Boolean Select Ngons Faces with more than four vertices which prevent an export will be selected after an attempted export Boolean Override Files Existing files will be overwritten during export Boolean the core file (.mdl, .grp or .msh) is overwritten by default if necessary Subfiles Create all files required for the object (e.g. .grp and .msh for models) Boolean Directory structure Save files in a folder structure which is the same as the on in the game folder "res" Boolean (No: all files are saved in the same folder) Material files Create texture and .mtl files Boolean UI files .mdl Create UI views for the model (only side views so far) Boolean Bounding Box .mdl The bounding box for the model is calculated based on the mesh data Boolean (No: the value of the corresponding custom properties will be used) UI only .mdl create the UI icon only (version 0.4.9 or higher) Boolean 0.4.9 Mesh dir Name of the subfolder for .msh files (if this input field isn't populated then all files will be put into String the direcory defined in "Model type". Model type Type of the object to be exported, specifies the path to the sub folders (e.g. "vehicle/train", predefined "vehicle/waggon, and so on). In case of "Other" the path specified in "Custom model type" will be used. strings Additionally the input field for file names supports a couple of options: * empty: 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. * name.extension: 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. * extension = .mdl, .grp or .msh: The file extension matches "extension" * other: the file extension is generated automatically The default values for file names are determined based on the following logic: * Model: object name * Group: 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) * Mesh: Name of the mesh, not that of the mesh object! * Material: material name * Texture: Name of the graphics without file extension 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: 1. Using the Add menu in the 3D View (Object Mode), record: Create TF Object. 2. 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). 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: 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 is the more logical choice). 2. Select the child object, then select the corresponding parent object in the dropdown list in the properties window. Object valid parent objects location of settings panel ----------------------------------------------- ----------------------------------------------- ------------------------------------------------------------------------------- Model none object view of the properties window Lod Model object view of the properties window Group Model, Lod, Group object view of the properties window Mesh Model, Lod, Group data view of the properties window Transport Network Provider Model object view of the properties window Transport Network Group Transport Network Provider object view of the properties window 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: https://www.transportfever.net/index.php/Attachment/36049-Blender-Texture-png/ If the texture slot is named according to the previously required scheme the type of texture will be selected automatically. Plugins ======= Animations and events --------------------- File Creator Panel ----------- ---------- ----------------------- rf_anims.py Merk Train Fever Object Enables export of animations and events. Animations: This field is only available for meshes, groups and lods and serves to assign more than one animation to an object: https://www.transportfever.net/index.php/Attachment/36023-Blender-animations-png/ Events: This field is only availabe for groups and lods. https://www.transportfever.net/index.php/Attachment/36024-Blender-events-png/ 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 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. Example: Sorry, I'm at a loss regarding translating the next couple of lines. Hope to add it later. Für eine Drehfalttür wird eine Gruppe erstellt die beide Türteile enthält. Diese Gruppe eine Animation durch die sie um die z-Achse rotiert wird, zusätzlich bekommt der zweite Türflügel noch eine andere Animation, die ihn in die entgegengesetzte Richtung rotiert. In der Gruppe wird nun ein Event zum Türöffnen erstellt, als Name wählt man z.B. "open_doors", in der zugehörigen Liste müssen dann zwei Einträge erstellt werden: 1.Child: Tür-Gruppe; Name: Name der Animation der Gruppe 2.Child: zweiter Türflügel; Name: Name der Türanimation Transport Network Provider (Paths) ---------------------------------- File Creator Panel ---------------------- ---------- ------------------------------ tf_transportNetwork.py eis_os Train Fever TransportNetwork 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: * 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) Custom Metadata Provider (meta data for models) ----------------------------------------------- File Creator Panel -------------- ------------- ------------------ tf_metadata.py eis_os & Merk Train Fever Object This plug-in inherits almost all functions which are related to the 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: https://www.transportfever.net/index.php/Attachment/36031-Blender-model-metadata-png/ 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 and will automatically be enclosed in <_(> and <)> 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 record has to be set again explicitly for all records as I was unable to determine it from the existing data. In case this isn't good enough and yet more records are required then unmarking the check box "Hide custom entries" will provide (wherever possible) additional sub items which can be used to create records with an individual name and content: https://www.transportfever.net/index.php/Attachment/36030-Blender-model-custom-metadata-png/ This example would generate the following lua code: source code 1. example_str = "test", 2. example_int = 7, 3. example_table = { 4. example_bool = false, 5. example_float = 2.35, 6. example_array = {1, 2, 3}, 7. }, Materials and MatConfigs ------------------------ File Creator Panel -------------- ------------- ------------------ tf_materials.py Merk Train Fever Object 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. :-) https://www.transportfever.net/index.php/Attachment/36027-Blender-matConfigs-png/ Additional materials can be used with meshes only, thus they're available 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 . 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 where they'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.