Model Editor¶

Der Model Editor gehört zum Spiel. Er importiert .fbx-Dateien als TF3-Modelle, bearbeitet Metadaten und Materialien, zeigt Animationen, Partikel, Beschriftungen, Güter und Alterung in der Vorschau, prüft Modelle auf Fehler und rendert die Fahrzeug-Icons. Diese Seite fasst die offizielle Wiki-Seite Model Editor zusammen. Die Dateiformate, die er schreibt, beschreibt Modelle und Assets.

Einrichtung¶

Starte im Installationsverzeichnis des Spiels ModelEditor.bat (Windows), ModelEditor.sh (Linux) oder ModelEditor.command (macOS). Es öffnen sich zwei Fenster: eine Konsole mit Debug-Ausgaben und der Editor selbst.

Beim ersten Start legt der Editor eine Konfigurationsdatei an und bittet dich, dort deinen Benutzerdatenordner als userDataPath einzutragen. Die Datei liegt hier:

System	Ordner
Windows	`%APPDATA%/Transport Fever 3/`
Linux	`~/.local/share/Transport Fever 3`
macOS	`/Users/<username>/Library/Application Support/Transport Fever 3/`

Das Spiel zeigt den Benutzerdatenordner unter Hauptmenü > Einstellungen > Erweitert > Userdata-Verzeichnis öffnen. Schreib den Pfad nur mit normalen Schrägstrichen (/), sonst startet der Editor unter Umständen nicht. Über diesen Pfad findet der Editor den Staging-Bereich (deine Mods in Arbeit) und den Ordner screenshots/. Schon beim ersten Start schreibt er außerdem einen Teal-Workspace in den Staging-Bereich: tlconfig.lua, eine globale Definitionsdatei und .vscode/extensions.json. Was diese Dateien tun und wie sich die Namen im Wiki von denen im mitgelieferten vscode-template/ unterscheiden, steht unter Erste Schritte.

Das Fenster¶

Die Werkzeugleiste hat fünf Gruppen: Öffnen und Speichern, Render-Modus und LOD, Animationsvorschau, die Detailfenster (Modell, Metadaten, Materialien, Animationen) sowie Validierung, Screenshots und Optionen. Die meisten Schaltflächen bleiben deaktiviert, bis ein Modell geladen ist.

Im Viewport drehst du die Ansicht mit gedrückter linker Maustaste, verschiebst sie mit der rechten und zoomst mit dem Mausrad. Mit Strg und gedrückter linker Maustaste drehst du die Skybox.

Öffnen und Speichern¶

Der Öffnen-Dialog zeigt das Basisspiel und jeden Mod im Staging-Bereich. Er durchsucht alle Unterordner des gewählten Ordners und führt eine Liste der zuletzt geöffneten Modelle. Beim Speichern landet das Modell in dem Mod, der im Dropdown neben der Speichern-Schaltfläche gewählt ist. Vorhandene Dateien überschreibt der Editor ohne Rückfrage. Im Dropdown legst du fest, was geschrieben wird:

Option	Schreibt
MODEL	die `.mdl`
MESH	`.msh` und `.msh.blob`, nur bei frisch importierten Meshes
MATERIAL	die `.mtl`-Dateien
ANIMATION	`.ani`-Dateien, nur bei frisch importierten Animationen

Ansichtsmodi und Animationsvorschau¶

Die Render-Schaltflächen schalten zwischen texturiert, einfach weiß und Drahtgitter um. Die LOD-Auswahl steht entweder auf Auto (nach Zoomstufe wie im Spiel) oder auf einer festen Stufe. Die Animationsgruppe spielt ein Animations-Event des Modells einmal oder in einer Schleife ab.

Modellfenster¶

Das Model-Fenster zeigt den Modellpfad, Schaltflächen zum Neuberechnen der Bounding Box und des Simulationsumfangs (Extent) sowie Felder, in denen du die Bounding Box bearbeitest. Pro LOD gibt es einen Tab mit visibleFrom, visibleTo und dem Flag für die Textur-LOD-Basis. Darunter steht der Knotenbaum mit Namen und Mesh-Dateien. Hakst du einen Knoten an oder fährst mit der Maus darüber, zeigt der Editor nur dieses Mesh. So findest du einzelne Teile schnell. Jeder Knoten hat eine Schaltfläche für einen Transformationsdialog. Die letzten Spalten zählen Materialien und Animationen pro Knoten, Extended View listet sie auf.

Metadatenfenster¶

