TrainzOnline - User contributions [en]

Category-class

2021-06-21T20:31:17Z

Gdennish: /* Class T: TRACK */

{{ORP-top}}
==Category-class Tags==
The '''"category-class" tag''' of the [[KIND_TrainzBaseSpec|TrainzBaseSpec]] is the ''key searching parameter'' defining what or how the human content creator meant for the new asset ''to be used and thought about.'' This should not be confused with the [[Category List]], which is a related but distinct topic.
{{UserTip|width=50%|This is a sometimes nebulous and confusing parameter requiring a new user to develop a degree of mental agility, for example, '''a 'house' asset''' might be classified (Coded by some asset creator) as scenery, building, industry, or even something as wildly inappropriate as 'fauna'.}}

The [[KIND]] specification defines which other ({{wp|data type}}) entries'' are needed'' in that particular asset's config.txt file. It is the entry which defines the asset's type, scope, and needs and the very important parameter that tells TRAINZ how to process and render the specific asset item correctly, error check against the standard for the category-class, and render it into {{wp|Three-dimensional space|3D graphics}} models.

Each Trainz asset's category-class tag helps describe the 'intent' of the Asset in the game, as opposed to the internal structure of the Asset. The Content Creators' Guide for Trainz Classics said these classes represent a standardized system for referring to the various types of Locos, Rolling stock, Scenery, Spline and Industry assets. The Category-class classification codes become important to all Trainzers when searching and/or filtering for suitable assets to make into content in a session or route (layout).

;Trainz Base Specification
:(all config.txt files can contain all these entries){{TBS}}
::'''<big><big>Figure: 1 TrainzBaseSpec for quick reference</big></big>'''


==Category-class code notes==
New users should be aware that these codes listed below are not the direct ContentManager.exe category sort by classifications as a simple comparison of lists will reveal, but they do affect what is displayed within such a sort filter selection.
:For example: Set a search filter for ''''''Location>Local + Category>Flora''''''.
: In the base installed content of TRS2006-SP0 this search will yield diverse assets such as the set of {'''Flora''' types: SOME few trees, Betonbridge (1,2,&3 tracks), crop splines, sidewalks, road types}
:but the sort will also list a much larger type group, the set of {Scenery: retaining wall splines (Arkaden...), LOADS of trees and Shrubs including Laubbaum with birds (and sound), grasses (textures?), Logs} and so forth.
In that search you will also find electrified railroad centenary parts and the occasional animal. The result of such a search will be no better in new Trainz versions, which means the new Trainzer needs to cultivate a certain mental agility when searching for suitable content. No one has the man-power, deep pockets, nor copyright authority to systematically fix such foibles. You as a user, can clone such items and change the classification to something more sensible to yourself. That however, is not an asset you can upload to the Download Station without a copyright clearance from the original asset creator. The Trainz community is severe in policing copyrights violations!
{{TrainzTip|These codes when applied by the content creator were in many cases cut and pasted into a new similar asset, in others, the way he or she was using the asset in their current project. In short, they are not definitive, but are indicative... even if it is only of the mental state of the creator at the time of donation to the DLS, or as happens in many cases, a case of translation from a native tounge with a different way of thinking than that of English.}} Rejoice in the positive, they are essentially free and cost you nothing but a bit of puzzlement. Free is good! Having them is better.

==The Category Classes are:==
Class "A" Motive Power
Class "B" Buildings and Structures
Class "C" Cabeese
Class "D" Defence
Class "E" Environment
Class "F" Foliage
Class "G" Ground
Class "H" Mesh
Class "I" Product
Class "J" Texture
Class "L" Light Rail & Monorail
Class "M" Maintenance Of Way
Class "O" Organism
Class "P" Passenger & Mail Cars
Class "R" Railcars & Multiple Unit Sets
Class "S" Splines
Class "T" Track
Class "V" Vehicles
Class "W" Wayside
Class "X" Freight Cars
Class "Y" Maps and Scenarios
Class "Z" Train Parts
::'''Figure 02: Base category-class prefixes'''

Each Category Class may have a number of subcategories as listed below. Please choose the most appropriate Category Class for your item. Select the Class from the [[Content Creator Plus]] drop down menu box - only one class may be selected for an asset.

Selecting a correct Category Class is important since Trainz will allow users to use the Category Class as a sort and selection criteria.

{|
|-valign="top"
|
===Class A: MOTIVE POWER===
*AA Electric Multi-current
*AC AC Electric
*AD DC Electric
*AE Experimental or Special
*AG Gas Turbine
*AH Diesel Hydraulic
*AL Diesel & Diesel Electric
*AM Mammal
*AS Steam Loco & Tender
*AT Steam Tank

===Class B: BUILDINGS & STRUCTURES===
*BB Buildable (Kind Buildable)
*BC Commercial (scenery non-functional)
*BI Industrial (scenery non-functional)
**BIN Industry asset with product processing functionality
*BH Home & Residential (scenery non-functional)
*''Subclass BP: Passenger Station''
**BPF Passenger Station with passenger processing functionality
**BPN Passenger Station (non-functional)
*BR Railway (scenery non-functional)
*BS Special (e.g. military) (scenery non-functional)
*BT Traffic & Streetscape (scenery non-functional)
*BU Utility (incl. Civil buildings) (scenery non-functional)

===Class C: CABEESE / CONSIST / EFFECTS===
*CB Brake van
*CC Caboose
*CLUT Clutter Effect
*CN Consist
*CS ControlSet

===Class D: DEFENCE===
*DA Military motive power
*DE Military experimental & special vehicles
*DP Military equipment - lab & personnel vehicles
*DX Military equipment - freight

===Class E: ENVIRONMENT===
*ES Sky
*EW Water

===Class F: FOLIAGE===
*FC Cactii
*FF Flowers
*FO Orchards & Crops
*FS Shrub
*FT Trees

===Class G: GROUND===
*GA Arid
*GL Lush
*GS Seasonal

===Class H: MESHES===
*HM Mesh

===Class I: PRODUCT===
*IC Container Category
*IP Passenger Category
*IB Bulkload Category
*IL Liquid Category

===Class J: TEXTURES===
*JC Corona
*JI Icon
*JP Particle Effects Texture
*JO Other Texture

===Class L: LIGHT RAIL & MONORAIL===
*LS Articulated train sets
*LT Trolleys, trams & streetcars
*LM Monorail vehicles

===Class M: MAINTENANCE of WAY===
*MA Camp vehicles
*MB Ballast cars
*MC Cranes/lifting
*MD Diagnostic vehicles (e.g. dynamometer)
*ME Instructional vehicles
*MF Fire vehicles
*MI Inspection vehicles
*MT Track vehicles (e.g. tamper)
*MP Snow ploughs
*MS Section cars (e.g. fairmont)
*MX Freight equipment (for MoW traffic)
*MW Weed spray

===Class O: ORGANISM===
*OA Animal Kingdom
*OH Human
**OHD Locomotive Driver

===Class P: PASSENGER & MAIL CARS===
*PA Suburban/short haul (no W.C.)
*PB Baggage cars
*PC Coach/chair cars
*PD Dome cars
*PH Bar/cafeteria cars
*PL Lounge cars
*PM Mail cars
*PO Observation cars
*PP Power cars
*PR Buffet/dining/restaurant cars
*PS Sleeping cars
*PU Special cars (e.g. Gaming Cars)
*PV Private cars
*PX Composite passenger cars

|
===Class R: RAILCARS & MULTIPLE UNIT SETS===
*RA AC electric
*RC DC electric
*RD Diesel & diesel electric
*RH Diesel hydraulic
*RP Petrol
*RS Steam

===Class S: SPLINES===
*SF Fences
*SR Roads
*SP Platforms
*SS Structure
*SV Vegetation

===Class T: TRACK===
*TB Bridge
*TC TestTrack Course
*TR Rails
*TT Tunnel
*TURF Turf Effect
*TF Fixed Track

===Class V: VEHICLES===
*VA Air
*VL Land
*VS Sea

===Class W: WAYSIDE===
*WA Signalling
*WS Trackside signage
*WX Accessories

===Class X: FREIGHT CARS===
*XA Auto transporter
**XAA Open sides
**XAB Auto box car
*XB Box car/covered van
**XBD Dangerous goods
**XBG General service
**XBI Insulated
*XF Flat
**XFA Articulated
**XFC Intermodal
**XFD Depressed center
**XFH Heavy duty
**XFM General service
*XG Gondola/open wagon
**XGB Bottom dumping
**XGC Combination bottom/end/side dumping
**XGE End dumping
**XGR Rotary dumping
**XGS Side dumping
**XGT Covered
*XH Hopper
**XHB Bottom dumping
**XHC Combination bottom/end/side dumping
**XHE End dumping
**XHR Rotary dumping
**XHS Side dumping
**XHT Covered
*XI Foundry
**XIB Bottle/torpedo cars
**XIT Tipper/slag cars
*XL Livestock
**XLA Single deck
**XLC Multiple deck and convertible
**XLH Horse box
*XR Refrigerated
**XRI Ice chilled
**XRM Mechanically chilled
*XS Special
**XSN Novelty
**XSU Unclassified
*XT Tanker
**XTA Domeless
**XTS Single dome
**XTM Multiple dome
*XV Ventilated car/louvred van
**XVG General service
**XVP Produce service

===Class Y: MAPS & SCENARIOS===
*YM Map
*YS Scenario
*YP Profile/Session
*YT Tutorial
*YR Rule
*YD Driver Command
*YH HTML-Asset
*YX Region

===Class Z: TRAIN PARTS===
*ZB Bogie/Truck
*ZE Enginespec
*ZH Hornsound
*ZI Interior
*ZP Pantographs
*ZS Enginesound
*ZX Displacement Map (PaintShed-Template Obsolete)
*ZY (Paintshed-Skin Obsolete)
|}
[[Category:Config Tag|category-class tag]]
{{ORP-bot|category-class tag}}

Category-class

2021-06-21T20:30:03Z

Gdennish: /* Class C: CABEESE */

{{ORP-top}}
==Category-class Tags==
The '''"category-class" tag''' of the [[KIND_TrainzBaseSpec|TrainzBaseSpec]] is the ''key searching parameter'' defining what or how the human content creator meant for the new asset ''to be used and thought about.'' This should not be confused with the [[Category List]], which is a related but distinct topic.
{{UserTip|width=50%|This is a sometimes nebulous and confusing parameter requiring a new user to develop a degree of mental agility, for example, '''a 'house' asset''' might be classified (Coded by some asset creator) as scenery, building, industry, or even something as wildly inappropriate as 'fauna'.}}

The [[KIND]] specification defines which other ({{wp|data type}}) entries'' are needed'' in that particular asset's config.txt file. It is the entry which defines the asset's type, scope, and needs and the very important parameter that tells TRAINZ how to process and render the specific asset item correctly, error check against the standard for the category-class, and render it into {{wp|Three-dimensional space|3D graphics}} models.

Each Trainz asset's category-class tag helps describe the 'intent' of the Asset in the game, as opposed to the internal structure of the Asset. The Content Creators' Guide for Trainz Classics said these classes represent a standardized system for referring to the various types of Locos, Rolling stock, Scenery, Spline and Industry assets. The Category-class classification codes become important to all Trainzers when searching and/or filtering for suitable assets to make into content in a session or route (layout).

;Trainz Base Specification
:(all config.txt files can contain all these entries){{TBS}}
::'''<big><big>Figure: 1 TrainzBaseSpec for quick reference</big></big>'''


==Category-class code notes==
New users should be aware that these codes listed below are not the direct ContentManager.exe category sort by classifications as a simple comparison of lists will reveal, but they do affect what is displayed within such a sort filter selection.
:For example: Set a search filter for ''''''Location>Local + Category>Flora''''''.
: In the base installed content of TRS2006-SP0 this search will yield diverse assets such as the set of {'''Flora''' types: SOME few trees, Betonbridge (1,2,&3 tracks), crop splines, sidewalks, road types}
:but the sort will also list a much larger type group, the set of {Scenery: retaining wall splines (Arkaden...), LOADS of trees and Shrubs including Laubbaum with birds (and sound), grasses (textures?), Logs} and so forth.
In that search you will also find electrified railroad centenary parts and the occasional animal. The result of such a search will be no better in new Trainz versions, which means the new Trainzer needs to cultivate a certain mental agility when searching for suitable content. No one has the man-power, deep pockets, nor copyright authority to systematically fix such foibles. You as a user, can clone such items and change the classification to something more sensible to yourself. That however, is not an asset you can upload to the Download Station without a copyright clearance from the original asset creator. The Trainz community is severe in policing copyrights violations!
{{TrainzTip|These codes when applied by the content creator were in many cases cut and pasted into a new similar asset, in others, the way he or she was using the asset in their current project. In short, they are not definitive, but are indicative... even if it is only of the mental state of the creator at the time of donation to the DLS, or as happens in many cases, a case of translation from a native tounge with a different way of thinking than that of English.}} Rejoice in the positive, they are essentially free and cost you nothing but a bit of puzzlement. Free is good! Having them is better.

==The Category Classes are:==
Class "A" Motive Power
Class "B" Buildings and Structures
Class "C" Cabeese
Class "D" Defence
Class "E" Environment
Class "F" Foliage
Class "G" Ground
Class "H" Mesh
Class "I" Product
Class "J" Texture
Class "L" Light Rail & Monorail
Class "M" Maintenance Of Way
Class "O" Organism
Class "P" Passenger & Mail Cars
Class "R" Railcars & Multiple Unit Sets
Class "S" Splines
Class "T" Track
Class "V" Vehicles
Class "W" Wayside
Class "X" Freight Cars
Class "Y" Maps and Scenarios
Class "Z" Train Parts
::'''Figure 02: Base category-class prefixes'''

Each Category Class may have a number of subcategories as listed below. Please choose the most appropriate Category Class for your item. Select the Class from the [[Content Creator Plus]] drop down menu box - only one class may be selected for an asset.

Selecting a correct Category Class is important since Trainz will allow users to use the Category Class as a sort and selection criteria.

{|
|-valign="top"
|
===Class A: MOTIVE POWER===
*AA Electric Multi-current
*AC AC Electric
*AD DC Electric
*AE Experimental or Special
*AG Gas Turbine
*AH Diesel Hydraulic
*AL Diesel & Diesel Electric
*AM Mammal
*AS Steam Loco & Tender
*AT Steam Tank

===Class B: BUILDINGS & STRUCTURES===
*BB Buildable (Kind Buildable)
*BC Commercial (scenery non-functional)
*BI Industrial (scenery non-functional)
**BIN Industry asset with product processing functionality
*BH Home & Residential (scenery non-functional)
*''Subclass BP: Passenger Station''
**BPF Passenger Station with passenger processing functionality
**BPN Passenger Station (non-functional)
*BR Railway (scenery non-functional)
*BS Special (e.g. military) (scenery non-functional)
*BT Traffic & Streetscape (scenery non-functional)
*BU Utility (incl. Civil buildings) (scenery non-functional)

===Class C: CABEESE / CONSIST / EFFECTS===
*CB Brake van
*CC Caboose
*CLUT Clutter Effect
*CN Consist
*CS ControlSet

===Class D: DEFENCE===
*DA Military motive power
*DE Military experimental & special vehicles
*DP Military equipment - lab & personnel vehicles
*DX Military equipment - freight

===Class E: ENVIRONMENT===
*ES Sky
*EW Water

===Class F: FOLIAGE===
*FC Cactii
*FF Flowers
*FO Orchards & Crops
*FS Shrub
*FT Trees

===Class G: GROUND===
*GA Arid
*GL Lush
*GS Seasonal

===Class H: MESHES===
*HM Mesh

===Class I: PRODUCT===
*IC Container Category
*IP Passenger Category
*IB Bulkload Category
*IL Liquid Category

===Class J: TEXTURES===
*JC Corona
*JI Icon
*JP Particle Effects Texture
*JO Other Texture

===Class L: LIGHT RAIL & MONORAIL===
*LS Articulated train sets
*LT Trolleys, trams & streetcars
*LM Monorail vehicles

===Class M: MAINTENANCE of WAY===
*MA Camp vehicles
*MB Ballast cars
*MC Cranes/lifting
*MD Diagnostic vehicles (e.g. dynamometer)
*ME Instructional vehicles
*MF Fire vehicles
*MI Inspection vehicles
*MT Track vehicles (e.g. tamper)
*MP Snow ploughs
*MS Section cars (e.g. fairmont)
*MX Freight equipment (for MoW traffic)
*MW Weed spray

===Class O: ORGANISM===
*OA Animal Kingdom
*OH Human
**OHD Locomotive Driver

===Class P: PASSENGER & MAIL CARS===
*PA Suburban/short haul (no W.C.)
*PB Baggage cars
*PC Coach/chair cars
*PD Dome cars
*PH Bar/cafeteria cars
*PL Lounge cars
*PM Mail cars
*PO Observation cars
*PP Power cars
*PR Buffet/dining/restaurant cars
*PS Sleeping cars
*PU Special cars (e.g. Gaming Cars)
*PV Private cars
*PX Composite passenger cars

|
===Class R: RAILCARS & MULTIPLE UNIT SETS===
*RA AC electric
*RC DC electric
*RD Diesel & diesel electric
*RH Diesel hydraulic
*RP Petrol
*RS Steam

===Class S: SPLINES===
*SF Fences
*SR Roads
*SP Platforms
*SS Structure
*SV Vegetation

===Class T: TRACK===
*TB Bridge
*TR Rails
*TT Tunnel
*TF Fixed Track

===Class V: VEHICLES===
*VA Air
*VL Land
*VS Sea

===Class W: WAYSIDE===
*WA Signalling
*WS Trackside signage
*WX Accessories

===Class X: FREIGHT CARS===
*XA Auto transporter
**XAA Open sides
**XAB Auto box car
*XB Box car/covered van
**XBD Dangerous goods
**XBG General service
**XBI Insulated
*XF Flat
**XFA Articulated
**XFC Intermodal
**XFD Depressed center
**XFH Heavy duty
**XFM General service
*XG Gondola/open wagon
**XGB Bottom dumping
**XGC Combination bottom/end/side dumping
**XGE End dumping
**XGR Rotary dumping
**XGS Side dumping
**XGT Covered
*XH Hopper
**XHB Bottom dumping
**XHC Combination bottom/end/side dumping
**XHE End dumping
**XHR Rotary dumping
**XHS Side dumping
**XHT Covered
*XI Foundry
**XIB Bottle/torpedo cars
**XIT Tipper/slag cars
*XL Livestock
**XLA Single deck
**XLC Multiple deck and convertible
**XLH Horse box
*XR Refrigerated
**XRI Ice chilled
**XRM Mechanically chilled
*XS Special
**XSN Novelty
**XSU Unclassified
*XT Tanker
**XTA Domeless
**XTS Single dome
**XTM Multiple dome
*XV Ventilated car/louvred van
**XVG General service
**XVP Produce service

===Class Y: MAPS & SCENARIOS===
*YM Map
*YS Scenario
*YP Profile/Session
*YT Tutorial
*YR Rule
*YD Driver Command
*YH HTML-Asset
*YX Region

===Class Z: TRAIN PARTS===
*ZB Bogie/Truck
*ZE Enginespec
*ZH Hornsound
*ZI Interior
*ZP Pantographs
*ZS Enginesound
*ZX Displacement Map (PaintShed-Template Obsolete)
*ZY (Paintshed-Skin Obsolete)
|}
[[Category:Config Tag|category-class tag]]
{{ORP-bot|category-class tag}}

Category-class

2021-06-21T20:28:22Z

Gdennish: /* Class C: CABEESE */

{{ORP-top}}
==Category-class Tags==
The '''"category-class" tag''' of the [[KIND_TrainzBaseSpec|TrainzBaseSpec]] is the ''key searching parameter'' defining what or how the human content creator meant for the new asset ''to be used and thought about.'' This should not be confused with the [[Category List]], which is a related but distinct topic.
{{UserTip|width=50%|This is a sometimes nebulous and confusing parameter requiring a new user to develop a degree of mental agility, for example, '''a 'house' asset''' might be classified (Coded by some asset creator) as scenery, building, industry, or even something as wildly inappropriate as 'fauna'.}}

The [[KIND]] specification defines which other ({{wp|data type}}) entries'' are needed'' in that particular asset's config.txt file. It is the entry which defines the asset's type, scope, and needs and the very important parameter that tells TRAINZ how to process and render the specific asset item correctly, error check against the standard for the category-class, and render it into {{wp|Three-dimensional space|3D graphics}} models.

Each Trainz asset's category-class tag helps describe the 'intent' of the Asset in the game, as opposed to the internal structure of the Asset. The Content Creators' Guide for Trainz Classics said these classes represent a standardized system for referring to the various types of Locos, Rolling stock, Scenery, Spline and Industry assets. The Category-class classification codes become important to all Trainzers when searching and/or filtering for suitable assets to make into content in a session or route (layout).

;Trainz Base Specification
:(all config.txt files can contain all these entries){{TBS}}
::'''<big><big>Figure: 1 TrainzBaseSpec for quick reference</big></big>'''


==Category-class code notes==
New users should be aware that these codes listed below are not the direct ContentManager.exe category sort by classifications as a simple comparison of lists will reveal, but they do affect what is displayed within such a sort filter selection.
:For example: Set a search filter for ''''''Location>Local + Category>Flora''''''.
: In the base installed content of TRS2006-SP0 this search will yield diverse assets such as the set of {'''Flora''' types: SOME few trees, Betonbridge (1,2,&3 tracks), crop splines, sidewalks, road types}
:but the sort will also list a much larger type group, the set of {Scenery: retaining wall splines (Arkaden...), LOADS of trees and Shrubs including Laubbaum with birds (and sound), grasses (textures?), Logs} and so forth.
In that search you will also find electrified railroad centenary parts and the occasional animal. The result of such a search will be no better in new Trainz versions, which means the new Trainzer needs to cultivate a certain mental agility when searching for suitable content. No one has the man-power, deep pockets, nor copyright authority to systematically fix such foibles. You as a user, can clone such items and change the classification to something more sensible to yourself. That however, is not an asset you can upload to the Download Station without a copyright clearance from the original asset creator. The Trainz community is severe in policing copyrights violations!
{{TrainzTip|These codes when applied by the content creator were in many cases cut and pasted into a new similar asset, in others, the way he or she was using the asset in their current project. In short, they are not definitive, but are indicative... even if it is only of the mental state of the creator at the time of donation to the DLS, or as happens in many cases, a case of translation from a native tounge with a different way of thinking than that of English.}} Rejoice in the positive, they are essentially free and cost you nothing but a bit of puzzlement. Free is good! Having them is better.

==The Category Classes are:==
Class "A" Motive Power
Class "B" Buildings and Structures
Class "C" Cabeese
Class "D" Defence
Class "E" Environment
Class "F" Foliage
Class "G" Ground
Class "H" Mesh
Class "I" Product
Class "J" Texture
Class "L" Light Rail & Monorail
Class "M" Maintenance Of Way
Class "O" Organism
Class "P" Passenger & Mail Cars
Class "R" Railcars & Multiple Unit Sets
Class "S" Splines
Class "T" Track
Class "V" Vehicles
Class "W" Wayside
Class "X" Freight Cars
Class "Y" Maps and Scenarios
Class "Z" Train Parts
::'''Figure 02: Base category-class prefixes'''

Each Category Class may have a number of subcategories as listed below. Please choose the most appropriate Category Class for your item. Select the Class from the [[Content Creator Plus]] drop down menu box - only one class may be selected for an asset.

Selecting a correct Category Class is important since Trainz will allow users to use the Category Class as a sort and selection criteria.

{|
|-valign="top"
|
===Class A: MOTIVE POWER===
*AA Electric Multi-current
*AC AC Electric
*AD DC Electric
*AE Experimental or Special
*AG Gas Turbine
*AH Diesel Hydraulic
*AL Diesel & Diesel Electric
*AM Mammal
*AS Steam Loco & Tender
*AT Steam Tank

===Class B: BUILDINGS & STRUCTURES===
*BB Buildable (Kind Buildable)
*BC Commercial (scenery non-functional)
*BI Industrial (scenery non-functional)
**BIN Industry asset with product processing functionality
*BH Home & Residential (scenery non-functional)
*''Subclass BP: Passenger Station''
**BPF Passenger Station with passenger processing functionality
**BPN Passenger Station (non-functional)
*BR Railway (scenery non-functional)
*BS Special (e.g. military) (scenery non-functional)
*BT Traffic & Streetscape (scenery non-functional)
*BU Utility (incl. Civil buildings) (scenery non-functional)

===Class C: CABEESE===
*CB Brake van
*CC Caboose
*CN Consist

===Class D: DEFENCE===
*DA Military motive power
*DE Military experimental & special vehicles
*DP Military equipment - lab & personnel vehicles
*DX Military equipment - freight

===Class E: ENVIRONMENT===
*ES Sky
*EW Water

===Class F: FOLIAGE===
*FC Cactii
*FF Flowers
*FO Orchards & Crops
*FS Shrub
*FT Trees

===Class G: GROUND===
*GA Arid
*GL Lush
*GS Seasonal

===Class H: MESHES===
*HM Mesh

===Class I: PRODUCT===
*IC Container Category
*IP Passenger Category
*IB Bulkload Category
*IL Liquid Category

===Class J: TEXTURES===
*JC Corona
*JI Icon
*JP Particle Effects Texture
*JO Other Texture

===Class L: LIGHT RAIL & MONORAIL===
*LS Articulated train sets
*LT Trolleys, trams & streetcars
*LM Monorail vehicles

===Class M: MAINTENANCE of WAY===
*MA Camp vehicles
*MB Ballast cars
*MC Cranes/lifting
*MD Diagnostic vehicles (e.g. dynamometer)
*ME Instructional vehicles
*MF Fire vehicles
*MI Inspection vehicles
*MT Track vehicles (e.g. tamper)
*MP Snow ploughs
*MS Section cars (e.g. fairmont)
*MX Freight equipment (for MoW traffic)
*MW Weed spray

===Class O: ORGANISM===
*OA Animal Kingdom
*OH Human
**OHD Locomotive Driver

===Class P: PASSENGER & MAIL CARS===
*PA Suburban/short haul (no W.C.)
*PB Baggage cars
*PC Coach/chair cars
*PD Dome cars
*PH Bar/cafeteria cars
*PL Lounge cars
*PM Mail cars
*PO Observation cars
*PP Power cars
*PR Buffet/dining/restaurant cars
*PS Sleeping cars
*PU Special cars (e.g. Gaming Cars)
*PV Private cars
*PX Composite passenger cars

|
===Class R: RAILCARS & MULTIPLE UNIT SETS===
*RA AC electric
*RC DC electric
*RD Diesel & diesel electric
*RH Diesel hydraulic
*RP Petrol
*RS Steam

===Class S: SPLINES===
*SF Fences
*SR Roads
*SP Platforms
*SS Structure
*SV Vegetation

===Class T: TRACK===
*TB Bridge
*TR Rails
*TT Tunnel
*TF Fixed Track

===Class V: VEHICLES===
*VA Air
*VL Land
*VS Sea

===Class W: WAYSIDE===
*WA Signalling
*WS Trackside signage
*WX Accessories

===Class X: FREIGHT CARS===
*XA Auto transporter
**XAA Open sides
**XAB Auto box car
*XB Box car/covered van
**XBD Dangerous goods
**XBG General service
**XBI Insulated
*XF Flat
**XFA Articulated
**XFC Intermodal
**XFD Depressed center
**XFH Heavy duty
**XFM General service
*XG Gondola/open wagon
**XGB Bottom dumping
**XGC Combination bottom/end/side dumping
**XGE End dumping
**XGR Rotary dumping
**XGS Side dumping
**XGT Covered
*XH Hopper
**XHB Bottom dumping
**XHC Combination bottom/end/side dumping
**XHE End dumping
**XHR Rotary dumping
**XHS Side dumping
**XHT Covered
*XI Foundry
**XIB Bottle/torpedo cars
**XIT Tipper/slag cars
*XL Livestock
**XLA Single deck
**XLC Multiple deck and convertible
**XLH Horse box
*XR Refrigerated
**XRI Ice chilled
**XRM Mechanically chilled
*XS Special
**XSN Novelty
**XSU Unclassified
*XT Tanker
**XTA Domeless
**XTS Single dome
**XTM Multiple dome
*XV Ventilated car/louvred van
**XVG General service
**XVP Produce service

===Class Y: MAPS & SCENARIOS===
*YM Map
*YS Scenario
*YP Profile/Session
*YT Tutorial
*YR Rule
*YD Driver Command
*YH HTML-Asset
*YX Region

===Class Z: TRAIN PARTS===
*ZB Bogie/Truck
*ZE Enginespec
*ZH Hornsound
*ZI Interior
*ZP Pantographs
*ZS Enginesound
*ZX Displacement Map (PaintShed-Template Obsolete)
*ZY (Paintshed-Skin Obsolete)
|}
[[Category:Config Tag|category-class tag]]
{{ORP-bot|category-class tag}}

HowTo/Build a cab interior

2021-06-17T04:54:00Z

Gdennish:

Trainz uses an [[KIND_Interior|interior]] object to represent a locomotive cab, or view from another vehicle, e.g. a passenger coach, brake van or caboose. Interiors can also be attached to some non-train assets. For this howto, I am going to assume that we are creating a traincar interior, and focus primarily on a cab interior for a diesel or electric locomotive.

=Basic structure=

The basic structure of a cab is quite similar to a number of different assets. You will have a main mesh with a number of attached sub-meshes, which are arranged using a [[%22mesh-table%22_container_(interior_version)|mesh-table]].

The main cab mesh typically consists of the interior walls, roof and floor of the cab, the control desk or stand, all furniture or other static objects visible inside the cab, and also all parts of the locomotive exterior that are visible from inside the cab - e.g. the top of any projecting nose below the cab windows. Remember to consider the sightlines out of rear windows too for visible bodywork panels - the user can move around the cab and rotate the camera to any angle. Users are not restricted to looking forward out of the front windows only.

=Artwork considerations=

There are some differences in style between the construction of an interior object and a typical trainz object.

Except in very specific circumstances, there will not be more than one interior object in existence at any time, and that interior is always viewed from very close range - the user is inside it. Because of this, interiors are typically modelled with a high polygon count and with high resolution textures, to give an impressive visual feel. LOD is not used, as the user never gets far enough away from the interior for LOD techniques to have worthwhile benefit. However, LOD techniques may be ideal in a case of a passenger wagon with high polygon chair models.

Trainz lights interior objects differently to map objects like buildings and other scenery - the main illumination is ambient, not directional. (A steam loco does have a directional light coming from the firebox, but a diesel or electric cab typically has no directional light inside, and relies entirely on ambient illumination).

With ambient illumination, effects such as normal and specular mapping do not have much (if any) effect. Because of this, more effort needs to be put into the diffuse texture for a cab interior than would normally be applied to Trainz objects. Drawing or baking shadows and other effects into the diffuse textures is required to produce a nice looking cab interior.

An example cab would be the [[File:PB_interior.rar]]

=A basic config file=

The minimal required config for an interior to show in-game is:

kind interior
kuid <kuid2:YOUR:KUID:HERE>
trainz-build 2.9
username "Your interior name here"
category-class ZI

mesh-table
{
default
{
mesh "your_interior_mesh_name.im"
auto-create 1
}
}

Note: There are also other base tags that should be added that are common to all asset types - e.g. the download station will require a valid thumbnails container before the asset can be uploaded. See the documentation for [[KIND TrainzBaseSpec]] for details of tags which apply to all trainz assets. Depending on which Trainz version you have and which trainz-build number you have specified, some of these may be required - content manager will tell you what is required, listing missing tags as errors.

==camera positions==

If we load a cab up with that config file, we will note that the view is not particularly appealing. Chances are we're right down near the floor. To fix this, we need to define some default positions for camera views. This is done with the [[%22cameralist%22_Container|cameralist container]] and the [[KIND_Interior#cameradefault|cameradefault]] tag.
Add the following to your config.txt file:

cameralist
{
camera0 0,0,2,0,0
}

cameradefault 0

The cameralist container can contain any number of cameras, but they must be numbered sequentially and start at zero.

The five numbers are the X, Y and Z coordinates of the camera in metres relative to the 0,0,0 point of the interior mesh, and the Yaw and Pitch in radians. Luckily you don't have to work these values out from scratch - add the line "-freeintcam" to your trainzoptions.txt file, and you can move the camera about in the cab with the mouse and keyboard, and the precise position will be displayed in the bottom right corner.

When you have found a position you like, write the numbers down. When you've got a good selection of positions recorded, add them to the cameralist container.

You may wish to return to this and tweak the values later once all the controls are in place - but it's handy to have a good starting position for the camera while testing.

=Cab controls=

A locomotive cab interior needs working cab controls. What fun would sitting in the drivers seat be without being able to pull on the levers, change the switches, and watch the gauges and dials move?

The moving part of each lever, switch, gauge or dial is created as a separate mesh, which is then attached to the cab with an attachment point. (The static part, e.g. guide rails for levers, should be part of the cab mesh itself).

==Lever==

The lever is the basic input device in a cab. It is based on rotational movement, and any object that requires rotational movement (e.g. a wheel or ring) can be implemented as a lever.

If you actually want linear movement, you can still use a lever - just move the attachment point a long way away - e.g. 10 or 20 metres away from the control. The resulting small arc will not be noticable over the length of movement. As an example, sliding windows in Trainz cabs have been implemented as levers "attached" something like 10 or 20 metres out to the side of the vehicle for a long time. (The exception to this is a horn pull rope - trainz provides a control specifically for this purpose).

You will need to create the lever in your modelling program aligned correctly - the rotation needs to be around the Z axis, and main part of the object will point along the Y axis.

When adding the attachment point to the main mesh, align it so the Z axis is the axis of rotation. It is common to point the Y axis at the default position - e.g. levers in the 'off' or 'neutral' position, and needles pointing to zero. This is not strictly required, as the range of movement can be adjusted at both ends, but it provides a handy reference when creating the config file.

[[File:BasicLeverSetup.png|350px|thumb|An example of a lever being used as a signboard cover.]]

It is worth noting that you can reuse a mesh for multiple attachments. This is particularly useful for switches, as identical appearance switches are often used repeatedly in a cab for different purposes.

===Throttle Lever===

A good example of a standard lever in use is a locomotive throttle control. A typical US diesel throttle has 9 notched positions (from 0 to 8 inclusive).

As noted above, the lever is created in the modelling package so it points along the Y axis and the axis of rotation is along the Z axis. The attachment point is added to the cab interior mesh at the correct position, and rotated so the Z axis is aligned with the axis of rotation, and the Y axis points to the default position.

Now we need to add an entry to the config file to add our throttle lever.

Into the mesh table, add an entry like this:

throttle_lever
{
kind "lever"
mesh "throttle_lever.im"
att "a.throttle_lever"
limits 0,8
angles 0,1.57
notches 0,0.125,0.25,0.375,0.5,0.625,0.75,0.875,1
notchheight 1,2,2,2,2,2,2,2,1
radius 0.35
auto-create 1
att-parent "default"
}

... remember to set your attachment point and mesh name correctly.

The 'angles' line defines how far the control rotates. It is in radians - there are 2 x Pi (6.28) radians in a complete circle. My default of 1.57 will give you about 90 degrees of rotation, in the positive direction. Adjust this number to get the control to rotate the correct amount. You should be able to work out the number you need in your modelling program by using the rotate tool on the attachment point, and recording the amount of rotation required to move to the intended maximum location. It should not require significant trial and error.

The 'radius' line defines the position of the notch position overlay and the text label. It is in metres. If the overlay is too close in, increase this number. If it is too far out, decrease it.

If the lever is the wrong way round (notch 8 is at the wrong end), swap the numbers in the 'angles' tag over, so the higher one is first.

If the lever moves the wrong way when you drag it with the mouse (i.e. it goes left in response to a right drag), add the line:
mousespeed -1
This will invert the mouse movement.

The fact we called this lever "throttle_lever" means it will be used to control the throttle by the default cab script.

So what happens if we wanted a different number of notches? Below is an example of a throttle which has 22 notches. The second value in the 'limits' tag has been edited to return up to notch 22, and more entries have been added to the 'notches' and 'notchheight' tags:

throttle_lever
{
kind "lever"
mesh "throttle_lever.im"
att "a.throttle_lever"
limits 0,22
angles 0,0.94
notches 0,0.045,0.091,0.136,0.182,0.227,0.273,0.318,0.364,0.409,0.455,0.5,0.545,0.591,0.636,0.682,0.727,0.773,0.818,0.864,0.909,0.955,1
notchheight 1,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,1
radius 0.35
auto-create 1
att-parent "default"
}

===Reverser Lever===

The reverser lever is created in a similar manner to throttle lever. The mesh table entry for this will look like:

reverser_lever
{
kind "lever"
mesh "reverser_lever.im"
att "a.reverser_lever"
limits 0,2
angles -0.79,0.79
notches 0,0.5,1
notchheight 1,1,1
radius 0.25
auto-create 1
att-parent "default"
}

In this case, because the 'angles' entry has a range both positive and negative, the lever can move in both directions relative to the attachment point. The game will set the default position to neutral (1), so if you've lined up your attachment point at one end, don't worry - you can use angles which range from zero if you need to.

===Train Air Brake Lever===

There are two types of train air brake lever. A given locomotive only has one type - the brakes are either require manual lapping or are self-lapping. Use the appropriate name and configuration for the loco you are modelling.

====Manual Lapped Brakes====

The manual train brake lever has five positions numbered from zero to four, each one representing a different function. Those functions are Release, Lap, Application, Emergency and Handle Off respectively.

A lever for a manual lap train air brake is defined as follows:

trainbrakelap_lever
{
kind "lever"
mesh "train_brake_lap_lever.im"
att "a.train_brake_lap_lever"
limits 0,4
angles 0,0.94
notches 0,0.25,0.5,0.75,1
notchheight 1,1,1,1,1
radius 0.25
att-parent "default"
auto-create 1
}

In this case, the attachment for the lever has been created in the 'release' position. If it had been created in the 'handle off' position, the angle tag would have been more like:

angles -0.94,0

====Self Lapping Brakes====

A self lapping trainbrake lever has a number of primary notches similar to the manual lap train brake lever. However, instead of a 'lap' and 'apply' position, it has a grade of application between the 'initial' and 'full application' positions. An example of a self-lapping brake handle is this one:

trainbrake_lever
{
kind "lever"
mesh "train_brake_lever.im"
att "a.train_brake_lever"
limits 0,4
angles 0,0.94
notches 0,0.25,0.27,0.29,0.31,0.33,0.35,0.37,0.39,0.41,0.43,0.45,0.47,0.49,0.5,0.75,1
notchheight 1,1,2,2,2,2,2,2,2,2,2,2,2,2,1,1,1
radius 0.25
att-parent "default"
auto-create 1
}

In this case, there are 14 possible levels of brake application - initial at 0.25, 12 intermediate levels, and full application at 0.5. There is no restriction on the number of intermediate levels - if you are modelling a prototype brake handle with a specific number, you may create precisely that number of notches and arrange them between 0.25 and 0.5 as required.

===Combined throttle brake lever===

There is also another control option - a combined throttle brake lever. This type of control is often found on multiple unit trains. This control is split into two halves. The first half of the movement is an inverted throttle - i.e. max power at zero, no power at 0.5. The second half is an auto lapped train brake application, with 0.5 as release, and 1.0 as emergency. An example of how to configure a combined throttle and brake lever is below:

throttle_brake_lever
{
kind "lever"
mesh "throttle_brake_handle.im"
auto-create 1
att "a.throttle_brake_handle"
limits 0,16
angles 0.94,-0.94
notches 0,0.0625,0.125,0.1875,0.25,0.3125,0.375,0.4375,0.5,0.5625,0.625,0.6875,0.8125,0.75,0.875,0.9375,1
notchheight 1,2,2,2,2,2,2,2,1,2,2,2,2,2,2,2,1
att-parent "default"
radius 0.12
invert 1
}

Unfortunately, trains that use this type of control generally use blended and/or EP brakes, and this control uses the standard Trainz air brake, which operates in a distinctly different manner, and as a result, can feel very wrong for this control type. (See the section on scripting controls for how a better combined brake and throttle lever may be implemented).

==Pull lever==

This is a sprung lever. You pull on this lever to activate it, and when you let it go, it returns to the original position. This kind of action is commonly associated with a locomotive horn, and this is what I am using as an example:

horn
{
kind "pulllever"
mesh "horn.im"
att "a.horn"
auto-create 1
angles 0,-0.55
limits 0,1
mousespeed -1
radius -0.02
notches 0,1
notchheight 0,0
}

==Switch==

A switch is a lever that does not require the user to 'drag' it with the mouse - it operates on a click only. This is used for smaller controls that are 'on' or 'off', and do not have intermediate positions. Parameters are much like they are for a 'lever', only a switch should only have two notches - on and off.

Unfortunately, some things you'd normally associate with being a 'switch' (e.g. the headlight switch control) require mulitple positions, and will need to remain as a 'lever' in order to allow the player to set the correct position for the control.

An example of a switch would be:

switch1
{
kind "switch"
mesh "switch.im"
att "a.switch1"
limits 0,1
angles 1.4,0
notches 0,1
notchheight 0,0
}

As 'switch' was introduced in TS2009 SP2, interiors that use kind 'switch' controls should be marked trainz-build 3.1 or later in the config.txt.

==button==

A button is a momentary contact press-and-hold button. This is a brand new control added for TS12 patch 2, released end of june 2011. Content using this feature should have trainz-build 3.6 or later in the config.txt.

Finally this brings Trainz the "click to press", "hold to hold pressed", "let go to release" style momentary pushbutton.

button1
{
kind "button"
mesh "switch.im"
att "a.switch1"
limits 0,1
angles 0,0.1
notches 0,1
notchheight 0,0
}

==Pull rope==

This is a linear pull rope control. Unlike the rotating controls discussed previously, this control type moves the mesh linearly along the Z axis of the attachment. It behaves as you would expect from a suspended rope - click and drag to pull, let go to release. It will spring back to it's initial position in the same manner as kind 'pulllever'.

[[File:Pullropetype.png|800px]]

horn
{
kind "pullrope"
mesh "horn_rope.im"
att "a.horn"
limits 0,1
angles 0.1,0
notches 0,1
notchheight 0,0
mousespeed -1
}

==needle==

A needle is the standard Trainz output device. Like the lever, it is based on rotational movement, and any gauge, dial, or other output device based on rotational movement can be implemented. Any static part of the gauge should be modelled as part of the cab, and only the moving part as part of the needle. Like the lever, the rotation will be around the Z axis of the needle, and it is common practice to point the point of the needle along the Y axis. Cabs often have a number of similar gauges, and re-using the same needle repeatedly in each gauge is a lot easier if this setup is done consistently.

As an example of a needle, here is a basic speedometer:

speedo_needle
{
kind "needle"
auto-create 1
mesh "speedo_needle.im"
att "a.speedo_needle"
limits 0,67.056
angles 0,4.712
}

The default cab script knows to move the "speedo_needle" object as the train speed changes, so simply by naming this control "speedo_needle", it has become a speedometer.

For a speedo, the 'limits' values will be the minimum and maximum reportable speed in m/s.

Creating other rotational gauges is similar - refer to the [[%22mesh-table%22_container_(interior_version)|mesh-table (interior version)]] documentation to see all the different values that Trainz can show by default.

==light==

Another common type of control is a light. This is created simply as a textured plane, which is either hidden or shown to represent light off or light on. It is attached as any other standard mesh attachment would be - there is no rotation to worry about here.

wheelslip_light
{
kind "light"
mesh "wheelslip_light.im"
att "a.wheelslip_light"
}

This light will be used to show wheelslip in a default cab.

==animated-lever==

If you want more complex movement than simple rotation, you have the option of animating the lever and using kind 'animated-lever'. This will use an animation you create in your modelling program to move the control about. An example of this is visible in the MN ACMU cab. (I've reduced the number of notches here for readability - the real one has 32, not 16).

throttle_lever
{
mesh "throttlehandle.im"
anim "throttlehandle.kin"
auto-create 1
att "a.throttlelever"
limits 0,16
notches 0,0.0625,0.125,0.1875,0.25,0.3125,0.375,0.4375,0.5,0.5625,0.625,0.6875,0.8125,0.75,0.875,0.9375,1
notchheight 1,2,2,2,2,2,2,2,1,2,2,2,2,2,2,2,1
att-parent "default"
kind "animated-lever"
test-collisions 0
mousespeed 1
}

Where the standard lever is rotated between it's angles to move from notch to notch, the animated-lever has it's animation played to the corresponding frame.

===collision-proxy===

Animated levers can be hard to grab hold of compared to normal levers. To get around this, an invisible mesh is used to show the game the range of movement the control has, and to allow the user to grab the lever more easily. This example again comes from the MN ACMU cab:

throttle-collision-box
{
mesh "throttlehandleselection.im"
att-parent "throttle_lever"
att "a.selection_box"
auto-create 1
kind "collision-proxy"
opacity 0
collision-parent "throttle_lever"
}

==animated-dial==

If you've been paying attention to levers, needles and animated levers, I think you can guess where we are going with this one. This is an animated needle. Instead of rotating between the angles specified, it plays it's animation to the relevant frame to show the value. Use this when what you want to achieve can't be done with simple rotational movement.

(Example usage for this control to follow).

==digital-dial==

Some locomotives use a digital readout rather than analogue dials.

Trainz has two control kinds to support digital displays - one for speed units, and one for pressure units. Instead of angles of movement, these both have some font specific options to configure how the digits appear. In both cases, the Y axis of the attachment point should be pointing upward to signify the up direction of the font.

"font" defines the typeface. For a list of valid typefaces, see the [[%22mesh-table%22_container_(interior_version)#font|mesh-table (interior version)]] documentation. Generally this follows closely with a number of default windows font names.

"fontsize" defines the size of the font. The default value for this is 0.02, and this is a pretty respectable size display.

"fontcolor" defines the RGB color of the text. Each value is a floating point number between 0.0 and 1.0.

"mesh" normally would display the mesh used for the needle. In the case of digital dials, they are not used, but the tag is still required. Any mesh can be used here; using an existing needle mesh would be fine.

===digital-dial-spd===

For a speedometer (or any other gauge that shows units in speed, e.g. a speed limit display), use kind 'digital-dial-spd'.

An example speedometer using this kind would be declared as:

speedo_needle2
{
kind "digital-dial-spd"
mesh "brake_needle.im"
att "a.digispeedo"
limits 0,55
font "arial"
fontsize 0.01
fontcolor 196,196,246
auto-create 1
}

===digital-dial-prs===

For a display using pressure units, use digital-dial-prs. This is a digital brake pipe pressure gauge:

bptrainbrakepipe_needle2
{
kind "digital-dial-prs"
mesh "brake_needle.im"
att "a.trainpipe_pressure"
limits 0,55
font "arial"
fontsize 0.01
fontcolor 0.0,1.0,0.0
auto-create 1
}

[[File:Digispeedoreference.png|An example of digital needles being used for pressure and speed.]]

==firebox==

The firebox control is a special kind to implement the fire of a steam locomotive.

(Further information about this specific control to follow).

Note: Some steam cab interior models use the firebox, fireglow and burning coal effects found in the Auran PB15 cab interior. This can cause quite severe flickering effects in some models The intensity of flickering varies on the textures used and can be attenuated by use of darker colours. The flickering can be eliminated by not using the firebox effect. The fireglow and burning coal (coal) effects are OK.

'''Note: This feature does not work currently in T:ANE and TRS19.
'''

You can, of course, always make your own.

=Scripting additional behaviour in a cab=

A lot can be achieved in Trainz purely by naming the controls correctly and relying on Trainz default cab scripts to make them work. A quite reasonable cab can be made for many locomotives without having to do any scripting whatsoever.

However, a lot more realism can be achieved by scripting the cab. Additional features can be added beyond what Trainz supports, including new types of controls, or extended behaviour on existing controls.

The first thing to consider when looking at scripting a cab, is "is the cab the best place for this feature?". A cab is not a persistent asset, which means it can go away at any point. When it's gone, it isn't running it's script. Consequently, it is a bad place for any persistent or time based logic - it should only be used to script the immediate behaviour of the controls. Anything beyond this should be implemented the vehicle itself or possibly a script library, both of which are more persistent objects.

If all you want to achieve is to add some simple extra features (e.g. a display of signal aspects within the cab), you can derive from the trainz standard classes, and inherit the default behaviour when adding your new behaviour. This means you can concentrate on just your extra feature, and don't have to worry about making existing functionality work.

If you want to do something a little more advanced (e.g. change the behaviour of the throttle and/or brake controllers), then you are probably best deriving your cab script from the 'cabin' class, ignoring the default cab scripts, and implementing your required behaviour from scratch. This gives you a lot more control, but you do need to do more yourself.

For some examples of the first route, have a look at the MN cabs - the M7 or the ACMU are good examples. Both have a cab signal repeater implemented in the cab interior script, and use the base functionality for almost everything else.

-~= To Be Continued... =~-

==Return to Index==

[[HowToGuides|<< How To Guides]]

[[Category:How-to guides]]

HowTo/Build a cab interior

2021-06-17T04:52:13Z

Gdennish:

Trainz uses an [[KIND_Interior|interior]] object to represent a locomotive cab, or view from another vehicle, e.g. a passenger coach, brake van or caboose. Interiors can also be attached to some non-train assets. For this howto, I am going to assume that we are creating a traincar interior, and focus primarily on a cab interior for a diesel or electric locomotive.

=Basic structure=

The basic structure of a cab is quite similar to a number of different assets. You will have a main mesh with a number of attached sub-meshes, which are arranged using a [[%22mesh-table%22_container_(interior_version)|mesh-table]].

The main cab mesh typically consists of the interior walls, roof and floor of the cab, the control desk or stand, all furniture or other static objects visible inside the cab, and also all parts of the locomotive exterior that are visible from inside the cab - e.g. the top of any projecting nose below the cab windows. Remember to consider the sightlines out of rear windows too for visible bodywork panels - the user can move around the cab and rotate the camera to any angle. Users are not restricted to looking forward out of the front windows only.

=Artwork considerations=

There are some differences in style between the construction of an interior object and a typical trainz object.

Except in very specific circumstances, there will not be more than one interior object in existence at any time, and that interior is always viewed from very close range - the user is inside it. Because of this, interiors are typically modelled with a high polygon count and with high resolution textures, to give an impressive visual feel. LOD is not used, as the user never gets far enough away from the interior for LOD techniques to have worthwhile benefit. However, LOD techniques may be ideal in a case of a passenger wagon with high polygon chair models.

Trainz lights interior objects differently to map objects like buildings and other scenery - the main illumination is ambient, not directional. (A steam loco does have a directional light coming from the firebox, but a diesel or electric cab typically has no directional light inside, and relies entirely on ambient illumination).

With ambient illumination, effects such as normal and specular mapping do not have much (if any) effect. Because of this, more effort needs to be put into the diffuse texture for a cab interior than would normally be applied to Trainz objects. Drawing or baking shadows and other effects into the diffuse textures is required to produce a nice looking cab interior.

An example cab would be the [[File:PB_interior.rar]]

=A basic config file=

The minimal required config for an interior to show in-game is:

kind interior
kuid <kuid2:YOUR:KUID:HERE>
trainz-build 2.9
username "Your interior name here"
category-class ZI

mesh-table
{
default
{
mesh "your_interior_mesh_name.im"
auto-create 1
}
}

Note: There are also other base tags that should be added that are common to all asset types - e.g. the download station will require a valid thumbnails container before the asset can be uploaded. See the documentation for [[KIND TrainzBaseSpec]] for details of tags which apply to all trainz assets. Depending on which Trainz version you have and which trainz-build number you have specified, some of these may be required - content manager will tell you what is required, listing missing tags as errors.

==camera positions==

If we load a cab up with that config file, we will note that the view is not particularly appealing. Chances are we're right down near the floor. To fix this, we need to define some default positions for camera views. This is done with the [[%22cameralist%22_Container|cameralist container]] and the [[KIND_Interior#cameradefault|cameradefault]] tag.
Add the following to your config.txt file:

cameralist
{
camera0 0,0,2,0,0
}

cameradefault 0

The cameralist container can contain any number of cameras, but they must be numbered sequentially and start at zero.

The five numbers are the X, Y and Z coordinates of the camera in metres relative to the 0,0,0 point of the interior mesh, and the Yaw and Pitch in radians. Luckily you don't have to work these values out from scratch - add the line "-freeintcam" to your trainzoptions.txt file, and you can move the camera about in the cab with the mouse and keyboard, and the precise position will be displayed in the bottom right corner.

When you have found a position you like, write the numbers down. When you've got a good selection of positions recorded, add them to the cameralist container.

You may wish to return to this and tweak the values later once all the controls are in place - but it's handy to have a good starting position for the camera while testing.

=Cab controls=

A locomotive cab interior needs working cab controls. What fun would sitting in the drivers seat be without being able to pull on the levers, change the switches, and watch the gauges and dials move?

The moving part of each lever, switch, gauge or dial is created as a separate mesh, which is then attached to the cab with an attachment point. (The static part, e.g. guide rails for levers, should be part of the cab mesh itself).

==Lever==

The lever is the basic input device in a cab. It is based on rotational movement, and any object that requires rotational movement (e.g. a wheel or ring) can be implemented as a lever.

If you actually want linear movement, you can still use a lever - just move the attachment point a long way away - e.g. 10 or 20 metres away from the control. The resulting small arc will not be noticable over the length of movement. As an example, sliding windows in Trainz cabs have been implemented as levers "attached" something like 10 or 20 metres out to the side of the vehicle for a long time. (The exception to this is a horn pull rope - trainz provides a control specifically for this purpose).

You will need to create the lever in your modelling program aligned correctly - the rotation needs to be around the Z axis, and main part of the object will point along the Y axis.

When adding the attachment point to the main mesh, align it so the Z axis is the axis of rotation. It is common to point the Y axis at the default position - e.g. levers in the 'off' or 'neutral' position, and needles pointing to zero. This is not strictly required, as the range of movement can be adjusted at both ends, but it provides a handy reference when creating the config file.

[[File:BasicLeverSetup.png|350px|thumb|An example of a lever being used as a signboard cover.]]

It is worth noting that you can reuse a mesh for multiple attachments. This is particularly useful for switches, as identical appearance switches are often used repeatedly in a cab for different purposes.

===Throttle Lever===

A good example of a standard lever in use is a locomotive throttle control. A typical US diesel throttle has 9 notched positions (from 0 to 8 inclusive).

As noted above, the lever is created in the modelling package so it points along the Y axis and the axis of rotation is along the Z axis. The attachment point is added to the cab interior mesh at the correct position, and rotated so the Z axis is aligned with the axis of rotation, and the Y axis points to the default position.

Now we need to add an entry to the config file to add our throttle lever.

Into the mesh table, add an entry like this:

throttle_lever
{
kind "lever"
mesh "throttle_lever.im"
att "a.throttle_lever"
limits 0,8
angles 0,1.57
notches 0,0.125,0.25,0.375,0.5,0.625,0.75,0.875,1
notchheight 1,2,2,2,2,2,2,2,1
radius 0.35
auto-create 1
att-parent "default"
}

... remember to set your attachment point and mesh name correctly.

The 'angles' line defines how far the control rotates. It is in radians - there are 2 x Pi (6.28) radians in a complete circle. My default of 1.57 will give you about 90 degrees of rotation, in the positive direction. Adjust this number to get the control to rotate the correct amount. You should be able to work out the number you need in your modelling program by using the rotate tool on the attachment point, and recording the amount of rotation required to move to the intended maximum location. It should not require significant trial and error.

The 'radius' line defines the position of the notch position overlay and the text label. It is in metres. If the overlay is too close in, increase this number. If it is too far out, decrease it.

If the lever is the wrong way round (notch 8 is at the wrong end), swap the numbers in the 'angles' tag over, so the higher one is first.

If the lever moves the wrong way when you drag it with the mouse (i.e. it goes left in response to a right drag), add the line:
mousespeed -1
This will invert the mouse movement.

The fact we called this lever "throttle_lever" means it will be used to control the throttle by the default cab script.

So what happens if we wanted a different number of notches? Below is an example of a throttle which has 22 notches. The second value in the 'limits' tag has been edited to return up to notch 22, and more entries have been added to the 'notches' and 'notchheight' tags:

throttle_lever
{
kind "lever"
mesh "throttle_lever.im"
att "a.throttle_lever"
limits 0,22
angles 0,0.94
notches 0,0.045,0.091,0.136,0.182,0.227,0.273,0.318,0.364,0.409,0.455,0.5,0.545,0.591,0.636,0.682,0.727,0.773,0.818,0.864,0.909,0.955,1
notchheight 1,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,1
radius 0.35
auto-create 1
att-parent "default"
}

===Reverser Lever===

The reverser lever is created in a similar manner to throttle lever. The mesh table entry for this will look like:

reverser_lever
{
kind "lever"
mesh "reverser_lever.im"
att "a.reverser_lever"
limits 0,2
angles -0.79,0.79
notches 0,0.5,1
notchheight 1,1,1
radius 0.25
auto-create 1
att-parent "default"
}

In this case, because the 'angles' entry has a range both positive and negative, the lever can move in both directions relative to the attachment point. The game will set the default position to neutral (1), so if you've lined up your attachment point at one end, don't worry - you can use angles which range from zero if you need to.

===Train Air Brake Lever===

There are two types of train air brake lever. A given locomotive only has one type - the brakes are either require manual lapping or are self-lapping. Use the appropriate name and configuration for the loco you are modelling.

====Manual Lapped Brakes====

The manual train brake lever has five positions numbered from zero to four, each one representing a different function. Those functions are Release, Lap, Application, Emergency and Handle Off respectively.

A lever for a manual lap train air brake is defined as follows:

trainbrakelap_lever
{
kind "lever"
mesh "train_brake_lap_lever.im"
att "a.train_brake_lap_lever"
limits 0,4
angles 0,0.94
notches 0,0.25,0.5,0.75,1
notchheight 1,1,1,1,1
radius 0.25
att-parent "default"
auto-create 1
}

In this case, the attachment for the lever has been created in the 'release' position. If it had been created in the 'handle off' position, the angle tag would have been more like:

angles -0.94,0

====Self Lapping Brakes====

A self lapping trainbrake lever has a number of primary notches similar to the manual lap train brake lever. However, instead of a 'lap' and 'apply' position, it has a grade of application between the 'initial' and 'full application' positions. An example of a self-lapping brake handle is this one:

trainbrake_lever
{
kind "lever"
mesh "train_brake_lever.im"
att "a.train_brake_lever"
limits 0,4
angles 0,0.94
notches 0,0.25,0.27,0.29,0.31,0.33,0.35,0.37,0.39,0.41,0.43,0.45,0.47,0.49,0.5,0.75,1
notchheight 1,1,2,2,2,2,2,2,2,2,2,2,2,2,1,1,1
radius 0.25
att-parent "default"
auto-create 1
}

In this case, there are 14 possible levels of brake application - initial at 0.25, 12 intermediate levels, and full application at 0.5. There is no restriction on the number of intermediate levels - if you are modelling a prototype brake handle with a specific number, you may create precisely that number of notches and arrange them between 0.25 and 0.5 as required.

===Combined throttle brake lever===

There is also another control option - a combined throttle brake lever. This type of control is often found on multiple unit trains. This control is split into two halves. The first half of the movement is an inverted throttle - i.e. max power at zero, no power at 0.5. The second half is an auto lapped train brake application, with 0.5 as release, and 1.0 as emergency. An example of how to configure a combined throttle and brake lever is below:

throttle_brake_lever
{
kind "lever"
mesh "throttle_brake_handle.im"
auto-create 1
att "a.throttle_brake_handle"
limits 0,16
angles 0.94,-0.94
notches 0,0.0625,0.125,0.1875,0.25,0.3125,0.375,0.4375,0.5,0.5625,0.625,0.6875,0.8125,0.75,0.875,0.9375,1
notchheight 1,2,2,2,2,2,2,2,1,2,2,2,2,2,2,2,1
att-parent "default"
radius 0.12
invert 1
}

Unfortunately, trains that use this type of control generally use blended and/or EP brakes, and this control uses the standard Trainz air brake, which operates in a distinctly different manner, and as a result, can feel very wrong for this control type. (See the section on scripting controls for how a better combined brake and throttle lever may be implemented).

==Pull lever==

This is a sprung lever. You pull on this lever to activate it, and when you let it go, it returns to the original position. This kind of action is commonly associated with a locomotive horn, and this is what I am using as an example:

horn
{
kind "pulllever"
mesh "horn.im"
att "a.horn"
auto-create 1
angles 0,-0.55
limits 0,1
mousespeed -1
radius -0.02
notches 0,1
notchheight 0,0
}

==Switch==

A switch is a lever that does not require the user to 'drag' it with the mouse - it operates on a click only. This is used for smaller controls that are 'on' or 'off', and do not have intermediate positions. Parameters are much like they are for a 'lever', only a switch should only have two notches - on and off.

Unfortunately, some things you'd normally associate with being a 'switch' (e.g. the headlight switch control) require mulitple positions, and will need to remain as a 'lever' in order to allow the player to set the correct position for the control.

An example of a switch would be:

switch1
{
kind "switch"
mesh "switch.im"
att "a.switch1"
limits 0,1
angles 1.4,0
notches 0,1
notchheight 0,0
}

As 'switch' was introduced in TS2009 SP2, interiors that use kind 'switch' controls should be marked trainz-build 3.1 or later in the config.txt.

==button==

A button is a momentary contact press-and-hold button. This is a brand new control added for TS12 patch 2, released end of june 2011. Content using this feature should have trainz-build 3.6 or later in the config.txt.

Finally this brings Trainz the "click to press", "hold to hold pressed", "let go to release" style momentary pushbutton.

button1
{
kind "button"
mesh "switch.im"
att "a.switch1"
limits 0,1
angles 0,0.1
notches 0,1
notchheight 0,0
}

==Pull rope==

This is a linear pull rope control. Unlike the rotating controls discussed previously, this control type moves the mesh linearly along the Z axis of the attachment. It behaves as you would expect from a suspended rope - click and drag to pull, let go to release. It will spring back to it's initial position in the same manner as kind 'pulllever'.

[[File:Pullropetype.png|800px]]]

horn
{
kind "pullrope"
mesh "horn_rope.im"
att "a.horn"
limits 0,1
angles 0.1,0
notches 0,1
notchheight 0,0
mousespeed -1
}

==needle==

A needle is the standard Trainz output device. Like the lever, it is based on rotational movement, and any gauge, dial, or other output device based on rotational movement can be implemented. Any static part of the gauge should be modelled as part of the cab, and only the moving part as part of the needle. Like the lever, the rotation will be around the Z axis of the needle, and it is common practice to point the point of the needle along the Y axis. Cabs often have a number of similar gauges, and re-using the same needle repeatedly in each gauge is a lot easier if this setup is done consistently.

As an example of a needle, here is a basic speedometer:

speedo_needle
{
kind "needle"
auto-create 1
mesh "speedo_needle.im"
att "a.speedo_needle"
limits 0,67.056
angles 0,4.712
}

The default cab script knows to move the "speedo_needle" object as the train speed changes, so simply by naming this control "speedo_needle", it has become a speedometer.

For a speedo, the 'limits' values will be the minimum and maximum reportable speed in m/s.

Creating other rotational gauges is similar - refer to the [[%22mesh-table%22_container_(interior_version)|mesh-table (interior version)]] documentation to see all the different values that Trainz can show by default.

==light==

Another common type of control is a light. This is created simply as a textured plane, which is either hidden or shown to represent light off or light on. It is attached as any other standard mesh attachment would be - there is no rotation to worry about here.

wheelslip_light
{
kind "light"
mesh "wheelslip_light.im"
att "a.wheelslip_light"
}

This light will be used to show wheelslip in a default cab.

==animated-lever==

If you want more complex movement than simple rotation, you have the option of animating the lever and using kind 'animated-lever'. This will use an animation you create in your modelling program to move the control about. An example of this is visible in the MN ACMU cab. (I've reduced the number of notches here for readability - the real one has 32, not 16).

throttle_lever
{
mesh "throttlehandle.im"
anim "throttlehandle.kin"
auto-create 1
att "a.throttlelever"
limits 0,16
notches 0,0.0625,0.125,0.1875,0.25,0.3125,0.375,0.4375,0.5,0.5625,0.625,0.6875,0.8125,0.75,0.875,0.9375,1
notchheight 1,2,2,2,2,2,2,2,1,2,2,2,2,2,2,2,1
att-parent "default"
kind "animated-lever"
test-collisions 0
mousespeed 1
}

Where the standard lever is rotated between it's angles to move from notch to notch, the animated-lever has it's animation played to the corresponding frame.

===collision-proxy===

Animated levers can be hard to grab hold of compared to normal levers. To get around this, an invisible mesh is used to show the game the range of movement the control has, and to allow the user to grab the lever more easily. This example again comes from the MN ACMU cab:

throttle-collision-box
{
mesh "throttlehandleselection.im"
att-parent "throttle_lever"
att "a.selection_box"
auto-create 1
kind "collision-proxy"
opacity 0
collision-parent "throttle_lever"
}

==animated-dial==

If you've been paying attention to levers, needles and animated levers, I think you can guess where we are going with this one. This is an animated needle. Instead of rotating between the angles specified, it plays it's animation to the relevant frame to show the value. Use this when what you want to achieve can't be done with simple rotational movement.

(Example usage for this control to follow).

==digital-dial==

Some locomotives use a digital readout rather than analogue dials.

Trainz has two control kinds to support digital displays - one for speed units, and one for pressure units. Instead of angles of movement, these both have some font specific options to configure how the digits appear. In both cases, the Y axis of the attachment point should be pointing upward to signify the up direction of the font.

"font" defines the typeface. For a list of valid typefaces, see the [[%22mesh-table%22_container_(interior_version)#font|mesh-table (interior version)]] documentation. Generally this follows closely with a number of default windows font names.

"fontsize" defines the size of the font. The default value for this is 0.02, and this is a pretty respectable size display.

"fontcolor" defines the RGB color of the text. Each value is a floating point number between 0.0 and 1.0.

"mesh" normally would display the mesh used for the needle. In the case of digital dials, they are not used, but the tag is still required. Any mesh can be used here; using an existing needle mesh would be fine.

===digital-dial-spd===

For a speedometer (or any other gauge that shows units in speed, e.g. a speed limit display), use kind 'digital-dial-spd'.

An example speedometer using this kind would be declared as:

speedo_needle2
{
kind "digital-dial-spd"
mesh "brake_needle.im"
att "a.digispeedo"
limits 0,55
font "arial"
fontsize 0.01
fontcolor 196,196,246
auto-create 1
}

===digital-dial-prs===

For a display using pressure units, use digital-dial-prs. This is a digital brake pipe pressure gauge:

bptrainbrakepipe_needle2
{
kind "digital-dial-prs"
mesh "brake_needle.im"
att "a.trainpipe_pressure"
limits 0,55
font "arial"
fontsize 0.01
fontcolor 0.0,1.0,0.0
auto-create 1
}

[[File:Digispeedoreference.png|350px|thumb|An example of digital needles being used for pressure and speed.]]

==firebox==

The firebox control is a special kind to implement the fire of a steam locomotive.

(Further information about this specific control to follow).

Note: Some steam cab interior models use the firebox, fireglow and burning coal effects found in the Auran PB15 cab interior. This can cause quite severe flickering effects in some models The intensity of flickering varies on the textures used and can be attenuated by use of darker colours. The flickering can be eliminated by not using the firebox effect. The fireglow and burning coal (coal) effects are OK.

'''Note: This feature does not work currently in T:ANE and TRS19.
'''

You can, of course, always make your own.

=Scripting additional behaviour in a cab=

A lot can be achieved in Trainz purely by naming the controls correctly and relying on Trainz default cab scripts to make them work. A quite reasonable cab can be made for many locomotives without having to do any scripting whatsoever.

However, a lot more realism can be achieved by scripting the cab. Additional features can be added beyond what Trainz supports, including new types of controls, or extended behaviour on existing controls.

The first thing to consider when looking at scripting a cab, is "is the cab the best place for this feature?". A cab is not a persistent asset, which means it can go away at any point. When it's gone, it isn't running it's script. Consequently, it is a bad place for any persistent or time based logic - it should only be used to script the immediate behaviour of the controls. Anything beyond this should be implemented the vehicle itself or possibly a script library, both of which are more persistent objects.

If all you want to achieve is to add some simple extra features (e.g. a display of signal aspects within the cab), you can derive from the trainz standard classes, and inherit the default behaviour when adding your new behaviour. This means you can concentrate on just your extra feature, and don't have to worry about making existing functionality work.

If you want to do something a little more advanced (e.g. change the behaviour of the throttle and/or brake controllers), then you are probably best deriving your cab script from the 'cabin' class, ignoring the default cab scripts, and implementing your required behaviour from scratch. This gives you a lot more control, but you do need to do more yourself.

For some examples of the first route, have a look at the MN cabs - the M7 or the ACMU are good examples. Both have a cab signal repeater implemented in the cab interior script, and use the base functionality for almost everything else.

-~= To Be Continued... =~-

==Return to Index==

[[HowToGuides|<< How To Guides]]

[[Category:How-to guides]]

File:Digispeedoreference.png

2021-06-17T04:51:13Z

Gdennish: Example of Digital Speedos using <kuid2:523:55585:1> MN M7 Interior

Example of Digital Speedos using <kuid2:523:55585:1> MN M7 Interior

HowTo/Build a cab interior

2021-06-16T19:24:21Z

Gdennish: Clarified Digital Needles

Trainz uses an [[KIND_Interior|interior]] object to represent a locomotive cab, or view from another vehicle, e.g. a passenger coach, brake van or caboose. Interiors can also be attached to some non-train assets. For this howto, I am going to assume that we are creating a traincar interior, and focus primarily on a cab interior for a diesel or electric locomotive.

=Basic structure=

The basic structure of a cab is quite similar to a number of different assets. You will have a main mesh with a number of attached sub-meshes, which are arranged using a [[%22mesh-table%22_container_(interior_version)|mesh-table]].

The main cab mesh typically consists of the interior walls, roof and floor of the cab, the control desk or stand, all furniture or other static objects visible inside the cab, and also all parts of the locomotive exterior that are visible from inside the cab - e.g. the top of any projecting nose below the cab windows. Remember to consider the sightlines out of rear windows too for visible bodywork panels - the user can move around the cab and rotate the camera to any angle. Users are not restricted to looking forward out of the front windows only.

=Artwork considerations=

There are some differences in style between the construction of an interior object and a typical trainz object.

Except in very specific circumstances, there will not be more than one interior object in existence at any time, and that interior is always viewed from very close range - the user is inside it. Because of this, interiors are typically modelled with a high polygon count and with high resolution textures, to give an impressive visual feel. LOD is not used, as the user never gets far enough away from the interior for LOD techniques to have worthwhile benefit. However, LOD techniques may be ideal in a case of a passenger wagon with high polygon chair models.

Trainz lights interior objects differently to map objects like buildings and other scenery - the main illumination is ambient, not directional. (A steam loco does have a directional light coming from the firebox, but a diesel or electric cab typically has no directional light inside, and relies entirely on ambient illumination).

With ambient illumination, effects such as normal and specular mapping do not have much (if any) effect. Because of this, more effort needs to be put into the diffuse texture for a cab interior than would normally be applied to Trainz objects. Drawing or baking shadows and other effects into the diffuse textures is required to produce a nice looking cab interior.

An example cab would be the [[File:PB_interior.rar]]

=A basic config file=

The minimal required config for an interior to show in-game is:

kind interior
kuid <kuid2:YOUR:KUID:HERE>
trainz-build 2.9
username "Your interior name here"
category-class ZI

mesh-table
{
default
{
mesh "your_interior_mesh_name.im"
auto-create 1
}
}

Note: There are also other base tags that should be added that are common to all asset types - e.g. the download station will require a valid thumbnails container before the asset can be uploaded. See the documentation for [[KIND TrainzBaseSpec]] for details of tags which apply to all trainz assets. Depending on which Trainz version you have and which trainz-build number you have specified, some of these may be required - content manager will tell you what is required, listing missing tags as errors.

==camera positions==

If we load a cab up with that config file, we will note that the view is not particularly appealing. Chances are we're right down near the floor. To fix this, we need to define some default positions for camera views. This is done with the [[%22cameralist%22_Container|cameralist container]] and the [[KIND_Interior#cameradefault|cameradefault]] tag.
Add the following to your config.txt file:

cameralist
{
camera0 0,0,2,0,0
}

cameradefault 0

The cameralist container can contain any number of cameras, but they must be numbered sequentially and start at zero.

The five numbers are the X, Y and Z coordinates of the camera in metres relative to the 0,0,0 point of the interior mesh, and the Yaw and Pitch in radians. Luckily you don't have to work these values out from scratch - add the line "-freeintcam" to your trainzoptions.txt file, and you can move the camera about in the cab with the mouse and keyboard, and the precise position will be displayed in the bottom right corner.

When you have found a position you like, write the numbers down. When you've got a good selection of positions recorded, add them to the cameralist container.

You may wish to return to this and tweak the values later once all the controls are in place - but it's handy to have a good starting position for the camera while testing.

=Cab controls=

A locomotive cab interior needs working cab controls. What fun would sitting in the drivers seat be without being able to pull on the levers, change the switches, and watch the gauges and dials move?

The moving part of each lever, switch, gauge or dial is created as a separate mesh, which is then attached to the cab with an attachment point. (The static part, e.g. guide rails for levers, should be part of the cab mesh itself).

==Lever==

The lever is the basic input device in a cab. It is based on rotational movement, and any object that requires rotational movement (e.g. a wheel or ring) can be implemented as a lever.

If you actually want linear movement, you can still use a lever - just move the attachment point a long way away - e.g. 10 or 20 metres away from the control. The resulting small arc will not be noticable over the length of movement. As an example, sliding windows in Trainz cabs have been implemented as levers "attached" something like 10 or 20 metres out to the side of the vehicle for a long time. (The exception to this is a horn pull rope - trainz provides a control specifically for this purpose).

You will need to create the lever in your modelling program aligned correctly - the rotation needs to be around the Z axis, and main part of the object will point along the Y axis.

When adding the attachment point to the main mesh, align it so the Z axis is the axis of rotation. It is common to point the Y axis at the default position - e.g. levers in the 'off' or 'neutral' position, and needles pointing to zero. This is not strictly required, as the range of movement can be adjusted at both ends, but it provides a handy reference when creating the config file.

[[File:BasicLeverSetup.png|350px|thumb|An example of a lever being used as a signboard cover.]]

It is worth noting that you can reuse a mesh for multiple attachments. This is particularly useful for switches, as identical appearance switches are often used repeatedly in a cab for different purposes.

===Throttle Lever===

A good example of a standard lever in use is a locomotive throttle control. A typical US diesel throttle has 9 notched positions (from 0 to 8 inclusive).

As noted above, the lever is created in the modelling package so it points along the Y axis and the axis of rotation is along the Z axis. The attachment point is added to the cab interior mesh at the correct position, and rotated so the Z axis is aligned with the axis of rotation, and the Y axis points to the default position.

Now we need to add an entry to the config file to add our throttle lever.

Into the mesh table, add an entry like this:

throttle_lever
{
kind "lever"
mesh "throttle_lever.im"
att "a.throttle_lever"
limits 0,8
angles 0,1.57
notches 0,0.125,0.25,0.375,0.5,0.625,0.75,0.875,1
notchheight 1,2,2,2,2,2,2,2,1
radius 0.35
auto-create 1
att-parent "default"
}

... remember to set your attachment point and mesh name correctly.

The 'angles' line defines how far the control rotates. It is in radians - there are 2 x Pi (6.28) radians in a complete circle. My default of 1.57 will give you about 90 degrees of rotation, in the positive direction. Adjust this number to get the control to rotate the correct amount. You should be able to work out the number you need in your modelling program by using the rotate tool on the attachment point, and recording the amount of rotation required to move to the intended maximum location. It should not require significant trial and error.

The 'radius' line defines the position of the notch position overlay and the text label. It is in metres. If the overlay is too close in, increase this number. If it is too far out, decrease it.

If the lever is the wrong way round (notch 8 is at the wrong end), swap the numbers in the 'angles' tag over, so the higher one is first.

If the lever moves the wrong way when you drag it with the mouse (i.e. it goes left in response to a right drag), add the line:
mousespeed -1
This will invert the mouse movement.

The fact we called this lever "throttle_lever" means it will be used to control the throttle by the default cab script.

So what happens if we wanted a different number of notches? Below is an example of a throttle which has 22 notches. The second value in the 'limits' tag has been edited to return up to notch 22, and more entries have been added to the 'notches' and 'notchheight' tags:

throttle_lever
{
kind "lever"
mesh "throttle_lever.im"
att "a.throttle_lever"
limits 0,22
angles 0,0.94
notches 0,0.045,0.091,0.136,0.182,0.227,0.273,0.318,0.364,0.409,0.455,0.5,0.545,0.591,0.636,0.682,0.727,0.773,0.818,0.864,0.909,0.955,1
notchheight 1,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,1
radius 0.35
auto-create 1
att-parent "default"
}

===Reverser Lever===

The reverser lever is created in a similar manner to throttle lever. The mesh table entry for this will look like:

reverser_lever
{
kind "lever"
mesh "reverser_lever.im"
att "a.reverser_lever"
limits 0,2
angles -0.79,0.79
notches 0,0.5,1
notchheight 1,1,1
radius 0.25
auto-create 1
att-parent "default"
}

In this case, because the 'angles' entry has a range both positive and negative, the lever can move in both directions relative to the attachment point. The game will set the default position to neutral (1), so if you've lined up your attachment point at one end, don't worry - you can use angles which range from zero if you need to.

===Train Air Brake Lever===

There are two types of train air brake lever. A given locomotive only has one type - the brakes are either require manual lapping or are self-lapping. Use the appropriate name and configuration for the loco you are modelling.

====Manual Lapped Brakes====

The manual train brake lever has five positions numbered from zero to four, each one representing a different function. Those functions are Release, Lap, Application, Emergency and Handle Off respectively.

A lever for a manual lap train air brake is defined as follows:

trainbrakelap_lever
{
kind "lever"
mesh "train_brake_lap_lever.im"
att "a.train_brake_lap_lever"
limits 0,4
angles 0,0.94
notches 0,0.25,0.5,0.75,1
notchheight 1,1,1,1,1
radius 0.25
att-parent "default"
auto-create 1
}

In this case, the attachment for the lever has been created in the 'release' position. If it had been created in the 'handle off' position, the angle tag would have been more like:

angles -0.94,0

====Self Lapping Brakes====

A self lapping trainbrake lever has a number of primary notches similar to the manual lap train brake lever. However, instead of a 'lap' and 'apply' position, it has a grade of application between the 'initial' and 'full application' positions. An example of a self-lapping brake handle is this one:

trainbrake_lever
{
kind "lever"
mesh "train_brake_lever.im"
att "a.train_brake_lever"
limits 0,4
angles 0,0.94
notches 0,0.25,0.27,0.29,0.31,0.33,0.35,0.37,0.39,0.41,0.43,0.45,0.47,0.49,0.5,0.75,1
notchheight 1,1,2,2,2,2,2,2,2,2,2,2,2,2,1,1,1
radius 0.25
att-parent "default"
auto-create 1
}

In this case, there are 14 possible levels of brake application - initial at 0.25, 12 intermediate levels, and full application at 0.5. There is no restriction on the number of intermediate levels - if you are modelling a prototype brake handle with a specific number, you may create precisely that number of notches and arrange them between 0.25 and 0.5 as required.

===Combined throttle brake lever===

There is also another control option - a combined throttle brake lever. This type of control is often found on multiple unit trains. This control is split into two halves. The first half of the movement is an inverted throttle - i.e. max power at zero, no power at 0.5. The second half is an auto lapped train brake application, with 0.5 as release, and 1.0 as emergency. An example of how to configure a combined throttle and brake lever is below:

throttle_brake_lever
{
kind "lever"
mesh "throttle_brake_handle.im"
auto-create 1
att "a.throttle_brake_handle"
limits 0,16
angles 0.94,-0.94
notches 0,0.0625,0.125,0.1875,0.25,0.3125,0.375,0.4375,0.5,0.5625,0.625,0.6875,0.8125,0.75,0.875,0.9375,1
notchheight 1,2,2,2,2,2,2,2,1,2,2,2,2,2,2,2,1
att-parent "default"
radius 0.12
invert 1
}

Unfortunately, trains that use this type of control generally use blended and/or EP brakes, and this control uses the standard Trainz air brake, which operates in a distinctly different manner, and as a result, can feel very wrong for this control type. (See the section on scripting controls for how a better combined brake and throttle lever may be implemented).

==Pull lever==

This is a sprung lever. You pull on this lever to activate it, and when you let it go, it returns to the original position. This kind of action is commonly associated with a locomotive horn, and this is what I am using as an example:

horn
{
kind "pulllever"
mesh "horn.im"
att "a.horn"
auto-create 1
angles 0,-0.55
limits 0,1
mousespeed -1
radius -0.02
notches 0,1
notchheight 0,0
}

==Switch==

A switch is a lever that does not require the user to 'drag' it with the mouse - it operates on a click only. This is used for smaller controls that are 'on' or 'off', and do not have intermediate positions. Parameters are much like they are for a 'lever', only a switch should only have two notches - on and off.

Unfortunately, some things you'd normally associate with being a 'switch' (e.g. the headlight switch control) require mulitple positions, and will need to remain as a 'lever' in order to allow the player to set the correct position for the control.

An example of a switch would be:

switch1
{
kind "switch"
mesh "switch.im"
att "a.switch1"
limits 0,1
angles 1.4,0
notches 0,1
notchheight 0,0
}

As 'switch' was introduced in TS2009 SP2, interiors that use kind 'switch' controls should be marked trainz-build 3.1 or later in the config.txt.

==button==

A button is a momentary contact press-and-hold button. This is a brand new control added for TS12 patch 2, released end of june 2011. Content using this feature should have trainz-build 3.6 or later in the config.txt.

Finally this brings Trainz the "click to press", "hold to hold pressed", "let go to release" style momentary pushbutton.

button1
{
kind "button"
mesh "switch.im"
att "a.switch1"
limits 0,1
angles 0,0.1
notches 0,1
notchheight 0,0
}

==Pull rope==

This is a linear pull rope control. Unlike the rotating controls discussed previously, this control type moves the mesh linearly along the Z axis of the attachment. It behaves as you would expect from a suspended rope - click and drag to pull, let go to release. It will spring back to it's initial position in the same manner as kind 'pulllever'.

[[File:Pullropetype.png|800px]]]

horn
{
kind "pullrope"
mesh "horn_rope.im"
att "a.horn"
limits 0,1
angles 0.1,0
notches 0,1
notchheight 0,0
mousespeed -1
}

==needle==

A needle is the standard Trainz output device. Like the lever, it is based on rotational movement, and any gauge, dial, or other output device based on rotational movement can be implemented. Any static part of the gauge should be modelled as part of the cab, and only the moving part as part of the needle. Like the lever, the rotation will be around the Z axis of the needle, and it is common practice to point the point of the needle along the Y axis. Cabs often have a number of similar gauges, and re-using the same needle repeatedly in each gauge is a lot easier if this setup is done consistently.

As an example of a needle, here is a basic speedometer:

speedo_needle
{
kind "needle"
auto-create 1
mesh "speedo_needle.im"
att "a.speedo_needle"
limits 0,67.056
angles 0,4.712
}

The default cab script knows to move the "speedo_needle" object as the train speed changes, so simply by naming this control "speedo_needle", it has become a speedometer.

For a speedo, the 'limits' values will be the minimum and maximum reportable speed in m/s.

Creating other rotational gauges is similar - refer to the [[%22mesh-table%22_container_(interior_version)|mesh-table (interior version)]] documentation to see all the different values that Trainz can show by default.

==light==

Another common type of control is a light. This is created simply as a textured plane, which is either hidden or shown to represent light off or light on. It is attached as any other standard mesh attachment would be - there is no rotation to worry about here.

wheelslip_light
{
kind "light"
mesh "wheelslip_light.im"
att "a.wheelslip_light"
}

This light will be used to show wheelslip in a default cab.

==animated-lever==

If you want more complex movement than simple rotation, you have the option of animating the lever and using kind 'animated-lever'. This will use an animation you create in your modelling program to move the control about. An example of this is visible in the MN ACMU cab. (I've reduced the number of notches here for readability - the real one has 32, not 16).

throttle_lever
{
mesh "throttlehandle.im"
anim "throttlehandle.kin"
auto-create 1
att "a.throttlelever"
limits 0,16
notches 0,0.0625,0.125,0.1875,0.25,0.3125,0.375,0.4375,0.5,0.5625,0.625,0.6875,0.8125,0.75,0.875,0.9375,1
notchheight 1,2,2,2,2,2,2,2,1,2,2,2,2,2,2,2,1
att-parent "default"
kind "animated-lever"
test-collisions 0
mousespeed 1
}

Where the standard lever is rotated between it's angles to move from notch to notch, the animated-lever has it's animation played to the corresponding frame.

===collision-proxy===

Animated levers can be hard to grab hold of compared to normal levers. To get around this, an invisible mesh is used to show the game the range of movement the control has, and to allow the user to grab the lever more easily. This example again comes from the MN ACMU cab:

throttle-collision-box
{
mesh "throttlehandleselection.im"
att-parent "throttle_lever"
att "a.selection_box"
auto-create 1
kind "collision-proxy"
opacity 0
collision-parent "throttle_lever"
}

==animated-dial==

If you've been paying attention to levers, needles and animated levers, I think you can guess where we are going with this one. This is an animated needle. Instead of rotating between the angles specified, it plays it's animation to the relevant frame to show the value. Use this when what you want to achieve can't be done with simple rotational movement.

(Example usage for this control to follow).

==digital-dial==

Some locomotives use a digital readout rather than analogue dials.

Trainz has two control kinds to support digital displays - one for speed units, and one for pressure units. Instead of angles of movement, these both have some font specific options to configure how the digits appear. In both cases, the Y axis of the attachment point should be pointing upward to signify the up direction of the font.

"font" defines the typeface. For a list of valid typefaces, see the [[%22mesh-table%22_container_(interior_version)#font|mesh-table (interior version)]] documentation. Generally this follows closely with a number of default windows font names.

"fontsize" defines the size of the font. The default value for this is 0.02, and this is a pretty respectable size display.

"fontcolor" defines the RGB color of the text. Each value is a floating point number between 0.0 and 1.0.

"mesh" normally would display the mesh used for the needle. In the case of digital dials, they are not used, but the tag is still required. Any mesh can be used here; using an existing needle mesh would be fine.

===digital-dial-spd===

For a speedometer (or any other gauge that shows units in speed, e.g. a speed limit display), use kind 'digital-dial-spd'.

An example speedometer using this kind would be declared as:

speedo_needle2
{
kind "digital-dial-spd"
mesh "brake_needle.im"
att "a.digispeedo"
limits 0,55
font "arial"
fontsize 0.01
fontcolor 196,196,246
auto-create 1
}

===digital-dial-prs===

For a display using pressure units, use digital-dial-prs. This is a digital brake pipe pressure gauge:

bptrainbrakepipe_needle2
{
kind "digital-dial-prs"
mesh "brake_needle.im"
att "a.trainpipe_pressure"
limits 0,55
font "arial"
fontsize 0.01
fontcolor 0.0,1.0,0.0
auto-create 1
}

==firebox==

The firebox control is a special kind to implement the fire of a steam locomotive.

(Further information about this specific control to follow).

Note: Some steam cab interior models use the firebox, fireglow and burning coal effects found in the Auran PB15 cab interior. This can cause quite severe flickering effects in some models The intensity of flickering varies on the textures used and can be attenuated by use of darker colours. The flickering can be eliminated by not using the firebox effect. The fireglow and burning coal (coal) effects are OK.

'''Note: This feature does not work currently in T:ANE and TRS19.
'''

You can, of course, always make your own.

=Scripting additional behaviour in a cab=

A lot can be achieved in Trainz purely by naming the controls correctly and relying on Trainz default cab scripts to make them work. A quite reasonable cab can be made for many locomotives without having to do any scripting whatsoever.

However, a lot more realism can be achieved by scripting the cab. Additional features can be added beyond what Trainz supports, including new types of controls, or extended behaviour on existing controls.

The first thing to consider when looking at scripting a cab, is "is the cab the best place for this feature?". A cab is not a persistent asset, which means it can go away at any point. When it's gone, it isn't running it's script. Consequently, it is a bad place for any persistent or time based logic - it should only be used to script the immediate behaviour of the controls. Anything beyond this should be implemented the vehicle itself or possibly a script library, both of which are more persistent objects.

If all you want to achieve is to add some simple extra features (e.g. a display of signal aspects within the cab), you can derive from the trainz standard classes, and inherit the default behaviour when adding your new behaviour. This means you can concentrate on just your extra feature, and don't have to worry about making existing functionality work.

If you want to do something a little more advanced (e.g. change the behaviour of the throttle and/or brake controllers), then you are probably best deriving your cab script from the 'cabin' class, ignoring the default cab scripts, and implementing your required behaviour from scratch. This gives you a lot more control, but you do need to do more yourself.

For some examples of the first route, have a look at the MN cabs - the M7 or the ACMU are good examples. Both have a cab signal repeater implemented in the cab interior script, and use the base functionality for almost everything else.

-~= To Be Continued... =~-

==Return to Index==

[[HowToGuides|<< How To Guides]]

[[Category:How-to guides]]

Animation Effect

2021-06-16T17:17:57Z

Gdennish: /* Explanations and default values */

The Animation effect kind is a [["mesh-table" Container]] effect container.

This page describes [[trainz-build]] 4.6.

The following tags are supported:

kind "animation"
name ""
anim ""
looped 0
speed 1.0
animation-starts-active 0
animation-has-random-start-position 0

===Explanations and default values===
The animation effect is used to define the animation for a mesh. Usually, the animation will be controlled by a script related to the asset.

kind
:Text. The kind name for this effect container.
:Compulsory "animation".

name
:Text. A name for this effect container. This name can be used in scripts.
:Optional. Default ""
:'''Obsolete as of TRS19 111951.'''

anim
:Name. The name of an animation (.kin) file included with this asset
:Compulsory.

looped
:Boolean. 0 (false) = the animation executes once when triggered, then stops. 1 = the animation restarts when it reaches the end.
:Compulsory.

speed
:Float. A multiplier for the execution rate of the animation.
:Compulsory.

animation-starts-active
:Boolean. 0 (false, default) = the animation only begins playing when triggered from script. 1 (true) = the animation starts playing immediately when the parent mesh is first created in the scene.

animation-has-random-start-position
:Boolean. 0 (false, default) = the animation starts playing from the beginning. 1 (true) = the animation starts at a random position. This is intended to permit multiple instances of a single scenery asset to avoid looking artificially synchronised. Script should avoid attempting to control the animation position if this tag is enabled, as the results may be unpredictable. Typically used with 'animation-starts-active' and 'looped' enabled.

[[Category:Config Container]]

M.tbumpenv

2021-02-03T08:11:45Z

Gdennish: /* Blender Material Configuration (2.8+) */

'''This is a legacy material, and should only be used where compatibility with older versions of Trainz is required.'''

=Description=

Bump mapped environment reflective material.

Blends a environment reflection map onto a bump map. The reflection is controlled in the alpha channel of the diffuse map. White in the alpha channel is full sun/sky reflection and black is no reflection.

The environment cube map is generated by the game and is not specified in the material configuration.

Used too heavily it will drastically change the original surface color. Used gently it has subtle advantages over m.reflect.

Reducing the specular level (changing the specular color to gray) will reduce the strength of reflection.

When used in '''TRS19''' , the alpha channel of the diffuse texture will represent the ''metallic'' and the normal map alpha will determine the ''roughness''.

=Preview=
[[Image:mat_tbumpenv.jpg]]
=Max Settings=
[[Image:max_material_tbumpenv.jpg]]
=Max Settings in detail=
* Ambient - Ambient color R,G,B
* Diffuse - Diffuse color R,G,B
* Specular - Specular color R,G,B
* Opacity - Level of transparency, 0 = transparent, 100 = opaque.
* Glossiness - Should be set to 32 to match game.
* [[Diffuse map]] - RGB = diffuse color, A = environment reflection strength/mask
* [[Opacity map]] - Legacy support for Diffuse texture Alpha channel - As per above, the alpha channel of the Diffuse texture provides the environment reflection strength/mask
* [[Normal map]] - RGB = bump normal A, = specular strength

=Blender Material Configuration (2.7x)=

You must use the Blender Render option in Blender as the Cycles Render in V2.79 doesn't export the texture names associated with the material. You will need a diffuse, and normal texture.
The material must have the suffix .m.tbumpenv , with any name you like. Here is an example with the material name called "Material."

[[File:Tbumpenv279config.png|border|middle|]]

[[File:Blender27TbumpenvDiffuse.png|border|middle|x700px]] [[File:Blender27TbumpenvNormal.png|border|middle|x700px]]

=Blender Material Configuration (2.8+)=

In order to export with Blender 2.8+, you will need Rileyzzz's IM Exporter: [https://github.com/rileyzzz/BlenderIMExporter https://github.com/rileyzzz/BlenderIMExporter]

The Eevee or Cycles renderer will work fine for exporting. The resulting material may look strange in Blender; this is normal. The material must have the suffix .m.tbumpenv , with any name you like.

Use the following node setup to export:

[[File:Tbumpenv - tbumptex Blender 2.8+.png|border|middle|x700px]]

Additionally, the Alpha, Roughness, Specular, and Emission sliders can be altered to change the appearance of your model.

[[File:AlphaSlider2.8+.png|border|middle|x300px]] Alpha - Reflects the Visibility (opacity) of the material

[[File:ShininessSlider2.8+.png|border|middle|x300px]] Roughness - Reflects the shininess of the material

[[File:SpecularSlider2.8+.png|border|middle|x300px]] Specular - Reflects the specular value of the material

[[File:EmissionSlider2.8+.png|border|middle|x300px]] Emission - The Emission strength value can be left at 1.0. If you want your material to glow, change the emission colour to any colour you'd like.

=Substance Painter Preset=

If you want to use Substance Painter for legacy materials, tbumpenv is your best option. It also lets content look almost up to par in TRS19. Here is a Dropbox link with a preset for you: [https://www.dropbox.com/s/6wpuivje3ua1f6v/tbumpenv.spexp?dl=0].
* '''Note: You may have to adjust the alpha channels more to your liking. By default Trainz is quite sensitive for the environment intensity, so you'll need to adjust the diffuse alpha accordingly.'''

=Related Links=
[[Material Types]] - Material types supported by Trainz.

[[Max Exporters]] - 3D Studio Max exporters.

[[Exporting with 3D Studio Max]] - Material setup and exporting with 3DS Max.

[[.texture.txt Files]] - What goes into a .texture.txt file

[[Category:Material types]]

M.tbumpenv

2021-02-03T08:07:32Z

Gdennish:

'''This is a legacy material, and should only be used where compatibility with older versions of Trainz is required.'''

=Description=

Bump mapped environment reflective material.

Blends a environment reflection map onto a bump map. The reflection is controlled in the alpha channel of the diffuse map. White in the alpha channel is full sun/sky reflection and black is no reflection.

The environment cube map is generated by the game and is not specified in the material configuration.

Used too heavily it will drastically change the original surface color. Used gently it has subtle advantages over m.reflect.

Reducing the specular level (changing the specular color to gray) will reduce the strength of reflection.

When used in '''TRS19''' , the alpha channel of the diffuse texture will represent the ''metallic'' and the normal map alpha will determine the ''roughness''.

=Preview=
[[Image:mat_tbumpenv.jpg]]
=Max Settings=
[[Image:max_material_tbumpenv.jpg]]
=Max Settings in detail=
* Ambient - Ambient color R,G,B
* Diffuse - Diffuse color R,G,B
* Specular - Specular color R,G,B
* Opacity - Level of transparency, 0 = transparent, 100 = opaque.
* Glossiness - Should be set to 32 to match game.
* [[Diffuse map]] - RGB = diffuse color, A = environment reflection strength/mask
* [[Opacity map]] - Legacy support for Diffuse texture Alpha channel - As per above, the alpha channel of the Diffuse texture provides the environment reflection strength/mask
* [[Normal map]] - RGB = bump normal A, = specular strength

=Blender Material Configuration (2.7x)=

You must use the Blender Render option in Blender as the Cycles Render in V2.79 doesn't export the texture names associated with the material. You will need a diffuse, and normal texture.
The material must have the suffix .m.tbumpenv , with any name you like. Here is an example with the material name called "Material."

[[File:Tbumpenv279config.png|border|middle|]]

[[File:Blender27TbumpenvDiffuse.png|border|middle|x700px]] [[File:Blender27TbumpenvNormal.png|border|middle|x700px]]

=Blender Material Configuration (2.8+)=

In order to export with Blender 2.8+, you will need Rileyzzz's IM Exporter: [https://github.com/rileyzzz/BlenderIMExporter https://github.com/rileyzzz/BlenderIMExporter]

The Eevee or Cycles renderer will work fine for exporting. The resulting material may look strange in Blender; this is normal. The material must have the suffix .m.tbumpenv , with any name you like.

Use the following node setup to export:

[[File:Tbumpenv - tbumptex Blender 2.8+.png|border|middle|x700px]]

Additionally, the Alpha, Roughness, Specular, and Emission sliders can be altered to change the appearance of your model.

Alpha - Reflects the Visibility (opacity) of the material

Roughness - Reflects the shininess of the material

Specular - Reflects the specular value of the material

Emission - The Emission strength value can be left at 1.0. If you want your material to glow, change the emission colour from black to any shade in-between black and white.

[[File:AlphaSlider2.8+.png|border|middle]]

[[File:ShininessSlider2.8+.png|border|middle]]

[[File:SpecularSlider2.8+.png|border|middle]]

[[File:EmissionSlider2.8+.png|border|middle]]

=Substance Painter Preset=

If you want to use Substance Painter for legacy materials, tbumpenv is your best option. It also lets content look almost up to par in TRS19. Here is a Dropbox link with a preset for you: [https://www.dropbox.com/s/6wpuivje3ua1f6v/tbumpenv.spexp?dl=0].
* '''Note: You may have to adjust the alpha channels more to your liking. By default Trainz is quite sensitive for the environment intensity, so you'll need to adjust the diffuse alpha accordingly.'''

=Related Links=
[[Material Types]] - Material types supported by Trainz.

[[Max Exporters]] - 3D Studio Max exporters.

[[Exporting with 3D Studio Max]] - Material setup and exporting with 3DS Max.

[[.texture.txt Files]] - What goes into a .texture.txt file

[[Category:Material types]]

M.tbumpenv

2021-02-03T08:03:36Z

Gdennish: Added Blender 2.8+ Configuration with Rileyzzz's Exporter

'''This is a legacy material, and should only be used where compatibility with older versions of Trainz is required.'''

=Description=

Bump mapped environment reflective material.

Blends a environment reflection map onto a bump map. The reflection is controlled in the alpha channel of the diffuse map. White in the alpha channel is full sun/sky reflection and black is no reflection.

The environment cube map is generated by the game and is not specified in the material configuration.

Used too heavily it will drastically change the original surface color. Used gently it has subtle advantages over m.reflect.

Reducing the specular level (changing the specular color to gray) will reduce the strength of reflection.

When used in '''TRS19''' , the alpha channel of the diffuse texture will represent the ''metallic'' and the normal map alpha will determine the ''roughness''.

=Preview=
[[Image:mat_tbumpenv.jpg]]
=Max Settings=
[[Image:max_material_tbumpenv.jpg]]
=Max Settings in detail=
* Ambient - Ambient color R,G,B
* Diffuse - Diffuse color R,G,B
* Specular - Specular color R,G,B
* Opacity - Level of transparency, 0 = transparent, 100 = opaque.
* Glossiness - Should be set to 32 to match game.
* [[Diffuse map]] - RGB = diffuse color, A = environment reflection strength/mask
* [[Opacity map]] - Legacy support for Diffuse texture Alpha channel - As per above, the alpha channel of the Diffuse texture provides the environment reflection strength/mask
* [[Normal map]] - RGB = bump normal A, = specular strength

=Blender Material Configuration (2.7x)=

You must use the Blender Render option in Blender as the Cycles Render in V2.79 doesn't export the texture names associated with the material. You will need a diffuse, and normal texture.
The material must have the suffix .m.tbumpenv , with any name you like. Here is an example with the material name called "Material."

[[File:Tbumpenv279config.png|border|middle|]]

[[File:Blender27TbumpenvDiffuse.png|border|middle|x700px]] [[File:Blender27TbumpenvNormal.png|border|middle|x700px]]

=Blender Material Configuration (2.8+)=

In order to export with Blender 2.8+, you will need Rileyzzz's IM Exporter: [https://github.com/rileyzzz/BlenderIMExporter https://github.com/rileyzzz/BlenderIMExporter]

The Eevee or Cycles renderer will work fine for exporting. The resulting material may look strange in Blender; this is normal. The material must have the suffix .m.tbumpenv , with any name you like.

Use the following node setup to export:

[[File:Tbumpenv - tbumptex Blender 2.8+.png|border|middle|x700px]]

Additionally, the Alpha, Roughness, Specular, and Emission sliders can be altered to change the appearance of your model.

Alpha - Reflects the Visibility (opacity) of the material

Roughness - Reflects the shininess of the material

Specular - Reflects the specular value of the material

Emission - The Emission strength value can be left at 1.0. If you want your material to glow, change the emission colour from black to any shade in-between black and white.

[[File:AlphaSlider2.8+.png|border|left]]
[[File:ShininessSlider2.8+.png|border|left]]
[[File:SpecularSlider2.8+.png|border|left]]
[[File:EmissionSlider2.8+.png|border|left]]

=Substance Painter Preset=

If you want to use Substance Painter for legacy materials, tbumpenv is your best option. It also lets content look almost up to par in TRS19. Here is a Dropbox link with a preset for you: [https://www.dropbox.com/s/6wpuivje3ua1f6v/tbumpenv.spexp?dl=0].
* '''Note: You may have to adjust the alpha channels more to your liking. By default Trainz is quite sensitive for the environment intensity, so you'll need to adjust the diffuse alpha accordingly.'''

=Related Links=
[[Material Types]] - Material types supported by Trainz.

[[Max Exporters]] - 3D Studio Max exporters.

[[Exporting with 3D Studio Max]] - Material setup and exporting with 3DS Max.

[[.texture.txt Files]] - What goes into a .texture.txt file

[[Category:Material types]]

File:ShininessSlider2.8+.png

2021-02-03T07:57:43Z

Gdennish:

File:SpecularSlider2.8+.png

2021-02-03T07:57:28Z

Gdennish:

File:AlphaSlider2.8+.png

2021-02-03T07:56:25Z

Gdennish:

File:EmissionSlider2.8+.png

2021-02-03T07:56:08Z

Gdennish:

File:Tbumpenv - tbumptex Blender 2.8+.png

2021-02-03T07:49:26Z

Gdennish:

M.pbrmetal

2021-02-03T06:43:39Z

Gdennish: /* Blender Material Configuration V2.8+ */

[[m.pbrmetal]] is the most basic PBR-based material type used in Trainz, and should be the default material type of choice for any mesh unless some specific feature of some other material type is required. All PBR materials are defined using a multitude of texture channels (not just a simple RGB image) which define various aspects of the material on a per-texel basis. One major advantage of this approach is that a single in-game [[material]] can be used to display various different real-world materials, rather than requiring multiple separate in-game materials with different parameters. Trainz uses a Metallic/Roughness style [[Physically Based Rendering|PBR workflow]].

It should be noted that the "metal" in the name of this material refers to the physical property used in the lighting equations; it does not mean that the material is only appropriate for metallic surfaces.

This page describes [["Trainz-build" number|content format v4.6]] and assumes that the [[FBX file format]] is used as a data source for any meshes.

=Texture Slots=
The following texture slots are used for this material. All textures should typically have the same dimensions unless they represent a uniform color, however this is not strictly enforced.

==Albedo==
RGB: The [[albedo map]] defines the base color of each texel. The sRGB color space is used.

Please note that there is no alpha channel support. For the most robust result, the alpha channel should be omitted or set to 1.0 (white). Note that unlike legacy Trainz materials, PBR materials do not autodetect opacity mode based on the texture in use. The content creator must select the appropriate material for their desired outcome. Runtime texture replacement should not expect to replace an opaque texture with a blended or masked texture and have the material update automatically.

'''Albedo Texture Example'''

[[File:pbralbedomap1.jpg|border|middle|x200px]]

==Normal==
RGB: Surface [[normal map]]. This defines which way the surface is facing, relative to the interpolated vertex normals. Since this is an XYZ format rather than color data, it should never be modified in Photoshop. Using Photoshop to add a fourth channel or copy/paste smaller textures into a [[texture atlas]] is acceptable. Per-pixel manipulation or use of filters on the "RGB" channels is not acceptable.

A: [[Parallax Occlusion Map|Displacement height]]. 0.0 represents the deepest possible value, while 1.0 represents the shallowest possible value. While it is possible to paint this data in Photoshop, a linear color space must be used, and far superior results will be available through other data sources. The parallax height and the surface normal must be kept in sync, which means that a third-party tool must be used to generate the surface normal from the parallax height if you are painting this map manually.

'''Normal Texture Example with no Alpha Channel (Parallax)'''

[[File:pbrnormalmap1.jpg|border|middle|x200px]]

'''Normal Texture Example with Alpha Channel (Parallax)'''

[[File:pbrnormalwithalpha.jpg|border|middle|x200px]]

==Parameter==
This texture is comprised of four separate channels which each form a separate data element. Linear color space (not sRGB) is used for these channels.

[[File:pbrparametersall.jpg|border|middle|x200px]]

R: Emissive. This causes the texture to have an internal glow, even when no external light is present. Used for phosphors, permanently-lit markings, etc. The glow color is based on the albedo. Note that this glow does not cast light upon surrounding surfaces except via the Bloom post-processing effect. You might want to consider making this a gray / dark gray color on some assets that you want more of the albedo color to show through indirect (ambient) lit surfaces.

'''Parameters (Emissive - Red Channel) Texture Example'''

[[File:pbrparametersemissivemap1.jpg|border|middle|x200px]]

G: Roughness. Defines whether the surface reflections are shiny (0.0) or matte (1.0). See the [[Physically Based Rendering|PBR metal workflow]] for details.

'''Parameters (Roughness - Green Channel) Texture Example'''

[[File:pbrparametersroughnessmap1.jpg|border|middle|x200px]]

B: Ambient Occlusion. Defines whether the surface is exposed to ambient lighting conditions (1.0) or affected only by direct lighting (0.0).

'''Parameters (Ambient Occlusion - Blue Channel) Texture Example'''

[[File:pbrparametersambientocclusionmap1.jpg|border|middle|x200px]]

A: Metallicity. Defines whether the surface is metallic (1.0) with the albedo used to colorize reflected light, or dielectric (0.0) with the albedo used to colorize the surface. While intermediate values are not physically accurate, they may be used to emulate subsurfaces which are partially metallic. See the [[Physically Based Rendering|PBR metal workflow]] for details.

'''Parameters (Metallic - Alpha Channel) Texture Example'''

[[File:pbrparametersmetallicmap1.jpg|border|middle|x200px]]

=Examples=
The following images show this material type with a few basic configurations of roughness and metallicity, under identical environmental conditions.

[[File:m.pbrmetal-0.png|border|middle|x200px]] [[File:m.pbrmetal-1.png|border|middle|x200px]] [[File:m.pbrmetal-2.png|border|middle|x200px]] [[File:m.pbrmetal-3.png|border|middle|x200px]]

[[File:trainz_material_cast_iron.jpg|border|middle|x512px]]

Example asset download:

[http://download.trainzportal.com/tutorials/Trainz_Material_-_pbrmetal_(cast_iron).cdp Trainz Material - pbrmetal (cast iron)]

[[File:trainz_material_gloss_paint.jpg|border|middle|x512px]]

Example asset download:

[http://download.trainzportal.com/tutorials/Trainz_Material_-_pbrmetal_(gloss_paint).cdp Trainz Material - pbrmetal (gloss paint)]

[[File:trainz_material_painted_metal.jpg|border|middle|x512px]]

Example asset download:

[http://download.trainzportal.com/tutorials/Trainz_Material_-_pbrmetal_(painted_metal).cdp Trainz Material - pbrmetal (painted metal)]

[[File:trainz_material_rubber.jpg|border|middle|x512px]]

Example asset download:

[http://download.trainzportal.com/tutorials/Trainz_Material_-_pbrmetal_(rubber).cdp Trainz Material - pbrmetal (rubber)]

[[File:trainz_material_stainless_steel.jpg|border|middle|x512px]]

Example asset download:

[http://download.trainzportal.com/tutorials/Trainz_Material_-_pbrmetal_(stainless_steel).cdp Trainz Material - pbrmetal (stainless steel)]

[[File:chart_roughness_metallic.jpg|border|middle|x512px]]

Example asset (route + objects) download:

[http://download.trainzportal.com/tutorials/pbr_roughness_metallic_chart_180831a.cdp PBR Roughness / Metallic Chart]

=3ds Max Material Configuration=

'''Texture Assignment'''

[[File:pbrmetal3dsmaxtextureassignment.jpg]]

=Blender Material Configuration V2.79b=

You must use the Blender Render option in Blender as the Cycles Render in V2.79b doesn't export the texture names associated with the material.

The albedo and normal textures have no special requirements but the parameters texture must use the Influence->Specular->Hardness tag (checkbox). The value of the hardness is not exported by the Blender FBX exporter. Sample settings are shown below. Note that the normal texture does not use an alpha channel in this example.

[[File:Blender_PBRMetal_albedo_setting.jpg|border|middle|x700px]] [[File:Blender_PBRMetal_normal_setting.jpg|border|middle|x700px]] [[File:Blender_PBRMetal_parameters_setting.jpg|border|middle|x700px]]

=Blender Material Configuration (2.8+)=

The shader node is a Principled BSDF shader and the FBX exporter supports the export of some texture names but not all. The following connections should be made:

Albedo texture to the Base Color input.

Parameter texture to the Roughness input.

The normal texture, via a normal converter set to Tangent, to the Normal input.

The 3D view of the mesh does not show a true PBR render.

You will need to update the texture.txt files created by the Trainz FBX importer.

[[File:Blender 2.80 shader export nodes.jpg|border|middle|x700px]]

=Maya LT Material Configuration=

Maya LT uses a Phong shader and the parameters texture should be linked to the shader Cosine Power input via a Set Range node. Note that the input and output of this node both use Value X. The Normal Map must be passed through a Bump converter and then connected to the shader Normal input. The Bump converter "Use as" value within the attributes editor must use the "Tangent Space Normals" option. See the images below.

''Note. The material name shown in these images has "FBXASC046" where the full stops (periods) appear in the name box.m.pbrmetal. Maya LT does not permit full stops (periods) in name and substitutes an underscore which doesn't work for Trainz. FBXASC046 gets replaced with a full stop on export. N3V are looking at this issue.''

[[File:Sample_pbrmetal_material.jpg|border|middle]]
[[File:Sample_pbrmetal_material_properties.jpg|border|middle]] [[File:Bump_normal_converter_properties.jpg|border|middle]]

=Substance Painter Export Preset=

Export preset for Substance Painter. This preset puts every map you need into Albedo, Normal and Parameter texture channels. As result you will get 3 textures, ready for importing into game.

The link below is a preset that has height maps enabled by default.

[https://www.dropbox.com/s/ukp3p8uw53332ay/Trainz2019_WithHeight.spexp?dl=0 Trainz 2019 Exporter with Height Maps Enabled]

The link below contains a preset that does not have height maps enabled, which may be more useful to some on rollingstock.

[https://www.dropbox.com/s/4gzmuzdy8g7nwzc/Trainz2019.spexp?dl=0 Trainz 2019 Exporter with Height Maps Disabled]

==Installing the Preset==

First download either or both presets to your computer from the links above. Open Substance Painter and navigate to File -> Import Resources.

[[File:Step2.png]]

At the top of the new window, click on "Add resources." Then locate your preset you'd like to import.

[[File:Step3.png]]

After selecting the preset Substance Painter should already recognize that it is an export preset.

[[File:Step4.png]]

In the dropdown window at the bottom right corner of the active window, you can select where you want to save it. You can either save this into your project file you are currently working on, or add it to your shelf. If you save it to your shelf you won't have to import it for every project, so this is the best method! After you are done, click Import.

[[File:Step5N.png]]

==Exporting Textures==

When you are ready to export your textures from your project, navigate at the top left to File -> Export Textures.

[[File:Step6.png]]

In this new window, select the dropdown window near "Config" and select your Trainz 2019 preset from the dropdown window. After you select which texture size you want to export or which materials to export, hit export and your textures will export! At the top of the window will be the directory where your textures will export to. In my case, it is exporting to K:\Class 47\Textures\game\lit up. You can change the directory by simply clicking on it.

[[File:Step7.png]]

That's all you have to do! These presets will support all PBR materials including pbrmetalmasked, and glass. However to use alphas you will need to enable opacity in the Texture Set Settings.

[[Category:Material types| ]]
[[Category:Modeling]]
[[Category:Content creation]]

M.glass

2021-02-03T06:43:16Z

Gdennish: /* Blender Material Configuration V2.8+ */

[[m.glass]] is a variation on the [[m.pbrmetal]] material. It adds a [[blended alpha]] channel to allow actual glass-like transparencies to be created. All PBR materials are defined using a multitude of texture channels (not just a simple RGB image) which define various aspects of the material on a per-texel basis. One major advantage of this approach is that a single in-game material can be used to display various different real-world materials, rather than requiring multiple separate in-game materials with different parameters. Trainz uses a Metallic/Roughness style PBR workflow.

This material should be used for creating glass and glass-like materials (eg. ice) only. This material has various limitations which make it unsuitable for general use. It is expected that this material will be enhanced over time to improve the glass-like effect, which will further compromise any meshes which attempt to misuse this material for non-glass surfaces. If cutout-style transparency is desired, [[m.pbrmetalmasked]] should be used instead. Foliage should use [[m.pbrmetalmasked]] or [[m.clutter]] with high-resolution geometry and/or texture maps to provide appropriate coverage, rather than attempting to fake coverage using blended alpha.

This page describes content format v4.6 and assumes that the FBX file format is used as a data source for any meshes.

=Texture Slots=
The following texture slots are used for this material. All textures should typically have the same dimensions unless they represent a uniform color, however this is not strictly enforced.

==Albedo==
RGB: The [[albedo map]] defines the base color of each texel. The sRGB color space is used.

'''Albedo Texture Example'''

[[File:Fire albedo.png|border|middle|x200px]]

A: The alpha channel provides a greyscale [[blended alpha]] channel. Black indicates full transparency. White indicates full opacity. Mid levels offer partial transparency. If the alpha channel is omitted, this material becomes fully opaque but still suffers from a number of drawbacks, unlike the truly opaque [[m.pbrmetal]]. Note that unlike legacy Trainz materials, PBR materials do not autodetect opacity mode based on the texture in use. The content creator must select the appropriate material for their desired outcome. Runtime texture replacement should not expect to replace an opaque texture with a blended or masked texture and have the material update automatically.

'''Alpha Texture Example'''

[[File:Fire alpha.png|border|middle|x200px]]

The full texture is available here: [[File:fire.tga]]

==Normal==
RGB: Surface [[normal map]]. This defines which way the surface is facing, relative to the interpolated vertex normals. Since this is an XYZ format rather than color data, it should never be modified in Photoshop. Using Photoshop to add a fourth channel or copy/paste smaller textures into a [[texture atlas]] is acceptable. Per-pixel manipulation or use of filters on the "RGB" channels is not acceptable.

A: [[Parallax Occlusion Map|Displacement height]]. 0.0 represents the deepest possible value, while 1.0 represents the shallowest possible value. While it is possible to paint this data in Photoshop, a linear color space must be used, and far superior results will be available through other data sources. The parallax height and the surface normal must be kept in sync, which means that a third-party tool must be used to generate the surface normal from the parallax height if you are painting this map manually.

'''Normal Texture Example with no Alpha Channel (Parallax)'''

[[File:pbrnormalmap1.jpg|border|middle|x200px]]

'''Normal Texture Example with Alpha Channel (Parallax)'''

[[File:pbrnormalwithalpha.jpg|border|middle|x200px]]

==Parameter==
This texture is comprised of four separate channels which each form a separate data element. Linear color space (not sRGB) is used for these channels.

[[File:pbrparametersall.jpg|border|middle|x200px]]

R: Emissive. This causes the texture to have an internal glow, even when no external light is present. Used for phosphors, permanently-lit markings, etc. The glow color is based on the albedo. Note that this glow does not cast light upon surrounding surfaces except via the Bloom post-processing effect.

'''Parameters (Emissive - Red Channel) Texture Example'''

[[File:pbrparametersemissivemap1.jpg|border|middle|x200px]]

G: Roughness. Defines whether the surface reflections are shiny (0.0) or matte (1.0). See the [[Physically Based Rendering|PBR metal workflow]] for details.

'''Parameters (Roughness - Green Channel) Texture Example'''

[[File:pbrparametersroughnessmap1.jpg|border|middle|x200px]]

B: Ambient Occlusion. Defines whether the surface is exposed to ambient lighting conditions (1.0) or affected only by direct lighting (0.0).

'''Parameters (Ambient Occlusion - Blue Channel) Texture Example'''

[[File:pbrparametersambientocclusionmap1.jpg|border|middle|x200px]]

A: Metallicity. Defines whether the surface is metallic (1.0) with the albedo used to colorize reflected light, or dielectric (0.0) with the albedo used to colorize the surface. While intermediate values are not physically accurate, they may be used to emulate subsurfaces which are partially metallic. See the [[Physically Based Rendering|PBR metal workflow]] for details.

'''Parameters (Metallic - Alpha Channel) Texture Example'''

[[File:pbrparametersmetallicmap1.jpg|border|middle|x200px]]

=Limitations=
As a truly transparent surface, [[m.glass]] offers excellent standalone visual quality but suffers from a number of drawbacks, including:
* Limited or no shadow-casting.
* Limited or no z-buffer writes.
* Limited capability to correctly resolve z-order against itself or other transparent surfaces.
* Lower performance.

These limitations are not considered defining characteristics of the material and may change in exact outcome based on changes to the underlying render technology. Minor rendering artifacts caused by these limitations are considered inevitable. Major artifacts (such as see-through walls or large objects with missing shadows) caused by these limitations are considered a content creation fault (eg. inappropriate use of this material where another material would have given a superior result; inappropriate use of a correct-but-limited asset while route building, etc.) and not an engine bug.

=Examples=

[[File:trainz_material_glass.jpg|border|middle|x512px]]

Example asset download:

[http://download.trainzportal.com/tutorials/Trainz_Material_-_glass.cdp Trainz Material - glass]

=3ds Max Material Configuration=

'''Texture Assignment'''

[[File:ConfigTextureMaxGlass.jpg]]

=Blender Material Configuration (2.7x)=
You must use the Blender Render option in Blender as the Cycles Render doesn't export the texture names associated with the material. The cycles option is still being investigated.

The albedo must have the "Use Alpha" and Influence->Diffuse->Alpha tag ticked. The normal does not require any special settings. The parameters texture must use the Influence->Specular->Hardness tag (checkbox). The value of the hardness is not exported by the Blender FBX exporter. Sample settings are shown below. All textures except the albedo are using png in this example because they do not require an Alpha channel.

[[File:BlenderFBXmglassAlbedo.png|border|middle|x700px]] [[File:BlenderFBXmglassNormal.png|border|middle|x700px]] [[File:BlenderFBXmglassparameter.png|border|middle|x700px]]

=Blender Material Configuration (2.8+)=

The shader node is a Principled BSDF shader and the FBX exporter supports the export of some texture names but not all. The following connections should be made:

Albedo texture to the Base Color input.

Parameter texture to the Roughness input.

The normal texture, via a normal converter set to Tangent, to the Normal input.

The 3D view of the mesh does not show a true PBR render.

You will need to update the texture.txt files created by the Trainz FBX importer.

[[File:Blender 2.80 shader export nodes.jpg|border|middle|x700px]]

[[Category:Material types| ]]
[[Category:Modeling]]
[[Category:Content creation]]

M.pbrmetalmasked

2021-02-03T06:43:07Z

Gdennish: /* Blender Material Configuration V2.8+ */

[[m.pbrmetalmasked]] is a minor variation on the [[m.pbrmetal]] material. It adds a [[masked alpha]] channel to allow a complex outline to be created without the use of large numbers of [[polygon]]s. All PBR materials are defined using a multitude of texture channels (not just a simple RGB image) which define various aspects of the material on a per-texel basis. One major advantage of this approach is that a single in-game material can be used to display various different real-world materials, rather than requiring multiple separate in-game materials with different parameters. Trainz uses a Metallic/Roughness style PBR workflow.

It should be noted that the "metal" in the name of this material refers to the physical property used in the lighting equations; it does not mean that the material is only appropriate for metallic surfaces.

On some hardware, [[masked alpha]] materials may perform substantially worse than an opaque material. This cost is per-[[fragment]], meaning that it may be suitable to use a masked material on low-[[Level of Detail|LOD]] meshes where polygon count must remain low and where fragment count is naturally low. On higher-LOD meshes, especially where the material is expected to fill a reasonable percentage of the screen, masked materials should be avoided in favor of higher polygon detail, or should be used in conjunction with true opaque materials such that the majority of opaque fragments are filled by the opaque materials and only the complex edge detail is filled by the masked material.

This page describes content format v4.6 and assumes that the FBX file format is used as a data source for any meshes.

=Texture Slots=
The following texture slots are used for this material. All textures should typically have the same dimensions unless they represent a uniform color, however this is not strictly enforced.

==Albedo==
RGB: The [[albedo map]] defines the base color of each texel. The sRGB color space is used.

A: The alpha channel provides a "black and white" [[masked alpha]] channel. Black indicates full transparency, meaning that the [[fragment]] is discarded. White indicates full opacity, meaning that rendering proceeds as per [[m.pbrmetal]]. If the alpha channel is omitted, this material acts exactly as [[m.pbrmetal]] except with lower performance. Note that unlike legacy Trainz materials, PBR materials do not autodetect opacity mode based on the texture in use. The content creator must select the appropriate material for their desired outcome. Runtime texture replacement should not expect to replace an opaque texture with a blended or masked texture and have the material update automatically.

'''Albedo Texture Example'''

[[File:PortalAlbedowAlpha.png|500px]]

Color Channel Separated

[[File:PortalAlbedo.png|500px]]

Alpha Channel Separated

[[File:PortalAlpha.png|500px]]

==Normal==
RGB: Surface [[normal map]]. This defines which way the surface is facing, relative to the interpolated vertex normals. Since this is an XYZ format rather than color data, it should never be modified in Photoshop. Using Photoshop to add a fourth channel or copy/paste smaller textures into a [[texture atlas]] is acceptable. Per-pixel manipulation or use of filters on the "RGB" channels is not acceptable.

A: [[Parallax Occlusion Map|Displacement height]]. 0.0 represents the deepest possible value, while 1.0 represents the shallowest possible value. While it is possible to paint this data in Photoshop, a linear color space must be used, and far superior results will be available through other data sources. The parallax height and the surface normal must be kept in sync, which means that a third-party tool must be used to generate the surface normal from the parallax height if you are painting this map manually.

'''Normal Texture Example with no Alpha Channel (Parallax)'''

[[File:pbrnormalmap1.jpg|border|middle|x200px]]

'''Normal Texture Example with Alpha Channel (Parallax)'''

[[File:pbrnormalwithalpha.jpg|border|middle|x200px]]

==Parameter==
This texture is comprised of four separate channels which each form a separate data element. Linear color space (not sRGB) is used for these channels.

[[File:pbrparametersall.jpg|border|middle|x200px]]

R: Emissive. This causes the texture to have an internal glow, even when no external light is present. Used for phosphors, permanently-lit markings, etc. The glow color is based on the albedo. Note that this glow does not cast light upon surrounding surfaces except via the Bloom post-processing effect.

'''Parameters (Emissive - Red Channel) Texture Example'''

[[File:pbrparametersemissivemap1.jpg|border|middle|x200px]]

G: Roughness. Defines whether the surface reflections are shiny (0.0) or matte (1.0). See the [[Physically Based Rendering|PBR metal workflow]] for details.

'''Parameters (Roughness - Green Channel) Texture Example'''

[[File:pbrparametersroughnessmap1.jpg|border|middle|x200px]]

B: Ambient Occlusion. Defines whether the surface is exposed to ambient lighting conditions (1.0) or affected only by direct lighting (0.0).

'''Parameters (Ambient Occlusion - Blue Channel) Texture Example'''

[[File:pbrparametersambientocclusionmap1.jpg|border|middle|x200px]]

A: Metallicity. Defines whether the surface is metallic (1.0) with the albedo used to colorize reflected light, or dielectric (0.0) with the albedo used to colorize the surface. While intermediate values are not physically accurate, they may be used to emulate subsurfaces which are partially metallic. See the [[Physically Based Rendering|PBR metal workflow]] for details.

'''Parameters (Metallic - Alpha Channel) Texture Example'''

[[File:pbrparametersmetallicmap1.jpg|border|middle|x200px]]

=Examples=

[[File:trainz_material_pbrmetalmasked.jpg|border|middle|x512px]]

Example asset download:

[http://download.trainzportal.com/tutorials/Trainz_Material_-_pbrmetalmasked.cdp Trainz Material - pbrmetalmasked + emissive]

=3ds Max Material Configuration=

'''Texture Assignment'''

[[File:kosl.png]]

=Blender Material Configuration (2.7x)=
You must use the Blender Render option in Blender as the Cycles Render doesn't export the texture names associated with the material. The cycles option is still being investigated.

The albedo must have the "Use Alpha" and Influence->Diffuse->Alpha tag ticked. The normal does not require any special settings. The parameters texture must use the Influence->Specular->Hardness tag (checkbox). The value of the hardness is not exported by the Blender FBX exporter. Sample settings are shown below. All textures except the albedo are using png in this example because they do not require an Alpha channel.

[[File:BlenderFBXmglassAlbedo.png|border|middle|x700px]] [[File:BlenderFBXmglassNormal.png|border|middle|x700px]] [[File:BlenderFBXmglassparameter.png|border|middle|x700px]]

=Blender Material Configuration (2.8+)=

The shader node is a Principled BSDF shader and the FBX exporter supports the export of some texture names but not all. The following connections should be made:

Albedo texture to the Base Color input.

Parameter texture to the Roughness input.

The normal texture, via a normal converter set to Tangent, to the Normal input.

The 3D view of the mesh does not show a true PBR render.

You will need to update the texture.txt files created by the Trainz FBX importer.

[[File:Blender 2.80 shader export nodes.jpg|border|middle|x700px]]

[[Category:Material types| ]]
[[Category:Modeling]]
[[Category:Content creation]]

M.pbrmetalmasked

2021-02-03T06:42:27Z

Gdennish: Updated Blender 2.7x settings with images, and added 2.8+ references

[[m.pbrmetalmasked]] is a minor variation on the [[m.pbrmetal]] material. It adds a [[masked alpha]] channel to allow a complex outline to be created without the use of large numbers of [[polygon]]s. All PBR materials are defined using a multitude of texture channels (not just a simple RGB image) which define various aspects of the material on a per-texel basis. One major advantage of this approach is that a single in-game material can be used to display various different real-world materials, rather than requiring multiple separate in-game materials with different parameters. Trainz uses a Metallic/Roughness style PBR workflow.

It should be noted that the "metal" in the name of this material refers to the physical property used in the lighting equations; it does not mean that the material is only appropriate for metallic surfaces.

On some hardware, [[masked alpha]] materials may perform substantially worse than an opaque material. This cost is per-[[fragment]], meaning that it may be suitable to use a masked material on low-[[Level of Detail|LOD]] meshes where polygon count must remain low and where fragment count is naturally low. On higher-LOD meshes, especially where the material is expected to fill a reasonable percentage of the screen, masked materials should be avoided in favor of higher polygon detail, or should be used in conjunction with true opaque materials such that the majority of opaque fragments are filled by the opaque materials and only the complex edge detail is filled by the masked material.

This page describes content format v4.6 and assumes that the FBX file format is used as a data source for any meshes.

=Texture Slots=
The following texture slots are used for this material. All textures should typically have the same dimensions unless they represent a uniform color, however this is not strictly enforced.

==Albedo==
RGB: The [[albedo map]] defines the base color of each texel. The sRGB color space is used.

A: The alpha channel provides a "black and white" [[masked alpha]] channel. Black indicates full transparency, meaning that the [[fragment]] is discarded. White indicates full opacity, meaning that rendering proceeds as per [[m.pbrmetal]]. If the alpha channel is omitted, this material acts exactly as [[m.pbrmetal]] except with lower performance. Note that unlike legacy Trainz materials, PBR materials do not autodetect opacity mode based on the texture in use. The content creator must select the appropriate material for their desired outcome. Runtime texture replacement should not expect to replace an opaque texture with a blended or masked texture and have the material update automatically.

'''Albedo Texture Example'''

[[File:PortalAlbedowAlpha.png|500px]]

Color Channel Separated

[[File:PortalAlbedo.png|500px]]

Alpha Channel Separated

[[File:PortalAlpha.png|500px]]

==Normal==
RGB: Surface [[normal map]]. This defines which way the surface is facing, relative to the interpolated vertex normals. Since this is an XYZ format rather than color data, it should never be modified in Photoshop. Using Photoshop to add a fourth channel or copy/paste smaller textures into a [[texture atlas]] is acceptable. Per-pixel manipulation or use of filters on the "RGB" channels is not acceptable.

A: [[Parallax Occlusion Map|Displacement height]]. 0.0 represents the deepest possible value, while 1.0 represents the shallowest possible value. While it is possible to paint this data in Photoshop, a linear color space must be used, and far superior results will be available through other data sources. The parallax height and the surface normal must be kept in sync, which means that a third-party tool must be used to generate the surface normal from the parallax height if you are painting this map manually.

'''Normal Texture Example with no Alpha Channel (Parallax)'''

[[File:pbrnormalmap1.jpg|border|middle|x200px]]

'''Normal Texture Example with Alpha Channel (Parallax)'''

[[File:pbrnormalwithalpha.jpg|border|middle|x200px]]

==Parameter==
This texture is comprised of four separate channels which each form a separate data element. Linear color space (not sRGB) is used for these channels.

[[File:pbrparametersall.jpg|border|middle|x200px]]

R: Emissive. This causes the texture to have an internal glow, even when no external light is present. Used for phosphors, permanently-lit markings, etc. The glow color is based on the albedo. Note that this glow does not cast light upon surrounding surfaces except via the Bloom post-processing effect.

'''Parameters (Emissive - Red Channel) Texture Example'''

[[File:pbrparametersemissivemap1.jpg|border|middle|x200px]]

G: Roughness. Defines whether the surface reflections are shiny (0.0) or matte (1.0). See the [[Physically Based Rendering|PBR metal workflow]] for details.

'''Parameters (Roughness - Green Channel) Texture Example'''

[[File:pbrparametersroughnessmap1.jpg|border|middle|x200px]]

B: Ambient Occlusion. Defines whether the surface is exposed to ambient lighting conditions (1.0) or affected only by direct lighting (0.0).

'''Parameters (Ambient Occlusion - Blue Channel) Texture Example'''

[[File:pbrparametersambientocclusionmap1.jpg|border|middle|x200px]]

A: Metallicity. Defines whether the surface is metallic (1.0) with the albedo used to colorize reflected light, or dielectric (0.0) with the albedo used to colorize the surface. While intermediate values are not physically accurate, they may be used to emulate subsurfaces which are partially metallic. See the [[Physically Based Rendering|PBR metal workflow]] for details.

'''Parameters (Metallic - Alpha Channel) Texture Example'''

[[File:pbrparametersmetallicmap1.jpg|border|middle|x200px]]

=Examples=

[[File:trainz_material_pbrmetalmasked.jpg|border|middle|x512px]]

Example asset download:

[http://download.trainzportal.com/tutorials/Trainz_Material_-_pbrmetalmasked.cdp Trainz Material - pbrmetalmasked + emissive]

=3ds Max Material Configuration=

'''Texture Assignment'''

[[File:kosl.png]]

=Blender Material Configuration (2.7x)=
You must use the Blender Render option in Blender as the Cycles Render doesn't export the texture names associated with the material. The cycles option is still being investigated.

The albedo must have the "Use Alpha" and Influence->Diffuse->Alpha tag ticked. The normal does not require any special settings. The parameters texture must use the Influence->Specular->Hardness tag (checkbox). The value of the hardness is not exported by the Blender FBX exporter. Sample settings are shown below. All textures except the albedo are using png in this example because they do not require an Alpha channel.

[[File:BlenderFBXmglassAlbedo.png|border|middle|x700px]] [[File:BlenderFBXmglassNormal.png|border|middle|x700px]] [[File:BlenderFBXmglassparameter.png|border|middle|x700px]]

=Blender Material Configuration V2.8+=

The shader node is a Principled BSDF shader and the FBX exporter supports the export of some texture names but not all. The following connections should be made:

Albedo texture to the Base Color input.

Parameter texture to the Roughness input.

The normal texture, via a normal converter set to Tangent, to the Normal input.

The 3D view of the mesh does not show a true PBR render.

You will need to update the texture.txt files created by the Trainz FBX importer.

[[File:Blender 2.80 shader export nodes.jpg|border|middle|x700px]]

[[Category:Material types| ]]
[[Category:Modeling]]
[[Category:Content creation]]

M.glass

2021-02-03T06:40:37Z

Gdennish: /* Blender Material Configuration */

[[m.glass]] is a variation on the [[m.pbrmetal]] material. It adds a [[blended alpha]] channel to allow actual glass-like transparencies to be created. All PBR materials are defined using a multitude of texture channels (not just a simple RGB image) which define various aspects of the material on a per-texel basis. One major advantage of this approach is that a single in-game material can be used to display various different real-world materials, rather than requiring multiple separate in-game materials with different parameters. Trainz uses a Metallic/Roughness style PBR workflow.

This material should be used for creating glass and glass-like materials (eg. ice) only. This material has various limitations which make it unsuitable for general use. It is expected that this material will be enhanced over time to improve the glass-like effect, which will further compromise any meshes which attempt to misuse this material for non-glass surfaces. If cutout-style transparency is desired, [[m.pbrmetalmasked]] should be used instead. Foliage should use [[m.pbrmetalmasked]] or [[m.clutter]] with high-resolution geometry and/or texture maps to provide appropriate coverage, rather than attempting to fake coverage using blended alpha.

This page describes content format v4.6 and assumes that the FBX file format is used as a data source for any meshes.

=Texture Slots=
The following texture slots are used for this material. All textures should typically have the same dimensions unless they represent a uniform color, however this is not strictly enforced.

==Albedo==
RGB: The [[albedo map]] defines the base color of each texel. The sRGB color space is used.

'''Albedo Texture Example'''

[[File:Fire albedo.png|border|middle|x200px]]

A: The alpha channel provides a greyscale [[blended alpha]] channel. Black indicates full transparency. White indicates full opacity. Mid levels offer partial transparency. If the alpha channel is omitted, this material becomes fully opaque but still suffers from a number of drawbacks, unlike the truly opaque [[m.pbrmetal]]. Note that unlike legacy Trainz materials, PBR materials do not autodetect opacity mode based on the texture in use. The content creator must select the appropriate material for their desired outcome. Runtime texture replacement should not expect to replace an opaque texture with a blended or masked texture and have the material update automatically.

'''Alpha Texture Example'''

[[File:Fire alpha.png|border|middle|x200px]]

The full texture is available here: [[File:fire.tga]]

==Normal==
RGB: Surface [[normal map]]. This defines which way the surface is facing, relative to the interpolated vertex normals. Since this is an XYZ format rather than color data, it should never be modified in Photoshop. Using Photoshop to add a fourth channel or copy/paste smaller textures into a [[texture atlas]] is acceptable. Per-pixel manipulation or use of filters on the "RGB" channels is not acceptable.

A: [[Parallax Occlusion Map|Displacement height]]. 0.0 represents the deepest possible value, while 1.0 represents the shallowest possible value. While it is possible to paint this data in Photoshop, a linear color space must be used, and far superior results will be available through other data sources. The parallax height and the surface normal must be kept in sync, which means that a third-party tool must be used to generate the surface normal from the parallax height if you are painting this map manually.

'''Normal Texture Example with no Alpha Channel (Parallax)'''

[[File:pbrnormalmap1.jpg|border|middle|x200px]]

'''Normal Texture Example with Alpha Channel (Parallax)'''

[[File:pbrnormalwithalpha.jpg|border|middle|x200px]]

==Parameter==
This texture is comprised of four separate channels which each form a separate data element. Linear color space (not sRGB) is used for these channels.

[[File:pbrparametersall.jpg|border|middle|x200px]]

R: Emissive. This causes the texture to have an internal glow, even when no external light is present. Used for phosphors, permanently-lit markings, etc. The glow color is based on the albedo. Note that this glow does not cast light upon surrounding surfaces except via the Bloom post-processing effect.

'''Parameters (Emissive - Red Channel) Texture Example'''

[[File:pbrparametersemissivemap1.jpg|border|middle|x200px]]

G: Roughness. Defines whether the surface reflections are shiny (0.0) or matte (1.0). See the [[Physically Based Rendering|PBR metal workflow]] for details.

'''Parameters (Roughness - Green Channel) Texture Example'''

[[File:pbrparametersroughnessmap1.jpg|border|middle|x200px]]

B: Ambient Occlusion. Defines whether the surface is exposed to ambient lighting conditions (1.0) or affected only by direct lighting (0.0).

'''Parameters (Ambient Occlusion - Blue Channel) Texture Example'''

[[File:pbrparametersambientocclusionmap1.jpg|border|middle|x200px]]

A: Metallicity. Defines whether the surface is metallic (1.0) with the albedo used to colorize reflected light, or dielectric (0.0) with the albedo used to colorize the surface. While intermediate values are not physically accurate, they may be used to emulate subsurfaces which are partially metallic. See the [[Physically Based Rendering|PBR metal workflow]] for details.

'''Parameters (Metallic - Alpha Channel) Texture Example'''

[[File:pbrparametersmetallicmap1.jpg|border|middle|x200px]]

=Limitations=
As a truly transparent surface, [[m.glass]] offers excellent standalone visual quality but suffers from a number of drawbacks, including:
* Limited or no shadow-casting.
* Limited or no z-buffer writes.
* Limited capability to correctly resolve z-order against itself or other transparent surfaces.
* Lower performance.

These limitations are not considered defining characteristics of the material and may change in exact outcome based on changes to the underlying render technology. Minor rendering artifacts caused by these limitations are considered inevitable. Major artifacts (such as see-through walls or large objects with missing shadows) caused by these limitations are considered a content creation fault (eg. inappropriate use of this material where another material would have given a superior result; inappropriate use of a correct-but-limited asset while route building, etc.) and not an engine bug.

=Examples=

[[File:trainz_material_glass.jpg|border|middle|x512px]]

Example asset download:

[http://download.trainzportal.com/tutorials/Trainz_Material_-_glass.cdp Trainz Material - glass]

=3ds Max Material Configuration=

'''Texture Assignment'''

[[File:ConfigTextureMaxGlass.jpg]]

=Blender Material Configuration (2.7x)=
You must use the Blender Render option in Blender as the Cycles Render doesn't export the texture names associated with the material. The cycles option is still being investigated.

The albedo must have the "Use Alpha" and Influence->Diffuse->Alpha tag ticked. The normal does not require any special settings. The parameters texture must use the Influence->Specular->Hardness tag (checkbox). The value of the hardness is not exported by the Blender FBX exporter. Sample settings are shown below. All textures except the albedo are using png in this example because they do not require an Alpha channel.

[[File:BlenderFBXmglassAlbedo.png|border|middle|x700px]] [[File:BlenderFBXmglassNormal.png|border|middle|x700px]] [[File:BlenderFBXmglassparameter.png|border|middle|x700px]]

=Blender Material Configuration V2.8+=

The shader node is a Principled BSDF shader and the FBX exporter supports the export of some texture names but not all. The following connections should be made:

Albedo texture to the Base Color input.

Parameter texture to the Roughness input.

The normal texture, via a normal converter set to Tangent, to the Normal input.

The 3D view of the mesh does not show a true PBR render.

You will need to update the texture.txt files created by the Trainz FBX importer.

[[File:Blender 2.80 shader export nodes.jpg|border|middle|x700px]]

[[Category:Material types| ]]
[[Category:Modeling]]
[[Category:Content creation]]

M.pbrmetal

2021-02-03T06:39:55Z

Gdennish: Edited Blender 2.8 references to not be in Beta

[[m.pbrmetal]] is the most basic PBR-based material type used in Trainz, and should be the default material type of choice for any mesh unless some specific feature of some other material type is required. All PBR materials are defined using a multitude of texture channels (not just a simple RGB image) which define various aspects of the material on a per-texel basis. One major advantage of this approach is that a single in-game [[material]] can be used to display various different real-world materials, rather than requiring multiple separate in-game materials with different parameters. Trainz uses a Metallic/Roughness style [[Physically Based Rendering|PBR workflow]].

It should be noted that the "metal" in the name of this material refers to the physical property used in the lighting equations; it does not mean that the material is only appropriate for metallic surfaces.

This page describes [["Trainz-build" number|content format v4.6]] and assumes that the [[FBX file format]] is used as a data source for any meshes.

=Texture Slots=
The following texture slots are used for this material. All textures should typically have the same dimensions unless they represent a uniform color, however this is not strictly enforced.

==Albedo==
RGB: The [[albedo map]] defines the base color of each texel. The sRGB color space is used.

Please note that there is no alpha channel support. For the most robust result, the alpha channel should be omitted or set to 1.0 (white). Note that unlike legacy Trainz materials, PBR materials do not autodetect opacity mode based on the texture in use. The content creator must select the appropriate material for their desired outcome. Runtime texture replacement should not expect to replace an opaque texture with a blended or masked texture and have the material update automatically.

'''Albedo Texture Example'''

[[File:pbralbedomap1.jpg|border|middle|x200px]]

==Normal==
RGB: Surface [[normal map]]. This defines which way the surface is facing, relative to the interpolated vertex normals. Since this is an XYZ format rather than color data, it should never be modified in Photoshop. Using Photoshop to add a fourth channel or copy/paste smaller textures into a [[texture atlas]] is acceptable. Per-pixel manipulation or use of filters on the "RGB" channels is not acceptable.

A: [[Parallax Occlusion Map|Displacement height]]. 0.0 represents the deepest possible value, while 1.0 represents the shallowest possible value. While it is possible to paint this data in Photoshop, a linear color space must be used, and far superior results will be available through other data sources. The parallax height and the surface normal must be kept in sync, which means that a third-party tool must be used to generate the surface normal from the parallax height if you are painting this map manually.

'''Normal Texture Example with no Alpha Channel (Parallax)'''

[[File:pbrnormalmap1.jpg|border|middle|x200px]]

'''Normal Texture Example with Alpha Channel (Parallax)'''

[[File:pbrnormalwithalpha.jpg|border|middle|x200px]]

==Parameter==
This texture is comprised of four separate channels which each form a separate data element. Linear color space (not sRGB) is used for these channels.

[[File:pbrparametersall.jpg|border|middle|x200px]]

R: Emissive. This causes the texture to have an internal glow, even when no external light is present. Used for phosphors, permanently-lit markings, etc. The glow color is based on the albedo. Note that this glow does not cast light upon surrounding surfaces except via the Bloom post-processing effect. You might want to consider making this a gray / dark gray color on some assets that you want more of the albedo color to show through indirect (ambient) lit surfaces.

'''Parameters (Emissive - Red Channel) Texture Example'''

[[File:pbrparametersemissivemap1.jpg|border|middle|x200px]]

G: Roughness. Defines whether the surface reflections are shiny (0.0) or matte (1.0). See the [[Physically Based Rendering|PBR metal workflow]] for details.

'''Parameters (Roughness - Green Channel) Texture Example'''

[[File:pbrparametersroughnessmap1.jpg|border|middle|x200px]]

B: Ambient Occlusion. Defines whether the surface is exposed to ambient lighting conditions (1.0) or affected only by direct lighting (0.0).

'''Parameters (Ambient Occlusion - Blue Channel) Texture Example'''

[[File:pbrparametersambientocclusionmap1.jpg|border|middle|x200px]]

A: Metallicity. Defines whether the surface is metallic (1.0) with the albedo used to colorize reflected light, or dielectric (0.0) with the albedo used to colorize the surface. While intermediate values are not physically accurate, they may be used to emulate subsurfaces which are partially metallic. See the [[Physically Based Rendering|PBR metal workflow]] for details.

'''Parameters (Metallic - Alpha Channel) Texture Example'''

[[File:pbrparametersmetallicmap1.jpg|border|middle|x200px]]

=Examples=
The following images show this material type with a few basic configurations of roughness and metallicity, under identical environmental conditions.

[[File:m.pbrmetal-0.png|border|middle|x200px]] [[File:m.pbrmetal-1.png|border|middle|x200px]] [[File:m.pbrmetal-2.png|border|middle|x200px]] [[File:m.pbrmetal-3.png|border|middle|x200px]]

[[File:trainz_material_cast_iron.jpg|border|middle|x512px]]

Example asset download:

[http://download.trainzportal.com/tutorials/Trainz_Material_-_pbrmetal_(cast_iron).cdp Trainz Material - pbrmetal (cast iron)]

[[File:trainz_material_gloss_paint.jpg|border|middle|x512px]]

Example asset download:

[http://download.trainzportal.com/tutorials/Trainz_Material_-_pbrmetal_(gloss_paint).cdp Trainz Material - pbrmetal (gloss paint)]

[[File:trainz_material_painted_metal.jpg|border|middle|x512px]]

Example asset download:

[http://download.trainzportal.com/tutorials/Trainz_Material_-_pbrmetal_(painted_metal).cdp Trainz Material - pbrmetal (painted metal)]

[[File:trainz_material_rubber.jpg|border|middle|x512px]]

Example asset download:

[http://download.trainzportal.com/tutorials/Trainz_Material_-_pbrmetal_(rubber).cdp Trainz Material - pbrmetal (rubber)]

[[File:trainz_material_stainless_steel.jpg|border|middle|x512px]]

Example asset download:

[http://download.trainzportal.com/tutorials/Trainz_Material_-_pbrmetal_(stainless_steel).cdp Trainz Material - pbrmetal (stainless steel)]

[[File:chart_roughness_metallic.jpg|border|middle|x512px]]

Example asset (route + objects) download:

[http://download.trainzportal.com/tutorials/pbr_roughness_metallic_chart_180831a.cdp PBR Roughness / Metallic Chart]

=3ds Max Material Configuration=

'''Texture Assignment'''

[[File:pbrmetal3dsmaxtextureassignment.jpg]]

=Blender Material Configuration V2.79b=

You must use the Blender Render option in Blender as the Cycles Render in V2.79b doesn't export the texture names associated with the material.

The albedo and normal textures have no special requirements but the parameters texture must use the Influence->Specular->Hardness tag (checkbox). The value of the hardness is not exported by the Blender FBX exporter. Sample settings are shown below. Note that the normal texture does not use an alpha channel in this example.

[[File:Blender_PBRMetal_albedo_setting.jpg|border|middle|x700px]] [[File:Blender_PBRMetal_normal_setting.jpg|border|middle|x700px]] [[File:Blender_PBRMetal_parameters_setting.jpg|border|middle|x700px]]

=Blender Material Configuration V2.8+=

The shader node is a Principled BSDF shader and the FBX exporter supports the export of some texture names but not all. The following connections should be made:

Albedo texture to the Base Color input.

Parameter texture to the Roughness input.

The normal texture, via a normal converter set to Tangent, to the Normal input.

The 3D view of the mesh does not show a true PBR render.

You will need to update the texture.txt files created by the Trainz FBX importer.

[[File:Blender 2.80 shader export nodes.jpg|border|middle|x700px]]

=Maya LT Material Configuration=

Maya LT uses a Phong shader and the parameters texture should be linked to the shader Cosine Power input via a Set Range node. Note that the input and output of this node both use Value X. The Normal Map must be passed through a Bump converter and then connected to the shader Normal input. The Bump converter "Use as" value within the attributes editor must use the "Tangent Space Normals" option. See the images below.

''Note. The material name shown in these images has "FBXASC046" where the full stops (periods) appear in the name box.m.pbrmetal. Maya LT does not permit full stops (periods) in name and substitutes an underscore which doesn't work for Trainz. FBXASC046 gets replaced with a full stop on export. N3V are looking at this issue.''

[[File:Sample_pbrmetal_material.jpg|border|middle]]
[[File:Sample_pbrmetal_material_properties.jpg|border|middle]] [[File:Bump_normal_converter_properties.jpg|border|middle]]

=Substance Painter Export Preset=

Export preset for Substance Painter. This preset puts every map you need into Albedo, Normal and Parameter texture channels. As result you will get 3 textures, ready for importing into game.

The link below is a preset that has height maps enabled by default.

[https://www.dropbox.com/s/ukp3p8uw53332ay/Trainz2019_WithHeight.spexp?dl=0 Trainz 2019 Exporter with Height Maps Enabled]

The link below contains a preset that does not have height maps enabled, which may be more useful to some on rollingstock.

[https://www.dropbox.com/s/4gzmuzdy8g7nwzc/Trainz2019.spexp?dl=0 Trainz 2019 Exporter with Height Maps Disabled]

==Installing the Preset==

First download either or both presets to your computer from the links above. Open Substance Painter and navigate to File -> Import Resources.

[[File:Step2.png]]

At the top of the new window, click on "Add resources." Then locate your preset you'd like to import.

[[File:Step3.png]]

After selecting the preset Substance Painter should already recognize that it is an export preset.

[[File:Step4.png]]

In the dropdown window at the bottom right corner of the active window, you can select where you want to save it. You can either save this into your project file you are currently working on, or add it to your shelf. If you save it to your shelf you won't have to import it for every project, so this is the best method! After you are done, click Import.

[[File:Step5N.png]]

==Exporting Textures==

When you are ready to export your textures from your project, navigate at the top left to File -> Export Textures.

[[File:Step6.png]]

In this new window, select the dropdown window near "Config" and select your Trainz 2019 preset from the dropdown window. After you select which texture size you want to export or which materials to export, hit export and your textures will export! At the top of the window will be the directory where your textures will export to. In my case, it is exporting to K:\Class 47\Textures\game\lit up. You can change the directory by simply clicking on it.

[[File:Step7.png]]

That's all you have to do! These presets will support all PBR materials including pbrmetalmasked, and glass. However to use alphas you will need to enable opacity in the Texture Set Settings.

[[Category:Material types| ]]
[[Category:Modeling]]
[[Category:Content creation]]

Adding the TRS19 F7 Cabin to your Asset

2020-08-27T00:02:19Z

Gdennish: /* Modifying the Nose color */

The new TRS19 EMD F7 cabin has the ability to change the color of the nose to match the road name of your locomotive asset. Changing the color of the nose is as simple as adding a few lines into the config of your locomotive of choice.

[[File:F7IntroPage.png|800px]]

== Adding the Cab to your Asset ==

To begin, open the config of the locomotive you wish to have a custom nose color for. For this tutorial, we will be using <kuid2:999999:2222:1> 1 Hot Rod Special F7 from the DLS. It is recommended to open the config in a superior notepad program such as Notepad++ to preserve formatting. When the config for the Hot Rod F7 is opened, it looks something like this:

kuid <kuid2:999999:2222:1>
username "1 Hot Rod Special F7"
kind "traincar"
trainz-build 3.5
engine 1
enginespec <kuid:999999:42004250>
enginesound <kuid:-1:42003000>
hornsound <kuid:37581:1234>
interior <kuid:217537:220>
mesh-table
{
default
{
mesh "f7_hotrod_body/f7_hotrod_body.im"
auto-create 1
}

shadow
{
mesh "f7_hotrod_shadow/f7_hotrod_shadow.im"
}
}
bogeys
{
0
{
bogey <kuid:999999:100100>
reversed 0
}
}
mass 100000
company "Auran Brew Crew"
fonts 0
smoke_shade 0.5
smoke_random 2.6
smoke_slowlife 5
smoke_fastlife 4
smoke_height 2.3
smoke_fastspeed 100
category-class "AC"
category-era "2000s"
category-region "AU"
description ""
author "Brew Crew Productions"
organisation "Auran Games Pty. Ltd."
contact-website "www.virtualtrainz.com"
contact-email "helpdesk@auran.com"
thumbnails
{
0
{
image "$screenshot$.jpg"
width 240
height 180
}
1
{
image "f7_hotrod_art\f7_hotrod_art_icon.texture"
width 128
height 64
}
}
kuid-table
{
0 <kuid:-1:101212>
1 <kuid:-1:42003000>
2 <kuid:-1:42003101>
3 <kuid:999999:100100>
4 <kuid:999999:42004250>
}

The first thing to change is the interior kuid to reference the proper F7 cab. If your locomotive is right-hand drive and uses MPH, use the following kuid:
<kuid:-25:1308>

Change the following line from:
interior <kuid:217537:220>
to:
interior <kuid:-25:1308>

The next step is to add an extensions table. Copy and paste the following code into your config:

extensions
{
f7cab_parameters
{
nosecolor "XXX"
}
}

The placement of this code does not matter. I placed it directly under the interior tag line and above the mesh table to make editing the extensions easier to edit in the future.

kuid <kuid2:999999:2222:1>
username "1 Hot Rod Special F7"
kind "traincar"
trainz-build 3.5
engine 1
enginespec <kuid:999999:42004250>
enginesound <kuid:-1:42003000>
hornsound <kuid:37581:1234>
interior <kuid:217537:220>
extensions
{
f7cab_parameters
{
nosecolor "XXX"
}
}
mesh-table
{
default
{
mesh "f7_hotrod_body/f7_hotrod_body.im"
auto-create 1
}

shadow
{
mesh "f7_hotrod_shadow/f7_hotrod_shadow.im"
}
}

....

== Modifying the Nose color ==

The final step is to change "XXX" to an appropriate string. Use the first column in the following table to determine the proper string to replace "XXX" with. The strings are case sensitive, so make sure it matches the table or else the cabin will default to black.

By default, the F7 Cab supports these pre-built liveries:
{| class="wikitable"
|+Supported Road names
|-
|String '''(case sensitive!)'''
|Color
|Roadname
|-
|red
|Red
|Generic Red
|-
|superchief
|Red with Yellow Stripe
|ATSF Warbonnet
|-
|darkblue
|Dark Blue with Yellow Stripe
|ATSF Blue Warbonnet
|-
|green
|Green
|Burlington Northern
|-
|orange
|Orange/Green
|Great Northern
|-
|yellow
|Yellow
|North Western/Alaska
|-
|lightgrey
|Light Grey
|Canadian Pacific
|-
|blackred
|Red with black nose top
|Canadian National / CP Rail
|-
|winetrain
|Green/Gold
|Nappa Valley Wine Train
|-
|silver
|Silver/Black
|Southern Pacific
|-
|unionpacific
|Yellow with Green nose top
|Union Pacific
|-
|darkgrey
|Dark Grey with Dark Blue nose top
|Baltimore and Ohio
|-
|amtrakphase1
|Black/Red/White
|Amtrak Phase I
|-
|hotrod
|Black with Flames
|Hot Rod Special
|-
|prr_red_5stripe
|PRR Tuscan with 5 Stripe
|Pennsylvania Railroad
|-
|prr_red_1stripe
|PRR Tuscan with 1 Stripe
|Pennsylvania Railroad
|-
|prr_green_5stripe
|PRR Brunswick with 5 Stripe
|Pennsylvania Railroad
|-
|prr_green_1stripe
|PRR Brunswick with 1 Stripe
|Pennsylvania Railroad
|}

The final config would look something like this:

kuid <kuid2:999999:2222:1>
username "1 Hot Rod Special F7"
kind "traincar"
trainz-build 3.5
engine 1
enginespec <kuid:999999:42004250>
enginesound <kuid:-1:42003000>
hornsound <kuid:37581:1234>
interior <kuid:217537:220>
extensions
{
f7cab_parameters
{
nosecolor "hotrod"
}
}
mesh-table
{
default
{
mesh "f7_hotrod_body/f7_hotrod_body.im"
auto-create 1
}

shadow
{
mesh "f7_hotrod_shadow/f7_hotrod_shadow.im"
}
}
bogeys
{
0
{
bogey <kuid:999999:100100>
reversed 0
}
}
mass 100000
company "Auran Brew Crew"
fonts 0
smoke_shade 0.5
smoke_random 2.6
smoke_slowlife 5
smoke_fastlife 4
smoke_height 2.3
smoke_fastspeed 100
category-class "AC"
category-era "2000s"
category-region "AU"
description ""
author "Brew Crew Productions"
organisation "Auran Games Pty. Ltd."
contact-website "www.virtualtrainz.com"
contact-email "helpdesk@auran.com"
thumbnails
{
0
{
image "$screenshot$.jpg"
width 240
height 180
}
1
{
image "f7_hotrod_art\f7_hotrod_art_icon.texture"
width 128
height 64
}
}
kuid-table
{
0 <kuid:-1:101212>
1 <kuid:-1:42003000>
2 <kuid:-1:42003101>
3 <kuid:999999:100100>
4 <kuid:999999:42004250>
}

==Return to Index==

[[HowToGuides|<< How To Guides]]

[[Category:How-to guides]]

Class Train

2020-08-19T22:48:05Z

Gdennish: Added Train Physics Mode constants (DCC, Cab mode)

*[[TrainzScript Language Reference|API Hierarchy]]
**[[Class GSObject|GSObject]] *
***[[Class GameObject|GameObject]]
****Train

 
*A train is a collection of vehicles in TRS.
*They act as a single entity and may be controlled using this class.
*A train is placed on a track in script by using [[Class World#CreateTrain|World.CreateTrain()]] or [[Class TrainUtil#CreateTrainFromSoup|TrainUtil.CreateTrainFromSoup()]].
*Trainz will automatically create a Train object for each consist that appears in the game.
*When an existing train is uncoupled and split up into two separate consists a new train object is created.
*Similarly when two trains couple one of the train objects is destroyed.
 

==Messages==
*Messages sent to and from Train objects are listed below:
 
{{TableHeader|width=50%|margin=15px}}
|-
|bgcolor="#EEEEEE"|'''Major'''||bgcolor="#EEEEEE"|'''Minor'''||bgcolor="#EEEEEE"|'''Source'''||bgcolor="#EEEEEE" |'''Destination'''
|-
|Schedule||Abort||Train||Train
|-
|Schedule||Complete||Train||Broadcast
|-
|Schedule||Touch||Train||Train
|-
|[[Train Messages|Train]]||Deleted||Train||
|-
|[[Signal Messages|Train]]||Entered red signal notify||Train||Broadcast
|-
|[[Signal Messages|Train]]||Entered red signal||Signal||Train
|-
|[[Object Messages|Train]]||EnterTrack||Track||Train
|-
|[[Object Messages|Train]]||InnerEnterTrack||Track||Train
|-
|[[Object Messages|Train]]||InnerLeaveTrack||Track||Train
|-
|[[Object Messages|Train]]||LeaveTrack||Track||Train
|-
|[[Train Messages|Train]]||Over advisory speed limit||Train||Broadcast
|-
|[[Train Messages|Train]]||Over floating speed limit||Train||Broadcast
|-
|[[Train Messages|Train]]||Over speed limit||Train||Broadcast
|-
|[[Train Messages|Train]]||ReachedTarget||Train||Train
|-
|[[Train Messages|Train]]||SlowingForTarget||Train||Train
|-
|[[Train Messages|Train]]||StartedMoving||Train||Train
|-
|[[Train Messages|Train]]||StoppedMoving||Train||Train
|-
|[[Train Messages|Train]]||Under advisory speed limit||Train||Broadcast
|-
|[[Train Messages|Train]]||Under floating speed limit||Train||Broadcast
|-
|[[Train Messages|Train]]||Under speed limit||Train||Broadcast
|}
 

==Constants==
 
===Train Control Modes===
 
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int CONTROL_MANUAL = 1||User controls train, script can change settings.
|-
|public define int CONTROL_AUTOPILOT = 2||Autopilot controls train.
|-
|public define int CONTROL_AUTOMANUAL = 3||User controls train, autopilot takes over when train is not currently 'focused'.
|-
|public define int CONTROL_SCRIPT = 4||Only the script can control the train.
|}
 
===Train Physics Modes===
 
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int PHYSICS_DCC = 1||DCC mode.
|-
|public define int PHYSICS_SIMULATION = 2||Cab mode.
|}
 
===Reverser Traction Modes===
 
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int TRACTION_FORWARD = 2||Reverse is in forward setting.
|-
|public define int TRACTION_NEUTRAL = 1||Reverser is in neutral.
|-
|public define int TRACTION_REVERSE = 0||Reverser is in reverse.
|}
 
===Train Brake Modes===
 
{{TableHeader|width=95%|margin=15px}}
|width=375|public define float TRAIN_BRAKE_RELEASE = 0.0||Train brakes are released.
|-
|public define float TRAIN_BRAKE_INITIAL = 1.0||Train brakes are in initial mode.
|-
|public define float TRAIN_BRAKE_APPLICATION = 2.0||Train brakes are applied.
|-
|public define float TRAIN_BRAKE_HANDLE_OFF = 3.0||Train brake handle is off.
|-
|public define float TRAIN_BRAKE_EMERGENCY = 4.0||Train brakes are in emergency stop position.
|-
|public define float TRAIN_BRAKE_LAP = 5.0||Train brakes are in the lap position, not available for all trains.
|}
 
===Dynamic Brake States===
 
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int DYNAMIC_BRAKE_TRACTION = 0||Dynamic brakes in traction mode.
|-
|public define int DYNAMIC_BRAKE_NEUTRAL = 1 ||Dynamic brakes in neutral.
|-
|public define int DYNAMIC_BRAKE_BRAKE = 2 ||Dynamic brakes are on.
|}
 

===Found Results===
 
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int RESULT_NONE = 0||Item not found.
|-
|public define int RESULT_FORWARD = 1||Item is in front of train.
|-
|public define int RESULT_INSIDE = 2||Item is within the train, ie between the front and the rear limits.
|-
|public define int RESULT_BACKWARD = 3||Item is behind the train.
|}
 
===Measurement Conversion Multipliers===
 
{{TableHeader|width=95%|margin=15px}}
|width=375|public define float KPH_TO_MPS = 0.278||Kilometres per hour -> Metres per second.
|-
|public define float MPH_TO_MPS = 0.447||Miles per hour -> Metres per second.
|-
|public define float MPH_TO_KPH = 1.609||Miles per hour -> Kilometres per hour.
|}
 

==Members==
 
{{TableHeader|width=95%|margin=15px}}
|width=375|public Browser timeTableInfo||A publicly accessible Browser object for timetable information.
|}
 
==Methods==
 

===AddVelocity===
{{MethodHeader|public native void AddVelocity(float velocity)}}
;Parameters
*'''velocity''' = Velocity to add to the current speed of the train.
;Returned Value
*None
;Syntax
train.AddVelocity(5.0);
;Notes
*Velocity parameter must be in metres per second and may be negative.
*Use the [[#Measurement Conversion Multipliers|Measurement Conversion Multipliers]] to convert from other units.
 

===ClearTrainTimetable===
{{MethodHeader|public void ClearTrainTimetable(ScenarioBehavior rule)}}
;Parameters
*'''rule''' = rule that called [[#SetTrainTimetable|SetTrainTimetable()]] on this train.
;Returned Value
*None
;Syntax
train.ClearTimeTable(timetableRule);
;Notes
*Clears the train timetable of this train.
*Having cleared the TrainTimetable, it is now safe again to set another TrainTimetable for this train through [[#SetTrainTimetable|SetTrainTimetable()]].
*This method must only be called by the rule which called SetTrainTimetable() in the first place.
*It is the responsibility of the caller to post a (TrainTimetable, Touch) message after calling this function.
 

===DecTrainBusy===
{{MethodHeader|public void DecTrainBusy(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.DecTrainBusy();
;Notes
*Decrements this train's busy count.
*See [[#IsTrainBusy|IsTrainBusy()]] for further details.
 

===Derail===
{{MethodHeader|public native void Derail(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.Derail();
;Notes
*Deliberately derails the train.
 

===EnablePhysics===
{{MethodHeader|public native void EnablePhysics(bool enable)}}
;Parameters
*'''enable''' = True to enable physics calculations for this train, false to disable
;Returned Value
*None
;Syntax
train.EnablePhysics(false);
;Notes
*Turning physics off for scenic rolling stock that the player cannot interact with can boost performance.
*There is no point in doing physic calculations for idle rollingstock.
 

===GetActiveDriver===
{{MethodHeader|public native DriverCharacter GetActiveDriver(void)}}
;Parameters
*None
;Returned Value
*The active driver of this train, null if there is no driver assigned.
;Syntax
DriverCharacter driver = train.GetActiveDriver();
;Notes
*There may be more than one driver on a train but there is only one active driver and an individual Locomotive may only have one driver assigned.
 

===GetAdvisoryLimit===
{{MethodHeader|public native float GetAdvisoryLimit(void)}}
;Parameters
*None
;Returned Value
*The current advisory speed limit set by script.
;Syntax
float speed = train.GetAdvisoryLimit();
;Notes
 

===GetAllowsUserContol===
{{MethodHeader|public native bool GetAllowsUserControl(void)}}
;Parameters
*None
;Returned Value
*True if this train allows the user to control it directly through DCC or Cabin interfaces, false otherwise.
;Syntax
bool canDrive =train.getAllowsUserControl();
;Notes
 

===GetAutopilotMode===
{{MethodHeader|public native int GetAutopilot Mode(void)}}
;Parameters
*None
;Returned Value
*One of the [[#Train Control Modes|Train Control Mode]] constants defining the method by which the train is currently controlled.
;Syntax
int controlMode = train.GetAutopilotMode();
;Notes
 

===GetAutopilotStopJunctionBase===
{{MethodHeader|public native JunctionBase GetAutopilotStopJunctionBase(void)}}
;Parameters
*None
;Returned Value
*The junction object that is preventing the autopilot from taking this train any further, null if the train is not stopped by a junction.
;Syntax
JunctionBase junction = train GetAutopilotStopJunctionBase();
;Notes
 

===GetAutopilotStopTrain===
{{MethodHeader|public native Train GetAutopilotStopTrain(void)}}
;Parameters
*None
;Returned Value
*The train that is preventing the autopilot from taking this train any further, null if the train is not being held up by another train.
;Syntax
Train otherTrain = train.GetAutopilotStopTrain();
;Notes
 

===GetAutopilotTargetSlowing===
{{MethodHeader|public native bool GetAutopilotTargetSlowing(void)}}
;Parameters
*None
;Returned Value
*True if the autopilot is slowing down for its target destination, false otherwise.
;Syntax
bool isSlowing = train.GetAutopilotTargetSlowing();
;Notes
 

===GetDCCThrottle===
{{MethodHeader|public native float GetDCCThrottle(void)}}
;Parameters
*None
;Returned Value
*The DCC throttle setting for this train when using DCC physics.
;Syntax
float throttle = GetDCCThrottle();
;Notes
*The returned value will be in the range [-1.0 .. 1.0] where -1.0 is full throttle in reverse, 0.0 is stationary and 1.0 is full throttle forward.
 

===GetFrontmostLocomotive===
{{MethodHeader|public native Locomotive GetFrontmostLocomotive(void)}}
;Parameters
*None
;Returned Value
*Returns a reference to the frontmost locomotive in the train.
;Syntax
Loco = Train.GetFrontmostLocomotive();
;Notes
*The ''front'' of the train is defined relative to the train's current heading.??
*The train's heading may not correspond to its physical appearance and can change during game play.
 

===GetHeadlightState===
{{MethodHeader|public native bool GetHeadlightState(void)}}
;Parameters
*None
;Returned Value
*True if headlights are turned on, false otherwise.
;Syntax
bool lights = train.GetHeadlightState();
;Notes
*Only the frontmost locomotive will display headlighs.
 

===GetLastVisitedBuildable===
{{MethodHeader|public Buildable GetLastVisitedBuildable(void)}}
;Parameters
*None
;Returned Value
*The last [[Class Buildable|Buildable]] object visited by this train, null if there have been no such visits.
;Syntax
Buildable buildable = train.GetLastVisitedBuildable();
;Notes
 

===GetLastVisitedIndustry===
{{MethodHeader|public Industry GetLastVisitedIndustry(void)}}
;Parameters
*None
;Returned Value
*The last Industry object visited by this train, null if there have been no such visits.
;Syntax
Industry industry = train.GetLastVisitedIndustry();
;Notes
 

===GetLastVisitedTrack===
{{MethodHeader|public Track GetLastVisitedTrack(void)}}
;Parameters
*None
;Returned Value
*The last track segment visited by this train.
;Syntax
Track track = train.GetLastVisitedTrack();
;Notes
*Note that the returned value may be null. How is that possible?
 

===GetHighBeams===
{{MethodHeader|public bool GetHighBeams(void)}}
;Parameters
*None
;Returned Value
*True if the frontmost locomotive's high beams are on, false otherwise.
;Syntax
bool High_Lights = train.GetHighBeams();
;Notes
*See also [[Class Vehicle#GetHighBeams|Vehicle.GetHighBeams()]]
 

===GetMaximumCouplingStressVehicle===
{{MethodHeader|public native Vehicle GetMaximumCouplingStressVehicle(void)}}
;Parameters
*None
;Returned Value
*The Vehicle in this consist that is experiencing the greatest level of coupling stress.
;Syntax
Vehicle vehicle = GetMaximumCouplingStressVehicle();
;Notes
 

===GetPantographState===
{{MethodHeader|public native int GetPantographState(void)}}
;Parameters
*None
;Returned Value
*The state of the pantographs of the electric locomotives in this train.
;Syntax
int pantoState = train.GetPantographState();
;Notes
*The returned value will be in the range [0..3] where:
**0 = Both pantographs down.
**1 = Front pantograph up.
**2 = Rear pantograph up.
**3 = Both pantographs up.
 

===GetPhysicsModel===
{{MethodHeader|public native int GetPhysicsModel(void)}}
;Parameters
*None
;Returned Value
*The mode of control chosen by the player to drive the locomotive
;Syntax
int Mode = train.GetPhysicsModel();
;Notes
*The returned value will be :
**2 = CabinControl
**1 = DCCMode
 

===GetSmoothedVelocity===
{{MethodHeader|public native float GetSmoothedVelocity(void)}}
;Parameters
*None
;Returned Value
*Returns a smoothed velocity, intended for human consumption.
;Syntax
float speed = train.GetSmoothedVelocity();
;Notes
*If you require an accurate velocity readout for physics operations, use [[#GetVelocity|GetVelocity()]].
*''In practice, even when the train stops completely, it does not report an absolute zero.''
 

===GetSpeedLimit===
{{MethodHeader|public native float GetSpeedLimit(void)}}
;Parameters
*None
;Returned Value
*The current sign posted speed limit.
;Syntax
float permittedSpeed = train.GetSpeedLimit();
;Notes
*The speed limit is dependent on trackside signs placed in Surveyor as well as the direction of the train.
*A default value applies to track that isn't sign posted.
 

===GetTrackmarkDirection===
{{MethodHeader|public native int GetTrackmarkDirection(TrackMark mark)}}
;Parameters
*'''mark''' = A reference to the Trackmark to search for.
;Returned Value
* One of the [[#Found Results|Found Result]] values representing the location of the given track mark relative to this train.
;Syntax
int location = train.GetTrackmarkDirection(trackmark);
;Notes
 

===GetTrainBrakes===
{{MethodHeader|public native float GetTrainBrakes(void)}}
;Parameters
*None
;Returned Value
*One of the [[#Train Brake Modes|Train Brake mode]] constants indicating the current state of this train's brakes.
;Syntax
float brakeState = train.GetTrainBrakes();
;Notes
 

===GetTrainDisplayName===
{{MethodHeader|public native string GetTrainDisplayName(void)}}
;Parameters
*None
;Returned Value
*A localised display name for this train.
;Syntax
string trainName = train.GetTrainDisplayName();
;Notes
*This will be a name Trainz has created for the consist such as "Consist 0" and will match the description shown in the Minimap view.
 

===GetTrainPriorityNumber===
{{MethodHeader|public native int GetTrainPriorityNumber(void)}}
;Parameters
*None
;Returned Value
*Train priority value in the range [1 .. 3]
;Syntax
int priority = train.GetTrainPriorityNumber();
;Notes
*See [[#SetTrainPriority|SetTrainPriority()]] for further details.
 

===GetTrainTimetable===
{{MethodHeader|public TrainTimetable GetTrainTimetable(void)}}
;Parameters
*None
;Returned Value
*The TrainTimetable that the train is currently using, null if there is none.
;Syntax
TrainTimetable timetable = train.GetTrainTimetable();
;Notes
 

===GetTrainVelocity===
{{MethodHeader|public native float GetTrainVelocity(void)}}
;Parameters
*None
;Returned Value
*The train's current velocity in metres per second.
;Syntax
float speed = train.GetTrainVelocity();
;Notes
* This function provides the instantaneous velocity for vehicles in this train, which is good for physics calculations but not good for human-readable display. If you want human-readable display, use [[#GetSmoothedVelocity|GetSmoothedVelocity()]] instead.
 

===GetVehicles===
{{MethodHeader|public native Vehicle[ ] GetVehicles(void)}}
;Parameters
*None
;Returned Value
*Returns an array consisting of all the vehicles making up this train.
;Syntax
Vehicle[] vehicles = train.GetVehicles();
;Notes
*GetVehicles[0] is always the front vehicle of the train relative to the train's current heading.
*The train's heading may not correspond to its physical appearance and can change during game play.
 

===GetVelocity===
{{MethodHeader|public native float GetVelocity(void)}}
;Parameters
*None
;Returned Value
*The train's current velocity.
;Syntax
float speed = train.GetVelocity();
;Notes
*Warning! The TS10 and TS12 Train.gs scripts advise this method is buggy and to use [[#GetSmoothedVelocity|GetSmoothedVelocity()]] or [[#GetTrainVelocity|GetTrainVelocity()]] instead.
*This function provides the instantaneous velocity for vehicles in this train, which is good for physics calculations but not good for human-readable display.
 

===HasReachedInnerJunctionRadius===
{{MethodHeader|public bool HasReachedJunctionInnerJunctionRadius(JunctionBase junction)}}
;Parameters
*'''junction''' = JunctionBase object to query.
;Returned Value
*True if this train is within the inner radius of the given junction, false otherwise.
;Syntax
bool arrived = train.HasReachedInnerJunctionRadius(junction10);
;Notes
 

===HasTrainTimetable===
{{MethodHeader|public bool HasTrainTimetable(void)}}
;Parameters
*None
;Returned Value
*True if this train has an attached TrainTimetable, false otherwise.
;Syntax
bool timed = train.HasTrainTimetable();
;Notes
 

===IsScheduleRunning===
{{MethodHeader|public bool IsScheduleRunning(void)}}
;Parameters
*None
;Returned Value
*True if this train is currently running to a Schedule, false otherwise.
;Syntax
bool scheduled = train.IsScheduleRunning();
;Notes
 

===IsScheduleWindowVisible===
{{MethodHeader|public bool IsScheduleWindowVisible(void)}}
;Parameters
*None
;Returned Value
*True if the schedule window for this train is currently open, false otherwise.
;Syntax
bool windowOpen = IsScheduleWindowVisible();
;Notes
 

===IsStillInJunction===
{{MethodHeader|public bool IsStillInJunction(JunctionBase junction)}}
;Parameters
*'''junction''' = JunctionBase object to query.
;Returned Value
*True if the train holds a Permit for the given junction, flse otherwise.
;Syntax
bool inJunction = train.IsStillInJunction(junction10);
;Notes
 

===IsStopped===
{{MethodHeader|public native bool IsStopped(void)}}
;Parameters
*None
;Returned Value
*True if the train is currently stationary, false if it is in motion.
;Syntax
bool moving=train.IsStopped();
;Notes
 

===IsTrainBusy===
{{MethodHeader|public bool IsTrainBusy(void)}}
;Parameters
*None
;Returned Value
*True if the train's 'busy' count is greater than zero, false otherwise.
;Syntax
bool busy = train.IsTrainBusy();
;Notes
*Using the [[#IncTrainBusy|IncTrainBusy()]] method, any piece of script code can tag a train being busy.
*The train can be untagged later by calling DecTrainBusy().
*This mechanism is mainly used by industries that are doing something with the train.
*A train can be tagged as being busy more than once by calling IncTrainBusy() multiple times so different industries can tag the train.
*Each time IncTrainBusy() is called, an internal busy count is incremented and if that busy count is greater than zero, the train is considered busy.
 

===IsViewDetailsVisible===
{{MethodHeader|public bool IsViewDetailsVisible(void)}}
;Parameters
*None
;Returned Value
*true if the ViewDetails window for this train is visible, false otherwise.
;Syntax
bool visible = train.IsViewDetailsVisible();
;Notes
 

===MapObjectIsInFront===
{{MethodHeader|public bool MapObjectIsInFront(MapObject obj, float range)}}
;Parameters
*'''obj''' = MapObject to search for.
*'''range''' = Maximum search distance.
;Returned Value
*True if the object is found within the specified distance and in front of the train, false otherwise.
;Syntax
bool isClose = train.MapObjectIsInFront(terminus,100.0);
;Notes
 

===ReleaseTrackPermits===
{{MethodHeader|public void ReleaseTrackPermits(Permit[ ] permitList)}}
;Parameters
*'''permitList''' = Permit array containing a list of permits to release.
;Returned Value
*None
;Syntax
train.ReleaseTrackPermits(permitList);
;Notes
*This method will release any permits from the ''permitList'' array that are currently held by this train.
*Any other permits in the array that are not held by this train will be ignored.
 

===RunSchedule===
{{MethodHeader|public thread void RunSchedule(Schedule schedule, bool loop, float delay)}}
;Parameters
*'''schedule''' = The Schedule that the train is to follow.
*'''loop''' = False to run the schedule once, True to repeat it continuously.
*'''delay''' = Time in seconds to wait before starting the schedule.
;Returned Value
*None
;Syntax
train.RunSchedule(schedule,false,10.0);
;Notes
*See [[Class Schedule|Schedule]] for information on how to build a schedule.
*Only one schedule may run on a train at a time and the user cannot control the train when it is running a schedule.
*This method is a thread, so the calling code does not need to wait for it to finish and return before executing other code.
 

===SetAdvisoryLimit===
{{MethodHeader|public native void SetAdvisoryLimit(float speed)}}
;Parameters
*'''speed''' = Speed limit to set in <del>KPH</del> metres/second.
;Returned Value
*None
;Syntax
train.SetAdvisoryLimit(60.0);
;Notes
*Sets an advisory speed limit for a script controlled train.
*Use zero in the speed parameter to clear any previously imposed limit.
*Does this really use KPH, most similar methods use MPS
*Experimental evidence confirms that it's in m/s not kph or mph
 

===SetAutopilotMode===
{{MethodHeader|public native void SetAutopilotMode(int mode)}}
;Parameters
*'''mode''' = One of the [[#Train Control Modes|Train Control Mode]] constants specifying the method by which this train is controlled.
;Returned Value
*None
;Syntax
train.SetAutopilotMode(Train.CONTROL_AUTOMANUAL);
;Notes
 

===SetAutopilotTarget===
{{MethodHeader|public native void SetAutopilotTarget(Buildable buildable, string trigger) public native void SetAutopilotTarget(Trackside trackside) public native void SetAutopilotTarget(Track track) public native void SetAutopilotTarget(JunctionBase junction)}}
;Parameters
*'''buildable''' = Buildable object to use as a destination.
*'''trigger''' = Attached trigger within the buildable, specified by name.
*'''trackside''' = Trackside object to use as a destination.
*'''track''' = Track segment to use as a destination.
*'''junction''' = JunctionBase object to use as a destination.
;Returned Value
*None
;Syntax
train.SetAutopilotTarget("Kings Cross Station","trigger1");
;Notes
*This method sets a destination for the autopilot to take this train to.
*Objects from respective child classes such as industries, signals and trackmarks may be specified.
 

===SetAutopilotTargetMinimumDistance===
{{MethodHeader|public native void SetAutopilotTargetMinimumDistance(float distance)}}
;Parameters
*'''distance''' = The minimum distance in metres, between the train and the autopilot target, to be reached before the train will start to slow down.
;Returned Value
*None
;Syntax
train SetAutopilotTargetMinimumDistance(100.0);
;Notes
 

===SetAutoPilotTargetMinimumSpeed===
{{MethodHeader|public native void SetAutopilotTargetMinimumSpeed(float speed)}}
;Parameters
*'''speed''' = Minimum speed, in metres per second, that the train should be travelling at when it reaches the Autopilot target.
;Returned Value
*None
;Syntax
train.SetAutoPilotTargetMinimumSpeed(20.0);
;Notes
*The documentation seems to mean that the train should be going at 20.0 OR MORE. Shouldn't it be MaximumSpeed???
 

===SetBail===
{{MethodHeader|public native void SetBail(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.SetBail();
;Notes
*Depresses the bail control for a short period.
 

===SetCouplingMask===
{{MethodHeader|public void SetCouplingMask(int mask)}}
;Parameters
*'''mask''' = A mask specifying which of the trains exposed couplers are allowed to couple.
;Returned Value
*None
;Syntax
train.SetCouplingMask(Vehicle.COUPLE_NONE); // prevents this train from coupling to another in Driver mode.
;Notes
*The mask can be built using the [[Class Vehicle#Coupler Flags|Coupler Flag]] constants defined in [[Class Vehicle]].
*This method will not prevent vehicles or trains from coupling in Surveyor, but takes effect in Driver mode.
 

===SetDCCThrottle===
{{MethodHeader|public native void SetDCCThrottle(float throttle)}}
;Parameters
*'''throttle''' = Float value in the range -1.0 .. 1.0 defining the throttle setting for the train when using DCC physics.
;Returned Value
*None
;Syntax
train.SetDCCThrottle(0.0); //sets the throttle to neutral.
;Notes
*Full speed ahead is 1.0
*Maximum in reverse is -1.0
*Neutral is 0.0
 

===SetDecouplingMask===
{{MethodHeader|public void SetDecouplingMask(int mask)}}
;Parameters
*'''mask''' = A mask specifying which of the couplers are allowed to couple, applies to all of the vehicles in the train.
;Returned Value
*None
;Syntax
train.SetDecouplingMask(Vehicle.COUPLE_FRONT|Vehicle.COUPLE_BACK); // prevents vehicles being uncoupled from the train in Driver mode.
;Notes
*The mask can be built using the [[Class Vehicle#Coupler Flags|Coupler Flag]] constants defined in [[Class Vehicle]].
*This method will not prevent vehicles or trains from being uncoupled in Surveyor, but takes effect in Driver mode.
 

===SetDynamicBrakeMode===
{{MethodHeader|public native void SetDynamicBrakeMode(int mode)}}
;Parameters
*One of the [[#Dynamic Brake States|Dynamic Brake State]] constants indicating the current state of this train's brakes.
;Returned Value
*None
;Syntax
train.SetDynamicBrakeMode(Train.DYNAMIC_BRAKE_TRACTION);
;Notes
 

===SetFloatingLimit===
{{MethodHeader|public native void SetFloatingLimit(float delta, bool enable)}}
;Parameters
*'''delta''' = Tolerance allowed from the posted limit in metres per second.
*'''enable''' = Use true to enable messages related to floating limits, false to disable.
;Returned Value
*None
;Syntax
train.SetFloatingLimit(5.0,true);
;Notes
*Sets the floating speed limit level above the sign posted limit.
*The floating limit is an amount of tolerance above the current speed limit.
*Messages for floating speed violations are not to be confused with regular speed limit messages.
*The floating limit is monitored by the Scenario.Monitor() thread, and may be used for point deduction when speeding. It should therefore be reserved for player trains.
 

===SetHandBrake===
{{MethodHeader|public void SetHandBrake(bool state)}}
;Parameters
*'''state''' = Use true to apply the handbrake to all vehicles in this train which are not Locomotives, false to release the handbrake.
;Returned Value
*None
;Syntax
train.SetHandBrake(true);
;Notes ''The use of this function did not reveal any effect on the physics of trains.''
 

===SetHeadlightState===
{{MethodHeader|public native void SetHeadlightState(bool lightsOn)}}
;Parameters
*'''lightsOn''' = True to turn the headlights on, false to turn them off.
;Returned Value
*None
;Syntax
train.SetHeadlightState(true);
;Notes
*This method affects only the headlights on the frontmost locomotive.
 

===SetHighBeams===
{{MethodHeader|public void SetHighBeams(bool value)}}
;Parameters
*'''value''' = True to turn on high beams, false to turn them off.
;Returned Value
*None
;Syntax
train.SetHighBeams(true);
;Notes
*See also [[Class Vehicle#SetHighBeams|Vehicle.SetHighColor()]]
 

===SetLastVisitedBuildable===
{{MethodHeader|public void SetLastVisitedBuildable(Buildable buildable)}}
;Parameters
*'''buildable''' = Sets the last visited buildable to the given object.
;Returned Value
*None
;Syntax
train.SetLastVisitedBuildable(KingsCrossStation);
;Notes
 

===SetManualThrottle===
{{MethodHeader|public native void SetManualThrottle(int notch)}}
;Parameters
*'''notch''' = Value in the range 0 .. 8 to set the throttle.
;Returned Value
*None
;Syntax
train.SetManualThrottle(5);
;Notes
 

===SetPantogaphState===
{{MethodHeader|public native void SetPantographState(int state)}}
;Parameters
*'''state''' = Value in the range 0 .. 3 to set the pantographs if this train has them.
;Returned Value
*None
;Syntax
train.SetPantographState(3);
;Notes
*Use one of these values for ''state'':
**0 = Both pantographs down.
**1 = Front pantograph up.
**2 = Rear pantograph up.
**3 = Both pantographs up.
 

===SetReverser===
{{MethodHeader|public native void SetReverser(int mode)}}
;Parameters
*'''mode''' = One of the [[#Reverser Traction Modes|Reverser Traction Mode]] constants defining the required state of the train's reverser lever.
;Returned Value
*None
;Syntax
train.SetReverser(Train.TRACTION_REVERSE);
;Notes
 

===SetTrainBrakes===
{{MethodHeader|public native void SetTrainBrakes(float mode)}}
;Parameters
*'''mode''' = One of the [[#Train Brake States|Train Brake State]] constants defining the required state of the train's brakes.
;Returned Value
*None
;Syntax
train.SetTrainBrakes(Train.TRAIN_BRAKE_EMERGENCY);
;Notes
 

===SetTrainPriorityNumber===
{{MethodHeader|public native void SetTrainPriority Number(int priority)}}
;Parameters
*'''priority''' = Priority value in the range 1 .. 3.
;Returned Value
*None
;Syntax
train.SetTrainPriorityNumber(2);
;Notes
*All trains and track sections can be assigned a priority value in the range of [1 - 3] with the default value being 2.
*The priority value is not a numerical scale of precedence, but a value for the AI driver to attempt to match.
*This means the driver will ''prefer'' track sections that have a priority equal to that of the train.
*Changing the priority of the train only takes affect when the driver restarts a new schedule.
 

===SetTrainTimetable===
{{MethodHeader|public void SetTrainTimetable(TrainTimetable timetable)}}
;Parameters
*'''timetable''' = Assigns the specified timetable to this train.
;Returned Value
*None
;Syntax
train.SetTrainTimetable(timetable);
;Notes
*This train must not already have a TrainTimetable assigned.
*To ensure that this proviso is met, use [[#ClearTrainTimetabel|ClearTrainTimetable()]] prior to calling this method.
*It is the responsibility of the caller to post a "TrainTimetable","Touch" message after calling this function.
 

===SetVelocity===
{{MethodHeader|public native void SetVelocity(float velocity)}}
;Parameters
*'''velocity''' = Velocity to apply to the train, in metres per second.
;Returned Value
*None
;Syntax
train.SetVelocity(0.0); // stops the train, subject to braking performance.
;Notes
 

===ShowInConsistMenu===
{{MethodHeader|public native void ShowInConsistMenu(bool show)}}
;Parameters
*'''show''' = True to make this train visible to the in-game consist menu, false to hide it.
;Returned Value
*None
;Syntax
train.ShowInConsistMenu(false);
;Notes
 

===SoundHorn===
{{MethodHeader|public native void SoundHorn(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.SoundHorn();
;Notes
*Sounds the horn or whictle for all locomotives in this train.
 

===StopSchedule===
{{MethodHeader|public void StopSchedule(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.StopSchedule();
;Notes
*This method stops the Schedule this train is currently running (if any).
 

===StopScheduleAndWait===
{{MethodHeader|public void StopSchedule(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.StopSchedule();
;Notes
*This method stops the Schedule this train is currently running (if any) and waits until the train's schedule actually stops before returning.
*If the train is not running a schedule, the method returns after broadcasting a "Schedule","Touch" message, in case someone is listening for schedule messages.
 

===StopTrainGently===
{{MethodHeader|public native void StopTrainGently(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.StopTrainGently();
;Notes
*Brings the train to a halt over a short time period.
 

===TakePermitOnTrack===
{{MethodHeader|public Permit[ ] TakePermitOnTrack(bool direction)}}
;Parameters
*'''direction''' = Direction relative to the train in which to take out permits.
;Returned Value
*An array including any permits taken which have not yet been granted to this train. Some of these permits may not yet have been granted.
;Syntax
Permit[] permits = train.TakePermitOnTrack(true);
;Notes
*Gets permits on the current track in the given direction.
 

===TestTrackPermit===
{{MethodHeader|public native bool TestTrackPermit(Permit permit, bool innerOnly)}}
;Parameters
*'''permit''' = An existing Permit object.
*'''innerOnly''' = If true the method will test only the inner radius, if false the default radius of 150 metres will be used.
;Returned Value
*True if this train is within the track controlled by ''permit'', false otherwise.
;Syntax
bool ownPermit = train.TestTrackPermit(permit1,false);
;Notes
*The method generates an exception if the ''permit'' parameter does not refer to a track.
 

===ToggleScheduleWindow===
{{MethodHeader|public void ToggleScheduleWindow(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.ToggleScheduleWindow();
;Notes
*If the schedule window is already open/visible, this method will destroy it.
*Otherwise if the view details window is not visible, UpdateScheduleWindow() is called to create it for display.
 

===ToggleViewDetailsWindow===
{{MethodHeader|public void ToggleViewDetailsWindow(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.ToggleViewDetailsWindow();
;Notes
*If the ViewDetails window is already open/visible, this method will destroy it.
*Otherwise if the view details window is not visible, ViewDetails() is called to create it for display.
 

===TrackSearch===
{{MethodHeader|public native MapObject[ ] TrackSearch(bool direction, float distance)}}
;Parameters
*'''direction''' = Direction to search relative to the train's heading, true for forwards, false for backwards.
*'''distance''' = Maximum search distance in metres.
;Returned Value
*An array of objects found along the track in the defined search direction, the array might be empty.
;Syntax
MapObject[] objects = train.TrackSearch(true,5000.0) // searches 5km forwards along the track.
;Notes
*Gets all of the Trackside and SceneryWithTrack objects on a length of track that is either in front of or behind this train.
*Descendants of these classes are also returned.
 

===TracksideIsInFront===
{{MethodHeader|public bool TracksideIsInFront(Trackside obj, float range)}}
;Parameters
*'''obj''' = Trackside object to search for.
*'''range''' = Mximum search distance.
;Returned Value
*True if the object is logically forward of this train, false otherwise.
;Syntax
bool found = train.TracksideIsInFront(signal1,500.0);
;Notes
 

===Turnaround===
{{MethodHeader|public native void Turnaround(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.Turnaround();
;Notes
*Reverses the logical direction of the train, ie changes its heading.
*The physical direction of the vehicles is not altered but the throttle direction is reversed.
*If the camera is focused on the train in tracking view when this method is called the camera's direction of view (relative to the map) will alter through 180 degrees.
 

===UpdateScheduleWindow===
{{MethodHeader|public void UpdateScheduleWindow(string vehicleName)}}
;Parameters
*'''vehicleName''' = Name of vehicle within the train.
;Returned Value
*None
;Syntax
train.UpdateScheduleWindow("brake2");
;Notes
*Updates the schedule window from the given vehicle.
 

===UpdateViewDetails===
{{MethodHeader|public void UpdateViewDetails(Vehicle vehicle)}}
;Parameters
*'''vehicle''' = Reference to a vehicle within the train.
;Returned Value
*None
;Syntax
train.UpdateViewDetails(vehicle);
;Notes
*Called by Vehicle.UpdateViewDetails() when a vehicle's load has changed so that the train's detail window can be amended.
 

===UpdateViewDetailsLocomotive===
{{MethodHeader|public void UpdateViewDetailsLocomotive(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.UpdateViewDetailsLocomotive(vehicle);
;Notes
*Called by Locomotive.UpdateViewDetails() when any of the Locomotive's operating parameters have changed so that the train's detail window can be amended.
 

===ViewDetails===
{{MethodHeader|public void ViewDetails(Vehicle vehicle)}}
;Parameters
*'''vehicle''' = Reference to a vehicle within the train.
;Returned Value
*None
;Syntax
train.ViewDetails(vehicle);
;Notes
*This method is called by Vehicle.ViewDetails() when the user has requested to view the details of the consist.
*It will create a Browser window listing information about the train including who the driver character is and the loads of all vehicles.
 

===WasRunScheduleSuccessful===
{{MethodHeader|public bool WasRunScheduleSuccessful(void)}}
;Parameters
*None
;Returned Value
*True if the most recently run schedule was successfully, false otherwise.
;Syntax
train.WasRunScheduleSuccessful();
;Notes
 

==Code Examples==
 

==Related Methods==
[[Class TrainUtil#AreInTrain|TrainUtil.AreInTrain()]] 
[[Class TrainUtil#CreateTrainFromSoup|TrainUtil.CreateTrainFromSoup()]] 
[[Class TrainUtil#IsInTrain|TrainUtil.IsInTrain()]] 
[[Class World#CreateTrain|World.CreateTrain()]] 
[[Class World#DeleteTrain|World.DeleteTrain()]] 
[[Class World#GetTrainList|World.GetTrainList()]] 
 

==Categories==
[[Category:Script Class]]

Texture file

2020-07-02T21:45:16Z

Gdennish: /* Notes on Image Editors */

{{ORP-top}}
Trainz '''Texture files''' are ASCII text format specification files describing a single texture. Texture files have a ".texture.txt" name extension, however when a texture file is specified within a [[config.txt file]] or similar, the ".txt" must be omitted (as you are specifying a resource name, not a file path), leaving only the ".texture" extension.

Texture files (*.texture.txt) should be distinguished from [[image file]]s (*.tga, etc.) and [[material]]s. A material may utilize zero or more texture files, and a texture file may utilize one or more image files. While we often refer to the image data as "a texture", this usage isn't strictly correct as any given texture also has a number of metadata attributes which are not present in the source image. Additionally, a texture may be compressed (at installation time) which may actually lose some of the data originally present in the source image.

When importing a [[trainzmesh file]] from an [[FBX file]], any image files referenced in the FBX which do not already have corresponding texture files will have generic texture files created automatically. These files may be suitable for basic purposes, but may need to be customized for more advanced functionality. Once the file has been created (and optionally customised) the importer will not recreate/overwrite it on subsequent runs.

This page describes [["Trainz-build" number|content format v4.6]].

=File format=

The user-editable *.texture.txt files are ASCII text formatted key-value pairs with the following options. Please note that this format is not the same (despite some similarities) as other text-based formats used by Trainz. Please be aware of the [[filename character restrictions]] when naming texture and image files.

;Syntax
Each key is specified on a new line. There is no white space anywhere in the line. A empty value is sometimes valid. The syntax is:

<key>=<value>

;Example:
Primary=WayCoolTexture.tga
Alpha=WayCoolTexture.tga
Tile=st
AlphaHint=masked
''(Example only, not recommended settings)''

==Keys and Values==

Primary=diffusemap.bmp

This tag specifies the filename of the image file representing the color (R, G, B) channels of the texture. Any alpha channel in the image file is ignored. The resultant texture will have a pure white (100%) alpha channel.

Primary=diffusemap.jpg
Alpha=diffusemap.bmp

This tag combination specifies the filenames of the image file representing the color (R, G, B) channels of the texture (Primary) and the image file representing the transparency of the texture (Alpha). The Alpha image should be grayscale. Neither file should contain an alpha (A) channel (ie, both images should be 24-bit). The two image files must be of identical size.

Primary=diffusemap.tga
Alpha=diffusemap.tga

This tag combination specifies the filename of a single image file representing the color and transparency (R, G, B, A) channels of the texture. In this case both tags must reference the same filename. The image file must contain an alpha channel.

Compression=dxt3

This tag hints the usage of a particular texture compression scheme. If you don't have a specific effect in mind, don't include this tag. Valid options are currently 'none', 'dxt1', 'dxt3', 'dxt5'. Refer [[DXT Compression]].

The current selection logic for texture compression is as follows, however it should be noted that this may change between Trainz versions. The first matching rule is used.

* Special texture formats (such as HDR) which don't support compression are stored uncompressed.
* "Compression=none" forces no compression. This gives the best visual result for a given input image, but typically yields worse visual results per output texture filesize. It is often better to activate compression and double the image dimensions, rather than disabling compression.
* Images with an "opaque" alpha hint use DXT1 compression.
* "Compression=dxt3" will use DXT3 compression.
* DXT5 compression is used.

NormalMapHint=normalmap

The 'NormalMapHint' tag allows the texture to be specified as a [[normal map]]. By default, Trainz will assume that your texture is a [[diffuse map]] and will apply some processing options which are not appropriate for normal maps. You must specify this option for normal maps. Valid options are 'none' and 'normalmap'.

ModifyMap=flipgreen

The 'ModifyMap' option allows a texture's green color channel to be flipped. Some programs such as [[Autodesk 3ds Max]] create [[normal map]]s with the Y axis facing the opposite way to what is expected by the Trainz shaders. This option can be used to make the bump effect look correct in Trainz. Valid options are 'none' and 'flipgreen'.

AlphaHint=opaque

The 'AlphaHint' tag allows you to force a particular alpha mode on the texture. Valid options are 'opaque' (meaning that the alpha channel is overwritten with pure white), 'semitransparent' (meaning that the alpha channel is a grayscale blend) and 'masked' (meaning that the alpha channel is clamped to a pure black&white bitmap based on a 50% threshold.) If omitted, Trainz will supply an appropriate value for this tag based on the actual contents of the Alpha channel.

Tile=st

Tiling refers to the ability for texture coordinates outside the range of (0.0 .. 1.0) to be treated as valid coordinates on an infinitely tiled texture. With tiling active, coordinates which pass the right/bottom side of the texture effectively wrap back onto the left/top side, and so on. Valid options include 's' (tile horizontally), 't' (tile vertically), 'st' (tile both horizontally and vertically), and 'none' (do not tile the image).

MipAlgorithm=no-weight-by-alpha

The default [[mipmap]] generation algorithm generally treats the alpha channel as an opacity and prioritizes opaque texels over transparent ones. This can lead to poor results in cases where the alpha channel is used for a different purpose (such as with PBR parameter textures). The "no-weight-by-alpha" hint can be used to ensure that the game will give equal weighting to texels regardless of their alpha channel.

The value of this key is only relevant where [[Content Manager]] is responsible for producing mipmap images. It is not relevant on any mipmap images provided in the source images.

nonpoweroftwo=1

By default, all textures must have both their width and height as a power of two (eg. 8, 16, 32, 64, 128, 256, 512, 1024, 2048), though they need not be square. Setting the value '1' for the 'nonpoweroftwo' key allows this restriction to be relaxed. This is currently considered experimental and may have unexpected performance, quality, or functionality outcomes. It is not recommended that end-users utilize this format at the current time.

Non-power-of-two (NPOT) textures may not support mipmapping and thus may be noticeably affected by the moire effect in addition to having higher overall GPU bandwidth requirements.

=Texture Formats=
The following texture formats are supported internally by Trainz on desktop platforms.
* R8 G8 B8 A8
* DXT1
* DXT3
* DXT5
* R32F G32F B32F A32F

The selection of internal format depends on the source image format and the value of the 'Compression' key.

=Texture Size=
Textures must be no more than 4096 pixels in either dimension, although it is strongly recommended that textures are kept below this maximum to avoid performance problems. Small objects should typically use approximately 512x512. Large, highly detailed objects such as train vehicles or ground textures will typically use 2048x2048.
Uniform-color textures (ie. textures in which all [[texel]]s have the same color) should be 8x8, 2x2, or 1x1.
Textures must be a power-of-two size in each dimension (unless the 'nonpoweroftwo' key is activated), but need not be square. Some materials may give unexpected results for non-square textures; consult the material-specific documentation for details.

=Source Image Formats=
The following image formats are acceptable as source data for the texture file. Note that these formats are not used at runtime, and that format-specific benefits such as compression will apply to the DLS download size of the content but not to the runtime memory footprint or GPU bandwidth usage.

* Targa (.tga) files. Targa is a lossless image format with optional compression and optional alpha channel. This is a sensible choice where compatibility with older versions of Trainz is desired.
* JPEG (.jpg) files. JPEG is a lossy image compression format with no alpha channel support. This format should generally be avoided since it will typically lead to the image being compressed in a lossy format (JPG), decompressed, recompressed again into another lossy format (DXT1), losing detail at each stage. Worse, if JPEG files are used during the creation of the image, each edit-save-test cycle may result in a loss of image quality.
* Windows Bitmap (.bmp) files. BMP is a lossless image format with no compression and optional alpha channel. This format should generally be avoided since it does not offer compression and has no redeeming benefits.
* HDR (.hdr) files. HDR is a lossless image format with 32 bits of precision per channel. The R32F G32F B32F A32F internal texture format is used, and texture compression is not supported. This is a very expensive format (in terms of memory and performance) and should only be used where absolutely essential. Textures created in this format should be kept as small as possible (eg. 256-512 pixels wide and high) but at least 8x8 pixels wide and high.
* PNG (.png) files. PNG is a lossless compressed image format with alpha channel support. This is the best choice where compatibility with older versions of Trainz is not required.
* DDS (.dds) files. This has very limited support intended for specific internal purposes; it is not recommended that end-users utilize this format at the current time.

All images which comprise a given texture must have identical dimensions (width, height).

Source images should use the SRGB color space except where material-specific documentation indicates otherwise.

=Notes on Image Editors=
* The Targa Exporter plugin shipped with some older versions of Adobe Photoshop is broken and silently corrupts or discards alpha channels; a free update is available which resolves this issue.
* Some image editors do not support alpha channels on BMP files.
* By default, Photoshop does not allow for explicit editing of the alpha channel in PNG images. There is a free plugin called [https://www.fnordware.com/superpng/ SuperPNG] which integrates better PNG support to enable saving and editing of PNG alpha masks.
* [http://www.amnoid.de/ddsview/ ddsview ] is an open source image editor that can properly open all of the texture formats used by Trainz. This is an easy tool to quickly convert between PNG parameters and TGA parameters.

=*.txt File Extension=
Texture files have a ".texture.txt" name extension, however when a texture file is specified within a [[config.txt file]] or similar, the ".txt" must be omitted, leaving the ".texture" extension.
For example, a texture file named ''grass.texture.txt'' is specified in a [[KIND Groundtexture]] config file using the syntax ''texture "grass.texture"''.

=Use of Image Files in Place of Texture Files=
Trainz previously supported using ''any supported image file'' type in place of a [[Texture file]]. [[TANE]] does not support this technique; a texture.txt file must be used.

[[Category:File formats]]
[[Category:Modeling]]
[[Category:Content creation]]
{{ORP-bot}}

Texture file

2020-07-02T21:39:16Z

Gdennish: /* Source Image Formats */

{{ORP-top}}
Trainz '''Texture files''' are ASCII text format specification files describing a single texture. Texture files have a ".texture.txt" name extension, however when a texture file is specified within a [[config.txt file]] or similar, the ".txt" must be omitted (as you are specifying a resource name, not a file path), leaving only the ".texture" extension.

Texture files (*.texture.txt) should be distinguished from [[image file]]s (*.tga, etc.) and [[material]]s. A material may utilize zero or more texture files, and a texture file may utilize one or more image files. While we often refer to the image data as "a texture", this usage isn't strictly correct as any given texture also has a number of metadata attributes which are not present in the source image. Additionally, a texture may be compressed (at installation time) which may actually lose some of the data originally present in the source image.

When importing a [[trainzmesh file]] from an [[FBX file]], any image files referenced in the FBX which do not already have corresponding texture files will have generic texture files created automatically. These files may be suitable for basic purposes, but may need to be customized for more advanced functionality. Once the file has been created (and optionally customised) the importer will not recreate/overwrite it on subsequent runs.

This page describes [["Trainz-build" number|content format v4.6]].

=File format=

The user-editable *.texture.txt files are ASCII text formatted key-value pairs with the following options. Please note that this format is not the same (despite some similarities) as other text-based formats used by Trainz. Please be aware of the [[filename character restrictions]] when naming texture and image files.

;Syntax
Each key is specified on a new line. There is no white space anywhere in the line. A empty value is sometimes valid. The syntax is:

<key>=<value>

;Example:
Primary=WayCoolTexture.tga
Alpha=WayCoolTexture.tga
Tile=st
AlphaHint=masked
''(Example only, not recommended settings)''

==Keys and Values==

Primary=diffusemap.bmp

This tag specifies the filename of the image file representing the color (R, G, B) channels of the texture. Any alpha channel in the image file is ignored. The resultant texture will have a pure white (100%) alpha channel.

Primary=diffusemap.jpg
Alpha=diffusemap.bmp

This tag combination specifies the filenames of the image file representing the color (R, G, B) channels of the texture (Primary) and the image file representing the transparency of the texture (Alpha). The Alpha image should be grayscale. Neither file should contain an alpha (A) channel (ie, both images should be 24-bit). The two image files must be of identical size.

Primary=diffusemap.tga
Alpha=diffusemap.tga

This tag combination specifies the filename of a single image file representing the color and transparency (R, G, B, A) channels of the texture. In this case both tags must reference the same filename. The image file must contain an alpha channel.

Compression=dxt3

This tag hints the usage of a particular texture compression scheme. If you don't have a specific effect in mind, don't include this tag. Valid options are currently 'none', 'dxt1', 'dxt3', 'dxt5'. Refer [[DXT Compression]].

The current selection logic for texture compression is as follows, however it should be noted that this may change between Trainz versions. The first matching rule is used.

* Special texture formats (such as HDR) which don't support compression are stored uncompressed.
* "Compression=none" forces no compression. This gives the best visual result for a given input image, but typically yields worse visual results per output texture filesize. It is often better to activate compression and double the image dimensions, rather than disabling compression.
* Images with an "opaque" alpha hint use DXT1 compression.
* "Compression=dxt3" will use DXT3 compression.
* DXT5 compression is used.

NormalMapHint=normalmap

The 'NormalMapHint' tag allows the texture to be specified as a [[normal map]]. By default, Trainz will assume that your texture is a [[diffuse map]] and will apply some processing options which are not appropriate for normal maps. You must specify this option for normal maps. Valid options are 'none' and 'normalmap'.

ModifyMap=flipgreen

The 'ModifyMap' option allows a texture's green color channel to be flipped. Some programs such as [[Autodesk 3ds Max]] create [[normal map]]s with the Y axis facing the opposite way to what is expected by the Trainz shaders. This option can be used to make the bump effect look correct in Trainz. Valid options are 'none' and 'flipgreen'.

AlphaHint=opaque

The 'AlphaHint' tag allows you to force a particular alpha mode on the texture. Valid options are 'opaque' (meaning that the alpha channel is overwritten with pure white), 'semitransparent' (meaning that the alpha channel is a grayscale blend) and 'masked' (meaning that the alpha channel is clamped to a pure black&white bitmap based on a 50% threshold.) If omitted, Trainz will supply an appropriate value for this tag based on the actual contents of the Alpha channel.

Tile=st

Tiling refers to the ability for texture coordinates outside the range of (0.0 .. 1.0) to be treated as valid coordinates on an infinitely tiled texture. With tiling active, coordinates which pass the right/bottom side of the texture effectively wrap back onto the left/top side, and so on. Valid options include 's' (tile horizontally), 't' (tile vertically), 'st' (tile both horizontally and vertically), and 'none' (do not tile the image).

MipAlgorithm=no-weight-by-alpha

The default [[mipmap]] generation algorithm generally treats the alpha channel as an opacity and prioritizes opaque texels over transparent ones. This can lead to poor results in cases where the alpha channel is used for a different purpose (such as with PBR parameter textures). The "no-weight-by-alpha" hint can be used to ensure that the game will give equal weighting to texels regardless of their alpha channel.

The value of this key is only relevant where [[Content Manager]] is responsible for producing mipmap images. It is not relevant on any mipmap images provided in the source images.

nonpoweroftwo=1

By default, all textures must have both their width and height as a power of two (eg. 8, 16, 32, 64, 128, 256, 512, 1024, 2048), though they need not be square. Setting the value '1' for the 'nonpoweroftwo' key allows this restriction to be relaxed. This is currently considered experimental and may have unexpected performance, quality, or functionality outcomes. It is not recommended that end-users utilize this format at the current time.

Non-power-of-two (NPOT) textures may not support mipmapping and thus may be noticeably affected by the moire effect in addition to having higher overall GPU bandwidth requirements.

=Texture Formats=
The following texture formats are supported internally by Trainz on desktop platforms.
* R8 G8 B8 A8
* DXT1
* DXT3
* DXT5
* R32F G32F B32F A32F

The selection of internal format depends on the source image format and the value of the 'Compression' key.

=Texture Size=
Textures must be no more than 4096 pixels in either dimension, although it is strongly recommended that textures are kept below this maximum to avoid performance problems. Small objects should typically use approximately 512x512. Large, highly detailed objects such as train vehicles or ground textures will typically use 2048x2048.
Uniform-color textures (ie. textures in which all [[texel]]s have the same color) should be 8x8, 2x2, or 1x1.
Textures must be a power-of-two size in each dimension (unless the 'nonpoweroftwo' key is activated), but need not be square. Some materials may give unexpected results for non-square textures; consult the material-specific documentation for details.

=Source Image Formats=
The following image formats are acceptable as source data for the texture file. Note that these formats are not used at runtime, and that format-specific benefits such as compression will apply to the DLS download size of the content but not to the runtime memory footprint or GPU bandwidth usage.

* Targa (.tga) files. Targa is a lossless image format with optional compression and optional alpha channel. This is a sensible choice where compatibility with older versions of Trainz is desired.
* JPEG (.jpg) files. JPEG is a lossy image compression format with no alpha channel support. This format should generally be avoided since it will typically lead to the image being compressed in a lossy format (JPG), decompressed, recompressed again into another lossy format (DXT1), losing detail at each stage. Worse, if JPEG files are used during the creation of the image, each edit-save-test cycle may result in a loss of image quality.
* Windows Bitmap (.bmp) files. BMP is a lossless image format with no compression and optional alpha channel. This format should generally be avoided since it does not offer compression and has no redeeming benefits.
* HDR (.hdr) files. HDR is a lossless image format with 32 bits of precision per channel. The R32F G32F B32F A32F internal texture format is used, and texture compression is not supported. This is a very expensive format (in terms of memory and performance) and should only be used where absolutely essential. Textures created in this format should be kept as small as possible (eg. 256-512 pixels wide and high) but at least 8x8 pixels wide and high.
* PNG (.png) files. PNG is a lossless compressed image format with alpha channel support. This is the best choice where compatibility with older versions of Trainz is not required.
* DDS (.dds) files. This has very limited support intended for specific internal purposes; it is not recommended that end-users utilize this format at the current time.

All images which comprise a given texture must have identical dimensions (width, height).

Source images should use the SRGB color space except where material-specific documentation indicates otherwise.

=Notes on Image Editors=
* The Targa Exporter plugin shipped with some older versions of Adobe Photoshop is broken and silently corrupts or discards alpha channels; a free update is available which resolves this issue.
* Some image editors do not support alpha channels on BMP files.

=*.txt File Extension=
Texture files have a ".texture.txt" name extension, however when a texture file is specified within a [[config.txt file]] or similar, the ".txt" must be omitted, leaving the ".texture" extension.
For example, a texture file named ''grass.texture.txt'' is specified in a [[KIND Groundtexture]] config file using the syntax ''texture "grass.texture"''.

=Use of Image Files in Place of Texture Files=
Trainz previously supported using ''any supported image file'' type in place of a [[Texture file]]. [[TANE]] does not support this technique; a texture.txt file must be used.

[[Category:File formats]]
[[Category:Modeling]]
[[Category:Content creation]]
{{ORP-bot}}

Texture file

2020-07-02T21:38:35Z

Gdennish: /* Texture Size */

{{ORP-top}}
Trainz '''Texture files''' are ASCII text format specification files describing a single texture. Texture files have a ".texture.txt" name extension, however when a texture file is specified within a [[config.txt file]] or similar, the ".txt" must be omitted (as you are specifying a resource name, not a file path), leaving only the ".texture" extension.

Texture files (*.texture.txt) should be distinguished from [[image file]]s (*.tga, etc.) and [[material]]s. A material may utilize zero or more texture files, and a texture file may utilize one or more image files. While we often refer to the image data as "a texture", this usage isn't strictly correct as any given texture also has a number of metadata attributes which are not present in the source image. Additionally, a texture may be compressed (at installation time) which may actually lose some of the data originally present in the source image.

When importing a [[trainzmesh file]] from an [[FBX file]], any image files referenced in the FBX which do not already have corresponding texture files will have generic texture files created automatically. These files may be suitable for basic purposes, but may need to be customized for more advanced functionality. Once the file has been created (and optionally customised) the importer will not recreate/overwrite it on subsequent runs.

This page describes [["Trainz-build" number|content format v4.6]].

=File format=

The user-editable *.texture.txt files are ASCII text formatted key-value pairs with the following options. Please note that this format is not the same (despite some similarities) as other text-based formats used by Trainz. Please be aware of the [[filename character restrictions]] when naming texture and image files.

;Syntax
Each key is specified on a new line. There is no white space anywhere in the line. A empty value is sometimes valid. The syntax is:

<key>=<value>

;Example:
Primary=WayCoolTexture.tga
Alpha=WayCoolTexture.tga
Tile=st
AlphaHint=masked
''(Example only, not recommended settings)''

==Keys and Values==

Primary=diffusemap.bmp

This tag specifies the filename of the image file representing the color (R, G, B) channels of the texture. Any alpha channel in the image file is ignored. The resultant texture will have a pure white (100%) alpha channel.

Primary=diffusemap.jpg
Alpha=diffusemap.bmp

This tag combination specifies the filenames of the image file representing the color (R, G, B) channels of the texture (Primary) and the image file representing the transparency of the texture (Alpha). The Alpha image should be grayscale. Neither file should contain an alpha (A) channel (ie, both images should be 24-bit). The two image files must be of identical size.

Primary=diffusemap.tga
Alpha=diffusemap.tga

This tag combination specifies the filename of a single image file representing the color and transparency (R, G, B, A) channels of the texture. In this case both tags must reference the same filename. The image file must contain an alpha channel.

Compression=dxt3

This tag hints the usage of a particular texture compression scheme. If you don't have a specific effect in mind, don't include this tag. Valid options are currently 'none', 'dxt1', 'dxt3', 'dxt5'. Refer [[DXT Compression]].

The current selection logic for texture compression is as follows, however it should be noted that this may change between Trainz versions. The first matching rule is used.

* Special texture formats (such as HDR) which don't support compression are stored uncompressed.
* "Compression=none" forces no compression. This gives the best visual result for a given input image, but typically yields worse visual results per output texture filesize. It is often better to activate compression and double the image dimensions, rather than disabling compression.
* Images with an "opaque" alpha hint use DXT1 compression.
* "Compression=dxt3" will use DXT3 compression.
* DXT5 compression is used.

NormalMapHint=normalmap

The 'NormalMapHint' tag allows the texture to be specified as a [[normal map]]. By default, Trainz will assume that your texture is a [[diffuse map]] and will apply some processing options which are not appropriate for normal maps. You must specify this option for normal maps. Valid options are 'none' and 'normalmap'.

ModifyMap=flipgreen

The 'ModifyMap' option allows a texture's green color channel to be flipped. Some programs such as [[Autodesk 3ds Max]] create [[normal map]]s with the Y axis facing the opposite way to what is expected by the Trainz shaders. This option can be used to make the bump effect look correct in Trainz. Valid options are 'none' and 'flipgreen'.

AlphaHint=opaque

The 'AlphaHint' tag allows you to force a particular alpha mode on the texture. Valid options are 'opaque' (meaning that the alpha channel is overwritten with pure white), 'semitransparent' (meaning that the alpha channel is a grayscale blend) and 'masked' (meaning that the alpha channel is clamped to a pure black&white bitmap based on a 50% threshold.) If omitted, Trainz will supply an appropriate value for this tag based on the actual contents of the Alpha channel.

Tile=st

Tiling refers to the ability for texture coordinates outside the range of (0.0 .. 1.0) to be treated as valid coordinates on an infinitely tiled texture. With tiling active, coordinates which pass the right/bottom side of the texture effectively wrap back onto the left/top side, and so on. Valid options include 's' (tile horizontally), 't' (tile vertically), 'st' (tile both horizontally and vertically), and 'none' (do not tile the image).

MipAlgorithm=no-weight-by-alpha

The default [[mipmap]] generation algorithm generally treats the alpha channel as an opacity and prioritizes opaque texels over transparent ones. This can lead to poor results in cases where the alpha channel is used for a different purpose (such as with PBR parameter textures). The "no-weight-by-alpha" hint can be used to ensure that the game will give equal weighting to texels regardless of their alpha channel.

The value of this key is only relevant where [[Content Manager]] is responsible for producing mipmap images. It is not relevant on any mipmap images provided in the source images.

nonpoweroftwo=1

By default, all textures must have both their width and height as a power of two (eg. 8, 16, 32, 64, 128, 256, 512, 1024, 2048), though they need not be square. Setting the value '1' for the 'nonpoweroftwo' key allows this restriction to be relaxed. This is currently considered experimental and may have unexpected performance, quality, or functionality outcomes. It is not recommended that end-users utilize this format at the current time.

Non-power-of-two (NPOT) textures may not support mipmapping and thus may be noticeably affected by the moire effect in addition to having higher overall GPU bandwidth requirements.

=Texture Formats=
The following texture formats are supported internally by Trainz on desktop platforms.
* R8 G8 B8 A8
* DXT1
* DXT3
* DXT5
* R32F G32F B32F A32F

The selection of internal format depends on the source image format and the value of the 'Compression' key.

=Texture Size=
Textures must be no more than 4096 pixels in either dimension, although it is strongly recommended that textures are kept below this maximum to avoid performance problems. Small objects should typically use approximately 512x512. Large, highly detailed objects such as train vehicles or ground textures will typically use 2048x2048.
Uniform-color textures (ie. textures in which all [[texel]]s have the same color) should be 8x8, 2x2, or 1x1.
Textures must be a power-of-two size in each dimension (unless the 'nonpoweroftwo' key is activated), but need not be square. Some materials may give unexpected results for non-square textures; consult the material-specific documentation for details.

=Source Image Formats=
The following image formats are acceptable as source data for the texture file. Note that these formats are not used at runtime, and that format-specific benefits such as compression will apply to the DLS download size of the content but not to the runtime memory footprint or GPU bandwidth usage.

* Targa (.tga) files. Targa is a lossless image format with optional compression and optional alpha channel. This is a sensible choice where compatibility with older versions of Trainz is desired.
* JPEG (.jpg) files. JPEG is a lossy image compression format with no alpha channel support. This format should generally be avoided since it will typically lead to the image being compressed in a lossy format (JPG), decompressed, recompressed again into another lossy format (DXT1), losing detail at each stage. Worse, if JPEG files are used during the creation of the image, each edit-save-test cycle may result in a loss of image quality.
* Windows Bitmap (.bmp) files. BMP is a lossless image format with no compression and optional alpha channel. This format should generally be avoided since it does not offer compression and has no redeeming benefits.
* HDR (.hdr) files. HDR is a lossless image format with 32 bits of precision per channel. The R32F G32F B32F A32F internal texture format is used, and texture compression is not supported. This is a very expensive format (in terms of memory and performance) and should only be used where absolutely essential. Textures created in this format should be kept as small as possible (eg. 256-512 pixels wide and high).
* PNG (.png) files. PNG is a lossless compressed image format with alpha channel support. This is the best choice where compatibility with older versions of Trainz is not required.
* DDS (.dds) files. This has very limited support intended for specific internal purposes; it is not recommended that end-users utilize this format at the current time.

All images which comprise a given texture must have identical dimensions (width, height).

Source images should use the SRGB color space except where material-specific documentation indicates otherwise.

=Notes on Image Editors=
* The Targa Exporter plugin shipped with some older versions of Adobe Photoshop is broken and silently corrupts or discards alpha channels; a free update is available which resolves this issue.
* Some image editors do not support alpha channels on BMP files.

=*.txt File Extension=
Texture files have a ".texture.txt" name extension, however when a texture file is specified within a [[config.txt file]] or similar, the ".txt" must be omitted, leaving the ".texture" extension.
For example, a texture file named ''grass.texture.txt'' is specified in a [[KIND Groundtexture]] config file using the syntax ''texture "grass.texture"''.

=Use of Image Files in Place of Texture Files=
Trainz previously supported using ''any supported image file'' type in place of a [[Texture file]]. [[TANE]] does not support this technique; a texture.txt file must be used.

[[Category:File formats]]
[[Category:Modeling]]
[[Category:Content creation]]
{{ORP-bot}}

M.pbrmetalmasked

2020-06-25T19:20:56Z

Gdennish: /* Albedo */

[[m.pbrmetalmasked]] is a minor variation on the [[m.pbrmetal]] material. It adds a [[masked alpha]] channel to allow a complex outline to be created without the use of large numbers of [[polygon]]s. All PBR materials are defined using a multitude of texture channels (not just a simple RGB image) which define various aspects of the material on a per-texel basis. One major advantage of this approach is that a single in-game material can be used to display various different real-world materials, rather than requiring multiple separate in-game materials with different parameters. Trainz uses a Metallic/Roughness style PBR workflow.

It should be noted that the "metal" in the name of this material refers to the physical property used in the lighting equations; it does not mean that the material is only appropriate for metallic surfaces.

On some hardware, [[masked alpha]] materials may perform substantially worse than an opaque material. This cost is per-[[fragment]], meaning that it may be suitable to use a masked material on low-[[Level of Detail|LOD]] meshes where polygon count must remain low and where fragment count is naturally low. On higher-LOD meshes, especially where the material is expected to fill a reasonable percentage of the screen, masked materials should be avoided in favor of higher polygon detail, or should be used in conjunction with true opaque materials such that the majority of opaque fragments are filled by the opaque materials and only the complex edge detail is filled by the masked material.

This page describes content format v4.6 and assumes that the FBX file format is used as a data source for any meshes.

=Texture Slots=
The following texture slots are used for this material. All textures should typically have the same dimensions unless they represent a uniform color, however this is not strictly enforced.

==Albedo==
RGB: The [[albedo map]] defines the base color of each texel. The sRGB color space is used.

A: The alpha channel provides a "black and white" [[masked alpha]] channel. Black indicates full transparency, meaning that the [[fragment]] is discarded. White indicates full opacity, meaning that rendering proceeds as per [[m.pbrmetal]]. If the alpha channel is omitted, this material acts exactly as [[m.pbrmetal]] except with lower performance. Note that unlike legacy Trainz materials, PBR materials do not autodetect opacity mode based on the texture in use. The content creator must select the appropriate material for their desired outcome. Runtime texture replacement should not expect to replace an opaque texture with a blended or masked texture and have the material update automatically.

'''Albedo Texture Example'''

[[File:PortalAlbedowAlpha.png|500px]]

Color Channel Separated

[[File:PortalAlbedo.png|500px]]

Alpha Channel Separated

[[File:PortalAlpha.png|500px]]

==Normal==
RGB: Surface [[normal map]]. This defines which way the surface is facing, relative to the interpolated vertex normals. Since this is an XYZ format rather than color data, it should never be modified in Photoshop. Using Photoshop to add a fourth channel or copy/paste smaller textures into a [[texture atlas]] is acceptable. Per-pixel manipulation or use of filters on the "RGB" channels is not acceptable.

A: [[Parallax Occlusion Map|Displacement height]]. 0.0 represents the deepest possible value, while 1.0 represents the shallowest possible value. While it is possible to paint this data in Photoshop, a linear color space must be used, and far superior results will be available through other data sources. The parallax height and the surface normal must be kept in sync, which means that a third-party tool must be used to generate the surface normal from the parallax height if you are painting this map manually.

'''Normal Texture Example with no Alpha Channel (Parallax)'''

[[File:pbrnormalmap1.jpg|border|middle|x200px]]

'''Normal Texture Example with Alpha Channel (Parallax)'''

[[File:pbrnormalwithalpha.jpg|border|middle|x200px]]

==Parameter==
This texture is comprised of four separate channels which each form a separate data element. Linear color space (not sRGB) is used for these channels.

[[File:pbrparametersall.jpg|border|middle|x200px]]

R: Emissive. This causes the texture to have an internal glow, even when no external light is present. Used for phosphors, permanently-lit markings, etc. The glow color is based on the albedo. Note that this glow does not cast light upon surrounding surfaces except via the Bloom post-processing effect.

'''Parameters (Emissive - Red Channel) Texture Example'''

[[File:pbrparametersemissivemap1.jpg|border|middle|x200px]]

G: Roughness. Defines whether the surface reflections are shiny (0.0) or matte (1.0). See the [[Physically Based Rendering|PBR metal workflow]] for details.

'''Parameters (Roughness - Green Channel) Texture Example'''

[[File:pbrparametersroughnessmap1.jpg|border|middle|x200px]]

B: Ambient Occlusion. Defines whether the surface is exposed to ambient lighting conditions (1.0) or affected only by direct lighting (0.0).

'''Parameters (Ambient Occlusion - Blue Channel) Texture Example'''

[[File:pbrparametersambientocclusionmap1.jpg|border|middle|x200px]]

A: Metallicity. Defines whether the surface is metallic (1.0) with the albedo used to colorize reflected light, or dielectric (0.0) with the albedo used to colorize the surface. While intermediate values are not physically accurate, they may be used to emulate subsurfaces which are partially metallic. See the [[Physically Based Rendering|PBR metal workflow]] for details.

'''Parameters (Metallic - Alpha Channel) Texture Example'''

[[File:pbrparametersmetallicmap1.jpg|border|middle|x200px]]

=Examples=

[[File:trainz_material_pbrmetalmasked.jpg|border|middle|x512px]]

Example asset download:

[http://download.trainzportal.com/tutorials/Trainz_Material_-_pbrmetalmasked.cdp Trainz Material - pbrmetalmasked + emissive]

=3ds Max Material Configuration=

'''Texture Assignment'''

TBD

=Blender Material Configuration=

The Blender settings for PBRMetalMasked are the same as [[M.pbrmetal#Blender Material Configuration|PBRMetal Blender Settings]] except for the albedo texture where the Image->Use_Alpha should be checked.

[[Category:Material types| ]]
[[Category:Modeling]]
[[Category:Content creation]]

File:PortalAlbedowAlpha.png

2020-06-25T19:19:51Z

Gdennish:

File:PortalAlpha.png

2020-06-25T19:16:32Z

Gdennish:

File:PortalAlbedo.png

2020-06-25T19:15:58Z

Gdennish:

FBX file format

2020-06-17T22:07:57Z

Gdennish: /* Animation Event Files */

The FBX file format is a proprietary file format owned by Autodesk, Inc. but used as a common interchange format for many products. As of trainz-build 4.5, Trainz uses FBX as a mesh import format.

=Creating an FBX File=
FBX files are typically created in modelling software such as [http://www.autodesk.com/products/3ds-max/overview Autodesk's 3DS Max], or the [https://www.blender.org Blender Foundation's Blender]. Export instructions for these software packages can be found here:

* [[HowTo/Export from 3DS Max using FBX]]
* [[HowTo/Export from Blender using FBX]]

While it is likely possible to create FBX files from a wide range of other software, we cannot guarantee that all software is capable of producing Trainz-compatible FBX files. The more that a given software is commonly used to produce in-game models in FBX format for other games, the more likely it will also work with Trainz.

=Importing from FBX=

No separate "import" step is required to source a Trainz mesh from FBX format. [[Content Manager]] will perform the necessary conversions when importing an asset.

== Asset Configuration ==
The following configuration is used to import from FBX format:

* The [[config.txt file]] must specify a [[trainz-build]] version of 4.5 or higher.
* The mesh reference in the [[config.txt file]] (for example, in the [["mesh-table" container]]) must use a [[Trainzmesh_file|"*.trainzmesh"]] file extension.
* If the FBX file contains animation tracks, the anim reference in the config.txt file should be named "<mesh-file-name>_<animation-track-name>.kin".
* The FBX file must be placed within the asset folder at the indicated location, but with a "*.FBX" file extension.
* If the FBX file references textures, an image file (eg. "*.tga") or a texture resource (eg. "*.texture.txt") with a matching file name must be present in the same folder as the FBX file.
* If the FBX file contains animation tracks, an animation event file may be present in the same folder as the FBX file. This should be named "<mesh-file-name>_<animation-track-name>.evt". This is not mandatory.

== Mesh Metadata Files ==
Various attributes which users may wish to control are frequently not available in standard modelling packages, or are not exported to the FBX file format. An optional "<mesh-file-name>.txt" file may be included alongside the "<mesh-file-name>.fbx" file to convey these attributes. Where attributes are specified in this metadata file, they override any entries read from the FBX file itself. If an attribute is not specified, it is calculated from the FBX file.

See the [[mesh metadata file]] page for full details.

== Animation Event Files ==
Animation event files are simple hand-created ASCII text files which provide additional sequencing data used to synchronise scripted behaviour with animation playback. They use the file extension "*.evt". Each line of the text file should contain three items separated by whitespace. The items are as follows:

''<frame-number> <event-type> <event-name>''

For example, if the FBX came from Blender and was called:

'''''doors.fbx'''''

the "*.evt" should be labeled

'''''doors_scene.evt'''''

Since Content Manager will create a *.kin file called:

'''''doors_scene.kin'''''

The frame number is a zero-based frame index. Animations are typically exported at 30fps, which means that 0 is the very start of the animation, 30 is one second into the animation, and so on. Events should be in ascending frame order. Frames must be in the form of three digits. For instance, if an event wanted to be triggered at frame 2, then it must be typed as ''002''

Event type must always be "Generic_Event" (without the quotes).

The event name is a word comprised of printable ASCII characters (not including whitespace or line break).

As the animation is played back within Trainz, each event sends a script message to the MeshObject with the major type [[Animation-Event Message|"Animation-Event"]] and the minor type equal to the event name.

Please note that animation event files are processed by the mesh importer and the results are included into the Trainz animation file (*.kin). The game proper never uses "*.evt" files.

An example "*.evt" could look like this:

001 Generic_Event door_start
002 Generic_Event door_sealing
007 Generic_Event door_beeping

If everything is labeled properly, Content Manager should find the event and report it in the log while submitting the Asset. It will display how many events were found in each event file.

[[File:ParsedEvent.png]]

== Submit ==
As the asset is submitted into the [[Trainz Asset Database]], Content Manager will import the FBX, TXT and EVT files, and create a number of matching Trainz-specific files:

* A mesh file is created with the name "<mesh-file-name>.trainzmesh". Any existing file at this path is overwritten.
* One animation file is created per animation track, named as "<mesh-file-name>_<animation-track-name>.kin". Any existing files at these paths are overwritten.
* If necessary, "*.texture.txt" files are created for each source image. Existing files are not overwritten. It is likely that you will want to hand-customise the auto-generated files to configure alpha behaviour or etc.

== Deleting Source Files ==
The source files (FBX, EVT, TXT) are not deleted in this process, however you may choose to delete them once the imports have been completed. Trainz will accept files in "*.trainzmesh" and "*.kin" format without requiring any equivalent "*.fbx", "*.txt" or "*.evt" files. You may alternatively leave the source files in place so that other users can load your source mesh directly into their own modelling package.

== Renaming Binary Files ==
"*.trainzmesh" files and "*.kin" files may optionally be renamed after the initial import once the creating "*.fbx" has been removed- there is no point in renaming binary files while the source "*.fbx" file is still present, as the binary files will simply be re-exported with the original name. When renaming binary files, be sure to update any config.txt references appropriately. This technique can be used to create multiple "*.kin" files which all apply to a single mesh (ie. by importing several *.trainzmesh and *.kin pairs with effectively identical meshes but different animations, then discarding the duplicate meshes).

== Open Source ==
Trainz reads FBX files courtesy of the [http://www.assimp.org ASSIMP] BSD-licensed mesh importer. This product supports both "text" and "binary" FBX formats, but we recommend using binary format where possible. Our version of ASSIMP includes a small number of modifications to improve the robustness of the importer and compatibility with typical Trainz meshes. While the ASSIMP importer library does support a number of other formats beyond FBX, we do not offer this capability in Trainz at the current time.

== Trouble Shooting ==

=== 3DS MAX ===

====Channel Maps====

Sometimes 3DS Max likes to add extra map channels without you realising, and FBX will most likely report an error such as "Error, T13316:FBX: ignoring binormal layer" or "Unable to determine vertex format".

You can remove the extras by:

1) Select mesh

2) Open 'utilities' tab in max

3) Click on 'more...'

4) Click on 'Channel Info'

5) Click on 'Channel Info' button

6) You'll see a list of ID/s etc. There will be a line marked '1:map" in the ID column, and another marked "2:map". Both will have the UVW channel in the 'channel name' column.

7) Select the '1:map' line and click on 'Name' at the top, and enter '-none-' and click ok

8) Select '2:map' and click on 'clear' at the top

Now try exporting.

====Mesh / Bone Scale====

Another one to check is your mesh scale. If any of your meshes are scaled to something other than 100% (X:100, Y:100, Z:100) your mesh is likely to look incorrect or animate incorrectly. Check all bones and meshes to make sure they are 100% scale.

====Displacement Slot====

When you render your scene with a pbrmetaldetail material and forget about the displacement slot, strange results will arise. Don't forget your displacement slot!

====Bogey Animations====
You must name your animation "anim.kin" in your bogey asset. You can leave the anim tag out of your config.txt as the anim.kin file is what the bogeys use.

====Warnings and Errors====
We will be updating this section with more information as we continue testing the new systems.

* Warn, T13272: FBX-DOM (TOK_KEY, offset 0x14d27) source object for connection does not exist
* Error, T13272: FBX: length of input data unexpected for ByPolygon mapping: 2586, expected 2463

To fix these errors, check your UV and channel maps then re-export.

[[Category:Modeling]]
[[Category:Content creation]]

File:ParsedEvent.png

2020-06-17T22:05:56Z

Gdennish:

"mesh-table" container (interior version)

2020-06-17T02:59:55Z

Gdennish: /* mousespeed */

The "mesh-table" container is a top-level [[config.txt file]] entry used by various [[Content_Configuration#Content_Types|Content Types]]. Refer to the [["mesh-table" Container]] documentation for the standard tags - this document only describes the extensions available within the mesh table when it is used in a [[KIND_Interior|cab interior]] asset.

Most of the entries in a mesh-table for an interior will be cab controls. A cab control has a single value associated with it, which could be an input (e.g. a lever position) or an output (a dial or gauge position).

=Standard Mesh Names=

There are a number of standard mesh names that the trainz default cab script uses for it's controls. For a Diesel or Electric cab (either unscripted, or scripted and inheriting from the DefaultLocomotiveCabin class), the following are the default mesh names:

'''Needles:'''
* speedo_needle -- speedometer
* speedo_needle2 -- speedometer
* bplocomain_needle -- loco main reservoir pressure gauge
* bptrainbrakecylinder_needle -- locomotive brake cylinder pressure gauge
* bptrainbrakecylinder_needle2 -- locomotive brake cylinder pressure gauge
* no3pipe_needle -- brake pressure gauge (currently loco brake cylinder -- but maybe intended for something else?)
* bptrainbrakecylinder2_needle -- brake pressure gauge (source unknown)
* bptrainbrakepipe_needle -- train brake pipe pressure gauge
* bptrainbrakepipe_needle2 -- train brake pipe pressure gauge
* bploco_equaliser -- brake equaliser pressure gauge
* flow_needle -- brake flow rate gauge
* ampmeter_needle -- traction ammeter gauge
* ampmeter2_needle -- traction ammeter gauge

'''Levers:'''

* throttle_lever -- throttle lever control
* reverser_lever -- reverser lever control
* trainbrake_lever -- self-lapping train brake control
* trainbrakelap_lever -- non self-lapping train brake control
* independantbrake_lever -- locomotive independent brake control. Note the typo in the control name.
* dynamicbrake_lever -- dynamic brake control
* wheelslip_light -- wheelslip indicator
* horn -- horn control
* light_switch -- light control
* pantograph_lever -- pantograph control
* throttle_brake_lever -- combined throttle/self-lapping brake lever
* bell -- bell control
For a Steam cab (either unscripted, or scripted and inheriting from the DefaultSteamCabin class), these default mesh names are available:

'''Needles:'''

* speedo_needle -- speedometer
* bplocomain_needle -- loco main reservoir pressure gauge
* bptrainbrakecylinder_needle -- locomotive brake cylinder pressure gauge
* no3pipe_needle -- brake pressure gauge (currently loco brake cylinder -- but maybe intended for something else?)
* bptrainbrakecylinder2_needle -- brake pressure gauge (source unknown)
* bptrainbrakepipe_needle -- train brake pipe pressure gauge
* bploco_equaliser -- brake equaliser pressure gauge
* flow_needle -- brake flow rate gauge
* boiler_needle -- boiler pressure
* boiler_needle1 -- boiler pressure
* steam_chest_needle -- steam chest pressure

'''Levers:'''

* trainbrake_lever -- self-lapping train brake control
* trainbrakelap_lever -- non self-lapping train brake control
* independantbrake_lever -- locomotive independent brake control. Note the typo in the control name.
* horn -- horn control
* light_switch -- light control
* waterglass_left -- boiler water level
* waterglass_right -- boiler water level
* firebox -- the interior of the firebox (to show fire temperature) Only works pre-TANE.
* regulator -- regulator (throttle) control
* reverser -- cutoff (reverser) control
* water_injector_0 -- primary water injector control
* water_injector_1 -- secondary water injector control
* blower -- steam blower control
* fire_plates -- the firebox door
* sanding_lever -- locomotive sander control
* blowdown_lever -- blowdown control (releases water out of the boiler)
* bell -- bell control
* left_window -- Left window control
* right_window -- Right window control
* left_sliding_window-- Left sliding window control
* right_sliding_window-- Right sliding window control
* seat0 -- Seat control
* seat1 -- Seat control
* whistle_lever -- Whistle lever control. (Doesn't seem to actually control the horn, so the whistle lever should actually be called "horn" to function properly."

=Supported Tags=
Each mesh subcontainer supports the following tags. Each tag is shown here with its default value. Standard tags inherited from the normal mesh table are omitted for brevity.

tooltip-text ""
tooltip-token ""
tooltip-mesh ""
limits 0,1
angles 0,0
kind ""
collision-parent ""
mousemode ""
mousespeed 1
notches
invert 0
notchheight
onlight ""
value 0.0
font "swiss"
fontsize 12
fontcolor 1.0,1.0,1.0
fade-time 0.5

====angles====
:Type: Decimal Pair
:Desc: Specifies the minimum and maximum extents of movement for a control or needle. For control types that rotate, these values are in radians[[http://en.wikipedia.org/wiki/Radian]]. In the case of a speedometer, this would define the amount of angular movement of the needle - a speedometer running from horizontal left to horizontal right may use -1.57 to 1.57, for example. If the cab control needs to move the other way, put the higher number first.

====collision-parent====
:Type: String
:Desc: A mesh of kind collision-proxy must specify a collision-parent - the mesh it is a collision proxy for. This is the name of another control in the mesh-table.

====fade-time====
:Type: Float
:Desc: The time, in seconds, for a "light" control to fully switch on or off. Default is 0.5 seconds.

====font====
:Type: String
:Desc: Font name to use for the readout of a digital control.
:Options are:
:* ''swiss'' (Default option. Renders with arial in PC builds.)
:* ''times_new_roman''
:* ''verdana''
:* ''century_gothic''
:* ''cordia''
:* ''courier''
:* ''helvetica''
:* ''arial''
:* ''comic_sans''
:* ''sans_serif''
:* ''impact''
:* ''console''
:* ''tohoma'' (renders using the ''Tahoma'' font on PC builds.)
:* ''garamond''
:These roughly correspond with Windows font names. Beware - not all fonts are available on all platforms, and where a font is not available, a different font may be substituted.

====fontcolor====
:Type: Decimal Triplet
:Desc: RGB font color for the readout of a digital control. Colors are specified within the range 0.0 to 1.0, with 0.0 being black and 1.0 being full intensity. Default is 1.0,1.0,1.0 - white.

====fontsize====
:Type: Decimal
:Desc: Font size for the readout of a digital control. Default is 12.

====invert====
:Type: Boolean
:Desc: Invert mouse movement for this control. If the control moves the wrong way compared to the mouse, change this setting.

====kind====
:Type: Selection
:Desc: The type of control this mesh table element represents.
:Options are:
:* ''animated-lever''
:Operates like a standard lever, only uses a named animation instead of the angles tag for movement.
:* ''animated-dial''
:Operates like a standard needle, only uses a named animation to represent the gauge readout instead of the angles tag.
:* ''collision-proxy''
:This element type defines a volume within the cab where the mouse pointer will be considered to be over the cab control. Generally used in conjunction with an animated-lever. Name of the animated lever is defined in the tag ''collision-parent''.
:* ''digital-dial-spd''
:Digital readout for a speedometer, and using speed units.
:* ''digital-dial-prs''
:Digital readout for a pressure gauge, using pressure units.
:* ''firebox''
:The animated firebox in a steam locomotive.
:* ''lever''
:A standard lever, often used for throttle and brake controls. Requires the user to click hold and move the mouse to move the lever between it's notches. This control will stay at any notch position when let go.
:* ''light''
:A light glow / overlay - this mesh is hidden when the light is off and shown when the light is on.
:* ''needle''
:An analogue gauge needle. Can be used to implement many different types of gauges.
:* ''pulllever''
:Like a lever, only sprung to return to it's initial position when the user lets go of the control. Useful for horns.
:* ''pullrope''
:Like a pulllever, only with linear (not rotational) movement.
:* ''switch''
:This control requires only a single click to move between it's two endpoints. It is better suited than a lever to small switches and buttons.
:* ''button''
:Similar to switch but requires the mouse be held down to keep the control active. I.e., press and hold the mouse button to push the control down, release the mouse and the control will return to the off position.

====limits====
:Type: Decimal Pair
:Desc: Specifies the minimum and maximum values for a cab control or needle at it's two endpoints of movement. In the case of a speedometer, this would be the range of speeds it can display - 0m/s to 50m/s, for example.

====mousemode====
:Type: String
:Desc: If set to "exact", will require the mouse to be positioned over the geometry of the control precisely to activate it. Otherwise a bounding volume is used. This is useful for large controls which would otherwise block access to smaller controls.

====mousespeed====
:Type: Float
:Desc: Controls the mouse speed and push/pull direction for controls. The higher the number, the less effort is required by the user to move the lever to another notch. '''''Do not use zero'''''.
:Examples of use:
:* mousespeed -1 - ''Inverts mouse direction.''
:* mousespeed 2 - ''Doubles mouse speed in default direction.''
:* mousespeed -0.5 - ''Inverts mouse direction and halves the speed.''
:* mousespeed 10 - ''Multiplies the mouse speed tenfold in default direction. Useful for smaller levers that require too much mouse movement to activate the lever.''

====notches====
:Type: Decimal List
:Desc: Specifies the positions of the notches for this control. Notches are discrete positions within the movement of the control where the lever can be stopped. If a lever does not have notches, it can be positioned at any location. There are two common uses for notches. Firstly, they can be used to define a control which has a number of discrete positions which mean specific things (e.g. a brake valve). Secondly, they are used to define pre-set discrete values that a control can provide (e.g. a throttle lever). A typical US diesel 8 notch throttle would have something like "notches 0.0,0.125,0.25,0.375,0.5,0.625,0.75,0.875,1.0", specifying nine positions (for 'off' and notches 1 thru 8).
:Notes: When using notches, the tag ''notchheight'' must be used otherwise the lever will not function and spring back to the original position.

====notchheight====
:Type: Integer List
:Desc: Specifies the importance of the notches for this control. This affects how the graphical overlay draws each notch. This is useful for a combined brake and throttle controller, or any other control where you want to mark a specific position relative to the others. This should have the same number of values as the 'notches' list.
:Three styles are available:
:* '1' configures this bar to be a standard length and width bar.
:* '2' configures this bar to be shorter in length, and is often used for intermediate positions.
:* '3' configures this bar to be standard length, but thicker in width. This is often used for marking a specific position.

:Notes: '''A kind ''lever'' type will not function unless notch heights are specified.'''

====onlight====
:Type: String
:Desc: Specify the name of a ''light'' kind mesh which is enabled when this switch/lever is in the ''on'' position, and disabled when it is in the ''off'' position. The mesh name must be in the mesh-table. See the example below.

====radius====
:Type: Decimal
:Desc: Specifies the distance for the 2D notch overlay.

====tooltip-mesh====
:Type: String
:Desc: Specifies the name of a mesh-table entry for a mesh to show when the control is moused over. The mesh will be faded in/out over a short period.

====tooltip-text====
:Type: String
:Desc: OBSOLETE: DO NOT USE. This text will be used in the tooltip that appears when the mouse cursor hovers over a cab control.

====tooltip-token====
:Type: String
:Desc: The name of a string table entry. The contents of the named string table entry will be displayed as a tooltip that appears when the mouse cursor hovers over a cab control. If a token is used then it must appear as a tag in the [[%22String-table%22 container]].

====value====
:Type: Decimal
:Desc: Specifies the initial value for this control. For a lever or other input device, this will specify the initial position of the control before the user moves it.

=Cab Interior Mesh-Table Example=
The following is an example of a mesh-table which implements a number of cab controls

mesh-table
{
default
{
mesh "interior.im"
auto-create 1
}

wheelslip_light
{
kind "light"
mesh "wheelslip_light.im"
auto-create 0
}

bptrainbrakepipe_needle2
{
kind "digital-dial-prs"
mesh "brakeneedle.im"
att "a.brakepipe2"
limits 0,55
font "arial"
fontsize 0.007
fontcolor 80,240,120
auto-create 1
}

speedo_needle2
{
kind "digital-dial-spd"
mesh "brakeneedle.im"
att "a.digispeedo"
limits 0,55
font "arial"
fontsize 0.01
fontcolor 0,0,0
auto-create 1
}

throttle_lever
{
kind "lever"
mesh "throttle.im"
att "a.throttle"
limits 0,8
angles 0,1.69
notches 0,0.125,0.25,0.375,0.5,0.625,0.75,0.875,1
notchheight 1,2,2,2,2,2,2,2,1
radius 0.35
mousespeed -1
auto-create 1
}

dynamicbrake_lever
{
kind "lever"
mesh "dynamic_handle.im"
att "a.dynamic"
limits 0,2
angles 0,-1.69
notches 0,1
notchheight 0.1,1
mousespeed -1
radius 0.35
auto-create 1
}

trainbrakelap_lever
{
kind "lever"
auto-create 1
mesh "trainbrake_handle.im"
att "a.trainbrake_handle"
limits 0,4
angles 0,-2
notches 0,0.25,0.5,0.75,1
notchheight 2,2,2,2,2
mousespeed 1
}

independantbrake_lever
{
kind "lever"
mesh "indy_handle.im"
att "a.ind"
limits 0,32
angles 0.94,0
notches 0,0.5,1
notchheight 1,1,1
radius 0.35
mousespeed 1
auto-create 1
}

flow_needle
{
kind "needle"
mesh "flowneedle.im"
att "a.bpflow"
limits 0,1050
auto-create 1
}

bplocomain_needle
{
kind "needle"
mesh "brakeneedlered.im"
att "a.mainres"
limits 0,1240
auto-create 1
}

bploco_equaliser
{
kind "needle"
mesh "brakeneedle.im"
att "a.eqres"
limits 0,1240
auto-create 1
}

bptrainbrakecylinder_needle
{
kind "needle"
mesh "brakeneedlered.im"
att "a.brakecyl"
limits -50,1390
auto-create 1
}

bptrainbrakepipe_needle
{
kind "needle"
mesh "brakeneedle.im"
att "a.brakepipe"
limits 0,1240
auto-create 1
}

speedo_needle
{
kind "needle"
mesh "speedo_pointer.im"
att "a.speedo"
limits 0,43
auto-create 1
}

ampmeter_needle
{
kind "needle"
mesh "needleamps.im"
att "a.ampmeter"
limits 0,1700
angles 0,3.02058
auto-create 1
}

reverser_lever
{
kind "lever"
mesh "reverser_handle.im"
att "a.throttle01"
limits 0,2
angles -0.55,0.55
notches 0,0.5,1
notchheight 1,1,1
mousespeed -1
auto-create 1
}

light_switch
{
kind "lever"
att "a.hdlt"
mesh "hdltswtch.im"
limits 0,1
angles 0,2
notches 0,1
notchheight 0.1,0.1
mousespeed -1
auto-create 1
}

horn
{
kind "pulllever"
mesh "horn.im"
att "a.horn"
auto-create 1
angles 0,-0.55
limits 0,1
mousespeed -1
radius -0.02
notches 0,1
notchheight 0,0
}

pantograph_lever
{
kind "lever"
mesh "pantograph_lever.im"
att "a.pantograph_lever"
limits 0,3
angles 1.4,0
notches 0,0.5,0.75,1.0
notchheight 0,0,1,1
mousespeed -1
onlight "line_power"
}

line_power
{
kind "light"
mesh "line_power.im"
att "a.line_power"
}
}

[[Category:Config Container|M]]

"mesh-table" container (interior version)

2020-06-17T02:55:31Z

Gdennish: /* notchheight */

The "mesh-table" container is a top-level [[config.txt file]] entry used by various [[Content_Configuration#Content_Types|Content Types]]. Refer to the [["mesh-table" Container]] documentation for the standard tags - this document only describes the extensions available within the mesh table when it is used in a [[KIND_Interior|cab interior]] asset.

Most of the entries in a mesh-table for an interior will be cab controls. A cab control has a single value associated with it, which could be an input (e.g. a lever position) or an output (a dial or gauge position).

=Standard Mesh Names=

There are a number of standard mesh names that the trainz default cab script uses for it's controls. For a Diesel or Electric cab (either unscripted, or scripted and inheriting from the DefaultLocomotiveCabin class), the following are the default mesh names:

'''Needles:'''
* speedo_needle -- speedometer
* speedo_needle2 -- speedometer
* bplocomain_needle -- loco main reservoir pressure gauge
* bptrainbrakecylinder_needle -- locomotive brake cylinder pressure gauge
* bptrainbrakecylinder_needle2 -- locomotive brake cylinder pressure gauge
* no3pipe_needle -- brake pressure gauge (currently loco brake cylinder -- but maybe intended for something else?)
* bptrainbrakecylinder2_needle -- brake pressure gauge (source unknown)
* bptrainbrakepipe_needle -- train brake pipe pressure gauge
* bptrainbrakepipe_needle2 -- train brake pipe pressure gauge
* bploco_equaliser -- brake equaliser pressure gauge
* flow_needle -- brake flow rate gauge
* ampmeter_needle -- traction ammeter gauge
* ampmeter2_needle -- traction ammeter gauge

'''Levers:'''

* throttle_lever -- throttle lever control
* reverser_lever -- reverser lever control
* trainbrake_lever -- self-lapping train brake control
* trainbrakelap_lever -- non self-lapping train brake control
* independantbrake_lever -- locomotive independent brake control. Note the typo in the control name.
* dynamicbrake_lever -- dynamic brake control
* wheelslip_light -- wheelslip indicator
* horn -- horn control
* light_switch -- light control
* pantograph_lever -- pantograph control
* throttle_brake_lever -- combined throttle/self-lapping brake lever
* bell -- bell control
For a Steam cab (either unscripted, or scripted and inheriting from the DefaultSteamCabin class), these default mesh names are available:

'''Needles:'''

* speedo_needle -- speedometer
* bplocomain_needle -- loco main reservoir pressure gauge
* bptrainbrakecylinder_needle -- locomotive brake cylinder pressure gauge
* no3pipe_needle -- brake pressure gauge (currently loco brake cylinder -- but maybe intended for something else?)
* bptrainbrakecylinder2_needle -- brake pressure gauge (source unknown)
* bptrainbrakepipe_needle -- train brake pipe pressure gauge
* bploco_equaliser -- brake equaliser pressure gauge
* flow_needle -- brake flow rate gauge
* boiler_needle -- boiler pressure
* boiler_needle1 -- boiler pressure
* steam_chest_needle -- steam chest pressure

'''Levers:'''

* trainbrake_lever -- self-lapping train brake control
* trainbrakelap_lever -- non self-lapping train brake control
* independantbrake_lever -- locomotive independent brake control. Note the typo in the control name.
* horn -- horn control
* light_switch -- light control
* waterglass_left -- boiler water level
* waterglass_right -- boiler water level
* firebox -- the interior of the firebox (to show fire temperature) Only works pre-TANE.
* regulator -- regulator (throttle) control
* reverser -- cutoff (reverser) control
* water_injector_0 -- primary water injector control
* water_injector_1 -- secondary water injector control
* blower -- steam blower control
* fire_plates -- the firebox door
* sanding_lever -- locomotive sander control
* blowdown_lever -- blowdown control (releases water out of the boiler)
* bell -- bell control
* left_window -- Left window control
* right_window -- Right window control
* left_sliding_window-- Left sliding window control
* right_sliding_window-- Right sliding window control
* seat0 -- Seat control
* seat1 -- Seat control
* whistle_lever -- Whistle lever control. (Doesn't seem to actually control the horn, so the whistle lever should actually be called "horn" to function properly."

=Supported Tags=
Each mesh subcontainer supports the following tags. Each tag is shown here with its default value. Standard tags inherited from the normal mesh table are omitted for brevity.

tooltip-text ""
tooltip-token ""
tooltip-mesh ""
limits 0,1
angles 0,0
kind ""
collision-parent ""
mousemode ""
mousespeed 1
notches
invert 0
notchheight
onlight ""
value 0.0
font "swiss"
fontsize 12
fontcolor 1.0,1.0,1.0
fade-time 0.5

====angles====
:Type: Decimal Pair
:Desc: Specifies the minimum and maximum extents of movement for a control or needle. For control types that rotate, these values are in radians[[http://en.wikipedia.org/wiki/Radian]]. In the case of a speedometer, this would define the amount of angular movement of the needle - a speedometer running from horizontal left to horizontal right may use -1.57 to 1.57, for example. If the cab control needs to move the other way, put the higher number first.

====collision-parent====
:Type: String
:Desc: A mesh of kind collision-proxy must specify a collision-parent - the mesh it is a collision proxy for. This is the name of another control in the mesh-table.

====fade-time====
:Type: Float
:Desc: The time, in seconds, for a "light" control to fully switch on or off. Default is 0.5 seconds.

====font====
:Type: String
:Desc: Font name to use for the readout of a digital control.
:Options are:
:* ''swiss'' (Default option. Renders with arial in PC builds.)
:* ''times_new_roman''
:* ''verdana''
:* ''century_gothic''
:* ''cordia''
:* ''courier''
:* ''helvetica''
:* ''arial''
:* ''comic_sans''
:* ''sans_serif''
:* ''impact''
:* ''console''
:* ''tohoma'' (renders using the ''Tahoma'' font on PC builds.)
:* ''garamond''
:These roughly correspond with Windows font names. Beware - not all fonts are available on all platforms, and where a font is not available, a different font may be substituted.

====fontcolor====
:Type: Decimal Triplet
:Desc: RGB font color for the readout of a digital control. Colors are specified within the range 0.0 to 1.0, with 0.0 being black and 1.0 being full intensity. Default is 1.0,1.0,1.0 - white.

====fontsize====
:Type: Decimal
:Desc: Font size for the readout of a digital control. Default is 12.

====invert====
:Type: Boolean
:Desc: Invert mouse movement for this control. If the control moves the wrong way compared to the mouse, change this setting.

====kind====
:Type: Selection
:Desc: The type of control this mesh table element represents.
:Options are:
:* ''animated-lever''
:Operates like a standard lever, only uses a named animation instead of the angles tag for movement.
:* ''animated-dial''
:Operates like a standard needle, only uses a named animation to represent the gauge readout instead of the angles tag.
:* ''collision-proxy''
:This element type defines a volume within the cab where the mouse pointer will be considered to be over the cab control. Generally used in conjunction with an animated-lever. Name of the animated lever is defined in the tag ''collision-parent''.
:* ''digital-dial-spd''
:Digital readout for a speedometer, and using speed units.
:* ''digital-dial-prs''
:Digital readout for a pressure gauge, using pressure units.
:* ''firebox''
:The animated firebox in a steam locomotive.
:* ''lever''
:A standard lever, often used for throttle and brake controls. Requires the user to click hold and move the mouse to move the lever between it's notches. This control will stay at any notch position when let go.
:* ''light''
:A light glow / overlay - this mesh is hidden when the light is off and shown when the light is on.
:* ''needle''
:An analogue gauge needle. Can be used to implement many different types of gauges.
:* ''pulllever''
:Like a lever, only sprung to return to it's initial position when the user lets go of the control. Useful for horns.
:* ''pullrope''
:Like a pulllever, only with linear (not rotational) movement.
:* ''switch''
:This control requires only a single click to move between it's two endpoints. It is better suited than a lever to small switches and buttons.
:* ''button''
:Similar to switch but requires the mouse be held down to keep the control active. I.e., press and hold the mouse button to push the control down, release the mouse and the control will return to the off position.

====limits====
:Type: Decimal Pair
:Desc: Specifies the minimum and maximum values for a cab control or needle at it's two endpoints of movement. In the case of a speedometer, this would be the range of speeds it can display - 0m/s to 50m/s, for example.

====mousemode====
:Type: String
:Desc: If set to "exact", will require the mouse to be positioned over the geometry of the control precisely to activate it. Otherwise a bounding volume is used. This is useful for large controls which would otherwise block access to smaller controls.

====mousespeed====
:Type: Float
:Desc: Controls the mouse speed and push/pull direction for controls. '''''Do not use zero'''''.
:Examples of use:
:* mousespeed -1 Inverts mouse direction.
:* mousespeed 2 Doubles mouse speed in default direction.
:* mousespeed -0.5 Inverts mouse direction and halves the speed.
:* mousespeed 10 Multiplies the mouse speed tenfold in default direction. Useful for smaller levers that require too much mouse movement to activate the lever.

====notches====
:Type: Decimal List
:Desc: Specifies the positions of the notches for this control. Notches are discrete positions within the movement of the control where the lever can be stopped. If a lever does not have notches, it can be positioned at any location. There are two common uses for notches. Firstly, they can be used to define a control which has a number of discrete positions which mean specific things (e.g. a brake valve). Secondly, they are used to define pre-set discrete values that a control can provide (e.g. a throttle lever). A typical US diesel 8 notch throttle would have something like "notches 0.0,0.125,0.25,0.375,0.5,0.625,0.75,0.875,1.0", specifying nine positions (for 'off' and notches 1 thru 8).
:Notes: When using notches, the tag ''notchheight'' must be used otherwise the lever will not function and spring back to the original position.

====notchheight====
:Type: Integer List
:Desc: Specifies the importance of the notches for this control. This affects how the graphical overlay draws each notch. This is useful for a combined brake and throttle controller, or any other control where you want to mark a specific position relative to the others. This should have the same number of values as the 'notches' list.
:Three styles are available:
:* '1' configures this bar to be a standard length and width bar.
:* '2' configures this bar to be shorter in length, and is often used for intermediate positions.
:* '3' configures this bar to be standard length, but thicker in width. This is often used for marking a specific position.

:Notes: '''A kind ''lever'' type will not function unless notch heights are specified.'''

====onlight====
:Type: String
:Desc: Specify the name of a ''light'' kind mesh which is enabled when this switch/lever is in the ''on'' position, and disabled when it is in the ''off'' position. The mesh name must be in the mesh-table. See the example below.

====radius====
:Type: Decimal
:Desc: Specifies the distance for the 2D notch overlay.

====tooltip-mesh====
:Type: String
:Desc: Specifies the name of a mesh-table entry for a mesh to show when the control is moused over. The mesh will be faded in/out over a short period.

====tooltip-text====
:Type: String
:Desc: OBSOLETE: DO NOT USE. This text will be used in the tooltip that appears when the mouse cursor hovers over a cab control.

====tooltip-token====
:Type: String
:Desc: The name of a string table entry. The contents of the named string table entry will be displayed as a tooltip that appears when the mouse cursor hovers over a cab control. If a token is used then it must appear as a tag in the [[%22String-table%22 container]].

====value====
:Type: Decimal
:Desc: Specifies the initial value for this control. For a lever or other input device, this will specify the initial position of the control before the user moves it.

=Cab Interior Mesh-Table Example=
The following is an example of a mesh-table which implements a number of cab controls

mesh-table
{
default
{
mesh "interior.im"
auto-create 1
}

wheelslip_light
{
kind "light"
mesh "wheelslip_light.im"
auto-create 0
}

bptrainbrakepipe_needle2
{
kind "digital-dial-prs"
mesh "brakeneedle.im"
att "a.brakepipe2"
limits 0,55
font "arial"
fontsize 0.007
fontcolor 80,240,120
auto-create 1
}

speedo_needle2
{
kind "digital-dial-spd"
mesh "brakeneedle.im"
att "a.digispeedo"
limits 0,55
font "arial"
fontsize 0.01
fontcolor 0,0,0
auto-create 1
}

throttle_lever
{
kind "lever"
mesh "throttle.im"
att "a.throttle"
limits 0,8
angles 0,1.69
notches 0,0.125,0.25,0.375,0.5,0.625,0.75,0.875,1
notchheight 1,2,2,2,2,2,2,2,1
radius 0.35
mousespeed -1
auto-create 1
}

dynamicbrake_lever
{
kind "lever"
mesh "dynamic_handle.im"
att "a.dynamic"
limits 0,2
angles 0,-1.69
notches 0,1
notchheight 0.1,1
mousespeed -1
radius 0.35
auto-create 1
}

trainbrakelap_lever
{
kind "lever"
auto-create 1
mesh "trainbrake_handle.im"
att "a.trainbrake_handle"
limits 0,4
angles 0,-2
notches 0,0.25,0.5,0.75,1
notchheight 2,2,2,2,2
mousespeed 1
}

independantbrake_lever
{
kind "lever"
mesh "indy_handle.im"
att "a.ind"
limits 0,32
angles 0.94,0
notches 0,0.5,1
notchheight 1,1,1
radius 0.35
mousespeed 1
auto-create 1
}

flow_needle
{
kind "needle"
mesh "flowneedle.im"
att "a.bpflow"
limits 0,1050
auto-create 1
}

bplocomain_needle
{
kind "needle"
mesh "brakeneedlered.im"
att "a.mainres"
limits 0,1240
auto-create 1
}

bploco_equaliser
{
kind "needle"
mesh "brakeneedle.im"
att "a.eqres"
limits 0,1240
auto-create 1
}

bptrainbrakecylinder_needle
{
kind "needle"
mesh "brakeneedlered.im"
att "a.brakecyl"
limits -50,1390
auto-create 1
}

bptrainbrakepipe_needle
{
kind "needle"
mesh "brakeneedle.im"
att "a.brakepipe"
limits 0,1240
auto-create 1
}

speedo_needle
{
kind "needle"
mesh "speedo_pointer.im"
att "a.speedo"
limits 0,43
auto-create 1
}

ampmeter_needle
{
kind "needle"
mesh "needleamps.im"
att "a.ampmeter"
limits 0,1700
angles 0,3.02058
auto-create 1
}

reverser_lever
{
kind "lever"
mesh "reverser_handle.im"
att "a.throttle01"
limits 0,2
angles -0.55,0.55
notches 0,0.5,1
notchheight 1,1,1
mousespeed -1
auto-create 1
}

light_switch
{
kind "lever"
att "a.hdlt"
mesh "hdltswtch.im"
limits 0,1
angles 0,2
notches 0,1
notchheight 0.1,0.1
mousespeed -1
auto-create 1
}

horn
{
kind "pulllever"
mesh "horn.im"
att "a.horn"
auto-create 1
angles 0,-0.55
limits 0,1
mousespeed -1
radius -0.02
notches 0,1
notchheight 0,0
}

pantograph_lever
{
kind "lever"
mesh "pantograph_lever.im"
att "a.pantograph_lever"
limits 0,3
angles 1.4,0
notches 0,0.5,0.75,1.0
notchheight 0,0,1,1
mousespeed -1
onlight "line_power"
}

line_power
{
kind "light"
mesh "line_power.im"
att "a.line_power"
}
}

[[Category:Config Container|M]]

"mesh-table" container (interior version)

2020-06-17T02:54:58Z

Gdennish: /* notches */

The "mesh-table" container is a top-level [[config.txt file]] entry used by various [[Content_Configuration#Content_Types|Content Types]]. Refer to the [["mesh-table" Container]] documentation for the standard tags - this document only describes the extensions available within the mesh table when it is used in a [[KIND_Interior|cab interior]] asset.

Most of the entries in a mesh-table for an interior will be cab controls. A cab control has a single value associated with it, which could be an input (e.g. a lever position) or an output (a dial or gauge position).

=Standard Mesh Names=

There are a number of standard mesh names that the trainz default cab script uses for it's controls. For a Diesel or Electric cab (either unscripted, or scripted and inheriting from the DefaultLocomotiveCabin class), the following are the default mesh names:

'''Needles:'''
* speedo_needle -- speedometer
* speedo_needle2 -- speedometer
* bplocomain_needle -- loco main reservoir pressure gauge
* bptrainbrakecylinder_needle -- locomotive brake cylinder pressure gauge
* bptrainbrakecylinder_needle2 -- locomotive brake cylinder pressure gauge
* no3pipe_needle -- brake pressure gauge (currently loco brake cylinder -- but maybe intended for something else?)
* bptrainbrakecylinder2_needle -- brake pressure gauge (source unknown)
* bptrainbrakepipe_needle -- train brake pipe pressure gauge
* bptrainbrakepipe_needle2 -- train brake pipe pressure gauge
* bploco_equaliser -- brake equaliser pressure gauge
* flow_needle -- brake flow rate gauge
* ampmeter_needle -- traction ammeter gauge
* ampmeter2_needle -- traction ammeter gauge

'''Levers:'''

* throttle_lever -- throttle lever control
* reverser_lever -- reverser lever control
* trainbrake_lever -- self-lapping train brake control
* trainbrakelap_lever -- non self-lapping train brake control
* independantbrake_lever -- locomotive independent brake control. Note the typo in the control name.
* dynamicbrake_lever -- dynamic brake control
* wheelslip_light -- wheelslip indicator
* horn -- horn control
* light_switch -- light control
* pantograph_lever -- pantograph control
* throttle_brake_lever -- combined throttle/self-lapping brake lever
* bell -- bell control
For a Steam cab (either unscripted, or scripted and inheriting from the DefaultSteamCabin class), these default mesh names are available:

'''Needles:'''

* speedo_needle -- speedometer
* bplocomain_needle -- loco main reservoir pressure gauge
* bptrainbrakecylinder_needle -- locomotive brake cylinder pressure gauge
* no3pipe_needle -- brake pressure gauge (currently loco brake cylinder -- but maybe intended for something else?)
* bptrainbrakecylinder2_needle -- brake pressure gauge (source unknown)
* bptrainbrakepipe_needle -- train brake pipe pressure gauge
* bploco_equaliser -- brake equaliser pressure gauge
* flow_needle -- brake flow rate gauge
* boiler_needle -- boiler pressure
* boiler_needle1 -- boiler pressure
* steam_chest_needle -- steam chest pressure

'''Levers:'''

* trainbrake_lever -- self-lapping train brake control
* trainbrakelap_lever -- non self-lapping train brake control
* independantbrake_lever -- locomotive independent brake control. Note the typo in the control name.
* horn -- horn control
* light_switch -- light control
* waterglass_left -- boiler water level
* waterglass_right -- boiler water level
* firebox -- the interior of the firebox (to show fire temperature) Only works pre-TANE.
* regulator -- regulator (throttle) control
* reverser -- cutoff (reverser) control
* water_injector_0 -- primary water injector control
* water_injector_1 -- secondary water injector control
* blower -- steam blower control
* fire_plates -- the firebox door
* sanding_lever -- locomotive sander control
* blowdown_lever -- blowdown control (releases water out of the boiler)
* bell -- bell control
* left_window -- Left window control
* right_window -- Right window control
* left_sliding_window-- Left sliding window control
* right_sliding_window-- Right sliding window control
* seat0 -- Seat control
* seat1 -- Seat control
* whistle_lever -- Whistle lever control. (Doesn't seem to actually control the horn, so the whistle lever should actually be called "horn" to function properly."

=Supported Tags=
Each mesh subcontainer supports the following tags. Each tag is shown here with its default value. Standard tags inherited from the normal mesh table are omitted for brevity.

tooltip-text ""
tooltip-token ""
tooltip-mesh ""
limits 0,1
angles 0,0
kind ""
collision-parent ""
mousemode ""
mousespeed 1
notches
invert 0
notchheight
onlight ""
value 0.0
font "swiss"
fontsize 12
fontcolor 1.0,1.0,1.0
fade-time 0.5

====angles====
:Type: Decimal Pair
:Desc: Specifies the minimum and maximum extents of movement for a control or needle. For control types that rotate, these values are in radians[[http://en.wikipedia.org/wiki/Radian]]. In the case of a speedometer, this would define the amount of angular movement of the needle - a speedometer running from horizontal left to horizontal right may use -1.57 to 1.57, for example. If the cab control needs to move the other way, put the higher number first.

====collision-parent====
:Type: String
:Desc: A mesh of kind collision-proxy must specify a collision-parent - the mesh it is a collision proxy for. This is the name of another control in the mesh-table.

====fade-time====
:Type: Float
:Desc: The time, in seconds, for a "light" control to fully switch on or off. Default is 0.5 seconds.

====font====
:Type: String
:Desc: Font name to use for the readout of a digital control.
:Options are:
:* ''swiss'' (Default option. Renders with arial in PC builds.)
:* ''times_new_roman''
:* ''verdana''
:* ''century_gothic''
:* ''cordia''
:* ''courier''
:* ''helvetica''
:* ''arial''
:* ''comic_sans''
:* ''sans_serif''
:* ''impact''
:* ''console''
:* ''tohoma'' (renders using the ''Tahoma'' font on PC builds.)
:* ''garamond''
:These roughly correspond with Windows font names. Beware - not all fonts are available on all platforms, and where a font is not available, a different font may be substituted.

====fontcolor====
:Type: Decimal Triplet
:Desc: RGB font color for the readout of a digital control. Colors are specified within the range 0.0 to 1.0, with 0.0 being black and 1.0 being full intensity. Default is 1.0,1.0,1.0 - white.

====fontsize====
:Type: Decimal
:Desc: Font size for the readout of a digital control. Default is 12.

====invert====
:Type: Boolean
:Desc: Invert mouse movement for this control. If the control moves the wrong way compared to the mouse, change this setting.

====kind====
:Type: Selection
:Desc: The type of control this mesh table element represents.
:Options are:
:* ''animated-lever''
:Operates like a standard lever, only uses a named animation instead of the angles tag for movement.
:* ''animated-dial''
:Operates like a standard needle, only uses a named animation to represent the gauge readout instead of the angles tag.
:* ''collision-proxy''
:This element type defines a volume within the cab where the mouse pointer will be considered to be over the cab control. Generally used in conjunction with an animated-lever. Name of the animated lever is defined in the tag ''collision-parent''.
:* ''digital-dial-spd''
:Digital readout for a speedometer, and using speed units.
:* ''digital-dial-prs''
:Digital readout for a pressure gauge, using pressure units.
:* ''firebox''
:The animated firebox in a steam locomotive.
:* ''lever''
:A standard lever, often used for throttle and brake controls. Requires the user to click hold and move the mouse to move the lever between it's notches. This control will stay at any notch position when let go.
:* ''light''
:A light glow / overlay - this mesh is hidden when the light is off and shown when the light is on.
:* ''needle''
:An analogue gauge needle. Can be used to implement many different types of gauges.
:* ''pulllever''
:Like a lever, only sprung to return to it's initial position when the user lets go of the control. Useful for horns.
:* ''pullrope''
:Like a pulllever, only with linear (not rotational) movement.
:* ''switch''
:This control requires only a single click to move between it's two endpoints. It is better suited than a lever to small switches and buttons.
:* ''button''
:Similar to switch but requires the mouse be held down to keep the control active. I.e., press and hold the mouse button to push the control down, release the mouse and the control will return to the off position.

====limits====
:Type: Decimal Pair
:Desc: Specifies the minimum and maximum values for a cab control or needle at it's two endpoints of movement. In the case of a speedometer, this would be the range of speeds it can display - 0m/s to 50m/s, for example.

====mousemode====
:Type: String
:Desc: If set to "exact", will require the mouse to be positioned over the geometry of the control precisely to activate it. Otherwise a bounding volume is used. This is useful for large controls which would otherwise block access to smaller controls.

====mousespeed====
:Type: Float
:Desc: Controls the mouse speed and push/pull direction for controls. '''''Do not use zero'''''.
:Examples of use:
:* mousespeed -1 Inverts mouse direction.
:* mousespeed 2 Doubles mouse speed in default direction.
:* mousespeed -0.5 Inverts mouse direction and halves the speed.
:* mousespeed 10 Multiplies the mouse speed tenfold in default direction. Useful for smaller levers that require too much mouse movement to activate the lever.

====notches====
:Type: Decimal List
:Desc: Specifies the positions of the notches for this control. Notches are discrete positions within the movement of the control where the lever can be stopped. If a lever does not have notches, it can be positioned at any location. There are two common uses for notches. Firstly, they can be used to define a control which has a number of discrete positions which mean specific things (e.g. a brake valve). Secondly, they are used to define pre-set discrete values that a control can provide (e.g. a throttle lever). A typical US diesel 8 notch throttle would have something like "notches 0.0,0.125,0.25,0.375,0.5,0.625,0.75,0.875,1.0", specifying nine positions (for 'off' and notches 1 thru 8).
:Notes: When using notches, the tag ''notchheight'' must be used otherwise the lever will not function and spring back to the original position.

====notchheight====
:Type: Integer List
:Desc: Specifies the importance of the notches for this control. This affects how the graphical overlay draws each notch. This is useful for a combined brake and throttle controller, or any other control where you want to mark a specific position relative to the others. This should have the same number of values as the 'notches' list.
:Three styles are available:
:* '1' configures this bar to be a standard length and width bar.
:* '2' configures this bar to be shorter in length, and is often used for intermediate positions.
:* '3' configures this bar to be standard length, but thicker in width. This is often used for marking a specific position.

'''A kind ''lever'' type will not function unless notch heights are specified.'''

====onlight====
:Type: String
:Desc: Specify the name of a ''light'' kind mesh which is enabled when this switch/lever is in the ''on'' position, and disabled when it is in the ''off'' position. The mesh name must be in the mesh-table. See the example below.

====radius====
:Type: Decimal
:Desc: Specifies the distance for the 2D notch overlay.

====tooltip-mesh====
:Type: String
:Desc: Specifies the name of a mesh-table entry for a mesh to show when the control is moused over. The mesh will be faded in/out over a short period.

====tooltip-text====
:Type: String
:Desc: OBSOLETE: DO NOT USE. This text will be used in the tooltip that appears when the mouse cursor hovers over a cab control.

====tooltip-token====
:Type: String
:Desc: The name of a string table entry. The contents of the named string table entry will be displayed as a tooltip that appears when the mouse cursor hovers over a cab control. If a token is used then it must appear as a tag in the [[%22String-table%22 container]].

====value====
:Type: Decimal
:Desc: Specifies the initial value for this control. For a lever or other input device, this will specify the initial position of the control before the user moves it.

=Cab Interior Mesh-Table Example=
The following is an example of a mesh-table which implements a number of cab controls

mesh-table
{
default
{
mesh "interior.im"
auto-create 1
}

wheelslip_light
{
kind "light"
mesh "wheelslip_light.im"
auto-create 0
}

bptrainbrakepipe_needle2
{
kind "digital-dial-prs"
mesh "brakeneedle.im"
att "a.brakepipe2"
limits 0,55
font "arial"
fontsize 0.007
fontcolor 80,240,120
auto-create 1
}

speedo_needle2
{
kind "digital-dial-spd"
mesh "brakeneedle.im"
att "a.digispeedo"
limits 0,55
font "arial"
fontsize 0.01
fontcolor 0,0,0
auto-create 1
}

throttle_lever
{
kind "lever"
mesh "throttle.im"
att "a.throttle"
limits 0,8
angles 0,1.69
notches 0,0.125,0.25,0.375,0.5,0.625,0.75,0.875,1
notchheight 1,2,2,2,2,2,2,2,1
radius 0.35
mousespeed -1
auto-create 1
}

dynamicbrake_lever
{
kind "lever"
mesh "dynamic_handle.im"
att "a.dynamic"
limits 0,2
angles 0,-1.69
notches 0,1
notchheight 0.1,1
mousespeed -1
radius 0.35
auto-create 1
}

trainbrakelap_lever
{
kind "lever"
auto-create 1
mesh "trainbrake_handle.im"
att "a.trainbrake_handle"
limits 0,4
angles 0,-2
notches 0,0.25,0.5,0.75,1
notchheight 2,2,2,2,2
mousespeed 1
}

independantbrake_lever
{
kind "lever"
mesh "indy_handle.im"
att "a.ind"
limits 0,32
angles 0.94,0
notches 0,0.5,1
notchheight 1,1,1
radius 0.35
mousespeed 1
auto-create 1
}

flow_needle
{
kind "needle"
mesh "flowneedle.im"
att "a.bpflow"
limits 0,1050
auto-create 1
}

bplocomain_needle
{
kind "needle"
mesh "brakeneedlered.im"
att "a.mainres"
limits 0,1240
auto-create 1
}

bploco_equaliser
{
kind "needle"
mesh "brakeneedle.im"
att "a.eqres"
limits 0,1240
auto-create 1
}

bptrainbrakecylinder_needle
{
kind "needle"
mesh "brakeneedlered.im"
att "a.brakecyl"
limits -50,1390
auto-create 1
}

bptrainbrakepipe_needle
{
kind "needle"
mesh "brakeneedle.im"
att "a.brakepipe"
limits 0,1240
auto-create 1
}

speedo_needle
{
kind "needle"
mesh "speedo_pointer.im"
att "a.speedo"
limits 0,43
auto-create 1
}

ampmeter_needle
{
kind "needle"
mesh "needleamps.im"
att "a.ampmeter"
limits 0,1700
angles 0,3.02058
auto-create 1
}

reverser_lever
{
kind "lever"
mesh "reverser_handle.im"
att "a.throttle01"
limits 0,2
angles -0.55,0.55
notches 0,0.5,1
notchheight 1,1,1
mousespeed -1
auto-create 1
}

light_switch
{
kind "lever"
att "a.hdlt"
mesh "hdltswtch.im"
limits 0,1
angles 0,2
notches 0,1
notchheight 0.1,0.1
mousespeed -1
auto-create 1
}

horn
{
kind "pulllever"
mesh "horn.im"
att "a.horn"
auto-create 1
angles 0,-0.55
limits 0,1
mousespeed -1
radius -0.02
notches 0,1
notchheight 0,0
}

pantograph_lever
{
kind "lever"
mesh "pantograph_lever.im"
att "a.pantograph_lever"
limits 0,3
angles 1.4,0
notches 0,0.5,0.75,1.0
notchheight 0,0,1,1
mousespeed -1
onlight "line_power"
}

line_power
{
kind "light"
mesh "line_power.im"
att "a.line_power"
}
}

[[Category:Config Container|M]]

"mesh-table" container (interior version)

2020-06-17T02:50:49Z

Gdennish: /* notchheight */

The "mesh-table" container is a top-level [[config.txt file]] entry used by various [[Content_Configuration#Content_Types|Content Types]]. Refer to the [["mesh-table" Container]] documentation for the standard tags - this document only describes the extensions available within the mesh table when it is used in a [[KIND_Interior|cab interior]] asset.

Most of the entries in a mesh-table for an interior will be cab controls. A cab control has a single value associated with it, which could be an input (e.g. a lever position) or an output (a dial or gauge position).

=Standard Mesh Names=

There are a number of standard mesh names that the trainz default cab script uses for it's controls. For a Diesel or Electric cab (either unscripted, or scripted and inheriting from the DefaultLocomotiveCabin class), the following are the default mesh names:

'''Needles:'''
* speedo_needle -- speedometer
* speedo_needle2 -- speedometer
* bplocomain_needle -- loco main reservoir pressure gauge
* bptrainbrakecylinder_needle -- locomotive brake cylinder pressure gauge
* bptrainbrakecylinder_needle2 -- locomotive brake cylinder pressure gauge
* no3pipe_needle -- brake pressure gauge (currently loco brake cylinder -- but maybe intended for something else?)
* bptrainbrakecylinder2_needle -- brake pressure gauge (source unknown)
* bptrainbrakepipe_needle -- train brake pipe pressure gauge
* bptrainbrakepipe_needle2 -- train brake pipe pressure gauge
* bploco_equaliser -- brake equaliser pressure gauge
* flow_needle -- brake flow rate gauge
* ampmeter_needle -- traction ammeter gauge
* ampmeter2_needle -- traction ammeter gauge

'''Levers:'''

* throttle_lever -- throttle lever control
* reverser_lever -- reverser lever control
* trainbrake_lever -- self-lapping train brake control
* trainbrakelap_lever -- non self-lapping train brake control
* independantbrake_lever -- locomotive independent brake control. Note the typo in the control name.
* dynamicbrake_lever -- dynamic brake control
* wheelslip_light -- wheelslip indicator
* horn -- horn control
* light_switch -- light control
* pantograph_lever -- pantograph control
* throttle_brake_lever -- combined throttle/self-lapping brake lever
* bell -- bell control
For a Steam cab (either unscripted, or scripted and inheriting from the DefaultSteamCabin class), these default mesh names are available:

'''Needles:'''

* speedo_needle -- speedometer
* bplocomain_needle -- loco main reservoir pressure gauge
* bptrainbrakecylinder_needle -- locomotive brake cylinder pressure gauge
* no3pipe_needle -- brake pressure gauge (currently loco brake cylinder -- but maybe intended for something else?)
* bptrainbrakecylinder2_needle -- brake pressure gauge (source unknown)
* bptrainbrakepipe_needle -- train brake pipe pressure gauge
* bploco_equaliser -- brake equaliser pressure gauge
* flow_needle -- brake flow rate gauge
* boiler_needle -- boiler pressure
* boiler_needle1 -- boiler pressure
* steam_chest_needle -- steam chest pressure

'''Levers:'''

* trainbrake_lever -- self-lapping train brake control
* trainbrakelap_lever -- non self-lapping train brake control
* independantbrake_lever -- locomotive independent brake control. Note the typo in the control name.
* horn -- horn control
* light_switch -- light control
* waterglass_left -- boiler water level
* waterglass_right -- boiler water level
* firebox -- the interior of the firebox (to show fire temperature) Only works pre-TANE.
* regulator -- regulator (throttle) control
* reverser -- cutoff (reverser) control
* water_injector_0 -- primary water injector control
* water_injector_1 -- secondary water injector control
* blower -- steam blower control
* fire_plates -- the firebox door
* sanding_lever -- locomotive sander control
* blowdown_lever -- blowdown control (releases water out of the boiler)
* bell -- bell control
* left_window -- Left window control
* right_window -- Right window control
* left_sliding_window-- Left sliding window control
* right_sliding_window-- Right sliding window control
* seat0 -- Seat control
* seat1 -- Seat control
* whistle_lever -- Whistle lever control. (Doesn't seem to actually control the horn, so the whistle lever should actually be called "horn" to function properly."

=Supported Tags=
Each mesh subcontainer supports the following tags. Each tag is shown here with its default value. Standard tags inherited from the normal mesh table are omitted for brevity.

tooltip-text ""
tooltip-token ""
tooltip-mesh ""
limits 0,1
angles 0,0
kind ""
collision-parent ""
mousemode ""
mousespeed 1
notches
invert 0
notchheight
onlight ""
value 0.0
font "swiss"
fontsize 12
fontcolor 1.0,1.0,1.0
fade-time 0.5

====angles====
:Type: Decimal Pair
:Desc: Specifies the minimum and maximum extents of movement for a control or needle. For control types that rotate, these values are in radians[[http://en.wikipedia.org/wiki/Radian]]. In the case of a speedometer, this would define the amount of angular movement of the needle - a speedometer running from horizontal left to horizontal right may use -1.57 to 1.57, for example. If the cab control needs to move the other way, put the higher number first.

====collision-parent====
:Type: String
:Desc: A mesh of kind collision-proxy must specify a collision-parent - the mesh it is a collision proxy for. This is the name of another control in the mesh-table.

====fade-time====
:Type: Float
:Desc: The time, in seconds, for a "light" control to fully switch on or off. Default is 0.5 seconds.

====font====
:Type: String
:Desc: Font name to use for the readout of a digital control.
:Options are:
:* ''swiss'' (Default option. Renders with arial in PC builds.)
:* ''times_new_roman''
:* ''verdana''
:* ''century_gothic''
:* ''cordia''
:* ''courier''
:* ''helvetica''
:* ''arial''
:* ''comic_sans''
:* ''sans_serif''
:* ''impact''
:* ''console''
:* ''tohoma'' (renders using the ''Tahoma'' font on PC builds.)
:* ''garamond''
:These roughly correspond with Windows font names. Beware - not all fonts are available on all platforms, and where a font is not available, a different font may be substituted.

====fontcolor====
:Type: Decimal Triplet
:Desc: RGB font color for the readout of a digital control. Colors are specified within the range 0.0 to 1.0, with 0.0 being black and 1.0 being full intensity. Default is 1.0,1.0,1.0 - white.

====fontsize====
:Type: Decimal
:Desc: Font size for the readout of a digital control. Default is 12.

====invert====
:Type: Boolean
:Desc: Invert mouse movement for this control. If the control moves the wrong way compared to the mouse, change this setting.

====kind====
:Type: Selection
:Desc: The type of control this mesh table element represents.
:Options are:
:* ''animated-lever''
:Operates like a standard lever, only uses a named animation instead of the angles tag for movement.
:* ''animated-dial''
:Operates like a standard needle, only uses a named animation to represent the gauge readout instead of the angles tag.
:* ''collision-proxy''
:This element type defines a volume within the cab where the mouse pointer will be considered to be over the cab control. Generally used in conjunction with an animated-lever. Name of the animated lever is defined in the tag ''collision-parent''.
:* ''digital-dial-spd''
:Digital readout for a speedometer, and using speed units.
:* ''digital-dial-prs''
:Digital readout for a pressure gauge, using pressure units.
:* ''firebox''
:The animated firebox in a steam locomotive.
:* ''lever''
:A standard lever, often used for throttle and brake controls. Requires the user to click hold and move the mouse to move the lever between it's notches. This control will stay at any notch position when let go.
:* ''light''
:A light glow / overlay - this mesh is hidden when the light is off and shown when the light is on.
:* ''needle''
:An analogue gauge needle. Can be used to implement many different types of gauges.
:* ''pulllever''
:Like a lever, only sprung to return to it's initial position when the user lets go of the control. Useful for horns.
:* ''pullrope''
:Like a pulllever, only with linear (not rotational) movement.
:* ''switch''
:This control requires only a single click to move between it's two endpoints. It is better suited than a lever to small switches and buttons.
:* ''button''
:Similar to switch but requires the mouse be held down to keep the control active. I.e., press and hold the mouse button to push the control down, release the mouse and the control will return to the off position.

====limits====
:Type: Decimal Pair
:Desc: Specifies the minimum and maximum values for a cab control or needle at it's two endpoints of movement. In the case of a speedometer, this would be the range of speeds it can display - 0m/s to 50m/s, for example.

====mousemode====
:Type: String
:Desc: If set to "exact", will require the mouse to be positioned over the geometry of the control precisely to activate it. Otherwise a bounding volume is used. This is useful for large controls which would otherwise block access to smaller controls.

====mousespeed====
:Type: Float
:Desc: Controls the mouse speed and push/pull direction for controls. '''''Do not use zero'''''.
:Examples of use:
:* mousespeed -1 Inverts mouse direction.
:* mousespeed 2 Doubles mouse speed in default direction.
:* mousespeed -0.5 Inverts mouse direction and halves the speed.
:* mousespeed 10 Multiplies the mouse speed tenfold in default direction. Useful for smaller levers that require too much mouse movement to activate the lever.

====notches====
:Type: Decimal List
:Desc: Specifies the positions of the notches for this control. Notches are discrete positions within the movement of the control where the lever can be stopped. If a lever does not have notches, it can be positioned at any location. There are two common uses for notches. Firstly, they can be used to define a control which has a number of discrete positions which mean specific things (e.g. a brake valve). Secondly, they are used to define pre-set discrete values that a control can provide (e.g. a throttle lever). A typical US diesel 8 notch throttle would have something like "notches 0.0,0.125,0.25,0.375,0.5,0.625,0.75,0.875,1.0", specifying nine positions (for 'off' and notches 1 thru 8).

====notchheight====
:Type: Integer List
:Desc: Specifies the importance of the notches for this control. This affects how the graphical overlay draws each notch. This is useful for a combined brake and throttle controller, or any other control where you want to mark a specific position relative to the others. This should have the same number of values as the 'notches' list.
:Three styles are available:
:* '1' configures this bar to be a standard length and width bar.
:* '2' configures this bar to be shorter in length, and is often used for intermediate positions.
:* '3' configures this bar to be standard length, but thicker in width. This is often used for marking a specific position.

'''A kind ''lever'' type will not function unless notch heights are specified.'''

====onlight====
:Type: String
:Desc: Specify the name of a ''light'' kind mesh which is enabled when this switch/lever is in the ''on'' position, and disabled when it is in the ''off'' position. The mesh name must be in the mesh-table. See the example below.

====radius====
:Type: Decimal
:Desc: Specifies the distance for the 2D notch overlay.

====tooltip-mesh====
:Type: String
:Desc: Specifies the name of a mesh-table entry for a mesh to show when the control is moused over. The mesh will be faded in/out over a short period.

====tooltip-text====
:Type: String
:Desc: OBSOLETE: DO NOT USE. This text will be used in the tooltip that appears when the mouse cursor hovers over a cab control.

====tooltip-token====
:Type: String
:Desc: The name of a string table entry. The contents of the named string table entry will be displayed as a tooltip that appears when the mouse cursor hovers over a cab control. If a token is used then it must appear as a tag in the [[%22String-table%22 container]].

====value====
:Type: Decimal
:Desc: Specifies the initial value for this control. For a lever or other input device, this will specify the initial position of the control before the user moves it.

=Cab Interior Mesh-Table Example=
The following is an example of a mesh-table which implements a number of cab controls

mesh-table
{
default
{
mesh "interior.im"
auto-create 1
}

wheelslip_light
{
kind "light"
mesh "wheelslip_light.im"
auto-create 0
}

bptrainbrakepipe_needle2
{
kind "digital-dial-prs"
mesh "brakeneedle.im"
att "a.brakepipe2"
limits 0,55
font "arial"
fontsize 0.007
fontcolor 80,240,120
auto-create 1
}

speedo_needle2
{
kind "digital-dial-spd"
mesh "brakeneedle.im"
att "a.digispeedo"
limits 0,55
font "arial"
fontsize 0.01
fontcolor 0,0,0
auto-create 1
}

throttle_lever
{
kind "lever"
mesh "throttle.im"
att "a.throttle"
limits 0,8
angles 0,1.69
notches 0,0.125,0.25,0.375,0.5,0.625,0.75,0.875,1
notchheight 1,2,2,2,2,2,2,2,1
radius 0.35
mousespeed -1
auto-create 1
}

dynamicbrake_lever
{
kind "lever"
mesh "dynamic_handle.im"
att "a.dynamic"
limits 0,2
angles 0,-1.69
notches 0,1
notchheight 0.1,1
mousespeed -1
radius 0.35
auto-create 1
}

trainbrakelap_lever
{
kind "lever"
auto-create 1
mesh "trainbrake_handle.im"
att "a.trainbrake_handle"
limits 0,4
angles 0,-2
notches 0,0.25,0.5,0.75,1
notchheight 2,2,2,2,2
mousespeed 1
}

independantbrake_lever
{
kind "lever"
mesh "indy_handle.im"
att "a.ind"
limits 0,32
angles 0.94,0
notches 0,0.5,1
notchheight 1,1,1
radius 0.35
mousespeed 1
auto-create 1
}

flow_needle
{
kind "needle"
mesh "flowneedle.im"
att "a.bpflow"
limits 0,1050
auto-create 1
}

bplocomain_needle
{
kind "needle"
mesh "brakeneedlered.im"
att "a.mainres"
limits 0,1240
auto-create 1
}

bploco_equaliser
{
kind "needle"
mesh "brakeneedle.im"
att "a.eqres"
limits 0,1240
auto-create 1
}

bptrainbrakecylinder_needle
{
kind "needle"
mesh "brakeneedlered.im"
att "a.brakecyl"
limits -50,1390
auto-create 1
}

bptrainbrakepipe_needle
{
kind "needle"
mesh "brakeneedle.im"
att "a.brakepipe"
limits 0,1240
auto-create 1
}

speedo_needle
{
kind "needle"
mesh "speedo_pointer.im"
att "a.speedo"
limits 0,43
auto-create 1
}

ampmeter_needle
{
kind "needle"
mesh "needleamps.im"
att "a.ampmeter"
limits 0,1700
angles 0,3.02058
auto-create 1
}

reverser_lever
{
kind "lever"
mesh "reverser_handle.im"
att "a.throttle01"
limits 0,2
angles -0.55,0.55
notches 0,0.5,1
notchheight 1,1,1
mousespeed -1
auto-create 1
}

light_switch
{
kind "lever"
att "a.hdlt"
mesh "hdltswtch.im"
limits 0,1
angles 0,2
notches 0,1
notchheight 0.1,0.1
mousespeed -1
auto-create 1
}

horn
{
kind "pulllever"
mesh "horn.im"
att "a.horn"
auto-create 1
angles 0,-0.55
limits 0,1
mousespeed -1
radius -0.02
notches 0,1
notchheight 0,0
}

pantograph_lever
{
kind "lever"
mesh "pantograph_lever.im"
att "a.pantograph_lever"
limits 0,3
angles 1.4,0
notches 0,0.5,0.75,1.0
notchheight 0,0,1,1
mousespeed -1
onlight "line_power"
}

line_power
{
kind "light"
mesh "line_power.im"
att "a.line_power"
}
}

[[Category:Config Container|M]]

"mesh-table" container (interior version)

2020-06-16T23:34:15Z

Gdennish: /* mousespeed */

The "mesh-table" container is a top-level [[config.txt file]] entry used by various [[Content_Configuration#Content_Types|Content Types]]. Refer to the [["mesh-table" Container]] documentation for the standard tags - this document only describes the extensions available within the mesh table when it is used in a [[KIND_Interior|cab interior]] asset.

Most of the entries in a mesh-table for an interior will be cab controls. A cab control has a single value associated with it, which could be an input (e.g. a lever position) or an output (a dial or gauge position).

=Standard Mesh Names=

There are a number of standard mesh names that the trainz default cab script uses for it's controls. For a Diesel or Electric cab (either unscripted, or scripted and inheriting from the DefaultLocomotiveCabin class), the following are the default mesh names:

'''Needles:'''
* speedo_needle -- speedometer
* speedo_needle2 -- speedometer
* bplocomain_needle -- loco main reservoir pressure gauge
* bptrainbrakecylinder_needle -- locomotive brake cylinder pressure gauge
* bptrainbrakecylinder_needle2 -- locomotive brake cylinder pressure gauge
* no3pipe_needle -- brake pressure gauge (currently loco brake cylinder -- but maybe intended for something else?)
* bptrainbrakecylinder2_needle -- brake pressure gauge (source unknown)
* bptrainbrakepipe_needle -- train brake pipe pressure gauge
* bptrainbrakepipe_needle2 -- train brake pipe pressure gauge
* bploco_equaliser -- brake equaliser pressure gauge
* flow_needle -- brake flow rate gauge
* ampmeter_needle -- traction ammeter gauge
* ampmeter2_needle -- traction ammeter gauge

'''Levers:'''

* throttle_lever -- throttle lever control
* reverser_lever -- reverser lever control
* trainbrake_lever -- self-lapping train brake control
* trainbrakelap_lever -- non self-lapping train brake control
* independantbrake_lever -- locomotive independent brake control. Note the typo in the control name.
* dynamicbrake_lever -- dynamic brake control
* wheelslip_light -- wheelslip indicator
* horn -- horn control
* light_switch -- light control
* pantograph_lever -- pantograph control
* throttle_brake_lever -- combined throttle/self-lapping brake lever
* bell -- bell control
For a Steam cab (either unscripted, or scripted and inheriting from the DefaultSteamCabin class), these default mesh names are available:

'''Needles:'''

* speedo_needle -- speedometer
* bplocomain_needle -- loco main reservoir pressure gauge
* bptrainbrakecylinder_needle -- locomotive brake cylinder pressure gauge
* no3pipe_needle -- brake pressure gauge (currently loco brake cylinder -- but maybe intended for something else?)
* bptrainbrakecylinder2_needle -- brake pressure gauge (source unknown)
* bptrainbrakepipe_needle -- train brake pipe pressure gauge
* bploco_equaliser -- brake equaliser pressure gauge
* flow_needle -- brake flow rate gauge
* boiler_needle -- boiler pressure
* boiler_needle1 -- boiler pressure
* steam_chest_needle -- steam chest pressure

'''Levers:'''

* trainbrake_lever -- self-lapping train brake control
* trainbrakelap_lever -- non self-lapping train brake control
* independantbrake_lever -- locomotive independent brake control. Note the typo in the control name.
* horn -- horn control
* light_switch -- light control
* waterglass_left -- boiler water level
* waterglass_right -- boiler water level
* firebox -- the interior of the firebox (to show fire temperature) Only works pre-TANE.
* regulator -- regulator (throttle) control
* reverser -- cutoff (reverser) control
* water_injector_0 -- primary water injector control
* water_injector_1 -- secondary water injector control
* blower -- steam blower control
* fire_plates -- the firebox door
* sanding_lever -- locomotive sander control
* blowdown_lever -- blowdown control (releases water out of the boiler)
* bell -- bell control
* left_window -- Left window control
* right_window -- Right window control
* left_sliding_window-- Left sliding window control
* right_sliding_window-- Right sliding window control
* seat0 -- Seat control
* seat1 -- Seat control
* whistle_lever -- Whistle lever control. (Doesn't seem to actually control the horn, so the whistle lever should actually be called "horn" to function properly."

=Supported Tags=
Each mesh subcontainer supports the following tags. Each tag is shown here with its default value. Standard tags inherited from the normal mesh table are omitted for brevity.

tooltip-text ""
tooltip-token ""
tooltip-mesh ""
limits 0,1
angles 0,0
kind ""
collision-parent ""
mousemode ""
mousespeed 1
notches
invert 0
notchheight
onlight ""
value 0.0
font "swiss"
fontsize 12
fontcolor 1.0,1.0,1.0
fade-time 0.5

====angles====
:Type: Decimal Pair
:Desc: Specifies the minimum and maximum extents of movement for a control or needle. For control types that rotate, these values are in radians[[http://en.wikipedia.org/wiki/Radian]]. In the case of a speedometer, this would define the amount of angular movement of the needle - a speedometer running from horizontal left to horizontal right may use -1.57 to 1.57, for example. If the cab control needs to move the other way, put the higher number first.

====collision-parent====
:Type: String
:Desc: A mesh of kind collision-proxy must specify a collision-parent - the mesh it is a collision proxy for. This is the name of another control in the mesh-table.

====fade-time====
:Type: Float
:Desc: The time, in seconds, for a "light" control to fully switch on or off. Default is 0.5 seconds.

====font====
:Type: String
:Desc: Font name to use for the readout of a digital control.
:Options are:
:* ''swiss'' (Default option. Renders with arial in PC builds.)
:* ''times_new_roman''
:* ''verdana''
:* ''century_gothic''
:* ''cordia''
:* ''courier''
:* ''helvetica''
:* ''arial''
:* ''comic_sans''
:* ''sans_serif''
:* ''impact''
:* ''console''
:* ''tohoma'' (renders using the ''Tahoma'' font on PC builds.)
:* ''garamond''
:These roughly correspond with Windows font names. Beware - not all fonts are available on all platforms, and where a font is not available, a different font may be substituted.

====fontcolor====
:Type: Decimal Triplet
:Desc: RGB font color for the readout of a digital control. Colors are specified within the range 0.0 to 1.0, with 0.0 being black and 1.0 being full intensity. Default is 1.0,1.0,1.0 - white.

====fontsize====
:Type: Decimal
:Desc: Font size for the readout of a digital control. Default is 12.

====invert====
:Type: Boolean
:Desc: Invert mouse movement for this control. If the control moves the wrong way compared to the mouse, change this setting.

====kind====
:Type: Selection
:Desc: The type of control this mesh table element represents.
:Options are:
:* ''animated-lever''
:Operates like a standard lever, only uses a named animation instead of the angles tag for movement.
:* ''animated-dial''
:Operates like a standard needle, only uses a named animation to represent the gauge readout instead of the angles tag.
:* ''collision-proxy''
:This element type defines a volume within the cab where the mouse pointer will be considered to be over the cab control. Generally used in conjunction with an animated-lever. Name of the animated lever is defined in the tag ''collision-parent''.
:* ''digital-dial-spd''
:Digital readout for a speedometer, and using speed units.
:* ''digital-dial-prs''
:Digital readout for a pressure gauge, using pressure units.
:* ''firebox''
:The animated firebox in a steam locomotive.
:* ''lever''
:A standard lever, often used for throttle and brake controls. Requires the user to click hold and move the mouse to move the lever between it's notches. This control will stay at any notch position when let go.
:* ''light''
:A light glow / overlay - this mesh is hidden when the light is off and shown when the light is on.
:* ''needle''
:An analogue gauge needle. Can be used to implement many different types of gauges.
:* ''pulllever''
:Like a lever, only sprung to return to it's initial position when the user lets go of the control. Useful for horns.
:* ''pullrope''
:Like a pulllever, only with linear (not rotational) movement.
:* ''switch''
:This control requires only a single click to move between it's two endpoints. It is better suited than a lever to small switches and buttons.
:* ''button''
:Similar to switch but requires the mouse be held down to keep the control active. I.e., press and hold the mouse button to push the control down, release the mouse and the control will return to the off position.

====limits====
:Type: Decimal Pair
:Desc: Specifies the minimum and maximum values for a cab control or needle at it's two endpoints of movement. In the case of a speedometer, this would be the range of speeds it can display - 0m/s to 50m/s, for example.

====mousemode====
:Type: String
:Desc: If set to "exact", will require the mouse to be positioned over the geometry of the control precisely to activate it. Otherwise a bounding volume is used. This is useful for large controls which would otherwise block access to smaller controls.

====mousespeed====
:Type: Float
:Desc: Controls the mouse speed and push/pull direction for controls. '''''Do not use zero'''''.
:Examples of use:
:* mousespeed -1 Inverts mouse direction.
:* mousespeed 2 Doubles mouse speed in default direction.
:* mousespeed -0.5 Inverts mouse direction and halves the speed.
:* mousespeed 10 Multiplies the mouse speed tenfold in default direction. Useful for smaller levers that require too much mouse movement to activate the lever.

====notches====
:Type: Decimal List
:Desc: Specifies the positions of the notches for this control. Notches are discrete positions within the movement of the control where the lever can be stopped. If a lever does not have notches, it can be positioned at any location. There are two common uses for notches. Firstly, they can be used to define a control which has a number of discrete positions which mean specific things (e.g. a brake valve). Secondly, they are used to define pre-set discrete values that a control can provide (e.g. a throttle lever). A typical US diesel 8 notch throttle would have something like "notches 0.0,0.125,0.25,0.375,0.5,0.625,0.75,0.875,1.0", specifying nine positions (for 'off' and notches 1 thru 8).

====notchheight====
:Type: Integer List
:Desc: Specifies the importance of the notches for this control. This affects how the graphical overlay draws each notch. This is useful for a combined brake and throttle controller, or any other control where you want to mark a specific position relative to the others. This should have the same number of values as the 'notches' list.
:Three styles are available:
:* '1' configures this bar to be a standard length and width bar.
:* '2' configures this bar to be shorter in length, and is often used for intermediate positions.
:* '3' configures this bar to be standard length, but thicker in width. This is often used for marking a specific position.

====onlight====
:Type: String
:Desc: Specify the name of a ''light'' kind mesh which is enabled when this switch/lever is in the ''on'' position, and disabled when it is in the ''off'' position. The mesh name must be in the mesh-table. See the example below.

====radius====
:Type: Decimal
:Desc: Specifies the distance for the 2D notch overlay.

====tooltip-mesh====
:Type: String
:Desc: Specifies the name of a mesh-table entry for a mesh to show when the control is moused over. The mesh will be faded in/out over a short period.

====tooltip-text====
:Type: String
:Desc: OBSOLETE: DO NOT USE. This text will be used in the tooltip that appears when the mouse cursor hovers over a cab control.

====tooltip-token====
:Type: String
:Desc: The name of a string table entry. The contents of the named string table entry will be displayed as a tooltip that appears when the mouse cursor hovers over a cab control. If a token is used then it must appear as a tag in the [[%22String-table%22 container]].

====value====
:Type: Decimal
:Desc: Specifies the initial value for this control. For a lever or other input device, this will specify the initial position of the control before the user moves it.

=Cab Interior Mesh-Table Example=
The following is an example of a mesh-table which implements a number of cab controls

mesh-table
{
default
{
mesh "interior.im"
auto-create 1
}

wheelslip_light
{
kind "light"
mesh "wheelslip_light.im"
auto-create 0
}

bptrainbrakepipe_needle2
{
kind "digital-dial-prs"
mesh "brakeneedle.im"
att "a.brakepipe2"
limits 0,55
font "arial"
fontsize 0.007
fontcolor 80,240,120
auto-create 1
}

speedo_needle2
{
kind "digital-dial-spd"
mesh "brakeneedle.im"
att "a.digispeedo"
limits 0,55
font "arial"
fontsize 0.01
fontcolor 0,0,0
auto-create 1
}

throttle_lever
{
kind "lever"
mesh "throttle.im"
att "a.throttle"
limits 0,8
angles 0,1.69
notches 0,0.125,0.25,0.375,0.5,0.625,0.75,0.875,1
notchheight 1,2,2,2,2,2,2,2,1
radius 0.35
mousespeed -1
auto-create 1
}

dynamicbrake_lever
{
kind "lever"
mesh "dynamic_handle.im"
att "a.dynamic"
limits 0,2
angles 0,-1.69
notches 0,1
notchheight 0.1,1
mousespeed -1
radius 0.35
auto-create 1
}

trainbrakelap_lever
{
kind "lever"
auto-create 1
mesh "trainbrake_handle.im"
att "a.trainbrake_handle"
limits 0,4
angles 0,-2
notches 0,0.25,0.5,0.75,1
notchheight 2,2,2,2,2
mousespeed 1
}

independantbrake_lever
{
kind "lever"
mesh "indy_handle.im"
att "a.ind"
limits 0,32
angles 0.94,0
notches 0,0.5,1
notchheight 1,1,1
radius 0.35
mousespeed 1
auto-create 1
}

flow_needle
{
kind "needle"
mesh "flowneedle.im"
att "a.bpflow"
limits 0,1050
auto-create 1
}

bplocomain_needle
{
kind "needle"
mesh "brakeneedlered.im"
att "a.mainres"
limits 0,1240
auto-create 1
}

bploco_equaliser
{
kind "needle"
mesh "brakeneedle.im"
att "a.eqres"
limits 0,1240
auto-create 1
}

bptrainbrakecylinder_needle
{
kind "needle"
mesh "brakeneedlered.im"
att "a.brakecyl"
limits -50,1390
auto-create 1
}

bptrainbrakepipe_needle
{
kind "needle"
mesh "brakeneedle.im"
att "a.brakepipe"
limits 0,1240
auto-create 1
}

speedo_needle
{
kind "needle"
mesh "speedo_pointer.im"
att "a.speedo"
limits 0,43
auto-create 1
}

ampmeter_needle
{
kind "needle"
mesh "needleamps.im"
att "a.ampmeter"
limits 0,1700
angles 0,3.02058
auto-create 1
}

reverser_lever
{
kind "lever"
mesh "reverser_handle.im"
att "a.throttle01"
limits 0,2
angles -0.55,0.55
notches 0,0.5,1
notchheight 1,1,1
mousespeed -1
auto-create 1
}

light_switch
{
kind "lever"
att "a.hdlt"
mesh "hdltswtch.im"
limits 0,1
angles 0,2
notches 0,1
notchheight 0.1,0.1
mousespeed -1
auto-create 1
}

horn
{
kind "pulllever"
mesh "horn.im"
att "a.horn"
auto-create 1
angles 0,-0.55
limits 0,1
mousespeed -1
radius -0.02
notches 0,1
notchheight 0,0
}

pantograph_lever
{
kind "lever"
mesh "pantograph_lever.im"
att "a.pantograph_lever"
limits 0,3
angles 1.4,0
notches 0,0.5,0.75,1.0
notchheight 0,0,1,1
mousespeed -1
onlight "line_power"
}

line_power
{
kind "light"
mesh "line_power.im"
att "a.line_power"
}
}

[[Category:Config Container|M]]

KIND Interior

2020-06-16T20:35:24Z

Gdennish: Added a event tag chart for cabin.txt

[[KIND Interior]] provides the basis for a building or vehicle interior, with or without control levers and dials.

This asset type inherits all mesh display characteristics, and adds interior-specific functionality such as control levers. Please read [[HowTo/Build a cab interior]] for a step-by-step guide to creating an Interior asset.

==KIND Hierarchy==
===Parent Classes===
* [[KIND Mesh]]
===Child Classes===
* ''none.''

==Supported Tags==
Each interior asset supports the following tags. Each tag is shown here with its default value.

kind "interior"
[[%22cameralist%22_Container|cameralist]]
{
camera0 0,0,0,0,0
}
[[%22soundscript%22_Container|soundscript]]
{
}
cameradefault 0
cabin-visible-from-outside 0
outside-visible-from-cabin 0
controlset ""
enable-shadows-in-cab 1
[[%22mesh-table%22_container_(interior_version)|mesh-table]]
{
}

====cameralist====
:Type: [[%22cameralist%22_Container|CameraList Container]]
:Desc: Lists the different camera view positions and orientations this interior has.
====soundscript====
:Type: [[%22soundscript%22_Container|SoundScript Container]]
:Desc: Details sounds that a cab interior can produce. Sounds may be triggered by the asset script, or by object animations.
====cameradefault====
:Type: Integer
:Desc: Defines which of the cameras in 'cameralist' is the default camera (the one selected when the user first goes into cab view mode). e.g. "cameradefault 3" will make "camera3" the default camera view.
====cabin-visible-from-outside====
:Type: Boolean
:Desc: If true, makes the cab mesh visible from the outside view.
This is intended for objects with simple but obviously visible cab controls that are not enclosed - e.g. the controls to operate a transfer table. It would be far too much of a performance impact to use this on locomotive models, as locomotive cabs are very performance intensive.
====outside-visible-from-cabin====
:Type: Boolean
:Desc: If true, makes the loco body mesh visible while in the cab interior view.
This is intended to be used with an interior where the cab controls that are not in an enclosed space - e.g. a transfer table.
While using this on a traincar is not considered problematic from a performance perspective, please note this will require a very carefully designed cab and loco asset - both the inside of the loco mesh and the cab interior will be visible at the same time, and unless done very carefully, this is likely to cause graphical problems with overlapping polygons and unexpectedly visible or opaque surfaces.
====controlset====
:Type: [[KUID]]
:Desc: Specifies a [[KIND_Controlset|controlset]] asset used to send script messages to this interiors custom script. Optional.

====enable-shadows-in-cab====
:Type: Boolean
:Desc: If true (1), makes the cab interior receive shadows. Note that this will cast a shadow of the interior onto the environment when viewed from the interior camera. It's therefore preferable that the interior mesh preserves the basic shape of the vehicle if you wish to apply this setting.

====interior-controls-type====
:Type: Text String
:Desc: Specifies the type of the control. Types are
:* none (non-powered car)
:* hostler (driveable B unit or cab car)
:* full (loco)
:Compulsory from 3.8.

====mesh-table====
:Type: [[%22mesh-table%22_container_(interior_version)|MeshTable Container (Interior version)]]
:Desc: All the meshes for the cab interior (the shell itself, along with all the controls and gauges) are listed here. A mesh table for an interior has a number of additional options that a normal mesh table does not.

==Example Config.txt==
Sample [[config.txt file]] for a interior asset, with the Standard Tags excluded for brevity:

kind "interior"

cameralist
{
camera0 -1.236,0.173,0.392,0.511,-0.155
camera1 -1.278,-0.176,0.392,0.511,-0.155
camera2 -1.247,0.344,0.52,6.708,-0.403
camera3 -0.113,0.965,0.52,6.312,-0.377
camera4 1.35,0.15,0.52,5.71,-0.265
camera5 1.374,0.208,0.205,6.048,-0.06
camera6 -0.754,0.926,1.011,6.636,-0.516
camera7 -1.293,0.449,0.459,6.757,-0.342
}
cameradefault 0

mesh-table
{
default
{
mesh "c_interior.im"
auto-create 1
}

wheelslip_light
{
kind "light"
mesh "wheelslip_light.im"
auto-create 0
}

bptrainbrakepipe_needle2
{
kind "digital-dial-prs"
mesh "brakeneedle.im"
att "a.brakepipe2"
limits 0,55
font "arial"
fontsize 0.007
fontcolor 80,240,120
auto-create 1
}

speedo_needle2
{
kind "digital-dial-spd"
mesh "brakeneedle.im"
att "a.digispeedo"
limits 0,55
font "arial"
fontsize 0.01
fontcolor 0,0,0
auto-create 1
}

throttle_lever
{
kind "lever"
mesh "throttle.im"
att "a.throttle"
limits 0,8
angles 0,1.69
notches 0,0.125,0.25,0.375,0.5,0.625,0.75,0.875,1
notchheight 1,2,2,2,2,2,2,2,1
radius 0.35
mousespeed -1
auto-create 1
}

dynamicbrake_lever
{
kind "lever"
mesh "dynamic_handle.im"
att "a.dynamic"
limits 0,2
angles 0,-1.69
notches 0,1
notchheight 0.1,1
mousespeed -1
radius 0.35
auto-create 1
}

trainbrakelap_lever
{
kind "lever"
auto-create 1
mesh "trainbrake_handle.im"
att "a.trainbrake_handle"
limits 0,4
angles 0,-2
notches 0,0.25,0.5,0.75,1
notchheight 2,2,2,2,2
mousespeed 1
}

independantbrake_lever
{
kind "lever"
mesh "indy_handle.im"
att "a.ind"
limits 0,32
angles 0.94,0
notches 0,0.5,1
notchheight 1,1,1
radius 0.35
mousespeed 1
auto-create 1
}

flow_needle
{
kind "needle"
mesh "flowneedle.im"
att "a.bpflow"
limits 0,1050
auto-create 1
}

bplocomain_needle
{
kind "needle"
mesh "brakeneedlered.im"
att "a.mainres"
limits 0,1240
auto-create 1
}

bploco_equaliser
{
kind "needle"
mesh "brakeneedle.im"
att "a.eqres"
limits 0,1240
auto-create 1
}

bptrainbrakecylinder_needle
{
kind "needle"
mesh "brakeneedlered.im"
att "a.brakecyl"
limits -50,1390
auto-create 1
}

bptrainbrakepipe_needle
{
kind "needle"
mesh "brakeneedle.im"
att "a.brakepipe"
limits 0,1240
auto-create 1
}

speedo_needle
{
kind "needle"
mesh "speedo_pointer.im"
att "a.speedo"
limits 0,43
auto-create 1
}

ampmeter_needle
{
kind "needle"
mesh "needleamps.im"
att "a.ampmeter"
limits 0,1700
angles 0,3.02058
auto-create 1
}

reverser_lever
{
kind "lever"
mesh "reverser_handle.im"
att "a.throttle01"
limits 0,2
angles -0.55,0.55
notches 0,0.5,1
notchheight 1,1,1
mousespeed -1
auto-create 1
}

right_sliding_window
{
mesh "window1.im"
auto-create 1
att "a.window1"
att-parent "default"
limits 0,1
angles 0,-0.009
notches 0,1
notchheight 1,1
kind "lever"
}

right_sliding_window2
{
mesh "window2.im"
auto-create 1
att "a.window2"
att-parent "default"
limits 0,1
angles 0,0.009
notches 0,1
notchheight 1,1
kind "lever"
mousespeed -1
}

left_sliding_window
{
mesh "window3.im"
auto-create 1
att "a.window3"
att-parent "default"
limits 0,1
angles 0,-0.009
notches 0,1
notchheight 1,1
kind "lever"
mousespeed -1
}

left_sliding_window2
{
mesh "window4.im"
auto-create 1
att "a.window4"
att-parent "default"
limits 0,1
angles 0,0.009
notches 0,1
notchheight 1,1
kind "lever"
mousespeed 1
}

light_switch
{
kind "lever"
att "a.hdlt"
mesh "hdltswtch.im"
limits 0,1
angles 0,2
notches 0,1
notchheight 0.1,0.1
mousespeed -1
auto-create 1
}

horn
{
kind "pulllever"
mesh "horn.im"
att "a.horn"
auto-create 1
angles 0,-0.55
limits 0,1
mousespeed -1
radius -0.02
notches 0,1
notchheight 0,0
}
}

'''Note:''' Mesh table entry speedo_needle is required to update speed information on a RailDriver console.

==Custom Sounds==
===Overview===
It is possible to assign custom sounds to cabin controls without using a custom script. This can be performed via the addition of a 'cabin.txt' configuration file to an interior asset. The cabin.txt and custom sounds files must be placed in the an asset sub-directory named 'sounds'.

===Cabin.txt File Format===
The cabin.txt file lists 1 sound even per row, with each sound event defined by three space separated values. Empty rows are permitted and will be safely ignored. Each sound event requires the following three values:

====Target====
The name of the mesh-table entry for the mesh of the cabin control.
====Event====
The name of a cabin control event which will trigger the sound. The full list of supported events is as follows: 
'''mouseenter''' :- Triggered when the players mouse hovers over the control 
'''mouseleave''' :- Triggered when the players mouse was over the control but no longer is 
'''mousedown''' :- Triggered when the player presses a mouse button while over the control 
'''beginselect''' :- Triggered when the player actives a control, i.e. selects it 
'''mouseup''' :- Triggered when the player releases a mouse button while over the control 
'''endselect''' :- Triggered when the player deselects a control 
'''change-notch''' :- Triggered on notched controls only, whenever the player moves the control one notch 
'''lever-low''' :- Triggered on lever type controls, when the lever is moved to the lowest position 
'''lever-high''' :- Triggered on lever type controls, when the lever is moved to the highest position 
'''looping''' :- Triggered when a control is moved to notch 1, this sound will play in a loop until the control is changed. A typical use for this would be a fire sound while the firedoor of a steam train is open. 

====Tips====
Some lever types will only create a sound based on the correct event type. Below is a chart to describe which events will work with the correct lever type. It is a work in-progress and is not fully complete:

{| class="wikitable"
|+Event tag chart
|-
|Lever Type
|Event tag
|Notes
|-
|animated-lever
|change-notch , beginselect, lever-high, lever-low
|Change-notch and beginselect are good choices for animated levers.
|-
|lever
|change-notch , beginselect, lever-high, lever-low
|Change-notch and beginselect are good choices for levers.
|-
|pulllever
|change-notch , lever-high, lever-low
|change-notch will only create a sound for each notch in a pulllever, which is typically the starting and ending position.
|-
|pullrope
|change-notch , lever-high, lever-low
|change-notch will only create a sound for each notch in a pullrope, which is typically the starting and ending position.
|-
|switch
|beginselect
|switch seems to only react to beginselect.
|-
|button
|unknown
|unknown
|}

====Sound File====
The file-name of the sound to play (relative to the 'sound' sub-directory)

Below is an example of a cabin.txt file which will assign custom sounds to the reverser and windows of the example config.txt file above.

reverser_lever lever-low reverser_notch.wav
reverser_lever lever-high reverser_throw.wav

right_sliding_window change-notch window_open.wav
right_sliding_window2 change-notch window_open.wav
left_sliding_window change-notch window_open.wav
left_sliding_window2 change-notch window_open.wav
handbrake_wheel looping handbrakemove.wav //
cool_switch beginselect click.wav // Note this is a kind "switch"

==Material/Textures==
For best visual results you should make sure there isn't anything below the gray color (R:100, G:100, B:100) in the red channel of the parameters texture (see TRS19 material - [[m.pbrmetal]] - for more information on the parameters texture).
You can have higher (whiter values) but RGB:100 is probably the minimum you'll want to go with to make things clear in-cabs.

[[file:in-cab_rgb100.jpg|1275px]]

==Downloads==
''Attach sample files here?''

==Categories==
[[Category:Asset KIND|I]]

HowTo/Build a cab interior

2020-06-10T20:57:31Z

Gdennish: /* Artwork considerations */

Trainz uses an [[KIND_Interior|interior]] object to represent a locomotive cab, or view from another vehicle, e.g. a passenger coach, brake van or caboose. Interiors can also be attached to some non-train assets. For this howto, I am going to assume that we are creating a traincar interior, and focus primarily on a cab interior for a diesel or electric locomotive.

=Basic structure=

The basic structure of a cab is quite similar to a number of different assets. You will have a main mesh with a number of attached sub-meshes, which are arranged using a [[%22mesh-table%22_container_(interior_version)|mesh-table]].

The main cab mesh typically consists of the interior walls, roof and floor of the cab, the control desk or stand, all furniture or other static objects visible inside the cab, and also all parts of the locomotive exterior that are visible from inside the cab - e.g. the top of any projecting nose below the cab windows. Remember to consider the sightlines out of rear windows too for visible bodywork panels - the user can move around the cab and rotate the camera to any angle. Users are not restricted to looking forward out of the front windows only.

=Artwork considerations=

There are some differences in style between the construction of an interior object and a typical trainz object.

Except in very specific circumstances, there will not be more than one interior object in existence at any time, and that interior is always viewed from very close range - the user is inside it. Because of this, interiors are typically modelled with a high polygon count and with high resolution textures, to give an impressive visual feel. LOD is not used, as the user never gets far enough away from the interior for LOD techniques to have worthwhile benefit. However, LOD techniques may be ideal in a case of a passenger wagon with high polygon chair models.

Trainz lights interior objects differently to map objects like buildings and other scenery - the main illumination is ambient, not directional. (A steam loco does have a directional light coming from the firebox, but a diesel or electric cab typically has no directional light inside, and relies entirely on ambient illumination).

With ambient illumination, effects such as normal and specular mapping do not have much (if any) effect. Because of this, more effort needs to be put into the diffuse texture for a cab interior than would normally be applied to Trainz objects. Drawing or baking shadows and other effects into the diffuse textures is required to produce a nice looking cab interior.

An example cab would be the [[File:PB_interior.rar]]

=A basic config file=

The minimal required config for an interior to show in-game is:

kind interior
kuid <kuid2:YOUR:KUID:HERE>
trainz-build 2.9
username "Your interior name here"
category-class ZI

mesh-table
{
default
{
mesh "your_interior_mesh_name.im"
auto-create 1
}
}

Note: There are also other base tags that should be added that are common to all asset types - e.g. the download station will require a valid thumbnails container before the asset can be uploaded. See the documentation for [[KIND TrainzBaseSpec]] for details of tags which apply to all trainz assets. Depending on which Trainz version you have and which trainz-build number you have specified, some of these may be required - content manager will tell you what is required, listing missing tags as errors.

==camera positions==

If we load a cab up with that config file, we will note that the view is not particularly appealing. Chances are we're right down near the floor. To fix this, we need to define some default positions for camera views. This is done with the [[%22cameralist%22_Container|cameralist container]] and the [[KIND_Interior#cameradefault|cameradefault]] tag.
Add the following to your config.txt file:

cameralist
{
camera0 0,0,2,0,0
}

cameradefault 0

The cameralist container can contain any number of cameras, but they must be numbered sequentially and start at zero.

The five numbers are the X, Y and Z coordinates of the camera in metres relative to the 0,0,0 point of the interior mesh, and the Yaw and Pitch in radians. Luckily you don't have to work these values out from scratch - add the line "-freeintcam" to your trainzoptions.txt file, and you can move the camera about in the cab with the mouse and keyboard, and the precise position will be displayed in the bottom right corner.

When you have found a position you like, write the numbers down. When you've got a good selection of positions recorded, add them to the cameralist container.

You may wish to return to this and tweak the values later once all the controls are in place - but it's handy to have a good starting position for the camera while testing.

=Cab controls=

A locomotive cab interior needs working cab controls. What fun would sitting in the drivers seat be without being able to pull on the levers, change the switches, and watch the gauges and dials move?

The moving part of each lever, switch, gauge or dial is created as a separate mesh, which is then attached to the cab with an attachment point. (The static part, e.g. guide rails for levers, should be part of the cab mesh itself).

==Lever==

The lever is the basic input device in a cab. It is based on rotational movement, and any object that requires rotational movement (e.g. a wheel or ring) can be implemented as a lever.

If you actually want linear movement, you can still use a lever - just move the attachment point a long way away - e.g. 10 or 20 metres away from the control. The resulting small arc will not be noticable over the length of movement. As an example, sliding windows in Trainz cabs have been implemented as levers "attached" something like 10 or 20 metres out to the side of the vehicle for a long time. (The exception to this is a horn pull rope - trainz provides a control specifically for this purpose).

You will need to create the lever in your modelling program aligned correctly - the rotation needs to be around the Z axis, and main part of the object will point along the Y axis.

When adding the attachment point to the main mesh, align it so the Z axis is the axis of rotation. It is common to point the Y axis at the default position - e.g. levers in the 'off' or 'neutral' position, and needles pointing to zero. This is not strictly required, as the range of movement can be adjusted at both ends, but it provides a handy reference when creating the config file.

[[File:BasicLeverSetup.png|350px|thumb|An example of a lever being used as a signboard cover.]]

It is worth noting that you can reuse a mesh for multiple attachments. This is particularly useful for switches, as identical appearance switches are often used repeatedly in a cab for different purposes.

===Throttle Lever===

A good example of a standard lever in use is a locomotive throttle control. A typical US diesel throttle has 9 notched positions (from 0 to 8 inclusive).

As noted above, the lever is created in the modelling package so it points along the Y axis and the axis of rotation is along the Z axis. The attachment point is added to the cab interior mesh at the correct position, and rotated so the Z axis is aligned with the axis of rotation, and the Y axis points to the default position.

Now we need to add an entry to the config file to add our throttle lever.

Into the mesh table, add an entry like this:

throttle_lever
{
kind "lever"
mesh "throttle_lever.im"
att "a.throttle_lever"
limits 0,8
angles 0,1.57
notches 0,0.125,0.25,0.375,0.5,0.625,0.75,0.875,1
notchheight 1,2,2,2,2,2,2,2,1
radius 0.35
auto-create 1
att-parent "default"
}

... remember to set your attachment point and mesh name correctly.

The 'angles' line defines how far the control rotates. It is in radians - there are 2 x Pi (6.28) radians in a complete circle. My default of 1.57 will give you about 90 degrees of rotation, in the positive direction. Adjust this number to get the control to rotate the correct amount. You should be able to work out the number you need in your modelling program by using the rotate tool on the attachment point, and recording the amount of rotation required to move to the intended maximum location. It should not require significant trial and error.

The 'radius' line defines the position of the notch position overlay and the text label. It is in metres. If the overlay is too close in, increase this number. If it is too far out, decrease it.

If the lever is the wrong way round (notch 8 is at the wrong end), swap the numbers in the 'angles' tag over, so the higher one is first.

If the lever moves the wrong way when you drag it with the mouse (i.e. it goes left in response to a right drag), add the line:
mousespeed -1
This will invert the mouse movement.

The fact we called this lever "throttle_lever" means it will be used to control the throttle by the default cab script.

So what happens if we wanted a different number of notches? Below is an example of a throttle which has 22 notches. The second value in the 'limits' tag has been edited to return up to notch 22, and more entries have been added to the 'notches' and 'notchheight' tags:

throttle_lever
{
kind "lever"
mesh "throttle_lever.im"
att "a.throttle_lever"
limits 0,22
angles 0,0.94
notches 0,0.045,0.091,0.136,0.182,0.227,0.273,0.318,0.364,0.409,0.455,0.5,0.545,0.591,0.636,0.682,0.727,0.773,0.818,0.864,0.909,0.955,1
notchheight 1,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,1
radius 0.35
auto-create 1
att-parent "default"
}

===Reverser Lever===

The reverser lever is created in a similar manner to throttle lever. The mesh table entry for this will look like:

reverser_lever
{
kind "lever"
mesh "reverser_lever.im"
att "a.reverser_lever"
limits 0,2
angles -0.79,0.79
notches 0,0.5,1
notchheight 1,1,1
radius 0.25
auto-create 1
att-parent "default"
}

In this case, because the 'angles' entry has a range both positive and negative, the lever can move in both directions relative to the attachment point. The game will set the default position to neutral (1), so if you've lined up your attachment point at one end, don't worry - you can use angles which range from zero if you need to.

===Train Air Brake Lever===

There are two types of train air brake lever. A given locomotive only has one type - the brakes are either require manual lapping or are self-lapping. Use the appropriate name and configuration for the loco you are modelling.

====Manual Lapped Brakes====

The manual train brake lever has five positions numbered from zero to four, each one representing a different function. Those functions are Release, Lap, Application, Emergency and Handle Off respectively.

A lever for a manual lap train air brake is defined as follows:

trainbrakelap_lever
{
kind "lever"
mesh "train_brake_lap_lever.im"
att "a.train_brake_lap_lever"
limits 0,4
angles 0,0.94
notches 0,0.25,0.5,0.75,1
notchheight 1,1,1,1,1
radius 0.25
att-parent "default"
auto-create 1
}

In this case, the attachment for the lever has been created in the 'release' position. If it had been created in the 'handle off' position, the angle tag would have been more like:

angles -0.94,0

====Self Lapping Brakes====

A self lapping trainbrake lever has a number of primary notches similar to the manual lap train brake lever. However, instead of a 'lap' and 'apply' position, it has a grade of application between the 'initial' and 'full application' positions. An example of a self-lapping brake handle is this one:

trainbrake_lever
{
kind "lever"
mesh "train_brake_lever.im"
att "a.train_brake_lever"
limits 0,4
angles 0,0.94
notches 0,0.25,0.27,0.29,0.31,0.33,0.35,0.37,0.39,0.41,0.43,0.45,0.47,0.49,0.5,0.75,1
notchheight 1,1,2,2,2,2,2,2,2,2,2,2,2,2,1,1,1
radius 0.25
att-parent "default"
auto-create 1
}

In this case, there are 14 possible levels of brake application - initial at 0.25, 12 intermediate levels, and full application at 0.5. There is no restriction on the number of intermediate levels - if you are modelling a prototype brake handle with a specific number, you may create precisely that number of notches and arrange them between 0.25 and 0.5 as required.

===Combined throttle brake lever===

There is also another control option - a combined throttle brake lever. This type of control is often found on multiple unit trains. This control is split into two halves. The first half of the movement is an inverted throttle - i.e. max power at zero, no power at 0.5. The second half is an auto lapped train brake application, with 0.5 as release, and 1.0 as emergency. An example of how to configure a combined throttle and brake lever is below:

throttle_brake_lever
{
kind "lever"
mesh "throttle_brake_handle.im"
auto-create 1
att "a.throttle_brake_handle"
limits 0,16
angles 0.94,-0.94
notches 0,0.0625,0.125,0.1875,0.25,0.3125,0.375,0.4375,0.5,0.5625,0.625,0.6875,0.8125,0.75,0.875,0.9375,1
notchheight 1,2,2,2,2,2,2,2,1,2,2,2,2,2,2,2,1
att-parent "default"
radius 0.12
invert 1
}

Unfortunately, trains that use this type of control generally use blended and/or EP brakes, and this control uses the standard Trainz air brake, which operates in a distinctly different manner, and as a result, can feel very wrong for this control type. (See the section on scripting controls for how a better combined brake and throttle lever may be implemented).

==Pull lever==

This is a sprung lever. You pull on this lever to activate it, and when you let it go, it returns to the original position. This kind of action is commonly associated with a locomotive horn, and this is what I am using as an example:

horn
{
kind "pulllever"
mesh "horn.im"
att "a.horn"
auto-create 1
angles 0,-0.55
limits 0,1
mousespeed -1
radius -0.02
notches 0,1
notchheight 0,0
}

==Switch==

A switch is a lever that does not require the user to 'drag' it with the mouse - it operates on a click only. This is used for smaller controls that are 'on' or 'off', and do not have intermediate positions. Parameters are much like they are for a 'lever', only a switch should only have two notches - on and off.

Unfortunately, some things you'd normally associate with being a 'switch' (e.g. the headlight switch control) require mulitple positions, and will need to remain as a 'lever' in order to allow the player to set the correct position for the control.

An example of a switch would be:

switch1
{
kind "switch"
mesh "switch.im"
att "a.switch1"
limits 0,1
angles 1.4,0
notches 0,1
notchheight 0,0
}

As 'switch' was introduced in TS2009 SP2, interiors that use kind 'switch' controls should be marked trainz-build 3.1 or later in the config.txt.

==button==

A button is a momentary contact press-and-hold button. This is a brand new control added for TS12 patch 2, released end of june 2011. Content using this feature should have trainz-build 3.6 or later in the config.txt.

Finally this brings Trainz the "click to press", "hold to hold pressed", "let go to release" style momentary pushbutton.

button1
{
kind "button"
mesh "switch.im"
att "a.switch1"
limits 0,1
angles 0,0.1
notches 0,1
notchheight 0,0
}

==Pull rope==

This is a linear pull rope control. Unlike the rotating controls discussed previously, this control type moves the mesh linearly along the Z axis of the attachment. It behaves as you would expect from a suspended rope - click and drag to pull, let go to release. It will spring back to it's initial position in the same manner as kind 'pulllever'.

[[File:Pullropetype.png|800px]]]

horn
{
kind "pullrope"
mesh "horn_rope.im"
att "a.horn"
limits 0,1
angles 0.1,0
notches 0,1
notchheight 0,0
mousespeed -1
}

==needle==

A needle is the standard Trainz output device. Like the lever, it is based on rotational movement, and any gauge, dial, or other output device based on rotational movement can be implemented. Any static part of the gauge should be modelled as part of the cab, and only the moving part as part of the needle. Like the lever, the rotation will be around the Z axis of the needle, and it is common practice to point the point of the needle along the Y axis. Cabs often have a number of similar gauges, and re-using the same needle repeatedly in each gauge is a lot easier if this setup is done consistently.

As an example of a needle, here is a basic speedometer:

speedo_needle
{
kind "needle"
auto-create 1
mesh "speedo_needle.im"
att "a.speedo_needle"
limits 0,67.056
angles 0,4.712
}

The default cab script knows to move the "speedo_needle" object as the train speed changes, so simply by naming this control "speedo_needle", it has become a speedometer.

For a speedo, the 'limits' values will be the minimum and maximum reportable speed in m/s.

Creating other rotational gauges is similar - refer to the [[%22mesh-table%22_container_(interior_version)|mesh-table (interior version)]] documentation to see all the different values that Trainz can show by default.

==light==

Another common type of control is a light. This is created simply as a textured plane, which is either hidden or shown to represent light off or light on. It is attached as any other standard mesh attachment would be - there is no rotation to worry about here.

wheelslip_light
{
kind "light"
mesh "wheelslip_light.im"
att "a.wheelslip_light"
}

This light will be used to show wheelslip in a default cab.

==animated-lever==

If you want more complex movement than simple rotation, you have the option of animating the lever and using kind 'animated-lever'. This will use an animation you create in your modelling program to move the control about. An example of this is visible in the MN ACMU cab. (I've reduced the number of notches here for readability - the real one has 32, not 16).

throttle_lever
{
mesh "throttlehandle.im"
anim "throttlehandle.kin"
auto-create 1
att "a.throttlelever"
limits 0,16
notches 0,0.0625,0.125,0.1875,0.25,0.3125,0.375,0.4375,0.5,0.5625,0.625,0.6875,0.8125,0.75,0.875,0.9375,1
notchheight 1,2,2,2,2,2,2,2,1,2,2,2,2,2,2,2,1
att-parent "default"
kind "animated-lever"
test-collisions 0
mousespeed 1
}

Where the standard lever is rotated between it's angles to move from notch to notch, the animated-lever has it's animation played to the corresponding frame.

===collision-proxy===

Animated levers can be hard to grab hold of compared to normal levers. To get around this, an invisible mesh is used to show the game the range of movement the control has, and to allow the user to grab the lever more easily. This example again comes from the MN ACMU cab:

throttle-collision-box
{
mesh "throttlehandleselection.im"
att-parent "throttle_lever"
att "a.selection_box"
auto-create 1
kind "collision-proxy"
opacity 0
collision-parent "throttle_lever"
}

==animated-dial==

If you've been paying attention to levers, needles and animated levers, I think you can guess where we are going with this one. This is an animated needle. Instead of rotating between the angles specified, it plays it's animation to the relevant frame to show the value. Use this when what you want to achieve can't be done with simple rotational movement.

(Example usage for this control to follow).

==digital-dial==

Some locomotives use a digital readout rather than analogue dials.

Trainz has two control kinds to support digital displays - one for speed units, and one for pressure units. Instead of angles of movement, these both have some font specific options to configure how the digits appear.

"font" defines the typeface. For a list of valid typefaces, see the [[%22mesh-table%22_container_(interior_version)#font|mesh-table (interior version)]] documentation. Generally this follows closely with a number of default windows font names.

"fontsize" defines the size of the font. The default value for this is 0.02, and this is a pretty respectable size display.

"fontcolor" defines the RGB color of the text. Each value is a floating point number between 0.0 and 1.0.

===digital-dial-spd===

For a speedometer (or any other gauge that shows units in speed, e.g. a speed limit display), use kind 'digital-dial-spd'.

An example speedometer using this kind would be declared as:

speedo_needle2
{
kind "digital-dial-spd"
att "a.digispeedo"
font "arial"
fontsize 0.01
fontcolor 1.0,1.0,1.0
auto-create 1
}

===digital-dial-prs===

For a display using pressure units, use digital-dial-prs. This is a digital brake pipe pressure gauge:

bptrainbrakepipe_needle2
{
kind "digital-dial-prs"
att "a.trainpipe_pressure"
font "arial"
fontsize 0.01
fontcolor 0.0,1.0,0.0
auto-create 1
}

==firebox==

The firebox control is a special kind to implement the fire of a steam locomotive.

(Further information about this specific control to follow).

Note: Some steam cab interior models use the firebox, fireglow and burning coal effects found in the Auran PB15 cab interior. This can cause quite severe flickering effects in some models The intensity of flickering varies on the textures used and can be attenuated by use of darker colours. The flickering can be eliminated by not using the firebox effect. The fireglow and burning coal (coal) effects are OK.

'''Note: This feature does not work currently in T:ANE and TRS19.
'''

You can, of course, always make your own.

=Scripting additional behaviour in a cab=

A lot can be achieved in Trainz purely by naming the controls correctly and relying on Trainz default cab scripts to make them work. A quite reasonable cab can be made for many locomotives without having to do any scripting whatsoever.

However, a lot more realism can be achieved by scripting the cab. Additional features can be added beyond what Trainz supports, including new types of controls, or extended behaviour on existing controls.

The first thing to consider when looking at scripting a cab, is "is the cab the best place for this feature?". A cab is not a persistent asset, which means it can go away at any point. When it's gone, it isn't running it's script. Consequently, it is a bad place for any persistent or time based logic - it should only be used to script the immediate behaviour of the controls. Anything beyond this should be implemented the vehicle itself or possibly a script library, both of which are more persistent objects.

If all you want to achieve is to add some simple extra features (e.g. a display of signal aspects within the cab), you can derive from the trainz standard classes, and inherit the default behaviour when adding your new behaviour. This means you can concentrate on just your extra feature, and don't have to worry about making existing functionality work.

If you want to do something a little more advanced (e.g. change the behaviour of the throttle and/or brake controllers), then you are probably best deriving your cab script from the 'cabin' class, ignoring the default cab scripts, and implementing your required behaviour from scratch. This gives you a lot more control, but you do need to do more yourself.

For some examples of the first route, have a look at the MN cabs - the M7 or the ACMU are good examples. Both have a cab signal repeater implemented in the cab interior script, and use the base functionality for almost everything else.

-~= To Be Continued... =~-

==Return to Index==

[[HowToGuides|<< How To Guides]]

[[Category:How-to guides]]

HowTo/Build a cab interior

2020-06-10T20:55:40Z

Gdennish: /* Lever */

Trainz uses an [[KIND_Interior|interior]] object to represent a locomotive cab, or view from another vehicle, e.g. a passenger coach, brake van or caboose. Interiors can also be attached to some non-train assets. For this howto, I am going to assume that we are creating a traincar interior, and focus primarily on a cab interior for a diesel or electric locomotive.

=Basic structure=

The basic structure of a cab is quite similar to a number of different assets. You will have a main mesh with a number of attached sub-meshes, which are arranged using a [[%22mesh-table%22_container_(interior_version)|mesh-table]].

The main cab mesh typically consists of the interior walls, roof and floor of the cab, the control desk or stand, all furniture or other static objects visible inside the cab, and also all parts of the locomotive exterior that are visible from inside the cab - e.g. the top of any projecting nose below the cab windows. Remember to consider the sightlines out of rear windows too for visible bodywork panels - the user can move around the cab and rotate the camera to any angle. Users are not restricted to looking forward out of the front windows only.

=Artwork considerations=

There are some differences in style between the construction of an interior object and a typical trainz object.

Except in very specific circumstances, there will not be more than one interior object in existence at any time, and that interior is always viewed from very close range - the user is inside it. Because of this, interiors are typically modelled with a high polygon count and with high resolution textures, to give an impressive visual feel. LOD is not used, as the user never gets far enough away from the interior for LOD techniques to have worthwhile benefit.

Trainz lights interior objects differently to map objects like buildings and other scenery - the main illumination is ambient, not directional. (A steam loco does have a directional light coming from the firebox, but a diesel or electric cab typically has no directional light inside, and relies entirely on ambient illumination).

With ambient illumination, effects such as normal and specular mapping do not have much (if any) effect. Because of this, more effort needs to be put into the diffuse texture for a cab interior than would normally be applied to Trainz objects. Drawing or baking shadows and other effects into the diffuse textures is required to produce a nice looking cab interior.

An example cab would be the [[File:PB_interior.rar]]

=A basic config file=

The minimal required config for an interior to show in-game is:

kind interior
kuid <kuid2:YOUR:KUID:HERE>
trainz-build 2.9
username "Your interior name here"
category-class ZI

mesh-table
{
default
{
mesh "your_interior_mesh_name.im"
auto-create 1
}
}

Note: There are also other base tags that should be added that are common to all asset types - e.g. the download station will require a valid thumbnails container before the asset can be uploaded. See the documentation for [[KIND TrainzBaseSpec]] for details of tags which apply to all trainz assets. Depending on which Trainz version you have and which trainz-build number you have specified, some of these may be required - content manager will tell you what is required, listing missing tags as errors.

==camera positions==

If we load a cab up with that config file, we will note that the view is not particularly appealing. Chances are we're right down near the floor. To fix this, we need to define some default positions for camera views. This is done with the [[%22cameralist%22_Container|cameralist container]] and the [[KIND_Interior#cameradefault|cameradefault]] tag.
Add the following to your config.txt file:

cameralist
{
camera0 0,0,2,0,0
}

cameradefault 0

The cameralist container can contain any number of cameras, but they must be numbered sequentially and start at zero.

The five numbers are the X, Y and Z coordinates of the camera in metres relative to the 0,0,0 point of the interior mesh, and the Yaw and Pitch in radians. Luckily you don't have to work these values out from scratch - add the line "-freeintcam" to your trainzoptions.txt file, and you can move the camera about in the cab with the mouse and keyboard, and the precise position will be displayed in the bottom right corner.

When you have found a position you like, write the numbers down. When you've got a good selection of positions recorded, add them to the cameralist container.

You may wish to return to this and tweak the values later once all the controls are in place - but it's handy to have a good starting position for the camera while testing.

=Cab controls=

A locomotive cab interior needs working cab controls. What fun would sitting in the drivers seat be without being able to pull on the levers, change the switches, and watch the gauges and dials move?

The moving part of each lever, switch, gauge or dial is created as a separate mesh, which is then attached to the cab with an attachment point. (The static part, e.g. guide rails for levers, should be part of the cab mesh itself).

==Lever==

The lever is the basic input device in a cab. It is based on rotational movement, and any object that requires rotational movement (e.g. a wheel or ring) can be implemented as a lever.

If you actually want linear movement, you can still use a lever - just move the attachment point a long way away - e.g. 10 or 20 metres away from the control. The resulting small arc will not be noticable over the length of movement. As an example, sliding windows in Trainz cabs have been implemented as levers "attached" something like 10 or 20 metres out to the side of the vehicle for a long time. (The exception to this is a horn pull rope - trainz provides a control specifically for this purpose).

You will need to create the lever in your modelling program aligned correctly - the rotation needs to be around the Z axis, and main part of the object will point along the Y axis.

When adding the attachment point to the main mesh, align it so the Z axis is the axis of rotation. It is common to point the Y axis at the default position - e.g. levers in the 'off' or 'neutral' position, and needles pointing to zero. This is not strictly required, as the range of movement can be adjusted at both ends, but it provides a handy reference when creating the config file.

[[File:BasicLeverSetup.png|350px|thumb|An example of a lever being used as a signboard cover.]]

It is worth noting that you can reuse a mesh for multiple attachments. This is particularly useful for switches, as identical appearance switches are often used repeatedly in a cab for different purposes.

===Throttle Lever===

A good example of a standard lever in use is a locomotive throttle control. A typical US diesel throttle has 9 notched positions (from 0 to 8 inclusive).

As noted above, the lever is created in the modelling package so it points along the Y axis and the axis of rotation is along the Z axis. The attachment point is added to the cab interior mesh at the correct position, and rotated so the Z axis is aligned with the axis of rotation, and the Y axis points to the default position.

Now we need to add an entry to the config file to add our throttle lever.

Into the mesh table, add an entry like this:

throttle_lever
{
kind "lever"
mesh "throttle_lever.im"
att "a.throttle_lever"
limits 0,8
angles 0,1.57
notches 0,0.125,0.25,0.375,0.5,0.625,0.75,0.875,1
notchheight 1,2,2,2,2,2,2,2,1
radius 0.35
auto-create 1
att-parent "default"
}

... remember to set your attachment point and mesh name correctly.

The 'angles' line defines how far the control rotates. It is in radians - there are 2 x Pi (6.28) radians in a complete circle. My default of 1.57 will give you about 90 degrees of rotation, in the positive direction. Adjust this number to get the control to rotate the correct amount. You should be able to work out the number you need in your modelling program by using the rotate tool on the attachment point, and recording the amount of rotation required to move to the intended maximum location. It should not require significant trial and error.

The 'radius' line defines the position of the notch position overlay and the text label. It is in metres. If the overlay is too close in, increase this number. If it is too far out, decrease it.

If the lever is the wrong way round (notch 8 is at the wrong end), swap the numbers in the 'angles' tag over, so the higher one is first.

If the lever moves the wrong way when you drag it with the mouse (i.e. it goes left in response to a right drag), add the line:
mousespeed -1
This will invert the mouse movement.

The fact we called this lever "throttle_lever" means it will be used to control the throttle by the default cab script.

So what happens if we wanted a different number of notches? Below is an example of a throttle which has 22 notches. The second value in the 'limits' tag has been edited to return up to notch 22, and more entries have been added to the 'notches' and 'notchheight' tags:

throttle_lever
{
kind "lever"
mesh "throttle_lever.im"
att "a.throttle_lever"
limits 0,22
angles 0,0.94
notches 0,0.045,0.091,0.136,0.182,0.227,0.273,0.318,0.364,0.409,0.455,0.5,0.545,0.591,0.636,0.682,0.727,0.773,0.818,0.864,0.909,0.955,1
notchheight 1,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,1
radius 0.35
auto-create 1
att-parent "default"
}

===Reverser Lever===

The reverser lever is created in a similar manner to throttle lever. The mesh table entry for this will look like:

reverser_lever
{
kind "lever"
mesh "reverser_lever.im"
att "a.reverser_lever"
limits 0,2
angles -0.79,0.79
notches 0,0.5,1
notchheight 1,1,1
radius 0.25
auto-create 1
att-parent "default"
}

In this case, because the 'angles' entry has a range both positive and negative, the lever can move in both directions relative to the attachment point. The game will set the default position to neutral (1), so if you've lined up your attachment point at one end, don't worry - you can use angles which range from zero if you need to.

===Train Air Brake Lever===

There are two types of train air brake lever. A given locomotive only has one type - the brakes are either require manual lapping or are self-lapping. Use the appropriate name and configuration for the loco you are modelling.

====Manual Lapped Brakes====

The manual train brake lever has five positions numbered from zero to four, each one representing a different function. Those functions are Release, Lap, Application, Emergency and Handle Off respectively.

A lever for a manual lap train air brake is defined as follows:

trainbrakelap_lever
{
kind "lever"
mesh "train_brake_lap_lever.im"
att "a.train_brake_lap_lever"
limits 0,4
angles 0,0.94
notches 0,0.25,0.5,0.75,1
notchheight 1,1,1,1,1
radius 0.25
att-parent "default"
auto-create 1
}

In this case, the attachment for the lever has been created in the 'release' position. If it had been created in the 'handle off' position, the angle tag would have been more like:

angles -0.94,0

====Self Lapping Brakes====

A self lapping trainbrake lever has a number of primary notches similar to the manual lap train brake lever. However, instead of a 'lap' and 'apply' position, it has a grade of application between the 'initial' and 'full application' positions. An example of a self-lapping brake handle is this one:

trainbrake_lever
{
kind "lever"
mesh "train_brake_lever.im"
att "a.train_brake_lever"
limits 0,4
angles 0,0.94
notches 0,0.25,0.27,0.29,0.31,0.33,0.35,0.37,0.39,0.41,0.43,0.45,0.47,0.49,0.5,0.75,1
notchheight 1,1,2,2,2,2,2,2,2,2,2,2,2,2,1,1,1
radius 0.25
att-parent "default"
auto-create 1
}

In this case, there are 14 possible levels of brake application - initial at 0.25, 12 intermediate levels, and full application at 0.5. There is no restriction on the number of intermediate levels - if you are modelling a prototype brake handle with a specific number, you may create precisely that number of notches and arrange them between 0.25 and 0.5 as required.

===Combined throttle brake lever===

There is also another control option - a combined throttle brake lever. This type of control is often found on multiple unit trains. This control is split into two halves. The first half of the movement is an inverted throttle - i.e. max power at zero, no power at 0.5. The second half is an auto lapped train brake application, with 0.5 as release, and 1.0 as emergency. An example of how to configure a combined throttle and brake lever is below:

throttle_brake_lever
{
kind "lever"
mesh "throttle_brake_handle.im"
auto-create 1
att "a.throttle_brake_handle"
limits 0,16
angles 0.94,-0.94
notches 0,0.0625,0.125,0.1875,0.25,0.3125,0.375,0.4375,0.5,0.5625,0.625,0.6875,0.8125,0.75,0.875,0.9375,1
notchheight 1,2,2,2,2,2,2,2,1,2,2,2,2,2,2,2,1
att-parent "default"
radius 0.12
invert 1
}

Unfortunately, trains that use this type of control generally use blended and/or EP brakes, and this control uses the standard Trainz air brake, which operates in a distinctly different manner, and as a result, can feel very wrong for this control type. (See the section on scripting controls for how a better combined brake and throttle lever may be implemented).

==Pull lever==

This is a sprung lever. You pull on this lever to activate it, and when you let it go, it returns to the original position. This kind of action is commonly associated with a locomotive horn, and this is what I am using as an example:

horn
{
kind "pulllever"
mesh "horn.im"
att "a.horn"
auto-create 1
angles 0,-0.55
limits 0,1
mousespeed -1
radius -0.02
notches 0,1
notchheight 0,0
}

==Switch==

A switch is a lever that does not require the user to 'drag' it with the mouse - it operates on a click only. This is used for smaller controls that are 'on' or 'off', and do not have intermediate positions. Parameters are much like they are for a 'lever', only a switch should only have two notches - on and off.

Unfortunately, some things you'd normally associate with being a 'switch' (e.g. the headlight switch control) require mulitple positions, and will need to remain as a 'lever' in order to allow the player to set the correct position for the control.

An example of a switch would be:

switch1
{
kind "switch"
mesh "switch.im"
att "a.switch1"
limits 0,1
angles 1.4,0
notches 0,1
notchheight 0,0
}

As 'switch' was introduced in TS2009 SP2, interiors that use kind 'switch' controls should be marked trainz-build 3.1 or later in the config.txt.

==button==

A button is a momentary contact press-and-hold button. This is a brand new control added for TS12 patch 2, released end of june 2011. Content using this feature should have trainz-build 3.6 or later in the config.txt.

Finally this brings Trainz the "click to press", "hold to hold pressed", "let go to release" style momentary pushbutton.

button1
{
kind "button"
mesh "switch.im"
att "a.switch1"
limits 0,1
angles 0,0.1
notches 0,1
notchheight 0,0
}

==Pull rope==

This is a linear pull rope control. Unlike the rotating controls discussed previously, this control type moves the mesh linearly along the Z axis of the attachment. It behaves as you would expect from a suspended rope - click and drag to pull, let go to release. It will spring back to it's initial position in the same manner as kind 'pulllever'.

[[File:Pullropetype.png|800px]]]

horn
{
kind "pullrope"
mesh "horn_rope.im"
att "a.horn"
limits 0,1
angles 0.1,0
notches 0,1
notchheight 0,0
mousespeed -1
}

==needle==

A needle is the standard Trainz output device. Like the lever, it is based on rotational movement, and any gauge, dial, or other output device based on rotational movement can be implemented. Any static part of the gauge should be modelled as part of the cab, and only the moving part as part of the needle. Like the lever, the rotation will be around the Z axis of the needle, and it is common practice to point the point of the needle along the Y axis. Cabs often have a number of similar gauges, and re-using the same needle repeatedly in each gauge is a lot easier if this setup is done consistently.

As an example of a needle, here is a basic speedometer:

speedo_needle
{
kind "needle"
auto-create 1
mesh "speedo_needle.im"
att "a.speedo_needle"
limits 0,67.056
angles 0,4.712
}

The default cab script knows to move the "speedo_needle" object as the train speed changes, so simply by naming this control "speedo_needle", it has become a speedometer.

For a speedo, the 'limits' values will be the minimum and maximum reportable speed in m/s.

Creating other rotational gauges is similar - refer to the [[%22mesh-table%22_container_(interior_version)|mesh-table (interior version)]] documentation to see all the different values that Trainz can show by default.

==light==

Another common type of control is a light. This is created simply as a textured plane, which is either hidden or shown to represent light off or light on. It is attached as any other standard mesh attachment would be - there is no rotation to worry about here.

wheelslip_light
{
kind "light"
mesh "wheelslip_light.im"
att "a.wheelslip_light"
}

This light will be used to show wheelslip in a default cab.

==animated-lever==

If you want more complex movement than simple rotation, you have the option of animating the lever and using kind 'animated-lever'. This will use an animation you create in your modelling program to move the control about. An example of this is visible in the MN ACMU cab. (I've reduced the number of notches here for readability - the real one has 32, not 16).

throttle_lever
{
mesh "throttlehandle.im"
anim "throttlehandle.kin"
auto-create 1
att "a.throttlelever"
limits 0,16
notches 0,0.0625,0.125,0.1875,0.25,0.3125,0.375,0.4375,0.5,0.5625,0.625,0.6875,0.8125,0.75,0.875,0.9375,1
notchheight 1,2,2,2,2,2,2,2,1,2,2,2,2,2,2,2,1
att-parent "default"
kind "animated-lever"
test-collisions 0
mousespeed 1
}

Where the standard lever is rotated between it's angles to move from notch to notch, the animated-lever has it's animation played to the corresponding frame.

===collision-proxy===

Animated levers can be hard to grab hold of compared to normal levers. To get around this, an invisible mesh is used to show the game the range of movement the control has, and to allow the user to grab the lever more easily. This example again comes from the MN ACMU cab:

throttle-collision-box
{
mesh "throttlehandleselection.im"
att-parent "throttle_lever"
att "a.selection_box"
auto-create 1
kind "collision-proxy"
opacity 0
collision-parent "throttle_lever"
}

==animated-dial==

If you've been paying attention to levers, needles and animated levers, I think you can guess where we are going with this one. This is an animated needle. Instead of rotating between the angles specified, it plays it's animation to the relevant frame to show the value. Use this when what you want to achieve can't be done with simple rotational movement.

(Example usage for this control to follow).

==digital-dial==

Some locomotives use a digital readout rather than analogue dials.

Trainz has two control kinds to support digital displays - one for speed units, and one for pressure units. Instead of angles of movement, these both have some font specific options to configure how the digits appear.

"font" defines the typeface. For a list of valid typefaces, see the [[%22mesh-table%22_container_(interior_version)#font|mesh-table (interior version)]] documentation. Generally this follows closely with a number of default windows font names.

"fontsize" defines the size of the font. The default value for this is 0.02, and this is a pretty respectable size display.

"fontcolor" defines the RGB color of the text. Each value is a floating point number between 0.0 and 1.0.

===digital-dial-spd===

For a speedometer (or any other gauge that shows units in speed, e.g. a speed limit display), use kind 'digital-dial-spd'.

An example speedometer using this kind would be declared as:

speedo_needle2
{
kind "digital-dial-spd"
att "a.digispeedo"
font "arial"
fontsize 0.01
fontcolor 1.0,1.0,1.0
auto-create 1
}

===digital-dial-prs===

For a display using pressure units, use digital-dial-prs. This is a digital brake pipe pressure gauge:

bptrainbrakepipe_needle2
{
kind "digital-dial-prs"
att "a.trainpipe_pressure"
font "arial"
fontsize 0.01
fontcolor 0.0,1.0,0.0
auto-create 1
}

==firebox==

The firebox control is a special kind to implement the fire of a steam locomotive.

(Further information about this specific control to follow).

Note: Some steam cab interior models use the firebox, fireglow and burning coal effects found in the Auran PB15 cab interior. This can cause quite severe flickering effects in some models The intensity of flickering varies on the textures used and can be attenuated by use of darker colours. The flickering can be eliminated by not using the firebox effect. The fireglow and burning coal (coal) effects are OK.

'''Note: This feature does not work currently in T:ANE and TRS19.
'''

You can, of course, always make your own.

=Scripting additional behaviour in a cab=

A lot can be achieved in Trainz purely by naming the controls correctly and relying on Trainz default cab scripts to make them work. A quite reasonable cab can be made for many locomotives without having to do any scripting whatsoever.

However, a lot more realism can be achieved by scripting the cab. Additional features can be added beyond what Trainz supports, including new types of controls, or extended behaviour on existing controls.

The first thing to consider when looking at scripting a cab, is "is the cab the best place for this feature?". A cab is not a persistent asset, which means it can go away at any point. When it's gone, it isn't running it's script. Consequently, it is a bad place for any persistent or time based logic - it should only be used to script the immediate behaviour of the controls. Anything beyond this should be implemented the vehicle itself or possibly a script library, both of which are more persistent objects.

If all you want to achieve is to add some simple extra features (e.g. a display of signal aspects within the cab), you can derive from the trainz standard classes, and inherit the default behaviour when adding your new behaviour. This means you can concentrate on just your extra feature, and don't have to worry about making existing functionality work.

If you want to do something a little more advanced (e.g. change the behaviour of the throttle and/or brake controllers), then you are probably best deriving your cab script from the 'cabin' class, ignoring the default cab scripts, and implementing your required behaviour from scratch. This gives you a lot more control, but you do need to do more yourself.

For some examples of the first route, have a look at the MN cabs - the M7 or the ACMU are good examples. Both have a cab signal repeater implemented in the cab interior script, and use the base functionality for almost everything else.

-~= To Be Continued... =~-

==Return to Index==

[[HowToGuides|<< How To Guides]]

[[Category:How-to guides]]

File:BasicLeverSetup.png

2020-06-10T20:48:51Z

Gdennish:

"mesh-table" container (interior version)

2020-06-10T20:39:59Z

Gdennish: Added more entries to the Steam cabin entries and organized by lever and needle type.

The "mesh-table" container is a top-level [[config.txt file]] entry used by various [[Content_Configuration#Content_Types|Content Types]]. Refer to the [["mesh-table" Container]] documentation for the standard tags - this document only describes the extensions available within the mesh table when it is used in a [[KIND_Interior|cab interior]] asset.

Most of the entries in a mesh-table for an interior will be cab controls. A cab control has a single value associated with it, which could be an input (e.g. a lever position) or an output (a dial or gauge position).

=Standard Mesh Names=

There are a number of standard mesh names that the trainz default cab script uses for it's controls. For a Diesel or Electric cab (either unscripted, or scripted and inheriting from the DefaultLocomotiveCabin class), the following are the default mesh names:

'''Needles:'''
* speedo_needle -- speedometer
* speedo_needle2 -- speedometer
* bplocomain_needle -- loco main reservoir pressure gauge
* bptrainbrakecylinder_needle -- locomotive brake cylinder pressure gauge
* bptrainbrakecylinder_needle2 -- locomotive brake cylinder pressure gauge
* no3pipe_needle -- brake pressure gauge (currently loco brake cylinder -- but maybe intended for something else?)
* bptrainbrakecylinder2_needle -- brake pressure gauge (source unknown)
* bptrainbrakepipe_needle -- train brake pipe pressure gauge
* bptrainbrakepipe_needle2 -- train brake pipe pressure gauge
* bploco_equaliser -- brake equaliser pressure gauge
* flow_needle -- brake flow rate gauge
* ampmeter_needle -- traction ammeter gauge
* ampmeter2_needle -- traction ammeter gauge

'''Levers:'''

* throttle_lever -- throttle lever control
* reverser_lever -- reverser lever control
* trainbrake_lever -- self-lapping train brake control
* trainbrakelap_lever -- non self-lapping train brake control
* independantbrake_lever -- locomotive independent brake control. Note the typo in the control name.
* dynamicbrake_lever -- dynamic brake control
* wheelslip_light -- wheelslip indicator
* horn -- horn control
* light_switch -- light control
* pantograph_lever -- pantograph control
* throttle_brake_lever -- combined throttle/self-lapping brake lever
* bell -- bell control
For a Steam cab (either unscripted, or scripted and inheriting from the DefaultSteamCabin class), these default mesh names are available:

'''Needles:'''

* speedo_needle -- speedometer
* bplocomain_needle -- loco main reservoir pressure gauge
* bptrainbrakecylinder_needle -- locomotive brake cylinder pressure gauge
* no3pipe_needle -- brake pressure gauge (currently loco brake cylinder -- but maybe intended for something else?)
* bptrainbrakecylinder2_needle -- brake pressure gauge (source unknown)
* bptrainbrakepipe_needle -- train brake pipe pressure gauge
* bploco_equaliser -- brake equaliser pressure gauge
* flow_needle -- brake flow rate gauge
* boiler_needle -- boiler pressure
* boiler_needle1 -- boiler pressure
* steam_chest_needle -- steam chest pressure

'''Levers:'''

* trainbrake_lever -- self-lapping train brake control
* trainbrakelap_lever -- non self-lapping train brake control
* independantbrake_lever -- locomotive independent brake control. Note the typo in the control name.
* horn -- horn control
* light_switch -- light control
* waterglass_left -- boiler water level
* waterglass_right -- boiler water level
* firebox -- the interior of the firebox (to show fire temperature) Only works pre-TANE.
* regulator -- regulator (throttle) control
* reverser -- cutoff (reverser) control
* water_injector_0 -- primary water injector control
* water_injector_1 -- secondary water injector control
* blower -- steam blower control
* fire_plates -- the firebox door
* sanding_lever -- locomotive sander control
* blowdown_lever -- blowdown control (releases water out of the boiler)
* bell -- bell control
* left_window -- Left window control
* right_window -- Right window control
* left_sliding_window-- Left sliding window control
* right_sliding_window-- Right sliding window control
* seat0 -- Seat control
* seat1 -- Seat control
* whistle_lever -- Whistle lever control. (Doesn't seem to actually control the horn, so the whistle lever should actually be called "horn" to function properly."

=Supported Tags=
Each mesh subcontainer supports the following tags. Each tag is shown here with its default value. Standard tags inherited from the normal mesh table are omitted for brevity.

tooltip-text ""
tooltip-token ""
tooltip-mesh ""
limits 0,1
angles 0,0
kind ""
collision-parent ""
mousemode ""
mousespeed 1
notches
invert 0
notchheight
onlight ""
value 0.0
font "swiss"
fontsize 12
fontcolor 1.0,1.0,1.0
fade-time 0.5

====angles====
:Type: Decimal Pair
:Desc: Specifies the minimum and maximum extents of movement for a control or needle. For control types that rotate, these values are in radians[[http://en.wikipedia.org/wiki/Radian]]. In the case of a speedometer, this would define the amount of angular movement of the needle - a speedometer running from horizontal left to horizontal right may use -1.57 to 1.57, for example. If the cab control needs to move the other way, put the higher number first.

====collision-parent====
:Type: String
:Desc: A mesh of kind collision-proxy must specify a collision-parent - the mesh it is a collision proxy for. This is the name of another control in the mesh-table.

====fade-time====
:Type: Float
:Desc: The time, in seconds, for a "light" control to fully switch on or off. Default is 0.5 seconds.

====font====
:Type: String
:Desc: Font name to use for the readout of a digital control.
:Options are:
:* ''swiss'' (Default option. Renders with arial in PC builds.)
:* ''times_new_roman''
:* ''verdana''
:* ''century_gothic''
:* ''cordia''
:* ''courier''
:* ''helvetica''
:* ''arial''
:* ''comic_sans''
:* ''sans_serif''
:* ''impact''
:* ''console''
:* ''tohoma'' (renders using the ''Tahoma'' font on PC builds.)
:* ''garamond''
:These roughly correspond with Windows font names. Beware - not all fonts are available on all platforms, and where a font is not available, a different font may be substituted.

====fontcolor====
:Type: Decimal Triplet
:Desc: RGB font color for the readout of a digital control. Colors are specified within the range 0.0 to 1.0, with 0.0 being black and 1.0 being full intensity. Default is 1.0,1.0,1.0 - white.

====fontsize====
:Type: Decimal
:Desc: Font size for the readout of a digital control. Default is 12.

====invert====
:Type: Boolean
:Desc: Invert mouse movement for this control. If the control moves the wrong way compared to the mouse, change this setting.

====kind====
:Type: Selection
:Desc: The type of control this mesh table element represents.
:Options are:
:* ''animated-lever''
:Operates like a standard lever, only uses a named animation instead of the angles tag for movement.
:* ''animated-dial''
:Operates like a standard needle, only uses a named animation to represent the gauge readout instead of the angles tag.
:* ''collision-proxy''
:This element type defines a volume within the cab where the mouse pointer will be considered to be over the cab control. Generally used in conjunction with an animated-lever. Name of the animated lever is defined in the tag ''collision-parent''.
:* ''digital-dial-spd''
:Digital readout for a speedometer, and using speed units.
:* ''digital-dial-prs''
:Digital readout for a pressure gauge, using pressure units.
:* ''firebox''
:The animated firebox in a steam locomotive.
:* ''lever''
:A standard lever, often used for throttle and brake controls. Requires the user to click hold and move the mouse to move the lever between it's notches. This control will stay at any notch position when let go.
:* ''light''
:A light glow / overlay - this mesh is hidden when the light is off and shown when the light is on.
:* ''needle''
:An analogue gauge needle. Can be used to implement many different types of gauges.
:* ''pulllever''
:Like a lever, only sprung to return to it's initial position when the user lets go of the control. Useful for horns.
:* ''pullrope''
:Like a pulllever, only with linear (not rotational) movement.
:* ''switch''
:This control requires only a single click to move between it's two endpoints. It is better suited than a lever to small switches and buttons.
:* ''button''
:Similar to switch but requires the mouse be held down to keep the control active. I.e., press and hold the mouse button to push the control down, release the mouse and the control will return to the off position.

====limits====
:Type: Decimal Pair
:Desc: Specifies the minimum and maximum values for a cab control or needle at it's two endpoints of movement. In the case of a speedometer, this would be the range of speeds it can display - 0m/s to 50m/s, for example.

====mousemode====
:Type: String
:Desc: If set to "exact", will require the mouse to be positioned over the geometry of the control precisely to activate it. Otherwise a bounding volume is used. This is useful for large controls which would otherwise block access to smaller controls.

====mousespeed====
:Type: Float
:Desc: Controls the mouse speed and push/pull direction for controls. '''''Do not use zero'''''.
:Examples of use:
:* mousespeed -1 Inverts mouse direction.
:* mousespeed 2 Doubles mouse speed in default direction.
:* mousespeed -0.5 Inverts mouse direction and halves the speed.

====notches====
:Type: Decimal List
:Desc: Specifies the positions of the notches for this control. Notches are discrete positions within the movement of the control where the lever can be stopped. If a lever does not have notches, it can be positioned at any location. There are two common uses for notches. Firstly, they can be used to define a control which has a number of discrete positions which mean specific things (e.g. a brake valve). Secondly, they are used to define pre-set discrete values that a control can provide (e.g. a throttle lever). A typical US diesel 8 notch throttle would have something like "notches 0.0,0.125,0.25,0.375,0.5,0.625,0.75,0.875,1.0", specifying nine positions (for 'off' and notches 1 thru 8).

====notchheight====
:Type: Integer List
:Desc: Specifies the importance of the notches for this control. This affects how the graphical overlay draws each notch. This is useful for a combined brake and throttle controller, or any other control where you want to mark a specific position relative to the others. This should have the same number of values as the 'notches' list.
:Three styles are available:
:* '1' configures this bar to be a standard length and width bar.
:* '2' configures this bar to be shorter in length, and is often used for intermediate positions.
:* '3' configures this bar to be standard length, but thicker in width. This is often used for marking a specific position.

====onlight====
:Type: String
:Desc: Specify the name of a ''light'' kind mesh which is enabled when this switch/lever is in the ''on'' position, and disabled when it is in the ''off'' position. The mesh name must be in the mesh-table. See the example below.

====radius====
:Type: Decimal
:Desc: Specifies the distance for the 2D notch overlay.

====tooltip-mesh====
:Type: String
:Desc: Specifies the name of a mesh-table entry for a mesh to show when the control is moused over. The mesh will be faded in/out over a short period.

====tooltip-text====
:Type: String
:Desc: OBSOLETE: DO NOT USE. This text will be used in the tooltip that appears when the mouse cursor hovers over a cab control.

====tooltip-token====
:Type: String
:Desc: The name of a string table entry. The contents of the named string table entry will be displayed as a tooltip that appears when the mouse cursor hovers over a cab control. If a token is used then it must appear as a tag in the [[%22String-table%22 container]].

====value====
:Type: Decimal
:Desc: Specifies the initial value for this control. For a lever or other input device, this will specify the initial position of the control before the user moves it.

=Cab Interior Mesh-Table Example=
The following is an example of a mesh-table which implements a number of cab controls

mesh-table
{
default
{
mesh "interior.im"
auto-create 1
}

wheelslip_light
{
kind "light"
mesh "wheelslip_light.im"
auto-create 0
}

bptrainbrakepipe_needle2
{
kind "digital-dial-prs"
mesh "brakeneedle.im"
att "a.brakepipe2"
limits 0,55
font "arial"
fontsize 0.007
fontcolor 80,240,120
auto-create 1
}

speedo_needle2
{
kind "digital-dial-spd"
mesh "brakeneedle.im"
att "a.digispeedo"
limits 0,55
font "arial"
fontsize 0.01
fontcolor 0,0,0
auto-create 1
}

throttle_lever
{
kind "lever"
mesh "throttle.im"
att "a.throttle"
limits 0,8
angles 0,1.69
notches 0,0.125,0.25,0.375,0.5,0.625,0.75,0.875,1
notchheight 1,2,2,2,2,2,2,2,1
radius 0.35
mousespeed -1
auto-create 1
}

dynamicbrake_lever
{
kind "lever"
mesh "dynamic_handle.im"
att "a.dynamic"
limits 0,2
angles 0,-1.69
notches 0,1
notchheight 0.1,1
mousespeed -1
radius 0.35
auto-create 1
}

trainbrakelap_lever
{
kind "lever"
auto-create 1
mesh "trainbrake_handle.im"
att "a.trainbrake_handle"
limits 0,4
angles 0,-2
notches 0,0.25,0.5,0.75,1
notchheight 2,2,2,2,2
mousespeed 1
}

independantbrake_lever
{
kind "lever"
mesh "indy_handle.im"
att "a.ind"
limits 0,32
angles 0.94,0
notches 0,0.5,1
notchheight 1,1,1
radius 0.35
mousespeed 1
auto-create 1
}

flow_needle
{
kind "needle"
mesh "flowneedle.im"
att "a.bpflow"
limits 0,1050
auto-create 1
}

bplocomain_needle
{
kind "needle"
mesh "brakeneedlered.im"
att "a.mainres"
limits 0,1240
auto-create 1
}

bploco_equaliser
{
kind "needle"
mesh "brakeneedle.im"
att "a.eqres"
limits 0,1240
auto-create 1
}

bptrainbrakecylinder_needle
{
kind "needle"
mesh "brakeneedlered.im"
att "a.brakecyl"
limits -50,1390
auto-create 1
}

bptrainbrakepipe_needle
{
kind "needle"
mesh "brakeneedle.im"
att "a.brakepipe"
limits 0,1240
auto-create 1
}

speedo_needle
{
kind "needle"
mesh "speedo_pointer.im"
att "a.speedo"
limits 0,43
auto-create 1
}

ampmeter_needle
{
kind "needle"
mesh "needleamps.im"
att "a.ampmeter"
limits 0,1700
angles 0,3.02058
auto-create 1
}

reverser_lever
{
kind "lever"
mesh "reverser_handle.im"
att "a.throttle01"
limits 0,2
angles -0.55,0.55
notches 0,0.5,1
notchheight 1,1,1
mousespeed -1
auto-create 1
}

light_switch
{
kind "lever"
att "a.hdlt"
mesh "hdltswtch.im"
limits 0,1
angles 0,2
notches 0,1
notchheight 0.1,0.1
mousespeed -1
auto-create 1
}

horn
{
kind "pulllever"
mesh "horn.im"
att "a.horn"
auto-create 1
angles 0,-0.55
limits 0,1
mousespeed -1
radius -0.02
notches 0,1
notchheight 0,0
}

pantograph_lever
{
kind "lever"
mesh "pantograph_lever.im"
att "a.pantograph_lever"
limits 0,3
angles 1.4,0
notches 0,0.5,0.75,1.0
notchheight 0,0,1,1
mousespeed -1
onlight "line_power"
}

line_power
{
kind "light"
mesh "line_power.im"
att "a.line_power"
}
}

[[Category:Config Container|M]]

Class MeshObject

2020-03-02T23:42:55Z

Gdennish:

*[[TrainzScript Language Reference|API Hierarchy]]
**[[Class GSObject|GSObject]]
***[[Class GameObject|GameObject]]
****[[Class PropertyObject|PropertyObject]]
****[[Class TrainzGameObject|TrainzGameObject]]
*****MeshObject
 

This is a base class for [[class Asset|Asset]] based game objects that have meshes, effects, animations and particles. Interface methods to deal with these are provided so things like showing or hiding a mesh, attaching a mesh to an attachment point or controlling an animation can be done from a script.

For animation Trainz interpolates between key frames. This means an intermediate animation frame is calculated dynamically to be-in-synch with the game's framerate.

Trainzscript is an interpreted scripting language intended to be used to monitor and react to events in the Trainz world, not to perform sophisticated real-time animation tasks. Using a script to start an animation in response to an event in a thread is reasonable. However trying to control animation tightly down to short intervals is likely to provide unsatisfactory results and to adversely affect overall performance of the game.

==MeshObject Messages==
Messages related to MeshObject assets:
*[[Animation-Event Message]]
*[[pfx Message]]
 

==GetFXAttachment==
{{MethodHeader|public native MeshObject GetFXAttachment(string effect)}}
;Parameters
*'''effect''' = name of the mesh effect to query.
;Returned Value
*Returns a reference to the MeshObject currently attached to the named effect.
;Syntax
MeshObject attachment = GetFXAttachment("coupler");
;Notes
*The method returns null if the effect is unoccupied.
 

==GetMeshAnimationFrame==
{{MethodHeader|public native float GetMeshAnimationFrame(string mesh)'''}}
;Parameters
*'''mesh''' = the name of the mesh or submesh container which includes the animation file to be queried.
;Returned Value
*Current fame of the animation file within the specified mesh container.
;Syntax
float height = GetMeshAnimationFrame("zPosition")
;Notes
*Note that the returned value is likely to be an interpreted floating point value.
 

==GetMeshAnimationFrameCount==
{{MethodHeader|public native float GetMeshAnimationFrameCount(string mesh)}}
;Parameters
*'''mesh''' = the name of the mesh or submesh container which includes the animation file to be queried.
;Returned Value
*The number of frames in the specified animation.
;Syntax
float positions = GetMeshAnimationFrameCount("lever");
;Notes
*Note that the returned value is a float rather than an integer.
 

==GetTextureSelfIlluminationState==
{{MethodHeader|public native bool GetTextureSelfIlluminationState(string texture)'''}}
;Parameters
*'''texture''' = root name of ''*.texture.text'' file to query.
;Returned Value
*Returns true if the specified texture has self illumination set.
;Syntax
bool isEmissive = GetTextureSelfIlluminationState("texture");
;Notes
*Compatibility warning: Use of this function is not recommended, it may become non-functional in future Trainz versions.
 

==HasMesh==
{{MethodHeader|public native bool HasMesh(string mesh)}}
;Parameters
*'''mesh''' = the name of the mesh or submesh to be queried.
;Returned Value
*None
;Syntax
if (HasMesh("ventilation")) StartMeshAnimationLoop("fans");
;Notes
*
 

==SetFXAnimationState==
{{MethodHeader|public native void SetFXAnimationState(string effect, bool state)}}
;Parameters
*'''effect''' = name of attached-animation effect containing the animation to play.
*'''state''' = true to start the animation loop, false to stop.
;Returned Value
*None
;Syntax
if (gateClosed) SetFXAnimationState("gate",false);
;Notes
 

==SetFXAttachment==
{{MethodHeader|public native MeshObject SetFXAttachment(string effect, Asset asset)'''}}
;Parameters
*'''effect''' = effect containing the attachment to be manipulated.
*'''asset''' = mesh asset to attach to the effect. If asset is null any existing asset will be removed and nothing will be added.
;Returned Value
*Returns a reference to the MeshObject which has been attached to the named effect. If the mesh asset isn't "kind mesh", returns null.
;Syntax
MeshObject lamp = SetFXAttachment("lamp0",redlamp);
;Notes
*Returns null if the effect is unoccupied when the method returns.
 

==SetFXCoronaTexture==
{{MethodHeader|public native void SetFXCoronaTexture(string effect, Asset texture)}}
;Parameters
*'''effect''' = effect containg the corona to be manipulated.
*'''asset''' = corona texture asset to attach to the effect. If asset is null the corona will be turned off.
;Returned Value
*None
;Syntax
SetFXCoronaTexture("stopLight",redCorona);
;Notes
*Other corona parameters such as frequency and size are defined in ''config.txt'' and cannot be altered by script code.
 

==SetFXNameText==
{{MethodHeader|public native void SetFXNameText(string effect, string text)}}
;Parameters
*'''effect''' = effect containg the name effect to be changed.
*'''text''' = new string value.
;Returned Value
*None
;Syntax
SetFXNameText("home","Shangri-La");
;Notes
*Method will not accept an empty string in the ''text'' parameter.
 

==SetFXTextureReplacement==
{{MethodHeader|public native void SetFXTextureReplacement(string effect, Asset textureGroup, int index)}}
;Parameters
*'''effect''' = texture-replacement effect to be changed.
*'''textureGroup''' = reference to texture group asset which is the source of the texture to be applied.
*'''index''' = index into ''textures'' table of texture-group indicating which texture to apply.
;Returned Value
*None
;Syntax
SetFXTextureReplacement("load",loadTextures,5); // applies texture 5 from texture-group
SetFXTextureReplacement("load",null,0); // clears the effect, reinstating the texture defined in the asset.
;Notes
*Use null in the textureGroup parameter to turn texture replacement off.
 

==SetFXTextureReplacementTexture==
{{MethodHeader|public native void SetFXTextureReplacementTexture(string effectName, string textureName)}}
;Parameters
*'''effectName''' = the name of the texture-replacement effect that is in the effects container of the mesh.
*'''textureName''' = the ''*.texture.txt'' file that will replace the current texture being used on the mesh.
;Returned Value
*None
;Syntax
SetFXTextureReplacementTexture("fk_parameter","lms_p3_fk_body/fk_parameter.texture");
;Notes
*This should replace any instance of SwapTextureOnMesh.
*Unlike SwapTextureOnMesh, there is no need to mention what the previous texture being used was. Simply telling Trainz to load the new texture is all that is needed for this to work.
*Swap one texture against another texture on specified mesh.
*Similar to texture-replacement effects, but without the need for an extra texture asset.
 

==SetMesh==
{{MethodHeader|public native void SetMesh(string mesh, float fadeDuration)}}
;Parameters
*'''mesh''' = the name of the mesh or submesh to be displayed.
*'''fadeDuration''' = period in seconds during which mesh visibility will be faded in or out.
;Returned Value
*None
;Syntax
SetMesh("default",0.5);
;Notes
*Shows the specified mesh and hides all other meshes.
*If fadeDuration is 0.0 the mesh transition will be instantaneous.
 

==SetMeshAnimationFrame==
{{MethodHeader|public native void SetMeshAnimationFrame(string mesh, float frame) 
public native void SetMeshAnimationFrame(string mesh, float frame, float period)}}
;Parameters
*'''mesh''' = the name of the mesh or submesh container which includes the animation file to be manipulated.
*'''frame''' = the frame position to which the animation is to be moved, this may be an interpolated value.
*'''period''' = the period over which the animation will be moved from its current position to the newly specified point.
;Returned Value
*None
;Syntax
SetMeshAnimationFrame("default",5.0); // move the animation to frame 5 instantaneously
SetMeshAnimationFrame("default",5.0,2.0); // move the animation to frame 5 over 2 seconds
;Notes
*Moves the specified animation to the specified frame.
*For the first variant the transition is instant.
*For the second variant the transition will complete during the specified period.
 

==SetMeshAnimationSpeed==
{{MethodHeader|public native void SetMeshAnimationSpeed(string mesh, float speed)}}
;Parameters
*'''mesh''' = the name of the mesh or submesh container which includes the animation file to be manipulated.
*'''speed''' = multiplication factor to apply to the original animation speed.
;Returned Value
*None
;Syntax
SetMeshAnimationSpeed("fans",2.0); // run fans at double speed
SetMeshAnimationSpeed("fans",-1.0); // run fans backwards at original speed
;Notes
*Modifies the speed at which the animation is played.
*The original speed is multiplied by the new speed factor.
*Use negative values to make the animation run in reverse.
*It is ''not'' compatible with SetMeshAnimationState function for the same mesh.
 

==SetMeshAnimationState==
{{MethodHeader|public native void SetMeshAnimationState(string mesh, bool state)}}
;Parameters
*'''mesh''' = the name of the mesh or submesh container which includes the animation file to be played.
*'''state''' = the direction in which the file is to be played, true for forwards, false for backwards.
;Returned Value
*None
;Syntax
SetMeshAnimationState("door",true); // opens the door
SetMeshAnimationState("door",false); // closes the door
;Notes
*This method plays animations and is best suited to those which have defined start and end points such as the opening and closing of a gate or door.
*If ''state'' is true the animation plays forwards from its current position to the last frame. If the current position is already at the last frame the call has no effect.
*If ''state'' is false the animation plays backwards from its current position to the first frame. If the current position is already at the first frame the call has no effect.
 

==SetMeshVisible==
{{MethodHeader|public native void SetMeshVisible(string mesh, bool visible, float fadeDuration)}}
;Parameters
*'''mesh''' = the name of the mesh or submesh to be displayed.
*'''visible''' = true to show the mesh, false to hide it.
*'''fadeDuration''' = period in seconds during which mesh visibility will be faded in or out.
;Returned Value
*None
;Syntax
SetMeshVisible("driver", false, 1.0);
;Notes
*If fadeDuration is 0.0 the mesh transition will be instantaneous.
 

==SetTextureSelfIllumination==
{{MethodHeader|public native void SetTextureSelfIllumination(string texture, float r, float g, float b)}}
;Parameters
*'''texture''' = root name of ''*.texture.text'' file to query.
*'''r,g,b''' = red green and blue components of self illumination value to apply.
;Returned Value
*None
;Syntax
SetTextureSelfIllumination("interior",0.5,0.5,0.5);
;Notes
*Applies a [[material emissive color]] to materials that use the texture, using the red, green and blue components specified.
*Compatibility warning: Use of this function is not recommended, it may become non-functional in future Trainz versions.
 

==StartMeshAnimationLoop==
{{MethodHeader|public native void StartMeshAnimationLoop(string mesh)}}
;Parameters
*'''mesh''' = the name of the mesh or submesh container which includes the animation file to be played.
;Returned Value
*None
;Syntax
StartMeshAnimationLoop("windmill");
;Notes
*This method plays animations and is best suited to those which are designed to run in a continuous loop.
*The speed of the animation can be altered using [[#SetMeshAnimationSpeed|SetMeshAnimationSpeed()]]
*Using [[#SetMeshAnimationSpeed|SetMeshAnimationSpeed()]] with a negative value will cause the animation to play in reverse.
*[[#StopMeshAnimation|StopMeshAnimation()]] will halt the animation.
 

==StopMeshAnimation==
{{MethodHeader|public native void StopMeshAnimation(string mesh)}}
;Parameters
*'''mesh''' = the name of the mesh or submesh container which includes the animation file to be stopped.
;Returned Value
*None
;Syntax
StopMeshAnimation("default");
;Notes
*Turns animation off for the specified mesh.
 

==SwapTextureOnMesh==
{{MethodHeader|public native void SwapTextureOnMesh(string mesh, string oldTexture, string newTexture)}}
;Parameters
*'''mesh''' = the name of the mesh or submesh container which includes the texture to be changed.
*'''oldTexture''' = the original ''*.texture.txt'' file to use as the source of the transition.
*'''newTexture''' = the new ''*.texture.txt'' file to apply.
;Returned Value
*None
;Syntax
SwapTextureOnMesh("left-passenger-door","gwr","lms");
;Notes
*'''Obsolete: Use SetFXTextureReplacementTexture instead.'''
*Swap one texture against another texture on specified mesh.
*Similar to texture-replacement effects, but without the need for an extra texture asset.
*'''possible bug''' Texture names in the .im file must be lower case for this function to work properly.
 

==Code Examples==

==Related Methods==

==Categories==
[[Category:Script Class]]

Class MeshObject

2020-03-02T23:34:22Z

Gdennish: Added SetFXTextureReplacementTexture

*[[TrainzScript Language Reference|API Hierarchy]]
**[[Class GSObject|GSObject]]
***[[Class GameObject|GameObject]]
****[[Class PropertyObject|PropertyObject]]
****[[Class TrainzGameObject|TrainzGameObject]]
*****MeshObject
 

This is a base class for [[class Asset|Asset]] based game objects that have meshes, effects, animations and particles. Interface methods to deal with these are provided so things like showing or hiding a mesh, attaching a mesh to an attachment point or controlling an animation can be done from a script.

For animation Trainz interpolates between key frames. This means an intermediate animation frame is calculated dynamically to be-in-synch with the game's framerate.

Trainzscript is an interpreted scripting language intended to be used to monitor and react to events in the Trainz world, not to perform sophisticated real-time animation tasks. Using a script to start an animation in response to an event in a thread is reasonable. However trying to control animation tightly down to short intervals is likely to provide unsatisfactory results and to adversely affect overall performance of the game.

==MeshObject Messages==
Messages related to MeshObject assets:
*[[Animation-Event Message]]
*[[pfx Message]]
 

==GetFXAttachment==
{{MethodHeader|public native MeshObject GetFXAttachment(string effect)}}
;Parameters
*'''effect''' = name of the mesh effect to query.
;Returned Value
*Returns a reference to the MeshObject currently attached to the named effect.
;Syntax
MeshObject attachment = GetFXAttachment("coupler");
;Notes
*The method returns null if the effect is unoccupied.
 

==GetMeshAnimationFrame==
{{MethodHeader|public native float GetMeshAnimationFrame(string mesh)'''}}
;Parameters
*'''mesh''' = the name of the mesh or submesh container which includes the animation file to be queried.
;Returned Value
*Current fame of the animation file within the specified mesh container.
;Syntax
float height = GetMeshAnimationFrame("zPosition")
;Notes
*Note that the returned value is likely to be an interpreted floating point value.
 

==GetMeshAnimationFrameCount==
{{MethodHeader|public native float GetMeshAnimationFrameCount(string mesh)}}
;Parameters
*'''mesh''' = the name of the mesh or submesh container which includes the animation file to be queried.
;Returned Value
*The number of frames in the specified animation.
;Syntax
float positions = GetMeshAnimationFrameCount("lever");
;Notes
*Note that the returned value is a float rather than an integer.
 

==GetTextureSelfIlluminationState==
{{MethodHeader|public native bool GetTextureSelfIlluminationState(string texture)'''}}
;Parameters
*'''texture''' = root name of ''*.texture.text'' file to query.
;Returned Value
*Returns true if the specified texture has self illumination set.
;Syntax
bool isEmissive = GetTextureSelfIlluminationState("texture");
;Notes
*Compatibility warning: Use of this function is not recommended, it may become non-functional in future Trainz versions.
 

==HasMesh==
{{MethodHeader|public native bool HasMesh(string mesh)}}
;Parameters
*'''mesh''' = the name of the mesh or submesh to be queried.
;Returned Value
*None
;Syntax
if (HasMesh("ventilation")) StartMeshAnimationLoop("fans");
;Notes
*
 

==SetFXAnimationState==
{{MethodHeader|public native void SetFXAnimationState(string effect, bool state)}}
;Parameters
*'''effect''' = name of attached-animation effect containing the animation to play.
*'''state''' = true to start the animation loop, false to stop.
;Returned Value
*None
;Syntax
if (gateClosed) SetFXAnimationState("gate",false);
;Notes
 

==SetFXAttachment==
{{MethodHeader|public native MeshObject SetFXAttachment(string effect, Asset asset)'''}}
;Parameters
*'''effect''' = effect containing the attachment to be manipulated.
*'''asset''' = mesh asset to attach to the effect. If asset is null any existing asset will be removed and nothing will be added.
;Returned Value
*Returns a reference to the MeshObject which has been attached to the named effect. If the mesh asset isn't "kind mesh", returns null.
;Syntax
MeshObject lamp = SetFXAttachment("lamp0",redlamp);
;Notes
*Returns null if the effect is unoccupied when the method returns.
 

==SetFXCoronaTexture==
{{MethodHeader|public native void SetFXCoronaTexture(string effect, Asset texture)}}
;Parameters
*'''effect''' = effect containg the corona to be manipulated.
*'''asset''' = corona texture asset to attach to the effect. If asset is null the corona will be turned off.
;Returned Value
*None
;Syntax
SetFXCoronaTexture("stopLight",redCorona);
;Notes
*Other corona parameters such as frequency and size are defined in ''config.txt'' and cannot be altered by script code.
 

==SetFXNameText==
{{MethodHeader|public native void SetFXNameText(string effect, string text)}}
;Parameters
*'''effect''' = effect containg the name effect to be changed.
*'''text''' = new string value.
;Returned Value
*None
;Syntax
SetFXNameText("home","Shangri-La");
;Notes
*Method will not accept an empty string in the ''text'' parameter.
 

==SetFXTextureReplacement==
{{MethodHeader|public native void SetFXTextureReplacement(string effect, Asset textureGroup, int index)}}
;Parameters
*'''effect''' = texture-replacement effect to be changed.
*'''textureGroup''' = reference to texture group asset which is the source of the texture to be applied.
*'''index''' = index into ''textures'' table of texture-group indicating which texture to apply.
;Returned Value
*None
;Syntax
SetFXTextureReplacement("load",loadTextures,5); // applies texture 5 from texture-group
SetFXTextureReplacement("load",null,0); // clears the effect, reinstating the texture defined in the asset.
;Notes
*Use null in the textureGroup parameter to turn texture replacement off.
 

==SetMesh==
{{MethodHeader|public native void SetMesh(string mesh, float fadeDuration)}}
;Parameters
*'''mesh''' = the name of the mesh or submesh to be displayed.
*'''fadeDuration''' = period in seconds during which mesh visibility will be faded in or out.
;Returned Value
*None
;Syntax
SetMesh("default",0.5);
;Notes
*Shows the specified mesh and hides all other meshes.
*If fadeDuration is 0.0 the mesh transition will be instantaneous.
 

==SetMeshAnimationFrame==
{{MethodHeader|public native void SetMeshAnimationFrame(string mesh, float frame) 
public native void SetMeshAnimationFrame(string mesh, float frame, float period)}}
;Parameters
*'''mesh''' = the name of the mesh or submesh container which includes the animation file to be manipulated.
*'''frame''' = the frame position to which the animation is to be moved, this may be an interpolated value.
*'''period''' = the period over which the animation will be moved from its current position to the newly specified point.
;Returned Value
*None
;Syntax
SetMeshAnimationFrame("default",5.0); // move the animation to frame 5 instantaneously
SetMeshAnimationFrame("default",5.0,2.0); // move the animation to frame 5 over 2 seconds
;Notes
*Moves the specified animation to the specified frame.
*For the first variant the transition is instant.
*For the second variant the transition will complete during the specified period.
 

==SetMeshAnimationSpeed==
{{MethodHeader|public native void SetMeshAnimationSpeed(string mesh, float speed)}}
;Parameters
*'''mesh''' = the name of the mesh or submesh container which includes the animation file to be manipulated.
*'''speed''' = multiplication factor to apply to the original animation speed.
;Returned Value
*None
;Syntax
SetMeshAnimationSpeed("fans",2.0); // run fans at double speed
SetMeshAnimationSpeed("fans",-1.0); // run fans backwards at original speed
;Notes
*Modifies the speed at which the animation is played.
*The original speed is multiplied by the new speed factor.
*Use negative values to make the animation run in reverse.
*It is ''not'' compatible with SetMeshAnimationState function for the same mesh.
 

==SetMeshAnimationState==
{{MethodHeader|public native void SetMeshAnimationState(string mesh, bool state)}}
;Parameters
*'''mesh''' = the name of the mesh or submesh container which includes the animation file to be played.
*'''state''' = the direction in which the file is to be played, true for forwards, false for backwards.
;Returned Value
*None
;Syntax
SetMeshAnimationState("door",true); // opens the door
SetMeshAnimationState("door",false); // closes the door
;Notes
*This method plays animations and is best suited to those which have defined start and end points such as the opening and closing of a gate or door.
*If ''state'' is true the animation plays forwards from its current position to the last frame. If the current position is already at the last frame the call has no effect.
*If ''state'' is false the animation plays backwards from its current position to the first frame. If the current position is already at the first frame the call has no effect.
 

==SetMeshVisible==
{{MethodHeader|public native void SetMeshVisible(string mesh, bool visible, float fadeDuration)}}
;Parameters
*'''mesh''' = the name of the mesh or submesh to be displayed.
*'''visible''' = true to show the mesh, false to hide it.
*'''fadeDuration''' = period in seconds during which mesh visibility will be faded in or out.
;Returned Value
*None
;Syntax
SetMeshVisible("driver", false, 1.0);
;Notes
*If fadeDuration is 0.0 the mesh transition will be instantaneous.
 

==SetTextureSelfIllumination==
{{MethodHeader|public native void SetTextureSelfIllumination(string texture, float r, float g, float b)}}
;Parameters
*'''texture''' = root name of ''*.texture.text'' file to query.
*'''r,g,b''' = red green and blue components of self illumination value to apply.
;Returned Value
*None
;Syntax
SetTextureSelfIllumination("interior",0.5,0.5,0.5);
;Notes
*Applies a [[material emissive color]] to materials that use the texture, using the red, green and blue components specified.
*Compatibility warning: Use of this function is not recommended, it may become non-functional in future Trainz versions.
 

==StartMeshAnimationLoop==
{{MethodHeader|public native void StartMeshAnimationLoop(string mesh)}}
;Parameters
*'''mesh''' = the name of the mesh or submesh container which includes the animation file to be played.
;Returned Value
*None
;Syntax
StartMeshAnimationLoop("windmill");
;Notes
*This method plays animations and is best suited to those which are designed to run in a continuous loop.
*The speed of the animation can be altered using [[#SetMeshAnimationSpeed|SetMeshAnimationSpeed()]]
*Using [[#SetMeshAnimationSpeed|SetMeshAnimationSpeed()]] with a negative value will cause the animation to play in reverse.
*[[#StopMeshAnimation|StopMeshAnimation()]] will halt the animation.
 

==StopMeshAnimation==
{{MethodHeader|public native void StopMeshAnimation(string mesh)}}
;Parameters
*'''mesh''' = the name of the mesh or submesh container which includes the animation file to be stopped.
;Returned Value
*None
;Syntax
StopMeshAnimation("default");
;Notes
*Turns animation off for the specified mesh.
 

==SetFXTextureReplacementTexture==
{{MethodHeader|public native void SetFXTextureReplacementTexture(string effectName, string textureName)}}
;Parameters
*'''effectName''' = the name of the texture-replacement effect that is in the effects container of the mesh.
*'''textureName''' = the ''*.texture.txt'' file that will replace the current texture being used on the mesh.
;Returned Value
*None
;Syntax
SetFXTextureReplacementTexture("fk_parameter","lms_p3_fk_body/fk_parameter.texture");
;Notes
*This should replace any instance of SwapTextureOnMesh.
*Unlike SwapTextureOnMesh, there is no need to mention what the previous texture being used was. Simply telling Trainz to load the new texture is all that is needed for this to work.
*Swap one texture against another texture on specified mesh.
*Similar to texture-replacement effects, but without the need for an extra texture asset.
 

==SwapTextureOnMesh==
{{MethodHeader|public native void SwapTextureOnMesh(string mesh, string oldTexture, string newTexture)}}
;Parameters
*'''mesh''' = the name of the mesh or submesh container which includes the texture to be changed.
*'''oldTexture''' = the original ''*.texture.txt'' file to use as the source of the transition.
*'''newTexture''' = the new ''*.texture.txt'' file to apply.
;Returned Value
*None
;Syntax
SwapTextureOnMesh("left-passenger-door","gwr","lms");
;Notes
*'''Obsolete: Use SetFXTextureReplacementTexture instead.'''
*Swap one texture against another texture on specified mesh.
*Similar to texture-replacement effects, but without the need for an extra texture asset.
*'''possible bug''' Texture names in the .im file must be lower case for this function to work properly.
 

==Code Examples==

==Related Methods==

==Categories==
[[Category:Script Class]]

Adding the TRS19 F7 Cabin to your Asset

2019-11-24T21:39:32Z

Gdennish: /* Modifying the Nose color */

The new TRS19 EMD F7 cabin has the ability to change the color of the nose to match the road name of your locomotive asset. Changing the color of the nose is as simple as adding a few lines into the config of your locomotive of choice.

[[File:F7IntroPage.png|800px]]

== Adding the Cab to your Asset ==

To begin, open the config of the locomotive you wish to have a custom nose color for. For this tutorial, we will be using <kuid2:999999:2222:1> 1 Hot Rod Special F7 from the DLS. It is recommended to open the config in a superior notepad program such as Notepad++ to preserve formatting. When the config for the Hot Rod F7 is opened, it looks something like this:

kuid <kuid2:999999:2222:1>
username "1 Hot Rod Special F7"
kind "traincar"
trainz-build 3.5
engine 1
enginespec <kuid:999999:42004250>
enginesound <kuid:-1:42003000>
hornsound <kuid:37581:1234>
interior <kuid:217537:220>
mesh-table
{
default
{
mesh "f7_hotrod_body/f7_hotrod_body.im"
auto-create 1
}

shadow
{
mesh "f7_hotrod_shadow/f7_hotrod_shadow.im"
}
}
bogeys
{
0
{
bogey <kuid:999999:100100>
reversed 0
}
}
mass 100000
company "Auran Brew Crew"
fonts 0
smoke_shade 0.5
smoke_random 2.6
smoke_slowlife 5
smoke_fastlife 4
smoke_height 2.3
smoke_fastspeed 100
category-class "AC"
category-era "2000s"
category-region "AU"
description ""
author "Brew Crew Productions"
organisation "Auran Games Pty. Ltd."
contact-website "www.virtualtrainz.com"
contact-email "helpdesk@auran.com"
thumbnails
{
0
{
image "$screenshot$.jpg"
width 240
height 180
}
1
{
image "f7_hotrod_art\f7_hotrod_art_icon.texture"
width 128
height 64
}
}
kuid-table
{
0 <kuid:-1:101212>
1 <kuid:-1:42003000>
2 <kuid:-1:42003101>
3 <kuid:999999:100100>
4 <kuid:999999:42004250>
}

The first thing to change is the interior kuid to reference the proper F7 cab. If your locomotive is right-hand drive and uses MPH, use the following kuid:
<kuid:-25:1308>

Change the following line from:
interior <kuid:217537:220>
to:
interior <kuid:-25:1308>

The next step is to add an extensions table. Copy and paste the following code into your config:

extensions
{
f7cab_parameters
{
nosecolor "XXX"
}
}

The placement of this code does not matter. I placed it directly under the interior tag line and above the mesh table to make editing the extensions easier to edit in the future.

kuid <kuid2:999999:2222:1>
username "1 Hot Rod Special F7"
kind "traincar"
trainz-build 3.5
engine 1
enginespec <kuid:999999:42004250>
enginesound <kuid:-1:42003000>
hornsound <kuid:37581:1234>
interior <kuid:217537:220>
extensions
{
f7cab_parameters
{
nosecolor "XXX"
}
}
mesh-table
{
default
{
mesh "f7_hotrod_body/f7_hotrod_body.im"
auto-create 1
}

shadow
{
mesh "f7_hotrod_shadow/f7_hotrod_shadow.im"
}
}

....

== Modifying the Nose color ==

The final step is to change "XXX" to an appropriate string. Use the first column in the following table to determine the proper string to replace "XXX" with. The strings are case sensitive, so make sure it matches the table or else the cabin will default to black.

By default, the F7 Cab supports these pre-built liveries:
{| class="wikitable"
|+Supported Road names
|-
|String '''(case sensitive!)'''
|Color
|Roadname
|-
|red
|Red
|Generic Red
|-
|superchief
|Red with Yellow Stripe
|ATSF Warbonnet
|-
|darkblue
|Dark Blue with Yellow Stripe
|ATSF Blue Warbonnet
|-
|green
|Green
|Burlington Northern
|-
|orange
|Orange/Green
|Great Northern
|-
|yellow
|Yellow
|North Western/Alaska
|-
|lightgrey
|Light Grey
|Canadian Pacific
|-
|blackred
|Red with black nose top
|Canadian National / CP Rail
|-
|winetrain
|Green/Gold
|Nappa Valley Wine Train
|-
|silver
|Silver/Black
|Southern Pacific
|-
|unionpacific
|Yellow with Green nose top
|Union Pacific
|-
|darkgrey
|Dark Grey with Dark Blue nose top
|Baltimore and Ohio
|-
|amtrakphase1
|Black/Red/White
|Amtrak Phase I
|-
|hotrod
|Black with Flames
|Hot Rod Special
|-
|prr_red_5stripe
|PRR Tuscan with 5 Stripe
|Pennsylvania Railroad
|-
|prr_red_1stripe
|PRR Tuscan with 1 Stripe
|Pennsylvania Railroad
|-
|prr_green_5stripe
|PRR Brunswick with 5 Stripe
|Pennsylvania Railroad
|-
|prr_green_1stripe
|PRR Brunswick with 1 Stripe
|Pennsylvania Railroad
|-
|southernpacific_orange
|Daylight Paint Scheme
|Southern Pacific
|}

The final config would look something like this:

kuid <kuid2:999999:2222:1>
username "1 Hot Rod Special F7"
kind "traincar"
trainz-build 3.5
engine 1
enginespec <kuid:999999:42004250>
enginesound <kuid:-1:42003000>
hornsound <kuid:37581:1234>
interior <kuid:217537:220>
extensions
{
f7cab_parameters
{
nosecolor "hotrod"
}
}
mesh-table
{
default
{
mesh "f7_hotrod_body/f7_hotrod_body.im"
auto-create 1
}

shadow
{
mesh "f7_hotrod_shadow/f7_hotrod_shadow.im"
}
}
bogeys
{
0
{
bogey <kuid:999999:100100>
reversed 0
}
}
mass 100000
company "Auran Brew Crew"
fonts 0
smoke_shade 0.5
smoke_random 2.6
smoke_slowlife 5
smoke_fastlife 4
smoke_height 2.3
smoke_fastspeed 100
category-class "AC"
category-era "2000s"
category-region "AU"
description ""
author "Brew Crew Productions"
organisation "Auran Games Pty. Ltd."
contact-website "www.virtualtrainz.com"
contact-email "helpdesk@auran.com"
thumbnails
{
0
{
image "$screenshot$.jpg"
width 240
height 180
}
1
{
image "f7_hotrod_art\f7_hotrod_art_icon.texture"
width 128
height 64
}
}
kuid-table
{
0 <kuid:-1:101212>
1 <kuid:-1:42003000>
2 <kuid:-1:42003101>
3 <kuid:999999:100100>
4 <kuid:999999:42004250>
}

==Return to Index==

[[HowToGuides|<< How To Guides]]

[[Category:How-to guides]]

Adding the TRS19 F7 Cabin to your Asset

2019-11-23T01:22:21Z

Gdennish: Created page with "The new TRS19 EMD F7 cabin has the ability to change the color of the nose to match the road name of your locomotive asset. Changing the color of the nose is as simple as addi..."

The new TRS19 EMD F7 cabin has the ability to change the color of the nose to match the road name of your locomotive asset. Changing the color of the nose is as simple as adding a few lines into the config of your locomotive of choice.

[[File:F7IntroPage.png|800px]]

== Adding the Cab to your Asset ==

To begin, open the config of the locomotive you wish to have a custom nose color for. For this tutorial, we will be using <kuid2:999999:2222:1> 1 Hot Rod Special F7 from the DLS. It is recommended to open the config in a superior notepad program such as Notepad++ to preserve formatting. When the config for the Hot Rod F7 is opened, it looks something like this:

kuid <kuid2:999999:2222:1>
username "1 Hot Rod Special F7"
kind "traincar"
trainz-build 3.5
engine 1
enginespec <kuid:999999:42004250>
enginesound <kuid:-1:42003000>
hornsound <kuid:37581:1234>
interior <kuid:217537:220>
mesh-table
{
default
{
mesh "f7_hotrod_body/f7_hotrod_body.im"
auto-create 1
}

shadow
{
mesh "f7_hotrod_shadow/f7_hotrod_shadow.im"
}
}
bogeys
{
0
{
bogey <kuid:999999:100100>
reversed 0
}
}
mass 100000
company "Auran Brew Crew"
fonts 0
smoke_shade 0.5
smoke_random 2.6
smoke_slowlife 5
smoke_fastlife 4
smoke_height 2.3
smoke_fastspeed 100
category-class "AC"
category-era "2000s"
category-region "AU"
description ""
author "Brew Crew Productions"
organisation "Auran Games Pty. Ltd."
contact-website "www.virtualtrainz.com"
contact-email "helpdesk@auran.com"
thumbnails
{
0
{
image "$screenshot$.jpg"
width 240
height 180
}
1
{
image "f7_hotrod_art\f7_hotrod_art_icon.texture"
width 128
height 64
}
}
kuid-table
{
0 <kuid:-1:101212>
1 <kuid:-1:42003000>
2 <kuid:-1:42003101>
3 <kuid:999999:100100>
4 <kuid:999999:42004250>
}

The first thing to change is the interior kuid to reference the proper F7 cab. If your locomotive is right-hand drive and uses MPH, use the following kuid:
<kuid:-25:1308>

Change the following line from:
interior <kuid:217537:220>
to:
interior <kuid:-25:1308>

The next step is to add an extensions table. Copy and paste the following code into your config:

extensions
{
f7cab_parameters
{
nosecolor "XXX"
}
}

The placement of this code does not matter. I placed it directly under the interior tag line and above the mesh table to make editing the extensions easier to edit in the future.

kuid <kuid2:999999:2222:1>
username "1 Hot Rod Special F7"
kind "traincar"
trainz-build 3.5
engine 1
enginespec <kuid:999999:42004250>
enginesound <kuid:-1:42003000>
hornsound <kuid:37581:1234>
interior <kuid:217537:220>
extensions
{
f7cab_parameters
{
nosecolor "XXX"
}
}
mesh-table
{
default
{
mesh "f7_hotrod_body/f7_hotrod_body.im"
auto-create 1
}

shadow
{
mesh "f7_hotrod_shadow/f7_hotrod_shadow.im"
}
}

....

== Modifying the Nose color ==

The final step is to change "XXX" to an appropriate string. Use the right column in the following table to determine the proper string to replace "XXX" with. The strings are case sensitive, so make sure it matches the table or else the cabin will default to black.

By default, the F7 Cab supports these pre-built liveries:
{| class="wikitable"
|+Supported Road names
|-
|String '''(case sensitive!)'''
|Color
|Roadname
|-
|red
|Red
|Generic Red
|-
|superchief
|Red with Yellow Stripe
|ATSF Warbonnet
|-
|darkblue
|Dark Blue with Yellow Stripe
|ATSF Blue Warbonnet
|-
|green
|Green
|Burlington Northern
|-
|orange
|Orange/Green
|Great Northern
|-
|yellow
|Yellow
|North Western/Alaska
|-
|lightgrey
|Light Grey
|Canadian Pacific
|-
|blackred
|Red with black nose top
|Canadian National / CP Rail
|-
|winetrain
|Green/Gold
|Nappa Valley Wine Train
|-
|silver
|Silver/Black
|Southern Pacific
|-
|unionpacific
|Yellow with Green nose top
|Union Pacific
|-
|darkgrey
|Dark Grey with Dark Blue nose top
|Baltimore and Ohio
|-
|amtrakphase1
|Black/Red/White
|Amtrak Phase I
|-
|hotrod
|Black with Flames
|Hot Rod Special
|-
|prr_red_5stripe
|PRR Tuscan with 5 Stripe
|Pennsylvania Railroad
|-
|prr_red_1stripe
|PRR Tuscan with 1 Stripe
|Pennsylvania Railroad
|-
|prr_green_5stripe
|PRR Brunswick with 5 Stripe
|Pennsylvania Railroad
|-
|prr_green_1stripe
|PRR Brunswick with 1 Stripe
|Pennsylvania Railroad
|-
|southernpacific_orange
|Daylight Paint Scheme
|Southern Pacific
|}

The final config would look something like this:

kuid <kuid2:999999:2222:1>
username "1 Hot Rod Special F7"
kind "traincar"
trainz-build 3.5
engine 1
enginespec <kuid:999999:42004250>
enginesound <kuid:-1:42003000>
hornsound <kuid:37581:1234>
interior <kuid:217537:220>
extensions
{
f7cab_parameters
{
nosecolor "hotrod"
}
}
mesh-table
{
default
{
mesh "f7_hotrod_body/f7_hotrod_body.im"
auto-create 1
}

shadow
{
mesh "f7_hotrod_shadow/f7_hotrod_shadow.im"
}
}
bogeys
{
0
{
bogey <kuid:999999:100100>
reversed 0
}
}
mass 100000
company "Auran Brew Crew"
fonts 0
smoke_shade 0.5
smoke_random 2.6
smoke_slowlife 5
smoke_fastlife 4
smoke_height 2.3
smoke_fastspeed 100
category-class "AC"
category-era "2000s"
category-region "AU"
description ""
author "Brew Crew Productions"
organisation "Auran Games Pty. Ltd."
contact-website "www.virtualtrainz.com"
contact-email "helpdesk@auran.com"
thumbnails
{
0
{
image "$screenshot$.jpg"
width 240
height 180
}
1
{
image "f7_hotrod_art\f7_hotrod_art_icon.texture"
width 128
height 64
}
}
kuid-table
{
0 <kuid:-1:101212>
1 <kuid:-1:42003000>
2 <kuid:-1:42003101>
3 <kuid:999999:100100>
4 <kuid:999999:42004250>
}

==Return to Index==

[[HowToGuides|<< How To Guides]]

[[Category:How-to guides]]

File:F7IntroPage.png

2019-11-23T01:13:44Z

Gdennish:

HowTo/Build a cab interior

2019-11-05T20:15:37Z

Gdennish: Added visual representation of a pull rope type

Trainz uses an [[KIND_Interior|interior]] object to represent a locomotive cab, or view from another vehicle, e.g. a passenger coach, brake van or caboose. Interiors can also be attached to some non-train assets. For this howto, I am going to assume that we are creating a traincar interior, and focus primarily on a cab interior for a diesel or electric locomotive.

=Basic structure=

The basic structure of a cab is quite similar to a number of different assets. You will have a main mesh with a number of attached sub-meshes, which are arranged using a [[%22mesh-table%22_container_(interior_version)|mesh-table]].

The main cab mesh typically consists of the interior walls, roof and floor of the cab, the control desk or stand, all furniture or other static objects visible inside the cab, and also all parts of the locomotive exterior that are visible from inside the cab - e.g. the top of any projecting nose below the cab windows. Remember to consider the sightlines out of rear windows too for visible bodywork panels - the user can move around the cab and rotate the camera to any angle. Users are not restricted to looking forward out of the front windows only.

=Artwork considerations=

There are some differences in style between the construction of an interior object and a typical trainz object.

Except in very specific circumstances, there will not be more than one interior object in existence at any time, and that interior is always viewed from very close range - the user is inside it. Because of this, interiors are typically modelled with a high polygon count and with high resolution textures, to give an impressive visual feel. LOD is not used, as the user never gets far enough away from the interior for LOD techniques to have worthwhile benefit.

Trainz lights interior objects differently to map objects like buildings and other scenery - the main illumination is ambient, not directional. (A steam loco does have a directional light coming from the firebox, but a diesel or electric cab typically has no directional light inside, and relies entirely on ambient illumination).

With ambient illumination, effects such as normal and specular mapping do not have much (if any) effect. Because of this, more effort needs to be put into the diffuse texture for a cab interior than would normally be applied to Trainz objects. Drawing or baking shadows and other effects into the diffuse textures is required to produce a nice looking cab interior.

An example cab would be the [[File:PB_interior.rar]]

=A basic config file=

The minimal required config for an interior to show in-game is:

kind interior
kuid <kuid2:YOUR:KUID:HERE>
trainz-build 2.9
username "Your interior name here"
category-class ZI

mesh-table
{
default
{
mesh "your_interior_mesh_name.im"
auto-create 1
}
}

Note: There are also other base tags that should be added that are common to all asset types - e.g. the download station will require a valid thumbnails container before the asset can be uploaded. See the documentation for [[KIND TrainzBaseSpec]] for details of tags which apply to all trainz assets. Depending on which Trainz version you have and which trainz-build number you have specified, some of these may be required - content manager will tell you what is required, listing missing tags as errors.

==camera positions==

If we load a cab up with that config file, we will note that the view is not particularly appealing. Chances are we're right down near the floor. To fix this, we need to define some default positions for camera views. This is done with the [[%22cameralist%22_Container|cameralist container]] and the [[KIND_Interior#cameradefault|cameradefault]] tag.
Add the following to your config.txt file:

cameralist
{
camera0 0,0,2,0,0
}

cameradefault 0

The cameralist container can contain any number of cameras, but they must be numbered sequentially and start at zero.

The five numbers are the X, Y and Z coordinates of the camera in metres relative to the 0,0,0 point of the interior mesh, and the Yaw and Pitch in radians. Luckily you don't have to work these values out from scratch - add the line "-freeintcam" to your trainzoptions.txt file, and you can move the camera about in the cab with the mouse and keyboard, and the precise position will be displayed in the bottom right corner.

When you have found a position you like, write the numbers down. When you've got a good selection of positions recorded, add them to the cameralist container.

You may wish to return to this and tweak the values later once all the controls are in place - but it's handy to have a good starting position for the camera while testing.

=Cab controls=

A locomotive cab interior needs working cab controls. What fun would sitting in the drivers seat be without being able to pull on the levers, change the switches, and watch the gauges and dials move?

The moving part of each lever, switch, gauge or dial is created as a separate mesh, which is then attached to the cab with an attachment point. (The static part, e.g. guide rails for levers, should be part of the cab mesh itself).

==Lever==

The lever is the basic input device in a cab. It is based on rotational movement, and any object that requires rotational movement (e.g. a wheel or ring) can be implemented as a lever.

If you actually want linear movement, you can still use a lever - just move the attachment point a long way away - e.g. 10 or 20 metres away from the control. The resulting small arc will not be noticable over the length of movement. As an example, sliding windows in Trainz cabs have been implemented as levers "attached" something like 10 or 20 metres out to the side of the vehicle for a long time. (The exception to this is a horn pull rope - trainz provides a control specifically for this purpose).

You will need to create the lever in your modelling program aligned correctly - the rotation needs to be around the Z axis, and main part of the object will point along the Y axis.

When adding the attachment point to the main mesh, align it so the Z axis is the axis of rotation. It is common to point the Y axis at the default position - e.g. levers in the 'off' or 'neutral' position, and needles pointing to zero. This is not strictly required, as the range of movement can be adjusted at both ends, but it provides a handy reference when creating the config file.

It is worth noting that you can reuse a mesh for multiple attachments. This is particularly useful for switches, as identical appearance switches are often used repeatedly in a cab for different purposes.

===Throttle Lever===

A good example of a standard lever in use is a locomotive throttle control. A typical US diesel throttle has 9 notched positions (from 0 to 8 inclusive).

As noted above, the lever is created in the modelling package so it points along the Y axis and the axis of rotation is along the Z axis. The attachment point is added to the cab interior mesh at the correct position, and rotated so the Z axis is aligned with the axis of rotation, and the Y axis points to the default position.

Now we need to add an entry to the config file to add our throttle lever.

Into the mesh table, add an entry like this:

throttle_lever
{
kind "lever"
mesh "throttle_lever.im"
att "a.throttle_lever"
limits 0,8
angles 0,1.57
notches 0,0.125,0.25,0.375,0.5,0.625,0.75,0.875,1
notchheight 1,2,2,2,2,2,2,2,1
radius 0.35
auto-create 1
att-parent "default"
}

... remember to set your attachment point and mesh name correctly.

The 'angles' line defines how far the control rotates. It is in radians - there are 2 x Pi (6.28) radians in a complete circle. My default of 1.57 will give you about 90 degrees of rotation, in the positive direction. Adjust this number to get the control to rotate the correct amount. You should be able to work out the number you need in your modelling program by using the rotate tool on the attachment point, and recording the amount of rotation required to move to the intended maximum location. It should not require significant trial and error.

The 'radius' line defines the position of the notch position overlay and the text label. It is in metres. If the overlay is too close in, increase this number. If it is too far out, decrease it.

If the lever is the wrong way round (notch 8 is at the wrong end), swap the numbers in the 'angles' tag over, so the higher one is first.

If the lever moves the wrong way when you drag it with the mouse (i.e. it goes left in response to a right drag), add the line:
mousespeed -1
This will invert the mouse movement.

The fact we called this lever "throttle_lever" means it will be used to control the throttle by the default cab script.

So what happens if we wanted a different number of notches? Below is an example of a throttle which has 22 notches. The second value in the 'limits' tag has been edited to return up to notch 22, and more entries have been added to the 'notches' and 'notchheight' tags:

throttle_lever
{
kind "lever"
mesh "throttle_lever.im"
att "a.throttle_lever"
limits 0,22
angles 0,0.94
notches 0,0.045,0.091,0.136,0.182,0.227,0.273,0.318,0.364,0.409,0.455,0.5,0.545,0.591,0.636,0.682,0.727,0.773,0.818,0.864,0.909,0.955,1
notchheight 1,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,1
radius 0.35
auto-create 1
att-parent "default"
}

===Reverser Lever===

The reverser lever is created in a similar manner to throttle lever. The mesh table entry for this will look like:

reverser_lever
{
kind "lever"
mesh "reverser_lever.im"
att "a.reverser_lever"
limits 0,2
angles -0.79,0.79
notches 0,0.5,1
notchheight 1,1,1
radius 0.25
auto-create 1
att-parent "default"
}

In this case, because the 'angles' entry has a range both positive and negative, the lever can move in both directions relative to the attachment point. The game will set the default position to neutral (1), so if you've lined up your attachment point at one end, don't worry - you can use angles which range from zero if you need to.

===Train Air Brake Lever===

There are two types of train air brake lever. A given locomotive only has one type - the brakes are either require manual lapping or are self-lapping. Use the appropriate name and configuration for the loco you are modelling.

====Manual Lapped Brakes====

The manual train brake lever has five positions numbered from zero to four, each one representing a different function. Those functions are Release, Lap, Application, Emergency and Handle Off respectively.

A lever for a manual lap train air brake is defined as follows:

trainbrakelap_lever
{
kind "lever"
mesh "train_brake_lap_lever.im"
att "a.train_brake_lap_lever"
limits 0,4
angles 0,0.94
notches 0,0.25,0.5,0.75,1
notchheight 1,1,1,1,1
radius 0.25
att-parent "default"
auto-create 1
}

In this case, the attachment for the lever has been created in the 'release' position. If it had been created in the 'handle off' position, the angle tag would have been more like:

angles -0.94,0

====Self Lapping Brakes====

A self lapping trainbrake lever has a number of primary notches similar to the manual lap train brake lever. However, instead of a 'lap' and 'apply' position, it has a grade of application between the 'initial' and 'full application' positions. An example of a self-lapping brake handle is this one:

trainbrake_lever
{
kind "lever"
mesh "train_brake_lever.im"
att "a.train_brake_lever"
limits 0,4
angles 0,0.94
notches 0,0.25,0.27,0.29,0.31,0.33,0.35,0.37,0.39,0.41,0.43,0.45,0.47,0.49,0.5,0.75,1
notchheight 1,1,2,2,2,2,2,2,2,2,2,2,2,2,1,1,1
radius 0.25
att-parent "default"
auto-create 1
}

In this case, there are 14 possible levels of brake application - initial at 0.25, 12 intermediate levels, and full application at 0.5. There is no restriction on the number of intermediate levels - if you are modelling a prototype brake handle with a specific number, you may create precisely that number of notches and arrange them between 0.25 and 0.5 as required.

===Combined throttle brake lever===

There is also another control option - a combined throttle brake lever. This type of control is often found on multiple unit trains. This control is split into two halves. The first half of the movement is an inverted throttle - i.e. max power at zero, no power at 0.5. The second half is an auto lapped train brake application, with 0.5 as release, and 1.0 as emergency. An example of how to configure a combined throttle and brake lever is below:

throttle_brake_lever
{
kind "lever"
mesh "throttle_brake_handle.im"
auto-create 1
att "a.throttle_brake_handle"
limits 0,16
angles 0.94,-0.94
notches 0,0.0625,0.125,0.1875,0.25,0.3125,0.375,0.4375,0.5,0.5625,0.625,0.6875,0.8125,0.75,0.875,0.9375,1
notchheight 1,2,2,2,2,2,2,2,1,2,2,2,2,2,2,2,1
att-parent "default"
radius 0.12
invert 1
}

Unfortunately, trains that use this type of control generally use blended and/or EP brakes, and this control uses the standard Trainz air brake, which operates in a distinctly different manner, and as a result, can feel very wrong for this control type. (See the section on scripting controls for how a better combined brake and throttle lever may be implemented).

==Pull lever==

This is a sprung lever. You pull on this lever to activate it, and when you let it go, it returns to the original position. This kind of action is commonly associated with a locomotive horn, and this is what I am using as an example:

horn
{
kind "pulllever"
mesh "horn.im"
att "a.horn"
auto-create 1
angles 0,-0.55
limits 0,1
mousespeed -1
radius -0.02
notches 0,1
notchheight 0,0
}

==Switch==

A switch is a lever that does not require the user to 'drag' it with the mouse - it operates on a click only. This is used for smaller controls that are 'on' or 'off', and do not have intermediate positions. Parameters are much like they are for a 'lever', only a switch should only have two notches - on and off.

Unfortunately, some things you'd normally associate with being a 'switch' (e.g. the headlight switch control) require mulitple positions, and will need to remain as a 'lever' in order to allow the player to set the correct position for the control.

An example of a switch would be:

switch1
{
kind "switch"
mesh "switch.im"
att "a.switch1"
limits 0,1
angles 1.4,0
notches 0,1
notchheight 0,0
}

As 'switch' was introduced in TS2009 SP2, interiors that use kind 'switch' controls should be marked trainz-build 3.1 or later in the config.txt.

==button==

A button is a momentary contact press-and-hold button. This is a brand new control added for TS12 patch 2, released end of june 2011. Content using this feature should have trainz-build 3.6 or later in the config.txt.

Finally this brings Trainz the "click to press", "hold to hold pressed", "let go to release" style momentary pushbutton.

button1
{
kind "button"
mesh "switch.im"
att "a.switch1"
limits 0,1
angles 0,0.1
notches 0,1
notchheight 0,0
}

==Pull rope==

This is a linear pull rope control. Unlike the rotating controls discussed previously, this control type moves the mesh linearly along the Z axis of the attachment. It behaves as you would expect from a suspended rope - click and drag to pull, let go to release. It will spring back to it's initial position in the same manner as kind 'pulllever'.

[[File:Pullropetype.png|800px]]]

horn
{
kind "pullrope"
mesh "horn_rope.im"
att "a.horn"
limits 0,1
angles 0.1,0
notches 0,1
notchheight 0,0
mousespeed -1
}

==needle==

A needle is the standard Trainz output device. Like the lever, it is based on rotational movement, and any gauge, dial, or other output device based on rotational movement can be implemented. Any static part of the gauge should be modelled as part of the cab, and only the moving part as part of the needle. Like the lever, the rotation will be around the Z axis of the needle, and it is common practice to point the point of the needle along the Y axis. Cabs often have a number of similar gauges, and re-using the same needle repeatedly in each gauge is a lot easier if this setup is done consistently.

As an example of a needle, here is a basic speedometer:

speedo_needle
{
kind "needle"
auto-create 1
mesh "speedo_needle.im"
att "a.speedo_needle"
limits 0,67.056
angles 0,4.712
}

The default cab script knows to move the "speedo_needle" object as the train speed changes, so simply by naming this control "speedo_needle", it has become a speedometer.

For a speedo, the 'limits' values will be the minimum and maximum reportable speed in m/s.

Creating other rotational gauges is similar - refer to the [[%22mesh-table%22_container_(interior_version)|mesh-table (interior version)]] documentation to see all the different values that Trainz can show by default.

==light==

Another common type of control is a light. This is created simply as a textured plane, which is either hidden or shown to represent light off or light on. It is attached as any other standard mesh attachment would be - there is no rotation to worry about here.

wheelslip_light
{
kind "light"
mesh "wheelslip_light.im"
att "a.wheelslip_light"
}

This light will be used to show wheelslip in a default cab.

==animated-lever==

If you want more complex movement than simple rotation, you have the option of animating the lever and using kind 'animated-lever'. This will use an animation you create in your modelling program to move the control about. An example of this is visible in the MN ACMU cab. (I've reduced the number of notches here for readability - the real one has 32, not 16).

throttle_lever
{
mesh "throttlehandle.im"
anim "throttlehandle.kin"
auto-create 1
att "a.throttlelever"
limits 0,16
notches 0,0.0625,0.125,0.1875,0.25,0.3125,0.375,0.4375,0.5,0.5625,0.625,0.6875,0.8125,0.75,0.875,0.9375,1
notchheight 1,2,2,2,2,2,2,2,1,2,2,2,2,2,2,2,1
att-parent "default"
kind "animated-lever"
test-collisions 0
mousespeed 1
}

Where the standard lever is rotated between it's angles to move from notch to notch, the animated-lever has it's animation played to the corresponding frame.

===collision-proxy===

Animated levers can be hard to grab hold of compared to normal levers. To get around this, an invisible mesh is used to show the game the range of movement the control has, and to allow the user to grab the lever more easily. This example again comes from the MN ACMU cab:

throttle-collision-box
{
mesh "throttlehandleselection.im"
att-parent "throttle_lever"
att "a.selection_box"
auto-create 1
kind "collision-proxy"
opacity 0
collision-parent "throttle_lever"
}

==animated-dial==

If you've been paying attention to levers, needles and animated levers, I think you can guess where we are going with this one. This is an animated needle. Instead of rotating between the angles specified, it plays it's animation to the relevant frame to show the value. Use this when what you want to achieve can't be done with simple rotational movement.

(Example usage for this control to follow).

==digital-dial==

Some locomotives use a digital readout rather than analogue dials.

Trainz has two control kinds to support digital displays - one for speed units, and one for pressure units. Instead of angles of movement, these both have some font specific options to configure how the digits appear.

"font" defines the typeface. For a list of valid typefaces, see the [[%22mesh-table%22_container_(interior_version)#font|mesh-table (interior version)]] documentation. Generally this follows closely with a number of default windows font names.

"fontsize" defines the size of the font. The default value for this is 0.02, and this is a pretty respectable size display.

"fontcolor" defines the RGB color of the text. Each value is a floating point number between 0.0 and 1.0.

===digital-dial-spd===

For a speedometer (or any other gauge that shows units in speed, e.g. a speed limit display), use kind 'digital-dial-spd'.

An example speedometer using this kind would be declared as:

speedo_needle2
{
kind "digital-dial-spd"
att "a.digispeedo"
font "arial"
fontsize 0.01
fontcolor 1.0,1.0,1.0
auto-create 1
}

===digital-dial-prs===

For a display using pressure units, use digital-dial-prs. This is a digital brake pipe pressure gauge:

bptrainbrakepipe_needle2
{
kind "digital-dial-prs"
att "a.trainpipe_pressure"
font "arial"
fontsize 0.01
fontcolor 0.0,1.0,0.0
auto-create 1
}

==firebox==

The firebox control is a special kind to implement the fire of a steam locomotive.

(Further information about this specific control to follow).

Note: Some steam cab interior models use the firebox, fireglow and burning coal effects found in the Auran PB15 cab interior. This can cause quite severe flickering effects in some models The intensity of flickering varies on the textures used and can be attenuated by use of darker colours. The flickering can be eliminated by not using the firebox effect. The fireglow and burning coal (coal) effects are OK.

'''Note: This feature does not work currently in T:ANE and TRS19.
'''

You can, of course, always make your own.

=Scripting additional behaviour in a cab=

A lot can be achieved in Trainz purely by naming the controls correctly and relying on Trainz default cab scripts to make them work. A quite reasonable cab can be made for many locomotives without having to do any scripting whatsoever.

However, a lot more realism can be achieved by scripting the cab. Additional features can be added beyond what Trainz supports, including new types of controls, or extended behaviour on existing controls.

The first thing to consider when looking at scripting a cab, is "is the cab the best place for this feature?". A cab is not a persistent asset, which means it can go away at any point. When it's gone, it isn't running it's script. Consequently, it is a bad place for any persistent or time based logic - it should only be used to script the immediate behaviour of the controls. Anything beyond this should be implemented the vehicle itself or possibly a script library, both of which are more persistent objects.

If all you want to achieve is to add some simple extra features (e.g. a display of signal aspects within the cab), you can derive from the trainz standard classes, and inherit the default behaviour when adding your new behaviour. This means you can concentrate on just your extra feature, and don't have to worry about making existing functionality work.

If you want to do something a little more advanced (e.g. change the behaviour of the throttle and/or brake controllers), then you are probably best deriving your cab script from the 'cabin' class, ignoring the default cab scripts, and implementing your required behaviour from scratch. This gives you a lot more control, but you do need to do more yourself.

For some examples of the first route, have a look at the MN cabs - the M7 or the ACMU are good examples. Both have a cab signal repeater implemented in the cab interior script, and use the base functionality for almost everything else.

-~= To Be Continued... =~-

==Return to Index==

[[HowToGuides|<< How To Guides]]

[[Category:How-to guides]]

File:Pullropetype.png

2019-11-05T20:13:03Z

Gdennish: