TrainzOnline - User contributions [en]

Material Types

2024-02-13T08:52:10Z

Microlem: Add m.foliage

[[Material]]s describe how a modelled surface will appear in the game. They specify a range of configurations and resources including classic material properties, textures and shaders. Each Material is an instance of a particular preset Material Type, from the selection described on this page.

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.

=Material Naming=

A material name consists of a creator-supplied given name and a material type suffix. The material type is one of a set of supported types defined below, eg. 'm.onetex'. The material type is manually appended to the name of the material within the creation program eg. [[Autodesk 3ds Max]], it is not implied by the configuration of the material. Material type names in Trainz are not case sensitive. In creation programs which do not support the period (".") character within a user-supplied material name, the underscore character ("_") may be used instead. (Note: in modern Trainz, the "m" may be omitted to leave "name.type" rather than the unsightly "namem.type".)

For more info about configuring materials see [[Exporting with 3D Studio Max]].

=PBR Material Types=
Trainz uses a Metallic/Roughness style [[Physically Based Rendering|PBR workflow]]. All materials are expressed in these terms, or (in the case of legacy materials) are converted into these terms using a best-effort approximation. PBR and the Metallic/Roughness workflow are discussed in great detail online, with a number of freely available presentations and demonstrations ranging from beginner material to advanced math. It is recommended that content creators read up on the subject before attempting to configure Trainz materials.

==m.pbrmetal==
[[m.pbrmetal]] is a generic opaque PBR material. This should be considered the starting point for any Trainz content creation which has no special needs.

* Albedo (RGB)
* Normal (XYZ)
* Height
* Emissive
* Roughness
* Ambient Occlusion
* Metallicity

For .CDP example files visit the [[m.pbrmetal]] page and look under the example section.

==m.pbrmetalmasked==
[[m.pbrmetalmasked]] gives identical results to m.pbrmetal but adds masked opacity support.

* Albedo (RGB)
* Masked Opacity (A)
* Normal (XYZ)
* Height
* Emissive
* Roughness
* Ambient Occlusion
* Metallicity

For .CDP example files visit the [[m.pbrmetalmasked]] page and look under the example section.

==m.pbrmetaldetail==
[[m.pbrmetaldetail]] gives identical results to m.pbrmetal but adds support for a detail map.

* Albedo (RGB)
* Opacity (A)
* Detail (RGB)
* Normal (XYZ)
* Height (A)
* Detail Normal (RGB)
* Emissive (R)
* Roughness (G)
* Ambient Occlusion (B)
* Metallicity (A)

For .CDP example files visit the [[m.pbrmetaldetail]] page and look under the example section.

==m.glass==
[[m.glass]] is a transparent PBR material. This enables glass-like substances to be rendered but has a number of peculiarities that make it inappropriate for other purposes.

* Albedo (RGB)
* Opacity (A)
* Normal (XYZ)
* Height
* Emissive
* Roughness
* Ambient Occlusion
* Metallicity

For .CDP example files visit the [[m.glass]] page and look under the example section.

==m.clutter==
[[m.clutter]] gives similar results to m.pbrmetalmasked but adds support for cross-faded LOD transitions and does not include support for parallax mapping. This is intended for use with [[Clutter Effect Layer]]s.

* Albedo (RGB)
* Masked Opacity (A)
* Normal (XYZ)
* Emissive
* Roughness
* Ambient Occlusion
* Metallicity

==m.foliage==
[[m.foliage]] gives similar results to m.clutter but adds support for per-vertex procedural wind animation and ground alignment. This material is intended for use with [[Clutter Effect Layer]]s and is supported in [["Trainz-build" number|content format v5.4]] and later.

* Albedo (RGB)
* Opacity (A)
* Normal (XYZ)
* Emissive
* Roughness
* Ambient Occlusion
* Metallicity

For .CDP example files visit the [[m.foliage]] page and look under the example section.

==Ground Texture Material==
[[KIND Groundtexture]] assets make use of a custom material which offers features equivalent to [[m.pbrmetal]]. It is not possible to override the ground texture material.

[[Surveyor]] allows the user to paint multiple layers of ground texture with automated blending. Historically, this capability was used extensively to help hide the fact that ground textures were low resolution and tiled heavily. Overuse of this approach may induce substantial blurriness and reduce performance. Current-generation ground materials are high resolution and should not tile noticeably. For best performance and visuals, blending should be reserved for actual changes in surface material (eg. grass vs rocks vs mud) rather than to simulate texture detail.

=Legacy Material Types=
The material types here are intended for backwards-compatibility with older versions of Trainz. They are not PBR materials and offer the content creator less control over the end result. It is recommended that the PBR materials are used instead.

==m.notex==
'''''This is a legacy material, and should only be used where compatibility with older versions of Trainz is required.''''' 
[[m.notex]] is a non-textured material.

Opacity = Uniform opacity can be controlled in the material settings.

Full details here: [[m.notex]]

[[Image:mat_notex.jpg]]
==m.onetex==
'''''This is a legacy material, and should only be used where compatibility with older versions of Trainz is required.''''' 
[[m.onetex]] is a diffuse texture mapped material.

Opacity = Per-texel opacity can be controlled via the diffuse texture's alpha channel.

Full details here: [[m.onetex]]

[[Image:mat_onetex.jpg]]
==m.reflect==
'''''This is a legacy material, and should only be used where compatibility with older versions of Trainz is required.''''' 
[[m.reflect]] is a reflective material.

Full details here: [[m.reflect]]

[[Image:mat_reflect.jpg]]

==m.gloss==
'''''This is a legacy material, and should only be used where compatibility with older versions of Trainz is required.''''' 
[[m.gloss]] is a glossy reflective material.

Opacity = Uniform opacity can be controlled in the material settings.

Full details here: [[m.gloss]]

[[Image:mat_gloss.jpg]]
==m.tbumptex==
'''''This is a legacy material, and should only be used where compatibility with older versions of Trainz is required.''''' 
[[m.tbumptex]] is a bump mapped material.

Opacity = Per-texel opacity can be controlled via the diffuse texture's alpha channel.

Specular = Per-texel specular strength can be controlled via the normal texture's alpha channel.

Full details here: [[m.tbumptex]]

[[Image:mat_tbumptex.jpg]]
==m.tbumpgloss==
'''''This is a legacy material, and should only be used where compatibility with older versions of Trainz is required.''''' 
[[m.tbumpgloss]] is a bump mapped reflective material.