Das Metadata-Fenster zeigt die ganze metadata-Tabelle als Baum. Die Schaltfläche + fügt einen Block hinzu, das Zahnradmenü löscht alle Metadaten, und Reset stellt den geladenen Zustand wieder her. Ein Klick mit gedrückter Umschalttaste auf einen Pfeil klappt einen Block vollständig auf. Jedes Feld und jeden Block kannst du zurücksetzen oder entfernen, Listeneinträge kannst du hinzufügen oder duplizieren. Wo es Vorlagen gibt, bietet sie die Zahnrad-Schaltfläche links neben dem Feld an.

Feldnamen, Typen und Vorlagen stammen aus base/content/model_editor/model_editor/meta_metadata.lua in den Spieldateien, z. B. ["transformatorConfig.skipFromLod"] = { name = "Skip LODs from", type = "INTEGER", order = 6 }.

Materialfenster¶

Das Materials-Fenster listet jedes Material des Modells mit seinem Typ-Präfix. Materialien mit relativem Pfad sind hervorgehoben. Materialien mit absolutem Pfad teilt sich das Modell wahrscheinlich mit anderen Modellen, also bearbeite sie mit Vorsicht. Fährst du mit der Maus über ein Material, blendet der Editor die übrige Geometrie aus. Beim gewählten Material kannst du order ändern, es in einen anderen Materialtyp umwandeln, es zurücksetzen und seine Eigenschaften bearbeiten. Texturpfade tippst du ein oder wählst sie in einem Dateidialog. Für einige Eigenschaften gibt es Vorlagen. Sie stehen in den Spieldateien in base/content/model_editor/model_editor/meta_material.lua: „Default dirt/rust“ für dirt_rust, „Interior / Exterior“ und „Interior / Exterior Glass“ für alpha_test sowie „Interior“ und „Exterior“ für light_receiver.

Validierung¶

Die Validieren-Schaltfläche in der Werkzeugleiste prüft das geladene Modell und hält beim ersten Problem an. Starte sie nach jeder Korrektur erneut. Das Werkzeug Validate unter Options > Tools prüft viele Modelle auf einmal. Das Wiki listet die möglichen Meldungen auf. Sie betreffen diese Bereiche:

Bereich	Prüfungen
`loadIndicator`	`cargoBay.childId` nennt einen fehlenden Knoten; die Box des Laderaums ist zu klein; eine Konfiguration verweist auf einen fehlenden Slot
`roadVehicle`, `railVehicle`	`fakeBogies` braucht eine Liste pro LOD (leere Listen sind erlaubt) oder muss leer sein
`waterVehicle`	`area` ist für `availPower` zu groß, das Schiff erreicht seine Höchstgeschwindigkeit nie
`airVehicle`	`wheels` und `axles` müssen beide gesetzt sein; ein Fahrwerk ohne Abstand zwischen den Rädern oder mit zu niedrigem oder zu hohem Bodenanstellwinkel
`seatProvider`	ein Sitz nennt einen fehlenden Knoten
`transportVehicle`	leere `loadConfigs`; ein Gütereintrag verweist auf eine fehlende Ladeanzeige oder einen fehlenden Sitz; negative Kapazität; unbekannter Gütertyp oder unbekannte Güterklasse
`categoryList`	unbekannter Gütertyp oder unbekanntes Güterformat
Mesh	der Materialtyp braucht ein Vertex-Attribut, das dem Mesh fehlt, meist `uv1` oder Skinning-Daten
Material	fehlende Texturdatei; die Zahl der Materialien oder Skin-Materialien weicht von der Zahl der Submeshes ab (der Editor gleicht das aus); ein Mesh mit Skinning, dessen Material kein Skinning hat
Animation	Zahl der Zeitpunkte und der Transformationen weicht ab; keine Keyframes; der erste Keyframe liegt nach 0

Optionen¶

Das Options-Fenster behält seine Einstellungen über Sitzungen hinweg. Die meisten Tabs haben eine Schaltfläche Reset to default.

Tab	Einstellungen
Rendering	Overlays für Achsen, Knoten, Knotennamen, Bounding Box, Extent-Box und Collider; Locators für Sitze, Lichter, Partikelemitter, Beschriftungen (mit Demotexten), Wasserlinie von Schiffen, Laderäume, Ladeplätze, Achsen und Räder, Drehgestelle und Fake-Drehgestelle; Vertex-Normalen und -Tangenten
Config	automatisches Neuladen bei Dateiänderung (nimm On Focus, wenn Texturen halb geschrieben aus deinem Bildbearbeitungsprogramm geladen werden), Animationsgeschwindigkeit, LOD-Skalierung, ein Referenzmodell zum Vergleich, Farbe für Color-Blend-Materialien, Alter für Dreck und Rost; Passagier- und Gütermenge, Zufallswert und Gütertyp pro Abteil; Partikelvorschau mit simulierter Geschwindigkeit und Tag-Filter; Testtexte für Beschriftungen
Graphics	Texturqualität, Antialiasing, Bloom, SSR, SSAO, Schatten, altes HDR-Rendering (TF2), VSync; manche Einstellungen brauchen einen Neustart
Environment	Sichtfeld und Hintergrundfarbe; Boden und Himmel an oder aus, die Umgebung, Tageszeit, Tag im Jahr, Helligkeit, Sonnenintensität sowie Umgebungsfarbe, HDR-Belichtung und Kontrast für Tag und Nacht
Icons	Screenshot-Format (das Spiel braucht `.tga`), Bühnenmodelle für Straßen- und Schienenfahrzeuge, Umgebung und Animationszustand für Screenshots, Icon-Breite und Pixel pro Meter, Kamera für 3D-Screenshots, welche Bilder die Screenshot-Schaltfläche erzeugt, Massenerzeugung für einen Ordner
Im-/Export	beim erneuten Import Meshes, Animationen, Materialien, `PHYS_TRANSPARENT_DIFFUSE`-Platzhaltermaterialien und Texturen überschreiben; Blender-Koordinatensystem; Qualität der Umwandlung von `.tga` nach `.dds`, oder vorhandene Texturen nicht neu komprimieren
Tools	Ziel-Mod und Ordner für Massenvorgänge; Rename (Suchen und Ersetzen in Dateinamen); Convert (TF2-Modelle aus `res` in die TF3-Struktur mit `content`, `.mtl`-Dateien mit gesetztem Legacy-Flag, Metadaten, bei denen du neue Werte noch von Hand eintragen musst); Copy (Modell in einen anderen Mod); Validate (viele Modelle)

Die Bühnenmodelle und Umgebungen für Screenshots liegen in den Spieldateien unter base/content/model_editor/model_editor/stage/ (etwa stage_track_standard.mdl, stage_street_country_new.mdl) und .../environments/ (vehicles.env.lua, vehicles_3d.env.lua, temperate_model_editor.env.lua, substance_3d_model_editor.env.lua).

Icons erzeugen¶

Die Screenshot-Schaltfläche in der Werkzeugleiste rendert die UI-Icons und legt sie an der richtigen Stelle im Mod ab. Sie kann außerdem Color-Blend-Masken, perspektivische Ansichten, große und kleine orthografische Ansichten und ein Bild des Viewports nach screenshots/ unter userDataPath schreiben. Bulk Generate macht das für jedes Modell in einem Ordner und kann lange dauern. Die Wiki-Seite Best practice bittet darum, dass Mods alle Icons mitliefern, auch die cblend-Masken.

Importieren¶

Der Editor importiert drei Arten von Dateien: .import.lua-Vorlagen, .fbx-Modelle und .fbx-Konstruktionsdaten. Unterstützt werden FBX-Dateien aus Modo und Blender. Für Blender schaltest du im Tab Im-/Export die Option Use Blender Coordinate System ein.

Vorlagen (.import.lua)¶

Ziehst du vor den Modellen eine .import.lua-Datei in den Editor, legt sie Standardwerte für die folgenden Importe fest. Sie definiert bis zu drei Funktionen in einer Tabelle fbxLoader:

fbxLoader = {
    predictMaterial = function(params)
        return "::physical_nrml_map_op_uv1_ao_op_mask.mat.lua"
    end,
    overrideProperties = function(params)
        return params.properties
    end,
    getMetadataMap = function()
        return { availability = { yearFrom = 1900, yearTo = 0, }, }
    end,
}

predictMaterial läuft für jedes Material und gibt eine Materialtyp-Datei oder nil zurück. Sein Argument params enthält fbxPath (Ordner der .fbx), fbxName (Dateiname ohne _lodX und Endung), fbxMaterialName und textures (die Texturdateien, die in der FBX zugewiesen sind). overrideProperties bekommt dasselbe und dazu materialType und properties (die Materialparameter wie in einer .mtl) und gibt die geänderten properties zurück. getMetadataMap nimmt keine Argumente und gibt die metadata-Tabelle für die danach importierten Modelle zurück. Im Wiki kannst du einen Material-Override für Fenster und eine Metadaten-Vorlage für Busse herunterladen.

FBX-Modelle¶