View the tutorial video on tbumpgloss [https://youtu.be/ymfWeaPLIEk HERE] and download an example asset [http://download.trainzportal.com/tutorials/16_1_trainz_material_rust.zip HERE] to drop into Trainz to see what effect can be created using this material. The example asset is a "rust" type material.

Opacity = Uniform opacity can be controlled in the material settings.

Specular = Per-texel specular strength can be controlled via the normal texture's alpha channel.

Reflection = Per-texel blend strength of the reflection can be controlled via the diffuse texture's alpha channel.

Full details here: [[m.tbumpgloss]]

[[Image:mat_tbumpgloss.jpg]]

==m.tbumpenv==
'''''This is a legacy material, and should only be used where compatibility with older versions of Trainz is required.''''' 
[[m.tbumpenv]] is a bump mapped environment reflective material. In current versions of Trainz this is the preferred material for most models lit by world lighting, unless a particular effect is desired. Exceptions include tunnels and interiors.

View the tutorial video on tbumpenv [https://youtu.be/YGGkb6nvg5I HERE] and download an example asset [http://download.trainzportal.com/tutorials/16_2_trainz_material_paint.zip HERE] to drop into Trainz to see what effect can be created using this material. The example asset is a "paint" type material.

Opacity = Uniform opacity can be controlled in the material settings.

Specular = Per-texel specular strength can be controlled via the normal texture's alpha channel.

Reflection = Per-texel blend strength of the environment map can be controlled via the diffuse texture's alpha channel.

Full details here: [[m.tbumpenv]]

[[Image:mat_tbumpenv.jpg]]

=Material Examples=
Download example assets below and drop them into Trainz to see what effect can be created using the Materials listed below:

These examples don't use the new PBR shaders:
- Rust - [http://download.trainzportal.com/tutorials/16_1_trainz_material_rust.zip Download Asset]. View the tutorial video for this asset [https://youtu.be/ymfWeaPLIEk HERE]
- Paint - [http://download.trainzportal.com/tutorials/16_2_trainz_material_paint.zip Download Asset]. View the tutorial video for this asset [https://youtu.be/YGGkb6nvg5I HERE]
- Creating Specular Maps - [http://download.trainzportal.com/tutorials/16_3_trainz_material_specular.zip Download Asset]. View the tutorial video for this asset [https://youtu.be/bR3l1LgHSAk HERE]

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

Mesh metadata file

2024-02-13T08:46:05Z

Microlem:

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.

Mesh metadata files are in a simple text format similar to the [[config.txt]] format. They are not currently validated in any fashion beyond basic readability; if you mis-type a tag it will simply be ignored by the reader. Do not rely on this behaviour- we may add validation in the future and it may apply retroactively.

At the current time, the only use for a mesh metadata file is to specify additional material parameters. A "materials" block is added to the file, and within this you may name any of the materials present within your FBX file. Within each of those, you may specify one of the following parameters:

* 'two-sided' - A boolean (0 / 1) value which indicates whether chunks which use this material should be rendered as two-sided (no backface culling) or one-sided (regular backface culling).
* 'blend-mode' - A string with one of the following values:
** 'alpha-blend' - Chunks which use this material are rendered using a true alpha blend.
** 'alpha-to-coverage' - Chunks which use this material are rendered using alpha-to-coverage. This technique is a fast approximation of alpha which sacrifices some visual detail in favour of performance and depth-independance.
** 'alpha-masked' - Chunks which use this material are rendered using alpha masking. This technique discards pixels with low diffuse alpha values, resulting in holes in the geometry.
** 'opaque' - Chunks which use this material are rendered fully opaque.
* 'material-type' - A string which specifies the [[Material_Types|material type]] to use. This causes the game to ignore any material type suffix on the material name. Be careful when overriding material types in this manner, as other requirements (such as texture slot bindings) may vary between material types. The material type string does not include a leading "m." - so "notex" is a valid entry here, but "m.notex" is not.
* 'textures' - A subcontainer list with zero or more texture containers. Each texture container is named for the material texture slot to which the texture is to be assigned ("albedo", "normal", "parameter", "detail-albedo" or "detail-normal"). If this list is present at all, it overrides ALL automatic texture assignment from the FBX file; a partial override is not supported. The following subtags are accepted within each texture container:
** 'texture-resource' - A string within the provides the texture resource name (eg. "foo.texture"). As always, texture resource names are equivalent to texture.txt file names without the trailing ".txt". The resource name may include sub-folder or parent-folder path prefixes, which are resolved relative to the folder containing the metadata file.
* 'bend-normals-upward-ratio' - The default value (0.0) will not modify the mesh normals imported from FBX. The maximal value (1.0) will force the normals to point directly upward. Mid-range values may be used, although care should be taken with normals which are pointing straight downward to start with. This is supported from v4.7 and will be ignored in any prior version. As Trainz is Z-up, "directly upward" means (0.0, 0.0, 1.0).
* 'clutter-wind-type' - Supported in [["Trainz-build" number|content format v5.4]] and later. This tag only applies to materials of type [[m.foliage]]. The details of this attribute can be found [[m.foliage|here]].
* 'clutter-sample-method' - Supported in [["Trainz-build" number|content format v5.4]] and later. This only applies pertains to materials of type [[m.foliage]]. The details of this attribute can be found [[m.foliage|here]].
* 'clutter-geometry-root' - Supported in [["Trainz-build" number|content format v5.4]] and later. This only applies pertains to materials of type [[m.foliage]]. The details of this attribute can be found [[m.foliage|here]].
= Mesh Metadata File Example =

<pre>materials
{
example0
{
two-sided 1
material-type "pbrmetal"
bend-normals-upward-ratio 0.0
textures
{
albedo
{
texture-resource "albedo.texture"
}
normal
{
texture-resource "normal.texture"
}
parameter
{
texture-resource "parameter.texture"
}
}
}
example1.m.onetex
{
two-sided 1
}
}
</pre>

M.foliage

2024-02-13T08:43:20Z

Microlem:

[[m.foliage]] is a variation on the [[m.pbrmetal]] material, supported in assets using trainz-build 5.4 and up.

This material is intended for use with the [[Clutter Effect Layer]], and is tuned to suit that purpose to the detriment of any other possible use-case. While it is permissible to use the material with non-clutter asset types (scenery, traincars, etc.), it may result in visual artifacts or errors if configured improperly. We reserve the right to make changes to the behaviour of the material in ways that do not impact negatively on the clutter effect layer usage, even where those changes negatively impact other uses. For this reason, and because performance of an m.foliage asset is likely to be lower than an equivalent m.pbrmetal asset, it is recommended that m.foliage is used for a non-clutter asset only where substantial performance and visual gains are possible which cannot be achieved using other techniques.

m.foliage introduces support for per-vertex procedural wind animation and ground alignment, to be used with clutter effect layers.

NOTE: This material pertains to meshes which require advanced wind animation or ground alignment. If your clutter mesh is intended to be a static object without ground shearing, the [[m.clutter]] material should be used instead.

[[File:Foliage_animation_1.gif|border|middle|x500px]]

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]].

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

= Mesh Metadata Config =

m.foliage supports several attributes which must be configured through the use of a [[mesh metadata file]].

Listed below are the mesh metadata tags associated with m.foliage, and their meaning.

==clutter-wind-type==

m.foliage supports three wind animation modes, specified by the ''clutter-wind-type'' tag:

===none===
Default behavior. Wind will not affect this material.

===vertex-color===
In this wind mode, the mesh vertex color represents the wind strength multiplier on a per-vertex basis (i.e. how far each vertex is allowed deviate from its initial position in windy conditions).
This is useful for assets such as trees or shrubs, which may need explicit control over how the individual vertices of leaves or branches are permitted to sway in the wind.

The vertex color channels control the following values:

R:
Wind strength factor [0-1].

GBA:
Currently unused. Care should be taken to ensure the green and blue channels remain 0, as they may become used by this material in future.

Authoring vertex color data: TBA

===position-z===
In this wind mode, the vertex Z position is used as the wind strength factor (Higher Z = sways more intensely in the wind).
This is useful for dense meshes, such as grass blades, where the root of each blade should remain fixed in place on the ground while the tips sway fully in the wind.

==clutter-sample-method==

m.foliage supports three ground alignment/shear modes, specified by the ''clutter-sample-method'' tag:

===origin===
Default behavior. No change is made to the vertex position depending on the ground height. This matches existing clutter behavior.

===per-vertex===
In this mode, each vertex will be offset based on the ground height directly below it. For instance, on meshes where all vertices are Z=0, this results in the mesh being projected directly onto the ground geometry.
This mode is useful for large dense ground cover meshes, or 'fake' grass meshes that use a simple billboard card rather than individually modeled blades. These meshes have no discernable 'roots' and thus must deform smoothly and continuously onto the ground rather than discretely.
This mode is NOT recommended for use on meshes featuring individually modeled grass blades. Those meshes should use the ''contiguous-geometry'' mode, documented below.

===contiguous-geometry===
In this mode, vertices will align to the ground intelligently as a group, determined by Trainz based on loose/unconnected geometry within the mesh.
This mode is most useful for grass meshes featuring individually modeled blades. It allows each connected blade in a mesh to snap to the ground as a single unit, preventing distortion effects that would otherwise be caused by rough or noisy ground height.

The contiguous-geometry sample point is determined according to the value of the clutter-geometry-root tag.
clutter-geometry-root can be one of three values:

* bottom - The vertex with the lowest Z position in each sample group is used as the sample location. This is the default behavior, and is the most typical for meshes featuring grass blades.

* top - The vertex with the highest Z position in each sample group is used as the sample location.

* center - The bounding box center of each sample group is used as the sample location.

== Mesh Metadata File Example ==

It is recommended to use the bend-normals-upward-ratio tag with grass meshes using m.foliage, as this allows the grass blades to be more convincingly lit.

<pre>materials
{
grass.m.foliage
{
clutter-sample-method per-vertex
clutter-wind-type position-z
two-sided 0
bend-normals-upward-ratio 1.0
}
}
</pre>

=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:Grass_12_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.

'''Alpha Texture Example'''

[[File:Grass_12_alpha.png|border|middle|x200px]]

The full texture is available here: [[File:Grass_12_albedo.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.

'''Normal Texture Example''

[[File:pbrnormalmap1.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:Foliage_blender_crop.png|border|middle|x300px]]
[[File:Foliage_animation_2.gif|border|middle|x300px]]

Example asset (blend + CDP) download:

[https://dl1.n3vgames.com/downloads/content/foliage/m.foliage-grass-12-sample-source.zip Sample asset and source files]

M.foliage

2024-02-13T08:38:30Z

Microlem: Created page with "m.foliage is a variation on the m.pbrmetal material, supported in assets using trainz-build 5.4 and up. This material is intended for use with the [[Clutter Effect La..."

[[m.foliage]] is a variation on the [[m.pbrmetal]] material, supported in assets using trainz-build 5.4 and up.

This material is intended for use with the [[Clutter Effect Layer]], and is tuned to suit that purpose to the detriment of any other possible use-case. While it is permissible to use the material with non-clutter asset types (scenery, traincars, etc.), it may result in visual artifacts or errors if configured improperly. We reserve the right to make changes to the behaviour of the material in ways that do not impact negatively on the clutter effect layer usage, even where those changes negatively impact other uses. For this reason, and because performance of an m.foliage asset is likely to be lower than an equivalent m.pbrmetal asset, it is recommended that m.foliage is used for a non-clutter asset only where substantial performance and visual gains are possible which cannot be achieved using other techniques.

m.foliage introduces support for per-vertex procedural wind animation and ground alignment, to be used with clutter effect layers.

NOTE: This material pertains to meshes which require advanced wind animation or ground alignment. If your clutter mesh is intended to be a static object without ground shearing, the [[m.clutter]] material should be used instead.

[[File:Foliage_animation_1.gif|border|middle|x500px]]

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]].

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

= Mesh Metadata Config =

m.foliage supports several attributes which must be configured through the use of a [[mesh metadata file]].

Listed below are the mesh metadata tags associated with m.foliage, and their meaning.

==clutter-wind-type==

m.foliage supports three wind animation modes, specified by the ''clutter-wind-type'' tag:

===none===
Default behavior. Wind will not affect this material.

===vertex-color===
In this wind mode, the mesh vertex color represents the wind strength multiplier on a per-vertex basis (i.e. how far each vertex is allowed deviate from its initial position in windy conditions).
This is useful for assets such as trees or shrubs, which may need explicit control over how the individual vertices of leaves or branches are permitted to sway in the wind.

The vertex color channels control the following values:

R:
Wind strength factor [0-1].

GBA:
Currently unused. Care should be taken to ensure the green and blue channels remain 0, as they may become used by this material in future.

Authoring vertex color data: TBA

===position-z===
In this wind mode, the vertex Z position is used as the wind strength factor (Higher Z = sways more intensely in the wind).
This is useful for dense meshes, such as grass blades, where the root of each blade should remain fixed in place on the ground while the tips sway fully in the wind.

==clutter-sample-method==

m.foliage supports three ground alignment/shear modes, specified by the ''clutter-sample-method'' tag:

===origin===
Default behavior. No change is made to the vertex position depending on the ground height. This matches existing clutter behavior.

===per-vertex===
In this mode, each vertex will be offset based on the ground height directly below it. For instance, on meshes where all vertices are Z=0, this results in the mesh being projected directly onto the ground geometry.
This mode is useful for large dense ground cover meshes, or 'fake' grass meshes that use a simple billboard card rather than individually modeled blades. These meshes have no discernable 'roots' and thus must deform smoothly and continuously onto the ground rather than discretely.
This mode is NOT recommended for use on meshes featuring individually modeled grass blades. Those meshes should use the ''contiguous-geometry'' mode, documented below.

===contiguous-geometry===
In this mode, vertices will align to the ground intelligently as a group, determined by Trainz based on loose/unconnected geometry within the mesh.
This mode is most useful for grass meshes featuring individually modeled blades. It allows each connected blade in a mesh to snap to the ground as a single unit, preventing distortion effects that would otherwise be caused by rough or noisy ground height.

The contiguous-geometry sample point is determined according to the value of the clutter-geometry-root tag.
clutter-geometry-root can be one of three values:

=====bottom=====
The vertex with the lowest Z position in each sample group is used as the sample location. This is the default behavior, and is the most typical for meshes featuring grass blades.

=====top=====
The vertex with the highest Z position in each sample group is used as the sample location.

=====center=====
The bounding box center of each sample group is used as the sample location.

== Mesh Metadata File Example ==

It is recommended to use the bend-normals-upward-ratio tag with grass meshes using m.foliage, as this allows the grass blades to be more convincingly lit.

<pre>materials
{
grass.m.foliage
{
clutter-sample-method per-vertex
clutter-wind-type position-z
two-sided 0
bend-normals-upward-ratio 1.0
}
}
</pre>

=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:Grass_12_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.

'''Alpha Texture Example'''

[[File:Grass_12_alpha.png|border|middle|x200px]]

The full texture is available here: [[File:Grass_12_albedo.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.

'''Normal Texture Example''

[[File:pbrnormalmap1.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:Foliage_blender_crop.png|border|middle|x300px]]
[[File:Foliage_animation_2.gif|border|middle|x300px]]

Example asset (blend + CDP) download:

[https://dl1.n3vgames.com/downloads/content/foliage/m.foliage-grass-12-sample-source.zip Sample asset and source files]

File:Grass 12 alpha.png

2024-02-13T07:46:34Z

Microlem:

File:Grass 12 albedo.png

2024-02-13T07:44:16Z

Microlem:

File:Grass 12 albedo.tga

2024-02-13T07:43:21Z

Microlem:

File:Foliage animation 2.gif

2024-02-13T07:37:34Z

Microlem:

File:Foliage blender crop.png

2024-02-13T07:35:11Z

Microlem:

File:Foliage blender example.jpg

2024-02-13T07:30:32Z

Microlem:

File:Foliage animation 1.gif

2024-02-13T07:28:18Z

Microlem:

KIND tni-physics-plugin

2021-02-15T03:22:23Z

Microlem: Created page with "KIND tni-physics-plugin is an asset type which provides control of the internal train physics for any traincar, via TrainzNativeInterface. This asset type requires nat..."

[[KIND tni-physics-plugin]] is an asset type which provides control of the internal train physics for any traincar, via [[TrainzNativeInterface]]. This asset type requires native code support and its use is restricted to authorised TNI content creators only.

==KIND Hierarchy==
===Parent Classes===
* [[KIND Library]]
===Child Classes===
* ''none''

==Supported Tags==
Each tni-physics-plugin asset supports the following tags:

kind "tni-physics-plugin"
tni-library-name ""

====tni-library-name====
:Type: string
:Desc: Specifies the filename of the [[TNI_Core_Interface|plugin DLL]] to load (minus the platform-specific file extension). This plugin is expected to return a processing priority and handle a relevant locomotive's physics requests through [[TNI_Physics_Interface|TNIPhysics]].

==Example Config.txt==
Sample [[config.txt file]] for a tni-physics-plugin asset, with some standard tags excluded for brevity:

kuid <kuid:401543:1085>
kind "tni-physics-plugin"
trainz-build 4.7
username "Core Train Physics Plugin"
tni-library-name "TNIPhysicsCore"
category-class "YL"
description "TNI plugin for default train physics"

==Categories==
[[Category:Asset KIND|T]]

TrainzNativeInterface

2021-02-15T03:04:44Z

Microlem: Add TNIPhysics link

[[TrainzNativeInterface]] is a plugin system which allows native-code developers to create extensions which perform tasks normally inaccessible from within the Trainz environment, such as communicating with custom hardware or external software. This allows third-party developers to extend Trainz into areas where the [[N3V Games]] development team do not presently have the resources to undertake core development.

Some sample ideas which might be viable candidates for TNI plugins:
* Connecting the controls in a real Train cab to a computer running Trainz.
* Controlling a model train layout from within Trainz Driver.
* Importing from third-party data sources into Surveyor.
* Implementing a custom train physics and/or train sound system for a specific series of locomotives.
* Interfacing with third-party train scheduling software.

Please note that this page is a "beginner's summary" of the TNI development process, and is not in itself a legal agreement.

=TNI Developer Requirements=
Creating a TNI plugin imposes a number of requirements on the developer:
* The developer program resources are in English, and the developer is required to provide a representative who can communicate technical concepts effectively in English. N3V Games is unfortunately unable to provide translation resources.
* The developer is required to agree to a development license. The license is intended to protect the developer, N3V Games, and the Trainz end users by defining a number of expectations and responsibilities. The license is not negotiable.
* The developer is expected to provide a short project proposal, which allows N3V Games to confirm that a TNI plugin is an appropriate solution for the project.
* The developer is expected to provide a development schedule detailing the proposed project, estimated delivery timeframe, business model, etc. Freeware and Open Source developers are welcome to apply.
* The developer is required to have an existing understanding of native C/C++ coding practices including the development of DLLs. N3V Games cannot assist with learning native code development.
* The developer must be willing to provide N3V Games with source-level access to the TNI plugin and all linked libraries for review and code-signing. If the plugin communicates with a third-party application, the source code of the application is not required.
* The developer must be prepared to address technical concerns raised by N3V Games, including bugs, stability concerns, and resource usage (memory, cpu, etc.) concerns.

=TNI Proposal Review=
Acceptance of a TNI development proposal is a complex process, but the following quick guide will help you determine if your idea is likely to be approved:

* Can your proposal be implemented effectively in TrainzScript? If yes, we are unlikely to approve a native solution.
* Does your proposal function as a reusable component? We are much more likely to approve projects which can be reused by many Trainz developers than a project which can only be deployed by the author. Individual components which work together via a documented API are preferred over monolithic systems which don't allow individual replacement of the various components.
* Does your proposal duplicate built-in functionality? We are unlikely to approve anything which duplicates core functionality. Exceptions to this guideline will be explicitly noted.
* Do you have the necessary resources to develop your proposal? Supporting TNI developers costs us time and money, which we will prefer to spend on developers who have the technical know-how or other necessary resources to complete their project.
* Does your proposal introduce unnecessary dependencies on third-party software or hardware? If there are two practical ways to do something, one which introduces dependencies and one which does not, we will favor the approach which does not.
* Does your proposed DLL require access to functionality outside that provided by the TrainzNativeInterface DLL? Direct usage of external functionality (including OS-provided functions) is not recommended and will only be approved if strictly necessary.
* Is your proposal mindful of user privacy, collecting only the minimum amount of data required to undertake its stated goal? Data collection that is not strictly required for a plugin's primary purpose will not be approved.

=TNI Codesigning=
As with any native software, TNI plugins are capable of performing any action authorised to the user account under which the Trainz application is running, typically including reading and writing user documents, changing security settings, and accessing the internet. As a security precaution, and to ensure ongoing compatibility, N3V Games does not allow ad hoc distribution of TNI plugin DLLs.

Access to the TNI development environment requires that the developer agrees to and abides by the TNI developer license agreement. Failure to abide by the terms of the agreement will make the developer subject to permanent ejection from the TNI developer program, meaning that they will no longer be able to develop TNI plugins or run development versions of plugins.

Outside of the TNI development environment, TNI plugins require code-signing before they can be deployed. Final build and code-sign of a TNI DLL is performed by N3V Games using source code provided by the developer. The (code-signed) distribution version of the TNI plugin may then be distributed according to the terms of the TNI developer license agreement.

Users require an active internet connection in order to authorise TNI plugins. Users who have no internet connection, or who choose to run Trainz in "offline mode" (where applicable) will not be able to utilise TNI plugins. The internet connection is not required to be permanently active while the TNI plugin is in use.

=Interfacing with Trainz=
TNI is not a magic wand to do anything within the Trainz environment. In order to access or replace any Trainz functionality, a relevant interface must be exposed by Trainz. Additional interfaces will be introduced over time as development resources allow. Please read and understand the capabilities of the interfaces to ensure that your project idea is actually feasible within the capabilities of TNI.

The following interfaces are implemented or planned. No release schedule is available for interfaces which are not yet implemented.

* [[TNI Core Interface]]
* [[TNI TrainzScript Interface]]
* [[TNI Controls Interface]]
* [[TNI Socket Interface]]
* [[TNI Physics Interface]]
* TNI Sound Interface - Not yet implemented.
* TNI Graphics Interface - Not yet implemented.
* TNI User Interface - Not yet implemented.
* TNI Asset Database Interface - Not yet implemented.
* TNI Surveyor Interface - Not yet implemented.

TNI Physics Interface

2021-02-15T03:03:01Z

Microlem: Created page with "TNIPhysics is a builtin TNILibrary within Trainz which allows physics plugin assets to control all the internal train physics for any traincar. Thi..."

TNIPhysics is a builtin TNILibrary within Trainz which allows [[KIND tni-physics-plugin|physics plugin]] assets to control all the internal train physics for any traincar. This includes engine physics, braking systems and shared systems such as track/air resistance. It doesn't currently include systems such as random motion, coupling interactions, collisions or derailments.

Before continuing, it is recommended you first familiarise yourself with the following pages:
* [[TrainzNativeInterface]] - For an overview of TNI and the associated licensing requirements
* [[TNI Core Interface]] - For details of the core TNI functionality, object types, etc.
* [[KIND tni-physics-plugin]] - For the specification of the physics plugin asset kind.

''NOTE: This page is a work in progress, and reflects technologies which are not yet present in retail versions of Trainz.''
''As of publication, TNI Physics is currently in beta release. Information may change.''

==Overview==
TNIPhysics is initialised at game startup, and will automatically locate and load any installed TNI physics plugin assets at world/map load time. All TNIPhysics plugins must have a QueryProcessingPriority function, which will allow Trainz to determine which of the user's installed plugins is best suited to handle a request. TNIPhysics will make all physics update calls through a plugin's LibraryCall interface.

The specific function calls supported by TNIPhysics are detailed in the next section.

==TNIPhysics Library Calls==

====Init====
TNIPhysics will call the plugin library DLL with the function name "Init" on initialization. This call can safely be ignored if no initialisation is necessary. This function expects no return object, and takes no parameters.

====QueryProcessingPriority====
This function is called from Trainz code to query the processing priority of a plugin for a given traincar. The function will be called across every plugin for every vehicle at load/creation time and when switching control modes (DCC vs cab). Whichever plugin returns the highest priority result will process the vehicle's physics. It has a single TNIPhysicsVehicle as the param, and expects a TNIInteger return result. The TNIPhysics_Priority enum defines a list of example return values, but the programmer is not constrained to using these defines.
*TNIPhysics_PriorityInvalid - Never use this plugin (-127)
*TNIPhysics_PriorityLowest - Only use this plugin if there's no other option (-20)
*TNIPhysics_PriorityLow - Prefer not using this plugin, but it might work ok (-10)
*TNIPhysics_PriorityDefault - This plugin can handle the request adequately (0). The builtin core plugin asset always returns this value.
*TNIPhysics_PriorityHigh - This plugin is somewhat specialised to handle the request (10)
*TNIPhysics_PriorityHighest - This plugin was built exactly for this request (20)

====RegisterVehicle====
This function is called from Trainz code on the plugin which returns the highest valid result from a call to "QueryProcessingPriority". It notifies a physics plugin that it has been selected to manage the vehicle, and should perform any appropriate internal initialisation. This function takes a single TNIPhysicsVehicle param (being the vehicle to register) and expects no return object.

====UnregisterVehicle====
This function is the counter to RegisterVehicle, and instructs a plugin that it is no longer managing the physics for a particular vehicle. This will occur when the vehicle is deleted, or Trainz hands it over to a more appropriate plugin (based on the result of a call to the "QueryProcessingPriority" function). This function takes a single TNIPhysicsVehicle param (being the vehicle to unregister) and expects no return object.

When called, the plugin should discard any internal data is has for the specified vehicle. If Trainz required anything to be saved, then a call to SaveVehicleState() will have already made.

====ProcessPhysicsCommands====
The main vehicle update function. This function is called from Trainz code to process a physics command stream for a specific vehicle. The function takes a TNIArray object which contains the TNIPhysicsVehicle (element 0) and a TNIStream (element 1) containing the commands to run (see enum TNIPhysicsPluginCommand for a list of physics commands and their params). Trainz expects a TNIStream return result, containing a list of physics update commands to Trainz from the plugin (see enum TNIPhysicsGameCommand).

==Physics Commands==
The ProcessPhysicsCommands LibraryCall employs incoming and outgoing command buffers to communicate physics information with Trainz.
The command buffer data is sequential - each command ID is written as a 16 bit integer, and will be followed followed by any relevant command parameters (see enum TNIPhysicsPluginCommand for specific command details).

As this is a raw command stream it is critical that the programmer carefully reads the documentation on each specific command, and correctly reads off each parameter value, even if they are not being used by the plugin. Failure to correctly read all command parameters will result in corruption of the stream, and undefinied application behaviour.

The stream has no terminating value, but stream end may be detected using the TNIStreamTell and TNIStreamGetSize functions, or simply by reading commands until failure is detected (e.g. <code>while (TNIStreamReadInt16(commandStream, 0))</code>).

The programmer must employ similar practices when writing the reply command stream. I.e. Each command is written as a 16 bit integer (TNIStreamWriteInt16), and must be followed by the parameters detailed in enum TNIPhysicsGameCommand. Failure to write data in the correct format will result in undefined behaviour within the application.

==Incoming Commands (TNIPhysicsPluginCommand)==
Enumeration listing the possible physics commands the game may issue to a plugin. Commands and parameters will be written, in sequence, to the TNIStream param passed to the ProcessPhysicsCommands library call.

====TNIP_UpdatePhysicsForVehicle====
The main physics update function. This is regularly called by Trainz code to update the traincar physics for a particular time period. This function takes two extra params for the front and rear coupled vehicles, but keep in mind these may be using different TNI plugins.

Parameters:
*float - The time interval to update for.
*TNIPhysicsVehicle - The front coupled vehicle.
*TNIPhysicsVehicle - The rear coupled vehicle.

====TNIP_AdjustMomentum====
Called from Trainz to notify of an adjustment to a vehicles momentum. This is typically used to apply the results of coupler physics interactions. Vehicles for which the plugin does not internally track momentum can safely ignore this call.

Parameters:
*double - The new vehicle momentum.

====TNIP_FinaliseFramePhysics====
Called by Trainz to notify that all updates relating to this vehicle for the current frame are complete. This includes all plugin updates and all coupler interactions. Plugins may use this as an appropriate location to synchronise plugin state to that of the game, or apply visible state changes only. At the time this call is made it is "too late" to perform or apply physics calculations for a given frame.

Parameters:
*float - The time interval that's been updated.
*double - The final momentum for this frame.

====TNIP_NormalisePhysicsData====
Called following an external physics state update in order to perform any physics-mode-specific follow up validation/correction. Examples include after physics/control state replication in multiplayer.

This command takes no parameters.

====TNIP_SaveVehicleState====
Called by Trainz code to request save data for a specific vehicle. If the plugin maintains any internal state for the specified vehicle then this function should save that state, so that players are able to save and reload with seamless physics behaviour. The save state should be returned to the game by adding a TNIP_ReturnSaveState command to the library call result stream (see TNIPhysicsGameCommand for more). If the plugin tracks no state for the vehicle passed, then this call can be safely ignored.

This command takes no parameters.

====TNIP_LoadVehicleState====
Called by Trainz code to load previously saved vehicle state. Note that this is always called, even if the plugin does not produce any save state when TNIP_SaveVehicleState is called. Also note that the the passed soup param may have been produced by a different plugin.

Parameters:
*TNISoup - A saved soup generated by a previous TNIP_SaveVehicleState call on this or another plugin. The soup will contain an AssetID param for the plugin that produced it, using the tag name "plugin-kuid".

====TNIP_SteamEngine_AddCoalToFire====
Called by Trainz code to add coal to a steam engine. For example, when the player uses the manual "Shovel coal" command.

Parameters:
*double - The volume (not mass) of coal to add.

==Outgoing Commands (TNIPhysicsGameCommand)==
Enumeration listing the possible physics commands a plugin may issue to the game. A TNIPhysics plugin may write these commands (and their params) to the TNIStream returned by a ProcessPhysicsCommands library call.

====TNIP_UpdateVehicleBegin====
Specifies which vehicle a sequence of update commands refers to. Use of this command is not necessary, and by default any written commands will update the vehicle which ProcessPhysicsCommands() was called for. If, however, the plugin wishes to run commands for connection data on one of the coupled vehicles (such as brake pipes, etc) then this is used to specify that vehicle.

Parameters:
*TNIPhysicsVehicle - The vehicle to start updating.

====TNIP_UpdateVehicleEnd====
Used to mark the end of a vehicle update stream. This will set the update vehicle to null. Following this, a new TNIP_UpdateVehicleBegin command *must* be written before any further update commands.

This command takes no parameters.

====TNIP_ReturnSaveState====
Used to return the generated save state for a TNIP_SaveVehicleState command (documented above, in TNIPhysicsPluginCommand).

Parameters:
*TNISoup - A soup containing the saved plugin state. The plugin should write enough state to adequately restore its current internal state for the given vehicle on reload. It is also courtesy to return known/common save data which this plugin itself may not use/require, but which may be useful/expected by other plugins (this aids in seemless plugin switchover during gameplay).

===Engine Commands===

====TNIP_SetResistanceForce====
Sets the current resistant force for train movement. This includes all track resistance, slope resistance, and internal engine resistances.

Parameters:
*double - The current resistance force, in Newtons.

====TNIP_SetBrakingForce====
Sets the current braking force for the train. This is the force from any/all applied brakes.

Parameters:
*double - The current braking force, in Newtons.

====TNIP_SetEngineForce====
Sets the force currently being output by the engine.

Parameters:
*double - The current engine force, in Newtons.

====TNIP_SetAppliedEngineForce====
Sets the force currently being applied to the wheels by the engine. In other words, this is the engine force minus any wheelslip.

Parameters:
*double - The current applied engine force, in Newtons.

====TNIP_SetWheelslipForce====
Sets the amount of force currently being lost to wheelslip.

Parameters:
*double - The current wheelslip force, in Newtons.

====TNIP_SetCurrentDrawn====
Updates the current drawn stat.

Parameters:
*double - The current being drawn, in Amps.

====TNIP_SetPFXEnergyUseAmount====
Updates the "energy use" stat, which is used to generate the PFX "load" variable. This currently has no effect on traincar physics, just particle effects (smoke).

Parameters:
*double - The energy use for the current time interval.

====TNIP_SetWheelMomentum====
Sets the current forward momentum for a traincar (i.e. this value will be negative if the traincar is not moving forwards).

Parameters:
*double - The new forward momentum for the updated traincar, in Newton seconds.

====TNIP_AddWheelMomentum====
Adds momentum to the updated traincar. A negative (or positive, for backward travelling traincars) value may be used to remove momentum.

Parameters:
*double - The momentum to add onto the traincar, in Newton seconds.

====TNIP_SetExtraEngineMass====
Sets the amount of 'extra' engine mass a vehicle currently has. This is typically the fuel mass (water and coal) for steam locos.

Parameters:
*double - The current extra engine mass, in kg.

====TNIP_SetEngineParam====
Sets the value of a named engine param, as returned by the script <code>GetEngineParam()</code> function on Vehicle. This is used to add support for custom named parameters, attempting to override the natively supported params may not work.

Parameters:
*TNILabel - The name of the engine parameter to add/update.
*double - The new value of the parameter.

====TNIP_SetEngineThrottle====
Sets the current engine throttle. This should gradually move toward the throttle setting, with some amount of latency.

Parameters:
*double - The new engine throttle amount (0 to 1).

====TNIP_SetCompressorActive====
Sets whether the brake system compressor is active.

Parameters:
*int8_t - The new compressor state (0- off, 1-on).

====TNIP_SetEqualiserPressure====
Sets the pressure of the brake system equaliser.

Parameters:
*double - The new equaliser pressure, in g/m^3.

====TNIP_SetMainReservoirPressure====
Sets the pressure of the brake system main reservoir.

Parameters:
*double - The new main reservoir pressure, in g/m^3.

====TNIP_SetAuxReservoirPressure====
Sets the pressure of the brake system auxiliary reservoir.

Parameters:
*double - The new auxiliary reservoir pressure, in g/m^3.

====TNIP_SetAutoBrakeCylinderPressure====
Sets the pressure of the brake cylinder.

Parameters:
*double - The new brake cylinder pressure, in g/m^3.

====TNIP_SetIndependentBrakeCylinderPressure====
Sets the pressure of the independent/loco brake cylinder.

Parameters:
*double - The new independent/loco brake cylinder pressure, in g/m^3.

====TNIP_SetTrainBrakePipePressure====
Sets the pressure of the main train brake pipe.

Parameters:
*double - The new train brake pipe pressure, in g/m^3.

====TNIP_SetEpReservoirPipePressure====
Sets the pressure of the electro-pneumatic brake pipe.

Parameters:
*double - The new electro-pneumatic brake pipe pressure, in g/m^3.

====TNIP_SetNo3PipePressure====
Sets the pressure of the no3 brake pipe.

Parameters:
*double - The new no3 brake pipe pressure, in g/m^3.

====TNIP_SetNo4PipePressure====
Sets the pressure of the no4 brake pipe.

Parameters:
*double - The new no4 brake pipe pressure, in g/m^3.

====TNIP_SetBrakePressureFlowRate====
Notifies of the brake pressure flow rate.

Parameters:
*double - The new brake pressure flow rate, in g/m^3.

===Steam Engine Commands===

====TNIP_SetCoalLevel====
Sets the coal level in a steam locomotive. This is the current ratio between the minimum (0) and maximum (1) coal levels for the firebox. i.e., a reading of 0 indicates the fire is at minimum coal, not that it's necessarily "empty", and a value over 1 indicates the fire is over-filled with coal.

Parameters:
*double - The current coal level in the firebox.

====TNIP_SetWaterLevel====
Sets the water level in a steam locomotive. This is the current ratio between the minimum (0) and maximum (1) water levels for the boiler, as would be shown on the cab gauge(s). i.e., a reading of 0 indicates the boiler is at or below minimum, not that it's necessarily "empty".

Parameters:
*double - The current water level in the boiler.

====TNIP_SetBoilerPressure====
Sets the current pressure within the boiler, in pascals.

Parameters:
*double - The new boiler pressure, in pascals.

====TNIP_SetSteamChestPressure====
Sets the current pressure within the steam chest, in pascals.

Parameters:
*double - The new steam chest pressure, in pascals.

====TNIP_SetThrashing====
Sets the amount the engine is being 'thrashed', as returned to script by a call to <code>Locomotive.GetEngineParam("thrashing");</code>

Parameters:
*double - The amount the engine is being 'thrashed', 0 to 1 for normal engine operation, >1 for thrashing.

====TNIP_ConsumeCoal====
Informs Trainz to consume an amount of coal product, for use as steam engine fuel. The caller should first verify that there is sufficient fuel to meet the request, using TNIPhysicsGetVehicleCoalAvailable().

Parameters:
*int32_t - The amount of product to consume.

====TNIP_ConsumeWater====
Informs Trainz to consume an amount of water product, for use as steam engine fuel. The caller should first verify that there is sufficient fuel to meet the request, using TNIPhysicsGetVehicleWaterAvailable().

Parameters:
*int32_t - The amount of product to consume.

===Effect Commands===

====TNIP_SetWheelAngularVelocity====
Sets the angular velocity of the wheels on a steam locomotive. This affects the value of the "cyclespeed2" PFX variable.

Parameters:
*float - The angular velocity of the driving wheels, in m/s.

====TNIP_SetWheelAnimationData====
Sets the animation data for the wheels of a traincar. Two values are always written here, but which is used will depend on the type of wheel animation which being used by the traincar.

Parameters:
*float - The current wheel rotation, from 0 to 2PI.
*float - The wheel velocity, in m/s.

====TNIP_SetBrakeReleaseSoundFade====
Sets the volume of the brake release sound on this traincar.

Parameters:
*float - The new brake release sound volume, 0 to 1.

====TNIP_SetPFXVariableValue====
Sets the value of a named PFX variable. See validation/steam-mode.txt for a list of valid variable names.

Parameters:
*TNILabel - The name of the variable to update.
*float - The new value of the variable.

==Accessor Commands (TNIPhysics.h)==
Basic accessors for TNIPhysicsVehicle member variables, including those on the frame data, engine spec or steam engine spec.

===AssetID/Config Accessors===
{{MethodHeader|const TNIAssetID* TNIPhysicsGetVehicleAssetID(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|const TNISoup* TNIPhysicsGetVehicleAssetConfig(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|const TNIAssetID* TNIPhysicsGetVehicleEngineAssetID(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|const TNISoup* TNIPhysicsGetVehicleEngineAssetConfig(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|const TNIAssetID* TNIPhysicsGetVehicleTrackAssetID(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|const TNISoup* TNIPhysicsGetVehicleTrackAssetConfig(const TNIPhysicsVehicle* vehicle)}}

===Train Control Settings===
{{MethodHeader|int8_t TNIPhysicsGetVehiclePhysicsModelSetting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|int8_t TNIPhysicsGetVehicleTractionSetting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleThrottleSetting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleSteamRegulatorSetting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleSteamCutoffSetting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleTrainBrakeSetting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|int8_t TNIPhysicsGetVehicleDynamicBrakeSetting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleLocoBrakeSetting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|int8_t TNIPhysicsGetVehicleEpBrakeSetting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleBailTimeSetting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleHandBrakeSetting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleSandingSetting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleCoalRateSetting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleInjector1Setting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleInjector2Setting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleBlowerSetting(const TNIPhysicsVehicle* vehicle)}}

===Vehicle State Accessors===
{{MethodHeader|double TNIPhysicsGetVehicleMass(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleVelocity(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|bool TNIPhysicsGetVehicleIsStopped(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleWheelMomentum(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleWheelslip(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleWheelslipTractionMultiplier(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleWheelslipMomentumMultiplier(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleEngineForce(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleEngineThrottle(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleThrottleGraphOutput(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleDynamicBrakeGraphOutput(const TNIPhysicsVehicle* vehicle)}}

{{MethodHeader|bool TNIPhysicsGetVehicleIsDerailed(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|bool TNIPhysicsGetVehicleAllowsUserControl(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|bool TNIPhysicsGetVehicleIsAutomaticFireman(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|uint32_t TNIPhysicsGetVehicleCoalAvailable(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|uint32_t TNIPhysicsGetVehicleWaterAvailable(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleSandingTractionMultiplier(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleScriptTractionMultiplier(const TNIPhysicsVehicle* vehicle)}}

===Vehicle Brake Pressure State Accessors===
{{MethodHeader|double TNIPhysicsGetVehicleEqualiserPressure(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleMainReservoirPressure(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleNo3PipePressure(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleTrainBrakePipePressure(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleEpReservoirPipePressure(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleNo4PipePressure(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleAuxReservoirPressure(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleAutoBrakeCylinderPressure(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleIndependentBrakeCylinderPressure(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleScriptBrakePressure(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleBrakePipeEfficiency(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleCompressorEfficiency(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|int8_t TNIPhysicsGetVehicleCompressorActive(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleBrakeReleaseSoundFade(const TNIPhysicsVehicle* vehicle)}}

===Vehicle Track State Accessors===
{{MethodHeader|double TNIPhysicsGetVehicleTrackGradient(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleTrackCurveAngle(const TNIPhysicsVehicle* vehicle)}}

===Vehicle Spec Accessors===
{{MethodHeader|int8_t TNIPhysicsGetVehicleEngineType(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleMaximumTractiveEffort(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleWheelDiameter(const TNIPhysicsVehicle* vehicle)}}

===Engine Spec Accessors===
{{MethodHeader|float TNIPhysicsGetVehicleMaxSpeed(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleMaxDCCAcceleration(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleMaxDCCDeceleration(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleMaxVoltage(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetEngineBrakeRatio(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleThrottleAdjustmentRate(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleAxleCount(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleSurfaceArea(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleMovingFrictionCoefficient(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleAirDragCoefficient(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleDrivingWheelWeightRatio(const TNIPhysicsVehicle* vehicle)}}

===Engine Spec Flowsize Accessors===
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_TrainBrakePipe(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_EpReservoirPipe(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_No3Pipe(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_No4Pipe(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_AuxReservoirVent(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_AuxReservoirToNo3Pipe(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_AuxReservoirToTrainBrakePipe(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_AutoBrakeCylinderVent(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_AuxReservoirToAutoBrakeCylinder(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_EqualiserMainReservoir(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_EqualiserVentHandleOff(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_EqualiserVentEmergency(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_EqualiserVent(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_No3PipeVent(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_No3PipeMainReservoir(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_Compressor(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_TrainBrakePipeReservoir(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_TrainBrakePipeVent(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_No3PipeToAutoBrakeCylinder(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_EpReservoirPipeToAutoBrakeCylinder(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_MainReservoirEP(const TNIPhysicsVehicle* vehicle)}}

===Engine Spec Volume Accessors===
{{MethodHeader|float TNIPhysicsGetVehicleVolume_Equaliser(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleVolume_MainReservoir(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleVolume_No3Pipe(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleVolume_TrainBrakePipe(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleVolume_EpReservoirPipe(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleVolume_No4Pipe(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleVolume_AuxReservoir(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleVolume_AutoBrakeCylinder(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleVolume_IndependentBrakeCylinder(const TNIPhysicsVehicle* vehicle)}}

===Engine Spec Pressure Accessors===
{{MethodHeader|float TNIPhysicsGetVehiclePressure_BrakePipe(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehiclePressure_BrakeInitial(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehiclePressure_BrakeFull(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehiclePressure_IndBrakeFull(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehiclePressure_Compressor(const TNIPhysicsVehicle* vehicle)}}

===Steam Engine Spec Accessors===
{{MethodHeader|float TNIPhysicsGetSteamEnginePistonVolumeMin(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEnginePistonVolumeMax(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEnginePistonArea(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEnginePistonLength(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|int TNIPhysicsGetSteamEnginePistonAngularOffsetsCount(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEnginePistonAngularOffset(const TNIPhysicsVehicle* vehicle, int i)}}

{{MethodHeader|float TNIPhysicsGetSteamEngineTractiveEffortConstant(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineHandBrakeMaxForce(const TNIPhysicsVehicle* vehicle)}}

{{MethodHeader|float TNIPhysicsGetSteamEngineTestSpeed(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineTestCutoff(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineBurnRate(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineBurnRateIdle(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineMinFireTemperature(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineMaxFireTemperature(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineFireboxEfficiency(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineFireboxHeatingSurfaceArea(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineFireboxPlateThickness(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineFireboxThermalConductivity(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineBlowerEffect(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineBlowerMaxFlow(const TNIPhysicsVehicle* vehicle)}}

{{MethodHeader|float TNIPhysicsGetSteamEngineStartingCoal(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineIdealCoalMass(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineMaxFireCoalMass(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineFuelEnergy(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineFuelSpecificHeatCapacity(const TNIPhysicsVehicle* vehicle)}}

{{MethodHeader|float TNIPhysicsGetSteamEngineBoilerVolume(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineBoilerVolumeMin(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineBoilerVolumeMax(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineBoilerFusiblePlugVolume(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineSteamChestVolume(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineSteamChestMaxFlow(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineValveLapPercent(const TNIPhysicsVehicle* vehicle)}}

{{MethodHeader|float TNIPhysicsGetSteamEngineBoilerEfficency(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineBoilerEfficencyIdle(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineBoilerEfficencyMin(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineBoilerHeatLoss(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineInitialBoilerTemperature(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineSuperheatingConstant(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineStartingWater(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineStartingBoilerSteam(const TNIPhysicsVehicle* vehicle)}}

{{MethodHeader|float TNIPhysicsGetSteamEngineSafetyValveLowPressure(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineSafetyValveLowFlow(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineSafetyValveHighPressure(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineSafetyValveHighFlow(const TNIPhysicsVehicle* vehicle)}}

{{MethodHeader|float TNIPhysicsGetSteamEngineCoalShovelMass(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineWaterInjectorRate(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineWaterInjectorRate2(const TNIPhysicsVehicle* vehicle)}}

Script Feature Requests

2019-01-27T17:53:39Z

Microlem: /* Requests */

This page is where the [[scripting]] community gets to post all their API feature requests. Request any additions that you think will enhance the game. Things to keep in mind:
* We are unlikely to add a feature which breaks any existing content.
* Script is for control purposes, and is not intended to enable significant modifications to the underlying game engine. We are very unlikely to introduce a feature where the obvious uses are going to result in significant performance penalties.
* We are far more likely to add features which are directly blocking something that the community is working on. If you have something cool, and need just a few minor additions then please detail what you're working on (ideally, on another wiki page linked from both here and your [[Content Creation Groups]] page) and why you need the additions.
* [[MiniBrowser]] requests should go on the separate [[MiniBrowser Feature Requests]] page.

==Requests==
Requests are placed in this section by the community, for discussion and possible inclusion.

* Str.Tokens("Foo", "") should return ["F", "o", "o"] when called without separator in 2nd argument analogous to other languages (String.split()). --[[User:Sachsenbahner|Sachsenbahner]] 19:53, 10 December 2018 (AEST)

* Add a method that will let you identify the industry at which a vehicle is located. If an industry track section can also carry the industry identifier, it would be most helpful.

* Add a handle to allow a custom bell animation to be played when the bell is played on a locomotive (Vehicle.StartBell() and Vehicle.StopBell(), perhaps?). Justification: Script can currently listen for the bell message, but since the message is a toggle, it is easy to get out of synch with the true state of the bell. For example, when coupling a locomotive whose bell is ringing to a locomotive whose bell is not ringing, the end result depends on which locomotive is currently in focus. - Curtis

* Scale the visible bulk load animation on a traincar such that it takes Vehicle.GetLoadTime() to complete. For example, if Vehicle.GetLoadTime() returns 5 seconds, the bulk animation would take 5 seconds to transition from the full state to the empty state. This would be useful for industries that take more than one second to load / unload a car, as the visible load animation could be synced more closely with the industry animation. -Curtis

* Extension to the function World.GetAssetList(string kind, bool OnlyIfUsedInCurrentMap) -Andi06

* Ability to play an avi and wait for it to finsh (no user interaction allowed) ~Jenolan

* The ability to modify scenery trigger radii on the fly in script. This is really aimed at crossings so that train detection can be varied in line with track speed limits. -Andi06

* A method of refreshing the Property Browser to take account of any change in the target object's name during a property editing session. (Objects which have 'autoname 1' in config will often be renamed by the user. In some circumstances I am using the object name to set other properties. Typically an object might be created as 'Double Slip 1' and might refer to its constituent nodes as 'Double Slip 1,Track 1'. This is to enable other objects to refer to it in a user friendly way. On a name change the Property Browser continues to use the old name until the browser has been closed and reopened. This is counter intuitive) -Andi

* Ability for a script to be able to read/change loco/rolling stock parameters (ie to simulate one loco losing air etc etc etc) ~Jenolan

* SetFXCoronaTexture() A means of resetting to config.txt defaults.

* Be able to play mp3 as well as wav. ~Jenolan
: ''I've been able to do this where the asset doing the playing is a script library, I had Acker Bilk coming over a station tannoy at one point. Not sure why it doesn't seem to work elsewhere. -Andi''

* Interface.MessageBox(Caption,Text), calling up a small browser with a close button would be helpful, especially for novices. Interface.Print() is a monumental PITA because it prints out upside down, doesn't hold enough lines, and only works in Driver. For sure its possible to write your own version of this but browsers aren't all that easy to get your head around and its a very basic facility that should be built in. -Andi

* A standard config.txt tag 'junction-type normal/singleslip/doubleslip' etc together with a spec for construction and behaviour might be helpful. I already have a complete schema for this. -Andi
: ''Uncertain what you're expecting to achieve here? -chris''
: ''see Animated Fixed Junctions Thread''

* Is it possible to make a mesh available which matches the existing graphic direction indicators, it appears to be some sort of directional corona or variant. If not could a new marker mesh be developed that could be used with both types? The existing one has nasty alpha effects in any case. -Andi

* Ability to dynamically change the length of a piece of rolling stock as part of the load / unload process; to support logging disconnects (see http://www.trainzone.co.nz/logging.htm for examples)- Curtis
: ''This is an interesting concept, but sounds difficult to implement. I can't think of any way of adjusting the length unless it was the end item of a consist, since adjustment at any other time would require displacing the remainder of the consist. Could you expand on your ideas please.'' -chris
: ''The entire car, including lmfront & lmback, would be part of the loading / unloading animation. When loading, it would probably be necessary to displace the consist by moving one of the ends - perhaps the end with the locomotive? Potential issue: if when loading, the increase in consist length causes the end of the consist to run off the end of the track or collide with another train. When unloading, you could break the consist at either or both lmfront / lmback - whichever move as part of the unloading animation.'' - Curtis
: ''May be simpler to just break the consist at both lmfront and lmback; centering the car in-between the two halves. -Curtis

*Allow SetFXNameText(effect,text) to accept an empty string in the second parameter - Reason: It's really irritating having to write workarounds for this. ~Andi

*SetMeshScale(X,Y,Z) and corresponding config tags. Positive or negative values would implement mesh mirroring at the same time. As an example of potential a placement option for trees might allow random scale factors (within reasonable limits) and random rotation. Each tree placed would then vary in size, shape and rotation getting much more variation from the same mesh asset. ~Andi

* Update to product loading / unloading functionality to allow incremental loads and unloads.
:Potential usages:
:- Animation that plays once per item being loaded; such as a forklift carrying a crate to a boxcar, or a crane lifting a log to a flatcar.
:- Allow dynamic load times of bulk loads (small cars load faster than large cars), with the animated load rising / lowering synchronously.

:Potential implementation:
:Extend vehicle.LoadProduct(report,units) where units = integer number of queue to be loaded each increment. 0 would be everything, defaulting to current LoadProduct() behavior, and add additional calls BeginIncrementalLoad(), EndIncrementalLoad(), BeginIncrementalUnload(), and EndIncrementalUnload().

:During a load operation that loads 3 increments (units=1, target queue on the car = 3), the flow would look like:
BeginLoad() // open car doors; station doors

BeginIncrementalLoad() // start loading animation, start sounds; pfx; add any delays
TransferProductFrom() // maximumToTransfer = units
EndIncrementalLoad() // animate forklift returning to station / end sounds / pfx / other cleanup

BeginIncrementalLoad()
TransferProductFrom()
EndIncrementalLoad()

BeginIncrementalLoad()
TransferProductFrom()
EndIncrementalLoad()

EndLoad() // close car & station doors

* Ability to add a vehicle to an existing consist like Vehicle.Reposition( Train, MyCouple, OtherCouple ) this would save needing a work track mark to add vehicles which would be very helpful ~Jenolan

* Extension to AddHandler to allow this syntax: AddHandler(target,"","","MessageHandler"), passing all messages to the specified handler, for justification see discussion page. -Andi

* Ability to store any information along with the layout and not the session (i.e. ''PropertyObject.SetLayoutProperties'' and ''PropertyObject.GetLayoutProperties'', taking/returning ''Soup'' objects respectively). Rationale: the non-existence is a major drawback with configurable signals - [[User:Klausm|Klausm]]

* Access to asset location, height, rotation in script. This came up twice - once when I wanted to keep traffic lights upright when the containing asset is rolled, and once when I wanted to add simple real time ground shadows to assets. -Andi06

* Ability to arbitrarily add an attachment point to an item. To allow things like FRED/BOG sundry animations and so on ~Jenolan

* Not really script. A generic clickable mesh object, its an easy hack using a fixedtrack junction but it would nice to have an official version - click on the engine shed to open the doors, click on the signal box to open a track browser etc etc. Mappable click regions too if its not too much to ask :-) -Andi

* Extension/Alternative to World.GetJunctionList to return fixed track junction objects or nodes, I can script this easily for objects using my library but this would not be the case for all junctions. -Andi

* World.Play2DSound(Asset,filename) allows sound files to be saved in a 'sound library' asset and avoids duplication. Can we have a similar facility for images to be used in html assets. A lot of the dependencies that I use are images and icons. I'm consciously trying to avoid this now - its the source of much pain - but to do this for the Junction Kit for instance I would have to have copies of all necessary images in all of the placeable assets (there are more than 50) If I could simply keep one copy in the script library it would save much bandwidth, diskspace and support. -Andi06

* genesteal : cab features.
- methods for light controls in cabin : Control.SetFlash (float frequency).Make the control visible/invisible on the intervall frequency. may be Meshobjects.gs for more general purpose. The same for texture swapping in texture replacement.
- New conrol cab "button" with vertical translation limit : method set and get value as usual, method for "while depressed" behavior: Setdepressed ( method to run).

- Speedlimiter method : Set a speedlimit replacing the max speed possible on cab mode.(engine)

- Set engine methods :
Locomotive.SwapEngine(kuid); replace engine by another for a locomotive. feature existing on actual loco to set a traction service if the loco have to drive freight or passengers consists. This method can replace speedlimit above and may be more accurate : speedlimit and power will be set together as prototypical setting before a journey.
- Locomotive.EngineStop(): stops the enginesound and play a stop.wav, located in enginesound folder.
- Locomotive.EngineStart() : starts enginesound like this : play a start.wav located in enginesound folder, then idle 0.wav.

* Allow function Vehicle.SetTractionMultiplier(float) to set multiplier to 0. ~Mike
: UPD: sorry, misunderstood functionality of this function. But could there be a method to disable traction on locos?

* Ability to change (or only to reduce) the presure in auxilary reservoir of a vehicle. This provides a way to create different types of tripte valves for long-length trains (~70 vehicles), where using Train.SetVelocity() is unrealistic

* Make in addition to Vehice.GetTrackGradient() also float Vehice.GetTrackCurveRadius() which return 0 for straight sections of track (instead of infinity). ~tram
* Make a function for smooth control of "soundscript"'s sound volume. For example like void MapObject.SetSoundScriptVolume(string soundTrigger, float NewVolume, float Duration). ~tram

* Ability to set the camera view within an interior by a script to one of the defined cameras in the cameralist container. It would also be handy if the camera orientation be configurable via a method call. --[[User:Pcas1986|pcas1986]] ([[User talk:Pcas1986|talk]]) 18:14, 20 February 2014 (EST)

* Ability to place a bogey in an interior via the interiors config file. This would allow for me to make a realistic gangway for my Amlfeets ~ Ashton

* Locomotive.SetEngineSetting(string setting, float value) - Ability to mute/activate engine sound for a locomotive adding setting "enginesound" to the list of settings, value 0 to mute, 1 to activate engine sound ~manweb
- setting = The name of the setting to save (enginesound).
- value = The value of the named setting. (0 - 1)

* Math.sin,cos,tan,arcsin,arccos,arctan - Trigonometric functions to get the sine, cosine, and tangent of a float, and inverses of these

==Complete==
* Simple destructor routine, or some other method of receiving notification of the deletion of scripted objects during a Surveyor session. (In the absence of World.GetJunctionBaseList() my new junction objects are maintaining a list of fixedtrack junctions via library calls in the Init() method of each object. Apart from using the list myself, it is intended to be returned on demand to any script making the appropriate LibraryCall. Since I have no way of telling that an object has been deleted, I need to rescan the entire list before returning it to ensure that each object still exists, this seems a touch inefficient when it could be easily kept up to date without a complete parse) -Andi
:''Now a function of the [[TrackSearch]] system.'' -chris

* The ability for [[TrackSearch]] to return the trigger or track reference found for SceneryWithTrack descendants, including turntables and the ability to initiate a search from a specified trigger or track in SceneryWithTrack descendants. A million reasons for this including trains being able to detect which track of an industry they can see in a proposed 'Call-At All Stations' rule. -Andi06
:''Now a function of the [[TrackSearch]] system.'' -chris

* Compatibility of the [[TrackSearch]] with the animated fixed junctions. When I first got TRS2006 in my hands, I tried out my TrackView rule, but quickly discovered that it was impossible to find out the track topology (forgot the exact details, though) - [[User:Klausm|Klausm]]
:''[[TrackSearch]] system is now considerably more robust.'' -chris

* Extensions to TrackSearch()/GSTrackSearch() covered elsewhere to be sufficient to allow the topography of multi node junctions to be fully discovered. -Andi
:''[[TrackSearch]] system is now considerably more robust.'' -chris

*If we are going to use radians now (SetMeshOrientation()) could we please have PI?
:''Math.PI'' -chris

* Ability to configure permit structure to allow multi node junctions to coexist with the AI, whilst denying conflicting paths, as discussed above. -Andi
:''Added named mutex support for attached junctions. See [[KIND SceneryWithTrack]].'' ~chris

* Fix World.GetAssetList("texture-group"), this has been broken since TRS2004. -Andi06
:''Now returns all assets with category-class 'JO'. This seems to contain all 'texture-group' type assets - though there maybe some unexpected extras.'' -James

* Ability to detect the use of 'Pause' easily (a message would do) to stop cheating in shunting puzzles ~Jenolan
:''New messages "World", "Paused" and "World", "Unpaused" now exist and should be broadcast at the appropriate times.'' -James

* World.GetCurrentTrain() Not essential obviously but it would save a lot of work. -Andi06
:''Now exists.'' -James

* Ability to optionally detect mouseclick/ Keys [J] & [^J] without switching the junction. This can be hacked by making node 0 an invisible junction, but this will result in other objects querying the junction structure not getting the answer they expect (or not one they can understand). This is needed to allow objects with more than one junction node to cycle through their options in response to the user. -Andi
:''I believe this is now possible via script overrides on the map object in question.'' ~chris

* A method of subclassing or outright using a script from another asset (ie. a script which is written once and reused heavily, allowing any fixes to be released as a single asset update.) - chris
:''TS2009 now has the ability to cross-include scripts from another asset.'' ~chris

* Dreamland, a new message: ''Junction,AboutToToggle'' -Andi
: ''How do you expect to act on this? -chris''
: ''see Animated Fixed Junctions Thread''
::'I believe this concept has been fulfilled via the UserRequestToggle overrides.'' ~chris

* On a similar note is there any chance you might amend the Exception dialogue to specify the object, (or even the Asset) which is causing the exception :-) -Andi
:: I think we did this one a while back. ~chris

* SetMeshPosition("meshname", x,y,z) absolute positioning of a Mesh or Object. -Caby
: This exists ~Andi
:: ''Not necessarily - we support relative positioning, not absolute. This may or may not achieve what he wants.'' ~chris
:: This has been added. ~chris

* GetMeshPosition("meshname", "x")["Y"]["Z"] receive the absolute position of a Mesh or Object. -Caby
: Since you have used SetMeshPosition() to move the mesh, this is unneccessary
:: ''Absolute position can be set in Surveyor. Relative position can be set in the [[config.txt file]]. I wouldn't say that this is completely unnecessary.'' ~chris
::: Thanks a lot for MapObject.GetMapObjectPosition() and MapObject.GetMapObjectOrientation() ~tram
:: This has been added. ~chris

* Ability to load a menu asset directly from the command line ~Jenolan
:: This exists with "-scriptedmenu=<KUID>" ~chris

==Rejected==
If there's a request that we're clearly not going to entertain at the current time, we'll move it to here. This includes both flat rejections and also requests which sound good but won't be done for the next version of Trainz.

[[Rejected Script Feature Requests]]

[[Category:Feature Request]]