Zieh eine .fbx-Datei in den Editor, um sie zu importieren, oder einen Ordner, um alle Dateien darin zu importieren. Eine .fbx enthält genau ein LOD und endet auf _lod0.fbx, _lod1.fbx und so weiter. _lod0 ist Pflicht. Alle LODs eines Modells gehören in einen Ordner, und der Ordnername bestimmt, wo das Modell im Mod landet:

Ordnername	Ergebnis
`vehicle-bus-my_bus/`	`vehicle/bus/my_bus/my_bus.mdl`
`vehicle-train+my_unit_a/`	`vehicle/train/my_unit_a.mdl`; so können sich mehrere Modelle einen Ordner teilen, z. B. bei einem Triebzug

Knotennamen¶

Knotennamen haben die Form <elementname>[#<comment>]. Der Elementname wird zum Knotennamen und zum Mesh-Namen. Er darf kein |, % oder # enthalten, und das Suffix _lodX hängt der Editor selbst an. Alles nach # wird ignoriert. Damit fallen Blenders Suffixe wie .001 weg, und zwei Knoten können denselben Namen tragen: middle_interior und middle_interior#borrowed_from_middle werden beide zum Knoten middle_interior mit dem Mesh middle_interior_lodX.msh. In Blender ist der Objektname der Knotenname und der Name der Mesh-Daten der Name der .msh-Datei.

Der Elementname kann auch ein Pfad sein. Dann verwendet der Editor ein vorhandenes Mesh wieder oder legt es an dieser Stelle an:

Elementname	Mesh
`w1`	`msh/w1_lodX.msh` neben dem Modell
`/vehicle/waggon/bay_05/msh/w1`	`vehicle/waggon/bay_05/msh/w1_lodX.msh` im aktuellen Mod, wird angelegt, falls es fehlt
`::/vehicle/waggon/bay_05/msh/w1`	derselbe Pfad im Basisspiel
`master_mod::/vehicle/waggon/bay_05/msh/w1`	derselbe Pfad im Mod `master_mod`, der in `mod.json` als Abhängigkeit eingetragen sein muss

Materialien¶

Materialnamen haben die Form <materialname>[|<prefix>][#<comment>]. Der Name funktioniert wie ein Mesh-Name: Ein einfacher Name legt das Material neben dem Modell an, ein absoluter Pfad wie /infrastructure/tracks/standard/mat/ballast verwendet dieses Material wieder oder legt es dort an. |<prefix> wählt den Materialtyp über sein Kürzel, z. B. window|PNOL für PHYSICAL_NRML_MAP_OP_LIGHT. Die Präfixe stehen in Modelle und Assets und in der rendering/*.mat.lua des jeweiligen Typs (prefix = "PNOL").

Texturen¶

Der Importer findet die Albedo-Textur, wenn sie in der FBX dem Material zugewiesen ist oder den Namen des Materials plus ein Albedo-Suffix trägt. Alle anderen Maps brauchen den Basisnamen der Albedo-Textur plus eines dieser Suffixe:

Map	Suffixe
`map_albedo`	`_alb`, `_albedo`
`map_albedo_opacity`	`_albo`, `_albedo_opacity`
`map_normal`	`_nrm`, `_normal`
`map_metal_gloss_ao`	`_mga`, `_metal_gloss_ao`
`map_cblend_dirt_rust`	`_cdr`, `_cblend_dirt_rust`
`map_cblend`	`_cblend`
`map_ao`	`_uv1_ao`
`map_id`	`_id`, `_emissive_ID_lod1`
`map_lgt`	`_e`
`map_op_1`, `map_op_2`	`_op1`, `_op2`

Die Texturen des Basisspiels nutzen dieselben kurzen Suffixe (am häufigsten _mga, _nrm, _alb, _albo, _id, _e und _cdr), daneben aber auch _albedo, _normal, _ao, _opacity und _texture. Beim Speichern des Modells wandelt der Editor .tga-Texturen in .dds um.

Animationen¶

Keyframe-Animationen an den Meshes werden zu .ani-Dateien. In Blender legst du sie als NLA-Strips ab, die nach dem Animations-Event benannt sind. Mehrere Strips (einer pro animiertem Mesh) können zum selben Event gehören, wenn du die Suffixe wie .001 mit # abschneidest.

Metadaten aus der FBX¶

FBX-Element	Wird zu
Point-, Spot- oder Directional-Licht (Blender: Point, Spot, Sun)	eine Lichtquelle vom Typ `POINT`, `SPOT` oder `PARALLEL` mit `lightId` aus dem Objektnamen, `transf`, `color`, `strength` (Blender-Leistung × 100), `angleMin`/`angleMax` aus Angle und Blend in Blender und dem Elternknoten
Locator `…\\|seat_<anim>` oder `…\\|seat_crew_<anim>`	ein Sitz für Passagiere oder Besatzung; `<anim>` ist `idle`, `sitting`, `driving_upright` oder `driving`. Meshes darunter fallen weg.
Locator `…\\|draft_animal_<mdl>[(<index>)]`	ein Zugtier, z. B. `something\\|draft_animal_mymod::/animal/draft_horse/draft_horse.mdl(2)#something` für die zweite Farbkonfiguration
Locator mit `emitter` im Namen	ein Partikelemitter mit `particleId`, `position` und `velocity` (aus der x-Skalierung); `smoke_bright` oder `smoke_dark` im Namen ergänzt Standardwerte für Rauch
Mesh `…\\|bounding_box`, `…\\|extent`, `…\\|collider_list`	die Bounding Box, der Extent oder ein Box-Collider; das Mesh selbst fällt weg
zwei verschachtelte Locators `…\\|label`	eine Beschriftung: Der Elternknoten ist die linke untere Ecke, das Kind die rechte obere. Beide brauchen dieselbe Rotation, müssen in einer x/y-Ebene liegen und in z-Richtung zeigen.

Massenimport¶

Für viele Modelle auf einmal, etwa Brücken und Tunnel, ziehst du eine .txt- oder .log-Datei in den Editor:

Scene;<scenename>
ModRefName;<modid>
DeleteTargetFolders;<False or True>
Path;<path to folder with fbx>
Path;<another path to folder with fbx>

ModRefName ist der Ziel-Mod. Scene ist eine optionale Notiz zur Quelldatei. DeleteTargetFolders = True überschreibt alles im Mod. Jede Path-Zeile nennt einen Ordner mit _lod0.fbx, _lod1.fbx und so weiter.

Konstruktionsdaten¶

Eine .fbx kann auch ein Konstruktionsskript füllen. Zieh sie auf das Feld im Tab Im-/Export. Ihre Empty-Knoten auf oberster Ebene tragen den Namen des Zielskripts, z. B. /industries/brewery/brewery.script. Das Skript muss die beiden Markierungszeilen unten enthalten, und der Import ersetzt alles dazwischen:

--Begin Generated

--End Generated

Darunter bilden Empty-Knoten mit dem Namen <name>.id (optional mit #comment) die obersten Ebenen, die das Construction-Util erwartet, etwa base, static oder level1. Darin gilt:

Knotenname	Bedeutung
`collider.curve[#comment]`	der Collider der Konstruktion
`less.mesh`, `greater.mesh`, `equal.mesh`	Geländeanpassung: Obergrenze, Untergrenze, exakt
`<mod>::<path>/<name>.mdl[#comment]`	ein platziertes Modell mit der Transformation des Knotens
`<key>.grp`	eine zufällige Asset-Gruppe aus `/scripts/construction/asset_util.tl`
`seed(<n>)\\|…`	gemeinsamer Zufallswert, z. B. `seed(123)\\|era_a_garden_chair.grp`
`align\\|…`	hält die Höhe relativ zum Ursprung der Konstruktion, statt dem Gelände zu folgen
`ignore(<percent>)\\|…`	zeigt das Modell nur manchmal, z. B. `ignore(50)\\|::/assets/buildings/ind/boxes/wood_box_long.mdl#`

align, seed und ignore funktionieren auch an einem Empty-Elternknoten und gelten dann für alle seine Kinder. Wie Konstruktionen diese Daten nutzen, steht unter Konstruktionen.

Hinweise aus den Spieldateien¶

Laut der Einrichtungsanleitung im Wiki liegen die Startskripte unter Windows im Installationsverzeichnis „of Transport Fever 2“. Sie gehören aber zur TF3-Installation.
Der Editor führt die Ladekette des Basisspiels für Modelle aus seinem eigenen Mod-Skript aus, base/content/model_editor/model_editor/editor_base_mod.lua (toCompartmentList, addTransformatorConfig, makeLoadIndicators, sortLods, addTextureLods, ...). Deshalb sieht ein Modell im Editor genauso aus wie im Spiel. Wie im Spiel wandeln addTransformatorConfig, sortLods und die Funktionen createAnimationEvents* nur Modelle um, die älter als version = 2 sind. Ein neues Modell braucht diese Blöcke also gleich in ihrer endgültigen Form (siehe Fahrzeuge).
Die Feldliste in meta_material.lua enthält ein Sampler-Flag compressionAllowed, das die Material-Seite im Wiki nicht beschreibt.

Offizielles Wiki: Model Editor, External tools, Best practice, Material definition (.mtl).