TrainzOnline - User contributions [en]

Help:VE173

2026-02-04T04:39:10Z

Windwalkr: Created page with "=Material '$(MATERIAL)' in mesh '$(FILE)' is not of a recognised material type.= This error occurs when loading a legacy Trainz IM mesh file, or when importing from an [[FBX ..."

=Material '$(MATERIAL)' in mesh '$(FILE)' is not of a recognised material type.=

This error occurs when loading a legacy Trainz IM mesh file, or when importing from an [[FBX file format|FBX mesh source file]]. It indicates that the mesh contains a [[Material Types|material type]] which is not supported by the game. Material types are typically determined by interpreting the material's name (as configured in the modelling program that created the file), however this may be overridden using a [[Mesh metadata file]].

==FBX Mesh Source Files==
The FBX mesh importer first checks for a 'material-type' tag in the mesh metadata file, if any. If present, this is used verbatim. Otherwise, it looks for the last occurrence of a period (".") character in the material name, and then uses the characters after that as the material type. From [[trainz-build]] v4.6 onwards, the importer also checks for a underscore ("_") character if no period is present, and applies the same logic; this is to support the Maya LT modeller which doesn't allow periods in material names.

The comparison is case sensitive. The supported material types are:
* tbumptex
* tbumpenv (prior to trainz-build v5.6)
* gloss (prior to trainz-build v5.6)
* tbumpgloss (prior to trainz-build v5.6)
* reflect (prior to trainz-build v5.6)
* onetex
* notex (prior to trainz-build v5.6)
* additive
* pbrmetal (at or above v4.6)
* pbrmetalmasked (at or above v4.6)
* pbrmetaldetail (at or above v4.6)
* leafcard (at or above v5.6)
* clutter (at or above v4.6)
* glass (at or above v4.6)
* leafcardbillboard (at or above v5.6)
* foliage (at or above v5.4)

Unknown material types result in a warning at trainz-build versions prior to v4.6, and an error since then.

==Legacy Trainz IM Mesh Files==
The mesh file reader looks for the last occurrence of a period (".") character in the material name, and then uses the characters after that as the material type. The comparison is case sensitive. The supported material types are:
* tbumptex
* tbumpenv
* gloss
* tbumpgloss
* reflect
* onetex
* notex

Unknown material types result in a warning.

[[Category:Validation Errors]]

DXT Compression

2025-11-24T00:38:51Z

Windwalkr: Remove some incorrect info.

The following are the DXT formats used in the Trainz (N3V) binary textures.

===DXT1 Compression===
DXT1 stores 16 input pixels in 64 bits of output, consisting of two 16-bit RGB 5:6:5 colour values and a 4x4 two bit lookup table.

If the first colour value (c0) is numerically greater than the second colour value (c1) then the two other colours are calculated, such that

c2 = 2/3*c0 + 1/3*c1 and c3=1/3*c0 + 2/3*c1

Otherwise if c0 <= c1 then c2 = 1/2*c0 + 1/2*c1 and c3 is transparent.

The lookup table is then consulted to determine the colour value of each pixel, with a value of 0 corresponding to c0 and a value of 3 corresponding to c3. DXT1 does not store alpha data enabling higher compression ratio of 8:1. DXT1 can be used for masked alpha textures.

===DXT3 Compression===
DXT3 converts 16 input pixels to 128 bits of output, consisting of 64 bit of alpha channel data (four bits for each pixel) followed by 64 bits of colour data encoded the same way as DXT1 (with the exception that the 4 colour version of DXT1 algorithm is always used instead of deciding which version to use based on the relative values of c0 and c1).

Typically DTX3 is well suited to images with sharp alpha transitions, between translucent and opaque areas. Compression ratio is 4:1.

===DXT5 Compression===
DXT5 converts 16 input pixels to 128 bits of output, consisting of 64 bits of alpha channel data (two 8 bit alpha values and a 4x4 3 bit lookup table) followed by 64 bits of colour data (encoded the same way as DXT3).
If a0 > a1, then six other alpha values are calculated, such that

a2 =(6a0 + a1)/7, a3 =(5a0 + 2a1)/7, a4 =(4a0 + 3a1)/7, a5 =(3a0 + 4a1)/7, a6 =(2a0 + 5a1)/7, a7 = (a0 + 6a1)/7

Otherwise, if a0 <= a1, four other alpha values are calculated as

a2 =(4a0 + a1)/5, a3 =(3a0 + 2a1)/5, a4 =(2a0 + 3a1)/5, a5 =(a0 + 4a1)/5, with a6 = 0, and a7 = 255.

The lookup table is then consulted to determine the alpha values for each pixel, with a value of 0 corresponding to a0 and a value of 7 corresponding to a7.

Because DXT5 uses an interpolated alpha scheme it generally produces superior results for alpha (transparency) gradients than DXT3.

Some consider DXT5 to be the most flexible general purpose compression codec. Compression ratio is 4:1.

Texture file

2024-10-01T04:37:05Z

Windwalkr:

{{ORP-top}}
Trainz '''Texture files''' are ASCII text format specification files describing a single texture. Texture files have a ".texture.txt" name extension, however when a texture file is specified within a [[config.txt file]] or similar, the ".txt" must be omitted (as you are specifying a resource name, not a file path), leaving only the ".texture" extension.

Texture files (*.texture.txt) should be distinguished from [[image file]]s (*.tga, etc.) and [[material]]s. A material may utilize zero or more texture files, and a texture file may utilize one or more image files. While we often refer to the image data as "a texture", this usage isn't strictly correct as any given texture also has a number of metadata attributes which are not present in the source image. Additionally, a texture may be compressed (at installation time) which may actually lose some of the data originally present in the source image.

When importing a [[trainzmesh file]] from an [[FBX file]], any image files referenced in the FBX which do not already have corresponding texture files will have generic texture files created automatically. These files may be suitable for basic purposes, but may need to be customized for more advanced functionality. Once the file has been created (and optionally customised) the importer will not recreate/overwrite it on subsequent runs.

This page describes [["Trainz-build" number|content format v5.6]].

=File format=

The user-editable *.texture.txt files are ASCII text formatted key-value pairs with the following options. Please note that this format is not the same (despite some similarities) as other text-based formats used by Trainz. Please be aware of the [[filename character restrictions]] when naming texture and image files.

;Syntax
Each key is specified on a new line. There is no white space anywhere in the line. A empty value is sometimes valid. The syntax is:

<key>=<value>

;Example:
Primary=WayCoolTexture.tga
Alpha=WayCoolTexture.tga
Tile=st
UsageHint=albedo
AlphaHint=semitransparent
MipAlgorithm=heavy-alpha
''(Example only, not recommended settings)''

==Keys and Values==

Primary=diffusemap.bmp

This tag specifies the filename of the image file representing the color (R, G, B) channels of the texture. Any alpha channel in the image file is ignored. The resultant texture will have a pure white (100%) alpha channel.

Primary=diffusemap.jpg
Alpha=diffusemap.bmp

This tag combination specifies the filenames of the image file representing the color (R, G, B) channels of the texture (Primary) and the image file representing the transparency of the texture (Alpha). The Alpha image should be grayscale. Neither file should contain an alpha (A) channel (ie, both images should be 24-bit). The two image files must be of identical size.

Primary=diffusemap.tga
Alpha=diffusemap.tga

This tag combination specifies the filename of a single image file representing the color and transparency (R, G, B, A) channels of the texture. In this case both tags must reference the same filename. The image file must contain an alpha channel.

Compression=dxt3

This tag hints the usage of a particular texture compression scheme. If you don't have a specific effect in mind, don't include this tag. Valid options are currently 'none', 'dxt1', 'dxt3', 'dxt5'. Refer [[DXT Compression]].

The current selection logic for texture compression is as follows, however it should be noted that this may change between Trainz versions. The first matching rule is used.

* Special texture formats (such as HDR) which don't support compression are stored uncompressed.
* "Compression=none" forces no compression. This gives the best visual result for a given input image, but typically yields worse visual results per output texture filesize. It is often better to activate compression and double the image dimensions, rather than disabling compression.
* Images with an "opaque" alpha hint use DXT1 compression.
* "Compression=dxt3" will use DXT3 compression.
* DXT5 compression is used.

NormalMapHint=normalmap

The 'NormalMapHint' tag allows the texture to be specified as a [[normal map]]. By default, Trainz will assume that your texture is a [[diffuse map]] and will apply some processing options which are not appropriate for normal maps. You must specify this option for normal maps. Valid options are 'none' and 'normalmap'.

ModifyMap=flipgreen

The 'ModifyMap' option allows a texture's green color channel to be flipped. Some programs such as [[Autodesk 3ds Max]] create [[normal map]]s with the Y axis facing the opposite way to what is expected by the Trainz shaders. This option can be used to make the bump effect look correct in Trainz. Valid options are 'none' and 'flipgreen'.

AlphaHint=opaque

The 'AlphaHint' tag allows you to force a particular alpha mode on the texture. Valid options are 'opaque' (meaning that the alpha channel is overwritten with pure white), 'semitransparent' (meaning that the alpha channel is a grayscale blend) and 'masked' (meaning that the alpha channel is clamped to a pure black&white bitmap based on a 50% threshold.) If omitted, Trainz will supply an appropriate value for this tag based on the actual contents of the Alpha channel.

Tile=st

Tiling refers to the ability for texture coordinates outside the range of (0.0 .. 1.0) to be treated as valid coordinates on an infinitely tiled texture. With tiling active, coordinates which pass the right/bottom side of the texture effectively wrap back onto the left/top side, and so on. Valid options include 's' (tile horizontally), 't' (tile vertically), 'st' (tile both horizontally and vertically), and 'none' (do not tile the image).

UsageHint=albedo

Textures are processed slightly differently depending on their intended use in the rendering pipeline. Valid options are 'albedo', 'normal', and 'parameter'. If no usage hint is supplied, the game will attempt to guess the ideal processing steps based on other clues, which may lead to undesirable outcomes if the guesses are wrong.

MipAlgorithm=weight-by-alpha

Specifies the [[mipmap]] generation algorithm to use for the texture. Valid options are 'weight-by-alpha', 'no-weight-by-alpha', and 'heavy-alpha'. If not specified, the 'UsageHint' for the texture is consulted to determine the default behaviour; for albedo textures the 'weight-by-alpha' mechanism is used, while other textures default to 'no-weight-by-alpha'. The 'weight-by-alpha' mechanism treats the alpha channel as an opacity and prioritizes opaque texels over transparent ones. The "no-weight-by-alpha" hint can be used to ensure that the game will give equal weighting to texels regardless of their alpha channel, which is desirable if the alpha channel does not represent opacity. The 'heavy-alpha' mechanism effectively increases the alpha channel on lower mip levels, which is useful on semitransparent foliage (eg. most trees) to avoid the tree appearing overly transparent in the distance.

The value of this key is only relevant where [[Content Manager]] is responsible for producing mipmap images. It is not relevant on any mipmap images provided in the source images.

nonpoweroftwo=1

By default, all textures must have both their width and height as a power of two (eg. 8, 16, 32, 64, 128, 256, 512, 1024, 2048), though they need not be square. Setting the value '1' for the 'nonpoweroftwo' key allows this restriction to be relaxed. This is currently considered experimental and may have unexpected performance, quality, or functionality outcomes. It is not recommended that end-users utilize this format at the current time.

Non-power-of-two (NPOT) textures may not support mipmapping and thus may be noticeably affected by the moire effect in addition to having higher overall GPU bandwidth requirements.

=Texture Formats=
The following texture formats are supported internally by Trainz on desktop platforms.
* R8 G8 B8 A8
* DXT1
* DXT3
* DXT5
* R32F G32F B32F A32F

The selection of internal format depends on the source image format and the value of the 'Compression' key.

=Texture Size=
Textures must be no more than 4096 pixels in either dimension, although it is strongly recommended that textures are kept below this maximum to avoid performance problems. Small objects should typically use approximately 512x512. Large, highly detailed objects such as train vehicles or ground textures will typically use 2048x2048.
Uniform-color textures (ie. textures in which all [[texel]]s have the same color) should be 8x8, 2x2, or 1x1.
Textures must be a power-of-two size in each dimension (unless the 'nonpoweroftwo' key is activated), but need not be square. Some materials may give unexpected results for non-square textures; consult the material-specific documentation for details.

=Source Image Formats=
The following image formats are acceptable as source data for the texture file. Note that these formats are not used at runtime, and that format-specific benefits such as compression will apply to the DLS download size of the content but not to the runtime memory footprint or GPU bandwidth usage.

* Targa (.tga) files. Targa is a lossless image format with optional compression and optional alpha channel. This is a sensible choice where compatibility with older versions of Trainz is desired.
* JPEG (.jpg) files. JPEG is a lossy image compression format with no alpha channel support. This format should generally be avoided since it will typically lead to the image being compressed in a lossy format (JPG), decompressed, recompressed again into another lossy format (DXT1), losing detail at each stage. Worse, if JPEG files are used during the creation of the image, each edit-save-test cycle may result in a loss of image quality.
* Windows Bitmap (.bmp) files. BMP is a lossless image format with no compression and optional alpha channel. This format should generally be avoided since it does not offer compression and has no redeeming benefits.
* HDR (.hdr) files. HDR is a lossless image format with 32 bits of precision per channel. The R32F G32F B32F A32F internal texture format is used, and texture compression is not supported. This is a very expensive format (in terms of memory and performance) and should only be used where absolutely essential. Textures created in this format should be kept as small as possible (eg. 256-512 pixels wide and high) but at least 8x8 pixels wide and high.
* PNG (.png) files. PNG is a lossless compressed image format with alpha channel support. This is the best choice where compatibility with older versions of Trainz is not required.
* DDS (.dds) files. This has very limited support intended for specific internal purposes; it is not recommended that end-users utilize this format at the current time.

All images which comprise a given texture must have identical dimensions (width, height).

Source images should use the SRGB color space except where material-specific documentation indicates otherwise.

=Notes on Image Editors=
* The Targa Exporter plugin shipped with some older versions of Adobe Photoshop is broken and silently corrupts or discards alpha channels; a free update is available which resolves this issue.
* Some image editors do not support alpha channels on BMP files.
* By default, Photoshop does not allow for explicit editing of the alpha channel in PNG images. There is a free plugin called [https://www.fnordware.com/superpng/ SuperPNG] which integrates better PNG support to enable saving and editing of PNG alpha masks.
* [http://www.amnoid.de/ddsview/ ddsview ] is an open source image editor that can properly open all of the texture formats used by Trainz. This is an easy tool to quickly convert between PNG parameters and TGA parameters.

=*.txt File Extension=
Texture files have a ".texture.txt" name extension, however when a texture file is specified within a [[config.txt file]] or similar, the ".txt" must be omitted, leaving the ".texture" extension.
For example, a texture file named ''grass.texture.txt'' is specified in a [[KIND Groundtexture]] config file using the syntax ''texture "grass.texture"''.

=Use of Image Files in Place of Texture Files=
Trainz previously supported using ''any supported image file'' type in place of a [[Texture file]]. [[TANE]] does not support this technique; a texture.txt file must be used.

[[Category:File formats]]
[[Category:Modeling]]
[[Category:Content creation]]
{{ORP-bot}}

Category:Validation Errors

2024-08-09T02:57:40Z

Windwalkr:

Validation Error (VE) numbers are logged during content validation, to allow users to look up particular validation messages to better understand the source of the problem. Normal logs provide a substantial amount of technical detail about the error, but typically assume that the reader is familiar with the subject matter and will understand why the log is relevant. This wiki provides the necessary background information to understanding many of the logs, however a user who is unfamiliar with the area in question may not know where to start looking. VE numbers allow users to quickly find relevant pages in the wiki without any prior knowledge of the subject.

This page serves as a master guide to all VE numbers currently logged by Trainz. This page does not provide detailed information on any given VE number- please refer to the individual VE number pages for specific details. The error text here is correct for the English localisation of Trainz at the time of writing, however the exact text may change from time to time. It is intended that the overall meaning of a VE number will never change- new VE numbers will be issued instead, and old VE numbers may be made obsolete.

Logs which lack VE numbers do not belong on this page.

The individual VE pages can be found at the links below, or can be accessed directly from [[Content Manager]] by right-clicking on the Validation Error in the results log, and selecting "View Help for This Message".

{|
|-
|1||[[Help:VE1|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Decimal value."]]
|-
|2||[[Help:VE2|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Integer value."]]
|-
|3||[[Help:VE3|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|4||[[Help:VE4|"'$(TAG_NAME)' must have a positive value."]]
|-
|5||[[Help:VE5|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|6||[[Help:VE6|"'$(TAG_NAME)' must not be zero."]]
|-
|7||[[Help:VE7|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|8||[[Help:VE8|"The value for '$(TAG_NAME)' must be between '$(MIN)' and '$(MAX)' but was specified as '$(VALUE)'."]]
|-
|9||[[Help:VE9|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|10||[[Help:VE10|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|11||[[Help:VE11|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|12||[[Help:VE12|"No string-table entry found with tag '$(VALUE)' for for string-token tag '$(TAG)'."]]
|-
|13||[[Help:VE13|"Missing or invalid selection for tag '$(TAG_NAME)' in '$(CONT_NAME)'."]]
|-
|14||[[Help:VE14|"Missing or invalid selection for tag '$(TAG_NAME)' in '$(CONT_NAME)'."]]
|-
|15||[[Help:VE15|"Attachment point '$(TAG_NAME)' in '$(CONT_NAME)' must be found in mesh '$(MESH_NAME)'."]]
|-
|16||[[Help:VE16|"Container '$(CONT_NAME)' does not have an 'att-parent' tag which is required to reference an attachment point."]]
|-
|17||[[Help:VE17|"Attachment point '$(TAG_NAME)' in '$(CONT_NAME)' must be found in mesh '$(MESH_NAME)'."]]
|-
|18||[[Help:VE18|"Attachment point '$(TAG_VAL)' referenced by tag '$(TAG_NAME)' in '$(CONT_NAME)' was not found."]]
|-
|19||[[Help:VE19|"Effect '$(EFFECT_NAME)' in '$(CONT_NAME)' was not found within the mesh table."]]
|-
|20||[[Help:VE20|"Mesh '$(MESH_NAME)' referenced in '$(CONT_NAME)' was not found within the mesh table."]]
|-
|21||[[Help:VE21|"Attachment point '$(TAG_VAL)' referenced by tag '$(TAG_NAME)' in '$(CONT_NAME)' was not found."]]
|-
|22||[[Help:VE22|"Missing or invalid selection for tag '$(TAG_NAME)' in '$(CONT_NAME)'."]]
|-
|23||[[Help:VE23|"Invalid tag name '$(TAG_NAME)' in container '$(CONT_NAME)'."]]
|-
|24||[[Help:VE24|"Invalid tag name '$(TAG_NAME)' in container '$(CONT_NAME)'."]]
|-
|25||[[Help:VE25|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|26||[[Help:VE26|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|27||[[Help:VE27|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' must have a mesh file extension."]]
|-
|28||[[Help:VE28|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' must have an image file extension."]]
|-
|29||[[Help:VE29|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' must have an animation file extension."]]
|-
|30||[[Help:VE30|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' refers to a nonexistent file: '$(FILENAME)'."]]
|-
|31||[[Help:VE31|"Invalid tag name '$(TAG_NAME)' in container '$(CONT_NAME)'."]]
|-
|32||[[Help:VE32|"Alias mesh requires valid parent asset."]]
|-
|33||[[Help:VE33|"Alias mesh '$(FILE)' not found in dependency $(KUID)."]]
|-
|34||[[Help:VE34|"Alias mesh '$(FILE)' not found in latest version ($(NEW_KUID)) of dependency $(OLD_KUID)."]]
|-
|35||[[Help:VE35|"Required alias mesh asset $(KUID) is missing and cannot be validated."]]
|-
|36||[[Help:VE36|"The texture '$(FILE)' failed to load."]]
|-
|37||[[Help:VE37|"The texture '$(FILE)' is not a power of 2, please resize it."]]
|-
|38||[[Help:VE38|"The texture '$(FILE)' is not square. Cubemap textures need to have the same width and height."]]
|-
|39||[[Help:VE39|"The texture '$(FILE)' is a uniform color."]]
|-
|40||[[Help:VE40|"Unable to load $(TYPE) texture '$(TEXTURE)' for texture file '$(FILE)'."]]
|-
|41||[[Help:VE41|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Integer value."]]
|-
|42||[[Help:VE42|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Decimal value."]]
|-
|43||[[Help:VE43|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Boolean value."]]
|-
|44||[[Help:VE44|"Tag '$(TAG_NAME)' in the container '$(CONT_NAME)' is obsolete."]]
|-
|45||[[Help:VE45|"The Tag '$(TAG_NAME)' is not permitted within a container of type '$(CONT_NAME)'."]]
|-
|46||[[Help:VE46|"Internal Error: The template does not specify that a smoke container is valid in the container being parsed."]]
|-
|47||[[Help:VE47|"Container '$(CONT_NAME)' is not permitted in this section."]]
|-
|48||[[Help:VE48|"This asset uses an obsolete trainz-build number. Trainz-build numbers below $(LOWEST_TRAINZBUILD) are no longer supported."]]
|-
|49||[[Help:VE49|"Required tag 'kind' is not present. Ensure this is a valid config file."]]
|-
|50||[[Help:VE50|"Unsupported kind '$(KIND)'."]]
|-
|51||[[Help:VE51|"Tag '$(TAG_NAME)' in the container '$(CONT_NAME)' is obsolete."]]
|-
|52||[[Help:VE52|"The Tag '$(TAG_NAME)' is not permitted within a container of type '$(CONT_NAME)'."]]
|-
|53||[[Help:VE53|"This container is no longer supported."]]
|-
|54||[[Help:VE54|"The Tag '$(TAG_NAME)' is not permitted within a container of type '$(CONT_NAME)'."]]
|-
|55||[[Help:VE55|"This container is no longer supported."]]
|-
|56||[[Help:VE56|"Container '$(CONT_NAME)' is not permitted in this section."]]
|-
|57||[[Help:VE57|"Container '$(CONT_NAME)' is not permitted in this section."]]
|-
|58||[[Help:VE58|"The tag '$(TAG_NAME)' is not a valid container type (expected '$(TYPE)')."]]
|-
|59||[[Help:VE59|"Internal error: unknown dataType - kind '$(KIND)'."]]
|-
|60||[[Help:VE60|"Required tag '$(TAG_NAME)' was missing and has been set to default."]]
|-
|61||[[Help:VE61|"Required tag '$(TAG_NAME)' was missing and has been set to default."]]
|-
|62||[[Help:VE62|"Required container '$(CONT_NAME)' is missing."]]
|-
|63||[[Help:VE63|"The cubemap texture '$(FILE)' has missing images. Please verify the texture.txt file."]]
|-
|64||[[Help:VE64|"Cubemap texture '$(FILE)' contains images of different sizes."]]
|-
|65||[[Help:VE65|"The *.texture.txt file is missing for texture resource '$(FILE)'."]]
|-
|66||[[Help:VE66|"The texture file '$(FILE)' contains non-ANSI characters. Textures must be ANSI."]]
|-
|67||[[Help:VE67|"The texture '$(FILE)' does not seem to have a primary texture set. Please verify the texture.txt file."]]
|-
|68||[[Help:VE68|"The primary and alpha texture are not the same size for '$(FILE)'."]]
|-
|69||[[Help:VE69|"Binary conversion failed for texture resource '$(FILE)'."]]
|-
|70||[[Help:VE70|"The KUID tag is not a valid KUID value: '$(string)'."]]
|-
|71||[[Help:VE71|"Unsupported SpeedTree version for mesh: $(FILE)"]]
|-
|72||[[Help:VE72|"Unable to load mesh file: '$(FILE)'"]]
|-
|73||[[Help:VE73|"Image file '$(FILE)' is incorrectly used as both a texture.txt source file and a raw image file."]]
|-
|74||[[Help:VE74|"Image file '$(FILE)' is incorrectly used as both a texture.txt source file and a raw image file."]]
|-
|76||[[Help:VE76|"Unable to load mesh file: '$(FILE)'"]]
|-
|77||[[Help:VE77|"Unable to load indexed mesh '$(FILE)'"]]
|-
|79||[[Help:VE79|"Unable to load animation file '$(FILE)' (mesh has not been loaded correctly)."]]
|-
|81||[[Help:VE81|"The high-poly mesh '$(FILE)' should have LOD levels."]]
|-
|82||[[Help:VE82|"High-detail .im files are not supported for traincar assets, as they are likely to perform poorly. It is recommended that you upgrade '$(FILE)' to a .lm file."]]
|-
|83||[[Help:VE83|"The file '$(FILE)' is provided in LM format despite having no attachment points and no animation support. This may have a negative impact on performance."]]
|-
|84||[[Help:VE84|"The file '$(FILE)' is provided in LM format despite containing only a single mesh. This may have a negative impact on performance."]]
|-
|85||[[Help:VE85|"The file '$(FILE)' is provided in LM format, however the high-detail mesh is comprised of less than 300 polygons. This may have a negative impact on performance."]]
|-
|86||[[Help:VE86|"Legacy .pm files are no longer supported, and will perform poorly. It is recommended that you switch to using a .lm file."]]
|-
|87||[[Help:VE87|"Legacy .pm files are no longer supported, and will perform poorly. It is recommended that you switch to using a .lm file."]]
|-
|88||[[Help:VE88|"This asset has a trainz-build number which is not recognised by this tool."]]
|-
|89||[[Help:VE89|"Tag '$(TAG_NAME)' in the container '$(CONT_NAME)' is obsolete."]]
|-
|90||[[Help:VE90|"This asset has an invalid KUID user id"]]
|-
|91||[[Help:VE91|"The dependency $(KUID) has an invalid KUID User ID and cannot be used"]]
|-
|92||[[Help:VE92|"Duplicate '$(TAG_NAME)' containers in '$(CONT_NAME)'. Containers must have a unique name."]]
|-
|93||[[Help:VE93|"Duplicate '$(TAG_NAME)' tags in '$(CONT_NAME)'. Tags must have a unique name."]]
|-
|94||[[Help:VE94|"This asset requires a shadow mesh, but the mesh table does not contain one."]]
|-
|95||[[Help:VE95|"This asset does not have a mesh that is visible by default."]]
|-
|96||[[Help:VE96|"Maximum of 5 running number fonts supported."]]
|-
|97||[[Help:VE97|"The running number font directory '$(DIR)' could not be found."]]
|-
|98||[[Help:VE98|"The running number font file '$(DIR)/$(FILE)' could not be found."]]
|-
|99||[[Help:VE99|"The track-sound container '$(NAME)' has no bogey, track or track-parent tag."]]
|-
|100||[[Help:VE100|"Required tag '$(TAG_NAME)' was missing and has been set to default."]]
|-
|101||[[Help:VE101|"The file '$(FILE)' does not exist."]]
|-
|102||[[Help:VE102|"Failed to load sound file '$(FILE)', please ensure this is a valid wav file."]]
|-
|103||[[Help:VE103|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|104||[[Help:VE104|"Multiple template property bindings for rule property '$(PROP)' for rule '$(RULE)'."]]
|-
|105||[[Help:VE105|"The template property '$(NAME)' specified in the rule-template-bindings container of rule '$(RULE)' does not exist."]]
|-
|106||[[Help:VE106|"The high-detail meshes in season $(SEASON) total more than $(LIMIT) polygons. This may have a negative impact on performance: $(LOD_SUMMARY)"]]
|-
|107||[[Help:VE107|"The high-detail meshes total more than $(LIMIT) polygons. This may have a negative impact on performance: $(LOD_SUMMARY)"]]
|-
|108||[[Help:VE108|"The low-detail meshes in season $(SEASON) total more than 500 polygons. This may have a negative impact on performance: $(LOD_SUMMARY)"]]
|-
|109||[[Help:VE109|"The low-detail meshes total more than 500 polygons. This may have a negative impact on performance: $(LOD_SUMMARY)"]]
|-
|110||[[Help:VE110|"The meshes in LOD level $(LOD_LEVEL) in season $(SEASON) must total at least 20% fewer polygons than the next higher LOD in the same season: $(LOD_SUMMARY)"]]
|-
|111||[[Help:VE111|"The meshes in LOD level $(LOD_LEVEL) must total at least 20% fewer polygons than the next higher LOD: $(LOD_SUMMARY)"]]
|-
|112||[[Help:VE112|"Multiple track stretches between '$(FROM_VERTEX)' and '$(TO_VERTEX)' in container '$(CONT_NAME)'. Track stretches must be unique."]]
|-
|113||[[Help:VE113|"An image file ('$(FILE)') has been supplied where a texture file ('*.texture.txt') is required."]]
|-
|114||[[Help:VE114|"An image file ('$(FILE)') has been supplied where a texture file ('*.texture.txt') is required."]]
|-
|115||[[Help:VE115|"The texture file '$(FILE)' does not exist."]]
|-
|116||[[Help:VE116|"No texture file has been specified for this texture asset."]]
|-
|117||[[Help:VE117|"'$(TAG_0)' must be set to a '$(KIND)' for '$(TAG_1)' to be allowed."]]
|-
|118||[[Help:VE118|"Tag '$(TAG_0)' requires that '$(TAG_1)' be set to '$(KIND)'."]]
|-
|119||[[Help:VE119|"The tag '$(TAG_NAME)' is not valid for kind '$(KIND)'."]]
|-
|120||[[Help:VE120|"Tag '$(TAG_0)', requires the tag '$(TAG_1)' to be present."]]
|-
|121||[[Help:VE121|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|122||[[Help:VE122|"'$(TAG_NAME)' must have a positive value."]]
|-
|123||[[Help:VE123|"The script file '$(FILE)' does not exist."]]
|-
|124||[[Help:VE124|"The file '$(FILE)' does not exist."]]
|-
|125||[[Help:VE125|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|126||[[Help:VE126|"'$(TAG_NAME)' must not be zero."]]
|-
|127||[[Help:VE127|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|128||[[Help:VE128|"The value for '$(TAG_NAME)' must be between '$(MIN)' and '$(MAX)' but was specified as '$(VALUE)'."]]
|-
|129||[[Help:VE129|"Incorrect number of values for the tag '$(TAG_NAME)', expected $(NUM_0) values, found $(NUM_1)."]]
|-
|130||[[Help:VE130|"Too many values for the tag '$(TAG_NAME)', maximum is $(MAX) values, found $(FOUND)."]]]]
|-
|131||[[Help:VE131|"Value must be a mesh from the mesh-table (not a parent container)."]]
|-
|132||[[Help:VE132|"The attachment point '$(ATT)' must belong to the parent mesh of the effect (mesh=$(MESH))."]]
|-
|133||[[Help:VE133|"A light container must be present to link the signals."]]
|-
|134||[[Help:VE134|"'$(NUM)' must be a valid light number from the light container."]]
|-
|135||[[Help:VE135|"'$(TAG_0)' requires that the tag '$(TAG_1)' be present."]]
|-
|136||[[Help:VE136|"'$(TAG_0)' requires that the tag '$(TAG_1)' be present."]]
|-
|137||[[Help:VE137|"Empty or invalid running number specified at character index $(INDEX)"]]
|-
|138||[[Help:VE138|"Running number specified at character index $(INDEX) is too large, must be less than 9 characters."]]
|-
|139||[[Help:VE139|"Invalid running number range specified at character index $(INDEX), ($(FROM)-$(TO))."]]
|-
|140||[[Help:VE140|"Running number range '$(FROM)-$(TO)' specified at character index $(INDEX) overlaps already in use numbers, running numbers must be unique."]]
|-
|141||[[Help:VE141|"Running number '$(NUMBER)' specified at character index $(INDEX) is already in use."]]
|-
|142||[[Help:VE142|"Invalid character '$(CHAR)' specified in running number list, only numbers, ',' and '-' are supported."]]
|-
|143||[[Help:VE143|"Possible running number list is too large, the set must contain less than 20000 possibilities."]]
|-
|144||[[Help:VE144|"Category code 'ZX - Paintshed template' is obsolete."]]
|-
|145||[[Help:VE145|"Category code 'ZX - Paintshed template' is obsolete."]]
|-
|146||[[Help:VE146|"An asset must be specified for tag '$(TAG_NAME)'."]]
|-
|147||[[Help:VE147|"The tag(s) $(MISPLACED_TAGS) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|148||[[Help:VE148|"The tag(s) $(MISPLACED_TAGS) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|149||[[Help:VE149|"The mesh(es) $(MISPLACED_MESHES) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|150||[[Help:VE150|"The mesh(es) $(MISPLACED_MESHES) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|151||[[Help:VE150|"The mesh(es) $(MISPLACED_MESHES) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|152||[[Help:VE152|"The tags $(MISSING_TAGS) are not all defined. The default values will be used and the positions of the elements may not fit your track."]]
|-
|153||[[Help:VE153|"The mesh $(MESH) is present but the tag $(MISSING_TAG) is not defined."]]
|-
|154||[[Help:VE154|"The mesh $(MESH) is present but the tag $(MISSING_TAG) is not defined."]]
|-
|155||[[Help:VE155|"The mesh $(MESH) is present but the tags $(MISSING_TAGS) are not all defined."]]
|-
|156||[[Help:VE156|"The tag $(MISSING_TAG) is not defined. The default value will be used and the positions of the elements may not fit your track."]]
|-
|157||[[Help:VE157|"The mesh $(MESH) is present but the tag $(MISSING_TAG) is missing. The default value will be used and the positions of the elements may not fit your track."]]
|-
|158||[[Help:VE158|"Unable to open .lm.txt file: $(FILE)"]]
|-
|159||[[Help:VE159|"Unable to parse .lm.txt file: $(FILE)"]]
|-
|160||[[Help:VE160|"No 'mesh' keys found in .lm.txt file: $(FILE)"]]
|-
|161||[[Help:VE161|"$(LODCOUNT) LODs in .lm.txt file: $(FILE)"]]
|-
|162||[[Help:VE162|"One of the LOD reductions of '$(FILE)' introduces a new attachment point: $(ATT)"]]
|-
|163||[[Help:VE163|"Unable to parse .im file: $(FILE)"]]
|-
|164||[[Help:VE164|"Invalid position data in .im file: $(FILE)"]]
|-
|165||[[Help:VE165|"Texture '$(TEXTURE)' is missing or could not be loaded in mesh '$(FILE)', material '$(MATERIAL)'."]]
|-
|166||[[Help:VE166|"$(COMBINEDCOUNT) combined chunks (of $(SOURCECOUNT) source) in .im file: $(FILE)"]]
|-
|167||[[Help:VE167|"Source image texture file '$(TEXTUREFILE)' is too large for '$(ASSETFILE)' ($(WIDTH)x$(HEIGHT))"]]
|-
|168||[[Help:VE168|"File '$(TEXTUREFILE)' is not a valid compiled texture file for '$(ASSETFILE)'"]]
|-
|169||[[Help:VE169|"Compiled texture file '$(TEXTUREFILE)' is unsupported version for '$(ASSETFILE)'"]]
|-
|170||[[Help:VE170|"Failed to open compiled texture '$(TEXTUREFILE)' for '$(ASSETFILE)'"]]
|-
|171||[[Help:VE171|"Expected texture file type but found '$(TEXTUREFILE)' for '$(ASSETFILE)'"]]
|-
|172||[[Help:VE172|"Script class does not match asset kind ($(KIND))."]]
|-
|173||[[Help:VE173|"Material '$(MATERIAL)' in mesh '$(FILE)' is not of a recognised material type."]]
|-
|174||[[Help:VE174|"MeshObjectSpec::LinkSpecs> Mesh-table element #$(MESH_INDEX) parent mesh is invalid."]]
|-
|175||[[Help:VE175|"MeshObjectSpec::LinkSpecs> Mesh-table element #$(MESH_INDEX) is part of invalid hierarchy."]]
|-
|176||[[Help:VE176|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' must have a texture file extension."]]
|-
|177||[[Help:VE177|"The kuid '$(KUID)' is not in the database, and could not be found in any known location. Ensure that this is a valid asset."]]
|-
|178||[[Help:VE178|"The asset specified in '$(KUID)' is not installed locally but is available for download."]]
|-
|179||[[Help:VE179|"The kuid '$(KUID)' specified in '$(TAG_NAME)' is not of the correct type."]]
|-
|180||[[Help:VE180|"Integrity check failure on $(FILE). One or more route/session tiles may be missing."]]
|-
|181||[[Help:VE181|"The tag '$(TAG_NAME)' requires a minimum asset version of $(MIN_VERSION)"]]
|-
|182||[[Help:VE182|"Material '$(MATERIAL)' in mesh '$(FILE)' is missing a texture for a mandatory texture slot."]]
|-
|183||[[Help:VE183|"FBX file is in an unsupported older format."]]
|-
|184||[[Help:VE184|"KIND '$(KIND)' requires trainz-build $(TRAINZBUILD)."]]
|-
|185||[[Help:VE185|"Material '$(MATERIAL)' in mesh '$(FILE)' has heightmap texture. Provide a normal map instead."]]
|-
|186||[[Help:VE186|"Material '$(MATERIAL)' is shared between multiple chunks in this asset but the material parameters conflict."]]
|-
|187||[[Help:VE187|"The value '$(VALUE)' in not a valid KUID."]]
|-
|188||[[Help:VE188|"Custom render plugin failed to load mesh '$(FILE)'"]]
|-
|189||[[Help:VE189|"Collision data exceeds $(LIMIT)KB. Please specify a different generation method or a simplified mesh."]]
|-
|190||[[Help:VE190|"Tag '$(NAME)' is unable to be converted from $(TYPE1) to $(TYPE2)"]]
|-
|191||[[Help:VE191|"Tag '$(NAME)' does not contain a valid integer: $(VALUE)"]]
|-
|192||[[Help:VE192|"Tag '$(NAME)' does not contain a valid float list: $(VALUE)"]]
|-
|193||[[Help:VE193|"Tag '$(NAME)' does not contain a valid float"]]
|-
|194||[[Help:VE194|"Tag '$(NAME)' does not contain a valid kuid: $(VALUE)"]]
|-
|195||[[Help:VE195|"Unable to parse chunk $(CHUNK_INDEX) in mesh file: $(FILE)"]]
|-
|196||[[Help:VE196|"Failed to load bogey $(KUID)"]]
|-
|197||[[Help:VE197|"Syntax error in script '$(SCRIPT)' for asset $(ASSET)"]]
|-
|198||[[Help:VE198|"Session failed to load route asset: $(KUID)"]]
|-
|199||[[Help:VE199|"Asset $(KUID) failed to load. Unloading resources."]]
|-
|200||[[Help:VE200|"Unable to load mesh $(NAME) for $(ASSET_ID)"]]
|-
|201||[[Help:VE201|"Traincar is missing required attachment point: $(ATT_NAME)"]]
|-
|202||[[Help:VE202|"Parse error reading twinkles file: $(FILE)"]]
|-
|203||[[Help:VE203|"Bad sequence order in $(TAG_NAME) list. Each element must be greater than the last."]]
|-
|204||[[Help:VE204|"Invalid range in $(TAG_NAME) list. Elements must be greater than or equal to $(INC_MIN) and less than $(EXC_MAX)."]]
|-
|205||[[Help:VE205|"Invalid element count in $(TAG_NAME) list. This list must have at least $(COUNT) elements (to match the $(TAG_START) list)."]]
|-
|206||[[Help:VE206|"The season-selector references season '$(SEASON)', but this does not exist in the texture-variants container."]]
|-
|207||[[Help:VE207|"Attached track asset $(CHILD) failed to load."]]
|-
|208||[[Help:VE208|"Attached track asset not specified for track $(INDEX)."]]
|-
|209||[[Help:VE209|"Asset is missing the required 'attached-track' container."]]
|-
|210||[[Help:VE210|"Asset is missing the required 'track' tag."]]
|-
|211||[[Help:VE211|"Asset is missing the required 'road' tag."]]
|-
|212||[[Help:VE212|"Traincar asset must have at least two bogeys."]]
|-
|213||[[Help:VE213|"Traincar asset has invalid bogey placement."]]
|-
|214||[[Help:VE214|"Traincar asset has invalid length."]]
|-
|215||[[Help:VE215|"Asset has an invalid number of LODs: $(LOD_COUNT)"]]
|-
|216||[[Help:VE216|"Material $(MATERIAL) in mesh file $(MESH) has an inappropriate texture slot assigned: $(TEXTURE)"]]
|-
|217||[[Help:VE217|"Material $(MATERIAL) in mesh file $(MESH) has no texture assigned to a required slot: $(TEXTURE)"]]
|-
|218||[[Help:VE218|"Asset has duplicate attached track at track $(INDEX)."]]
|-
|219||[[Help:VE219|"Failed to load driver mesh $(ASSETID)."]]
|-
|220||[[Help:VE220|Generic script compilation error.]]
|-
|221||[[Help:VE221|"$(ASSETID) is faulty and will not be loaded."]]
|-
|222||[[Help:VE222|"Failed to load mesh $(ASSETID)-$(MESHFILE) for TNI plugin renderer."]]
|-
|223||[[Help:VE223|"Unable to create mesh index $(MESHINDEX) for asset $(ASSET)."]]
|-
|224||[[Help:VE224|"Corrupted data in mesh file '$(FILENAME)'."]]
|-
|225||[[Help:VE225|"Failed to query asset details for featured asset."]]
|-
|226||[[Help:VE226|"Failed to upload asset details for featured asset: $(ERRORTEXT)"]]
|-
|227||[[Help:VE227|"Missing image for featured asset."]]
|-
|228||[[Help:VE228|"Failed to read image file for featured asset."]]
|-
|229||[[Help:VE229|"DLC marketing image is missing or incorrectly sized for featured asset."]]
|-
|230||[[Help:VE230|"DLS thumbnail image is missing or incorrectly sized for featured asset."]]
|-
|231||[[Help:VE231|"Failed to open image file for featured asset."]]
|-
|232||[[Help:VE232|"Failed to upload image for featured asset: $(ERRORTEXT)"]]
|-
|233||[[Help:VE233|"One or more featured assets was not provided."]]
|-
|234||[[Help:VE234|"Asset is not present in the featured assets list."]]
|-
|235||[[Help:VE235|"Featured asset is not present in the input."]]
|-
|236||[[Help:VE236|"Featured asset was not available."]]
|-
|237||[[Help:VE237|"Featured asset failed validation."]]
|-
|238||[[Help:VE238|"Featured asset has faulty or missing dependencies."]]
|-
|239||[[Help:VE239|"Featured asset is Base content."]]
|-
|240||[[Help:VE240|"Featured asset is missing an English name or description."]]
|-
|241||[[Help:VE241|"Newly built package is not compatible with previously released version."]]
|-
|242||[[Help:VE242|"Unable to load animation file '$(FILE)' (file not found, or is damaged)."]]
|-
|243||[[Help:VE243|"Failed to submit changes to asset $(ASSET_KUID) due to file access error"]]
|-
|244||[[Help:VE244|"Files in base assets cannot use importers: $(FILE)"]]
|-
|245||[[Help:VE245|"Missing compiled texture: $(FILE)"]]
|-
|246||[[Help:VE246|"Missing source texture: $(FILE)"]]
|-
|247||[[Help:VE247|"Creating default texture.txt file: $(FILE)"]]
|-
|248||[[Help:VE248|"Failed to create *.texture.txt file for source image: $(FILE)"]]
|-
|249||[[Help:VE249|"Failed to compile *.texture.txt file: $(FILE)"]]
|-
|250||[[Help:VE250|"Material Metadata expected data for texture slot '$(SLOT)' of material '$(MATERIAL)' but none found."]]
|-
|251||[[Help:VE251|"Material Metadata expected *.texture resource for texture slot '$(SLOT)' of material '$(MATERIAL)' bout found: $(FOUND)"]]
|-
|252||[[Help:VE252|"Mesh material expected data for texture slot '$(SLOT)' of material '$(MATERIAL)' but none found."]]
|-
|253||[[Help:VE253|"WriteAnimationFileBoneChunk> excessive bone-chunk count."]]
|-
|254||[[Help:VE254|"Unable to open mesh metadata file: $(FILE)"]]
|-
|255||[[Help:VE255|"Mesh contains unsupported non-triangle primitives."]]
|-
|256||[[Help:VE256|"Mesh contains invalid material index."]]
|-
|257||[[Help:VE257|"Mesh contains no primitives."]]
|-
|258||[[Help:VE258|"Unable to determine vertex format."]]
|-
|259||[[Help:VE259|"Unsupported number of texture channels."]]
|-
|260||[[Help:VE260|"Invalid index in primitive."]]
|-
|261||[[Help:VE261|"Unable to create animation file: $(FILE)"]]
|-
|262||[[Help:VE262|"Unable to open animation event file: $(FILE)"]]
|-
|263||[[Help:VE263|"Unable to parse animation event file: $(FILE)"]]
|-
|264||[[Help:VE264|"Parsed animation event file $(FILE) with $(COUNT) events."]]
|-
|265||[[Help:VE265|"Unable to search path: '$(FILE_PATH)'"]]
|-
|266||[[Help:VE266|"Multiple values found for engine spec param <kuid:xxx:yyy>/tag-name (Value1 and Value2)"]]
|-
|267||[[Help:VE267|"member $(MEMBER) is obsolete in object $(CLASS)."]]
|-
|268||[[Help:VE268|"Mesh file is unused in this asset: '$(FILE)'"]]
|-
|269||[[Help:VE269|"Texture table is incorrectly indexed, some textures may be unloadable."]]
|-
|270||[[Help:VE270|"Density LOD multiplier in level $(LEVEL) is not in descending order."]]
|-
|271||[[Help:VE271|"The specified TCB flags are invalid, please check the wiki for valid configurations."]]
|-
|272||[[Help:VE272|"No overridden function found when calling inherited()."]]
|-
|273||[[Help:VE273|"Variable '<variable name>' already declared in this scope."]]
|-
|274||[[Help:VE274|"Variable '<variable name>' already declared in parent scope on class '<class name>'."]]
|-
|275||[[Help:VE275|"Excessive chunk count $(CHUNK_COUNT) in mesh file: $(FILE)"]]
|}

Category:Validation Errors

2024-08-09T02:55:28Z

Windwalkr:

Validation Error (VE) numbers are logged during content validation, to allow users to look up particular validation messages to better understand the source of the problem. Normal logs provide a substantial amount of technical detail about the error, but typically assume that the reader is familiar with the subject matter and will understand why the log is relevant. This wiki provides the necessary background information to understanding many of the logs, however a user who is unfamiliar with the area in question may not know where to start looking. VE numbers allow users to quickly find relevant pages in the wiki without any prior knowledge of the subject.

This page serves as a master guide to all VE numbers currently logged by Trainz. This page does not provide detailed information on any given VE number- please refer to the individual VE number pages for specific details. The error text here is correct for the English localisation of Trainz at the time of writing, however the exact text may change from time to time. It is intended that the overall meaning of a VE number will never change- new VE numbers will be issued instead, and old VE numbers may be made obsolete.

Logs which lack VE numbers do not belong on this page.

The individual VE pages can be found at the links below, or can be accessed directly from [[Content Manager]] by right-clicking on the Validation Error in the results log, and selecting "View Help for This Message".

{|
|-
|1||[[Help:VE1|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Decimal value."]]
|-
|2||[[Help:VE2|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Integer value."]]
|-
|3||[[Help:VE3|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|4||[[Help:VE4|"'$(TAG_NAME)' must have a positive value."]]
|-
|5||[[Help:VE5|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|6||[[Help:VE6|"'$(TAG_NAME)' must not be zero."]]
|-
|7||[[Help:VE7|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|8||[[Help:VE8|"The value for '$(TAG_NAME)' must be between '$(MIN)' and '$(MAX)' but was specified as '$(VALUE)'."]]
|-
|9||[[Help:VE9|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|10||[[Help:VE10|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|11||[[Help:VE11|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|12||[[Help:VE12|"No string-table entry found with tag '$(VALUE)' for for string-token tag '$(TAG)'."]]
|-
|13||[[Help:VE13|"Missing or invalid selection for tag '$(TAG_NAME)' in '$(CONT_NAME)'."]]
|-
|14||[[Help:VE14|"Missing or invalid selection for tag '$(TAG_NAME)' in '$(CONT_NAME)'."]]
|-
|15||[[Help:VE15|"Attachment point '$(TAG_NAME)' in '$(CONT_NAME)' must be found in mesh '$(MESH_NAME)'."]]
|-
|16||[[Help:VE16|"Container '$(CONT_NAME)' does not have an 'att-parent' tag which is required to reference an attachment point."]]
|-
|17||[[Help:VE17|"Attachment point '$(TAG_NAME)' in '$(CONT_NAME)' must be found in mesh '$(MESH_NAME)'."]]
|-
|18||[[Help:VE18|"Attachment point '$(TAG_VAL)' referenced by tag '$(TAG_NAME)' in '$(CONT_NAME)' was not found."]]
|-
|19||[[Help:VE19|"Effect '$(EFFECT_NAME)' in '$(CONT_NAME)' was not found within the mesh table."]]
|-
|20||[[Help:VE20|"Mesh '$(MESH_NAME)' referenced in '$(CONT_NAME)' was not found within the mesh table."]]
|-
|21||[[Help:VE21|"Attachment point '$(TAG_VAL)' referenced by tag '$(TAG_NAME)' in '$(CONT_NAME)' was not found."]]
|-
|22||[[Help:VE22|"Missing or invalid selection for tag '$(TAG_NAME)' in '$(CONT_NAME)'."]]
|-
|23||[[Help:VE23|"Invalid tag name '$(TAG_NAME)' in container '$(CONT_NAME)'."]]
|-
|24||[[Help:VE24|"Invalid tag name '$(TAG_NAME)' in container '$(CONT_NAME)'."]]
|-
|25||[[Help:VE25|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|26||[[Help:VE26|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|27||[[Help:VE27|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' must have a mesh file extension."]]
|-
|28||[[Help:VE28|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' must have an image file extension."]]
|-
|29||[[Help:VE29|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' must have an animation file extension."]]
|-
|30||[[Help:VE30|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' refers to a nonexistent file: '$(FILENAME)'."]]
|-
|31||[[Help:VE31|"Invalid tag name '$(TAG_NAME)' in container '$(CONT_NAME)'."]]
|-
|32||[[Help:VE32|"Alias mesh requires valid parent asset."]]
|-
|33||[[Help:VE33|"Alias mesh '$(FILE)' not found in dependency $(KUID)."]]
|-
|34||[[Help:VE34|"Alias mesh '$(FILE)' not found in latest version ($(NEW_KUID)) of dependency $(OLD_KUID)."]]
|-
|35||[[Help:VE35|"Required alias mesh asset $(KUID) is missing and cannot be validated."]]
|-
|36||[[Help:VE36|"The texture '$(FILE)' failed to load."]]
|-
|37||[[Help:VE37|"The texture '$(FILE)' is not a power of 2, please resize it."]]
|-
|38||[[Help:VE38|"The texture '$(FILE)' is not square. Cubemap textures need to have the same width and height."]]
|-
|39||[[Help:VE39|"The texture '$(FILE)' is a uniform color."]]
|-
|40||[[Help:VE40|"Unable to load $(TYPE) texture '$(TEXTURE)' for texture file '$(FILE)'."]]
|-
|41||[[Help:VE41|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Integer value."]]
|-
|42||[[Help:VE42|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Decimal value."]]
|-
|43||[[Help:VE43|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Boolean value."]]
|-
|44||[[Help:VE44|"Tag '$(TAG_NAME)' in the container '$(CONT_NAME)' is obsolete."]]
|-
|45||[[Help:VE45|"The Tag '$(TAG_NAME)' is not permitted within a container of type '$(CONT_NAME)'."]]
|-
|46||[[Help:VE46|"Internal Error: The template does not specify that a smoke container is valid in the container being parsed."]]
|-
|47||[[Help:VE47|"Container '$(CONT_NAME)' is not permitted in this section."]]
|-
|48||[[Help:VE48|"This asset uses an obsolete trainz-build number. Trainz-build numbers below $(LOWEST_TRAINZBUILD) are no longer supported."]]
|-
|49||[[Help:VE49|"Required tag 'kind' is not present. Ensure this is a valid config file."]]
|-
|50||[[Help:VE50|"Unsupported kind '$(KIND)'."]]
|-
|51||[[Help:VE51|"Tag '$(TAG_NAME)' in the container '$(CONT_NAME)' is obsolete."]]
|-
|52||[[Help:VE52|"The Tag '$(TAG_NAME)' is not permitted within a container of type '$(CONT_NAME)'."]]
|-
|53||[[Help:VE53|"This container is no longer supported."]]
|-
|54||[[Help:VE54|"The Tag '$(TAG_NAME)' is not permitted within a container of type '$(CONT_NAME)'."]]
|-
|55||[[Help:VE55|"This container is no longer supported."]]
|-
|56||[[Help:VE56|"Container '$(CONT_NAME)' is not permitted in this section."]]
|-
|57||[[Help:VE57|"Container '$(CONT_NAME)' is not permitted in this section."]]
|-
|58||[[Help:VE58|"The tag '$(TAG_NAME)' is not a valid container type (expected '$(TYPE)')."]]
|-
|59||[[Help:VE59|"Internal error: unknown dataType - kind '$(KIND)'."]]
|-
|60||[[Help:VE60|"Required tag '$(TAG_NAME)' was missing and has been set to default."]]
|-
|61||[[Help:VE61|"Required tag '$(TAG_NAME)' was missing and has been set to default."]]
|-
|62||[[Help:VE62|"Required container '$(CONT_NAME)' is missing."]]
|-
|63||[[Help:VE63|"The cubemap texture '$(FILE)' has missing images. Please verify the texture.txt file."]]
|-
|64||[[Help:VE64|"Cubemap texture '$(FILE)' contains images of different sizes."]]
|-
|65||[[Help:VE65|"The *.texture.txt file is missing for texture resource '$(FILE)'."]]
|-
|66||[[Help:VE66|"The texture file '$(FILE)' contains non-ANSI characters. Textures must be ANSI."]]
|-
|67||[[Help:VE67|"The texture '$(FILE)' does not seem to have a primary texture set. Please verify the texture.txt file."]]
|-
|68||[[Help:VE68|"The primary and alpha texture are not the same size for '$(FILE)'."]]
|-
|69||[[Help:VE69|"Binary conversion failed for texture resource '$(FILE)'."]]
|-
|70||[[Help:VE70|"The KUID tag is not a valid KUID value: '$(string)'."]]
|-
|71||[[Help:VE71|"Unsupported SpeedTree version for mesh: $(FILE)"]]
|-
|72||[[Help:VE72|"Unable to load mesh file: '$(FILE)'"]]
|-
|73||[[Help:VE73|"Image file '$(FILE)' is incorrectly used as both a texture.txt source file and a raw image file."]]
|-
|74||[[Help:VE74|"Image file '$(FILE)' is incorrectly used as both a texture.txt source file and a raw image file."]]
|-
|76||[[Help:VE76|"Unable to load mesh file: '$(FILE)'"]]
|-
|77||[[Help:VE77|"Unable to load indexed mesh '$(FILE)'"]]
|-
|79||[[Help:VE79|"Unable to load animation file '$(FILE)' (mesh has not been loaded correctly)."]]
|-
|81||[[Help:VE81|"The high-poly mesh '$(FILE)' should have LOD levels."]]
|-
|82||[[Help:VE82|"High-detail .im files are not supported for traincar assets, as they are likely to perform poorly. It is recommended that you upgrade '$(FILE)' to a .lm file."]]
|-
|83||[[Help:VE83|"The file '$(FILE)' is provided in LM format despite having no attachment points and no animation support. This may have a negative impact on performance."]]
|-
|84||[[Help:VE84|"The file '$(FILE)' is provided in LM format despite containing only a single mesh. This may have a negative impact on performance."]]
|-
|85||[[Help:VE85|"The file '$(FILE)' is provided in LM format, however the high-detail mesh is comprised of less than 300 polygons. This may have a negative impact on performance."]]
|-
|86||[[Help:VE86|"Legacy .pm files are no longer supported, and will perform poorly. It is recommended that you switch to using a .lm file."]]
|-
|87||[[Help:VE87|"Legacy .pm files are no longer supported, and will perform poorly. It is recommended that you switch to using a .lm file."]]
|-
|88||[[Help:VE88|"This asset has a trainz-build number which is not recognised by this tool."]]
|-
|89||[[Help:VE89|"Tag '$(TAG_NAME)' in the container '$(CONT_NAME)' is obsolete."]]
|-
|90||[[Help:VE90|"This asset has an invalid KUID user id"]]
|-
|91||[[Help:VE91|"The dependency $(KUID) has an invalid KUID User ID and cannot be used"]]
|-
|92||[[Help:VE92|"Duplicate '$(TAG_NAME)' containers in '$(CONT_NAME)'. Containers must have a unique name."]]
|-
|93||[[Help:VE93|"Duplicate '$(TAG_NAME)' tags in '$(CONT_NAME)'. Tags must have a unique name."]]
|-
|94||[[Help:VE94|"This asset requires a shadow mesh, but the mesh table does not contain one."]]
|-
|95||[[Help:VE95|"This asset does not have a mesh that is visible by default."]]
|-
|96||[[Help:VE96|"Maximum of 5 running number fonts supported."]]
|-
|97||[[Help:VE97|"The running number font directory '$(DIR)' could not be found."]]
|-
|98||[[Help:VE98|"The running number font file '$(DIR)/$(FILE)' could not be found."]]
|-
|99||[[Help:VE99|"The track-sound container '$(NAME)' has no bogey, track or track-parent tag."]]
|-
|100||[[Help:VE100|"Required tag '$(TAG_NAME)' was missing and has been set to default."]]
|-
|101||[[Help:VE101|"The file '$(FILE)' does not exist."]]
|-
|102||[[Help:VE102|"Failed to load sound file '$(FILE)', please ensure this is a valid wav file."]]
|-
|103||[[Help:VE103|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|104||[[Help:VE104|"Multiple template property bindings for rule property '$(PROP)' for rule '$(RULE)'."]]
|-
|105||[[Help:VE105|"The template property '$(NAME)' specified in the rule-template-bindings container of rule '$(RULE)' does not exist."]]
|-
|106||[[Help:VE106|"The high-detail meshes in season $(SEASON) total more than $(LIMIT) polygons. This may have a negative impact on performance: $(LOD_SUMMARY)"]]
|-
|107||[[Help:VE107|"The high-detail meshes total more than $(LIMIT) polygons. This may have a negative impact on performance: $(LOD_SUMMARY)"]]
|-
|108||[[Help:VE108|"The low-detail meshes in season $(SEASON) total more than 500 polygons. This may have a negative impact on performance: $(LOD_SUMMARY)"]]
|-
|109||[[Help:VE109|"The low-detail meshes total more than 500 polygons. This may have a negative impact on performance: $(LOD_SUMMARY)"]]
|-
|110||[[Help:VE110|"The meshes in LOD level $(LOD_LEVEL) in season $(SEASON) must total at least 20% fewer polygons than the next higher LOD in the same season: $(LOD_SUMMARY)"]]
|-
|111||[[Help:VE111|"The meshes in LOD level $(LOD_LEVEL) must total at least 20% fewer polygons than the next higher LOD: $(LOD_SUMMARY)"]]
|-
|112||[[Help:VE112|"Multiple track stretches between '$(FROM_VERTEX)' and '$(TO_VERTEX)' in container '$(CONT_NAME)'. Track stretches must be unique."]]
|-
|113||[[Help:VE113|"An image file ('$(FILE)') has been supplied where a texture file ('*.texture.txt') is required."]]
|-
|114||[[Help:VE114|"An image file ('$(FILE)') has been supplied where a texture file ('*.texture.txt') is required."]]
|-
|115||[[Help:VE115|"The texture file '$(FILE)' does not exist."]]
|-
|116||[[Help:VE116|"No texture file has been specified for this texture asset."]]
|-
|117||[[Help:VE117|"'$(TAG_0)' must be set to a '$(KIND)' for '$(TAG_1)' to be allowed."]]
|-
|118||[[Help:VE118|"Tag '$(TAG_0)' requires that '$(TAG_1)' be set to '$(KIND)'."]]
|-
|119||[[Help:VE119|"The tag '$(TAG_NAME)' is not valid for kind '$(KIND)'."]]
|-
|120||[[Help:VE120|"Tag '$(TAG_0)', requires the tag '$(TAG_1)' to be present."]]
|-
|121||[[Help:VE121|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|122||[[Help:VE122|"'$(TAG_NAME)' must have a positive value."]]
|-
|123||[[Help:VE123|"The script file '$(FILE)' does not exist."]]
|-
|124||[[Help:VE124|"The file '$(FILE)' does not exist."]]
|-
|125||[[Help:VE125|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|126||[[Help:VE126|"'$(TAG_NAME)' must not be zero."]]
|-
|127||[[Help:VE127|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|128||[[Help:VE128|"The value for '$(TAG_NAME)' must be between '$(MIN)' and '$(MAX)' but was specified as '$(VALUE)'."]]
|-
|129||[[Help:VE129|"Incorrect number of values for the tag '$(TAG_NAME)', expected $(NUM_0) values, found $(NUM_1)."]]
|-
|130||[[Help:VE130|"Too many values for the tag '$(TAG_NAME)', maximum is $(MAX) values, found $(FOUND)."]]]]
|-
|131||[[Help:VE131|"Value must be a mesh from the mesh-table (not a parent container)."]]
|-
|132||[[Help:VE132|"The attachment point '$(ATT)' must belong to the parent mesh of the effect (mesh=$(MESH))."]]
|-
|133||[[Help:VE133|"A light container must be present to link the signals."]]
|-
|134||[[Help:VE134|"'$(NUM)' must be a valid light number from the light container."]]
|-
|135||[[Help:VE135|"'$(TAG_0)' requires that the tag '$(TAG_1)' be present."]]
|-
|136||[[Help:VE136|"'$(TAG_0)' requires that the tag '$(TAG_1)' be present."]]
|-
|137||[[Help:VE137|"Empty or invalid running number specified at character index $(INDEX)"]]
|-
|138||[[Help:VE138|"Running number specified at character index $(INDEX) is too large, must be less than 9 characters."]]
|-
|139||[[Help:VE139|"Invalid running number range specified at character index $(INDEX), ($(FROM)-$(TO))."]]
|-
|140||[[Help:VE140|"Running number range '$(FROM)-$(TO)' specified at character index $(INDEX) overlaps already in use numbers, running numbers must be unique."]]
|-
|141||[[Help:VE141|"Running number '$(NUMBER)' specified at character index $(INDEX) is already in use."]]
|-
|142||[[Help:VE142|"Invalid character '$(CHAR)' specified in running number list, only numbers, ',' and '-' are supported."]]
|-
|143||[[Help:VE143|"Possible running number list is too large, the set must contain less than 20000 possibilities."]]
|-
|144||[[Help:VE144|"Category code 'ZX - Paintshed template' is obsolete."]]
|-
|145||[[Help:VE145|"Category code 'ZX - Paintshed template' is obsolete."]]
|-
|146||[[Help:VE146|"An asset must be specified for tag '$(TAG_NAME)'."]]
|-
|147||[[Help:VE147|"The tag(s) $(MISPLACED_TAGS) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|148||[[Help:VE148|"The tag(s) $(MISPLACED_TAGS) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|149||[[Help:VE149|"The mesh(es) $(MISPLACED_MESHES) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|150||[[Help:VE150|"The mesh(es) $(MISPLACED_MESHES) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|151||[[Help:VE150|"The mesh(es) $(MISPLACED_MESHES) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|152||[[Help:VE152|"The tags $(MISSING_TAGS) are not all defined. The default values will be used and the positions of the elements may not fit your track."]]
|-
|153||[[Help:VE153|"The mesh $(MESH) is present but the tag $(MISSING_TAG) is not defined."]]
|-
|154||[[Help:VE154|"The mesh $(MESH) is present but the tag $(MISSING_TAG) is not defined."]]
|-
|155||[[Help:VE155|"The mesh $(MESH) is present but the tags $(MISSING_TAGS) are not all defined."]]
|-
|156||[[Help:VE156|"The tag $(MISSING_TAG) is not defined. The default value will be used and the positions of the elements may not fit your track."]]
|-
|157||[[Help:VE157|"The mesh $(MESH) is present but the tag $(MISSING_TAG) is missing. The default value will be used and the positions of the elements may not fit your track."]]
|-
|158||[[Help:VE158|"Unable to open .lm.txt file: $(FILE)"]]
|-
|159||[[Help:VE159|"Unable to parse .lm.txt file: $(FILE)"]]
|-
|160||[[Help:VE160|"No 'mesh' keys found in .lm.txt file: $(FILE)"]]
|-
|161||[[Help:VE161|"$(LODCOUNT) LODs in .lm.txt file: $(FILE)"]]
|-
|162||[[Help:VE162|"One of the LOD reductions of '$(FILE)' introduces a new attachment point: $(ATT)"]]
|-
|163||[[Help:VE163|"Unable to parse .im file: $(FILE)"]]
|-
|164||[[Help:VE164|"Invalid position data in .im file: $(FILE)"]]
|-
|165||[[Help:VE165|"Texture '$(TEXTURE)' is missing or could not be loaded in mesh '$(FILE)', material '$(MATERIAL)'."]]
|-
|166||[[Help:VE166|"$(COMBINEDCOUNT) combined chunks (of $(SOURCECOUNT) source) in .im file: $(FILE)"]]
|-
|167||[[Help:VE167|"Source image texture file '$(TEXTUREFILE)' is too large for '$(ASSETFILE)' ($(WIDTH)x$(HEIGHT))"]]
|-
|168||[[Help:VE168|"File '$(TEXTUREFILE)' is not a valid compiled texture file for '$(ASSETFILE)'"]]
|-
|169||[[Help:VE169|"Compiled texture file '$(TEXTUREFILE)' is unsupported version for '$(ASSETFILE)'"]]
|-
|170||[[Help:VE170|"Failed to open compiled texture '$(TEXTUREFILE)' for '$(ASSETFILE)'"]]
|-
|171||[[Help:VE171|"Expected texture file type but found '$(TEXTUREFILE)' for '$(ASSETFILE)'"]]
|-
|172||[[Help:VE172|"Script class does not match asset kind ($(KIND))."]]
|-
|173||[[Help:VE173|"Material '$(MATERIAL)' in mesh '$(FILE)' is not of a recognised material type."]]
|-
|174||[[Help:VE174|"MeshObjectSpec::LinkSpecs> Mesh-table element #$(MESH_INDEX) parent mesh is invalid."]]
|-
|175||[[Help:VE175|"MeshObjectSpec::LinkSpecs> Mesh-table element #$(MESH_INDEX) is part of invalid hierarchy."]]
|-
|176||[[Help:VE176|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' must have a texture file extension."]]
|-
|177||[[Help:VE177|"The kuid '$(KUID)' is not in the database, and could not be found in any known location. Ensure that this is a valid asset."]]
|-
|178||[[Help:VE178|"The asset specified in '$(KUID)' is not installed locally but is available for download."]]
|-
|179||[[Help:VE179|"The kuid '$(KUID)' specified in '$(TAG_NAME)' is not of the correct type."]]
|-
|180||[[Help:VE180|"Integrity check failure on $(FILE). One or more route/session tiles may be missing."]]
|-
|181||[[Help:VE181|"The tag '$(TAG_NAME)' requires a minimum asset version of $(MIN_VERSION)"]]
|-
|182||[[Help:VE182|"Material '$(MATERIAL)' in mesh '$(FILE)' is missing a texture for a mandatory texture slot."]]
|-
|183||[[Help:VE183|"FBX file is in an unsupported older format."]]
|-
|184||[[Help:VE184|"KIND '$(KIND)' requires trainz-build $(TRAINZBUILD)."]]
|-
|185||[[Help:VE185|"Material '$(MATERIAL)' in mesh '$(FILE)' has heightmap texture. Provide a normal map instead."]]
|-
|186||[[Help:VE186|"Material '$(MATERIAL)' is shared between multiple chunks in this asset but the material parameters conflict."]]
|-
|187||[[Help:VE187|"The value '$(VALUE)' in not a valid KUID."]]
|-
|188||[[Help:VE188|"Custom render plugin failed to load mesh '$(FILE)'"]]
|-
|189||[[Help:VE189|"Collision data exceeds $(LIMIT)KB. Please specify a different generation method or a simplified mesh."]]
|-
|190||[[Help:VE190|"Tag '$(NAME)' is unable to be converted from $(TYPE1) to $(TYPE2)"]]
|-
|191||[[Help:VE191|"Tag '$(NAME)' does not contain a valid integer: $(VALUE)"]]
|-
|192||[[Help:VE192|"Tag '$(NAME)' does not contain a valid float list: $(VALUE)"]]
|-
|193||[[Help:VE193|"Tag '$(NAME)' does not contain a valid float"]]
|-
|194||[[Help:VE194|"Tag '$(NAME)' does not contain a valid kuid: $(VALUE)"]]
|-
|195||[[Help:VE195|"Unable to parse chunk $(CHUNK_INDEX) in mesh file: $(FILE)"]]
|-
|196||[[Help:VE196|"Failed to load bogey $(KUID)"]]
|-
|197||[[Help:VE197|"Syntax error in script '$(SCRIPT)' for asset $(ASSET)"]]
|-
|198||[[Help:VE198|"Session failed to load route asset: $(KUID)"]]
|-
|199||[[Help:VE199|"Asset $(KUID) failed to load. Unloading resources."]]
|-
|200||[[Help:VE200|"Unable to load mesh $(NAME) for $(ASSET_ID)"]]
|-
|201||[[Help:VE201|"Traincar is missing required attachment point: $(ATT_NAME)"]]
|-
|202||[[Help:VE202|"Parse error reading twinkles file: $(FILE)"]]
|-
|203||[[Help:VE203|"Bad sequence order in $(TAG_NAME) list. Each element must be greater than the last."]]
|-
|204||[[Help:VE204|"Invalid range in $(TAG_NAME) list. Elements must be greater than or equal to $(INC_MIN) and less than $(EXC_MAX)."]]
|-
|205||[[Help:VE205|"Invalid element count in $(TAG_NAME) list. This list must have at least $(COUNT) elements (to match the $(TAG_START) list)."]]
|-
|206||[[Help:VE206|"The season-selector references season '$(SEASON)', but this does not exist in the texture-variants container."]]
|-
|207||[[Help:VE207|"Attached track asset $(CHILD) failed to load."]]
|-
|208||[[Help:VE208|"Attached track asset not specified for track $(INDEX)."]]
|-
|209||[[Help:VE209|"Asset is missing the required 'attached-track' container."]]
|-
|210||[[Help:VE210|"Asset is missing the required 'track' tag."]]
|-
|211||[[Help:VE211|"Asset is missing the required 'road' tag."]]
|-
|212||[[Help:VE212|"Traincar asset must have at least two bogeys."]]
|-
|213||[[Help:VE213|"Traincar asset has invalid bogey placement."]]
|-
|214||[[Help:VE214|"Traincar asset has invalid length."]]
|-
|215||[[Help:VE215|"Asset has an invalid number of LODs: $(LOD_COUNT)"]]
|-
|216||[[Help:VE216|"Material $(MATERIAL) in mesh file $(MESH) has an inappropriate texture slot assigned: $(TEXTURE)"]]
|-
|217||[[Help:VE217|"Material $(MATERIAL) in mesh file $(MESH) has no texture assigned to a required slot: $(TEXTURE)"]]
|-
|218||[[Help:VE218|"Asset has duplicate attached track at track $(INDEX)."]]
|-
|219||[[Help:VE219|"Failed to load driver mesh $(ASSETID)."]]
|-
|220||[[Help:VE220|Generic script compilation error.]]
|-
|221||[[Help:VE221|"$(ASSETID) is faulty and will not be loaded."]]
|-
|222||[[Help:VE222|"Failed to load mesh $(ASSETID)-$(MESHFILE) for TNI plugin renderer."]]
|-
|223||[[Help:VE223|"Unable to create mesh index $(MESHINDEX) for asset $(ASSET)."]]
|-
|224||[[Help:VE224|"Corrupted data in mesh file '$(FILENAME)'."]]
|-
|225||[[Help:VE225|"Failed to query asset details for featured asset."]]
|-
|226||[[Help:VE226|"Failed to upload asset details for featured asset: $(ERRORTEXT)"]]
|-
|227||[[Help:VE227|"Missing image for featured asset."]]
|-
|228||[[Help:VE228|"Failed to read image file for featured asset."]]
|-
|229||[[Help:VE229|"DLC marketing image is missing or incorrectly sized for featured asset."]]
|-
|230||[[Help:VE230|"DLS thumbnail image is missing or incorrectly sized for featured asset."]]
|-
|231||[[Help:VE231|"Failed to open image file for featured asset."]]
|-
|232||[[Help:VE232|"Failed to upload image for featured asset: $(ERRORTEXT)"]]
|-
|233||[[Help:VE233|"One or more featured assets was not provided."]]
|-
|234||[[Help:VE234|"Asset is not present in the featured assets list."]]
|-
|235||[[Help:VE235|"Featured asset is not present in the input."]]
|-
|236||[[Help:VE236|"Featured asset was not available."]]
|-
|237||[[Help:VE237|"Featured asset failed validation."]]
|-
|238||[[Help:VE238|"Featured asset has faulty or missing dependencies."]]
|-
|239||[[Help:VE239|"Featured asset is Base content."]]
|-
|240||[[Help:VE240|"Featured asset is missing an English name or description."]]
|-
|241||[[Help:VE241|"Newly built package is not compatible with previously released version."]]
|-
|242||[[Help:VE242|"Unable to load animation file '$(FILE)' (file not found, or is damaged)."]]
|-
|243||[[Help:VE243|"Failed to submit changes to asset $(ASSET_KUID) due to file access error"]]
|-
|244||[[Help:VE244|"Files in base assets cannot use importers: $(FILE)"]]
|-
|245||[[Help:VE245|"Missing compiled texture: $(FILE)"]]
|-
|246||[[Help:VE246|"Missing source texture: $(FILE)"]]
|-
|247||[[Help:VE247|"Creating default texture.txt file: $(FILE)"]]
|-
|248||[[Help:VE248|"Failed to create *.texture.txt file for source image: $(FILE)"]]
|-
|249||[[Help:VE249|"Failed to compile *.texture.txt file: $(FILE)"]]
|-
|250||[[Help:VE250|"Material Metadata expected data for texture slot '$(SLOT)' of material '$(MATERIAL)' but none found."]]
|-
|251||[[Help:VE251|"Material Metadata expected *.texture resource for texture slot '$(SLOT)' of material '$(MATERIAL)' bout found: $(FOUND)"]]
|-
|252||[[Help:VE252|"Mesh material expected data for texture slot '$(SLOT)' of material '$(MATERIAL)' but none found."]]
|-
|253||[[Help:VE253|"WriteAnimationFileBoneChunk> excessive bone-chunk count."]]
|-
|254||[[Help:VE254|"Unable to open mesh metadata file: $(FILE)"]]
|-
|255||[[Help:VE255|"Mesh contains unsupported non-triangle primitives."]]
|-
|256||[[Help:VE256|"Mesh contains invalid material index."]]
|-
|257||[[Help:VE257|"Mesh contains no primitives."]]
|-
|258||[[Help:VE258|"Unable to determine vertex format."]]
|-
|259||[[Help:VE259|"Unsupported number of texture channels."]]
|-
|260||[[Help:VE260|"Invalid index in primitive."]]
|-
|261||[[Help:VE261|"Unable to create animation file: $(FILE)"]]
|-
|262||[[Help:VE262|"Unable to open animation event file: $(FILE)"]]
|-
|263||[[Help:VE263|"Unable to parse animation event file: $(FILE)"]]
|-
|264||[[Help:VE264|"Parsed animation event file $(FILE) with $(COUNT) events."]]
|-
|265||[[Help:VE265|"Unable to search path: '$(FILE_PATH)'"]]
|-
|266||[[Help:VE266|"Multiple values found for engine spec param <kuid:xxx:yyy>/tag-name (Value1 and Value2)"]]
|-
|267||[[Help:VE267|"member $(MEMBER) is obsolete in object $(CLASS)."]]
|-
|268||[[Help:VE268|"Mesh file is unused in this asset: '$(FILE)'"]]
|-
|269||[[Help:VE269|"Texture table is incorrectly indexed, some textures may be unloadable."]]
|-
|270||[[Help:VE270|"Density LOD multiplier in level $(LEVEL) is not in descending order."]]
|-
|271||[[Help:VE271|"The specified TCB flags are invalid, please check the wiki for valid configurations."]]
|-
|272||[[Help:VE272|"No overridden function found when calling inherited()."]]
|-
|273||[[Help:VE273|"Excessive chunk count $(CHUNK_COUNT) in mesh file: $(FILE)"]]
|}

M.leafcard

2024-06-10T05:24:07Z

Windwalkr:

[[m.leafcard]] is a new material introduced as part of the "[[Treez]]" foliage system. It is used when creating leaves and minor branches for trees and plants, and is tuned to provide visual outcomes which are suitable for this usage. This may result in subtle rendering differences when compared to the standard materials such as [[m.pbrmetal]]. The exact nature of these differences may change in the future. These differences make [[m.leafcard]] unsuitable as a general-purpose material.

[[Image:m_leaf_card_tree_1.jpg|400px]]

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

We recommend using the free PlantFactory software to create trees with this material type. Detailed tutorials are available on the [[Treez]] page.

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

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

A: The alpha channel provides an opacity channel. Black indicates full transparency, meaning that the [[fragment]] is discarded. White indicates full opacity. Shades of gray are supported, which represent partial transparency. The alpha channel may be heavily quantised.

'''Albedo Texture Example'''

[[File:m_leafcard_1.png|300px]]

Color Channel Separated

[[File:m_leafcard_2.jpg|300px]]

Alpha Channel Separated

[[File:m_leafcard_2b.jpg|300px]]

==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 with no Alpha Channel (Parallax)'''

[[File:m_leafcard_3.jpg|border|middle|x300px]]

==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:m_leafcard_4.jpg|border|middle|800px]]

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:m_leafcard_5.jpg|border|middle|x300px]]

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:m_leafcard_6.jpg|border|middle|x300px]]

B: The blue channel of the parameters texture is used to modulate the strength of the directional lighting. This is intended to give the feel of individual leaves being deeper inside the tree and shadowed from all directions, even though the leaf card as a whole is not shadowed. (Note that this is the same channel used for Ambient Occlusion on m.pbrmetal; the leaf card materials do not support ambient occlusion.)

Full brightness (100% blue channel) gives a standard lighting response, while darker values give a weaker response to directional lighting.

'''Parameters (Directional Lighting Strength - Blue Channel) Texture Example'''

[[File:m_leafcard_7.jpg|border|middle|x300px]]

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:m_leafcard_8.jpg|border|middle|x300px]]

=Examples=

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

M.leafcardbillboard

2024-06-10T05:23:44Z

Windwalkr:

[[m.leafcardbillboard]] is a camera-facing variation of the [[m.leafcard]] material, introduced as part of the "[[Treez]]" foliage system. It is used when creating leaves and minor branches for trees and plants, and is tuned to provide visual outcomes which are suitable for this usage. This may result in subtle rendering differences when compared to the standard materials such as [[m.pbrmetal]]. The exact nature of these differences may change in the future. These differences make [[m.leafcardbillboard]] unsuitable as a general-purpose billboard material.

[[Image:m_leaf_card_billboard_tree_1.jpg|400px]]

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

We recommend using the free PlantFactory software to create trees with this material type. Detailed tutorials are available on the [[Treez]] page.

=Camera Facing Leaf Cards=

[[Image:m_leaf_card_billboard_cam_face_1.gif|500px]]

If you are using a standard 3D modelling program to create your trees and wish to use camera facing leaf cards then you must point your leaf cards in the positive X direction. Each leaf card must be configured as a separate mesh within the FBX file so they can rotate separately.

[[Image:leaf_card_blender.jpg|400px]] [[Image:leaf_card_blender_2.jpg|384px]] [[Image:leaf_card_blender_3.jpg|350px]]

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

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

A: The alpha channel provides an opacity channel. Black indicates full transparency, meaning that the [[fragment]] is discarded. White indicates full opacity. Shades of gray are supported, which represent partial transparency. The alpha channel may be heavily quantised.

'''Albedo Texture Example'''

[[File:m_leafcard_billboard_1.png|300px]]

Color Channel Separated

[[File:m_leafcard_billboard_2.jpg|300px]]

Alpha Channel Separated

[[File:m_leafcard_billboard_2b.jpg|300px]]

==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 with no Alpha Channel (Parallax)'''

[[File:m_leafcard_billboard_3.jpg|border|middle|x300px]]

==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:m_leafcard_billboard_4.jpg|border|middle|800px]]

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:m_leafcard_5.jpg|border|middle|x300px]]

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:m_leafcard_billboard_6.jpg|border|middle|x300px]]

B: The blue channel of the parameters texture is used to modulate the strength of the directional lighting. This is intended to give the feel of individual leaves being deeper inside the tree and shadowed from all directions, even though the leaf card as a whole is not shadowed. (Note that this is the same channel used for Ambient Occlusion on m.pbrmetal; the leaf card materials do not support ambient occlusion.)

Full brightness (100% blue channel) gives a standard lighting response, while darker values give a weaker response to directional lighting.

'''Parameters (Directional Lighting Strength - Blue Channel) Texture Example'''

[[File:m_leafcard_billboard_7.jpg|border|middle|x300px]]

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:m_leafcard_8.jpg|border|middle|x300px]]

=Examples=

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

M.leafcard

2024-06-10T05:17:44Z

Windwalkr:

[[m.leafcard]] is a new material introduced as part of the "[[Treez]]" foliage system. It is used when creating leaves and minor branches for trees and plants, and is tuned to provide visual outcomes which are suitable for this usage. This may result in subtle rendering differences when compared to the standard materials such as [[m.pbrmetal]]. The exact nature of these differences may change in the future. These differences make [[m.leafcard]] unsuitable as a general-purpose material.

[[Image:m_leaf_card_tree_1.jpg|400px]]

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

We recommend using the free PlantFactory software to create trees with this material type. Detailed tutorials are available on the [[Treez]] page.

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

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

A: The alpha channel provides an opacity channel. Black indicates full transparency, meaning that the [[fragment]] is discarded. White indicates full opacity. Shades of gray are supported, which represent partial transparency. The alpha channel may be heavily quantised.

'''Albedo Texture Example'''

[[File:m_leafcard_1.png|300px]]

Color Channel Separated

[[File:m_leafcard_2.jpg|300px]]

Alpha Channel Separated

[[File:m_leafcard_2b.jpg|300px]]

==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 with no Alpha Channel (Parallax)'''

[[File:m_leafcard_3.jpg|border|middle|x300px]]

==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:m_leafcard_4.jpg|border|middle|800px]]

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:m_leafcard_5.jpg|border|middle|x300px]]

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:m_leafcard_6.jpg|border|middle|x300px]]

B: The blue channel of the parameters texture is used to modulate the strength of the directional lighting. This is intended to give the feel of individual leaves being deeper inside the tree and shadowed from all directions, even though the leaf card as a whole is not shadowed. (Note that this is the same channel used for Ambient Occlusion on m.pbrmetal; the leaf card materials do not support ambient occlusion.)

Full brightness (100% blue channel) gives a standard lighting response, while darker values give a weaker response to directional lighting.

'''Parameters (Directional Lighting Strength - Blue Channel) Texture Example'''

[[File:m_leafcard_7.jpg|border|middle|x300px]]

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:m_leafcard_8.jpg|border|middle|x300px]]

=Examples=

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

Treez

2024-06-10T04:36:15Z

Windwalkr:

[[Image:treez.png|250px|link=https://info.trainzsimulator.com/trainz-plus/#treez]] [[Image:trainz_trees_join_the_beta.jpg|250px|link=https://forms.gle/cQTjZxixZeCT3DHS7]] [[Image:discord_community_trees_foliage.jpg|250px|link=https://discord.gg/WgQ5VbUdar]]

=Software Requirements=

This is a step by step tutorial that will teach you how to create a 3D TREE model for use in Trainz. This method uses PlantFactory (free software) to create the 3D tree model but you could use Blender or any other 3D modelling software in its place. The principles are the same.

Before you start you will need:

* A copy of [["Trainz-build" number|Trainz version 5.6]] or newer. Currently this is in development so in order to test this new foliage system you must be part of the BETA - [https://forms.gle/cQTjZxixZeCT3DHS7 JOIN].

* A copy of [https://www.bentley.com/software/e-on-software-free-downloads/ PlantFactory 2024]. Click the Download button on that page, agree to the EULA and the next page the software should show for download.

* You need a set of textures (Bark and Leaves at a minimum) for your trees. These can be created from scratch using the likes of [https://www.adobe.com/au/products/photoshop.html Photoshop] (paid) or [https://www.gimp.org GIMP] (free). You can look to source them from many different websites including [https://substance3d.adobe.com/assets/allassets?q=leaf%20fir%20branch&sort=-searchScore Adobe Substance Library] or other stock places. There are many other places you can purchase tree stock as a base or to get ideas to build from including [https://www.cgtrader.com/search?keywords=tree CGTrader] and [https://www.turbosquid.com/Search/Index.cfm?keyword=tree&media_typeid=2 TurboSquid].

=PlantFactory Examples=

A good place to start is with one of our PlantFactory templates. This can speed up your development a lot, especially if you are new to PlantFactory.

[https://images.n3vgames.com/uploads/content_creation/trainz_pf_basic_tree_example_files.zip Download Youtube Video 1 Example Files]

[https://images.n3vgames.com/uploads/content_creation/trainz_pf_tree_1_example_files.zip Download Youtube Video 2 Example Files]

=Tree Asset Creation Overview=

Trees are created as standard [[KIND Scenery|scenery]] assets.

They use the [[FBX file format]] for their mesh files.

.PNG or .TGA is recommended for the [[Texture file|textures]].

Trees may use standard materials, but benefit heavily from the new foliage-specific materials are outlined below.

The texture setup is outlined below.

You should try and keep the highest LOD under 5000 polygons. Each additional LOD level should drop down by at least 25%. Your lowest LOD should be under 1000 polygons, ideally under 500 polygons. There is no need to create bottom-LOD billboards as Trainz will create this for you using a new [[Imposter system]] that will release alongside [[Treez]].

If using PlantFactory you will want to get the example files above and look at the [[Mesh metadata file]]s to determine what additional tags are being used. You will also want to watch the PlantFactory video information below to understand how to use the program and also how to export from PlantFactory, setup your Trainz Asset and import into Trainz.

If you are using another 3D modelling program to create your trees and want to use [[m.leafcardbillboard|camera facing leaf cards]] then you must point your leaf card geometry in the positive X direction. Each leaf card must be a separate mesh within the FBX so they can rotate separately.

[[Image:leaf_card_blender.jpg|400px]] [[Image:leaf_card_blender_2.jpg|384px]] [[Image:leaf_card_blender_3.jpg|350px]]

=Materials=

There are two new materials to use for trees.

'''[[m.leafcard]]''' - Use this material for your transparent leaf cards that are not camera facing. This material structure is identical to [[m.pbrmetal]]. The only difference in setup is the name of your material.

'''[[m.leafcardbillboard]]''' - Use this material for your transparent leaf cards that are to be camera facing. This material structure is identical to [[m.pbrmetalmasked]]. The only difference in setup is the name of your material.

=Textures=

The makeup of both [[m.leafcard]] and [[m.leafcardbillboard]] is similar to [[m.pbrmetalmasked]].

The one exception is that the blue channel in the parameters texture is used to modulate the strength of the directional lighting. This is intended to give the feel of individual leaves being deeper inside the tree and shadowed from all directions, even though the leaf card as a whole is not shadowed. (Note that this is the same channel used for Ambient Occlusion on m.pbrmetal; the leaf card materials do not support ambient occlusion.)

Full brightness (100% blue channel) gives a standard lighting response, while darker values give a weaker response to directional lighting.

Here is an example of what the blue (AO) channel could look like in the parameters texture for both [[m.leafcard]] and [[m.leafcardbillboard]].

[[Image:directional_light_Scattering.jpg|400px]]

=PlantFactory Tutorial=

Once the software starts up and you've either loaded one of the templates above or you've started a new tree from scratch, if you are new to PlantFactory, you will want to read the "PlantFactory — Reference Manual" (specifically 'Section 5 - Modifying Plants: Using Parameters') which can be accessed by clicking on the Main Menu -> Help -> Reference Manual. This manual explains everything you need to know about the software. It is definitely worth the read.

For those that want to come back to the manual later, here is a video breakdown on a very raw PlantFactory / Trainz explanation you can get started with.

[[Image:plantfactory_trainz_1.jpg|750px|link=https://www.youtube.com/watch?v=pNY0kHEqsTQ]]

[[Image:plantfactory_trainz_2.jpg|750px|link=https://www.youtube.com/watch?v=c-LA4VkZrvs]]

===Work-in-Progress Test Trees===

There isn't one way to create trees in PlantFactory but these trees were created using the procedural node method.

[[Image:plantfactory_trainz_0_i.jpg|300px]]
[[Image:plantfactory_trainz_0_g.jpg|300px]]

[[Image:plantfactory_trainz_2_i.jpg|300px]]
[[Image:plantfactory_trainz_2_g.jpg|300px]]

[[Image:plantfactory_trainz_3_i.jpg|300px]]
[[Image:plantfactory_trainz_3_g.jpg|300px]]

[[Image:plantfactory_trainz_4a_i.jpg|300px]]
[[Image:plantfactory_trainz_4b_i.jpg|300px]]
[[Image:plantfactory_trainz_4_g.jpg|300px]]

[[Image:plantfactory_trainz_5a_i.jpg|300px]]
[[Image:plantfactory_trainz_5b_i.jpg|300px]]
[[Image:plantfactory_trainz_5_g.jpg|300px]]

[[Image:plantfactory_trainz_6_i.jpg|300px]]
[[Image:plantfactory_trainz_6_g.jpg|300px]]

[[Image:plantfactory_trainz_7_i.jpg|300px]]
[[Image:plantfactory_trainz_7_g.jpg|300px]]

Mesh metadata file

2024-06-10T04:18:16Z

Windwalkr:

The [[Mesh metadata file]] allows content creators to control various mesh and material attributes which may not be available in standard modelling packages, or are not exported to the [[FBX file format]].

It exists as an optional "<mesh-file-name>.txt" file included alongside the "<mesh-file-name>.fbx" file. 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.

=Validation=
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.

='materials' array=

materials
{
material_name_a
{
..
}
material_name_b
{
..
}
}

The "materials" array allows the creator to override attributes of the various materials present within the FBX file. Only the specified materials and attributes are overridden, all other materials and attributes are configured in the normal fashion. Each element in the array must be named exactly as per a single material in the FBX file, including any name suffixes.

Each material may be configured with the following attributes:

==two-sided==

two-sided 0

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==

blend-mode opaque

The 'blend-mode' tag supports the following values:
** 'alpha-blend' - Chunks which use this material are rendered using a true alpha blend. Due to technical limitations, render ordering of overlapping alpha-blend materials may be incorrect. This is not considered a bug; it is the creator's responsibility to avoid this becoming problematic.
** '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==

material-type onetex

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==

textures
{
albedo
{
texture-resource "my-albedo.texture"
}
normal
{
texture-resource "my-normal.texture"
}
}

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 for the parent material; a partial override is not supported. The following subtags are accepted within each texture container:

===texture-resource===
A string which 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 texture files must be present within the same asset as the mesh. 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==

bend-normals-upward-ratio 0.0

The 'bend-normals-upward-ratio' tag allows the input normals to be reoriented towards the sky.

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. As Trainz is Z-up, "directly upward" means (0.0, 0.0, 1.0).

Supported in [["Trainz-build" number|content format v4.8]] and later.

==clutter-wind-type==

clutter-wind-type none

This tag only applies to materials of type [[m.foliage]]. Supported values are "none" (default), "vertex-color", and "position-z". The details of this attribute can be found [[m.foliage|here]].

Supported in [["Trainz-build" number|content format v5.4]] and later.

==clutter-sample-method==

clutter-sample-method origin

This only applies pertains to materials of type [[m.foliage]]. Supported values are "origin" (default), "node-origin", "per-vertex", and "contiguous-geometry". The details of this attribute can be found [[m.foliage|here]].

Supported in [["Trainz-build" number|content format v5.4]] and later.

==clutter-geometry-root==

clutter-geometry-root bottom

This only applies pertains to materials of type [[m.foliage]]. Supported values are "bottom" (default), "top", and "center". The details of this attribute can be found [[m.foliage|here]].

Supported in [["Trainz-build" number|content format v5.4]] and later.

==fadeInEndDistance==

fadeInEndDistance 0.0

This only applies pertains to materials of type [[m.foliage]] and [[m.clutter]]. This defines the fade-in distance for materials of this chunk. Below this distance, chunks of this material are fully transparent and thus invisible (but still rendered; this is not a performance optimisation). Beyond this distance, the chunks start to become opaque.

This is typically used in conjunction with [[Mesh-table LOD]] to allow cross-fading between clutter LODs. The LOD transitions offer performance gains, while the cross-fading pays a small performance penalty but reduces potentially jarring visuals.

==fadeOutEndDistance==

fadeOutEndDistance 200.0

This only applies pertains to materials of type [[m.foliage]] and [[m.clutter]]. This defines the fade-out distance for materials of this chunk. Beyond this distance, chunks of this material are fully transparent and thus invisible (but still rendered; this is not a performance optimisation). Below this distance, the chunks start to become opaque.

This is typically used in conjunction with [[Mesh-table LOD]] to allow cross-fading between clutter LODs. The LOD transitions offer performance gains, while the cross-fading pays a small performance penalty but reduces potentially jarring visuals.

==detail-scale==

detail-scale 0.09

This only applies pertains to materials of type [[m.pbrmetaldetail]]. This controls the scaling ratio between the regular texture and the detail texture. The tag has a minimum value of 0.001.

==diffuse-color==

diffuse-color 1.0, 1.0, 1.0, 1.0

The 'diffuse-color' tag allows the RGBA diffuse color of the material to be overridden. The standard RGB color range is between 0.0 and 1.0, but higher (HDR) numbers are permitted. This does not add a new capability to the material; it is ignored where the material does not support a diffuse color input.

==emissive-color==

emissive-color 0.0, 0.0, 0.0, 0.0

The 'emissive-color' tag allows the RGBA emissive color of the material to be overridden. The standard RGB color range is between 0.0 and 1.0, but higher (HDR) numbers are permitted. This does not add a new capability to the material; it is ignored where the material does not support an emissive color input.

==specular-color==

specular-color 1.0, 1.0, 1.0, 1.0

The 'specular-color' tag allows the RGBA specular color of the material to be overridden. The standard RGB color range is between 0.0 and 1.0, but higher (HDR) numbers are permitted. This does not add a new capability to the material; it is ignored where the material does not support a specular color input.

==specular-power==

specular-power 10.0

The 'specular-power' tag allows the specular power of the material to be overridden. The value must be between 10.0 and 128.0 inclusive. This does not add a new capability to the material; it is ignored where the material does not support a specular power input.

=rotate-mesh=

rotate-mesh 90, 0, 0

The 'rotate-mesh' tag allows the entire input mesh to be rotated on import. This is useful in cases where the orientation of the mesh is incorrect, but the FBX file cannot be regenerated or cannot easily be rotated in the modeller application. The three parameters describe an Euler rotation (roll, pitch, yaw) expressed in degrees.

= 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>

HowTo/Upgrade obsolete script functions

2022-06-21T05:38:07Z

Windwalkr:

This page serves as a hub for how to upgrade/replace uses of various obsolete script functions.

Note that this is not a comprehensive list. Trainz has existed for more than two decades and there are dozens of obsolete script functions as a result. This guide aims to cover only the more complex upgrade cases, where the replacement functions may not be immediately obvious, or may be considerably more difficult to use.

__NOEDITSECTION__
==GameObject.GetId==
'''Previous Usage''' 
Returns a numeric ID used to identify a GameObject within the script context. This ID is not consistent between Route/Session loads and cannot be used for long term storage.

'''Reason for Obsoletion''' 
With the advent of [[Asynchronous_Route_Streaming|Route streaming]] world objects may now be unloaded/reloaded during gameplay, and these IDs can be reused by different objects. This makes the ID itself unreliable, and uses of it are better served by more modern functions.

'''Replacement Function''' 
Standard uses of the integer ID can be swapped to using the objects GameObjectID instead. Call GameObject.GetGameObject() to get the ID.

'''Further Reading'''
* See GameObjectID.gs in your Trainz installations resources/script folder for more information on the GameObjectID class.
* See [[HowTo/Upgrade_GameObject.GetId()]] for a practical example of how to replace some common integer ID uses with GameObjectID.

==GameObject.GetName==
'''Previous Usage''' 
Returns a string ID used to identify a GameObject within the script context. This ID is automatically generated by Trainz code, using the object type or asset name as a prefix. It can generally be considered constant between runs of the game, and was therefore suitable for long term storage.

'''Reason for Obsoletion''' 
This script name was often confused for the objects localised (translatable) name, and (despite script comments to the contrary) was never truly guaranteed unique.

'''Replacement Function''' 
Cases which use of the script name as an ID can be swapped to using the objects GameObjectID instead. Cases which use it for display to the player should instead use the localised name.

'''Further Reading'''
* See GameObjectID.gs in your Trainz installations resources/script folder for more information on the GameObjectID class.
* See [[HowTo/Upgrade_GameObject.GetName()]] for a practical example of how to replace some common script name uses with GameObjectID or localised name.

==Router.GetGameObject==
'''Previous Usage''' 
Returns a GameObject instance from either it's script name or integer ID.

'''Reason for Obsoletion''' 
As both GetId() and GetName() are obsolete, both the string and int variants of this function are also obsolete. See GameObject.GetId and GameObject.GetName above for more information.

'''Replacement Function''' 
All uses of the integer ID and script name identifiers should be replaced with GameObjectID. To retrieve an GameObject which is currently loaded into memory, a script may then call Router.GetGameObject(GameObjectID) or World.GetGameObjectByIDIfLoaded(GameObjectID).

If a script requires access to an object which may not be loaded, it may call World.GetGameObjectByID(GameObjectID) to request that native code loads the object. Note that this requires native code to load the entire tile/section that the object is in, which may impact performance, and may take some time. As the call may take a while, it behaves asynchronously, returning a [[Class_AsyncObjectSearchResult|AsyncObjectSearchResult]] to the caller.

'''Further Reading'''
* See GameObjectID.gs in your Trainz installations resources/script folder for more information on the GameObjectID class.
* See [[HowTo/Upgrade_GameObject.GetName()]] for a practical example of how to upgrade uses of Router.GetGameObject(string).

==World.Get*List==
'''Previous Usage''' 
These functions (e.g. World.GetJunctionList()) were used to return a list of a particular type of items within the World.

'''Reason for Obsoletion''' 
The functions represented a considerable performance hit, especially on large Routes. With the advent of [[Asynchronous_Route_Streaming|Route streaming]] they are also only able to return objects which are currently loaded, limiting their usefulness.

'''Replacement Function''' 
Due to the inherent performance concerns it is no longer possible to synchronously query for a list of objects within the world. Instead, an asynchronous interface now exists to run searches for objects of a particular type or name, World.GetNamedObjectList(). This function takes a category string and partial name, and returns a list of matching objects. Both parameters are optional, but at least one must be provided. The function returns a [[Class_AsyncObjectSearchResult|AsyncObjectSearchResult]] to the caller.

'''Further Reading'''
* See [[HowTo/Search_for_objects_in_the_world]] for a practical example of how to list objects using category codes.

==Asset.GetConfigSoup==
'''Previous Usage''' 
This function returns the config.txt file for an asset, as a Soup object.

'''Reason for Obsoletion''' 
Calls to this function may require loading an asset config file from disk, which can be very slow (in computational terms). For this reason, the function has been marked obsolete to avoid performance issues in script.

'''Replacement Function''' 
A new async query interface exists on Asset which will cache the config file on a background thread. To use this feature script must first call Asset.CacheConfigSoup(), and then wait on the returned AsyncQueryHelper. When the caching is complete, the caller may call Asset.GetConfigSoupCached() to get the config file Soup.

==Asset.GetStringTable==
'''Previous Usage''' 
This function returns the localised string-table from the config.txt file for an asset.

'''Reason for Obsoletion''' 
Calls to this function may require loading an asset config file from disk, which can be very slow (in computational terms). For this reason, the function has been marked obsolete to avoid performance issues in script.

'''Replacement Function''' 
A new async query interface exists on Asset which will cache the config file on a background thread. To use this feature script must first call Asset.CacheConfigSoup(), and then wait on the returned AsyncQueryHelper. When the caching is complete, the caller may call Asset.GetStringTable() to get the StringTable.

==TrainzScript.GetAssetList==
'''Previous Usage''' 
This function is used to return a list of installed assets of a given kind (e.g. "signal").

'''Reason for Obsoletion''' 
Asset searches can be very slow, and this function was marked obsolete for performance reasons.

'''Replacement Function''' 
A much more powerful asset search system exists in [[Class_TrainzAssetSearch|TrainzAssetSearch]]. This class allows script to asynchronously search on any criteria, eliminating the performance concerns.

==TrainzScript.SearchAssets==
'''Previous Usage''' 
This function is used to return a list of assets of a given asset category filter.

'''Reason for Obsoletion''' 
Asset searches can be very slow, and this function was marked obsolete for performance reasons.

'''Replacement Function''' 
A much more powerful asset search system exists in [[Class_TrainzAssetSearch|TrainzAssetSearch]]. This class allows script to asynchronously search on any criteria, eliminating the performance concerns.

==Router.MESSAGE_BROADCAST==
'''Previous Usage''' 
This pseudo router ID was used to post a message to ALL game objects.

'''Reason for Obsoletion''' 
Broadcasting is inefficient by nature, and the same effects can be achieved by having scripts listen (via Sniff() or AddHandler()) to the specific objects and messages that they're interested in. Additionally, game objects have a limited message queue capacity, so with large numbers of objects broadcasting it was common to overflow the message queues and permanently lose messages, leading to unexpected and unpredictable outcomes. Finally, with [[Asynchronous Route Streaming]], broadcasts do not actually reach all objects in the route.

'''Replacement Function''' 
No replacement functionality is required. Scripts should use the existing PostMessage(), Sniff, AddHandler() and similar functionality instead of broadcasting. This should be kept to the minimum necessary to achieve the desired goal.
In order to support interoperability with legacy scripts that expect message broadcasts, the LegacyBroadcastMessage() function can be used in parallel with any updated mechanisms.

==See Also==
* [[TrainzScript_Language_Reference|TrainzScript Language Reference]]
* [[Compatibility_mode|Compatibility Mode Setting]]
* [[Asynchronous_Route_Streaming| Asynchronous Route Streaming]]

Compatibility mode

2022-06-21T05:25:01Z

Windwalkr:

The "Compatibility mode" setting in Trainz is used to disable various optimisations in order to support legacy content (Routes, Sessions, and their dependencies).

This page details the various compatibility mode options available in TRS19 and later, and how they each affect gameplay and performance.

==Maximise compatibility==
In "maximise compatibility" mode, Trainz will disable all [[Asynchronous_Route_Streaming|Route streaming]], and maintain the maximum level of [[TrainzScript|script]] support possible. While running in this mode Trainz will keep the entire Route loaded into system memory, which can massively degrade performance.

This mode should only be used to run legacy content which fails to operate correctly with streaming enabled.

In both [[TRS19]] and [[TRS22]], this mode is the default for the game due to the large number of legacy scripts in circulation. Users may override this default in the (out-of-game) Trainz Settings, and are encouraged to do so in order to achieve better game performance and/or test content to ensure that it functions correctly.

==Stream objects==
This mode enables [[Asynchronous_Route_Streaming|Route streaming]], but keeps the maximum level of [[TrainzScript|script]] support possible. With streaming enabled, Trainz avoids loading portions of the Route which are inactive and far away from the player, increasing performance, reducing loading times, and reducing overall system resource consumption. This is especially evident on very large Routes. However, older scripted assets (especially session rules) can experience issues, as they may attempt to query Route data which is not currently loaded.

This mode is most appropriate for running most content from older versions of Trainz.

Packaged routes which are bundled with the [[TRS19]] and [[TRS22]] products use this mode even if "Maximise Compatibility" is selected, because they have been tested internally at N3V to confirm correct operation.

==Maximise performance==
In maximise performance mode Trainz enables [[Asynchronous_Route_Streaming|Route streaming]], and also prevents many [[HowTo/Upgrade obsolete script functions|legacy script functions]] from running. This can hugely improve performance but older scripted content is likely to function incorrectly, or not at all. Specifically, script functions which are tagged with the [[TrainzScript Keywords#obsolete|'obsolete' keyword]] are likely not to function, and may return empty, null, or incomplete results.

It is expected that future Trainz products will enable this mode by default, so script authors should run in this mode or beyond when developing and testing their creations.

==Show errors on legacy calls==
This mode is useful for finding/debugging content which attempts to use legacy script features. While in 'Show errors on legacy calls' mode, Trainz will operate identically to 'Maximise performance' mode, but script calls to obsolete/legacy functions will also generate script exceptions. This allows content creators to determine which assets require fixing/replacing in order to support 'Maximise performance' mode, but due to the extra processing game performance will be slightly worse than when running in 'Maximise performance'.

This mode should only be used for testing and debugging during content creation.

==See Also==
* [[Asynchronous_Route_Streaming| Asynchronous Route Streaming]]
* [[HowTo/Search_for_objects_in_the_world| How to Search for objects in the world]]
* [[HowTo/Upgrade obsolete script functions]]

Help:VE268

2022-02-21T05:49:24Z

Windwalkr: Created page with "=Mesh file is unused in this asset: '$(FILE)'= This warning (trainz-build <= 500) or error (trainz-build > 500) is logged when an asset contains a mesh file which is not refe..."

=Mesh file is unused in this asset: '$(FILE)'=

This warning (trainz-build <= 500) or error (trainz-build > 500) is logged when an asset contains a mesh file which is not referenced in the asset's config.txt file.

This results either because the mesh file is entirely redundant, meaning that it should not be included in the asset, or because the mesh file is referenced indirectly from the config.txt of some other asset (eg. as a mesh library) without also being referenced in the config.txt file. In the latter case, the correct solution is to configure an appropriate mesh-table entry in the asset to reference the mesh, in the same manner that you expect other assets to reference the mesh.

Category:Validation Errors

2022-02-21T05:44:39Z

Windwalkr:

Validation Error (VE) numbers are logged during content validation, to allow users to look up particular validation messages to better understand the source of the problem. Normal logs provide a substantial amount of technical detail about the error, but typically assume that the reader is familiar with the subject matter and will understand why the log is relevant. This wiki provides the necessary background information to understanding many of the logs, however a user who is unfamiliar with the area in question may not know where to start looking. VE numbers allow users to quickly find relevant pages in the wiki without any prior knowledge of the subject.

This page serves as a master guide to all VE numbers currently logged by Trainz. This page does not provide detailed information on any given VE number- please refer to the individual VE number pages for specific details. The error text here is correct for the English localisation of Trainz at the time of writing, however the exact text may change from time to time. It is intended that the overall meaning of a VE number will never change- new VE numbers will be issued instead, and old VE numbers may be made obsolete.

Logs which lack VE numbers do not belong on this page.

The individual VE pages can be found at the links below, or can be accessed directly from [[Content Manager]] by right-clicking on the Validation Error in the results log, and selecting "View Help for This Message".

{|
|-
|1||[[Help:VE1|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Decimal value."]]
|-
|2||[[Help:VE2|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Integer value."]]
|-
|3||[[Help:VE3|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|4||[[Help:VE4|"'$(TAG_NAME)' must have a positive value."]]
|-
|5||[[Help:VE5|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|6||[[Help:VE6|"'$(TAG_NAME)' must not be zero."]]
|-
|7||[[Help:VE7|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|8||[[Help:VE8|"The value for '$(TAG_NAME)' must be between '$(MIN)' and '$(MAX)' but was specified as '$(VALUE)'."]]
|-
|9||[[Help:VE9|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|10||[[Help:VE10|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|11||[[Help:VE11|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|12||[[Help:VE12|"No string-table entry found with tag '$(VALUE)' for for string-token tag '$(TAG)'."]]
|-
|13||[[Help:VE13|"Missing or invalid selection for tag '$(TAG_NAME)' in '$(CONT_NAME)'."]]
|-
|14||[[Help:VE14|"Missing or invalid selection for tag '$(TAG_NAME)' in '$(CONT_NAME)'."]]
|-
|15||[[Help:VE15|"Attachment point '$(TAG_NAME)' in '$(CONT_NAME)' must be found in mesh '$(MESH_NAME)'."]]
|-
|16||[[Help:VE16|"Container '$(CONT_NAME)' does not have an 'att-parent' tag which is required to reference an attachment point."]]
|-
|17||[[Help:VE17|"Attachment point '$(TAG_NAME)' in '$(CONT_NAME)' must be found in mesh '$(MESH_NAME)'."]]
|-
|18||[[Help:VE18|"Attachment point '$(TAG_VAL)' referenced by tag '$(TAG_NAME)' in '$(CONT_NAME)' was not found."]]
|-
|19||[[Help:VE19|"Effect '$(EFFECT_NAME)' in '$(CONT_NAME)' was not found within the mesh table."]]
|-
|20||[[Help:VE20|"Mesh '$(MESH_NAME)' referenced in '$(CONT_NAME)' was not found within the mesh table."]]
|-
|21||[[Help:VE21|"Attachment point '$(TAG_VAL)' referenced by tag '$(TAG_NAME)' in '$(CONT_NAME)' was not found."]]
|-
|22||[[Help:VE22|"Missing or invalid selection for tag '$(TAG_NAME)' in '$(CONT_NAME)'."]]
|-
|23||[[Help:VE23|"Invalid tag name '$(TAG_NAME)' in container '$(CONT_NAME)'."]]
|-
|24||[[Help:VE24|"Invalid tag name '$(TAG_NAME)' in container '$(CONT_NAME)'."]]
|-
|25||[[Help:VE25|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|26||[[Help:VE26|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|27||[[Help:VE27|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' must have a mesh file extension."]]
|-
|28||[[Help:VE28|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' must have an image file extension."]]
|-
|29||[[Help:VE29|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' must have an animation file extension."]]
|-
|30||[[Help:VE30|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' refers to a nonexistent file: '$(FILENAME)'."]]
|-
|31||[[Help:VE31|"Invalid tag name '$(TAG_NAME)' in container '$(CONT_NAME)'."]]
|-
|32||[[Help:VE32|"Alias mesh requires valid parent asset."]]
|-
|33||[[Help:VE33|"Alias mesh '$(FILE)' not found in dependency $(KUID)."]]
|-
|34||[[Help:VE34|"Alias mesh '$(FILE)' not found in latest version ($(NEW_KUID)) of dependency $(OLD_KUID)."]]
|-
|35||[[Help:VE35|"Required alias mesh asset $(KUID) is missing and cannot be validated."]]
|-
|36||[[Help:VE36|"The texture '$(FILE)' failed to load."]]
|-
|37||[[Help:VE37|"The texture '$(FILE)' is not a power of 2, please resize it."]]
|-
|38||[[Help:VE38|"The texture '$(FILE)' is not square. Cubemap textures need to have the same width and height."]]
|-
|39||[[Help:VE39|"The texture '$(FILE)' is a uniform color."]]
|-
|40||[[Help:VE40|"Unable to load $(TYPE) texture '$(TEXTURE)' for texture file '$(FILE)'."]]
|-
|41||[[Help:VE41|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Integer value."]]
|-
|42||[[Help:VE42|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Decimal value."]]
|-
|43||[[Help:VE43|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Boolean value."]]
|-
|44||[[Help:VE44|"Tag '$(TAG_NAME)' in the container '$(CONT_NAME)' is obsolete."]]
|-
|45||[[Help:VE45|"The Tag '$(TAG_NAME)' is not permitted within a container of type '$(CONT_NAME)'."]]
|-
|46||[[Help:VE46|"Internal Error: The template does not specify that a smoke container is valid in the container being parsed."]]
|-
|47||[[Help:VE47|"Container '$(CONT_NAME)' is not permitted in this section."]]
|-
|48||[[Help:VE48|"This asset uses an obsolete trainz-build number. Trainz-build numbers below $(LOWEST_TRAINZBUILD) are no longer supported."]]
|-
|49||[[Help:VE49|"Required tag 'kind' is not present. Ensure this is a valid config file."]]
|-
|50||[[Help:VE50|"Unsupported kind '$(KIND)'."]]
|-
|51||[[Help:VE51|"Tag '$(TAG_NAME)' in the container '$(CONT_NAME)' is obsolete."]]
|-
|52||[[Help:VE52|"The Tag '$(TAG_NAME)' is not permitted within a container of type '$(CONT_NAME)'."]]
|-
|53||[[Help:VE53|"This container is no longer supported."]]
|-
|54||[[Help:VE54|"The Tag '$(TAG_NAME)' is not permitted within a container of type '$(CONT_NAME)'."]]
|-
|55||[[Help:VE55|"This container is no longer supported."]]
|-
|56||[[Help:VE56|"Container '$(CONT_NAME)' is not permitted in this section."]]
|-
|57||[[Help:VE57|"Container '$(CONT_NAME)' is not permitted in this section."]]
|-
|58||[[Help:VE58|"The tag '$(TAG_NAME)' is not a valid container type (expected '$(TYPE)')."]]
|-
|59||[[Help:VE59|"Internal error: unknown dataType - kind '$(KIND)'."]]
|-
|60||[[Help:VE60|"Required tag '$(TAG_NAME)' was missing and has been set to default."]]
|-
|61||[[Help:VE61|"Required tag '$(TAG_NAME)' was missing and has been set to default."]]
|-
|62||[[Help:VE62|"Required container '$(CONT_NAME)' is missing."]]
|-
|63||[[Help:VE63|"The cubemap texture '$(FILE)' has missing images. Please verify the texture.txt file."]]
|-
|64||[[Help:VE64|"Cubemap texture '$(FILE)' contains images of different sizes."]]
|-
|65||[[Help:VE65|"The *.texture.txt file is missing for texture resource '$(FILE)'."]]
|-
|66||[[Help:VE66|"The texture file '$(FILE)' contains non-ANSI characters. Textures must be ANSI."]]
|-
|67||[[Help:VE67|"The texture '$(FILE)' does not seem to have a primary texture set. Please verify the texture.txt file."]]
|-
|68||[[Help:VE68|"The primary and alpha texture are not the same size for '$(FILE)'."]]
|-
|69||[[Help:VE69|"Binary conversion failed for texture resource '$(FILE)'."]]
|-
|70||[[Help:VE70|"The KUID tag is not a valid KUID value: '$(string)'."]]
|-
|71||[[Help:VE71|"Unsupported SpeedTree version for mesh: $(FILE)"]]
|-
|72||[[Help:VE72|"Unable to load mesh file: '$(FILE)'"]]
|-
|73||[[Help:VE73|"Image file '$(FILE)' is incorrectly used as both a texture.txt source file and a raw image file."]]
|-
|74||[[Help:VE74|"Image file '$(FILE)' is incorrectly used as both a texture.txt source file and a raw image file."]]
|-
|76||[[Help:VE76|"Unable to load mesh file: '$(FILE)'"]]
|-
|77||[[Help:VE77|"Unable to load indexed mesh '$(FILE)'"]]
|-
|79||[[Help:VE79|"Unable to load animation file '$(FILE)' (mesh has not been loaded correctly)."]]
|-
|81||[[Help:VE81|"The high-poly mesh '$(FILE)' should have LOD levels."]]
|-
|82||[[Help:VE82|"High-detail .im files are not supported for traincar assets, as they are likely to perform poorly. It is recommended that you upgrade '$(FILE)' to a .lm file."]]
|-
|83||[[Help:VE83|"The file '$(FILE)' is provided in LM format despite having no attachment points and no animation support. This may have a negative impact on performance."]]
|-
|84||[[Help:VE84|"The file '$(FILE)' is provided in LM format despite containing only a single mesh. This may have a negative impact on performance."]]
|-
|85||[[Help:VE85|"The file '$(FILE)' is provided in LM format, however the high-detail mesh is comprised of less than 300 polygons. This may have a negative impact on performance."]]
|-
|86||[[Help:VE86|"Legacy .pm files are no longer supported, and will perform poorly. It is recommended that you switch to using a .lm file."]]
|-
|87||[[Help:VE87|"Legacy .pm files are no longer supported, and will perform poorly. It is recommended that you switch to using a .lm file."]]
|-
|88||[[Help:VE88|"This asset has a trainz-build number which is not recognised by this tool."]]
|-
|89||[[Help:VE89|"Tag '$(TAG_NAME)' in the container '$(CONT_NAME)' is obsolete."]]
|-
|90||[[Help:VE90|"This asset has an invalid KUID user id"]]
|-
|91||[[Help:VE91|"The dependency $(KUID) has an invalid KUID User ID and cannot be used"]]
|-
|92||[[Help:VE92|"Duplicate '$(TAG_NAME)' containers in '$(CONT_NAME)'. Containers must have a unique name."]]
|-
|93||[[Help:VE93|"Duplicate '$(TAG_NAME)' tags in '$(CONT_NAME)'. Tags must have a unique name."]]
|-
|94||[[Help:VE94|"This asset requires a shadow mesh, but the mesh table does not contain one."]]
|-
|95||[[Help:VE95|"This asset does not have a mesh that is visible by default."]]
|-
|96||[[Help:VE96|"Maximum of 5 running number fonts supported."]]
|-
|97||[[Help:VE97|"The running number font directory '$(DIR)' could not be found."]]
|-
|98||[[Help:VE98|"The running number font file '$(DIR)/$(FILE)' could not be found."]]
|-
|99||[[Help:VE99|"The track-sound container '$(NAME)' has no bogey, track or track-parent tag."]]
|-
|100||[[Help:VE100|"Required tag '$(TAG_NAME)' was missing and has been set to default."]]
|-
|101||[[Help:VE101|"The file '$(FILE)' does not exist."]]
|-
|102||[[Help:VE102|"Failed to load sound file '$(FILE)', please ensure this is a valid wav file."]]
|-
|103||[[Help:VE103|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|104||[[Help:VE104|"Multiple template property bindings for rule property '$(PROP)' for rule '$(RULE)'."]]
|-
|105||[[Help:VE105|"The template property '$(NAME)' specified in the rule-template-bindings container of rule '$(RULE)' does not exist."]]
|-
|106||[[Help:VE106|"The high-detail meshes in season $(SEASON) total more than $(LIMIT) polygons. This may have a negative impact on performance: $(LOD_SUMMARY)"]]
|-
|107||[[Help:VE107|"The high-detail meshes total more than $(LIMIT) polygons. This may have a negative impact on performance: $(LOD_SUMMARY)"]]
|-
|108||[[Help:VE108|"The low-detail meshes in season $(SEASON) total more than 500 polygons. This may have a negative impact on performance: $(LOD_SUMMARY)"]]
|-
|109||[[Help:VE109|"The low-detail meshes total more than 500 polygons. This may have a negative impact on performance: $(LOD_SUMMARY)"]]
|-
|110||[[Help:VE110|"The meshes in LOD level $(LOD_LEVEL) in season $(SEASON) must total at least 20% fewer polygons than the next higher LOD in the same season: $(LOD_SUMMARY)"]]
|-
|111||[[Help:VE111|"The meshes in LOD level $(LOD_LEVEL) must total at least 20% fewer polygons than the next higher LOD: $(LOD_SUMMARY)"]]
|-
|112||[[Help:VE112|"Multiple track stretches between '$(FROM_VERTEX)' and '$(TO_VERTEX)' in container '$(CONT_NAME)'. Track stretches must be unique."]]
|-
|113||[[Help:VE113|"An image file ('$(FILE)') has been supplied where a texture file ('*.texture.txt') is required."]]
|-
|114||[[Help:VE114|"An image file ('$(FILE)') has been supplied where a texture file ('*.texture.txt') is required."]]
|-
|115||[[Help:VE115|"The texture file '$(FILE)' does not exist."]]
|-
|116||[[Help:VE116|"No texture file has been specified for this texture asset."]]
|-
|117||[[Help:VE117|"'$(TAG_0)' must be set to a '$(KIND)' for '$(TAG_1)' to be allowed."]]
|-
|118||[[Help:VE118|"Tag '$(TAG_0)' requires that '$(TAG_1)' be set to '$(KIND)'."]]
|-
|119||[[Help:VE119|"The tag '$(TAG_NAME)' is not valid for kind '$(KIND)'."]]
|-
|120||[[Help:VE120|"Tag '$(TAG_0)', requires the tag '$(TAG_1)' to be present."]]
|-
|121||[[Help:VE121|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|122||[[Help:VE122|"'$(TAG_NAME)' must have a positive value."]]
|-
|123||[[Help:VE123|"The script file '$(FILE)' does not exist."]]
|-
|124||[[Help:VE124|"The file '$(FILE)' does not exist."]]
|-
|125||[[Help:VE125|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|126||[[Help:VE126|"'$(TAG_NAME)' must not be zero."]]
|-
|127||[[Help:VE127|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|128||[[Help:VE128|"The value for '$(TAG_NAME)' must be between '$(MIN)' and '$(MAX)' but was specified as '$(VALUE)'."]]
|-
|129||[[Help:VE129|"Incorrect number of values for the tag '$(TAG_NAME)', expected $(NUM_0) values, found $(NUM_1)."]]
|-
|130||[[Help:VE130|"Too many values for the tag '$(TAG_NAME)', maximum is $(MAX) values, found $(FOUND)."]]]]
|-
|131||[[Help:VE131|"Value must be a mesh from the mesh-table (not a parent container)."]]
|-
|132||[[Help:VE132|"The attachment point '$(ATT)' must belong to the parent mesh of the effect (mesh=$(MESH))."]]
|-
|133||[[Help:VE133|"A light container must be present to link the signals."]]
|-
|134||[[Help:VE134|"'$(NUM)' must be a valid light number from the light container."]]
|-
|135||[[Help:VE135|"'$(TAG_0)' requires that the tag '$(TAG_1)' be present."]]
|-
|136||[[Help:VE136|"'$(TAG_0)' requires that the tag '$(TAG_1)' be present."]]
|-
|137||[[Help:VE137|"Empty or invalid running number specified at character index $(INDEX)"]]
|-
|138||[[Help:VE138|"Running number specified at character index $(INDEX) is too large, must be less than 9 characters."]]
|-
|139||[[Help:VE139|"Invalid running number range specified at character index $(INDEX), ($(FROM)-$(TO))."]]
|-
|140||[[Help:VE140|"Running number range '$(FROM)-$(TO)' specified at character index $(INDEX) overlaps already in use numbers, running numbers must be unique."]]
|-
|141||[[Help:VE141|"Running number '$(NUMBER)' specified at character index $(INDEX) is already in use."]]
|-
|142||[[Help:VE142|"Invalid character '$(CHAR)' specified in running number list, only numbers, ',' and '-' are supported."]]
|-
|143||[[Help:VE143|"Possible running number list is too large, the set must contain less than 20000 possibilities."]]
|-
|144||[[Help:VE144|"Category code 'ZX - Paintshed template' is obsolete."]]
|-
|145||[[Help:VE145|"Category code 'ZX - Paintshed template' is obsolete."]]
|-
|146||[[Help:VE146|"An asset must be specified for tag '$(TAG_NAME)'."]]
|-
|147||[[Help:VE147|"The tag(s) $(MISPLACED_TAGS) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|148||[[Help:VE148|"The tag(s) $(MISPLACED_TAGS) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|149||[[Help:VE149|"The mesh(es) $(MISPLACED_MESHES) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|150||[[Help:VE150|"The mesh(es) $(MISPLACED_MESHES) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|151||[[Help:VE150|"The mesh(es) $(MISPLACED_MESHES) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|152||[[Help:VE152|"The tags $(MISSING_TAGS) are not all defined. The default values will be used and the positions of the elements may not fit your track."]]
|-
|153||[[Help:VE153|"The mesh $(MESH) is present but the tag $(MISSING_TAG) is not defined."]]
|-
|154||[[Help:VE154|"The mesh $(MESH) is present but the tag $(MISSING_TAG) is not defined."]]
|-
|155||[[Help:VE155|"The mesh $(MESH) is present but the tags $(MISSING_TAGS) are not all defined."]]
|-
|156||[[Help:VE156|"The tag $(MISSING_TAG) is not defined. The default value will be used and the positions of the elements may not fit your track."]]
|-
|157||[[Help:VE157|"The mesh $(MESH) is present but the tag $(MISSING_TAG) is missing. The default value will be used and the positions of the elements may not fit your track."]]
|-
|158||[[Help:VE158|"Unable to open .lm.txt file: $(FILE)"]]
|-
|159||[[Help:VE159|"Unable to parse .lm.txt file: $(FILE)"]]
|-
|160||[[Help:VE160|"No 'mesh' keys found in .lm.txt file: $(FILE)"]]
|-
|161||[[Help:VE161|"$(LODCOUNT) LODs in .lm.txt file: $(FILE)"]]
|-
|162||[[Help:VE162|"One of the LOD reductions of '$(FILE)' introduces a new attachment point: $(ATT)"]]
|-
|163||[[Help:VE163|"Unable to parse .im file: $(FILE)"]]
|-
|164||[[Help:VE164|"Invalid position data in .im file: $(FILE)"]]
|-
|165||[[Help:VE165|"Texture '$(TEXTURE)' is missing or could not be loaded in mesh '$(FILE)', material '$(MATERIAL)'."]]
|-
|166||[[Help:VE166|"$(COMBINEDCOUNT) combined chunks (of $(SOURCECOUNT) source) in .im file: $(FILE)"]]
|-
|167||[[Help:VE167|"Source image texture file '$(TEXTUREFILE)' is too large for '$(ASSETFILE)' ($(WIDTH)x$(HEIGHT))"]]
|-
|168||[[Help:VE168|"File '$(TEXTUREFILE)' is not a valid compiled texture file for '$(ASSETFILE)'"]]
|-
|169||[[Help:VE169|"Compiled texture file '$(TEXTUREFILE)' is unsupported version for '$(ASSETFILE)'"]]
|-
|170||[[Help:VE170|"Failed to open compiled texture '$(TEXTUREFILE)' for '$(ASSETFILE)'"]]
|-
|171||[[Help:VE171|"Expected texture file type but found '$(TEXTUREFILE)' for '$(ASSETFILE)'"]]
|-
|172||[[Help:VE172|"Script class does not match asset kind ($(KIND))."]]
|-
|173||[[Help:VE173|"Material '$(MATERIAL)' in mesh '$(FILE)' is not of a recognised material type."]]
|-
|174||[[Help:VE174|"MeshObjectSpec::LinkSpecs> Mesh-table element #$(MESH_INDEX) parent mesh is invalid."]]
|-
|175||[[Help:VE175|"MeshObjectSpec::LinkSpecs> Mesh-table element #$(MESH_INDEX) is part of invalid hierarchy."]]
|-
|176||[[Help:VE176|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' must have a texture file extension."]]
|-
|177||[[Help:VE177|"The kuid '$(KUID)' is not in the database, and could not be found in any known location. Ensure that this is a valid asset."]]
|-
|178||[[Help:VE178|"The asset specified in '$(KUID)' is not installed locally but is available for download."]]
|-
|179||[[Help:VE179|"The kuid '$(KUID)' specified in '$(TAG_NAME)' is not of the correct type."]]
|-
|180||[[Help:VE180|"Integrity check failure on $(FILE). One or more route/session tiles may be missing."]]
|-
|181||[[Help:VE181|"The tag '$(TAG_NAME)' requires a minimum asset version of $(MIN_VERSION)"]]
|-
|182||[[Help:VE182|"Material '$(MATERIAL)' in mesh '$(FILE)' is missing a texture for a mandatory texture slot."]]
|-
|183||[[Help:VE183|"FBX file is in an unsupported older format."]]
|-
|184||[[Help:VE184|"KIND '$(KIND)' requires trainz-build $(TRAINZBUILD)."]]
|-
|185||[[Help:VE185|"Material '$(MATERIAL)' in mesh '$(FILE)' has heightmap texture. Provide a normal map instead."]]
|-
|186||[[Help:VE186|"Material '$(MATERIAL)' is shared between multiple chunks in this asset but the material parameters conflict."]]
|-
|187||[[Help:VE187|"The value '$(VALUE)' in not a valid KUID."]]
|-
|188||[[Help:VE188|"Custom render plugin failed to load mesh '$(FILE)'"]]
|-
|189||[[Help:VE189|"Collision data exceeds $(LIMIT)KB. Please specify a different generation method or a simplified mesh."]]
|-
|190||[[Help:VE190|"Tag '$(NAME)' is unable to be converted from $(TYPE1) to $(TYPE2)"]]
|-
|191||[[Help:VE191|"Tag '$(NAME)' does not contain a valid integer: $(VALUE)"]]
|-
|192||[[Help:VE192|"Tag '$(NAME)' does not contain a valid float list: $(VALUE)"]]
|-
|193||[[Help:VE193|"Tag '$(NAME)' does not contain a valid float"]]
|-
|194||[[Help:VE194|"Tag '$(NAME)' does not contain a valid kuid: $(VALUE)"]]
|-
|195||[[Help:VE195|"Unable to parse chunk $(CHUNK_INDEX) in mesh file: $(FILE)"]]
|-
|196||[[Help:VE196|"Failed to load bogey $(KUID)"]]
|-
|197||[[Help:VE197|"Syntax error in script '$(SCRIPT)' for asset $(ASSET)"]]
|-
|198||[[Help:VE198|"Session failed to load route asset: $(KUID)"]]
|-
|199||[[Help:VE199|"Asset $(KUID) failed to load. Unloading resources."]]
|-
|200||[[Help:VE200|"Unable to load mesh $(NAME) for $(ASSET_ID)"]]
|-
|201||[[Help:VE201|"Traincar is missing required attachment point: $(ATT_NAME)"]]
|-
|202||[[Help:VE202|"Parse error reading twinkles file: $(FILE)"]]
|-
|203||[[Help:VE203|"Bad sequence order in $(TAG_NAME) list. Each element must be greater than the last."]]
|-
|204||[[Help:VE204|"Invalid range in $(TAG_NAME) list. Elements must be greater than or equal to $(INC_MIN) and less than $(EXC_MAX)."]]
|-
|205||[[Help:VE205|"Invalid element count in $(TAG_NAME) list. This list must have at least $(COUNT) elements (to match the $(TAG_START) list)."]]
|-
|206||[[Help:VE206|"The season-selector references season '$(SEASON)', but this does not exist in the texture-variants container."]]
|-
|207||[[Help:VE207|"Attached track asset $(CHILD) failed to load."]]
|-
|208||[[Help:VE208|"Attached track asset not specified for track $(INDEX)."]]
|-
|209||[[Help:VE209|"Asset is missing the required 'attached-track' container."]]
|-
|210||[[Help:VE210|"Asset is missing the required 'track' tag."]]
|-
|211||[[Help:VE211|"Asset is missing the required 'road' tag."]]
|-
|212||[[Help:VE212|"Traincar asset must have at least two bogeys."]]
|-
|213||[[Help:VE213|"Traincar asset has invalid bogey placement."]]
|-
|214||[[Help:VE214|"Traincar asset has invalid length."]]
|-
|215||[[Help:VE215|"Asset has an invalid number of LODs: $(LOD_COUNT)"]]
|-
|216||[[Help:VE216|"Material $(MATERIAL) in mesh file $(MESH) has an inappropriate texture slot assigned: $(TEXTURE)"]]
|-
|217||[[Help:VE217|"Material $(MATERIAL) in mesh file $(MESH) has no texture assigned to a required slot: $(TEXTURE)"]]
|-
|218||[[Help:VE218|"Asset has duplicate attached track at track $(INDEX)."]]
|-
|219||[[Help:VE219|"Failed to load driver mesh $(ASSETID)."]]
|-
|220||[[Help:VE220|Miscellaneous script compiler output.]]
|-
|221||[[Help:VE221|"$(ASSETID) is faulty and will not be loaded."]]
|-
|222||[[Help:VE222|"Failed to load mesh $(ASSETID)-$(MESHFILE) for TNI plugin renderer."]]
|-
|223||[[Help:VE223|"Unable to create mesh index $(MESHINDEX) for asset $(ASSET)."]]
|-
|224||[[Help:VE224|"Corrupted data in mesh file '$(FILENAME)'."]]
|-
|225||[[Help:VE225|"Failed to query asset details for featured asset."]]
|-
|226||[[Help:VE226|"Failed to upload asset details for featured asset: $(ERRORTEXT)"]]
|-
|227||[[Help:VE227|"Missing image for featured asset."]]
|-
|228||[[Help:VE228|"Failed to read image file for featured asset."]]
|-
|229||[[Help:VE229|"DLC marketing image is missing or incorrectly sized for featured asset."]]
|-
|230||[[Help:VE230|"DLS thumbnail image is missing or incorrectly sized for featured asset."]]
|-
|231||[[Help:VE231|"Failed to open image file for featured asset."]]
|-
|232||[[Help:VE232|"Failed to upload image for featured asset: $(ERRORTEXT)"]]
|-
|233||[[Help:VE233|"One or more featured assets was not provided."]]
|-
|234||[[Help:VE234|"Asset is not present in the featured assets list."]]
|-
|235||[[Help:VE235|"Featured asset is not present in the input."]]
|-
|236||[[Help:VE236|"Featured asset was not available."]]
|-
|237||[[Help:VE237|"Featured asset failed validation."]]
|-
|238||[[Help:VE238|"Featured asset has faulty or missing dependencies."]]
|-
|239||[[Help:VE239|"Featured asset is Base content."]]
|-
|240||[[Help:VE240|"Featured asset is missing an English name or description."]]
|-
|241||[[Help:VE241|"Newly built package is not compatible with previously released version."]]
|-
|242||[[Help:VE242|"Unable to load animation file '$(FILE)' (file not found, or is damaged)."]]
|-
|243||[[Help:VE243|"Failed to submit changes to asset $(ASSET_KUID) due to file access error"]]
|-
|244||[[Help:VE244|"Files in base assets cannot use importers: $(FILE)"]]
|-
|245||[[Help:VE245|"Missing compiled texture: $(FILE)"]]
|-
|246||[[Help:VE246|"Missing source texture: $(FILE)"]]
|-
|247||[[Help:VE247|"Creating default texture.txt file: $(FILE)"]]
|-
|248||[[Help:VE248|"Failed to create *.texture.txt file for source image: $(FILE)"]]
|-
|249||[[Help:VE249|"Failed to compile *.texture.txt file: $(FILE)"]]
|-
|250||[[Help:VE250|"Material Metadata expected data for texture slot '$(SLOT)' of material '$(MATERIAL)' but none found."]]
|-
|251||[[Help:VE251|"Material Metadata expected *.texture resource for texture slot '$(SLOT)' of material '$(MATERIAL)' bout found: $(FOUND)"]]
|-
|252||[[Help:VE252|"Mesh material expected data for texture slot '$(SLOT)' of material '$(MATERIAL)' but none found."]]
|-
|253||[[Help:VE253|"WriteAnimationFileBoneChunk> excessive bone-chunk count."]]
|-
|254||[[Help:VE254|"Unable to open mesh metadata file: $(FILE)"]]
|-
|255||[[Help:VE255|"Mesh contains unsupported non-triangle primitives."]]
|-
|256||[[Help:VE256|"Mesh contains invalid material index."]]
|-
|257||[[Help:VE257|"Mesh contains no primitives."]]
|-
|258||[[Help:VE258|"Unable to determine vertex format."]]
|-
|259||[[Help:VE259|"Unsupported number of texture channels."]]
|-
|260||[[Help:VE260|"Invalid index in primitive."]]
|-
|261||[[Help:VE261|"Unable to create animation file: $(FILE)"]]
|-
|262||[[Help:VE262|"Unable to open animation event file: $(FILE)"]]
|-
|263||[[Help:VE263|"Unable to parse animation event file: $(FILE)"]]
|-
|264||[[Help:VE264|"Parsed animation event file $(FILE) with $(COUNT) events."]]
|-
|265||[[Help:VE265|"Unable to search path: '$(FILE_PATH)'"]]
|-
|266||[[Help:VE266|"Multiple values found for engine spec param <kuid:xxx:yyy>/tag-name (Value1 and Value2)"]]
|-
|267||[[Help:VE267|"member $(MEMBER) is obsolete in object $(CLASS)."]]
|-
|268||[[Help:VE268|"Mesh file is unused in this asset: '$(FILE)'"]]
|}

Help:VE267

2021-11-16T03:51:28Z

Windwalkr: Created page with "=member $(MEMBER) is obsolete in object $(CLASS).= This error is reported by the TrainzScript compiler when script code is attempting to call an obsolete function or acce..."

=member $(MEMBER) is obsolete in object $(CLASS).=

This error is reported by the [[TrainzScript]] compiler when script code is attempting to call an obsolete function or access an obsolete member. This error indicates that the script is not fully compatible with newer versions of the game (eg. TRS19 onward) and may not work correctly or may induce runtime performance problems. Depending on the version of Trainz in use, and the [[trainz-build]] version of the asset in question, this error may be considered a warning only. Script authors should be careful attention to this message even in cases where it is "just" a warning; it indicates a problem that needs fixing to ensure correct behaviour.

==Legacy Scripts==
Assets scripts developed at a time when the function/member in question was not flagged as obsolete may trigger this error. This means that the asset is reliant on obsolete functionality and will need to be updated or replaced. Route and session developers should avoid using such content in their routes. Any such content uploaded to the [[Download Station]] may be considered faulty and may be automatically submitted to the [[Content Repair Group]].

==Legacy Session Support==
There is also a scenario where an update to a legacy asset may correctly use modern functionality, but also offer a fallback mode where legacy script APIs are used if the asset version originally placed used the legacy APIs. Scripts should be written such that this should be a one-off scenario with an in-place upgrade to new data formats. This should not result in the scripts continuing to use the fallback mode in place of the modern APIs.

Category:Validation Errors

2021-11-16T02:07:16Z

Windwalkr:

Validation Error (VE) numbers are logged during content validation, to allow users to look up particular validation messages to better understand the source of the problem. Normal logs provide a substantial amount of technical detail about the error, but typically assume that the reader is familiar with the subject matter and will understand why the log is relevant. This wiki provides the necessary background information to understanding many of the logs, however a user who is unfamiliar with the area in question may not know where to start looking. VE numbers allow users to quickly find relevant pages in the wiki without any prior knowledge of the subject.

This page serves as a master guide to all VE numbers currently logged by Trainz. This page does not provide detailed information on any given VE number- please refer to the individual VE number pages for specific details. The error text here is correct for the English localisation of Trainz at the time of writing, however the exact text may change from time to time. It is intended that the overall meaning of a VE number will never change- new VE numbers will be issued instead, and old VE numbers may be made obsolete.

Logs which lack VE numbers do not belong on this page.

The individual VE pages can be found at the links below, or can be accessed directly from [[Content Manager]] by right-clicking on the Validation Error in the results log, and selecting "View Help for This Message".

{|
|-
|1||[[Help:VE1|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Decimal value."]]
|-
|2||[[Help:VE2|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Integer value."]]
|-
|3||[[Help:VE3|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|4||[[Help:VE4|"'$(TAG_NAME)' must have a positive value."]]
|-
|5||[[Help:VE5|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|6||[[Help:VE6|"'$(TAG_NAME)' must not be zero."]]
|-
|7||[[Help:VE7|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|8||[[Help:VE8|"The value for '$(TAG_NAME)' must be between '$(MIN)' and '$(MAX)' but was specified as '$(VALUE)'."]]
|-
|9||[[Help:VE9|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|10||[[Help:VE10|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|11||[[Help:VE11|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|12||[[Help:VE12|"No string-table entry found with tag '$(VALUE)' for for string-token tag '$(TAG)'."]]
|-
|13||[[Help:VE13|"Missing or invalid selection for tag '$(TAG_NAME)' in '$(CONT_NAME)'."]]
|-
|14||[[Help:VE14|"Missing or invalid selection for tag '$(TAG_NAME)' in '$(CONT_NAME)'."]]
|-
|15||[[Help:VE15|"Attachment point '$(TAG_NAME)' in '$(CONT_NAME)' must be found in mesh '$(MESH_NAME)'."]]
|-
|16||[[Help:VE16|"Container '$(CONT_NAME)' does not have an 'att-parent' tag which is required to reference an attachment point."]]
|-
|17||[[Help:VE17|"Attachment point '$(TAG_NAME)' in '$(CONT_NAME)' must be found in mesh '$(MESH_NAME)'."]]
|-
|18||[[Help:VE18|"Attachment point '$(TAG_VAL)' referenced by tag '$(TAG_NAME)' in '$(CONT_NAME)' was not found."]]
|-
|19||[[Help:VE19|"Effect '$(EFFECT_NAME)' in '$(CONT_NAME)' was not found within the mesh table."]]
|-
|20||[[Help:VE20|"Mesh '$(MESH_NAME)' referenced in '$(CONT_NAME)' was not found within the mesh table."]]
|-
|21||[[Help:VE21|"Attachment point '$(TAG_VAL)' referenced by tag '$(TAG_NAME)' in '$(CONT_NAME)' was not found."]]
|-
|22||[[Help:VE22|"Missing or invalid selection for tag '$(TAG_NAME)' in '$(CONT_NAME)'."]]
|-
|23||[[Help:VE23|"Invalid tag name '$(TAG_NAME)' in container '$(CONT_NAME)'."]]
|-
|24||[[Help:VE24|"Invalid tag name '$(TAG_NAME)' in container '$(CONT_NAME)'."]]
|-
|25||[[Help:VE25|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|26||[[Help:VE26|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|27||[[Help:VE27|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' must have a mesh file extension."]]
|-
|28||[[Help:VE28|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' must have an image file extension."]]
|-
|29||[[Help:VE29|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' must have an animation file extension."]]
|-
|30||[[Help:VE30|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' refers to a nonexistent file: '$(FILENAME)'."]]
|-
|31||[[Help:VE31|"Invalid tag name '$(TAG_NAME)' in container '$(CONT_NAME)'."]]
|-
|32||[[Help:VE32|"Alias mesh requires valid parent asset."]]
|-
|33||[[Help:VE33|"Alias mesh '$(FILE)' not found in dependency $(KUID)."]]
|-
|34||[[Help:VE34|"Alias mesh '$(FILE)' not found in latest version ($(NEW_KUID)) of dependency $(OLD_KUID)."]]
|-
|35||[[Help:VE35|"Required alias mesh asset $(KUID) is missing and cannot be validated."]]
|-
|36||[[Help:VE36|"The texture '$(FILE)' failed to load."]]
|-
|37||[[Help:VE37|"The texture '$(FILE)' is not a power of 2, please resize it."]]
|-
|38||[[Help:VE38|"The texture '$(FILE)' is not square. Cubemap textures need to have the same width and height."]]
|-
|39||[[Help:VE39|"The texture '$(FILE)' is a uniform color."]]
|-
|40||[[Help:VE40|"Unable to load $(TYPE) texture '$(TEXTURE)' for texture file '$(FILE)'."]]
|-
|41||[[Help:VE41|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Integer value."]]
|-
|42||[[Help:VE42|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Decimal value."]]
|-
|43||[[Help:VE43|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Boolean value."]]
|-
|44||[[Help:VE44|"Tag '$(TAG_NAME)' in the container '$(CONT_NAME)' is obsolete."]]
|-
|45||[[Help:VE45|"The Tag '$(TAG_NAME)' is not permitted within a container of type '$(CONT_NAME)'."]]
|-
|46||[[Help:VE46|"Internal Error: The template does not specify that a smoke container is valid in the container being parsed."]]
|-
|47||[[Help:VE47|"Container '$(CONT_NAME)' is not permitted in this section."]]
|-
|48||[[Help:VE48|"This asset uses an obsolete trainz-build number. Trainz-build numbers below $(LOWEST_TRAINZBUILD) are no longer supported."]]
|-
|49||[[Help:VE49|"Required tag 'kind' is not present. Ensure this is a valid config file."]]
|-
|50||[[Help:VE50|"Unsupported kind '$(KIND)'."]]
|-
|51||[[Help:VE51|"Tag '$(TAG_NAME)' in the container '$(CONT_NAME)' is obsolete."]]
|-
|52||[[Help:VE52|"The Tag '$(TAG_NAME)' is not permitted within a container of type '$(CONT_NAME)'."]]
|-
|53||[[Help:VE53|"This container is no longer supported."]]
|-
|54||[[Help:VE54|"The Tag '$(TAG_NAME)' is not permitted within a container of type '$(CONT_NAME)'."]]
|-
|55||[[Help:VE55|"This container is no longer supported."]]
|-
|56||[[Help:VE56|"Container '$(CONT_NAME)' is not permitted in this section."]]
|-
|57||[[Help:VE57|"Container '$(CONT_NAME)' is not permitted in this section."]]
|-
|58||[[Help:VE58|"The tag '$(TAG_NAME)' is not a valid container type (expected '$(TYPE)')."]]
|-
|59||[[Help:VE59|"Internal error: unknown dataType - kind '$(KIND)'."]]
|-
|60||[[Help:VE60|"Required tag '$(TAG_NAME)' was missing and has been set to default."]]
|-
|61||[[Help:VE61|"Required tag '$(TAG_NAME)' was missing and has been set to default."]]
|-
|62||[[Help:VE62|"Required container '$(CONT_NAME)' is missing."]]
|-
|63||[[Help:VE63|"The cubemap texture '$(FILE)' has missing images. Please verify the texture.txt file."]]
|-
|64||[[Help:VE64|"Cubemap texture '$(FILE)' contains images of different sizes."]]
|-
|65||[[Help:VE65|"The *.texture.txt file is missing for texture resource '$(FILE)'."]]
|-
|66||[[Help:VE66|"The texture file '$(FILE)' contains non-ANSI characters. Textures must be ANSI."]]
|-
|67||[[Help:VE67|"The texture '$(FILE)' does not seem to have a primary texture set. Please verify the texture.txt file."]]
|-
|68||[[Help:VE68|"The primary and alpha texture are not the same size for '$(FILE)'."]]
|-
|69||[[Help:VE69|"Binary conversion failed for texture resource '$(FILE)'."]]
|-
|70||[[Help:VE70|"The KUID tag is not a valid KUID value: '$(string)'."]]
|-
|71||[[Help:VE71|"Unsupported SpeedTree version for mesh: $(FILE)"]]
|-
|72||[[Help:VE72|"Unable to load mesh file: '$(FILE)'"]]
|-
|73||[[Help:VE73|"Image file '$(FILE)' is incorrectly used as both a texture.txt source file and a raw image file."]]
|-
|74||[[Help:VE74|"Image file '$(FILE)' is incorrectly used as both a texture.txt source file and a raw image file."]]
|-
|76||[[Help:VE76|"Unable to load mesh file: '$(FILE)'"]]
|-
|77||[[Help:VE77|"Unable to load indexed mesh '$(FILE)'"]]
|-
|79||[[Help:VE79|"Unable to load animation file '$(FILE)' (mesh has not been loaded correctly)."]]
|-
|81||[[Help:VE81|"The high-poly mesh '$(FILE)' should have LOD levels."]]
|-
|82||[[Help:VE82|"High-detail .im files are not supported for traincar assets, as they are likely to perform poorly. It is recommended that you upgrade '$(FILE)' to a .lm file."]]
|-
|83||[[Help:VE83|"The file '$(FILE)' is provided in LM format despite having no attachment points and no animation support. This may have a negative impact on performance."]]
|-
|84||[[Help:VE84|"The file '$(FILE)' is provided in LM format despite containing only a single mesh. This may have a negative impact on performance."]]
|-
|85||[[Help:VE85|"The file '$(FILE)' is provided in LM format, however the high-detail mesh is comprised of less than 300 polygons. This may have a negative impact on performance."]]
|-
|86||[[Help:VE86|"Legacy .pm files are no longer supported, and will perform poorly. It is recommended that you switch to using a .lm file."]]
|-
|87||[[Help:VE87|"Legacy .pm files are no longer supported, and will perform poorly. It is recommended that you switch to using a .lm file."]]
|-
|88||[[Help:VE88|"This asset has a trainz-build number which is not recognised by this tool."]]
|-
|89||[[Help:VE89|"Tag '$(TAG_NAME)' in the container '$(CONT_NAME)' is obsolete."]]
|-
|90||[[Help:VE90|"This asset has an invalid KUID user id"]]
|-
|91||[[Help:VE91|"The dependency $(KUID) has an invalid KUID User ID and cannot be used"]]
|-
|92||[[Help:VE92|"Duplicate '$(TAG_NAME)' containers in '$(CONT_NAME)'. Containers must have a unique name."]]
|-
|93||[[Help:VE93|"Duplicate '$(TAG_NAME)' tags in '$(CONT_NAME)'. Tags must have a unique name."]]
|-
|94||[[Help:VE94|"This asset requires a shadow mesh, but the mesh table does not contain one."]]
|-
|95||[[Help:VE95|"This asset does not have a mesh that is visible by default."]]
|-
|96||[[Help:VE96|"Maximum of 5 running number fonts supported."]]
|-
|97||[[Help:VE97|"The running number font directory '$(DIR)' could not be found."]]
|-
|98||[[Help:VE98|"The running number font file '$(DIR)/$(FILE)' could not be found."]]
|-
|99||[[Help:VE99|"The track-sound container '$(NAME)' has no bogey, track or track-parent tag."]]
|-
|100||[[Help:VE100|"Required tag '$(TAG_NAME)' was missing and has been set to default."]]
|-
|101||[[Help:VE101|"The file '$(FILE)' does not exist."]]
|-
|102||[[Help:VE102|"Failed to load sound file '$(FILE)', please ensure this is a valid wav file."]]
|-
|103||[[Help:VE103|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|104||[[Help:VE104|"Multiple template property bindings for rule property '$(PROP)' for rule '$(RULE)'."]]
|-
|105||[[Help:VE105|"The template property '$(NAME)' specified in the rule-template-bindings container of rule '$(RULE)' does not exist."]]
|-
|106||[[Help:VE106|"The high-detail meshes in season $(SEASON) total more than $(LIMIT) polygons. This may have a negative impact on performance: $(LOD_SUMMARY)"]]
|-
|107||[[Help:VE107|"The high-detail meshes total more than $(LIMIT) polygons. This may have a negative impact on performance: $(LOD_SUMMARY)"]]
|-
|108||[[Help:VE108|"The low-detail meshes in season $(SEASON) total more than 500 polygons. This may have a negative impact on performance: $(LOD_SUMMARY)"]]
|-
|109||[[Help:VE109|"The low-detail meshes total more than 500 polygons. This may have a negative impact on performance: $(LOD_SUMMARY)"]]
|-
|110||[[Help:VE110|"The meshes in LOD level $(LOD_LEVEL) in season $(SEASON) must total at least 20% fewer polygons than the next higher LOD in the same season: $(LOD_SUMMARY)"]]
|-
|111||[[Help:VE111|"The meshes in LOD level $(LOD_LEVEL) must total at least 20% fewer polygons than the next higher LOD: $(LOD_SUMMARY)"]]
|-
|112||[[Help:VE112|"Multiple track stretches between '$(FROM_VERTEX)' and '$(TO_VERTEX)' in container '$(CONT_NAME)'. Track stretches must be unique."]]
|-
|113||[[Help:VE113|"An image file ('$(FILE)') has been supplied where a texture file ('*.texture.txt') is required."]]
|-
|114||[[Help:VE114|"An image file ('$(FILE)') has been supplied where a texture file ('*.texture.txt') is required."]]
|-
|115||[[Help:VE115|"The texture file '$(FILE)' does not exist."]]
|-
|116||[[Help:VE116|"No texture file has been specified for this texture asset."]]
|-
|117||[[Help:VE117|"'$(TAG_0)' must be set to a '$(KIND)' for '$(TAG_1)' to be allowed."]]
|-
|118||[[Help:VE118|"Tag '$(TAG_0)' requires that '$(TAG_1)' be set to '$(KIND)'."]]
|-
|119||[[Help:VE119|"The tag '$(TAG_NAME)' is not valid for kind '$(KIND)'."]]
|-
|120||[[Help:VE120|"Tag '$(TAG_0)', requires the tag '$(TAG_1)' to be present."]]
|-
|121||[[Help:VE121|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|122||[[Help:VE122|"'$(TAG_NAME)' must have a positive value."]]
|-
|123||[[Help:VE123|"The script file '$(FILE)' does not exist."]]
|-
|124||[[Help:VE124|"The file '$(FILE)' does not exist."]]
|-
|125||[[Help:VE125|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|126||[[Help:VE126|"'$(TAG_NAME)' must not be zero."]]
|-
|127||[[Help:VE127|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|128||[[Help:VE128|"The value for '$(TAG_NAME)' must be between '$(MIN)' and '$(MAX)' but was specified as '$(VALUE)'."]]
|-
|129||[[Help:VE129|"Incorrect number of values for the tag '$(TAG_NAME)', expected $(NUM_0) values, found $(NUM_1)."]]
|-
|130||[[Help:VE130|"Too many values for the tag '$(TAG_NAME)', maximum is $(MAX) values, found $(FOUND)."]]]]
|-
|131||[[Help:VE131|"Value must be a mesh from the mesh-table (not a parent container)."]]
|-
|132||[[Help:VE132|"The attachment point '$(ATT)' must belong to the parent mesh of the effect (mesh=$(MESH))."]]
|-
|133||[[Help:VE133|"A light container must be present to link the signals."]]
|-
|134||[[Help:VE134|"'$(NUM)' must be a valid light number from the light container."]]
|-
|135||[[Help:VE135|"'$(TAG_0)' requires that the tag '$(TAG_1)' be present."]]
|-
|136||[[Help:VE136|"'$(TAG_0)' requires that the tag '$(TAG_1)' be present."]]
|-
|137||[[Help:VE137|"Empty or invalid running number specified at character index $(INDEX)"]]
|-
|138||[[Help:VE138|"Running number specified at character index $(INDEX) is too large, must be less than 9 characters."]]
|-
|139||[[Help:VE139|"Invalid running number range specified at character index $(INDEX), ($(FROM)-$(TO))."]]
|-
|140||[[Help:VE140|"Running number range '$(FROM)-$(TO)' specified at character index $(INDEX) overlaps already in use numbers, running numbers must be unique."]]
|-
|141||[[Help:VE141|"Running number '$(NUMBER)' specified at character index $(INDEX) is already in use."]]
|-
|142||[[Help:VE142|"Invalid character '$(CHAR)' specified in running number list, only numbers, ',' and '-' are supported."]]
|-
|143||[[Help:VE143|"Possible running number list is too large, the set must contain less than 20000 possibilities."]]
|-
|144||[[Help:VE144|"Category code 'ZX - Paintshed template' is obsolete."]]
|-
|145||[[Help:VE145|"Category code 'ZX - Paintshed template' is obsolete."]]
|-
|146||[[Help:VE146|"An asset must be specified for tag '$(TAG_NAME)'."]]
|-
|147||[[Help:VE147|"The tag(s) $(MISPLACED_TAGS) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|148||[[Help:VE148|"The tag(s) $(MISPLACED_TAGS) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|149||[[Help:VE149|"The mesh(es) $(MISPLACED_MESHES) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|150||[[Help:VE150|"The mesh(es) $(MISPLACED_MESHES) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|151||[[Help:VE150|"The mesh(es) $(MISPLACED_MESHES) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|152||[[Help:VE152|"The tags $(MISSING_TAGS) are not all defined. The default values will be used and the positions of the elements may not fit your track."]]
|-
|153||[[Help:VE153|"The mesh $(MESH) is present but the tag $(MISSING_TAG) is not defined."]]
|-
|154||[[Help:VE154|"The mesh $(MESH) is present but the tag $(MISSING_TAG) is not defined."]]
|-
|155||[[Help:VE155|"The mesh $(MESH) is present but the tags $(MISSING_TAGS) are not all defined."]]
|-
|156||[[Help:VE156|"The tag $(MISSING_TAG) is not defined. The default value will be used and the positions of the elements may not fit your track."]]
|-
|157||[[Help:VE157|"The mesh $(MESH) is present but the tag $(MISSING_TAG) is missing. The default value will be used and the positions of the elements may not fit your track."]]
|-
|158||[[Help:VE158|"Unable to open .lm.txt file: $(FILE)"]]
|-
|159||[[Help:VE159|"Unable to parse .lm.txt file: $(FILE)"]]
|-
|160||[[Help:VE160|"No 'mesh' keys found in .lm.txt file: $(FILE)"]]
|-
|161||[[Help:VE161|"$(LODCOUNT) LODs in .lm.txt file: $(FILE)"]]
|-
|162||[[Help:VE162|"One of the LOD reductions of '$(FILE)' introduces a new attachment point: $(ATT)"]]
|-
|163||[[Help:VE163|"Unable to parse .im file: $(FILE)"]]
|-
|164||[[Help:VE164|"Invalid position data in .im file: $(FILE)"]]
|-
|165||[[Help:VE165|"Texture '$(TEXTURE)' is missing or could not be loaded in mesh '$(FILE)', material '$(MATERIAL)'."]]
|-
|166||[[Help:VE166|"$(COMBINEDCOUNT) combined chunks (of $(SOURCECOUNT) source) in .im file: $(FILE)"]]
|-
|167||[[Help:VE167|"Source image texture file '$(TEXTUREFILE)' is too large for '$(ASSETFILE)' ($(WIDTH)x$(HEIGHT))"]]
|-
|168||[[Help:VE168|"File '$(TEXTUREFILE)' is not a valid compiled texture file for '$(ASSETFILE)'"]]
|-
|169||[[Help:VE169|"Compiled texture file '$(TEXTUREFILE)' is unsupported version for '$(ASSETFILE)'"]]
|-
|170||[[Help:VE170|"Failed to open compiled texture '$(TEXTUREFILE)' for '$(ASSETFILE)'"]]
|-
|171||[[Help:VE171|"Expected texture file type but found '$(TEXTUREFILE)' for '$(ASSETFILE)'"]]
|-
|172||[[Help:VE172|"Script class does not match asset kind ($(KIND))."]]
|-
|173||[[Help:VE173|"Material '$(MATERIAL)' in mesh '$(FILE)' is not of a recognised material type."]]
|-
|174||[[Help:VE174|"MeshObjectSpec::LinkSpecs> Mesh-table element #$(MESH_INDEX) parent mesh is invalid."]]
|-
|175||[[Help:VE175|"MeshObjectSpec::LinkSpecs> Mesh-table element #$(MESH_INDEX) is part of invalid hierarchy."]]
|-
|176||[[Help:VE176|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' must have a texture file extension."]]
|-
|177||[[Help:VE177|"The kuid '$(KUID)' is not in the database, and could not be found in any known location. Ensure that this is a valid asset."]]
|-
|178||[[Help:VE178|"The asset specified in '$(KUID)' is not installed locally but is available for download."]]
|-
|179||[[Help:VE179|"The kuid '$(KUID)' specified in '$(TAG_NAME)' is not of the correct type."]]
|-
|180||[[Help:VE180|"Integrity check failure on $(FILE). One or more route/session tiles may be missing."]]
|-
|181||[[Help:VE181|"The tag '$(TAG_NAME)' requires a minimum asset version of $(MIN_VERSION)"]]
|-
|182||[[Help:VE182|"Material '$(MATERIAL)' in mesh '$(FILE)' is missing a texture for a mandatory texture slot."]]
|-
|183||[[Help:VE183|"FBX file is in an unsupported older format."]]
|-
|184||[[Help:VE184|"KIND '$(KIND)' requires trainz-build $(TRAINZBUILD)."]]
|-
|185||[[Help:VE185|"Material '$(MATERIAL)' in mesh '$(FILE)' has heightmap texture. Provide a normal map instead."]]
|-
|186||[[Help:VE186|"Material '$(MATERIAL)' is shared between multiple chunks in this asset but the material parameters conflict."]]
|-
|187||[[Help:VE187|"The value '$(VALUE)' in not a valid KUID."]]
|-
|188||[[Help:VE188|"Custom render plugin failed to load mesh '$(FILE)'"]]
|-
|189||[[Help:VE189|"Collision data exceeds $(LIMIT)KB. Please specify a different generation method or a simplified mesh."]]
|-
|190||[[Help:VE190|"Tag '$(NAME)' is unable to be converted from $(TYPE1) to $(TYPE2)"]]
|-
|191||[[Help:VE191|"Tag '$(NAME)' does not contain a valid integer: $(VALUE)"]]
|-
|192||[[Help:VE192|"Tag '$(NAME)' does not contain a valid float list: $(VALUE)"]]
|-
|193||[[Help:VE193|"Tag '$(NAME)' does not contain a valid float"]]
|-
|194||[[Help:VE194|"Tag '$(NAME)' does not contain a valid kuid: $(VALUE)"]]
|-
|195||[[Help:VE195|"Unable to parse chunk $(CHUNK_INDEX) in mesh file: $(FILE)"]]
|-
|196||[[Help:VE196|"Failed to load bogey $(KUID)"]]
|-
|197||[[Help:VE197|"Syntax error in script '$(SCRIPT)' for asset $(ASSET)"]]
|-
|198||[[Help:VE198|"Session failed to load route asset: $(KUID)"]]
|-
|199||[[Help:VE199|"Asset $(KUID) failed to load. Unloading resources."]]
|-
|200||[[Help:VE200|"Unable to load mesh $(NAME) for $(ASSET_ID)"]]
|-
|201||[[Help:VE201|"Traincar is missing required attachment point: $(ATT_NAME)"]]
|-
|202||[[Help:VE202|"Parse error reading twinkles file: $(FILE)"]]
|-
|203||[[Help:VE203|"Bad sequence order in $(TAG_NAME) list. Each element must be greater than the last."]]
|-
|204||[[Help:VE204|"Invalid range in $(TAG_NAME) list. Elements must be greater than or equal to $(INC_MIN) and less than $(EXC_MAX)."]]
|-
|205||[[Help:VE205|"Invalid element count in $(TAG_NAME) list. This list must have at least $(COUNT) elements (to match the $(TAG_START) list)."]]
|-
|206||[[Help:VE206|"The season-selector references season '$(SEASON)', but this does not exist in the texture-variants container."]]
|-
|207||[[Help:VE207|"Attached track asset $(CHILD) failed to load."]]
|-
|208||[[Help:VE208|"Attached track asset not specified for track $(INDEX)."]]
|-
|209||[[Help:VE209|"Asset is missing the required 'attached-track' container."]]
|-
|210||[[Help:VE210|"Asset is missing the required 'track' tag."]]
|-
|211||[[Help:VE211|"Asset is missing the required 'road' tag."]]
|-
|212||[[Help:VE212|"Traincar asset must have at least two bogeys."]]
|-
|213||[[Help:VE213|"Traincar asset has invalid bogey placement."]]
|-
|214||[[Help:VE214|"Traincar asset has invalid length."]]
|-
|215||[[Help:VE215|"Asset has an invalid number of LODs: $(LOD_COUNT)"]]
|-
|216||[[Help:VE216|"Material $(MATERIAL) in mesh file $(MESH) has an inappropriate texture slot assigned: $(TEXTURE)"]]
|-
|217||[[Help:VE217|"Material $(MATERIAL) in mesh file $(MESH) has no texture assigned to a required slot: $(TEXTURE)"]]
|-
|218||[[Help:VE218|"Asset has duplicate attached track at track $(INDEX)."]]
|-
|219||[[Help:VE219|"Failed to load driver mesh $(ASSETID)."]]
|-
|220||[[Help:VE220|Miscellaneous script compiler output.]]
|-
|221||[[Help:VE221|"$(ASSETID) is faulty and will not be loaded."]]
|-
|222||[[Help:VE222|"Failed to load mesh $(ASSETID)-$(MESHFILE) for TNI plugin renderer."]]
|-
|223||[[Help:VE223|"Unable to create mesh index $(MESHINDEX) for asset $(ASSET)."]]
|-
|224||[[Help:VE224|"Corrupted data in mesh file '$(FILENAME)'."]]
|-
|225||[[Help:VE225|"Failed to query asset details for featured asset."]]
|-
|226||[[Help:VE226|"Failed to upload asset details for featured asset: $(ERRORTEXT)"]]
|-
|227||[[Help:VE227|"Missing image for featured asset."]]
|-
|228||[[Help:VE228|"Failed to read image file for featured asset."]]
|-
|229||[[Help:VE229|"DLC marketing image is missing or incorrectly sized for featured asset."]]
|-
|230||[[Help:VE230|"DLS thumbnail image is missing or incorrectly sized for featured asset."]]
|-
|231||[[Help:VE231|"Failed to open image file for featured asset."]]
|-
|232||[[Help:VE232|"Failed to upload image for featured asset: $(ERRORTEXT)"]]
|-
|233||[[Help:VE233|"One or more featured assets was not provided."]]
|-
|234||[[Help:VE234|"Asset is not present in the featured assets list."]]
|-
|235||[[Help:VE235|"Featured asset is not present in the input."]]
|-
|236||[[Help:VE236|"Featured asset was not available."]]
|-
|237||[[Help:VE237|"Featured asset failed validation."]]
|-
|238||[[Help:VE238|"Featured asset has faulty or missing dependencies."]]
|-
|239||[[Help:VE239|"Featured asset is Base content."]]
|-
|240||[[Help:VE240|"Featured asset is missing an English name or description."]]
|-
|241||[[Help:VE241|"Newly built package is not compatible with previously released version."]]
|-
|242||[[Help:VE242|"Unable to load animation file '$(FILE)' (file not found, or is damaged)."]]
|-
|243||[[Help:VE243|"Failed to submit changes to asset $(ASSET_KUID) due to file access error"]]
|-
|244||[[Help:VE244|"Files in base assets cannot use importers: $(FILE)"]]
|-
|245||[[Help:VE245|"Missing compiled texture: $(FILE)"]]
|-
|246||[[Help:VE246|"Missing source texture: $(FILE)"]]
|-
|247||[[Help:VE247|"Creating default texture.txt file: $(FILE)"]]
|-
|248||[[Help:VE248|"Failed to create *.texture.txt file for source image: $(FILE)"]]
|-
|249||[[Help:VE249|"Failed to compile *.texture.txt file: $(FILE)"]]
|-
|250||[[Help:VE250|"Material Metadata expected data for texture slot '$(SLOT)' of material '$(MATERIAL)' but none found."]]
|-
|251||[[Help:VE251|"Material Metadata expected *.texture resource for texture slot '$(SLOT)' of material '$(MATERIAL)' bout found: $(FOUND)"]]
|-
|252||[[Help:VE252|"Mesh material expected data for texture slot '$(SLOT)' of material '$(MATERIAL)' but none found."]]
|-
|253||[[Help:VE253|"WriteAnimationFileBoneChunk> excessive bone-chunk count."]]
|-
|254||[[Help:VE254|"Unable to open mesh metadata file: $(FILE)"]]
|-
|255||[[Help:VE255|"Mesh contains unsupported non-triangle primitives."]]
|-
|256||[[Help:VE256|"Mesh contains invalid material index."]]
|-
|257||[[Help:VE257|"Mesh contains no primitives."]]
|-
|258||[[Help:VE258|"Unable to determine vertex format."]]
|-
|259||[[Help:VE259|"Unsupported number of texture channels."]]
|-
|260||[[Help:VE260|"Invalid index in primitive."]]
|-
|261||[[Help:VE261|"Unable to create animation file: $(FILE)"]]
|-
|262||[[Help:VE262|"Unable to open animation event file: $(FILE)"]]
|-
|263||[[Help:VE263|"Unable to parse animation event file: $(FILE)"]]
|-
|264||[[Help:VE264|"Parsed animation event file $(FILE) with $(COUNT) events."]]
|-
|265||[[Help:VE265|"Unable to search path: '$(FILE_PATH)'"]]
|-
|266||[[Help:VE266|"Multiple values found for engine spec param <kuid:xxx:yyy>/tag-name (Value1 and Value2)"]]
|-
|267||[[Help:VE267|"member $(MEMBER) is obsolete in object $(CLASS)."]]

|}

Vehicle-running-numbers container

2021-08-04T23:48:26Z

Windwalkr:

The vehicle-running-numbers container is an optional subcontainer used by [[KIND Traincar]] assets to define the behaviour of automatic random running-number generation. Support for this subcontainer was added in [[Trainz A New Era]] as a faster alternative to various custom scripts which attempt to do the same thing.

==vehicle-running-numbers Container==

Example running numbers container:

vehicle-running-numbers
{
running-numbers "35050-35150"
}

==Supported Tags==
The vehicle-running-numbers container supports the following tags. Each tag is shown here with its default value.

running-numbers ""
multiple-unit-increment-front
multiple-unit-increment-rear

====running-numbers====
:Type: Text
:Desc: Specifies the valid running-number range(s) to randomly select from. This can be a list, a range, or any combination of both. For example:
running-numbers "12345,67890,30000-31000"
This example will cause the traincar to be randomly assigned the running number 12345, 67890, or any number in between 30000 (inclusive) and 31000 (exclusive). Running numbers are assigned on train placement, and can be overridden using the traincar properties dialog.

====multiple-unit-increment-front====
:Type: Integer
:Desc: Optional tag used for assigning sequential/identical running numbers to multiple-unit trains. See the following section for more information about multiple units.

====multiple-unit-increment-rear====
:Type: Integer
:Desc: Optional tag used for assigning sequential/identical running numbers to multiple-unit trains. See the following section for more information about multiple units.

==Multiple unit trains==
The multiple-unit-increment-* tags allow you to define sets of traincars which are automatically numbered identically or sequentially. This is useful for prototypical situations where multiple locomotives may be considered one unit, and thus numbered in some patterned way.

Each of these tags specifies whether the front/rear coupler of the traincar continues the multiple unit set. For example if you have a traincar asset which species only multiple-unit-increment-front, then two of those traincars coupled nose-to-nose will create a 'set'. Without the multiple-unit-increment-rear tag any traincar coupled to the rear will *not* be considered part of the set (regardless of any multiple-unit tag on that other traincar). This means that these tags effectively have no default value, as there presence alone will change the behaviour of the automatic numbering. If you do not want set numbering at all, do not add these tags.

Once a set of compatible traincars exists in a consist the frontmost traincar will be chosen as the 'seed' and given a random running number as normal. The coupled traincar will then be assigned a running-number based on the value of the relevant tag (e.g. multiple-unit-increment-front if the 'seed' traincar is coupled to the front). If this number is 0, the running-number will be identical. A value of 100 will result in adding 100 to the running-number of the seed. Negative values are allowed. This process continues until the end of the set, or until an invalid running-number is generated. Generation of an invalid running-number will result in a new set being created (with the current traincar becoming the new seed).

==Asset Creation / Trouble Shooting==

There is more information [[Alpha_Numbers|HERE]] to find out how to put running numbers on your Trainz content.

You can find a How To guide for adding the vehicle-running-numbers container to your asset [[Adding_the_Native_Automatic_Running_Numbers_system_to_a_traincar|Here]]

Return To
*[[Content_Creation]]
*[[KIND_Traincar|Kind Traincar]]

[[Category:Config Container|V]]

Adding the Native Automatic Running Numbers system to a traincar

2021-08-04T23:44:20Z

Windwalkr:

Introduced with Trainz: A New Era, the Native Vehicle Running Numbers system provides a built-in method of automatic running numbers for traincars (locomotives and rolling stock) in Trainz, using a range of numbers specified in the config.txt file to assign running numbers to the traincar when placed. The system also supports multiple-unit numbering (ie where each vehicle in a multiple-unit set will either have the same number, or can increase the number by an amount set in the relevant tags; see [[#Adding the Native Vehicle Running Numbers system to an asset|Adding to an asset.]]

The numbers can still be changed in-game via the Properties window as per any other traincar in Trainz.

The visible numbers on the traincar will still use the existing [[Alpha_Numbers|Alpha-Numbers]] system.

==Scripted assets==
Prior to Trainz: A New Era, many assets used scripts such as 'NumberIt', 'ARN' (Automatic Running Numbers), and other custom scripts to assign the running numbers to the traincar when placed. The script is the '.gs' file found in some Trainz assets; a single script file is normally used in Trainz, and as such may do multiple different things.

In many cases, these scripts allowed effectively unlimited number ranges, which caused the script to take a long time to load or process the running numbers. This could cause issues with Trainz loading the asset. Trainz: A New Era will limit how long the script can take to load, and hence if it takes too long it will time out and not load.

For Trainz: A New Era and onwards, it is recommended to use the Native Vehicle Running Numbers system to assign numbers to your traincars. This will help avoid script errors (causing numbers to not load, and possibly other functions on the traincar to not operate), and reduce the script load on Trainz itself.

==The Vehicle Running Numbers Container==
The Native Vehicle Running Numbers system is configured with some very simple tags, specifically the Vehicle Running Numbers container.

For detailed information on the tags in this container, see [[Vehicle-running-numbers_container|Vehicle Running Numbers container]], including information on multiple unit train setup.

The container, when entered into the config.txt file will appear as

vehicle-running-numbers
{
running-numbers "1-5,7,9-11"
}

The container allows you to enter individual numbers, as well as number ranges. Number ranges are specified with the lower end of the range first (inclusive), then a hyphen, then the higher end of the range (exclusive). Individual numbers, or multiple ranges, are separated by a comma (,). The above example will give the numbers 1, 2, 3, 4, 7, 9, 10.

==Adding the Native Vehicle Running Numbers system to an asset==
It is very simple to add the Native Vehicle Running Numbers system to an asset by following these steps. Please note, these steps do not cover updating assets to Trainz-Build 4.2, or adding alpha-numbers to an asset.

1) Open the asset for edit in Content Manager (Trainz Content), and open in explorer/finder (right click on the asset, go to 'open', then click on 'in explorer' or 'in finder')

2) Double click on the 'config.txt' file

3) Now that the config file is open, the first step is to ensure that your asset's Trainz-Build number is set to 4.2 (TANE release) or higher. You should always use the minimum Trainz-Build number that you can test the asset in (ie if you only have access to TANE SP2 or SP3 for testing, then you should use build 4.5).

3-A) Changing the Trainz-Build number on an existing asset will enforce the TANE level error checking on the assets, placing stricter [[Level_of_Detail|Level Of Detail]] requirements on assets, and correct material configuration (in particular where a material with the same name is shared between different meshes) and naming.

4) The next step is to enter the vehicle-running-numbers container into your asset. This is placed at the 'root level' of the config.txt (ie not inside any other containers). Copy and paste the following into your config.txt:
vehicle-running-numbers
{
running-numbers ""
}

5) You will now need to enter the number range for your traincar between the quote marks. For example:
running-numbers "1,5,20-50,75-100"

6) Save your config.txt file, and close the text editor.

7) Go back to Content Manager, right click on your asset, then click on submit.

8) Now try placing your traincar within Surveyor (do not place in Driver in TANE, as the running numbers may not automatically load due to a known bug in TANE). When placed it should automatically receive a number within the specified number range.

==Updating an asset with scripted running numbers==
If you are updating an existing asset with scripted running numbers, then there are a few things to be mindful of. The following steps are a general guide, as different script methods used may function differently, and require different steps.

1) Open the asset for edit in Content Manager, and open in explorer/finder (right click on the asset, go to 'open', then click on 'in explorer' or 'in finder')

2) Double click on the 'config.txt' file

3) Now that the config file is open, the first step is to ensure that your asset's Trainz-Build number is set to 4.2 (TANE release) or higher. You should always use the minimum Trainz-Build number that you can test the asset in (ie if you only have access to TANE SP2 or SP3 for testing, then you should use build 4.5).

3-A)Changing the Trainz-Build number on an existing asset will enforce the TANE level error checking on the assets, placing stricter [[Level_of_Detail|Level Of Detail]] requirements on assets, and correct material configuration (in particular where a material with the same name is shared between different meshes) and naming.

4) The next step is to remove the old config tags for the scripted running numbers. These will vary, but will generally mention 'numbers' or similar. For example, the 'NumbertIt' script has the following tags:
numberit-75134
{
numberit_prefix "94"
numberit_min "0000"
numberit_max "9999"
}
This entire container must be removed.

5)Once removed, the next step is to enter the vehicle-running-numbers container into your asset. This is placed at the 'root level' of the config.txt (ie not inside any other containers). Copy and paste the following into your config.txt:
vehicle-running-numbers
{
running-numbers ""
}

5) You will now need to enter the number range for your traincar between the quote marks. For example:
running-numbers "1,5,20-50,75-100"

6) Save your config.txt file, and close the text editor.

7) Go back to Content Manager, right click on your asset, then click on submit.

8) Now try placing your traincar within Surveyor (do not place in Driver in TANE, as the running numbers may not automatically load due to a known bug in TANE). When placed it should automatically receive a number within the specified number range.

<div style="background-color: #ddf5eb; border-style: dotted;">
TIP: Most scripts should not need the script edited after doing this, although if you know how to it is recommended that the running number code be removed from your asset's script, so as to reduce the resources used.

If the script only provides automatic running numbers, then the entire script (gs file) and the 'script' and 'class' config tags can be removed.
</div>

==In-game use==
When used in-game, the numbers will be automatically assigned. You can change the number on a traincar in Surveyor (or Driver) by following these steps:
#Open the Trains Tab
#Select the 'Properties' tool (the ? icon)
#Click on the traincar you wish to change; this will open that traincar's Properties window
#Click on the running number shown
#Enter the number you want the traincar to have
#Click the checkmark in the running number window
#Click the checkmark in the 'Properties' window
#You should now see the new number shown on the traincar

Alternatively, you can assign a new random number by following these steps:
#Open the Trains Tab
#Select the 'Properties' tool (the ? icon)
#Click on the traincar you wish to change; this will open that traincar's Properties window
#Click on the ( Automatic ) or ( Manual ) text to the right of the running number; this will cause a new number to be automatically generated.
#Click the checkmark in the 'Properties' window
#You should now see the new number shown on the traincar

Return To
*[[HowTo|How To Guides]]
*[[KIND_Traincar|Kind Traincar]]
*[[Vehicle-running-numbers_container|Vehicle-Running-Numbers Container]]

[[Category:How-to_guides|HowTo Guides]]

KIND Map

2021-04-06T23:58:16Z

Windwalkr: remove incorrect mention of carrate

{{FUN-beg}}
{{ORP-top}}
[[KIND Map]] is the trainz [[KIND|kind]] (Base {{wp|data type}}) used for organizing and storing a Map. The Maps data types are created in surveyor and stored under the \User data subfolder of the Trainz installation (versions after TS2009 SP2), so for the most part, hand-editing of a map [[Config.txt_file|config file]] should not be required.
{{user-tip|width=66%
|Maps, are called in ContentManager a Route (Set the search pane for '''category [[Route]]s''' to list all) and often called in the model railroading community as a '''Layout'''.
}}
=KIND Hierarchy=
Short of considering ContentManager a container, or speaking of the data base, the Map data type (in it's folder) is the highest organized data type in the software system data heirarchy. It holds the [[kuid-table|kuid]] and [[string-table|string]] tables defining the virtual world the player will interact with and links to all other assets applicable to a routes navigation in Surveyor, as well as specifying most of the 'world' data needed in the Driver Module.

==Parent Classes==
* [[KIND TrainzBaseSpec]]
==Child Classes==
* ''All non-map assets might be referenced in a map asset.''

=Supported Tags=
Each map asset supports the following tags. Each tag is shown here with its default value.

holdcarz 1
info-page "filename.htm"
region <NULLKUID>
workingscale 0
workingunits 0
water <KUID:-1:8009>
car0 <NULLKUID>
soundscript
{
}
world-origin
{
}
autosave 0

====holdcarz====
:Type: Boolean
:Desc: True if road traffic should be disabled.

====info-page====
:Type: Filename
:Desc:
::Original use: File reference to (usually) an HTML file (so called 'Tech Manuals') describing use of an asset, or in the case of a complex session or route, providing details in the form of text explanations, lists, tables, schedules and many many maps.
::Today:
::: a) In the vision of N3V game software engineers, obsolescent, so should be "No longer used."
::: b) In practice, some game asset developers are linking pages here on the TrainzOnline Wiki to serve as the tech manual for assets, a highly important need in complex routes.

====region====
:Type: [[KUID]]
:Desc: KUID of [[KIND_Region|Region]] asset that this map is set in.

====workingscale====
:Type: Number
:Desc: Index of the option picked for the world 'scale' in surveyor.

0 - 1:1 (Real Scale)
1 - 1:22.5 (G Scale)
2 - 1:24 (Half Inch scale)
3 - 1:32 (1 scale)
4 - 1:48 (0 scale)
5 - 1:64.5 (S scale)
6 - 1:76.2 (00 scale)
7 - 1:87.1 (HO scale)
8 - 1:120 (TT scale)
9 - 1:160 (N scale)
10 - 1:220 (Z scale)

====workingunits====
:Type: Number
:Desc: 0 for metric (speed in km/h, distances in metres), 1 for imperial (speed in mph, distances in feet).

====water====
:Type: [[KUID]]
:Desc: KUID of [[KIND_Water2|water]] asset that this map uses.

====soundscript====
:Type: Container
:Desc: [[%22soundscript%22_Container|SoundScript Container]] to specify ambient sound in this map.

====[["World-origin"_container|world-origin]]====
:Type: Container
:Desc: World origin container

====car0====
:Type: [[KUID]]
:Desc: KUID of car to add to the pool of available road traffic provided by the region.

This is a sequence - increment the number to add more cars.

====autosave====
:Type: boolean
:Desc: True if this map was generated by the surveyor auto-save process.

=Categories=
[[Category:Asset KIND|map]]
{{FUN-bot|map}}
{{ORP-bot|map}}

Category:Validation Errors

2020-07-30T08:36:11Z

Windwalkr:

Validation Error (VE) numbers are logged during content validation, to allow users to look up particular validation messages to better understand the source of the problem. Normal logs provide a substantial amount of technical detail about the error, but typically assume that the reader is familiar with the subject matter and will understand why the log is relevant. This wiki provides the necessary background information to understanding many of the logs, however a user who is unfamiliar with the area in question may not know where to start looking. VE numbers allow users to quickly find relevant pages in the wiki without any prior knowledge of the subject.

This page serves as a master guide to all VE numbers currently logged by Trainz. This page does not provide detailed information on any given VE number- please refer to the individual VE number pages for specific details. The error text here is correct for the English localisation of Trainz at the time of writing, however the exact text may change from time to time. It is intended that the overall meaning of a VE number will never change- new VE numbers will be issued instead, and old VE numbers may be made obsolete.

Logs which lack VE numbers do not belong on this page.

The individual VE pages can be found at the links below, or can be accessed directly from [[Content Manager]] by right-clicking on the Validation Error in the results log, and selecting "View Help for This Message".

{|
|-
|1||[[Help:VE1|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Decimal value."]]
|-
|2||[[Help:VE2|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Integer value."]]
|-
|3||[[Help:VE3|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|4||[[Help:VE4|"'$(TAG_NAME)' must have a positive value."]]
|-
|5||[[Help:VE5|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|6||[[Help:VE6|"'$(TAG_NAME)' must not be zero."]]
|-
|7||[[Help:VE7|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|8||[[Help:VE8|"The value for '$(TAG_NAME)' must be between '$(MIN)' and '$(MAX)' but was specified as '$(VALUE)'."]]
|-
|9||[[Help:VE9|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|10||[[Help:VE10|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|11||[[Help:VE11|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|12||[[Help:VE12|"No string-table entry found with tag '$(VALUE)' for for string-token tag '$(TAG)'."]]
|-
|13||[[Help:VE13|"Missing or invalid selection for tag '$(TAG_NAME)' in '$(CONT_NAME)'."]]
|-
|14||[[Help:VE14|"Missing or invalid selection for tag '$(TAG_NAME)' in '$(CONT_NAME)'."]]
|-
|15||[[Help:VE15|"Attachment point '$(TAG_NAME)' in '$(CONT_NAME)' must be found in mesh '$(MESH_NAME)'."]]
|-
|16||[[Help:VE16|"Container '$(CONT_NAME)' does not have an 'att-parent' tag which is required to reference an attachment point."]]
|-
|17||[[Help:VE17|"Attachment point '$(TAG_NAME)' in '$(CONT_NAME)' must be found in mesh '$(MESH_NAME)'."]]
|-
|18||[[Help:VE18|"Attachment point '$(TAG_VAL)' referenced by tag '$(TAG_NAME)' in '$(CONT_NAME)' was not found."]]
|-
|19||[[Help:VE19|"Effect '$(EFFECT_NAME)' in '$(CONT_NAME)' was not found within the mesh table."]]
|-
|20||[[Help:VE20|"Mesh '$(MESH_NAME)' referenced in '$(CONT_NAME)' was not found within the mesh table."]]
|-
|21||[[Help:VE21|"Attachment point '$(TAG_VAL)' referenced by tag '$(TAG_NAME)' in '$(CONT_NAME)' was not found."]]
|-
|22||[[Help:VE22|"Missing or invalid selection for tag '$(TAG_NAME)' in '$(CONT_NAME)'."]]
|-
|23||[[Help:VE23|"Invalid tag name '$(TAG_NAME)' in container '$(CONT_NAME)'."]]
|-
|24||[[Help:VE24|"Invalid tag name '$(TAG_NAME)' in container '$(CONT_NAME)'."]]
|-
|25||[[Help:VE25|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|26||[[Help:VE26|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|27||[[Help:VE27|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' must have a mesh file extension."]]
|-
|28||[[Help:VE28|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' must have an image file extension."]]
|-
|29||[[Help:VE29|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' must have an animation file extension."]]
|-
|30||[[Help:VE30|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' refers to a nonexistent file: '$(FILENAME)'."]]
|-
|31||[[Help:VE31|"Invalid tag name '$(TAG_NAME)' in container '$(CONT_NAME)'."]]
|-
|32||[[Help:VE32|"Alias mesh requires valid parent asset."]]
|-
|33||[[Help:VE33|"Alias mesh '$(FILE)' not found in dependency $(KUID)."]]
|-
|34||[[Help:VE34|"Alias mesh '$(FILE)' not found in latest version ($(NEW_KUID)) of dependency $(OLD_KUID)."]]
|-
|35||[[Help:VE35|"Required alias mesh asset $(KUID) is missing and cannot be validated."]]
|-
|36||[[Help:VE36|"The texture '$(FILE)' failed to load."]]
|-
|37||[[Help:VE37|"The texture '$(FILE)' is not a power of 2, please resize it."]]
|-
|38||[[Help:VE38|"The texture '$(FILE)' is not square. Cubemap textures need to have the same width and height."]]
|-
|39||[[Help:VE39|"The texture '$(FILE)' is a uniform color."]]
|-
|40||[[Help:VE40|"Unable to load $(TYPE) texture '$(TEXTURE)' for texture file '$(FILE)'."]]
|-
|41||[[Help:VE41|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Integer value."]]
|-
|42||[[Help:VE42|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Decimal value."]]
|-
|43||[[Help:VE43|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Boolean value."]]
|-
|44||[[Help:VE44|"Tag '$(TAG_NAME)' in the container '$(CONT_NAME)' is obsolete."]]
|-
|45||[[Help:VE45|"The Tag '$(TAG_NAME)' is not permitted within a container of type '$(CONT_NAME)'."]]
|-
|46||[[Help:VE46|"Internal Error: The template does not specify that a smoke container is valid in the container being parsed."]]
|-
|47||[[Help:VE47|"Container '$(CONT_NAME)' is not permitted in this section."]]
|-
|48||[[Help:VE48|"This asset uses an obsolete trainz-build number. Trainz-build numbers below $(LOWEST_TRAINZBUILD) are no longer supported."]]
|-
|49||[[Help:VE49|"Required tag 'kind' is not present. Ensure this is a valid config file."]]
|-
|50||[[Help:VE50|"Unsupported kind '$(KIND)'."]]
|-
|51||[[Help:VE51|"Tag '$(TAG_NAME)' in the container '$(CONT_NAME)' is obsolete."]]
|-
|52||[[Help:VE52|"The Tag '$(TAG_NAME)' is not permitted within a container of type '$(CONT_NAME)'."]]
|-
|53||[[Help:VE53|"This container is no longer supported."]]
|-
|54||[[Help:VE54|"The Tag '$(TAG_NAME)' is not permitted within a container of type '$(CONT_NAME)'."]]
|-
|55||[[Help:VE55|"This container is no longer supported."]]
|-
|56||[[Help:VE56|"Container '$(CONT_NAME)' is not permitted in this section."]]
|-
|57||[[Help:VE57|"Container '$(CONT_NAME)' is not permitted in this section."]]
|-
|58||[[Help:VE58|"The tag '$(TAG_NAME)' is not a valid container type (expected '$(TYPE)')."]]
|-
|59||[[Help:VE59|"Internal error: unknown dataType - kind '$(KIND)'."]]
|-
|60||[[Help:VE60|"Required tag '$(TAG_NAME)' was missing and has been set to default."]]
|-
|61||[[Help:VE61|"Required tag '$(TAG_NAME)' was missing and has been set to default."]]
|-
|62||[[Help:VE62|"Required container '$(CONT_NAME)' is missing."]]
|-
|63||[[Help:VE63|"The cubemap texture '$(FILE)' has missing images. Please verify the texture.txt file."]]
|-
|64||[[Help:VE64|"Cubemap texture '$(FILE)' contains images of different sizes."]]
|-
|65||[[Help:VE65|"The *.texture.txt file is missing for texture resource '$(FILE)'."]]
|-
|66||[[Help:VE66|"The texture file '$(FILE)' contains non-ANSI characters. Textures must be ANSI."]]
|-
|67||[[Help:VE67|"The texture '$(FILE)' does not seem to have a primary texture set. Please verify the texture.txt file."]]
|-
|68||[[Help:VE68|"The primary and alpha texture are not the same size for '$(FILE)'."]]
|-
|69||[[Help:VE69|"Binary conversion failed for texture resource '$(FILE)'."]]
|-
|70||[[Help:VE70|"The KUID tag is not a valid KUID value: '$(string)'."]]
|-
|71||[[Help:VE71|"Unsupported SpeedTree version for mesh: $(FILE)"]]
|-
|72||[[Help:VE72|"Unable to load mesh file: '$(FILE)'"]]
|-
|73||[[Help:VE73|"Image file '$(FILE)' is incorrectly used as both a texture.txt source file and a raw image file."]]
|-
|74||[[Help:VE74|"Image file '$(FILE)' is incorrectly used as both a texture.txt source file and a raw image file."]]
|-
|76||[[Help:VE76|"Unable to load mesh file: '$(FILE)'"]]
|-
|77||[[Help:VE77|"Unable to load indexed mesh '$(FILE)'"]]
|-
|79||[[Help:VE79|"Unable to load animation file '$(FILE)' (mesh has not been loaded correctly)."]]
|-
|81||[[Help:VE81|"The high-poly mesh '$(FILE)' should have LOD levels."]]
|-
|82||[[Help:VE82|"High-detail .im files are not supported for traincar assets, as they are likely to perform poorly. It is recommended that you upgrade '$(FILE)' to a .lm file."]]
|-
|83||[[Help:VE83|"The file '$(FILE)' is provided in LM format despite having no attachment points and no animation support. This may have a negative impact on performance."]]
|-
|84||[[Help:VE84|"The file '$(FILE)' is provided in LM format despite containing only a single mesh. This may have a negative impact on performance."]]
|-
|85||[[Help:VE85|"The file '$(FILE)' is provided in LM format, however the high-detail mesh is comprised of less than 300 polygons. This may have a negative impact on performance."]]
|-
|86||[[Help:VE86|"Legacy .pm files are no longer supported, and will perform poorly. It is recommended that you switch to using a .lm file."]]
|-
|87||[[Help:VE87|"Legacy .pm files are no longer supported, and will perform poorly. It is recommended that you switch to using a .lm file."]]
|-
|88||[[Help:VE88|"This asset has a trainz-build number which is not recognised by this tool."]]
|-
|89||[[Help:VE89|"Tag '$(TAG_NAME)' in the container '$(CONT_NAME)' is obsolete."]]
|-
|90||[[Help:VE90|"This asset has an invalid KUID user id"]]
|-
|91||[[Help:VE91|"The dependency $(KUID) has an invalid KUID User ID and cannot be used"]]
|-
|92||[[Help:VE92|"Duplicate '$(TAG_NAME)' containers in '$(CONT_NAME)'. Containers must have a unique name."]]
|-
|93||[[Help:VE93|"Duplicate '$(TAG_NAME)' tags in '$(CONT_NAME)'. Tags must have a unique name."]]
|-
|94||[[Help:VE94|"This asset requires a shadow mesh, but the mesh table does not contain one."]]
|-
|95||[[Help:VE95|"This asset does not have a mesh that is visible by default."]]
|-
|96||[[Help:VE96|"Maximum of 5 running number fonts supported."]]
|-
|97||[[Help:VE97|"The running number font directory '$(DIR)' could not be found."]]
|-
|98||[[Help:VE98|"The running number font file '$(DIR)/$(FILE)' could not be found."]]
|-
|99||[[Help:VE99|"The track-sound container '$(NAME)' has no bogey, track or track-parent tag."]]
|-
|100||[[Help:VE100|"Required tag '$(TAG_NAME)' was missing and has been set to default."]]
|-
|101||[[Help:VE101|"The file '$(FILE)' does not exist."]]
|-
|102||[[Help:VE102|"Failed to load sound file '$(FILE)', please ensure this is a valid wav file."]]
|-
|103||[[Help:VE103|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|104||[[Help:VE104|"Multiple template property bindings for rule property '$(PROP)' for rule '$(RULE)'."]]
|-
|105||[[Help:VE105|"The template property '$(NAME)' specified in the rule-template-bindings container of rule '$(RULE)' does not exist."]]
|-
|106||[[Help:VE106|"The high-detail meshes in season $(SEASON) total more than $(LIMIT) polygons. This may have a negative impact on performance: $(LOD_SUMMARY)"]]
|-
|107||[[Help:VE107|"The high-detail meshes total more than $(LIMIT) polygons. This may have a negative impact on performance: $(LOD_SUMMARY)"]]
|-
|108||[[Help:VE108|"The low-detail meshes in season $(SEASON) total more than 500 polygons. This may have a negative impact on performance: $(LOD_SUMMARY)"]]
|-
|109||[[Help:VE109|"The low-detail meshes total more than 500 polygons. This may have a negative impact on performance: $(LOD_SUMMARY)"]]
|-
|110||[[Help:VE110|"The meshes in LOD level $(LOD_LEVEL) in season $(SEASON) must total at least 20% fewer polygons than the next higher LOD in the same season: $(LOD_SUMMARY)"]]
|-
|111||[[Help:VE111|"The meshes in LOD level $(LOD_LEVEL) must total at least 20% fewer polygons than the next higher LOD: $(LOD_SUMMARY)"]]
|-
|112||[[Help:VE112|"Multiple track stretches between '$(FROM_VERTEX)' and '$(TO_VERTEX)' in container '$(CONT_NAME)'. Track stretches must be unique."]]
|-
|113||[[Help:VE113|"An image file ('$(FILE)') has been supplied where a texture file ('*.texture.txt') is required."]]
|-
|114||[[Help:VE114|"An image file ('$(FILE)') has been supplied where a texture file ('*.texture.txt') is required."]]
|-
|115||[[Help:VE115|"The texture file '$(FILE)' does not exist."]]
|-
|116||[[Help:VE116|"No texture file has been specified for this texture asset."]]
|-
|117||[[Help:VE117|"'$(TAG_0)' must be set to a '$(KIND)' for '$(TAG_1)' to be allowed."]]
|-
|118||[[Help:VE118|"Tag '$(TAG_0)' requires that '$(TAG_1)' be set to '$(KIND)'."]]
|-
|119||[[Help:VE119|"The tag '$(TAG_NAME)' is not valid for kind '$(KIND)'."]]
|-
|120||[[Help:VE120|"Tag '$(TAG_0)', requires the tag '$(TAG_1)' to be present."]]
|-
|121||[[Help:VE121|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|122||[[Help:VE122|"'$(TAG_NAME)' must have a positive value."]]
|-
|123||[[Help:VE123|"The script file '$(FILE)' does not exist."]]
|-
|124||[[Help:VE124|"The file '$(FILE)' does not exist."]]
|-
|125||[[Help:VE125|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|126||[[Help:VE126|"'$(TAG_NAME)' must not be zero."]]
|-
|127||[[Help:VE127|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|128||[[Help:VE128|"The value for '$(TAG_NAME)' must be between '$(MIN)' and '$(MAX)' but was specified as '$(VALUE)'."]]
|-
|129||[[Help:VE129|"Incorrect number of values for the tag '$(TAG_NAME)', expected $(NUM_0) values, found $(NUM_1)."]]
|-
|130||[[Help:VE130|"Too many values for the tag '$(TAG_NAME)', maximum is $(MAX) values, found $(FOUND)."]]]]
|-
|131||[[Help:VE131|"Value must be a mesh from the mesh-table (not a parent container)."]]
|-
|132||[[Help:VE132|"The attachment point '$(ATT)' must belong to the parent mesh of the effect (mesh=$(MESH))."]]
|-
|133||[[Help:VE133|"A light container must be present to link the signals."]]
|-
|134||[[Help:VE134|"'$(NUM)' must be a valid light number from the light container."]]
|-
|135||[[Help:VE135|"'$(TAG_0)' requires that the tag '$(TAG_1)' be present."]]
|-
|136||[[Help:VE136|"'$(TAG_0)' requires that the tag '$(TAG_1)' be present."]]
|-
|137||[[Help:VE137|"Empty or invalid running number specified at character index $(INDEX)"]]
|-
|138||[[Help:VE138|"Running number specified at character index $(INDEX) is too large, must be less than 9 characters."]]
|-
|139||[[Help:VE139|"Invalid running number range specified at character index $(INDEX), ($(FROM)-$(TO))."]]
|-
|140||[[Help:VE140|"Running number range '$(FROM)-$(TO)' specified at character index $(INDEX) overlaps already in use numbers, running numbers must be unique."]]
|-
|141||[[Help:VE141|"Running number '$(NUMBER)' specified at character index $(INDEX) is already in use."]]
|-
|142||[[Help:VE142|"Invalid character '$(CHAR)' specified in running number list, only numbers, ',' and '-' are supported."]]
|-
|143||[[Help:VE143|"Possible running number list is too large, the set must contain less than 20000 possibilities."]]
|-
|144||[[Help:VE144|"Category code 'ZX - Paintshed template' is obsolete."]]
|-
|145||[[Help:VE145|"Category code 'ZX - Paintshed template' is obsolete."]]
|-
|146||[[Help:VE146|"An asset must be specified for tag '$(TAG_NAME)'."]]
|-
|147||[[Help:VE147|"The tag(s) $(MISPLACED_TAGS) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|148||[[Help:VE148|"The tag(s) $(MISPLACED_TAGS) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|149||[[Help:VE149|"The mesh(es) $(MISPLACED_MESHES) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|150||[[Help:VE150|"The mesh(es) $(MISPLACED_MESHES) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|151||[[Help:VE150|"The mesh(es) $(MISPLACED_MESHES) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|152||[[Help:VE152|"The tags $(MISSING_TAGS) are not all defined. The default values will be used and the positions of the elements may not fit your track."]]
|-
|153||[[Help:VE153|"The mesh $(MESH) is present but the tag $(MISSING_TAG) is not defined."]]
|-
|154||[[Help:VE154|"The mesh $(MESH) is present but the tag $(MISSING_TAG) is not defined."]]
|-
|155||[[Help:VE155|"The mesh $(MESH) is present but the tags $(MISSING_TAGS) are not all defined."]]
|-
|156||[[Help:VE156|"The tag $(MISSING_TAG) is not defined. The default value will be used and the positions of the elements may not fit your track."]]
|-
|157||[[Help:VE157|"The mesh $(MESH) is present but the tag $(MISSING_TAG) is missing. The default value will be used and the positions of the elements may not fit your track."]]
|-
|158||[[Help:VE158|"Unable to open .lm.txt file: $(FILE)"]]
|-
|159||[[Help:VE159|"Unable to parse .lm.txt file: $(FILE)"]]
|-
|160||[[Help:VE160|"No 'mesh' keys found in .lm.txt file: $(FILE)"]]
|-
|161||[[Help:VE161|"$(LODCOUNT) LODs in .lm.txt file: $(FILE)"]]
|-
|162||[[Help:VE162|"One of the LOD reductions of '$(FILE)' introduces a new attachment point: $(ATT)"]]
|-
|163||[[Help:VE163|"Unable to parse .im file: $(FILE)"]]
|-
|164||[[Help:VE164|"Invalid position data in .im file: $(FILE)"]]
|-
|165||[[Help:VE165|"Texture '$(TEXTURE)' is missing or could not be loaded in mesh '$(FILE)', material '$(MATERIAL)'."]]
|-
|166||[[Help:VE166|"$(COMBINEDCOUNT) combined chunks (of $(SOURCECOUNT) source) in .im file: $(FILE)"]]
|-
|167||[[Help:VE167|"Source image texture file '$(TEXTUREFILE)' is too large for '$(ASSETFILE)' ($(WIDTH)x$(HEIGHT))"]]
|-
|168||[[Help:VE168|"File '$(TEXTUREFILE)' is not a valid compiled texture file for '$(ASSETFILE)'"]]
|-
|169||[[Help:VE169|"Compiled texture file '$(TEXTUREFILE)' is unsupported version for '$(ASSETFILE)'"]]
|-
|170||[[Help:VE170|"Failed to open compiled texture '$(TEXTUREFILE)' for '$(ASSETFILE)'"]]
|-
|171||[[Help:VE171|"Expected texture file type but found '$(TEXTUREFILE)' for '$(ASSETFILE)'"]]
|-
|172||[[Help:VE172|"Script class does not match asset kind ($(KIND))."]]
|-
|173||[[Help:VE173|"Material '$(MATERIAL)' in mesh '$(FILE)' is not of a recognised material type."]]
|-
|174||[[Help:VE174|"MeshObjectSpec::LinkSpecs> Mesh-table element #$(MESH_INDEX) parent mesh is invalid."]]
|-
|175||[[Help:VE175|"MeshObjectSpec::LinkSpecs> Mesh-table element #$(MESH_INDEX) is part of invalid hierarchy."]]
|-
|176||[[Help:VE176|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' must have a texture file extension."]]
|-
|177||[[Help:VE177|"The kuid '$(KUID)' is not in the database, and could not be found in any known location. Ensure that this is a valid asset."]]
|-
|178||[[Help:VE178|"The asset specified in '$(KUID)' is not installed locally but is available for download."]]
|-
|179||[[Help:VE179|"The kuid '$(KUID)' specified in '$(TAG_NAME)' is not of the correct type."]]
|-
|180||[[Help:VE180|"Integrity check failure on $(FILE). One or more route/session tiles may be missing."]]
|-
|181||[[Help:VE181|"The tag '$(TAG_NAME)' requires a minimum asset version of $(MIN_VERSION)"]]
|-
|182||[[Help:VE182|"Material '$(MATERIAL)' in mesh '$(FILE)' is missing a texture for a mandatory texture slot."]]
|-
|183||[[Help:VE183|"FBX file is in an unsupported older format."]]
|-
|184||[[Help:VE184|"KIND '$(KIND)' requires trainz-build $(TRAINZBUILD)."]]
|-
|185||[[Help:VE185|"Material '$(MATERIAL)' in mesh '$(FILE)' has heightmap texture. Provide a normal map instead."]]
|-
|186||[[Help:VE186|"Material '$(MATERIAL)' is shared between multiple chunks in this asset but the material parameters conflict."]]
|-
|187||[[Help:VE187|"The value '$(VALUE)' in not a valid KUID."]]
|-
|188||[[Help:VE188|"Custom render plugin failed to load mesh '$(FILE)'"]]
|-
|189||[[Help:VE189|"Collision data exceeds $(LIMIT)KB. Please specify a different generation method or a simplified mesh."]]
|-
|190||[[Help:VE190|"Tag '$(NAME)' is unable to be converted from $(TYPE1) to $(TYPE2)"]]
|-
|191||[[Help:VE191|"Tag '$(NAME)' does not contain a valid integer: $(VALUE)"]]
|-
|192||[[Help:VE192|"Tag '$(NAME)' does not contain a valid float list: $(VALUE)"]]
|-
|193||[[Help:VE193|"Tag '$(NAME)' does not contain a valid float"]]
|-
|194||[[Help:VE194|"Tag '$(NAME)' does not contain a valid kuid: $(VALUE)"]]
|-
|195||[[Help:VE195|"Unable to parse chunk $(CHUNK_INDEX) in mesh file: $(FILE)"]]
|-
|196||[[Help:VE196|"Failed to load bogey $(KUID)"]]
|-
|197||[[Help:VE197|"Syntax error in script '$(SCRIPT)' for asset $(ASSET)"]]
|-
|198||[[Help:VE198|"Session failed to load route asset: $(KUID)"]]
|-
|199||[[Help:VE199|"Asset $(KUID) failed to load. Unloading resources."]]
|-
|200||[[Help:VE200|"Unable to load mesh $(NAME) for $(ASSET_ID)"]]
|-
|201||[[Help:VE201|"Traincar is missing required attachment point: $(ATT_NAME)"]]
|-
|202||[[Help:VE202|"Parse error reading twinkles file: $(FILE)"]]
|-
|203||[[Help:VE203|"Bad sequence order in $(TAG_NAME) list. Each element must be greater than the last."]]
|-
|204||[[Help:VE204|"Invalid range in $(TAG_NAME) list. Elements must be greater than or equal to $(INC_MIN) and less than $(EXC_MAX)."]]
|-
|205||[[Help:VE205|"Invalid element count in $(TAG_NAME) list. This list must have at least $(COUNT) elements (to match the $(TAG_START) list)."]]
|-
|206||[[Help:VE206|"The season-selector references season '$(SEASON)', but this does not exist in the texture-variants container."]]
|-
|207||[[Help:VE207|"Attached track asset $(CHILD) failed to load."]]
|-
|208||[[Help:VE208|"Attached track asset not specified for track $(INDEX)."]]
|-
|209||[[Help:VE209|"Asset is missing the required 'attached-track' container."]]
|-
|210||[[Help:VE210|"Asset is missing the required 'track' tag."]]
|-
|211||[[Help:VE211|"Asset is missing the required 'road' tag."]]
|-
|212||[[Help:VE212|"Traincar asset must have at least two bogeys."]]
|-
|213||[[Help:VE213|"Traincar asset has invalid bogey placement."]]
|-
|214||[[Help:VE214|"Traincar asset has invalid length."]]
|-
|215||[[Help:VE215|"Asset has an invalid number of LODs: $(LOD_COUNT)"]]
|-
|216||[[Help:VE216|"Material $(MATERIAL) in mesh file $(MESH) has an inappropriate texture slot assigned: $(TEXTURE)"]]
|-
|217||[[Help:VE217|"Material $(MATERIAL) in mesh file $(MESH) has no texture assigned to a required slot: $(TEXTURE)"]]
|-
|218||[[Help:VE218|"Asset has duplicate attached track at track $(INDEX)."]]
|-
|225||[[Help:VE225|"Failed to query asset details for featured asset."]]
|-
|226||[[Help:VE226|"Failed to upload asset details for featured asset: $(ERRORTEXT)"]]
|-
|227||[[Help:VE227|"Missing image for featured asset."]]
|-
|228||[[Help:VE228|"Failed to read image file for featured asset."]]
|-
|229||[[Help:VE229|"DLC marketing image is missing or incorrectly sized for featured asset."]]
|-
|230||[[Help:VE230|"DLS thumbnail image is missing or incorrectly sized for featured asset."]]
|-
|231||[[Help:VE231|"Failed to open image file for featured asset."]]
|-
|232||[[Help:VE232|"Failed to upload image for featured asset: $(ERRORTEXT)"]]
|-
|233||[[Help:VE233|"One or more featured assets was not provided."]]
|-
|234||[[Help:VE234|"Asset is not present in the featured assets list."]]
|-
|235||[[Help:VE235|"Featured asset is not present in the input."]]
|-
|236||[[Help:VE236|"Featured asset was not available."]]
|-
|237||[[Help:VE237|"Featured asset failed validation."]]
|-
|238||[[Help:VE238|"Featured asset has faulty or missing dependencies."]]
|-
|239||[[Help:VE239|"Featured asset is Base content."]]
|-
|240||[[Help:VE240|"Featured asset is missing an English name or description."]]
|-
|241||[[Help:VE241|"Newly built package is not compatible with previously released version."]]
|-
|242||[[Help:VE242|"Unable to load animation file '$(FILE)' (file not found, or is damaged)."]]
|-
|243||[[Help:VE243|"Failed to submit changes to asset $(ASSET_KUID) due to file access error"]]
|-
|244||[[Help:VE244|"Files in base assets cannot use importers: $(FILE)"]]
|-
|245||[[Help:VE245|"Missing compiled texture: $(FILE)"]]
|-
|246||[[Help:VE246|"Missing source texture: $(FILE)"]]
|-
|247||[[Help:VE247|"Creating default texture.txt file: $(FILE)"]]
|-
|248||[[Help:VE248|"Failed to create *.texture.txt file for source image: $(FILE)"]]
|-
|249||[[Help:VE249|"Failed to compile *.texture.txt file: $(FILE)"]]
|-
|250||[[Help:VE250|"Material Metadata expected data for texture slot '$(SLOT)' of material '$(MATERIAL)' but none found."]]
|-
|251||[[Help:VE251|"Material Metadata expected *.texture resource for texture slot '$(SLOT)' of material '$(MATERIAL)' bout found: $(FOUND)"]]
|-
|252||[[Help:VE252|"Mesh material expected data for texture slot '$(SLOT)' of material '$(MATERIAL)' but none found."]]
|-
|253||[[Help:VE253|"WriteAnimationFileBoneChunk> excessive bone-chunk count."]]
|-
|254||[[Help:VE254|"Unable to open mesh metadata file: $(FILE)"]]
|-
|255||[[Help:VE255|"Mesh contains unsupported non-triangle primitives."]]
|-
|256||[[Help:VE256|"Mesh contains invalid material index."]]
|-
|257||[[Help:VE257|"Mesh contains no primitives."]]
|-
|258||[[Help:VE258|"Unable to determine vertex format."]]
|-
|259||[[Help:VE259|"Unsupported number of texture channels."]]
|-
|260||[[Help:VE260|"Invalid index in primitive."]]
|-
|261||[[Help:VE261|"Unable to create animation file: $(FILE)"]]
|-
|262||[[Help:VE262|"Unable to open animation event file: $(FILE)"]]
|-
|263||[[Help:VE263|"Unable to parse animation event file: $(FILE)"]]
|-
|264||[[Help:VE264|"Parsed animation event file $(FILE) with $(COUNT) events."]]
|}

Category:Validation Errors

2020-06-11T03:56:05Z

Windwalkr:

Validation Error (VE) numbers are logged during content validation, to allow users to look up particular validation messages to better understand the source of the problem. Normal logs provide a substantial amount of technical detail about the error, but typically assume that the reader is familiar with the subject matter and will understand why the log is relevant. This wiki provides the necessary background information to understanding many of the logs, however a user who is unfamiliar with the area in question may not know where to start looking. VE numbers allow users to quickly find relevant pages in the wiki without any prior knowledge of the subject.

This page serves as a master guide to all VE numbers currently logged by Trainz. This page does not provide detailed information on any given VE number- please refer to the individual VE number pages for specific details. The error text here is correct for the English localisation of Trainz at the time of writing, however the exact text may change from time to time. It is intended that the overall meaning of a VE number will never change- new VE numbers will be issued instead, and old VE numbers may be made obsolete.

Logs which lack VE numbers do not belong on this page.

The individual VE pages can be found at the links below, or can be accessed directly from [[Content Manager]] by right-clicking on the Validation Error in the results log, and selecting "View Help for This Message".

{|
|-
|1||[[Help:VE1|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Decimal value."]]
|-
|2||[[Help:VE2|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Integer value."]]
|-
|3||[[Help:VE3|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|4||[[Help:VE4|"'$(TAG_NAME)' must have a positive value."]]
|-
|5||[[Help:VE5|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|6||[[Help:VE6|"'$(TAG_NAME)' must not be zero."]]
|-
|7||[[Help:VE7|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|8||[[Help:VE8|"The value for '$(TAG_NAME)' must be between '$(MIN)' and '$(MAX)' but was specified as '$(VALUE)'."]]
|-
|9||[[Help:VE9|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|10||[[Help:VE10|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|11||[[Help:VE11|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|12||[[Help:VE12|"No string-table entry found with tag '$(VALUE)' for for string-token tag '$(TAG)'."]]
|-
|13||[[Help:VE13|"Missing or invalid selection for tag '$(TAG_NAME)' in '$(CONT_NAME)'."]]
|-
|14||[[Help:VE14|"Missing or invalid selection for tag '$(TAG_NAME)' in '$(CONT_NAME)'."]]
|-
|15||[[Help:VE15|"Attachment point '$(TAG_NAME)' in '$(CONT_NAME)' must be found in mesh '$(MESH_NAME)'."]]
|-
|16||[[Help:VE16|"Container '$(CONT_NAME)' does not have an 'att-parent' tag which is required to reference an attachment point."]]
|-
|17||[[Help:VE17|"Attachment point '$(TAG_NAME)' in '$(CONT_NAME)' must be found in mesh '$(MESH_NAME)'."]]
|-
|18||[[Help:VE18|"Attachment point '$(TAG_VAL)' referenced by tag '$(TAG_NAME)' in '$(CONT_NAME)' was not found."]]
|-
|19||[[Help:VE19|"Effect '$(EFFECT_NAME)' in '$(CONT_NAME)' was not found within the mesh table."]]
|-
|20||[[Help:VE20|"Mesh '$(MESH_NAME)' referenced in '$(CONT_NAME)' was not found within the mesh table."]]
|-
|21||[[Help:VE21|"Attachment point '$(TAG_VAL)' referenced by tag '$(TAG_NAME)' in '$(CONT_NAME)' was not found."]]
|-
|22||[[Help:VE22|"Missing or invalid selection for tag '$(TAG_NAME)' in '$(CONT_NAME)'."]]
|-
|23||[[Help:VE23|"Invalid tag name '$(TAG_NAME)' in container '$(CONT_NAME)'."]]
|-
|24||[[Help:VE24|"Invalid tag name '$(TAG_NAME)' in container '$(CONT_NAME)'."]]
|-
|25||[[Help:VE25|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|26||[[Help:VE26|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|27||[[Help:VE27|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' must have a mesh file extension."]]
|-
|28||[[Help:VE28|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' must have an image file extension."]]
|-
|29||[[Help:VE29|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' must have an animation file extension."]]
|-
|30||[[Help:VE30|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' refers to a nonexistent file: '$(FILENAME)'."]]
|-
|31||[[Help:VE31|"Invalid tag name '$(TAG_NAME)' in container '$(CONT_NAME)'."]]
|-
|32||[[Help:VE32|"Alias mesh requires valid parent asset."]]
|-
|33||[[Help:VE33|"Alias mesh '$(FILE)' not found in dependency $(KUID)."]]
|-
|34||[[Help:VE34|"Alias mesh '$(FILE)' not found in latest version ($(NEW_KUID)) of dependency $(OLD_KUID)."]]
|-
|35||[[Help:VE35|"Required alias mesh asset $(KUID) is missing and cannot be validated."]]
|-
|36||[[Help:VE36|"The texture '$(FILE)' failed to load."]]
|-
|37||[[Help:VE37|"The texture '$(FILE)' is not a power of 2, please resize it."]]
|-
|38||[[Help:VE38|"The texture '$(FILE)' is not square. Cubemap textures need to have the same width and height."]]
|-
|39||[[Help:VE39|"The texture '$(FILE)' is a uniform color."]]
|-
|40||[[Help:VE40|"Unable to load $(TYPE) texture '$(TEXTURE)' for texture file '$(FILE)'."]]
|-
|41||[[Help:VE41|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Integer value."]]
|-
|42||[[Help:VE42|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Decimal value."]]
|-
|43||[[Help:VE43|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Boolean value."]]
|-
|44||[[Help:VE44|"Tag '$(TAG_NAME)' in the container '$(CONT_NAME)' is obsolete."]]
|-
|45||[[Help:VE45|"The Tag '$(TAG_NAME)' is not permitted within a container of type '$(CONT_NAME)'."]]
|-
|46||[[Help:VE46|"Internal Error: The template does not specify that a smoke container is valid in the container being parsed."]]
|-
|47||[[Help:VE47|"Container '$(CONT_NAME)' is not permitted in this section."]]
|-
|48||[[Help:VE48|"This asset uses an obsolete trainz-build number. Trainz-build numbers below $(LOWEST_TRAINZBUILD) are no longer supported."]]
|-
|49||[[Help:VE49|"Required tag 'kind' is not present. Ensure this is a valid config file."]]
|-
|50||[[Help:VE50|"Unsupported kind '$(KIND)'."]]
|-
|51||[[Help:VE51|"Tag '$(TAG_NAME)' in the container '$(CONT_NAME)' is obsolete."]]
|-
|52||[[Help:VE52|"The Tag '$(TAG_NAME)' is not permitted within a container of type '$(CONT_NAME)'."]]
|-
|53||[[Help:VE53|"This container is no longer supported."]]
|-
|54||[[Help:VE54|"The Tag '$(TAG_NAME)' is not permitted within a container of type '$(CONT_NAME)'."]]
|-
|55||[[Help:VE55|"This container is no longer supported."]]
|-
|56||[[Help:VE56|"Container '$(CONT_NAME)' is not permitted in this section."]]
|-
|57||[[Help:VE57|"Container '$(CONT_NAME)' is not permitted in this section."]]
|-
|58||[[Help:VE58|"The tag '$(TAG_NAME)' is not a valid container type (expected '$(TYPE)')."]]
|-
|59||[[Help:VE59|"Internal error: unknown dataType - kind '$(KIND)'."]]
|-
|60||[[Help:VE60|"Required tag '$(TAG_NAME)' was missing and has been set to default."]]
|-
|61||[[Help:VE61|"Required tag '$(TAG_NAME)' was missing and has been set to default."]]
|-
|62||[[Help:VE62|"Required container '$(CONT_NAME)' is missing."]]
|-
|63||[[Help:VE63|"The cubemap texture '$(FILE)' has missing images. Please verify the texture.txt file."]]
|-
|64||[[Help:VE64|"Cubemap texture '$(FILE)' contains images of different sizes."]]
|-
|65||[[Help:VE65|"The *.texture.txt file is missing for texture resource '$(FILE)'."]]
|-
|66||[[Help:VE66|"The texture file '$(FILE)' contains non-ANSI characters. Textures must be ANSI."]]
|-
|67||[[Help:VE67|"The texture '$(FILE)' does not seem to have a primary texture set. Please verify the texture.txt file."]]
|-
|68||[[Help:VE68|"The primary and alpha texture are not the same size for '$(FILE)'."]]
|-
|69||[[Help:VE69|"Binary conversion failed for texture resource '$(FILE)'."]]
|-
|70||[[Help:VE70|"The KUID tag is not a valid KUID value: '$(string)'."]]
|-
|71||[[Help:VE71|"Unsupported SpeedTree version for mesh: $(FILE)"]]
|-
|72||[[Help:VE72|"Unable to load mesh file: '$(FILE)'"]]
|-
|73||[[Help:VE73|"Image file '$(FILE)' is incorrectly used as both a texture.txt source file and a raw image file."]]
|-
|74||[[Help:VE74|"Image file '$(FILE)' is incorrectly used as both a texture.txt source file and a raw image file."]]
|-
|76||[[Help:VE76|"Unable to load mesh file: '$(FILE)'"]]
|-
|77||[[Help:VE77|"Unable to load indexed mesh '$(FILE)'"]]
|-
|79||[[Help:VE79|"Unable to load animation file '$(FILE)' (mesh has not been loaded correctly)."]]
|-
|81||[[Help:VE81|"The high-poly mesh '$(FILE)' should have LOD levels."]]
|-
|82||[[Help:VE82|"High-detail .im files are not supported for traincar assets, as they are likely to perform poorly. It is recommended that you upgrade '$(FILE)' to a .lm file."]]
|-
|83||[[Help:VE83|"The file '$(FILE)' is provided in LM format despite having no attachment points and no animation support. This may have a negative impact on performance."]]
|-
|84||[[Help:VE84|"The file '$(FILE)' is provided in LM format despite containing only a single mesh. This may have a negative impact on performance."]]
|-
|85||[[Help:VE85|"The file '$(FILE)' is provided in LM format, however the high-detail mesh is comprised of less than 300 polygons. This may have a negative impact on performance."]]
|-
|86||[[Help:VE86|"Legacy .pm files are no longer supported, and will perform poorly. It is recommended that you switch to using a .lm file."]]
|-
|87||[[Help:VE87|"Legacy .pm files are no longer supported, and will perform poorly. It is recommended that you switch to using a .lm file."]]
|-
|88||[[Help:VE88|"This asset has a trainz-build number which is not recognised by this tool."]]
|-
|89||[[Help:VE89|"Tag '$(TAG_NAME)' in the container '$(CONT_NAME)' is obsolete."]]
|-
|90||[[Help:VE90|"This asset has an invalid KUID user id"]]
|-
|91||[[Help:VE91|"The dependency $(KUID) has an invalid KUID User ID and cannot be used"]]
|-
|92||[[Help:VE92|"Duplicate '$(TAG_NAME)' containers in '$(CONT_NAME)'. Containers must have a unique name."]]
|-
|93||[[Help:VE93|"Duplicate '$(TAG_NAME)' tags in '$(CONT_NAME)'. Tags must have a unique name."]]
|-
|94||[[Help:VE94|"This asset requires a shadow mesh, but the mesh table does not contain one."]]
|-
|95||[[Help:VE95|"This asset does not have a mesh that is visible by default."]]
|-
|96||[[Help:VE96|"Maximum of 5 running number fonts supported."]]
|-
|97||[[Help:VE97|"The running number font directory '$(DIR)' could not be found."]]
|-
|98||[[Help:VE98|"The running number font file '$(DIR)/$(FILE)' could not be found."]]
|-
|99||[[Help:VE99|"The track-sound container '$(NAME)' has no bogey, track or track-parent tag."]]
|-
|100||[[Help:VE100|"Required tag '$(TAG_NAME)' was missing and has been set to default."]]
|-
|101||[[Help:VE101|"The file '$(FILE)' does not exist."]]
|-
|102||[[Help:VE102|"Failed to load sound file '$(FILE)', please ensure this is a valid wav file."]]
|-
|103||[[Help:VE103|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|104||[[Help:VE104|"Multiple template property bindings for rule property '$(PROP)' for rule '$(RULE)'."]]
|-
|105||[[Help:VE105|"The template property '$(NAME)' specified in the rule-template-bindings container of rule '$(RULE)' does not exist."]]
|-
|106||[[Help:VE106|"The high-detail meshes in season $(SEASON) total more than $(LIMIT) polygons. This may have a negative impact on performance: $(LOD_SUMMARY)"]]
|-
|107||[[Help:VE107|"The high-detail meshes total more than $(LIMIT) polygons. This may have a negative impact on performance: $(LOD_SUMMARY)"]]
|-
|108||[[Help:VE108|"The low-detail meshes in season $(SEASON) total more than 500 polygons. This may have a negative impact on performance: $(LOD_SUMMARY)"]]
|-
|109||[[Help:VE109|"The low-detail meshes total more than 500 polygons. This may have a negative impact on performance: $(LOD_SUMMARY)"]]
|-
|110||[[Help:VE110|"The meshes in LOD level $(LOD_LEVEL) in season $(SEASON) must total at least 20% fewer polygons than the next higher LOD in the same season: $(LOD_SUMMARY)"]]
|-
|111||[[Help:VE111|"The meshes in LOD level $(LOD_LEVEL) must total at least 20% fewer polygons than the next higher LOD: $(LOD_SUMMARY)"]]
|-
|112||[[Help:VE112|"Multiple track stretches between '$(FROM_VERTEX)' and '$(TO_VERTEX)' in container '$(CONT_NAME)'. Track stretches must be unique."]]
|-
|113||[[Help:VE113|"An image file ('$(FILE)') has been supplied where a texture file ('*.texture.txt') is required."]]
|-
|114||[[Help:VE114|"An image file ('$(FILE)') has been supplied where a texture file ('*.texture.txt') is required."]]
|-
|115||[[Help:VE115|"The texture file '$(FILE)' does not exist."]]
|-
|116||[[Help:VE116|"No texture file has been specified for this texture asset."]]
|-
|117||[[Help:VE117|"'$(TAG_0)' must be set to a '$(KIND)' for '$(TAG_1)' to be allowed."]]
|-
|118||[[Help:VE118|"Tag '$(TAG_0)' requires that '$(TAG_1)' be set to '$(KIND)'."]]
|-
|119||[[Help:VE119|"The tag '$(TAG_NAME)' is not valid for kind '$(KIND)'."]]
|-
|120||[[Help:VE120|"Tag '$(TAG_0)', requires the tag '$(TAG_1)' to be present."]]
|-
|121||[[Help:VE121|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|122||[[Help:VE122|"'$(TAG_NAME)' must have a positive value."]]
|-
|123||[[Help:VE123|"The script file '$(FILE)' does not exist."]]
|-
|124||[[Help:VE124|"The file '$(FILE)' does not exist."]]
|-
|125||[[Help:VE125|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|126||[[Help:VE126|"'$(TAG_NAME)' must not be zero."]]
|-
|127||[[Help:VE127|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|128||[[Help:VE128|"The value for '$(TAG_NAME)' must be between '$(MIN)' and '$(MAX)' but was specified as '$(VALUE)'."]]
|-
|129||[[Help:VE129|"Incorrect number of values for the tag '$(TAG_NAME)', expected $(NUM_0) values, found $(NUM_1)."]]
|-
|130||[[Help:VE130|"Too many values for the tag '$(TAG_NAME)', maximum is $(MAX) values, found $(FOUND)."]]]]
|-
|131||[[Help:VE131|"Value must be a mesh from the mesh-table (not a parent container)."]]
|-
|132||[[Help:VE132|"The attachment point '$(ATT)' must belong to the parent mesh of the effect (mesh=$(MESH))."]]
|-
|133||[[Help:VE133|"A light container must be present to link the signals."]]
|-
|134||[[Help:VE134|"'$(NUM)' must be a valid light number from the light container."]]
|-
|135||[[Help:VE135|"'$(TAG_0)' requires that the tag '$(TAG_1)' be present."]]
|-
|136||[[Help:VE136|"'$(TAG_0)' requires that the tag '$(TAG_1)' be present."]]
|-
|137||[[Help:VE137|"Empty or invalid running number specified at character index $(INDEX)"]]
|-
|138||[[Help:VE138|"Running number specified at character index $(INDEX) is too large, must be less than 9 characters."]]
|-
|139||[[Help:VE139|"Invalid running number range specified at character index $(INDEX), ($(FROM)-$(TO))."]]
|-
|140||[[Help:VE140|"Running number range '$(FROM)-$(TO)' specified at character index $(INDEX) overlaps already in use numbers, running numbers must be unique."]]
|-
|141||[[Help:VE141|"Running number '$(NUMBER)' specified at character index $(INDEX) is already in use."]]
|-
|142||[[Help:VE142|"Invalid character '$(CHAR)' specified in running number list, only numbers, ',' and '-' are supported."]]
|-
|143||[[Help:VE143|"Possible running number list is too large, the set must contain less than 20000 possibilities."]]
|-
|144||[[Help:VE144|"Category code 'ZX - Paintshed template' is obsolete."]]
|-
|145||[[Help:VE145|"Category code 'ZX - Paintshed template' is obsolete."]]
|-
|146||[[Help:VE146|"An asset must be specified for tag '$(TAG_NAME)'."]]
|-
|147||[[Help:VE147|"The tag(s) $(MISPLACED_TAGS) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|148||[[Help:VE148|"The tag(s) $(MISPLACED_TAGS) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|149||[[Help:VE149|"The mesh(es) $(MISPLACED_MESHES) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|150||[[Help:VE150|"The mesh(es) $(MISPLACED_MESHES) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|151||[[Help:VE150|"The mesh(es) $(MISPLACED_MESHES) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|152||[[Help:VE152|"The tags $(MISSING_TAGS) are not all defined. The default values will be used and the positions of the elements may not fit your track."]]
|-
|153||[[Help:VE153|"The mesh $(MESH) is present but the tag $(MISSING_TAG) is not defined."]]
|-
|154||[[Help:VE154|"The mesh $(MESH) is present but the tag $(MISSING_TAG) is not defined."]]
|-
|155||[[Help:VE155|"The mesh $(MESH) is present but the tags $(MISSING_TAGS) are not all defined."]]
|-
|156||[[Help:VE156|"The tag $(MISSING_TAG) is not defined. The default value will be used and the positions of the elements may not fit your track."]]
|-
|157||[[Help:VE157|"The mesh $(MESH) is present but the tag $(MISSING_TAG) is missing. The default value will be used and the positions of the elements may not fit your track."]]
|-
|158||[[Help:VE158|"Unable to open .lm.txt file: $(FILE)"]]
|-
|159||[[Help:VE159|"Unable to parse .lm.txt file: $(FILE)"]]
|-
|160||[[Help:VE160|"No 'mesh' keys found in .lm.txt file: $(FILE)"]]
|-
|161||[[Help:VE161|"$(LODCOUNT) LODs in .lm.txt file: $(FILE)"]]
|-
|162||[[Help:VE162|"One of the LOD reductions of '$(FILE)' introduces a new attachment point: $(ATT)"]]
|-
|163||[[Help:VE163|"Unable to parse .im file: $(FILE)"]]
|-
|164||[[Help:VE164|"Invalid position data in .im file: $(FILE)"]]
|-
|165||[[Help:VE165|"Texture '$(TEXTURE)' is missing or could not be loaded in mesh '$(FILE)', material '$(MATERIAL)'."]]
|-
|166||[[Help:VE166|"$(COMBINEDCOUNT) combined chunks (of $(SOURCECOUNT) source) in .im file: $(FILE)"]]
|-
|167||[[Help:VE167|"Source image texture file '$(TEXTUREFILE)' is too large for '$(ASSETFILE)' ($(WIDTH)x$(HEIGHT))"]]
|-
|168||[[Help:VE168|"File '$(TEXTUREFILE)' is not a valid compiled texture file for '$(ASSETFILE)'"]]
|-
|169||[[Help:VE169|"Compiled texture file '$(TEXTUREFILE)' is unsupported version for '$(ASSETFILE)'"]]
|-
|170||[[Help:VE170|"Failed to open compiled texture '$(TEXTUREFILE)' for '$(ASSETFILE)'"]]
|-
|171||[[Help:VE171|"Expected texture file type but found '$(TEXTUREFILE)' for '$(ASSETFILE)'"]]
|-
|172||[[Help:VE172|"Script class does not match asset kind ($(KIND))."]]
|-
|173||[[Help:VE173|"Material '$(MATERIAL)' in mesh '$(FILE)' is not of a recognised material type."]]
|-
|174||[[Help:VE174|"MeshObjectSpec::LinkSpecs> Mesh-table element #$(MESH_INDEX) parent mesh is invalid."]]
|-
|175||[[Help:VE175|"MeshObjectSpec::LinkSpecs> Mesh-table element #$(MESH_INDEX) is part of invalid hierarchy."]]
|-
|176||[[Help:VE176|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' must have a texture file extension."]]
|-
|177||[[Help:VE177|"The kuid '$(KUID)' is not in the database, and could not be found in any known location. Ensure that this is a valid asset."]]
|-
|178||[[Help:VE178|"The asset specified in '$(KUID)' is not installed locally but is available for download."]]
|-
|179||[[Help:VE179|"The kuid '$(KUID)' specified in '$(TAG_NAME)' is not of the correct type."]]
|-
|180||[[Help:VE180|"Integrity check failure on $(FILE). One or more route/session tiles may be missing."]]
|-
|181||[[Help:VE181|"The tag '$(TAG_NAME)' requires a minimum asset version of $(MIN_VERSION)"]]
|-
|182||[[Help:VE182|"Material '$(MATERIAL)' in mesh '$(FILE)' is missing a texture for a mandatory texture slot."]]
|-
|183||[[Help:VE183|"FBX file is in an unsupported older format."]]
|-
|184||[[Help:VE184|"KIND '$(KIND)' requires trainz-build $(TRAINZBUILD)."]]
|-
|185||[[Help:VE185|"Material '$(MATERIAL)' in mesh '$(FILE)' has heightmap texture. Provide a normal map instead."]]
|-
|186||[[Help:VE186|"Material '$(MATERIAL)' is shared between multiple chunks in this asset but the material parameters conflict."]]
|-
|187||[[Help:VE187|"The value '$(VALUE)' in not a valid KUID."]]
|-
|188||[[Help:VE188|"Custom render plugin failed to load mesh '$(FILE)'"]]
|-
|189||[[Help:VE189|"Collision data exceeds $(LIMIT)KB. Please specify a different generation method or a simplified mesh."]]
|-
|190||[[Help:VE190|"Tag '$(NAME)' is unable to be converted from $(TYPE1) to $(TYPE2)"]]
|-
|191||[[Help:VE191|"Tag '$(NAME)' does not contain a valid integer: $(VALUE)"]]
|-
|192||[[Help:VE192|"Tag '$(NAME)' does not contain a valid float list: $(VALUE)"]]
|-
|193||[[Help:VE193|"Tag '$(NAME)' does not contain a valid float"]]
|-
|194||[[Help:VE194|"Tag '$(NAME)' does not contain a valid kuid: $(VALUE)"]]
|-
|195||[[Help:VE195|"Unable to parse chunk $(CHUNK_INDEX) in mesh file: $(FILE)"]]
|-
|196||[[Help:VE196|"Failed to load bogey $(KUID)"]]
|-
|197||[[Help:VE197|"Syntax error in script '$(SCRIPT)' for asset $(ASSET)"]]
|-
|198||[[Help:VE198|"Session failed to load route asset: $(KUID)"]]
|-
|199||[[Help:VE199|"Asset $(KUID) failed to load. Unloading resources."]]
|-
|200||[[Help:VE200|"Unable to load mesh $(NAME) for $(ASSET_ID)"]]
|-
|201||[[Help:VE201|"Traincar is missing required attachment point: $(ATT_NAME)"]]
|-
|202||[[Help:VE202|"Parse error reading twinkles file: $(FILE)"]]
|-
|203||[[Help:VE203|"Bad sequence order in $(TAG_NAME) list. Each element must be greater than the last."]]
|-
|204||[[Help:VE204|"Invalid range in $(TAG_NAME) list. Elements must be greater than or equal to $(INC_MIN) and less than $(EXC_MAX)."]]
|-
|205||[[Help:VE205|"Invalid element count in $(TAG_NAME) list. This list must have at least $(COUNT) elements (to match the $(TAG_START) list)."]]
|-
|206||[[Help:VE206|"The season-selector references season '$(SEASON)', but this does not exist in the texture-variants container."]]
|-
|207||[[Help:VE207|"Attached track asset $(CHILD) failed to load."]]
|-
|208||[[Help:VE208|"Attached track asset not specified for track $(INDEX)."]]
|-
|209||[[Help:VE209|"Asset is missing the required 'attached-track' container."]]
|-
|210||[[Help:VE210|"Asset is missing the required 'track' tag."]]
|-
|211||[[Help:VE211|"Asset is missing the required 'road' tag."]]
|-
|212||[[Help:VE212|"Traincar asset must have at least two bogeys."]]
|-
|213||[[Help:VE213|"Traincar asset has invalid bogey placement."]]
|-
|214||[[Help:VE214|"Traincar asset has invalid length."]]
|-
|215||[[Help:VE215|"Asset has an invalid number of LODs: $(LOD_COUNT)"]]
|-
|216||[[Help:VE216|"Material $(MATERIAL) in mesh file $(MESH) has an inappropriate texture slot assigned: $(TEXTURE)"]]
|-
|217||[[Help:VE217|"Material $(MATERIAL) in mesh file $(MESH) has no texture assigned to a required slot: $(TEXTURE)"]]
|-
|218||[[Help:VE218|"Asset has duplicate attached track at track $(INDEX)."]]
|-
|225||[[Help:VE225|"Failed to query asset details for featured asset."]]
|-
|226||[[Help:VE226|"Failed to upload asset details for featured asset: $(ERRORTEXT)"]]
|-
|227||[[Help:VE227|"Missing image for featured asset."]]
|-
|228||[[Help:VE228|"Failed to read image file for featured asset."]]
|-
|229||[[Help:VE229|"DLC marketing image is missing or incorrectly sized for featured asset."]]
|-
|230||[[Help:VE230|"DLS thumbnail image is missing or incorrectly sized for featured asset."]]
|-
|231||[[Help:VE231|"Failed to open image file for featured asset."]]
|-
|232||[[Help:VE232|"Failed to upload image for featured asset: $(ERRORTEXT)"]]
|-
|233||[[Help:VE233|"One or more featured assets was not provided."]]
|-
|234||[[Help:VE234|"Asset is not present in the featured assets list."]]
|-
|235||[[Help:VE235|"Featured asset is not present in the input."]]
|-
|236||[[Help:VE236|"Featured asset was not available."]]
|-
|237||[[Help:VE237|"Featured asset failed validation."]]
|-
|238||[[Help:VE238|"Featured asset has faulty or missing dependencies."]]
|-
|239||[[Help:VE239|"Featured asset is Base content."]]
|-
|240||[[Help:VE240|"Featured asset is missing an English name or description."]]
|-
|241||[[Help:VE241|"Newly built package is not compatible with previously released version."]]
|-
|242||[[Help:VE242|"Unable to load animation file '$(FILE)' (file not found, or is damaged)."]]
|}

Category:Validation Errors

2020-06-11T03:55:38Z

Windwalkr:

Validation Error (VE) numbers are logged during content validation, to allow users to look up particular validation messages to better understand the source of the problem. Normal logs provide a substantial amount of technical detail about the error, but typically assume that the reader is familiar with the subject matter and will understand why the log is relevant. This wiki provides the necessary background information to understanding many of the logs, however a user who is unfamiliar with the area in question may not know where to start looking. VE numbers allow users to quickly find relevant pages in the wiki without any prior knowledge of the subject.

This page serves as a master guide to all VE numbers currently logged by Trainz. This page does not provide detailed information on any given VE number- please refer to the individual VE number pages for specific details. The error text here is correct for the English localisation of Trainz at the time of writing, however the exact text may change from time to time. It is intended that the overall meaning of a VE number will never change- new VE numbers will be issued instead, and old VE numbers may be made obsolete.

Logs which lack VE numbers do not belong on this page.

The individual VE pages can be found at the links below, or can be accessed directly from [[Content Manager]] by right-clicking on the Validation Error in the results log, and selecting "View Help for This Message".

{|
|-
|1||[[Help:VE1|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Decimal value."]]
|-
|2||[[Help:VE2|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Integer value."]]
|-
|3||[[Help:VE3|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|4||[[Help:VE4|"'$(TAG_NAME)' must have a positive value."]]
|-
|5||[[Help:VE5|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|6||[[Help:VE6|"'$(TAG_NAME)' must not be zero."]]
|-
|7||[[Help:VE7|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|8||[[Help:VE8|"The value for '$(TAG_NAME)' must be between '$(MIN)' and '$(MAX)' but was specified as '$(VALUE)'."]]
|-
|9||[[Help:VE9|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|10||[[Help:VE10|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|11||[[Help:VE11|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|12||[[Help:VE12|"No string-table entry found with tag '$(VALUE)' for for string-token tag '$(TAG)'."]]
|-
|13||[[Help:VE13|"Missing or invalid selection for tag '$(TAG_NAME)' in '$(CONT_NAME)'."]]
|-
|14||[[Help:VE14|"Missing or invalid selection for tag '$(TAG_NAME)' in '$(CONT_NAME)'."]]
|-
|15||[[Help:VE15|"Attachment point '$(TAG_NAME)' in '$(CONT_NAME)' must be found in mesh '$(MESH_NAME)'."]]
|-
|16||[[Help:VE16|"Container '$(CONT_NAME)' does not have an 'att-parent' tag which is required to reference an attachment point."]]
|-
|17||[[Help:VE17|"Attachment point '$(TAG_NAME)' in '$(CONT_NAME)' must be found in mesh '$(MESH_NAME)'."]]
|-
|18||[[Help:VE18|"Attachment point '$(TAG_VAL)' referenced by tag '$(TAG_NAME)' in '$(CONT_NAME)' was not found."]]
|-
|19||[[Help:VE19|"Effect '$(EFFECT_NAME)' in '$(CONT_NAME)' was not found within the mesh table."]]
|-
|20||[[Help:VE20|"Mesh '$(MESH_NAME)' referenced in '$(CONT_NAME)' was not found within the mesh table."]]
|-
|21||[[Help:VE21|"Attachment point '$(TAG_VAL)' referenced by tag '$(TAG_NAME)' in '$(CONT_NAME)' was not found."]]
|-
|22||[[Help:VE22|"Missing or invalid selection for tag '$(TAG_NAME)' in '$(CONT_NAME)'."]]
|-
|23||[[Help:VE23|"Invalid tag name '$(TAG_NAME)' in container '$(CONT_NAME)'."]]
|-
|24||[[Help:VE24|"Invalid tag name '$(TAG_NAME)' in container '$(CONT_NAME)'."]]
|-
|25||[[Help:VE25|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|26||[[Help:VE26|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|27||[[Help:VE27|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' must have a mesh file extension."]]
|-
|28||[[Help:VE28|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' must have an image file extension."]]
|-
|29||[[Help:VE29|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' must have an animation file extension."]]
|-
|30||[[Help:VE30|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' refers to a nonexistent file: '$(FILENAME)'."]]
|-
|31||[[Help:VE31|"Invalid tag name '$(TAG_NAME)' in container '$(CONT_NAME)'."]]
|-
|32||[[Help:VE32|"Alias mesh requires valid parent asset."]]
|-
|33||[[Help:VE33|"Alias mesh '$(FILE)' not found in dependency $(KUID)."]]
|-
|34||[[Help:VE34|"Alias mesh '$(FILE)' not found in latest version ($(NEW_KUID)) of dependency $(OLD_KUID)."]]
|-
|35||[[Help:VE35|"Required alias mesh asset $(KUID) is missing and cannot be validated."]]
|-
|36||[[Help:VE36|"The texture '$(FILE)' failed to load."]]
|-
|37||[[Help:VE37|"The texture '$(FILE)' is not a power of 2, please resize it."]]
|-
|38||[[Help:VE38|"The texture '$(FILE)' is not square. Cubemap textures need to have the same width and height."]]
|-
|39||[[Help:VE39|"The texture '$(FILE)' is a uniform color."]]
|-
|40||[[Help:VE40|"Unable to load $(TYPE) texture '$(TEXTURE)' for texture file '$(FILE)'."]]
|-
|41||[[Help:VE41|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Integer value."]]
|-
|42||[[Help:VE42|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Decimal value."]]
|-
|43||[[Help:VE43|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is not a valid Boolean value."]]
|-
|44||[[Help:VE44|"Tag '$(TAG_NAME)' in the container '$(CONT_NAME)' is obsolete."]]
|-
|45||[[Help:VE45|"The Tag '$(TAG_NAME)' is not permitted within a container of type '$(CONT_NAME)'."]]
|-
|46||[[Help:VE46|"Internal Error: The template does not specify that a smoke container is valid in the container being parsed."]]
|-
|47||[[Help:VE47|"Container '$(CONT_NAME)' is not permitted in this section."]]
|-
|48||[[Help:VE48|"This asset uses an obsolete trainz-build number. Trainz-build numbers below $(LOWEST_TRAINZBUILD) are no longer supported."]]
|-
|49||[[Help:VE49|"Required tag 'kind' is not present. Ensure this is a valid config file."]]
|-
|50||[[Help:VE50|"Unsupported kind '$(KIND)'."]]
|-
|51||[[Help:VE51|"Tag '$(TAG_NAME)' in the container '$(CONT_NAME)' is obsolete."]]
|-
|52||[[Help:VE52|"The Tag '$(TAG_NAME)' is not permitted within a container of type '$(CONT_NAME)'."]]
|-
|53||[[Help:VE53|"This container is no longer supported."]]
|-
|54||[[Help:VE54|"The Tag '$(TAG_NAME)' is not permitted within a container of type '$(CONT_NAME)'."]]
|-
|55||[[Help:VE55|"This container is no longer supported."]]
|-
|56||[[Help:VE56|"Container '$(CONT_NAME)' is not permitted in this section."]]
|-
|57||[[Help:VE57|"Container '$(CONT_NAME)' is not permitted in this section."]]
|-
|58||[[Help:VE58|"The tag '$(TAG_NAME)' is not a valid container type (expected '$(TYPE)')."]]
|-
|59||[[Help:VE59|"Internal error: unknown dataType - kind '$(KIND)'."]]
|-
|60||[[Help:VE60|"Required tag '$(TAG_NAME)' was missing and has been set to default."]]
|-
|61||[[Help:VE61|"Required tag '$(TAG_NAME)' was missing and has been set to default."]]
|-
|62||[[Help:VE62|"Required container '$(CONT_NAME)' is missing."]]
|-
|63||[[Help:VE63|"The cubemap texture '$(FILE)' has missing images. Please verify the texture.txt file."]]
|-
|64||[[Help:VE64|"Cubemap texture '$(FILE)' contains images of different sizes."]]
|-
|65||[[Help:VE65|"The *.texture.txt file is missing for texture resource '$(FILE)'."]]
|-
|66||[[Help:VE66|"The texture file '$(FILE)' contains non-ANSI characters. Textures must be ANSI."]]
|-
|67||[[Help:VE67|"The texture '$(FILE)' does not seem to have a primary texture set. Please verify the texture.txt file."]]
|-
|68||[[Help:VE68|"The primary and alpha texture are not the same size for '$(FILE)'."]]
|-
|69||[[Help:VE69|"Binary conversion failed for texture resource '$(FILE)'."]]
|-
|70||[[Help:VE70|"The KUID tag is not a valid KUID value: '$(string)'."]]
|-
|71||[[Help:VE71|"Unsupported SpeedTree version for mesh: $(FILE)"]]
|-
|72||[[Help:VE72|"Unable to load mesh file: '$(FILE)'"]]
|-
|73||[[Help:VE73|"Image file '$(FILE)' is incorrectly used as both a texture.txt source file and a raw image file."]]
|-
|74||[[Help:VE74|"Image file '$(FILE)' is incorrectly used as both a texture.txt source file and a raw image file."]]
|-
|76||[[Help:VE76|"Unable to load mesh file: '$(FILE)'"]]
|-
|77||[[Help:VE77|"Unable to load indexed mesh '$(FILE)'"]]
|-
|79||[[Help:VE79|"Unable to load animation file '$(FILE)' (mesh has not been loaded correctly)."]]
|-
|81||[[Help:VE81|"The high-poly mesh '$(FILE)' should have LOD levels."]]
|-
|82||[[Help:VE82|"High-detail .im files are not supported for traincar assets, as they are likely to perform poorly. It is recommended that you upgrade '$(FILE)' to a .lm file."]]
|-
|83||[[Help:VE83|"The file '$(FILE)' is provided in LM format despite having no attachment points and no animation support. This may have a negative impact on performance."]]
|-
|84||[[Help:VE84|"The file '$(FILE)' is provided in LM format despite containing only a single mesh. This may have a negative impact on performance."]]
|-
|85||[[Help:VE85|"The file '$(FILE)' is provided in LM format, however the high-detail mesh is comprised of less than 300 polygons. This may have a negative impact on performance."]]
|-
|86||[[Help:VE86|"Legacy .pm files are no longer supported, and will perform poorly. It is recommended that you switch to using a .lm file."]]
|-
|87||[[Help:VE87|"Legacy .pm files are no longer supported, and will perform poorly. It is recommended that you switch to using a .lm file."]]
|-
|88||[[Help:VE88|"This asset has a trainz-build number which is not recognised by this tool."]]
|-
|89||[[Help:VE89|"Tag '$(TAG_NAME)' in the container '$(CONT_NAME)' is obsolete."]]
|-
|90||[[Help:VE90|"This asset has an invalid KUID user id"]]
|-
|91||[[Help:VE91|"The dependency $(KUID) has an invalid KUID User ID and cannot be used"]]
|-
|92||[[Help:VE92|"Duplicate '$(TAG_NAME)' containers in '$(CONT_NAME)'. Containers must have a unique name."]]
|-
|93||[[Help:VE93|"Duplicate '$(TAG_NAME)' tags in '$(CONT_NAME)'. Tags must have a unique name."]]
|-
|94||[[Help:VE94|"This asset requires a shadow mesh, but the mesh table does not contain one."]]
|-
|95||[[Help:VE95|"This asset does not have a mesh that is visible by default."]]
|-
|96||[[Help:VE96|"Maximum of 5 running number fonts supported."]]
|-
|97||[[Help:VE97|"The running number font directory '$(DIR)' could not be found."]]
|-
|98||[[Help:VE98|"The running number font file '$(DIR)/$(FILE)' could not be found."]]
|-
|99||[[Help:VE99|"The track-sound container '$(NAME)' has no bogey, track or track-parent tag."]]
|-
|100||[[Help:VE100|"Required tag '$(TAG_NAME)' was missing and has been set to default."]]
|-
|101||[[Help:VE101|"The file '$(FILE)' does not exist."]]
|-
|102||[[Help:VE102|"Failed to load sound file '$(FILE)', please ensure this is a valid wav file."]]
|-
|103||[[Help:VE103|"The tag '$(TAG_NAME)' in container '$(CONT_NAME)' is empty."]]
|-
|104||[[Help:VE104|"Multiple template property bindings for rule property '$(PROP)' for rule '$(RULE)'."]]
|-
|105||[[Help:VE105|"The template property '$(NAME)' specified in the rule-template-bindings container of rule '$(RULE)' does not exist."]]
|-
|106||[[Help:VE106|"The high-detail meshes in season $(SEASON) total more than $(LIMIT) polygons. This may have a negative impact on performance: $(LOD_SUMMARY)"]]
|-
|107||[[Help:VE107|"The high-detail meshes total more than $(LIMIT) polygons. This may have a negative impact on performance: $(LOD_SUMMARY)"]]
|-
|108||[[Help:VE108|"The low-detail meshes in season $(SEASON) total more than 500 polygons. This may have a negative impact on performance: $(LOD_SUMMARY)"]]
|-
|109||[[Help:VE109|"The low-detail meshes total more than 500 polygons. This may have a negative impact on performance: $(LOD_SUMMARY)"]]
|-
|110||[[Help:VE110|"The meshes in LOD level $(LOD_LEVEL) in season $(SEASON) must total at least 20% fewer polygons than the next higher LOD in the same season: $(LOD_SUMMARY)"]]
|-
|111||[[Help:VE111|"The meshes in LOD level $(LOD_LEVEL) must total at least 20% fewer polygons than the next higher LOD: $(LOD_SUMMARY)"]]
|-
|112||[[Help:VE112|"Multiple track stretches between '$(FROM_VERTEX)' and '$(TO_VERTEX)' in container '$(CONT_NAME)'. Track stretches must be unique."]]
|-
|113||[[Help:VE113|"An image file ('$(FILE)') has been supplied where a texture file ('*.texture.txt') is required."]]
|-
|114||[[Help:VE114|"An image file ('$(FILE)') has been supplied where a texture file ('*.texture.txt') is required."]]
|-
|115||[[Help:VE115|"The texture file '$(FILE)' does not exist."]]
|-
|116||[[Help:VE116|"No texture file has been specified for this texture asset."]]
|-
|117||[[Help:VE117|"'$(TAG_0)' must be set to a '$(KIND)' for '$(TAG_1)' to be allowed."]]
|-
|118||[[Help:VE118|"Tag '$(TAG_0)' requires that '$(TAG_1)' be set to '$(KIND)'."]]
|-
|119||[[Help:VE119|"The tag '$(TAG_NAME)' is not valid for kind '$(KIND)'."]]
|-
|120||[[Help:VE120|"Tag '$(TAG_0)', requires the tag '$(TAG_1)' to be present."]]
|-
|121||[[Help:VE121|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|122||[[Help:VE122|"'$(TAG_NAME)' must have a positive value."]]
|-
|123||[[Help:VE123|"The script file '$(FILE)' does not exist."]]
|-
|124||[[Help:VE124|"The file '$(FILE)' does not exist."]]
|-
|125||[[Help:VE125|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|126||[[Help:VE126|"'$(TAG_NAME)' must not be zero."]]
|-
|127||[[Help:VE127|"No value has been entered for tag '$(TAG_NAME).'"]]
|-
|128||[[Help:VE128|"The value for '$(TAG_NAME)' must be between '$(MIN)' and '$(MAX)' but was specified as '$(VALUE)'."]]
|-
|129||[[Help:VE129|"Incorrect number of values for the tag '$(TAG_NAME)', expected $(NUM_0) values, found $(NUM_1)."]]
|-
|130||[[Help:VE130|"Too many values for the tag '$(TAG_NAME)', maximum is $(MAX) values, found $(FOUND)."]]]]
|-
|131||[[Help:VE131|"Value must be a mesh from the mesh-table (not a parent container)."]]
|-
|132||[[Help:VE132|"The attachment point '$(ATT)' must belong to the parent mesh of the effect (mesh=$(MESH))."]]
|-
|133||[[Help:VE133|"A light container must be present to link the signals."]]
|-
|134||[[Help:VE134|"'$(NUM)' must be a valid light number from the light container."]]
|-
|135||[[Help:VE135|"'$(TAG_0)' requires that the tag '$(TAG_1)' be present."]]
|-
|136||[[Help:VE136|"'$(TAG_0)' requires that the tag '$(TAG_1)' be present."]]
|-
|137||[[Help:VE137|"Empty or invalid running number specified at character index $(INDEX)"]]
|-
|138||[[Help:VE138|"Running number specified at character index $(INDEX) is too large, must be less than 9 characters."]]
|-
|139||[[Help:VE139|"Invalid running number range specified at character index $(INDEX), ($(FROM)-$(TO))."]]
|-
|140||[[Help:VE140|"Running number range '$(FROM)-$(TO)' specified at character index $(INDEX) overlaps already in use numbers, running numbers must be unique."]]
|-
|141||[[Help:VE141|"Running number '$(NUMBER)' specified at character index $(INDEX) is already in use."]]
|-
|142||[[Help:VE142|"Invalid character '$(CHAR)' specified in running number list, only numbers, ',' and '-' are supported."]]
|-
|143||[[Help:VE143|"Possible running number list is too large, the set must contain less than 20000 possibilities."]]
|-
|144||[[Help:VE144|"Category code 'ZX - Paintshed template' is obsolete."]]
|-
|145||[[Help:VE145|"Category code 'ZX - Paintshed template' is obsolete."]]
|-
|146||[[Help:VE146|"An asset must be specified for tag '$(TAG_NAME)'."]]
|-
|147||[[Help:VE147|"The tag(s) $(MISPLACED_TAGS) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|148||[[Help:VE148|"The tag(s) $(MISPLACED_TAGS) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|149||[[Help:VE149|"The mesh(es) $(MISPLACED_MESHES) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|150||[[Help:VE150|"The mesh(es) $(MISPLACED_MESHES) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|151||[[Help:VE150|"The mesh(es) $(MISPLACED_MESHES) can only be used when track-type = $(CORRECT_TRACK_TYPE). They will be ignored in this asset."]]
|-
|152||[[Help:VE152|"The tags $(MISSING_TAGS) are not all defined. The default values will be used and the positions of the elements may not fit your track."]]
|-
|153||[[Help:VE153|"The mesh $(MESH) is present but the tag $(MISSING_TAG) is not defined."]]
|-
|154||[[Help:VE154|"The mesh $(MESH) is present but the tag $(MISSING_TAG) is not defined."]]
|-
|155||[[Help:VE155|"The mesh $(MESH) is present but the tags $(MISSING_TAGS) are not all defined."]]
|-
|156||[[Help:VE156|"The tag $(MISSING_TAG) is not defined. The default value will be used and the positions of the elements may not fit your track."]]
|-
|157||[[Help:VE157|"The mesh $(MESH) is present but the tag $(MISSING_TAG) is missing. The default value will be used and the positions of the elements may not fit your track."]]
|-
|158||[[Help:VE158|"Unable to open .lm.txt file: $(FILE)"]]
|-
|159||[[Help:VE159|"Unable to parse .lm.txt file: $(FILE)"]]
|-
|160||[[Help:VE160|"No 'mesh' keys found in .lm.txt file: $(FILE)"]]
|-
|161||[[Help:VE161|"$(LODCOUNT) LODs in .lm.txt file: $(FILE)"]]
|-
|162||[[Help:VE162|"One of the LOD reductions of '$(FILE)' introduces a new attachment point: $(ATT)"]]
|-
|163||[[Help:VE163|"Unable to parse .im file: $(FILE)"]]
|-
|164||[[Help:VE164|"Invalid position data in .im file: $(FILE)"]]
|-
|165||[[Help:VE165|"Texture '$(TEXTURE)' is missing or could not be loaded in mesh '$(FILE)', material '$(MATERIAL)'."]]
|-
|166||[[Help:VE166|"$(COMBINEDCOUNT) combined chunks (of $(SOURCECOUNT) source) in .im file: $(FILE)"]]
|-
|167||[[Help:VE167|"Source image texture file '$(TEXTUREFILE)' is too large for '$(ASSETFILE)' ($(WIDTH)x$(HEIGHT))"]]
|-
|168||[[Help:VE168|"File '$(TEXTUREFILE)' is not a valid compiled texture file for '$(ASSETFILE)'"]]
|-
|169||[[Help:VE169|"Compiled texture file '$(TEXTUREFILE)' is unsupported version for '$(ASSETFILE)'"]]
|-
|170||[[Help:VE170|"Failed to open compiled texture '$(TEXTUREFILE)' for '$(ASSETFILE)'"]]
|-
|171||[[Help:VE171|"Expected texture file type but found '$(TEXTUREFILE)' for '$(ASSETFILE)'"]]
|-
|172||[[Help:VE172|"Script class does not match asset kind ($(KIND))."]]
|-
|173||[[Help:VE173|"Material '$(MATERIAL)' in mesh '$(FILE)' is not of a recognised material type."]]
|-
|174||[[Help:VE174|"MeshObjectSpec::LinkSpecs> Mesh-table element #$(MESH_INDEX) parent mesh is invalid."]]
|-
|175||[[Help:VE175|"MeshObjectSpec::LinkSpecs> Mesh-table element #$(MESH_INDEX) is part of invalid hierarchy."]]
|-
|176||[[Help:VE176|"The tag '$(TAG_NAME)' in '$(CONT_NAME)' must have a texture file extension."]]
|-
|177||[[Help:VE177|"The kuid '$(KUID)' is not in the database, and could not be found in any known location. Ensure that this is a valid asset."]]
|-
|178||[[Help:VE178|"The asset specified in '$(KUID)' is not installed locally but is available for download."]]
|-
|179||[[Help:VE179|"The kuid '$(KUID)' specified in '$(TAG_NAME)' is not of the correct type."]]
|-
|180||[[Help:VE180|"Integrity check failure on $(FILE). One or more route/session tiles may be missing."]]
|-
|181||[[Help:VE181|"The tag '$(TAG_NAME)' requires a minimum asset version of $(MIN_VERSION)"]]
|-
|182||[[Help:VE182|"Material '$(MATERIAL)' in mesh '$(FILE)' is missing a texture for a mandatory texture slot."]]
|-
|183||[[Help:VE183|"FBX file is in an unsupported older format."]]
|-
|184||[[Help:VE184|"KIND '$(KIND)' requires trainz-build $(TRAINZBUILD)."]]
|-
|185||[[Help:VE185|"Material '$(MATERIAL)' in mesh '$(FILE)' has heightmap texture. Provide a normal map instead."]]
|-
|186||[[Help:VE186|"Material '$(MATERIAL)' is shared between multiple chunks in this asset but the material parameters conflict."]]
|-
|187||[[Help:VE187|"The value '$(VALUE)' in not a valid KUID."]]
|-
|188||[[Help:VE188|"Custom render plugin failed to load mesh '$(FILE)'"]]
|-
|189||[[Help:VE189|"Collision data exceeds $(LIMIT)KB. Please specify a different generation method or a simplified mesh."]]
|-
|190||[[Help:VE190|"Tag '$(NAME)' is unable to be converted from $(TYPE1) to $(TYPE2)"]]
|-
|191||[[Help:VE191|"Tag '$(NAME)' does not contain a valid integer: $(VALUE)"]]
|-
|192||[[Help:VE192|"Tag '$(NAME)' does not contain a valid float list: $(VALUE)"]]
|-
|193||[[Help:VE193|"Tag '$(NAME)' does not contain a valid float"]]
|-
|194||[[Help:VE194|"Tag '$(NAME)' does not contain a valid kuid: $(VALUE)"]]
|-
|195||[[Help:VE195|"Unable to parse chunk $(CHUNK_INDEX) in mesh file: $(FILE)"]]
|-
|196||[[Help:VE196|"Failed to load bogey $(KUID)"]]
|-
|197||[[Help:VE197|"Syntax error in script '$(SCRIPT)' for asset $(ASSET)"]]
|-
|198||[[Help:VE198|"Session failed to load route asset: $(KUID)"]]
|-
|199||[[Help:VE199|"Asset $(KUID) failed to load. Unloading resources."]]
|-
|200||[[Help:VE200|"Unable to load mesh $(NAME) for $(ASSET_ID)"]]
|-
|201||[[Help:VE201|"Traincar is missing required attachment point: $(ATT_NAME)"]]
|-
|202||[[Help:VE202|"Parse error reading twinkles file: $(FILE)"]]
|-
|203||[[Help:VE203|"Bad sequence order in $(TAG_NAME) list. Each element must be greater than the last."]]
|-
|204||[[Help:VE204|"Invalid range in $(TAG_NAME) list. Elements must be greater than or equal to $(INC_MIN) and less than $(EXC_MAX)."]]
|-
|205||[[Help:VE205|"Invalid element count in $(TAG_NAME) list. This list must have at least $(COUNT) elements (to match the $(TAG_START) list)."]]
|-
|206||[[Help:VE206|"The season-selector references season '$(SEASON)', but this does not exist in the texture-variants container."]]
|-
|207||[[Help:VE207|"Attached track asset $(CHILD) failed to load."]]
|-
|208||[[Help:VE208|"Attached track asset not specified for track $(INDEX)."]]
|-
|209||[[Help:VE209|"Asset is missing the required 'attached-track' container."]]
|-
|210||[[Help:VE210|"Asset is missing the required 'track' tag."]]
|-
|211||[[Help:VE211|"Asset is missing the required 'road' tag."]]
|-
|212||[[Help:VE212|"Traincar asset must have at least two bogeys."]]
|-
|213||[[Help:VE213|"Traincar asset has invalid bogey placement."]]
|-
|214||[[Help:VE214|"Traincar asset has invalid length."]]
|-
|215||[[Help:VE215|"Asset has an invalid number of LODs: $(LOD_COUNT)"]]
|-
|216||[[Help:VE216|"Material $(MATERIAL) in mesh file $(MESH) has an inappropriate texture slot assigned: $(TEXTURE)"]]
|-
|217||[[Help:VE217|"Material $(MATERIAL) in mesh file $(MESH) has no texture assigned to a required slot: $(TEXTURE)"]]
|-
|218||[[Help:VE218|"Asset has duplicate attached track at track $(INDEX)."]]
|-
|225||[[Help:VE225|"Failed to query asset details for featured asset."]]
|-
|226||[[Help:VE226|"Failed to upload asset details for featured asset: $(ERRORTEXT)"]]
|-
|227||[[Help:VE227|"Missing image for featured asset."]]
|-
|228||[[Help:VE228|"Failed to read image file for featured asset."]]
|-
|229||[[Help:VE229|"DLC marketing image is missing or incorrectly sized for featured asset."]]
|-
|230||[[Help:VE230|"DLS thumbnail image is missing or incorrectly sized for featured asset."]]
|-
|231||[[Help:VE231|"Failed to open image file for featured asset."]]
|-
|232||[[Help:VE232|"Failed to upload image for featured asset: $(ERRORTEXT)"]]
|-
|233||[[Help:VE233|"One or more featured assets was not provided."]]
|-
|234||[[Help:VE234|"Asset is not present in the featured assets list."]]
|-
|235||[[Help:VE235|"Featured asset is not present in the input."]]
|-
|236||[[Help:VE236|"Featured asset was not available."]]
|-
|237||[[Help:VE237|"Featured asset failed validation."]]
|-
|238||[[Help:VE238|"Featured asset has faulty or missing dependencies."]]
|-
|239||[[Help:VE239|"Featured asset is Base content."]]
|-
|240||[[Help:VE240|"Featured asset is missing an English name or description."]]
|-
|241||[[Help:VE241|"Newly built package is not compatible with previously released version."]]
|-
|241||[[Help:VE241|"Unable to load animation file '$(FILE)' (file not found, or is damaged)."]]
|}

Texture file

2019-11-04T03:58:10Z

Windwalkr:

{{ORP-top}}
Trainz '''Texture files''' are ASCII text format specification files describing a single texture. Texture files have a ".texture.txt" name extension, however when a texture file is specified within a [[config.txt file]] or similar, the ".txt" must be omitted (as you are specifying a resource name, not a file path), leaving only the ".texture" extension.

Texture files (*.texture.txt) should be distinguished from [[image file]]s (*.tga, etc.) and [[material]]s. A material may utilize zero or more texture files, and a texture file may utilize one or more image files. While we often refer to the image data as "a texture", this usage isn't strictly correct as any given texture also has a number of metadata attributes which are not present in the source image. Additionally, a texture may be compressed (at installation time) which may actually lose some of the data originally present in the source image.

When importing a [[trainzmesh file]] from an [[FBX file]], any image files referenced in the FBX which do not already have corresponding texture files will have generic texture files created automatically. These files may be suitable for basic purposes, but may need to be customized for more advanced functionality. Once the file has been created (and optionally customised) the importer will not recreate/overwrite it on subsequent runs.

This page describes [["Trainz-build" number|content format v4.6]].

=File format=

The user-editable *.texture.txt files are ASCII text formatted key-value pairs with the following options. Please note that this format is not the same (despite some similarities) as other text-based formats used by Trainz. Please be aware of the [[filename character restrictions]] when naming texture and image files.

;Syntax
Each key is specified on a new line. There is no white space anywhere in the line. A empty value is sometimes valid. The syntax is:

<key>=<value>

;Example:
Primary=WayCoolTexture.tga
Alpha=WayCoolTexture.tga
Tile=st
AlphaHint=masked
''(Example only, not recommended settings)''

==Keys and Values==

Primary=diffusemap.bmp

This tag specifies the filename of the image file representing the color (R, G, B) channels of the texture. Any alpha channel in the image file is ignored. The resultant texture will have a pure white (100%) alpha channel.

Primary=diffusemap.jpg
Alpha=diffusemap.bmp

This tag combination specifies the filenames of the image file representing the color (R, G, B) channels of the texture (Primary) and the image file representing the transparency of the texture (Alpha). The Alpha image should be grayscale. Neither file should contain an alpha (A) channel (ie, both images should be 24-bit). The two image files must be of identical size.

Primary=diffusemap.tga
Alpha=diffusemap.tga

This tag combination specifies the filename of a single image file representing the color and transparency (R, G, B, A) channels of the texture. In this case both tags must reference the same filename. The image file must contain an alpha channel.

Compression=dxt3

This tag hints the usage of a particular texture compression scheme. If you don't have a specific effect in mind, don't include this tag. Valid options are currently 'none', 'dxt1', 'dxt3', 'dxt5'. Refer [[DXT Compression]].

The current selection logic for texture compression is as follows, however it should be noted that this may change between Trainz versions. The first matching rule is used.

* Special texture formats (such as HDR) which don't support compression are stored uncompressed.
* "Compression=none" forces no compression. This gives the best visual result for a given input image, but typically yields worse visual results per output texture filesize. It is often better to activate compression and double the image dimensions, rather than disabling compression.
* Images with an "opaque" alpha hint use DXT1 compression.
* "Compression=dxt3" will use DXT3 compression.
* DXT5 compression is used.

NormalMapHint=normalmap

The 'NormalMapHint' tag allows the texture to be specified as a [[normal map]]. By default, Trainz will assume that your texture is a [[diffuse map]] and will apply some processing options which are not appropriate for normal maps. You must specify this option for normal maps. Valid options are 'none' and 'normalmap'.

ModifyMap=flipgreen

The 'ModifyMap' option allows a texture's green color channel to be flipped. Some programs such as [[Autodesk 3ds Max]] create [[normal map]]s with the Y axis facing the opposite way to what is expected by the Trainz shaders. This option can be used to make the bump effect look correct in Trainz. Valid options are 'none' and 'flipgreen'.

AlphaHint=opaque

The 'AlphaHint' tag allows you to force a particular alpha mode on the texture. Valid options are 'opaque' (meaning that the alpha channel is overwritten with pure white), 'semitransparent' (meaning that the alpha channel is a grayscale blend) and 'masked' (meaning that the alpha channel is clamped to a pure black&white bitmap based on a 50% threshold.) If omitted, Trainz will supply an appropriate value for this tag based on the actual contents of the Alpha channel.

Tile=st

Tiling refers to the ability for texture coordinates outside the range of (0.0 .. 1.0) to be treated as valid coordinates on an infinitely tiled texture. With tiling active, coordinates which pass the right/bottom side of the texture effectively wrap back onto the left/top side, and so on. Valid options include 's' (tile horizontally), 't' (tile vertically), 'st' (tile both horizontally and vertically), and 'none' (do not tile the image).

MipAlgorithm=no-weight-by-alpha

The default [[mipmap]] generation algorithm generally treats the alpha channel as an opacity and prioritizes opaque texels over transparent ones. This can lead to poor results in cases where the alpha channel is used for a different purpose (such as with PBR parameter textures). The "no-weight-by-alpha" hint can be used to ensure that the game will give equal weighting to texels regardless of their alpha channel.

The value of this key is only relevant where [[Content Manager]] is responsible for producing mipmap images. It is not relevant on any mipmap images provided in the source images.

nonpoweroftwo=1

By default, all textures must have both their width and height as a power of two (eg. 8, 16, 32, 64, 128, 256, 512, 1024, 2048), though they need not be square. Setting the value '1' for the 'nonpoweroftwo' key allows this restriction to be relaxed. This is currently considered experimental and may have unexpected performance, quality, or functionality outcomes. It is not recommended that end-users utilize this format at the current time.

Non-power-of-two (NPOT) textures may not support mipmapping and thus may be noticeably affected by the moire effect in addition to having higher overall GPU bandwidth requirements.

=Texture Formats=
The following texture formats are supported internally by Trainz on desktop platforms.
* R8 G8 B8 A8
* DXT1
* DXT3
* DXT5
* R32F G32F B32F A32F

The selection of internal format depends on the source image format and the value of the 'Compression' key.

=Texture Size=
Textures must be no more than 4096 pixels in either dimension, although it is strongly recommended that textures are kept below this maximum to avoid performance problems. Small objects should typically use approximately 512x512. Large, highly detailed objects such as train vehicles or ground textures will typically use 2048x2048.
Uniform-color textures (ie. textures in which all [[texel]]s have the same color) should be 8x8.
Textures must be a power-of-two size in each dimension (unless the 'nonpoweroftwo' key is activated), but need not be square. Some materials may give unexpected results for non-square textures; consult the material-specific documentation for details.

=Source Image Formats=
The following image formats are acceptable as source data for the texture file. Note that these formats are not used at runtime, and that format-specific benefits such as compression will apply to the DLS download size of the content but not to the runtime memory footprint or GPU bandwidth usage.

* Targa (.tga) files. Targa is a lossless image format with optional compression and optional alpha channel. This is a sensible choice where compatibility with older versions of Trainz is desired.
* JPEG (.jpg) files. JPEG is a lossy image compression format with no alpha channel support. This format should generally be avoided since it will typically lead to the image being compressed in a lossy format (JPG), decompressed, recompressed again into another lossy format (DXT1), losing detail at each stage. Worse, if JPEG files are used during the creation of the image, each edit-save-test cycle may result in a loss of image quality.
* Windows Bitmap (.bmp) files. BMP is a lossless image format with no compression and optional alpha channel. This format should generally be avoided since it does not offer compression and has no redeeming benefits.
* HDR (.hdr) files. HDR is a lossless image format with 32 bits of precision per channel. The R32F G32F B32F A32F internal texture format is used, and texture compression is not supported. This is a very expensive format (in terms of memory and performance) and should only be used where absolutely essential. Textures created in this format should be kept as small as possible (eg. 256-512 pixels wide and high).
* PNG (.png) files. PNG is a lossless compressed image format with alpha channel support. This is the best choice where compatibility with older versions of Trainz is not required.
* DDS (.dds) files. This has very limited support intended for specific internal purposes; it is not recommended that end-users utilize this format at the current time.

All images which comprise a given texture must have identical dimensions (width, height).

Source images should use the SRGB color space except where material-specific documentation indicates otherwise.

=Notes on Image Editors=
* The Targa Exporter plugin shipped with some older versions of Adobe Photoshop is broken and silently corrupts or discards alpha channels; a free update is available which resolves this issue.
* Some image editors do not support alpha channels on BMP files.

=*.txt File Extension=
Texture files have a ".texture.txt" name extension, however when a texture file is specified within a [[config.txt file]] or similar, the ".txt" must be omitted, leaving the ".texture" extension.
For example, a texture file named ''grass.texture.txt'' is specified in a [[KIND Groundtexture]] config file using the syntax ''texture "grass.texture"''.

=Use of Image Files in Place of Texture Files=
Trainz previously supported using ''any supported image file'' type in place of a [[Texture file]]. [[TANE]] does not support this technique; a texture.txt file must be used.

[[Category:File formats]]
[[Category:Modeling]]
[[Category:Content creation]]
{{ORP-bot}}

"Soundscript" container

2019-06-12T01:50:46Z

Windwalkr: /* distance */

{{ORP-top}}
A container type tag for defining asset sounds.

==Supported Tags==
Each soundscript subcontainer supports the following tags. Each tag is shown here with its default value.

repeat-delay 0,0
distance 50,150
ambient 0
attachment ""
nostartdelay 0
priority 1
trigger ""
volume 1
value-range 0,0
sound-asset
sound
{
}

====ambient====
:Type: Boolean
:Default: 0
:Compulsory: No
:Desc: If true this is an 'ambient' sound, ambient sounds are played in 2D and do not make use of 3D positioning in the world other than to affect volume. Unlike positional sounds, ambient sounds may be stereo.

====attachment====
:Type: Attachment point
:Default: ""
:Compulsory: No
:Desc: Point to attach the sound source to. Attachment points are specified in the mesh file during creation.

====distance====
:Type: Decimal Pair
:Default: 50,150
:Compulsory: No
:Desc: The minimum distance (first value, in meters) defines the radius within which the sound remains at 100% volume. Beyond that distance, the sound volume will begin to decay naturally. The maximum distance (second value, in meters) defines a radius beyond which the game need no longer play the sound. This does not mean that the sound will fade to zero by the maximum distance, but rather that the sound may cut off abruptly beyond that point. It is up to the content creator to choose an appropriate maximum distance - smaller is better for performance, but overly small values may result in the sound audibly cutting off. Many Trainz editions ignore the configured maximum distance value and instead perform their own optimized calculation of the appropriate value.

====nostartdelay====
:Type: Boolean
:Default: 0
:Compulsory: No
:Desc: If added and true this tag specifies that the sound will play immediately once triggered. By default sounds have a random start delay between 0 & 4 seconds. Start delay should be left active in most cases, as turning it off may cause significant audio artifacts when several identical sounds are in proximity.

====priority====
:Type: Integer
:Default: 1
:Compulsory: No
:Desc: Sets the priority of the sound, if their are not enough sound channels available higher priority sounds will be played first. Defaults to 1, can be negative.

====repeat-delay====
:Type: Decimal Pair
:Default: 0,0
:Compulsory: No
:Desc: Time range (in seconds) to delay, after the sound finishes playing, before playing the sound again. To set a constant delay either set both these values the same or only provide one of them, otherwise a random value between them will be chosen. When used with a trigger event (see the 'trigger' tag), a positive value indicates that the sound should not repeat, but should wait until triggered again.

====sound====
:Type: Container
:Default: {}
:Compulsory: Yes
:Desc: Contains list of the sound files to play. If the list has more than one entry then one file will be picked at random from the list. The value of each tag in this container is the filename of a WAV sound file. Filenames are relative to the base directory of the asset, i.e. relative to the location of the config file.

:Valid WAV files are:
:* Uncompressed.
:* 8 or 16 bit
:* Mono, Stereo or Surround

:Sampling rate can be 22kHz (22,050Hz) or 44kHz (44,100Hz). The higher sampling rate doubles the size of the file for no significant improvement in quality, and is not recommended. For some purposes there are additional requirements - for instance directional sounds must be mono.

====sound-asset====
:Type: KUID
:Compulsory: No
:Desc: The asset to source the sound files from. Allows the creation of "sound library" assets, so that sound files can be shared between multiple other assets. Defaults to the current asset.

====trigger====
:Type: String
:Default: ""
:Compulsory: No
:Desc: The 'trigger' tag gives your sound a name that can allow it to be played from [[Scripting|TrainzScript]] (see: Class MapObject), animations and certain predefined events. (At least one of these "predefined events" is to use the word "toggle" when including a soundscript container in the config.txt of a "MOjunction". This will make the sound fire each time the turnout is switched)

====value-range====
:Type: Float pair
:Default: 0,0 (off)
:Compulsory: No
:Desc: 2 numbers, where the numbers are not the same, which set the start and end times for the sound to play. Midnight is 0.5, midday = 0.0 or 1.0. (TBD. This is a bit vague.)

====volume====
:Type: Decimal
:Default: 1
:Compulsory: No
:Desc: Specifies the volume gain of the sound. Defaults to 1 (100%).

==Example Config.txt==
Sample [[config.txt file]] for a map asset that has a different day and night background sounds:

kind map
kuid <KUID:0:0>
soundscript
{
morning
{
ambient 1
value-range 1, 0.1
volume 0.3
sound
{
0 "ctry_day_1.wav"
1 "ctry_day_2.wav"
}
}
night
{
ambient 1
value-range 0, 0.9
volume 0.3
sound
{
0 "night_loop.wav"
}
}
}

==Categories==
[[Category:Config Container|Soundscript container]]
{{ORP-bot|Soundscript container}}

Trainz Life-Cycle Policy

2019-01-29T07:03:52Z

Windwalkr:

N3V Games typically maintain support for major product releases for at least four years from the initial release date. This is known as the "end-of-support" date for the product. Support includes the following areas:

* Product-specific information, downloads, and utilities on the N3V Games web site.
* Product assistance through the N3V Games Helpdesk.
* Maintenance of product-specific forums.
* Access to the [[Download Station]].
* Access to upload content to the [[Download Station]]
* Access to the iTrainz network.
* Access to other product-specific network services.

At the end-of-support date for a given product release (or at any time thereafter), some or all of the above services MAY be withdrawn at N3V Games's discretion. Users are encouraged to upgrade to a more recent version of Trainz to maintain support.

= Upgrades to Trainz Versions =
Prior to a new "Version" of Trainz being released (i.e. a new release with a new name), there may be one or more Service Pack released (i.e. game patches). These free updates provide a variety of fixes, improvements and upgrades to a product. A Service Pack will generally increment the [["Trainz-build" tag]] as these usually contain changes to the way content is configured or validated.

Once a Service Pack is released, we no longer test against older builds so we strongly recommend all Service Packs are applied to ensure you are using the latest, fully supported version. If any retrograde issues are identified, we may also release a "Hotfix" update to resolve the issue immediately (i.e. without waiting for a group of fixes or improvements) but these hotfixes will always be only for the latest version.

Please remember that “not-supported” does not mean the product is “unusable” or "broken", but rather it means that we do not test against that build nor release updates for it.

= End-of-support Dates =

The following end-of-support dates are formally acknowledged, and as of May 2015, 3 months advance notice will be provided prior to any changes to support.

{| border=1 cellpadding=2 cellspacing=0
|'''Product'''||'''End-of-support Date'''
|-
|[[Trainz 1.0]]||September 2010
|-
|[[UTC]]||September 2010
|-
|MSTS Regional Add-on Pack: USA and Canada Volume 1||September 2010
|-
|Microsoft Train Simulator Paint Shed||September 2010
|-
|Content Creation Art Source||September 2010
|-
|[[TRS2004]]||September 2010
|-
|Trainz Driver||September 2010
|-
|[[TRS2006]]||September 2010
|-
|Trainz Routes 1,2,3,4||September 2010
|-
|Trainz Collection||September 2010
|-
|Trainz Paintshed||September 2010
|-
|[[TC1|Trainz Classics 1]] (Harlem Line)||September 2011
|-
|[[TC2|Trainz Classics 2]] (Metropolis)||September 2011
|-
|[[TC3|Trainz Classics 3]] (Settle & Carlisle)||September 2012
|-
|[[TS2009]] World Builder Edition||September 2014
|-
|Treez Content Pack||September 2014
|-
|Settle and Carlisle Content Pack||September 2014
|-
|Cabon City Content Pack||September 2014
|-
|Murchison 2 Content Pack||September 2014
|-
|[[TS2010|Trainz Simulator 2010]] (Engineers Edition)||September 2014
|-
|[[TS12|Trainz Simulator 12]]||September 2018
|-
|[[Trainz Simulator Mac]]||September 2016
|-
|[[Trainz Simulator Mac 2]]||September 2018
|-
|[[TANE|Trainz: A New Era]]||September 2020
|-
|[[TRS19|Trainz Railroad Simulator 2019]]||September 2023
|}

= Q&A =

'''Q: ''Will the named products continue to operate after the listed end-of-support date?'''''

:'''A:''' We will do nothing specific to prevent the products from operating. However, if they were to stop working for some reason (for example, they were found to be incompatible with the latest Windows Operating System) we would not take any steps to resolve the issue. Additionally, any product features which rely on server support (for example, in-game [[Download Station]] access or iTrainz) may cease functioning correctly.

'''Q: ''Do you support non-upgraded products after a Service Pack has been released?'''''

:'''A:''' Once we have released a Service Pack update, the product has moved on from where it once was and we can no longer "fully support" the older version. e.g. we will not release an update solely for the older version, only further updates to the latest version. We will support all owners of the product and we will do nothing specific to prevent an non-updated version from operating normally, within reason.

'''Q: ''Should I always upgrade?'''''

:'''A:'''Service Packs implement additional features and fixes that we believe improve upon the original release. If you do not wish to update to the latest Service Pack release, then you are free to continue using the older version with whatever limitations come with that version. If there are problems identified with older versions that are resolved by upgrading, then the obvious solution is to upgrade.

'''Q: ''Can I still access the Download Station after the end-of-support date?'''''

:'''A:''' Access granted to you by the unsupported product may be terminated. If you have purchased access through other means (newer products, [[First Class Ticket]], etc.) then your access will continue thanks to these products.

'''Q: ''Can I still access the Download Station from within Trainz, Trainz Helper, or [[Content Manager]] after the end-of-support date?'''''

:'''A:''' Access to our servers from an unsupported product is not guaranteed, regardless of your level of Download Station access. You may need to download the content separately and then manually move it into the unsupported Trainz installation.

'''Q: ''Will the Download Station continue to host content for Trainz editions beyond their end-of-support date?'''''

:'''A:''' We will not immediately remove older content from the Download Station, as newer editions of Trainz can still use this content.

'''Q: ''Will I be able to upload old-format content to the Download Station?'''''

:'''A:''' New uploads to the Download Station must be in a format no older than our oldest supported product. Attempts to upload content with a trainz-build number lower than our oldest supported product will be rejected or will result in the content being flagged for third-party repair. This ensures that legacy formats are cleanly phased out over time.

'''Q: ''Will my Lifetime First Class Ticket continue to operate if all my registered products are beyond their end-of-support date?'''''

:'''A:''' Yes, we will ensure that all users who have a right to Download Station access can continue to download content. The specific techniques required to download content may change. At the current time, we offer support for using an FCT with the DLS web site to manually download content. We do not offer support for using an FCT with Content Manager (or similar) in an unsupported product. We do not offer support for installing manually-downloaded content into an unsupported product.

'''Q: ''I recently bought a copy of an unsupported product. Will you give support?'''''

:'''A:''' No. We will not sell products which are nearing the end-of-support date. It may be possible to purchase such a product from a third party through a bargain-bin outlet or similar, however we can not offer support for these products. We expect that the product will continue to operate as normal, and hope that you enjoy your experience with the product will be sufficiently enjoyable that you'll decide to upgrade to one of our supported products.

'''Q: ''My only Trainz product will shortly become unsupported. Will my forum access be removed?'''''

:'''A:''' No. We're not in the business of kicking our loyal users out of the community. We really think it would be beneficial if you upgraded to a supported version of Trainz, but that's a decision that you'll have to make. The product-specific forum may be removed, but your overall forum access will remain valid.

'''Q: ''Will the Download Station website be removed?'''''

:'''A:''' The Download Station website is not tied to a specific product. Our plans for this website are not affected by the end-of-support for any specific Trainz product. Your access to the Download Station is conditional upon having a supported product or other form of access such as a First Class Ticket. We expect to continue support and development of our web services indefinitely, although the exact form of these services may change over time.

'''Q: ''Is there a list of validation changes by version number?'''''

:'''A:''' No, but we have prepared a non-exhaustive list of [[validation changes]] made in the 5 years after TS2009 was released.

Help:VE218

2019-01-29T07:02:10Z

Windwalkr: Created page with "'''Asset has duplicate attached track at track $(INDEX).''' This error results when a KIND SceneryWithTrack-derived asset specifies two or more attached tracks between th..."

'''Asset has duplicate attached track at track $(INDEX).'''

This error results when a [[KIND SceneryWithTrack]]-derived asset specifies two or more attached tracks between the same pair of track vertices. This construction is never permitted by Trainz, and so the requested configuration cannot be fulfilled.

Note that in cases where the track vertices move (such as a turntable or transfer table) it may be possible for this scenario to exist only at specific instants within the animation. Current asset validation will only detect this problem if it occurs in the default state of the asset, meaning that it is possible for such an asset to pass validation but still encounter problems at runtime. This should still be considered a fault in the asset construction, as Trainz will not correctly honor such a configuration.

When repairing legacy assets which exhibit this error, the simplistic fix is to remove the duplicate entry. Such a change will, however, result in a different number of attached-track entries which means that existing instances of the asset saved into routes may encounter loader conflicts with the updated asset. If this is found to cause problems in practice, a more robust fix might be to move the duplicate entry to a "harmless" location which resolves the problem without introducing other concerns.

[[Category:Validation Errors]]

Session Rule Implementation

2018-11-28T04:31:59Z

Windwalkr:

This page seeks to clearly define expected script behavior for [[KIND Scenariobehavior|Session Rule assets]]. This focuses specifically on correct behavior from the code perspective, rather than addressing how rules should be designed for best gameplay outcomes.

= Legacy Behavior Note =
Please note that many existing rules do not behave correctly as defined here. This is considered a bug in the individual session rules. [[N3V Games]] has a policy of updating session rules to behave correctly even where that may lead to changes of function in existing [[session]] assets. Where reasonable to achieve, emulation of the existing (buggy) behavior may occur for existing rule instances in existing sessions, however any newly created rule instances will use the corrected behavior.

These expectations were codified at the end of [[TS12]] development due to an increasing inability of session rules to work together resulting from the unpredictable nature of their responses to various common use-cases. The systems as a whole, including most of the core rules discussed in this document, have existed for far longer than this document. The document does not redefine any existing systems, but simply presents the only reasonable implementation approach possible if rules are to be expected to work properly in all use-cases. In some cases we also choose to mandate specific points of behavior relating to user expectations rather than technical necessities.

Certain additional API mechanisms were introduced alongside the development of this document, to allow better communication with session authors regarding the differences in behavior between certain types of rule. The correct usage for these mechanisms is also included in this document.

= The Rule Hierarchy =
All rules within a given session form a simple tree structure.

== Rule State Flags ==
Each rule in the tree may have certain associated state flagged, including a combination of the following:

=== PAUSED ===
The rule is currently paused, meaning that it does not affect the game world in any way and does not respond to any changes in the game world. The parent rule must cause the rule to become unpaused for the rule to have any effect. It is not correct behavior for a rule to unpause itself.

=== COMPLETE ===
This flag indicates that rule has fully completed its operation (including any child rule operations) and does not affect the game world in any way. This flag is set by the rule itself, not by an outside entity such as the parent. This state should not be changed while the rule is PAUSED.

Being COMPLETE does not imply being PAUSED. In many scenarios, the parent rule may respond to a child becoming COMPLETE by causing it to also become PAUSED, however this is certainly not guaranteed in all cases, and is not guaranteed to be immediate in the cases where it does happen.

The rule may optionally respond to specific changes in the game world by deflagging the COMPLETE status. For example, a rule which specifically implements a condition check may choose to become COMPLETE when that condition is met, but return to an incomplete state when the condition is no longer met (again, remembering that a change in either direction should only happen while the rule itself is not PAUSED).

When a rule's COMPLETE state is changed via ScenarioBehavior.SetComplete(), a "ScenarioBehavior", "Touch" message is sent to its parent rule (if any), unless the parent is in the PAUSED state. This allows the parent to react to changes in its child rules' states. It is important to note that the message indicates a possible change which the parent may be interested in, but it is the parent rule's responsibility to determine whether the state change is worth reacting to.

=== WAS COMPLETE ===
This is typically set when a rule first becomes flagged as COMPLETE, and will stay set even if the rule later flags as incomplete. This can be used by a parent which only cares that the child rule has been flagged as COMPLETE at some point, rather than caring what its current completion status is.

=== DOES COMPLETE ===
This indicates whether the rule can ever reach the COMPLETE state. Its value is constant for a given rule configuration, and does not change based on the runtime rule state or other game state. Rules which are flagged as DOES COMPLETE are expected to become complete after some discreet operations are completed. Rules which are not flagged are expected to run indefinitely unless PAUSED by an external agent (such as the parent rule).

== Initial State ==
All rules are initially in the PAUSED state when in [[Surveyor]], and only become unpaused after gameplay begins in a [[Driver]] session. Since a PAUSED rule is not permitted to unpause itself, this is a stable state which will persist until the native code takes step to begin program flow.

== Top Level Rules ==
All rules at the top level (ie. rules which are not a child of any other rule) simultaneously become unpaused after the session has loaded into Driver. Some of these rules may take initial setup steps and then become COMPLETE. Some of these rules may begin monitoring for specific game conditions before taking any further action. Some of these rules may begin taking action immediately. The rules are not sequenced against each other in any way, and it is the session author's responsibility to ensure that this does not cause any conflicts.

== Scheduling ==
Since the script VM is a cooperatively-threaded environment, it is technically true that rule evaluation will occur in an ordered manner rather than truly simultaneously. However, no guarantees are made regarding the order in which the simultaneously-running rules will perform their checks or outcomes. Since rules may wait internally rather than fulfilling their entire purpose in an atomic operation, it is also not guaranteed that a first-running rule will fully complete before some other simultaneously-executing rule begins completion. In short, if order-of-execution is critical to the correct behavior of a session, then the order should be enforced by the session creator using the rule hierarchy rather than by making assumptions about execution order of simultaneously-running rules.

(Note: with the introduction of [[Asynchronous Route Streaming]], this is even more true than previously. What may have been a near-instantaneous operation in older builds may now require a wait of several seconds while the necessary data is streamed in.)

It is important to note that some conditional rules may partially or completely rely on a polling behavior to evaluate their conditions. (An example of partial reliance is a rule which waits for an event, but then evaluates a condition to clarify whether the event should be acted upon.) In these cases, it is possible that the condition can rapidly become true and then become false again without the rule responding. This results in an uncertainty as to whether the conditional rule will correctly detect a given instance of the condition. This type of scenario should be avoided completely where possible, and should most definitely be limited to outcomes that do not significantly affect gameplay.

For a hypothetical example, if the player's train speeds for 0.5sec, and a speeding check rule was implemented that polled every second, then the overspeed event may or may not trigger on any given occurrence. A session creator should not use this outcome as a failure condition, since some players may be able to speed without penalty, whereas other players would be penalised on the first attempt. A sensible solution in this case might be to increment a counter while speeding is detected, and only take action if the counter reaches a certain threshold. If the only penalty was a warning to the player which had no actual gameplay impact, then it might be acceptable to forgo this check and simply accept that some players will receive a warning where others may not.

==Child Rules==
As with all other rules, child rules (ie. those that have parent rules in the hierarchy) start out in the PAUSED state. They do not become unpaused until the parent is ready for the children to start operating. Exactly when this occurs depends on the specific parent rule, but the general flow is the same for all rules:

1. Parent rule becomes unpaused and begins operation.

2. Parent rule configures any necessary world state changes.

3. Parent rule optionally waits for a specific condition to occur.

4. Parent rule begins executing its children. This involves unpausing one or more of the children (as discussed below in "Parent Rule Styles").

5. Parent waits for its children to complete (as discussed below in "Parent Rule Styles") and then pauses the children.

6. Parent flags itself as COMPLETE.

This process allows program control flow to pass from a top-level rule, to its immediate children, to their immediate children, and so on. As the bottom-level children become complete, completion flows back to the higher level children until finally the top-level rules become COMPLETE.

It is worth noting that there is nothing special about a top-level rule being flagged as COMPLETE. This does not indicate an end-of-session or any other fundamental gameplay mode change. Since the pausing of rules on completion is handled by the parent rule (see step 5 above), the top-level rules never become PAUSED on completion.

==Parent Rule Styles==
There are a few common techniques with which parent rules interact with their children. Rules should always fit one of these descriptions. The vast majority of rules should follow either the "Does Not Support Children" style, or the "Ordered Execution of Children" style.

=== Does Not Support Children ===
The rule is incapable of supporting children and will always ignore them.

This is used for trivial rules which perform a set function and then become permanently COMPLETE. Such rules are not conditional and do not wait for any world state changes except those which they initiate internally.
The rule should be configured to validate and/or enforce that no child rules can be added.

=== Simultaneous Execution of Children ===
When the rule is ready to begin executing children, it unpauses all children simultaneously. The rule then waits for all children to flag as WAS COMPLETE. Once this is detected, the rule pauses all children and flags itself as COMPLETE.
This is used for rules which have a specific need to simultaneously execute children, such as the "Simultaneous List" rule.

The rule editor interface should be explicit that child rules will be executed simultaneously. Child rules should be tagged appropriately in the rule editor list to denote unordered execution.

=== Ordered Execution of Children ===
When the rule is ready to begin executing children, it iterates through the children in top-to-bottom order. If the child is flagged as WAS COMPLETE, the child is paused and iteration continues. If the child is not flagged as WAS COMPLETE, the child is unpaused and iteration ends. Whenever a child state change is detected, this process is repeated from the start. Once iteration passes over all children without leaving any child unpaused, the rule flags itself as COMPLETE.

This style is used for all rules which do not explicitly fall under one of the other styles described here. Almost all third-party rules will follow this style. Implementing one of the other styles without there being a fundamental requirement to do so is considered a programming error.

Rules which follow this style should derive from [[ConditionalScenarioBehavior]] in order to avoid re-implementing the control flow logic, as it is exceedingly complex to implement correctly. Any rules which do not derive from ConditionalScenarioBehavior should be accompanied by a clear explanation of the reasons that ConditionalScenarioBehavior is an unsuitable base class for the intended behavior. Rules which do derive from ConditionalScenarioBehavior should avoid complex overrides of the default logic.

Child rules should be tagged appropriately in the rule editor list to denote execution order.

=== Controlled Selection of a Single Child ===
When the rule is ready to begin executing children, it selects a single child and unpauses it. All other children remain paused. Once the selected child becomes flagged as WAS COMPLETE, the child is paused and the rule flags itself as COMPLETE.

This style is used where complex conditional selection of child rules is required. This can be used to implement an "if-else" logic flow, a "switch-case" logic flow, or the "Random List" rule. This style should not be used to implement a simple "if" logic flow, because that would unnecessarily restrict the rule to a single child where the "Ordered Execution of Children" style would provide the same functionality while allowing multiple children.
The rule editor interface should be very explicit about how the child rules will be selected. Child rules should be tagged appropriately in the rule editor list to avoid the user attempting to fit a child rule into the wrong role.

=== Custom Execution with Multiple Children ===
This style is used for very specific custom-purpose rules, such as a passenger station stop handler. Such rules should give a clear and complete explanation of their operation and their interaction with any child rules in the rule editor interface.

Individual child rules may be executed in an ad-hoc manner by the rule in response to changes in game state. Child rules may or may not be executed simultaneously and may or may not be executed repeatedly depending on the rule; any limitations or gotchas deriving from this should be carefully explained in the rule editor interface.

Child rules should be tagged appropriately in the rule editor list to avoid the user attempting to fit a child rule into the wrong role.

= Early Termination via Pause =
A rule must accept being paused by its parent at any time. This should cause the rule to cease any game state monitoring or other direct effects. The rule must pause all child rules immediately.

In cases where the rule is maintaining some reversible effect on the game world, pausing the rule should end this effect. For example, a rule which displays a message to the user should typically hide the message upon becoming paused, and a rule which causes a rain storm in a specific area should return the weather to normal upon becoming paused. Rules which make a single permanent change to the game world and then immediately flag as COMPLETE should not attempt to reverse the change upon becoming paused. Examples of these rules include configuration of the global weather conditions, or a rule which increments the player's score or penalty counter.

It is important to note that any pause is resumable, although the parent may not choose to take advantage of this. Pausing a rule followed by unpausing it should result in the rule continuing operation where it left off. The notes on Saving and Loading Driver Sessions (below) are worth considering when evaluating techniques for implementing pause.

= Early Termination via Internal Logic =
In some cases, a rule may begin executing child rules but then make an internal decision to abort execution. This typically occurs in conditional rules where the condition may be re-evaluated as false after it has already been evaluated as true. Such behavior should be made explicit in the rule editor interface and should usually be made optional by providing a checkbox.

There are in fact several possible behavioral variants affecting how condition-deflag is interpreted:
* Once the condition is flagged, the rule starts executing child rules and no further evaluation is performed. The rule eventually flags itself as COMPLETE and does not later deflag this.
* Once the condition is flagged, the rule starts executing child rules. If the condition becomes deflagged, the child rules are paused. If the condition becomes flagged again, the child rules are continued. Once the child rules have fully completed execution, the rule flags itself as COMPLETE and does not later deflag this.
* Once the condition is flagged, the rule starts executing child rules. If the condition becomes deflagged, the child rules are paused. If the condition becomes flagged again, the children are reset and execution starts anew. The rule flags itself as COMPLETE if all children successfully complete, but it will deflag if the condition deflags.
* Once the condition is flagged, the rule starts executing child rules. If the condition becomes deflagged, the child rules continue executing. If the condition becomes flagged again, the children are reset and execution starts anew. The rule will flag as COMPLETE if all children successfully complete, but it will deflag if the condition deflags.
* Once the condition is flagged, the rule starts executing child rules. The child rules continue execution with no regard for whether the condition changes between flagged or deflagged in either direction. If the condition transitions from deflagged to flagged again after the children have completed, the children are reset and execution starts anew. The rule will flag as COMPLETE if all children successfully complete, but it will deflag itself if the condition deflags.

The complexity here derives from the fact that it is not possible to use the same set of rules multiple times concurrently for different trigger conditions. For example, if a set of rules is used to give demerit points and provide user notifications, and those rules live under a single conditional check which determines whether a train is speeding, it may be difficult to define what should happen if two trains are detected as speeding at the same time, or if a train stops speeding while the notification process is still in progress. It is not always possible to achieve a perfect solution to tracking multiple objects using a single set of rules, but correct selection from the above behaviors can minimise the possibility of serious side-effects.

It is important to note that these behaviors describe how the rule reacts to internal condition checks. The rule's reaction to being paused by its parent is discussed above under "Early Termination via Pause" and is not affected by the description here.

In short, there are many ways of handling this, and the important thing is for your (parent) rule to clearly explain which approach it is going to use.

= Rule Reset =
A rule may be ''reset'' by its parent. This causes both the COMPLETE and WAS COMPLETE states to be deflagged. Individual rules may also react to the reset by modifying their internal state to forget past or present actions. Parent rules must also cause their children to be reset in turn.

This mechanism is used to permit rules to be used in a repeating scenario, such as responding to a condition which can occur multiple times, or in a repeating loop. At some point after a rule has become flagged as WAS COMPLETE, it will typically become paused and will not be unpaused again. If the rule is to be included in some repeating behavior, this would normally prevent the behavior from operating successfully after the first run through. To avoid this, the parent rule responsible for implementing the repeating behavior will ''reset'' all children when a repeat occurs. This effectively cleans the rules back to their initial state ready to perform their roles again.

It is important to note that a reset should cause the rule to return to its configured settings. For example, if a timer value is configured and is decremented during rule operation, the timer must be reset back to its initial value during rule reset.

It is important to note that there is no requirement to pause a rule prior to resetting it.

= Saving and Loading Driver Sessions =
For better or worse, the script VM does not persist across a save/load operation. This means that each rule must correctly save both its configuration state and its runtime state, and must correctly reload those such that the state after a save/load operation is indistinguishable from the original state. The following aspects of the script state must be considered:

* Member variables in the Rule instance.
* Which threads are running on the Rule instance, and where they are up to in the code flow.
* Local variables on the stack of each running thread.
* Non-persistent changes made to the state of other script objects (such as active 'sniff' statements).
* Script Messages which might be in flight at the time of save (these are not persisted, so the net effect is that they are simply deleted between the save and the load.)

Since the game state continues normal operation after a Save, no code flow or other behavioral changes should result from the Save operation itself. Instead, the Save operation (and the design of the rule as a whole) is responsible for ensuring that sufficient data is persisted in the save file such that the Load operation is able to restore to the correct running state.

The rule base class, ScenarioBehavior, is responsible for saving and loading the rule state flags (COMPLETE, PAUSED, WAS COMPLETE, etc.) A rule which was paused at Save time will still be paused after the Load. A rule which was complete at Save time will still be complete after the Load. During a Load operation, the rule should inherit the parent class' SetProperties() method so that these flags are correctly configured, then honor the paused state during the rest of the loading process.

It is rarely appropriate for an unpaused rule to simply restart execution from the beginning. Care must be taken to ensure that execution resumes from the point that it left off at the time of saving. This process can be simplified by keeping as much state as possible in the rule member variables at all times, and only keeping reconstructible temporary values on the stack. If the member variables are correctly stored and restored, this approach will allow the loading process to detect the runtime state of the rule and resume any necessary threads, which will in turn be able to jump forward to the correct area of the code based on the stored state.

Finally, the COMPLETE, WAS COMPLETE, and PAUSED flags on child rules should be honored. This is typically sufficient information to determine the running state of child rules, so no further state will generally need to be maintained. More accurately, the child rules take care of their own state at all times, and the parent only needs to react to changes in the child state. Since no child state change occurs across a Save/Load operation, the parent does not need to become involved.

For rules which derive ConditionalScenarioBehavior, the majority of load/save logic is handled automatically. The only state information that such a rule should typically preserve is the instance-specific configuration data. The condition-monitor thread will be automatically restarted as required, and there is generally no need to distinguish between a first-startup and any subsequent startup.

= Spurious Events =
There are various events (typically script messages) that a rule may listen for in order to detect state changes. It is important to note that spurious events are often possible, and that an event handler should often be coupled with a condition check. As a specific example, the "ScenarioBehavior", "Touch" message typically indicates that a child state has changed, but the message may in fact be sent at any time. This message should prompt the rule to evaluate whether any state changes are necessary, but the rule should not simply assume that a state change is necessary without performing an evaluation.

Similarly, calls to a function such as Pause() may in some cases have no effect. For example, if a rule is already executing and its parent calls Pause(false), the rule should not pause, reset, or change state in any way at all. Similarly, if a rule is already paused and its parent calls Pause(true), the rule should not unpause, reset, fire any events, or otherwise change state in any way at all.

The short version is: do not assume that every event and every method call is supposed to achieve something meaningful. Check first, and if the event is meaningless to you then do nothing at all.

= Future Considerations =
Rules should base their functionality on the state flags such as the PAUSED state, rather than attempting to detect and vary their functionality based on the state of the game.

For example, we currently (in development builds) expose the rules editor in Driver for debugging purposes. This, or some mechanism like it, is likely to be included in public builds in the future. Rules should not assume that it is impossible to be reconfigured during gameplay. This will of course introduce some side effects, such as when an unpaused rule is modified during execution. It is the rule's responsibility to ensure that these side effects do not lead to script exceptions or to leaked state. For example, if a single thread is supposed to be running, reconfiguring the rule should not cause a second thread to run simultaneously. If a rule sniffs a target vehicle, and the target vehicle is redefined, then the rule should unsniff the original vehicle rather than now sniffing two vehicles.

Likewise, we may in future allow some form of partial state swap between Driver and Surveyor. Rules should not assume that it is impossible to change from any one game state or module to any other game state or module, just because it is not possible at the current time. APIs already exist to detect such state changes where necessary, and in most cases it's simply not necessary to care whether your rule is in Surveyor or Driver - you should act based on the PAUSED state instead. Rules should deal with the game state as they find it rather than assuming that certain states will not ever occur.

= Gotchas =
There are a few potential gotchas in the script environment that are worth considering when writing any non-trivial rule.

== Response Latency ==
Scripts tend to rely heavily on message passing and threading. In both cases, there is a delay between triggering a certain behavior (eg. posting an event, or calling a threaded function) and having the receiving code react. Other code may execute during this delay.

<code><pre>
// Calling this might be expected to start and then stop the thread; in reality it
// will likely simply start the thread and leave it running, because the message
// is sent prior to the wait() statement starting.
void DemonstrateBug1(void)
{
Pause(false);
Pause(true);
}

// In this case, we use a Sleep() statement to "ensure" that the thread has
// finished starting. This isn't actually reliable, but it works as long as the
// system isn't under too much load. We follow this up with a rapid pause-
// unpause sequence. As above, this doesn't work - the message is sent,
// then the function immediately checks whether the thread is still running
// (which it is) and thus the thread isn't restarted. The function completes,
// and finally the thread receives the message and exits.
void DemonstrateBug2(void)
{
Pause(false);
Sleep(1.0);
Pause(true);
Pause(false);
}

// Helper code for the above functions.
void Pause(bool bIsPaused)
{
if (bIsPaused)
{
PostMessage(me, "ThisRule", "Pause");
}
else if (!m_bIsThreadRunning)
{
m_bIsThreadRunning = true;
StartThread();
}
}
thread void StartThread(void)
{
while (true)
{
wait ()
{
on "ThisRule", "Pause":
break;
...
}
m_bIsThreadRunning = false;
}
</pre></code>

== Multiple Messages in Flight ==
It's possible to post multiple identical messages. This can be useful, but if you're expecting only one then it can be a source of errors.

In the following pseudocode, each call to SetProperties() will place an additional "Timer", "Tick" message into the cycle, effectively increasing the rate at which the IdleFunction is called. This will seem to be working for a single call to SetProperties(), which may be all that is called during a trivial testcase. It will probably give reasonable results for a few calls to SetProperties(), although if the function is time-sensitive then the results might be different to expectations. After a larger number of calls to SetProperties(), the object's message queue may become full, causing it to lose messages at random (perhaps the tick messages, or perhaps other unrelated messages that are more problematic).

<code><pre>
void Init(void)
{
inherited();

AddHandler(me, "Timer", "Tick", "IdleFunction");
}

void EnterIdleState(void)
{
IdleFunction();
}

void IdleFunction(void)
{
PostMessage(me, "Timer", "Tick", 1.0);
.. do something here ..
}

void SetProperties(Soup soup)
{
inherited(soup);

EnterIdleState();
}

</pre></code>

A similar problem can occur if you start new threads rather than post new messages.

== Thread Guard Variables ==
It's common to prevent a singleton thread from being started twice by using a boolean guard variable. Care must be taken to ensure that the guard variable is set and cleared at the correct locations, or they may be ineffective.

The following pseudocode demonstrates one such correct usage. The key points to note are:
* We set 'm_bIsThreadedFunctionRunning' prior to calling the threaded function. Setting it within the threaded function is too late; multiple threads might have already been started before the first thread reaches that point.
* We don't confuse whether the thread is actually running with whether we want the thread to be running. Once we ask a thread to start, we can't stop it starting. If we change our minds and want to stop it again, we must inform it in a way that it will realise after it finishes starting. In the worst-case scenario, we might flipflop on this multiple times before the thread actually starts.
* Similarly, we don't rely on messages to control the thread. Enqueuing a separate start or stop message with each StartThread()/StopThread() call might be possible, and we could clear any unwanted prior messages from the object's queue, but if the thread hasn't finished starting then it won't receive the messages anyway.
* We do rely on messages to wake the thread if it's waiting on messages, but we don't use those messages to imply any state - we just have it recheck the current state boolean to get the very latest info.
* We clear 'm_bIsThreadedFunctionRunning' once the decision to exit has become unconditional. At this point, even though the thread is technically still running, we'll have to start a new thread if we want the thread to continue running.

<code><pre>
bool m_bIsThreadedFunctionRunning = false;
bool m_bWantThreadedFunctionRunning = false;

void StartThread(void)
{
m_bWantThreadedFunctionRunning = true;

if (m_bIsThreadedFunctionRunning)
return;

m_bIsThreadedFunctionRunning = true;
ThreadedFunction();
}

void StopThread(void)
{
if (!m_bWantThreadedFunctionRunning)
return;

m_bWantThreadedFunctionRunning = false;
PostMessage(me, "Thread", "Touch");
}

thread void ThreadedFunction(void)
{
while (m_bWantThreadedFunctionRunning)
{
wait()
{
on "Thread", "Touch":
break;
.. whatever else..
}
}
m_bIsThreadedFunctionRunning = false;
}
</pre></code>

== Not Waiting For Messages ==
As seen above, it's possible for a thread to fail to receive posted messages because it wasn't waiting for them at the time. A more commonly problematic example follows.

<code><pre>
thread void MyThread(void)
{
wait ()
{
on "Some", "Condition":
HandleSomeCondition();
continue;
on "Thread", "Exit":
break;
}
}

void HandleSomeCondition(void)
{
wait ()
{
on "Some", "End-Condition":
break;
}
}
</pre></code>

In this example, the thread is waiting on both "Some", "Condition" and also "Thread", "Exit". Either one will be handled correctly assuming that the thread is already running at the time they are posted. Even if multiple are posted, the thread will simply queue them and run each in turn.

The problem occurs when HandleSomeCondition() is triggered and the thread begins waiting on "Some", "End-Condition". In this scenario, the thread is no longer waiting on "Thread", "Exit", and any attempt to post that message will simply be ignored. To reiterate: the message dispatch is NOT postponed until the function returns; the message is dropped entirely.

In many cases, the correct behaviour is to move HandleSomeCondition() to a new thread, although that may also carry gotchas that you will need to be careful of (eg. you'll probably want to terminate the second thread at the same time as the first one, and you may need to consider whether you want multiple of the second thread to run simultaneously or not).

== Performing Actions After Being Told to Stop ==
In many cases, you may wish to perform cleanup actions when stopping your rule. If your rule is threaded, this can easily become problematic.

Consider the following pseudocode example:

<code><pre>
void Pause(bool bIsPaused)
{
if (!bIsPaused && !m_bIsThreadRunning)
{
m_bIsThreadRunning = true;
MyThread();
}
}

thread void MyThread(void)
{
BeginRule();
while (!IsPaused())
{
Sleep(0.5);
UpdateRule();
}
EndRule();
m_bIsThreadRunning = false;
}
</pre></code>

There are three immediately obvious problems:

1. That BeginRule() is called when the thread starts, even if the rule has already been paused again.

2. That UpdateRule() will be called after each sleep, even if the rule was paused during the sleep.

3. That EndRule() will be called after the rule has been paused.

This is very problematic because it likely violates a core principles of the rules system: that rules will not undertake any meaningful behaviour when paused. All three functions may be called while the rule is paused, so unless the rule does nothing meaningful at all, this is a guaranteed violation.

The best approach to resolving this may depend on exactly what these functions do, but one possible solution is as follows:

<code><pre>
void Pause(bool bIsPaused)
{
if (bIsPaused)
{
if (m_bNeedsEndRule)
{
m_bNeedsEndRule = false;
EndRule();
}
}
else
{
if (!m_bNeedsEndRule)
{
BeginRule();
m_bNeedsEndRule = true;
}
if (!m_bIsThreadRunning)
{
m_bIsThreadRunning = true;
MyThread();
}
}
}

thread void MyThread(void)
{
while (!IsPaused())
{
UpdateRule();
Sleep(0.5);
}
m_bIsThreadRunning = false;
}
</pre></code>

== Handler Called while Paused ==
This one is pretty obvious, but can still catch you out. Handler functions created with AddHandler() will always be called, regardless of whether your rule is paused. You should generally only add your required handlers when your rule is unpaused, and remove them again when paused. If that's not feasible for some reason, then the alternative is to have you handler function confirm the paused state of the rule before doing any actual work (but keep in mind that this approach wastes CPU time).

== Failing to Inherit from ConditionalScenarioBehavior ==
This isn't really a separate gotcha, but it can't be stressed enough that your rule should inherit from ConditionalScenarioBehavior and should minimise the number of overrides to its default behavior. Apart from the "users expect things to work like this, so that's what you should do" argument, there are some much more compelling arguments for would-be rule developers:

1. Developing a rule with correct threading behavior is hard. Just have a look at some of the above gotchas. Were you already consciously aware of them all? If not, you're probably not ready to write your own rule which involves threading. ConditionalScenarioBehavior provides a polling thread mechanism that's already built, so you can reap the benefits of that approach without having to worry about whether you made any mistakes in the threading code.

2. Developing a rule with correct load/save behavior can be hard. Did you correctly restart your threads when necessary? Did you accidentally restart your threads when you weren't supposed to? Was there a message in flight during the save which you lost by reloading, and have you handled that loss correctly? ConditionalScenarioBehavior can help with a lot of that kind of thing, leaving you to worry about your rule-specific implementation only.

3. Developing a rule with correct child-rule-handling behavior can be really hard. You need to have a thorough understand of everything listed in this document, and you need to ensure that you don't make any mistakes which could cause your rule to violate any of the principles in this document, even in edge-case behaviours. Because this is the real world, you also need to handle child rules which don't necessarily follow the rules to the letter. ConditionalScenarioBehavior does all of this automatically with no effort on your part.

4. Inheriting from ConditionalScenarioBehavior means that many future issues can be fixed automatically by [[N3V Games]] without you having to update your rule. This includes both fixes to our own code (hey, we're human too) and also new changes to adapt our code to future requirements.

5. Inheriting from ConditionalScenarioBehavior typically means that there's a lot less semi-custom boilerplate in your rule, making your rule much simpler to read and maintain. This helps you while you're debugging your own rule, helps you when you're coming back in a year's time and wondering how it all worked, and perhaps helps others in the community if they need to update your rule in 10 years time after you've moved on from developing Trainz script code.

Session Rule Implementation

2018-11-27T17:26:22Z

Windwalkr: /* Gotchas */

This page seeks to clearly define expected script behavior for [[KIND Scenariobehavior|Session Rule assets]]. This focuses specifically on correct behavior from the code perspective, rather than addressing how rules should be designed for best gameplay outcomes.

= Legacy Behavior Note =
Please note that many existing rules do not behave correctly as defined here. This is considered a bug in the individual session rules. [[N3V Games]] has a policy of updating session rules to behave correctly even where that may lead to changes of function in existing [[session]] assets. Where reasonable to achieve, emulation of the existing (buggy) behavior may occur for existing rule instances in existing sessions, however any newly created rule instances will use the corrected behavior.

These expectations were codified at the end of [[TS12]] development due to an increasing inability of session rules to work together resulting from the unpredictable nature of their responses to various common use-cases. The systems as a whole, including most of the core rules discussed in this document, have existed for far longer than this document. The document does not redefine any existing systems, but simply presents the only reasonable implementation approach possible if rules are to be expected to work properly in all use-cases. In some cases we also choose to mandate specific points of behavior relating to user expectations rather than technical necessities.

Certain additional API mechanisms were introduced alongside the development of this document, to allow better communication with session authors regarding the differences in behavior between certain types of rule. The correct usage for these mechanisms is also included in this document.

= The Rule Hierarchy =
All rules within a given session form a simple tree structure.

== Rule State Flags ==
Each rule in the tree may have certain associated state flagged, including a combination of the following:

=== PAUSED ===
The rule is currently paused, meaning that it does not affect the game world in any way and does not respond to any changes in the game world. The parent rule must cause the rule to become unpaused for the rule to have any effect. It is not correct behavior for a rule to unpause itself.

=== COMPLETE ===
This flag indicates that rule has fully completed its operation (including any child rule operations) and does not affect the game world in any way. This flag is set by the rule itself, not by an outside entity such as the parent. This state should not be changed while the rule is PAUSED.

Being COMPLETE does not imply being PAUSED. In many scenarios, the parent rule may respond to a child becoming COMPLETE by causing it to also become PAUSED, however this is certainly not guaranteed in all cases, and is not guaranteed to be immediate in the cases where it does happen.

The rule may optionally respond to specific changes in the game world by deflagging the COMPLETE status. For example, a rule which specifically implements a condition check may choose to become COMPLETE when that condition is met, but return to an incomplete state when the condition is no longer met (again, remembering that a change in either direction should only happen while the rule itself is not PAUSED).

When a rule's COMPLETE state is changed via ScenarioBehavior.SetComplete(), a "ScenarioBehavior", "Touch" message is sent to its parent rule (if any), unless the parent is in the PAUSED state. This allows the parent to react to changes in its child rules' states. It is important to note that the message indicates a possible change which the parent may be interested in, but it is the parent rule's responsibility to determine whether the state change is worth reacting to.

=== WAS COMPLETE ===
This is typically set when a rule first becomes flagged as COMPLETE, and will stay set even if the rule later flags as incomplete. This can be used by a parent which only cares that the child rule has been flagged as COMPLETE at some point, rather than caring what its current completion status is.

=== DOES COMPLETE ===
This indicates whether the rule can ever reach the COMPLETE state. Its value is constant for a given rule configuration, and does not change based on the runtime rule state or other game state. Rules which are flagged as DOES COMPLETE are expected to become complete after some discreet operations are completed. Rules which are not flagged are expected to run indefinitely unless PAUSED by an external agent (such as the parent rule).

== Initial State ==
All rules are initially in the PAUSED state when in [[Surveyor]], and only become unpaused after gameplay begins in a [[Driver]] session. Since a PAUSED rule is not permitted to unpause itself, this is a stable state which will persist until the native code takes step to begin program flow.

== Top Level Rules ==
All rules at the top level (ie. rules which are not a child of any other rule) simultaneously become unpaused after the session has loaded into Driver. Some of these rules may take initial setup steps and then become COMPLETE. Some of these rules may begin monitoring for specific game conditions before taking any further action. Some of these rules may begin taking action immediately. The rules are not sequenced against each other in any way, and it is the session author's responsibility to ensure that this does not cause any conflicts.

== Scheduling ==
Since the script VM is a cooperatively-threaded environment, it is technically true that rule evaluation will occur in an ordered manner rather than truly simultaneously. However, no guarantees are made regarding the order in which the simultaneously-running rules will perform their checks or outcomes. Since rules may wait internally rather than fulfilling their entire purpose in an atomic operation, it is also not guaranteed that a first-running rule will fully complete before some other simultaneously-executing rule begins completion. In short, if order-of-execution is critical to the correct behavior of a session, then the order should be enforced by the session creator using the rule hierarchy rather than by making assumptions about execution order of simultaneously-running rules.

(Note: with the introduction of [[Asynchronous Route Streaming]], this is even more true than previously. What may have been a near-instantaneous operation in older builds may now require a wait of several seconds while the necessary data is streamed in.)

It is important to note that some conditional rules may partially or completely rely on a polling behavior to evaluate their conditions. (An example of partial reliance is a rule which waits for an event, but then evaluates a condition to clarify whether the event should be acted upon.) In these cases, it is possible that the condition can rapidly become true and then become false again without the rule responding. This results in an uncertainty as to whether the conditional rule will correctly detect a given instance of the condition. This type of scenario should be avoided completely where possible, and should most definitely be limited to outcomes that do not significantly affect gameplay.

For a hypothetical example, if the player's train speeds for 0.5sec, and a speeding check rule was implemented that polled every second, then the overspeed event may or may not trigger on any given occurrence. A session creator should not use this outcome as a failure condition, since some players may be able to speed without penalty, whereas other players would be penalised on the first attempt. A sensible solution in this case might be to increment a counter while speeding is detected, and only take action if the counter reaches a certain threshold. If the only penalty was a warning to the player which had no actual gameplay impact, then it might be acceptable to forgo this check and simply accept that some players will receive a warning where others may not.

==Child Rules==
As with all other rules, child rules (ie. those that have parent rules in the hierarchy) start out in the PAUSED state. They do not become unpaused until the parent is ready for the children to start operating. Exactly when this occurs depends on the specific parent rule, but the general flow is the same for all rules:

1. Parent rule becomes unpaused and begins operation.

2. Parent rule configures any necessary world state changes.

3. Parent rule optionally waits for a specific condition to occur.

4. Parent rule begins executing its children. This involves unpausing one or more of the children (as discussed below in "Parent Rule Styles").

5. Parent waits for its children to complete (as discussed below in "Parent Rule Styles") and then pauses the children.

6. Parent flags itself as COMPLETE.

This process allows program control flow to pass from a top-level rule, to its immediate children, to their immediate children, and so on. As the bottom-level children become complete, completion flows back to the higher level children until finally the top-level rules become COMPLETE.

It is worth noting that there is nothing special about a top-level rule being flagged as COMPLETE. This does not indicate an end-of-session or any other fundamental gameplay mode change. Since the pausing of rules on completion is handled by the parent rule (see step 5 above), the top-level rules never become PAUSED on completion.

==Parent Rule Styles==
There are a few common techniques with which parent rules interact with their children. Rules should always fit one of these descriptions. The vast majority of rules should follow either the "Does Not Support Children" style, or the "Ordered Execution of Children" style.

=== Does Not Support Children ===
The rule is incapable of supporting children and will always ignore them.

This is used for trivial rules which perform a set function and then become permanently COMPLETE. Such rules are not conditional and do not wait for any world state changes except those which they initiate internally.
The rule should be configured to validate and/or enforce that no child rules can be added.

=== Simultaneous Execution of Children ===
When the rule is ready to begin executing children, it unpauses all children simultaneously. The rule then waits for all children to flag as WAS COMPLETE. Once this is detected, the rule pauses all children and flags itself as COMPLETE.
This is used for rules which have a specific need to simultaneously execute children, such as the "Simultaneous List" rule.

The rule editor interface should be explicit that child rules will be executed simultaneously. Child rules should be tagged appropriately in the rule editor list to denote unordered execution.

=== Ordered Execution of Children ===
When the rule is ready to begin executing children, it iterates through the children in top-to-bottom order. If the child is flagged as WAS COMPLETE, the child is paused and iteration continues. If the child is not flagged as WAS COMPLETE, the child is unpaused and iteration ends. Whenever a child state change is detected, this process is repeated from the start. Once iteration passes over all children without leaving any child unpaused, the rule flags itself as COMPLETE.

This style is used for all rules which do not explicitly fall under one of the other styles described here. Almost all third-party rules will follow this style. Implementing one of the other styles without there being a fundamental requirement to do so is considered a programming error.

Rules which follow this style should derive from [[ConditionalScenarioBehavior]] in order to avoid re-implementing the control flow logic, as it is exceedingly complex to implement correctly. Any rules which do not derive from ConditionalScenarioBehavior should be accompanied by a clear explanation of the reasons that ConditionalScenarioBehavior is an unsuitable base class for the intended behavior. Rules which do derive from ConditionalScenarioBehavior should avoid complex overrides of the default logic.

Child rules should be tagged appropriately in the rule editor list to denote execution order.

=== Controlled Selection of a Single Child ===
When the rule is ready to begin executing children, it selects a single child and unpauses it. All other children remain paused. Once the selected child becomes flagged as WAS COMPLETE, the child is paused and the rule flags itself as COMPLETE.

This style is used where complex conditional selection of child rules is required. This can be used to implement an "if-else" logic flow, a "switch-case" logic flow, or the "Random List" rule. This style should not be used to implement a simple "if" logic flow, because that would unnecessarily restrict the rule to a single child where the "Ordered Execution of Children" style would provide the same functionality while allowing multiple children.
The rule editor interface should be very explicit about how the child rules will be selected. Child rules should be tagged appropriately in the rule editor list to avoid the user attempting to fit a child rule into the wrong role.

=== Custom Execution with Multiple Children ===
This style is used for very specific custom-purpose rules, such as a passenger station stop handler. Such rules should give a clear and complete explanation of their operation and their interaction with any child rules in the rule editor interface.

Individual child rules may be executed in an ad-hoc manner by the rule in response to changes in game state. Child rules may or may not be executed simultaneously and may or may not be executed repeatedly depending on the rule; any limitations or gotchas deriving from this should be carefully explained in the rule editor interface.

Child rules should be tagged appropriately in the rule editor list to avoid the user attempting to fit a child rule into the wrong role.

= Early Termination via Pause =
A rule must accept being paused by its parent at any time. This should cause the rule to cease any game state monitoring or other direct effects. The rule must pause all child rules immediately.

In cases where the rule is maintaining some reversible effect on the game world, pausing the rule should end this effect. For example, a rule which displays a message to the user should typically hide the message upon becoming paused, and a rule which causes a rain storm in a specific area should return the weather to normal upon becoming paused. Rules which make a single permanent change to the game world and then immediately flag as COMPLETE should not attempt to reverse the change upon becoming paused. Examples of these rules include configuration of the global weather conditions, or a rule which increments the player's score or penalty counter.

It is important to note that any pause is resumable, although the parent may not choose to take advantage of this. Pausing a rule followed by unpausing it should result in the rule continuing operation where it left off. The notes on Saving and Loading Driver Sessions (below) are worth considering when evaluating techniques for implementing pause.

= Early Termination via Internal Logic =
In some cases, a rule may begin executing child rules but then make an internal decision to abort execution. This typically occurs in conditional rules where the condition may be re-evaluated as false after it has already been evaluated as true. Such behavior should be made explicit in the rule editor interface and should usually be made optional by providing a checkbox.

There are in fact several possible behavioral variants affecting how condition-deflag is interpreted:
* Once the condition is flagged, the rule starts executing child rules and no further evaluation is performed. The rule eventually flags itself as COMPLETE and does not later deflag this.
* Once the condition is flagged, the rule starts executing child rules. If the condition becomes deflagged, the child rules are paused. If the condition becomes flagged again, the child rules are continued. Once the child rules have fully completed execution, the rule flags itself as COMPLETE and does not later deflag this.
* Once the condition is flagged, the rule starts executing child rules. If the condition becomes deflagged, the child rules are paused. If the condition becomes flagged again, the children are reset and execution starts anew. The rule flags itself as COMPLETE if all children successfully complete, but it will deflag if the condition deflags.
* Once the condition is flagged, the rule starts executing child rules. If the condition becomes deflagged, the child rules continue executing. If the condition becomes flagged again, the children are reset and execution starts anew. The rule will flag as COMPLETE if all children successfully complete, but it will deflag if the condition deflags.
* Once the condition is flagged, the rule starts executing child rules. The child rules continue execution with no regard for whether the condition changes between flagged or deflagged in either direction. If the condition transitions from deflagged to flagged again after the children have completed, the children are reset and execution starts anew. The rule will flag as COMPLETE if all children successfully complete, but it will deflag itself if the condition deflags.

The complexity here derives from the fact that it is not possible to use the same set of rules multiple times concurrently for different trigger conditions. For example, if a set of rules is used to give demerit points and provide user notifications, and those rules live under a single conditional check which determines whether a train is speeding, it may be difficult to define what should happen if two trains are detected as speeding at the same time, or if a train stops speeding while the notification process is still in progress. It is not always possible to achieve a perfect solution to tracking multiple objects using a single set of rules, but correct selection from the above behaviors can minimise the possibility of serious side-effects.

It is important to note that these behaviors describe how the rule reacts to internal condition checks. The rule's reaction to being paused by its parent is discussed above under "Early Termination via Pause" and is not affected by the description here.

In short, there are many ways of handling this, and the important thing is for your (parent) rule to clearly explain which approach it is going to use.

= Rule Reset =
A rule may be ''reset'' by its parent. This causes both the COMPLETE and WAS COMPLETE states to be deflagged. Individual rules may also react to the reset by modifying their internal state to forget past or present actions. Parent rules must also cause their children to be reset in turn.

This mechanism is used to permit rules to be used in a repeating scenario, such as responding to a condition which can occur multiple times, or in a repeating loop. At some point after a rule has become flagged as WAS COMPLETE, it will typically become paused and will not be unpaused again. If the rule is to be included in some repeating behavior, this would normally prevent the behavior from operating successfully after the first run through. To avoid this, the parent rule responsible for implementing the repeating behavior will ''reset'' all children when a repeat occurs. This effectively cleans the rules back to their initial state ready to perform their roles again.

It is important to note that a reset should cause the rule to return to its configured settings. For example, if a timer value is configured and is decremented during rule operation, the timer must be reset back to its initial value during rule reset.

It is important to note that there is no requirement to pause a rule prior to resetting it.

= Saving and Loading Driver Sessions =
For better or worse, the script VM does not persist across a save/load operation. This means that each rule must correctly save both its configuration state and its runtime state, and must correctly reload those such that the state after a save/load operation is indistinguishable from the original state. The following aspects of the script state must be considered:

* Member variables in the Rule instance.
* Which threads are running on the Rule instance, and where they are up to in the code flow.
* Local variables on the stack of each running thread.
* Non-persistent changes made to the state of other script objects (such as active 'sniff' statements).
* Script Messages which might be in flight at the time of save (these are not persisted, so the net effect is that they are simply deleted between the save and the load.)

Since the game state continues normal operation after a Save, no code flow or other behavioral changes should result from the Save operation itself. Instead, the Save operation (and the design of the rule as a whole) is responsible for ensuring that sufficient data is persisted in the save file such that the Load operation is able to restore to the correct running state.

The rule base class, ScenarioBehavior, is responsible for saving and loading the rule state flags (COMPLETE, PAUSED, WAS COMPLETE, etc.) A rule which was paused at Save time will still be paused after the Load. A rule which was complete at Save time will still be complete after the Load. During a Load operation, the rule should inherit the parent class' SetProperties() method so that these flags are correctly configured, then honor the paused state during the rest of the loading process.

It is rarely appropriate for an unpaused rule to simply restart execution from the beginning. Care must be taken to ensure that execution resumes from the point that it left off at the time of saving. This process can be simplified by keeping as much state as possible in the rule member variables at all times, and only keeping reconstructible temporary values on the stack. If the member variables are correctly stored and restored, this approach will allow the loading process to detect the runtime state of the rule and resume any necessary threads, which will in turn be able to jump forward to the correct area of the code based on the stored state.

Finally, the COMPLETE, WAS COMPLETE, and PAUSED flags on child rules should be honored. This is typically sufficient information to determine the running state of child rules, so no further state will generally need to be maintained. More accurately, the child rules take care of their own state at all times, and the parent only needs to react to changes in the child state. Since no child state change occurs across a Save/Load operation, the parent does not need to become involved.

For rules which derive ConditionalScenarioBehavior, the majority of load/save logic is handled automatically. The only state information that such a rule should typically preserve is the instance-specific configuration data. The condition-monitor thread will be automatically restarted as required, and there is generally no need to distinguish between a first-startup and any subsequent startup.

= Spurious Events =
There are various events (typically script messages) that a rule may listen for in order to detect state changes. It is important to note that spurious events are often possible, and that an event handler should often be coupled with a condition check. As a specific example, the "ScenarioBehavior", "Touch" message typically indicates that a child state has changed, but the message may in fact be sent at any time. This message should prompt the rule to evaluate whether any state changes are necessary, but the rule should not simply assume that a state change is necessary without performing an evaluation.

Similarly, calls to a function such as Pause() may in some cases have no effect. For example, if a rule is already executing and its parent calls Pause(false), the rule should not pause, reset, or change state in any way at all. Similarly, if a rule is already paused and its parent calls Pause(true), the rule should not unpause, reset, fire any events, or otherwise change state in any way at all.

The short version is: do not assume that every event and every method call is supposed to achieve something meaningful. Check first, and if the event is meaningless to you then do nothing at all.

= Future Considerations =
Rules should base their functionality on the state flags such as the PAUSED state, rather than attempting to detect and vary their functionality based on the state of the game.

For example, we currently (in development builds) expose the rules editor in Driver for debugging purposes. This, or some mechanism like it, is likely to be included in public builds in the future. Rules should not assume that it is impossible to be reconfigured during gameplay. This will of course introduce some side effects, such as when an unpaused rule is modified during execution. It is the rule's responsibility to ensure that these side effects do not lead to script exceptions or to leaked state. For example, if a single thread is supposed to be running, reconfiguring the rule should not cause a second thread to run simultaneously. If a rule sniffs a target vehicle, and the target vehicle is redefined, then the rule should unsniff the original vehicle rather than now sniffing two vehicles.

Likewise, we may in future allow some form of partial state swap between Driver and Surveyor. Rules should not assume that it is impossible to change from any one game state or module to any other game state or module, just because it is not possible at the current time. APIs already exist to detect such state changes where necessary, and in most cases it's simply not necessary to care whether your rule is in Surveyor or Driver - you should act based on the PAUSED state instead. Rules should deal with the game state as they find it rather than assuming that certain states will not ever occur.

= Gotchas =
There are a few potential gotchas in the script environment that are worth considering when writing any non-trivial rule.

== Response Latency ==
Scripts tend to rely heavily on message passing and threading. In both cases, there is a delay between triggering a certain behavior (eg. posting an event, or calling a threaded function) and having the receiving code react. Other code may execute during this delay.

<code><pre>
// Calling this might be expected to start and then stop the thread; in reality it
// will likely simply start the thread and leave it running, because the message
// is sent prior to the wait() statement starting.
void DemonstrateBug1(void)
{
Pause(false);
Pause(true);
}

// In this case, we use a Sleep() statement to "ensure" that the thread has
// finished starting. This isn't actually reliable, but it works as long as the
// system isn't under too much load. We follow this up with a rapid pause-
// unpause sequence. As above, this doesn't work - the message is sent,
// then the function immediately checks whether the thread is still running
// (which it is) and thus the thread isn't restarted. The function completes,
// and finally the thread receives the message and exits.
void DemonstrateBug2(void)
{
Pause(false);
Sleep(1.0);
Pause(true);
Pause(false);
}

// Helper code for the above functions.
void Pause(bool bIsPaused)
{
if (bIsPaused)
{
PostMessage(me, "ThisRule", "Pause");
}
else if (!m_bIsThreadRunning)
{
m_bIsThreadRunning = true;
StartThread();
}
}
thread void StartThread(void)
{
while (true)
{
wait ()
{
on "ThisRule", "Pause":
break;
...
}
m_bIsThreadRunning = false;
}
</pre></code>

== Multiple Messages in Flight ==
It's possible to post multiple identical messages. This can be useful, but if you're expecting only one then it can be a source of errors.

In the following pseudocode, each call to SetProperties() will place an additional "Timer", "Tick" message into the cycle, effectively increasing the rate at which the IdleFunction is called. This will seem to be working for a single call to SetProperties(), which may be all that is called during a trivial testcase. It will probably give reasonable results for a few calls to SetProperties(), although if the function is time-sensitive then the results might be different to expectations. After a larger number of calls to SetProperties(), the object's message queue may become full, causing it to lose messages at random (perhaps the tick messages, or perhaps other unrelated messages that are more problematic).

<code><pre>
void Init(void)
{
inherited();

AddHandler(me, "Timer", "Tick", "IdleFunction");
}

void EnterIdleState(void)
{
IdleFunction();
}

void IdleFunction(void)
{
PostMessage(me, "Timer", "Tick", 1.0);
.. do something here ..
}

void SetProperties(Soup soup)
{
inherited(soup);

EnterIdleState();
}

</pre></code>

A similar problem can occur if you start new threads rather than post new messages.

== Thread Guard Variables ==
It's common to prevent a singleton thread from being started twice by using a boolean guard variable. Care must be taken to ensure that the guard variable is set and cleared at the correct locations, or they may be ineffective.

The following pseudocode demonstrates one such correct usage. The key points to note are:
* We set 'm_bIsThreadedFunctionRunning' prior to calling the threaded function. Setting it within the threaded function is too late; multiple threads might have already been started before the first thread reaches that point.
* We don't confuse whether the thread is actually running with whether we want the thread to be running. Once we ask a thread to start, we can't stop it starting. If we change our minds and want to stop it again, we must inform it in a way that it will realise after it finishes starting. In the worst-case scenario, we might flipflop on this multiple times before the thread actually starts.
* Similarly, we don't rely on messages to control the thread. Enqueuing a separate start or stop message with each StartThread()/StopThread() call might be possible, and we could clear any unwanted prior messages from the object's queue, but if the thread hasn't finished starting then it won't receive the messages anyway.
* We do rely on messages to wake the thread if it's waiting on messages, but we don't use those messages to imply any state - we just have it recheck the current state boolean to get the very latest info.
* We clear 'm_bIsThreadedFunctionRunning' once the decision to exit has become unconditional. At this point, even though the thread is technically still running, we'll have to start a new thread if we want the thread to continue running.

<code><pre>
bool m_bIsThreadedFunctionRunning = false;
bool m_bWantThreadedFunctionRunning = false;

void StartThread(void)
{
m_bWantThreadedFunctionRunning = true;

if (m_bIsThreadedFunctionRunning)
return;

m_bIsThreadedFunctionRunning = true;
ThreadedFunction();
}

void StopThread(void)
{
if (!m_bWantThreadedFunctionRunning)
return;

m_bWantThreadedFunctionRunning = false;
PostMessage(me, "Thread", "Touch");
}

thread void ThreadedFunction(void)
{
while (m_bWantThreadedFunctionRunning)
{
wait()
{
on "Thread", "Touch":
break;
.. whatever else..
}
}
m_bIsThreadedFunctionRunning = false;
}
</pre></code>

== Not Waiting For Messages ==
As seen above, it's possible for a thread to fail to receive posted messages because it wasn't waiting for them at the time. A more commonly problematic example follows.

<code><pre>
thread void MyThread(void)
{
wait ()
{
on "Some", "Condition":
HandleSomeCondition();
continue;
on "Thread", "Exit":
break;
}
}

void HandleSomeCondition(void)
{
wait ()
{
on "Some", "End-Condition":
break;
}
}
</pre></code>

In this example, the thread is waiting on both "Some", "Condition" and also "Thread", "Exit". Either one will be handled correctly assuming that the thread is already running at the time they are posted. Even if multiple are posted, the thread will simply queue them and run each in turn.

The problem occurs when HandleSomeCondition() is triggered and the thread begins waiting on "Some", "End-Condition". In this scenario, the thread is no longer waiting on "Thread", "Exit", and any attempt to post that message will simply be ignored. To reiterate: the message dispatch is NOT postponed until the function returns; the message is dropped entirely.

In many cases, the correct behaviour is to move HandleSomeCondition() to a new thread, although that may also carry gotchas that you will need to be careful of (eg. you'll probably want to terminate the second thread at the same time as the first one, and you may need to consider whether you want multiple of the second thread to run simultaneously or not).

== Performing Actions After Being Told to Stop ==
In many cases, you may wish to perform cleanup actions when stopping your rule. If your rule is threaded, this can easily become problematic.

Consider the following pseudocode example:

<code><pre>
void Pause(bool bIsPaused)
{
if (!bIsPaused && !m_bIsThreadRunning)
{
m_bIsThreadRunning = true;
MyThread();
}
}

thread void MyThread(void)
{
BeginRule();
while (!IsPaused())
{
Sleep(0.5);
UpdateRule();
}
EndRule();
m_bIsThreadRunning = false;
}
</pre></code>

There are three immediately obvious problems:

1. That BeginRule() is called when the thread starts, even if the rule has already been paused again.

2. That UpdateRule() will be called after each sleep, even if the rule was paused during the sleep.

3. That EndRule() will be called after the rule has been paused.

This is very problematic because it likely violates a core principles of the rules system: that rules will not undertake any meaningful behaviour when paused. All three functions may be called while the rule is paused, so unless the rule does nothing meaningful at all, this is a guaranteed violation.

The best approach to resolving this may depend on exactly what these functions do, but one possible solution is as follows:

<code><pre>
void Pause(bool bIsPaused)
{
if (bIsPaused)
{
if (m_bNeedsEndRule)
{
m_bNeedsEndRule = false;
EndRule();
}
}
else
{
if (!m_bNeedsEndRule)
{
BeginRule();
m_bNeedsEndRule = true;
}
if (!m_bIsThreadRunning)
{
m_bIsThreadRunning = true;
MyThread();
}
}
}

thread void MyThread(void)
{
while (!IsPaused())
{
UpdateRule();
Sleep(0.5);
}
m_bIsThreadRunning = false;
}
</pre></code>

== Failing to Inherit from ConditionalScenarioBehavior ==
This isn't really a separate gotcha, but it can't be stressed enough that your rule should inherit from ConditionalScenarioBehavior and should minimise the number of overrides to its default behavior. Apart from the "users expect things to work like this, so that's what you should do" argument, there are some much more compelling arguments for would-be rule developers:

1. Developing a rule with correct threading behavior is hard. Just have a look at some of the above gotchas. Were you already consciously aware of them all? If not, you're probably not ready to write your own rule which involves threading. ConditionalScenarioBehavior provides a polling thread mechanism that's already built, so you can reap the benefits of that approach without having to worry about whether you made any mistakes in the threading code.

2. Developing a rule with correct load/save behavior can be hard. Did you correctly restart your threads when necessary? Did you accidentally restart your threads when you weren't supposed to? Was there a message in flight during the save which you lost by reloading, and have you handled that loss correctly? ConditionalScenarioBehavior can help with a lot of that kind of thing, leaving you to worry about your rule-specific implementation only.

3. Developing a rule with correct child-rule-handling behavior can be really hard. You need to have a thorough understand of everything listed in this document, and you need to ensure that you don't make any mistakes which could cause your rule to violate any of the principles in this document, even in edge-case behaviours. Because this is the real world, you also need to handle child rules which don't necessarily follow the rules to the letter. ConditionalScenarioBehavior does all of this automatically with no effort on your part.

4. Inheriting from ConditionalScenarioBehavior means that many future issues can be fixed automatically by [[N3V Games]] without you having to update your rule. This includes both fixes to our own code (hey, we're human too) and also new changes to adapt our code to future requirements.

5. Inheriting from ConditionalScenarioBehavior typically means that there's a lot less semi-custom boilerplate in your rule, making your rule much simpler to read and maintain. This helps you while you're debugging your own rule, helps you when you're coming back in a year's time and wondering how it all worked, and perhaps helps others in the community if they need to update your rule in 10 years time after you've moved on from developing Trainz script code.

Session Rule Implementation

2018-11-27T17:10:40Z

Windwalkr: /* COMPLETE */

Session Rule Implementation

2018-11-27T17:05:41Z

Windwalkr: /* Ordered Execution of Children */

This page seeks to clearly define expected script behavior for [[KIND Scenariobehavior|Session Rule assets]]. This focuses specifically on correct behavior from the code perspective, rather than addressing how rules should be designed for best gameplay outcomes.

= Legacy Behavior Note =
Please note that many existing rules do not behave correctly as defined here. This is considered a bug in the individual session rules. [[N3V Games]] has a policy of updating session rules to behave correctly even where that may lead to changes of function in existing [[session]] assets. Where reasonable to achieve, emulation of the existing (buggy) behavior may occur for existing rule instances in existing sessions, however any newly created rule instances will use the corrected behavior.

These expectations were codified at the end of [[TS12]] development due to an increasing inability of session rules to work together resulting from the unpredictable nature of their responses to various common use-cases. The systems as a whole, including most of the core rules discussed in this document, have existed for far longer than this document. The document does not redefine any existing systems, but simply presents the only reasonable implementation approach possible if rules are to be expected to work properly in all use-cases. In some cases we also choose to mandate specific points of behavior relating to user expectations rather than technical necessities.

Certain additional API mechanisms were introduced alongside the development of this document, to allow better communication with session authors regarding the differences in behavior between certain types of rule. The correct usage for these mechanisms is also included in this document.

= The Rule Hierarchy =
All rules within a given session form a simple tree structure.

== Rule State Flags ==
Each rule in the tree may have certain associated state flagged, including a combination of the following:

=== PAUSED ===
The rule is currently paused, meaning that it does not affect the game world in any way and does not respond to any changes in the game world. The parent rule must cause the rule to become unpaused for the rule to have any effect. It is not correct behavior for a rule to unpause itself.

=== COMPLETE ===
This flag indicates that rule has fully completed its operation (including any child rule operations) and does not affect the game world in any way. This flag is set by the rule itself, not by an outside entity such as the parent. This state should not be changed while the rule is PAUSED.

Being COMPLETE does not imply being PAUSED. In many scenarios, the parent rule may respond to a child becoming COMPLETE by causing it to also become PAUSED, however this is certainly not guaranteed in all cases, and is not guaranteed to be immediate in the cases where it does happen.

The rule may optionally respond to specific changes in the game world by deflagging the COMPLETE status. For example, a rule which specifically implements a condition check may choose to become COMPLETE when that condition is met, but return to an incomplete state when the condition is no longer met (again, remembering that a change in either direction should only happen while the rule itself is not PAUSED).

When a rule's COMPLETE state changes, a "ScenarioBehavior", "Touch" message is sent '''(TBD: BY WHAT MECHANISM?)''' to its parent rule (if any), unless the parent is in the PAUSED state. This allows the parent to react to changes in its child rules' states. It is important to note that the message indicates a possible change which the parent may be interested in, but it is the parent rule's responsibility to determine whether the state change is worth reacting to.

=== WAS COMPLETE ===
This is typically set when a rule first becomes flagged as COMPLETE, and will stay set even if the rule later flags as incomplete. This can be used by a parent which only cares that the child rule has been flagged as COMPLETE at some point, rather than caring what its current completion status is.

=== DOES COMPLETE ===
This indicates whether the rule can ever reach the COMPLETE state. Its value is constant for a given rule configuration, and does not change based on the runtime rule state or other game state. Rules which are flagged as DOES COMPLETE are expected to become complete after some discreet operations are completed. Rules which are not flagged are expected to run indefinitely unless PAUSED by an external agent (such as the parent rule).

== Initial State ==
All rules are initially in the PAUSED state when in [[Surveyor]], and only become unpaused after gameplay begins in a [[Driver]] session. Since a PAUSED rule is not permitted to unpause itself, this is a stable state which will persist until the native code takes step to begin program flow.

== Top Level Rules ==
All rules at the top level (ie. rules which are not a child of any other rule) simultaneously become unpaused after the session has loaded into Driver. Some of these rules may take initial setup steps and then become COMPLETE. Some of these rules may begin monitoring for specific game conditions before taking any further action. Some of these rules may begin taking action immediately. The rules are not sequenced against each other in any way, and it is the session author's responsibility to ensure that this does not cause any conflicts.

== Scheduling ==
Since the script VM is a cooperatively-threaded environment, it is technically true that rule evaluation will occur in an ordered manner rather than truly simultaneously. However, no guarantees are made regarding the order in which the simultaneously-running rules will perform their checks or outcomes. Since rules may wait internally rather than fulfilling their entire purpose in an atomic operation, it is also not guaranteed that a first-running rule will fully complete before some other simultaneously-executing rule begins completion. In short, if order-of-execution is critical to the correct behavior of a session, then the order should be enforced by the session creator using the rule hierarchy rather than by making assumptions about execution order of simultaneously-running rules.

(Note: with the introduction of [[Asynchronous Route Streaming]], this is even more true than previously. What may have been a near-instantaneous operation in older builds may now require a wait of several seconds while the necessary data is streamed in.)

It is important to note that some conditional rules may partially or completely rely on a polling behavior to evaluate their conditions. (An example of partial reliance is a rule which waits for an event, but then evaluates a condition to clarify whether the event should be acted upon.) In these cases, it is possible that the condition can rapidly become true and then become false again without the rule responding. This results in an uncertainty as to whether the conditional rule will correctly detect a given instance of the condition. This type of scenario should be avoided completely where possible, and should most definitely be limited to outcomes that do not significantly affect gameplay.

For a hypothetical example, if the player's train speeds for 0.5sec, and a speeding check rule was implemented that polled every second, then the overspeed event may or may not trigger on any given occurrence. A session creator should not use this outcome as a failure condition, since some players may be able to speed without penalty, whereas other players would be penalised on the first attempt. A sensible solution in this case might be to increment a counter while speeding is detected, and only take action if the counter reaches a certain threshold. If the only penalty was a warning to the player which had no actual gameplay impact, then it might be acceptable to forgo this check and simply accept that some players will receive a warning where others may not.

==Child Rules==
As with all other rules, child rules (ie. those that have parent rules in the hierarchy) start out in the PAUSED state. They do not become unpaused until the parent is ready for the children to start operating. Exactly when this occurs depends on the specific parent rule, but the general flow is the same for all rules:

1. Parent rule becomes unpaused and begins operation.

2. Parent rule configures any necessary world state changes.

3. Parent rule optionally waits for a specific condition to occur.

4. Parent rule begins executing its children. This involves unpausing one or more of the children (as discussed below in "Parent Rule Styles").

5. Parent waits for its children to complete (as discussed below in "Parent Rule Styles") and then pauses the children.

6. Parent flags itself as COMPLETE.

This process allows program control flow to pass from a top-level rule, to its immediate children, to their immediate children, and so on. As the bottom-level children become complete, completion flows back to the higher level children until finally the top-level rules become COMPLETE.

It is worth noting that there is nothing special about a top-level rule being flagged as COMPLETE. This does not indicate an end-of-session or any other fundamental gameplay mode change. Since the pausing of rules on completion is handled by the parent rule (see step 5 above), the top-level rules never become PAUSED on completion.

==Parent Rule Styles==
There are a few common techniques with which parent rules interact with their children. Rules should always fit one of these descriptions. The vast majority of rules should follow either the "Does Not Support Children" style, or the "Ordered Execution of Children" style.

=== Does Not Support Children ===
The rule is incapable of supporting children and will always ignore them.

This is used for trivial rules which perform a set function and then become permanently COMPLETE. Such rules are not conditional and do not wait for any world state changes except those which they initiate internally.
The rule should be configured to validate and/or enforce that no child rules can be added.

=== Simultaneous Execution of Children ===
When the rule is ready to begin executing children, it unpauses all children simultaneously. The rule then waits for all children to flag as WAS COMPLETE. Once this is detected, the rule pauses all children and flags itself as COMPLETE.
This is used for rules which have a specific need to simultaneously execute children, such as the "Simultaneous List" rule.

The rule editor interface should be explicit that child rules will be executed simultaneously. Child rules should be tagged appropriately in the rule editor list to denote unordered execution.

=== Ordered Execution of Children ===
When the rule is ready to begin executing children, it iterates through the children in top-to-bottom order. If the child is flagged as WAS COMPLETE, the child is paused and iteration continues. If the child is not flagged as WAS COMPLETE, the child is unpaused and iteration ends. Whenever a child state change is detected, this process is repeated from the start. Once iteration passes over all children without leaving any child unpaused, the rule flags itself as COMPLETE.

This style is used for all rules which do not explicitly fall under one of the other styles described here. Almost all third-party rules will follow this style. Implementing one of the other styles without there being a fundamental requirement to do so is considered a programming error.

Rules which follow this style should derive from [[ConditionalScenarioBehavior]] in order to avoid re-implementing the control flow logic, as it is exceedingly complex to implement correctly. Any rules which do not derive from ConditionalScenarioBehavior should be accompanied by a clear explanation of the reasons that ConditionalScenarioBehavior is an unsuitable base class for the intended behavior. Rules which do derive from ConditionalScenarioBehavior should avoid complex overrides of the default logic.

Child rules should be tagged appropriately in the rule editor list to denote execution order.

=== Controlled Selection of a Single Child ===
When the rule is ready to begin executing children, it selects a single child and unpauses it. All other children remain paused. Once the selected child becomes flagged as WAS COMPLETE, the child is paused and the rule flags itself as COMPLETE.

This style is used where complex conditional selection of child rules is required. This can be used to implement an "if-else" logic flow, a "switch-case" logic flow, or the "Random List" rule. This style should not be used to implement a simple "if" logic flow, because that would unnecessarily restrict the rule to a single child where the "Ordered Execution of Children" style would provide the same functionality while allowing multiple children.
The rule editor interface should be very explicit about how the child rules will be selected. Child rules should be tagged appropriately in the rule editor list to avoid the user attempting to fit a child rule into the wrong role.

=== Custom Execution with Multiple Children ===
This style is used for very specific custom-purpose rules, such as a passenger station stop handler. Such rules should give a clear and complete explanation of their operation and their interaction with any child rules in the rule editor interface.

Individual child rules may be executed in an ad-hoc manner by the rule in response to changes in game state. Child rules may or may not be executed simultaneously and may or may not be executed repeatedly depending on the rule; any limitations or gotchas deriving from this should be carefully explained in the rule editor interface.

Child rules should be tagged appropriately in the rule editor list to avoid the user attempting to fit a child rule into the wrong role.

= Early Termination via Pause =
A rule must accept being paused by its parent at any time. This should cause the rule to cease any game state monitoring or other direct effects. The rule must pause all child rules immediately.

In cases where the rule is maintaining some reversible effect on the game world, pausing the rule should end this effect. For example, a rule which displays a message to the user should typically hide the message upon becoming paused, and a rule which causes a rain storm in a specific area should return the weather to normal upon becoming paused. Rules which make a single permanent change to the game world and then immediately flag as COMPLETE should not attempt to reverse the change upon becoming paused. Examples of these rules include configuration of the global weather conditions, or a rule which increments the player's score or penalty counter.

It is important to note that any pause is resumable, although the parent may not choose to take advantage of this. Pausing a rule followed by unpausing it should result in the rule continuing operation where it left off. The notes on Saving and Loading Driver Sessions (below) are worth considering when evaluating techniques for implementing pause.

= Early Termination via Internal Logic =
In some cases, a rule may begin executing child rules but then make an internal decision to abort execution. This typically occurs in conditional rules where the condition may be re-evaluated as false after it has already been evaluated as true. Such behavior should be made explicit in the rule editor interface and should usually be made optional by providing a checkbox.

There are in fact several possible behavioral variants affecting how condition-deflag is interpreted:
* Once the condition is flagged, the rule starts executing child rules and no further evaluation is performed. The rule eventually flags itself as COMPLETE and does not later deflag this.
* Once the condition is flagged, the rule starts executing child rules. If the condition becomes deflagged, the child rules are paused. If the condition becomes flagged again, the child rules are continued. Once the child rules have fully completed execution, the rule flags itself as COMPLETE and does not later deflag this.
* Once the condition is flagged, the rule starts executing child rules. If the condition becomes deflagged, the child rules are paused. If the condition becomes flagged again, the children are reset and execution starts anew. The rule flags itself as COMPLETE if all children successfully complete, but it will deflag if the condition deflags.
* Once the condition is flagged, the rule starts executing child rules. If the condition becomes deflagged, the child rules continue executing. If the condition becomes flagged again, the children are reset and execution starts anew. The rule will flag as COMPLETE if all children successfully complete, but it will deflag if the condition deflags.
* Once the condition is flagged, the rule starts executing child rules. The child rules continue execution with no regard for whether the condition changes between flagged or deflagged in either direction. If the condition transitions from deflagged to flagged again after the children have completed, the children are reset and execution starts anew. The rule will flag as COMPLETE if all children successfully complete, but it will deflag itself if the condition deflags.

The complexity here derives from the fact that it is not possible to use the same set of rules multiple times concurrently for different trigger conditions. For example, if a set of rules is used to give demerit points and provide user notifications, and those rules live under a single conditional check which determines whether a train is speeding, it may be difficult to define what should happen if two trains are detected as speeding at the same time, or if a train stops speeding while the notification process is still in progress. It is not always possible to achieve a perfect solution to tracking multiple objects using a single set of rules, but correct selection from the above behaviors can minimise the possibility of serious side-effects.

It is important to note that these behaviors describe how the rule reacts to internal condition checks. The rule's reaction to being paused by its parent is discussed above under "Early Termination via Pause" and is not affected by the description here.

In short, there are many ways of handling this, and the important thing is for your (parent) rule to clearly explain which approach it is going to use.

= Rule Reset =
A rule may be ''reset'' by its parent. This causes both the COMPLETE and WAS COMPLETE states to be deflagged. Individual rules may also react to the reset by modifying their internal state to forget past or present actions. Parent rules must also cause their children to be reset in turn.

This mechanism is used to permit rules to be used in a repeating scenario, such as responding to a condition which can occur multiple times, or in a repeating loop. At some point after a rule has become flagged as WAS COMPLETE, it will typically become paused and will not be unpaused again. If the rule is to be included in some repeating behavior, this would normally prevent the behavior from operating successfully after the first run through. To avoid this, the parent rule responsible for implementing the repeating behavior will ''reset'' all children when a repeat occurs. This effectively cleans the rules back to their initial state ready to perform their roles again.

It is important to note that a reset should cause the rule to return to its configured settings. For example, if a timer value is configured and is decremented during rule operation, the timer must be reset back to its initial value during rule reset.

It is important to note that there is no requirement to pause a rule prior to resetting it.

= Saving and Loading Driver Sessions =
For better or worse, the script VM does not persist across a save/load operation. This means that each rule must correctly save both its configuration state and its runtime state, and must correctly reload those such that the state after a save/load operation is indistinguishable from the original state. The following aspects of the script state must be considered:

* Member variables in the Rule instance.
* Which threads are running on the Rule instance, and where they are up to in the code flow.
* Local variables on the stack of each running thread.
* Non-persistent changes made to the state of other script objects (such as active 'sniff' statements).
* Script Messages which might be in flight at the time of save (these are not persisted, so the net effect is that they are simply deleted between the save and the load.)

Since the game state continues normal operation after a Save, no code flow or other behavioral changes should result from the Save operation itself. Instead, the Save operation (and the design of the rule as a whole) is responsible for ensuring that sufficient data is persisted in the save file such that the Load operation is able to restore to the correct running state.

The rule base class, ScenarioBehavior, is responsible for saving and loading the rule state flags (COMPLETE, PAUSED, WAS COMPLETE, etc.) A rule which was paused at Save time will still be paused after the Load. A rule which was complete at Save time will still be complete after the Load. During a Load operation, the rule should inherit the parent class' SetProperties() method so that these flags are correctly configured, then honor the paused state during the rest of the loading process.

It is rarely appropriate for an unpaused rule to simply restart execution from the beginning. Care must be taken to ensure that execution resumes from the point that it left off at the time of saving. This process can be simplified by keeping as much state as possible in the rule member variables at all times, and only keeping reconstructible temporary values on the stack. If the member variables are correctly stored and restored, this approach will allow the loading process to detect the runtime state of the rule and resume any necessary threads, which will in turn be able to jump forward to the correct area of the code based on the stored state.

Finally, the COMPLETE, WAS COMPLETE, and PAUSED flags on child rules should be honored. This is typically sufficient information to determine the running state of child rules, so no further state will generally need to be maintained. More accurately, the child rules take care of their own state at all times, and the parent only needs to react to changes in the child state. Since no child state change occurs across a Save/Load operation, the parent does not need to become involved.

For rules which derive ConditionalScenarioBehavior, the majority of load/save logic is handled automatically. The only state information that such a rule should typically preserve is the instance-specific configuration data. The condition-monitor thread will be automatically restarted as required, and there is generally no need to distinguish between a first-startup and any subsequent startup.

= Spurious Events =
There are various events (typically script messages) that a rule may listen for in order to detect state changes. It is important to note that spurious events are often possible, and that an event handler should often be coupled with a condition check. As a specific example, the "ScenarioBehavior", "Touch" message typically indicates that a child state has changed, but the message may in fact be sent at any time. This message should prompt the rule to evaluate whether any state changes are necessary, but the rule should not simply assume that a state change is necessary without performing an evaluation.

Similarly, calls to a function such as Pause() may in some cases have no effect. For example, if a rule is already executing and its parent calls Pause(false), the rule should not pause, reset, or change state in any way at all. Similarly, if a rule is already paused and its parent calls Pause(true), the rule should not unpause, reset, fire any events, or otherwise change state in any way at all.

The short version is: do not assume that every event and every method call is supposed to achieve something meaningful. Check first, and if the event is meaningless to you then do nothing at all.

= Future Considerations =
Rules should base their functionality on the state flags such as the PAUSED state, rather than attempting to detect and vary their functionality based on the state of the game.

For example, we currently (in development builds) expose the rules editor in Driver for debugging purposes. This, or some mechanism like it, is likely to be included in public builds in the future. Rules should not assume that it is impossible to be reconfigured during gameplay. This will of course introduce some side effects, such as when an unpaused rule is modified during execution. It is the rule's responsibility to ensure that these side effects do not lead to script exceptions or to leaked state. For example, if a single thread is supposed to be running, reconfiguring the rule should not cause a second thread to run simultaneously. If a rule sniffs a target vehicle, and the target vehicle is redefined, then the rule should unsniff the original vehicle rather than now sniffing two vehicles.

Likewise, we may in future allow some form of partial state swap between Driver and Surveyor. Rules should not assume that it is impossible to change from any one game state or module to any other game state or module, just because it is not possible at the current time. APIs already exist to detect such state changes where necessary, and in most cases it's simply not necessary to care whether your rule is in Surveyor or Driver - you should act based on the PAUSED state instead. Rules should deal with the game state as they find it rather than assuming that certain states will not ever occur.

= Gotchas =
There are a few potential gotchas in the script environment that are worth considering when writing any non-trivial rule.

== Response Latency ==
Scripts tend to rely heavily on message passing and threading. In both cases, there is a delay between triggering a certain behavior (eg. posting an event, or calling a threaded function) and having the receiving code react. Other code may execute during this delay.

<code><pre>
// Calling this might be expected to start and then stop the thread; in reality it
// will likely simply start the thread and leave it running, because the message
// is sent prior to the wait() statement starting.
void DemonstrateBug1(void)
{
Pause(false);
Pause(true);
}

// In this case, we use a Sleep() statement to "ensure" that the thread has
// finished starting. This isn't actually reliable, but it works as long as the
// system isn't under too much load. We follow this up with a rapid pause-
// unpause sequence. As above, this doesn't work - the message is sent,
// then the function immediately checks whether the thread is still running
// (which it is) and thus the thread isn't restarted. The function completes,
// and finally the thread receives the message and exits.
void DemonstrateBug2(void)
{
Pause(false);
Sleep(1.0);
Pause(true);
Pause(false);
}

// Helper code for the above functions.
void Pause(bool bIsPaused)
{
if (bIsPaused)
{
PostMessage(me, "ThisRule", "Pause");
}
else if (!m_bIsThreadRunning)
{
m_bIsThreadRunning = true;
StartThread();
}
}
thread void StartThread(void)
{
while (true)
{
wait ()
{
on "ThisRule", "Pause":
break;
...
}
m_bIsThreadRunning = false;
}
</pre></code>

== Multiple Messages in Flight ==
It's possible to post multiple identical messages. This can be useful, but if you're expecting only one then it can be a source of errors.

In the following pseudocode, each call to SetProperties() will place an additional "Timer", "Tick" message into the cycle, effectively increasing the rate at which the IdleFunction is called. This will seem to be working for a single call to SetProperties(), which may be all that is called during a trivial testcase. It will probably give reasonable results for a few calls to SetProperties(), although if the function is time-sensitive then the results might be different to expectations. After a larger number of calls to SetProperties(), the object's message queue may become full, causing it to lose messages at random (perhaps the tick messages, or perhaps other unrelated messages that are more problematic).

<code><pre>
void Init(void)
{
inherited();

AddHandler(me, "Timer", "Tick", "IdleFunction");
}

void EnterIdleState(void)
{
IdleFunction();
}

void IdleFunction(void)
{
PostMessage(me, "Timer", "Tick", 1.0);
.. do something here ..
}

void SetProperties(Soup soup)
{
inherited(soup);

EnterIdleState();
}

</pre></code>

A similar problem can occur if you start new threads rather than post new messages.

== Thread Guard Variables ==
It's common to prevent a singleton thread from being started twice by using a boolean guard variable. Care must be taken to ensure that the guard variable is set and cleared at the correct locations, or they may be ineffective.

The following pseudocode demonstrates one such correct usage. The key points to note are:
* We set 'm_bIsThreadedFunctionRunning' prior to calling the threaded function. Setting it within the threaded function is too late; multiple threads might have already been started before the first thread reaches that point.
* We don't confuse whether the thread is actually running with whether we want the thread to be running. Once we ask a thread to start, we can't stop it starting. If we change our minds and want to stop it again, we must inform it in a way that it will realise after it finishes starting. In the worst-case scenario, we might flipflop on this multiple times before the thread actually starts.
* Similarly, we don't rely on messages to control the thread. Enqueuing a separate start or stop message with each StartThread()/StopThread() call might be possible, and we could clear any unwanted prior messages from the object's queue, but if the thread hasn't finished starting then it won't receive the messages anyway.
* We do rely on messages to wake the thread if it's waiting on messages, but we don't use those messages to imply any state - we just have it recheck the current state boolean to get the very latest info.
* We clear 'm_bIsThreadedFunctionRunning' once the decision to exit has become unconditional. At this point, even though the thread is technically still running, we'll have to start a new thread if we want the thread to continue running.

<code><pre>
bool m_bIsThreadedFunctionRunning = false;
bool m_bWantThreadedFunctionRunning = false;

void StartThread(void)
{
m_bWantThreadedFunctionRunning = true;

if (m_bIsThreadedFunctionRunning)
return;

m_bIsThreadedFunctionRunning = true;
ThreadedFunction();
}

void StopThread(void)
{
if (!m_bWantThreadedFunctionRunning)
return;

m_bWantThreadedFunctionRunning = false;
PostMessage(me, "Thread", "Touch");
}

thread void ThreadedFunction(void)
{
while (m_bWantThreadedFunctionRunning)
{
wait()
{
on "Thread", "Touch":
break;
.. whatever else..
}
}
m_bIsThreadedFunctionRunning = false;
}
</pre></code>

== Not Waiting For Messages ==
As seen above, it's possible for a thread to fail to receive posted messages because it wasn't waiting for them at the time. A more commonly problematic example follows.

<code><pre>
thread void MyThread(void)
{
wait ()
{
on "Some", "Condition":
HandleSomeCondition();
continue;
on "Thread", "Exit":
break;
}
}

void HandleSomeCondition(void)
{
wait ()
{
on "Some", "End-Condition":
break;
}
}
</pre></code>

In this example, the thread is waiting on both "Some", "Condition" and also "Thread", "Exit". Either one will be handled correctly assuming that the thread is already running at the time they are posted. Even if multiple are posted, the thread will simply queue them and run each in turn.

The problem occurs when HandleSomeCondition() is triggered and the thread begins waiting on "Some", "End-Condition". In this scenario, the thread is no longer waiting on "Thread", "Exit", and any attempt to post that message will simply be ignored. To reiterate: the message dispatch is NOT postponed until the function returns; the message is dropped entirely.

In many cases, the correct behaviour is to move HandleSomeCondition() to a new thread, although that may also carry gotchas that you will need to be careful of (eg. you'll probably want to terminate the second thread at the same time as the first one, and you may need to consider whether you want multiple of the second thread to run simultaneously or not).

== Performing Actions After Being Told to Stop ==
In many cases, you may wish to perform cleanup actions when stopping your rule. If your rule is threaded, this can easily become problematic.

Consider the following pseudocode example:

<code><pre>
void Pause(bool bIsPaused)
{
if (!bIsPaused && !m_bIsThreadRunning)
{
m_bIsThreadRunning = true;
MyThread();
}
}

thread void MyThread(void)
{
BeginRule();
while (!IsPaused())
{
Sleep(0.5);
UpdateRule();
}
EndRule();
m_bIsThreadRunning = false;
}
</pre></code>

There are three immediately obvious problems:

1. That BeginRule() is called when the thread starts, even if the rule has already been paused again.

2. That UpdateRule() will be called after each sleep, even if the rule was paused during the sleep.

3. That EndRule() will be called after the rule has been paused.

This is very problematic because it likely violates a core principles of the rules system: that rules will not undertake any meaningful behaviour when paused. All three functions may be called while the rule is paused, so unless the rule does nothing meaningful at all, this is a guaranteed violation.

The best approach to resolving this may depend on exactly what these functions do, but one possible solution is as follows:

<code><pre>
void Pause(bool bIsPaused)
{
if (bIsPaused)
{
if (m_bNeedsEndRule)
{
m_bNeedsEndRule = false;
EndRule();
}
}
else
{
if (!m_bNeedsEndRule)
{
BeginRule();
m_bNeedsEndRule = true;
}
if (!m_bIsThreadRunning)
{
m_bIsThreadRunning = true;
MyThread();
}
}
}

thread void MyThread(void)
{
while (!IsPaused())
{
UpdateRule();
Sleep(0.5);
}
m_bIsThreadRunning = false;
}
</pre></code>

Session Rule Implementation

2018-11-27T17:04:47Z

Windwalkr: /* Child Rules */

This page seeks to clearly define expected script behavior for [[KIND Scenariobehavior|Session Rule assets]]. This focuses specifically on correct behavior from the code perspective, rather than addressing how rules should be designed for best gameplay outcomes.

= Legacy Behavior Note =
Please note that many existing rules do not behave correctly as defined here. This is considered a bug in the individual session rules. [[N3V Games]] has a policy of updating session rules to behave correctly even where that may lead to changes of function in existing [[session]] assets. Where reasonable to achieve, emulation of the existing (buggy) behavior may occur for existing rule instances in existing sessions, however any newly created rule instances will use the corrected behavior.

These expectations were codified at the end of [[TS12]] development due to an increasing inability of session rules to work together resulting from the unpredictable nature of their responses to various common use-cases. The systems as a whole, including most of the core rules discussed in this document, have existed for far longer than this document. The document does not redefine any existing systems, but simply presents the only reasonable implementation approach possible if rules are to be expected to work properly in all use-cases. In some cases we also choose to mandate specific points of behavior relating to user expectations rather than technical necessities.

Certain additional API mechanisms were introduced alongside the development of this document, to allow better communication with session authors regarding the differences in behavior between certain types of rule. The correct usage for these mechanisms is also included in this document.

= The Rule Hierarchy =
All rules within a given session form a simple tree structure.

== Rule State Flags ==
Each rule in the tree may have certain associated state flagged, including a combination of the following:

=== PAUSED ===
The rule is currently paused, meaning that it does not affect the game world in any way and does not respond to any changes in the game world. The parent rule must cause the rule to become unpaused for the rule to have any effect. It is not correct behavior for a rule to unpause itself.

=== COMPLETE ===
This flag indicates that rule has fully completed its operation (including any child rule operations) and does not affect the game world in any way. This flag is set by the rule itself, not by an outside entity such as the parent. This state should not be changed while the rule is PAUSED.

Being COMPLETE does not imply being PAUSED. In many scenarios, the parent rule may respond to a child becoming COMPLETE by causing it to also become PAUSED, however this is certainly not guaranteed in all cases, and is not guaranteed to be immediate in the cases where it does happen.

The rule may optionally respond to specific changes in the game world by deflagging the COMPLETE status. For example, a rule which specifically implements a condition check may choose to become COMPLETE when that condition is met, but return to an incomplete state when the condition is no longer met (again, remembering that a change in either direction should only happen while the rule itself is not PAUSED).

When a rule's COMPLETE state changes, a "ScenarioBehavior", "Touch" message is sent '''(TBD: BY WHAT MECHANISM?)''' to its parent rule (if any), unless the parent is in the PAUSED state. This allows the parent to react to changes in its child rules' states. It is important to note that the message indicates a possible change which the parent may be interested in, but it is the parent rule's responsibility to determine whether the state change is worth reacting to.

=== WAS COMPLETE ===
This is typically set when a rule first becomes flagged as COMPLETE, and will stay set even if the rule later flags as incomplete. This can be used by a parent which only cares that the child rule has been flagged as COMPLETE at some point, rather than caring what its current completion status is.

=== DOES COMPLETE ===
This indicates whether the rule can ever reach the COMPLETE state. Its value is constant for a given rule configuration, and does not change based on the runtime rule state or other game state. Rules which are flagged as DOES COMPLETE are expected to become complete after some discreet operations are completed. Rules which are not flagged are expected to run indefinitely unless PAUSED by an external agent (such as the parent rule).

== Initial State ==
All rules are initially in the PAUSED state when in [[Surveyor]], and only become unpaused after gameplay begins in a [[Driver]] session. Since a PAUSED rule is not permitted to unpause itself, this is a stable state which will persist until the native code takes step to begin program flow.

== Top Level Rules ==
All rules at the top level (ie. rules which are not a child of any other rule) simultaneously become unpaused after the session has loaded into Driver. Some of these rules may take initial setup steps and then become COMPLETE. Some of these rules may begin monitoring for specific game conditions before taking any further action. Some of these rules may begin taking action immediately. The rules are not sequenced against each other in any way, and it is the session author's responsibility to ensure that this does not cause any conflicts.

== Scheduling ==
Since the script VM is a cooperatively-threaded environment, it is technically true that rule evaluation will occur in an ordered manner rather than truly simultaneously. However, no guarantees are made regarding the order in which the simultaneously-running rules will perform their checks or outcomes. Since rules may wait internally rather than fulfilling their entire purpose in an atomic operation, it is also not guaranteed that a first-running rule will fully complete before some other simultaneously-executing rule begins completion. In short, if order-of-execution is critical to the correct behavior of a session, then the order should be enforced by the session creator using the rule hierarchy rather than by making assumptions about execution order of simultaneously-running rules.

(Note: with the introduction of [[Asynchronous Route Streaming]], this is even more true than previously. What may have been a near-instantaneous operation in older builds may now require a wait of several seconds while the necessary data is streamed in.)

It is important to note that some conditional rules may partially or completely rely on a polling behavior to evaluate their conditions. (An example of partial reliance is a rule which waits for an event, but then evaluates a condition to clarify whether the event should be acted upon.) In these cases, it is possible that the condition can rapidly become true and then become false again without the rule responding. This results in an uncertainty as to whether the conditional rule will correctly detect a given instance of the condition. This type of scenario should be avoided completely where possible, and should most definitely be limited to outcomes that do not significantly affect gameplay.

For a hypothetical example, if the player's train speeds for 0.5sec, and a speeding check rule was implemented that polled every second, then the overspeed event may or may not trigger on any given occurrence. A session creator should not use this outcome as a failure condition, since some players may be able to speed without penalty, whereas other players would be penalised on the first attempt. A sensible solution in this case might be to increment a counter while speeding is detected, and only take action if the counter reaches a certain threshold. If the only penalty was a warning to the player which had no actual gameplay impact, then it might be acceptable to forgo this check and simply accept that some players will receive a warning where others may not.

==Child Rules==
As with all other rules, child rules (ie. those that have parent rules in the hierarchy) start out in the PAUSED state. They do not become unpaused until the parent is ready for the children to start operating. Exactly when this occurs depends on the specific parent rule, but the general flow is the same for all rules:

1. Parent rule becomes unpaused and begins operation.

2. Parent rule configures any necessary world state changes.

3. Parent rule optionally waits for a specific condition to occur.

4. Parent rule begins executing its children. This involves unpausing one or more of the children (as discussed below in "Parent Rule Styles").

5. Parent waits for its children to complete (as discussed below in "Parent Rule Styles") and then pauses the children.

6. Parent flags itself as COMPLETE.

This process allows program control flow to pass from a top-level rule, to its immediate children, to their immediate children, and so on. As the bottom-level children become complete, completion flows back to the higher level children until finally the top-level rules become COMPLETE.

It is worth noting that there is nothing special about a top-level rule being flagged as COMPLETE. This does not indicate an end-of-session or any other fundamental gameplay mode change. Since the pausing of rules on completion is handled by the parent rule (see step 5 above), the top-level rules never become PAUSED on completion.

==Parent Rule Styles==
There are a few common techniques with which parent rules interact with their children. Rules should always fit one of these descriptions. The vast majority of rules should follow either the "Does Not Support Children" style, or the "Ordered Execution of Children" style.

=== Does Not Support Children ===
The rule is incapable of supporting children and will always ignore them.

This is used for trivial rules which perform a set function and then become permanently COMPLETE. Such rules are not conditional and do not wait for any world state changes except those which they initiate internally.
The rule should be configured to validate and/or enforce that no child rules can be added.

=== Simultaneous Execution of Children ===
When the rule is ready to begin executing children, it unpauses all children simultaneously. The rule then waits for all children to flag as WAS COMPLETE. Once this is detected, the rule pauses all children and flags itself as COMPLETE.
This is used for rules which have a specific need to simultaneously execute children, such as the "Simultaneous List" rule.

The rule editor interface should be explicit that child rules will be executed simultaneously. Child rules should be tagged appropriately in the rule editor list to denote unordered execution.

=== Ordered Execution of Children ===
When the rule is ready to begin executing children, it iterates through the children in top-to-bottom order. If the child is flagged as WAS COMPLETE, the child is paused and iteration continues. If the child is not flagged as WAS COMPLETE, the child is unpaused and iteration ends. Whenever a child state change is detected, this process is repeated from the start. Once iteration passes over all children without leaving any child unpaused, the rule flags itself as COMPLETE.

This style is used for all rules which do not explicitly fall under one of the other styles described here. Almost all third-party rules will follow this style. Implementing one of the other styles without there being a fundamental requirement to do so is considered a programming error.

Rules which follow this style should derive from ConditionalScenarioBehavior in order to avoid re-implementing the control flow logic, as it is exceedingly complex to implement correctly. Any rules which do not derive from ConditionalScenarioBehavior should be accompanied by a clear explanation of the reasons that ConditionalScenarioBehavior is an unsuitable base class for the intended behavior. Rules which do derive from ConditionalScenarioBehavior should avoid complex overrides of the default logic.

Child rules should be tagged appropriately in the rule editor list to denote execution order.

=== Controlled Selection of a Single Child ===
When the rule is ready to begin executing children, it selects a single child and unpauses it. All other children remain paused. Once the selected child becomes flagged as WAS COMPLETE, the child is paused and the rule flags itself as COMPLETE.

This style is used where complex conditional selection of child rules is required. This can be used to implement an "if-else" logic flow, a "switch-case" logic flow, or the "Random List" rule. This style should not be used to implement a simple "if" logic flow, because that would unnecessarily restrict the rule to a single child where the "Ordered Execution of Children" style would provide the same functionality while allowing multiple children.
The rule editor interface should be very explicit about how the child rules will be selected. Child rules should be tagged appropriately in the rule editor list to avoid the user attempting to fit a child rule into the wrong role.

=== Custom Execution with Multiple Children ===
This style is used for very specific custom-purpose rules, such as a passenger station stop handler. Such rules should give a clear and complete explanation of their operation and their interaction with any child rules in the rule editor interface.

Individual child rules may be executed in an ad-hoc manner by the rule in response to changes in game state. Child rules may or may not be executed simultaneously and may or may not be executed repeatedly depending on the rule; any limitations or gotchas deriving from this should be carefully explained in the rule editor interface.

Child rules should be tagged appropriately in the rule editor list to avoid the user attempting to fit a child rule into the wrong role.

= Early Termination via Pause =
A rule must accept being paused by its parent at any time. This should cause the rule to cease any game state monitoring or other direct effects. The rule must pause all child rules immediately.

In cases where the rule is maintaining some reversible effect on the game world, pausing the rule should end this effect. For example, a rule which displays a message to the user should typically hide the message upon becoming paused, and a rule which causes a rain storm in a specific area should return the weather to normal upon becoming paused. Rules which make a single permanent change to the game world and then immediately flag as COMPLETE should not attempt to reverse the change upon becoming paused. Examples of these rules include configuration of the global weather conditions, or a rule which increments the player's score or penalty counter.

It is important to note that any pause is resumable, although the parent may not choose to take advantage of this. Pausing a rule followed by unpausing it should result in the rule continuing operation where it left off. The notes on Saving and Loading Driver Sessions (below) are worth considering when evaluating techniques for implementing pause.

= Early Termination via Internal Logic =
In some cases, a rule may begin executing child rules but then make an internal decision to abort execution. This typically occurs in conditional rules where the condition may be re-evaluated as false after it has already been evaluated as true. Such behavior should be made explicit in the rule editor interface and should usually be made optional by providing a checkbox.

There are in fact several possible behavioral variants affecting how condition-deflag is interpreted:
* Once the condition is flagged, the rule starts executing child rules and no further evaluation is performed. The rule eventually flags itself as COMPLETE and does not later deflag this.
* Once the condition is flagged, the rule starts executing child rules. If the condition becomes deflagged, the child rules are paused. If the condition becomes flagged again, the child rules are continued. Once the child rules have fully completed execution, the rule flags itself as COMPLETE and does not later deflag this.
* Once the condition is flagged, the rule starts executing child rules. If the condition becomes deflagged, the child rules are paused. If the condition becomes flagged again, the children are reset and execution starts anew. The rule flags itself as COMPLETE if all children successfully complete, but it will deflag if the condition deflags.
* Once the condition is flagged, the rule starts executing child rules. If the condition becomes deflagged, the child rules continue executing. If the condition becomes flagged again, the children are reset and execution starts anew. The rule will flag as COMPLETE if all children successfully complete, but it will deflag if the condition deflags.
* Once the condition is flagged, the rule starts executing child rules. The child rules continue execution with no regard for whether the condition changes between flagged or deflagged in either direction. If the condition transitions from deflagged to flagged again after the children have completed, the children are reset and execution starts anew. The rule will flag as COMPLETE if all children successfully complete, but it will deflag itself if the condition deflags.

The complexity here derives from the fact that it is not possible to use the same set of rules multiple times concurrently for different trigger conditions. For example, if a set of rules is used to give demerit points and provide user notifications, and those rules live under a single conditional check which determines whether a train is speeding, it may be difficult to define what should happen if two trains are detected as speeding at the same time, or if a train stops speeding while the notification process is still in progress. It is not always possible to achieve a perfect solution to tracking multiple objects using a single set of rules, but correct selection from the above behaviors can minimise the possibility of serious side-effects.

It is important to note that these behaviors describe how the rule reacts to internal condition checks. The rule's reaction to being paused by its parent is discussed above under "Early Termination via Pause" and is not affected by the description here.

In short, there are many ways of handling this, and the important thing is for your (parent) rule to clearly explain which approach it is going to use.

= Rule Reset =
A rule may be ''reset'' by its parent. This causes both the COMPLETE and WAS COMPLETE states to be deflagged. Individual rules may also react to the reset by modifying their internal state to forget past or present actions. Parent rules must also cause their children to be reset in turn.

This mechanism is used to permit rules to be used in a repeating scenario, such as responding to a condition which can occur multiple times, or in a repeating loop. At some point after a rule has become flagged as WAS COMPLETE, it will typically become paused and will not be unpaused again. If the rule is to be included in some repeating behavior, this would normally prevent the behavior from operating successfully after the first run through. To avoid this, the parent rule responsible for implementing the repeating behavior will ''reset'' all children when a repeat occurs. This effectively cleans the rules back to their initial state ready to perform their roles again.

It is important to note that a reset should cause the rule to return to its configured settings. For example, if a timer value is configured and is decremented during rule operation, the timer must be reset back to its initial value during rule reset.

It is important to note that there is no requirement to pause a rule prior to resetting it.

= Saving and Loading Driver Sessions =
For better or worse, the script VM does not persist across a save/load operation. This means that each rule must correctly save both its configuration state and its runtime state, and must correctly reload those such that the state after a save/load operation is indistinguishable from the original state. The following aspects of the script state must be considered:

* Member variables in the Rule instance.
* Which threads are running on the Rule instance, and where they are up to in the code flow.
* Local variables on the stack of each running thread.
* Non-persistent changes made to the state of other script objects (such as active 'sniff' statements).
* Script Messages which might be in flight at the time of save (these are not persisted, so the net effect is that they are simply deleted between the save and the load.)

Since the game state continues normal operation after a Save, no code flow or other behavioral changes should result from the Save operation itself. Instead, the Save operation (and the design of the rule as a whole) is responsible for ensuring that sufficient data is persisted in the save file such that the Load operation is able to restore to the correct running state.

The rule base class, ScenarioBehavior, is responsible for saving and loading the rule state flags (COMPLETE, PAUSED, WAS COMPLETE, etc.) A rule which was paused at Save time will still be paused after the Load. A rule which was complete at Save time will still be complete after the Load. During a Load operation, the rule should inherit the parent class' SetProperties() method so that these flags are correctly configured, then honor the paused state during the rest of the loading process.

It is rarely appropriate for an unpaused rule to simply restart execution from the beginning. Care must be taken to ensure that execution resumes from the point that it left off at the time of saving. This process can be simplified by keeping as much state as possible in the rule member variables at all times, and only keeping reconstructible temporary values on the stack. If the member variables are correctly stored and restored, this approach will allow the loading process to detect the runtime state of the rule and resume any necessary threads, which will in turn be able to jump forward to the correct area of the code based on the stored state.

Finally, the COMPLETE, WAS COMPLETE, and PAUSED flags on child rules should be honored. This is typically sufficient information to determine the running state of child rules, so no further state will generally need to be maintained. More accurately, the child rules take care of their own state at all times, and the parent only needs to react to changes in the child state. Since no child state change occurs across a Save/Load operation, the parent does not need to become involved.

For rules which derive ConditionalScenarioBehavior, the majority of load/save logic is handled automatically. The only state information that such a rule should typically preserve is the instance-specific configuration data. The condition-monitor thread will be automatically restarted as required, and there is generally no need to distinguish between a first-startup and any subsequent startup.

= Spurious Events =
There are various events (typically script messages) that a rule may listen for in order to detect state changes. It is important to note that spurious events are often possible, and that an event handler should often be coupled with a condition check. As a specific example, the "ScenarioBehavior", "Touch" message typically indicates that a child state has changed, but the message may in fact be sent at any time. This message should prompt the rule to evaluate whether any state changes are necessary, but the rule should not simply assume that a state change is necessary without performing an evaluation.

Similarly, calls to a function such as Pause() may in some cases have no effect. For example, if a rule is already executing and its parent calls Pause(false), the rule should not pause, reset, or change state in any way at all. Similarly, if a rule is already paused and its parent calls Pause(true), the rule should not unpause, reset, fire any events, or otherwise change state in any way at all.

The short version is: do not assume that every event and every method call is supposed to achieve something meaningful. Check first, and if the event is meaningless to you then do nothing at all.

= Future Considerations =
Rules should base their functionality on the state flags such as the PAUSED state, rather than attempting to detect and vary their functionality based on the state of the game.

For example, we currently (in development builds) expose the rules editor in Driver for debugging purposes. This, or some mechanism like it, is likely to be included in public builds in the future. Rules should not assume that it is impossible to be reconfigured during gameplay. This will of course introduce some side effects, such as when an unpaused rule is modified during execution. It is the rule's responsibility to ensure that these side effects do not lead to script exceptions or to leaked state. For example, if a single thread is supposed to be running, reconfiguring the rule should not cause a second thread to run simultaneously. If a rule sniffs a target vehicle, and the target vehicle is redefined, then the rule should unsniff the original vehicle rather than now sniffing two vehicles.

Likewise, we may in future allow some form of partial state swap between Driver and Surveyor. Rules should not assume that it is impossible to change from any one game state or module to any other game state or module, just because it is not possible at the current time. APIs already exist to detect such state changes where necessary, and in most cases it's simply not necessary to care whether your rule is in Surveyor or Driver - you should act based on the PAUSED state instead. Rules should deal with the game state as they find it rather than assuming that certain states will not ever occur.

= Gotchas =
There are a few potential gotchas in the script environment that are worth considering when writing any non-trivial rule.

== Response Latency ==
Scripts tend to rely heavily on message passing and threading. In both cases, there is a delay between triggering a certain behavior (eg. posting an event, or calling a threaded function) and having the receiving code react. Other code may execute during this delay.

<code><pre>
// Calling this might be expected to start and then stop the thread; in reality it
// will likely simply start the thread and leave it running, because the message
// is sent prior to the wait() statement starting.
void DemonstrateBug1(void)
{
Pause(false);
Pause(true);
}

// In this case, we use a Sleep() statement to "ensure" that the thread has
// finished starting. This isn't actually reliable, but it works as long as the
// system isn't under too much load. We follow this up with a rapid pause-
// unpause sequence. As above, this doesn't work - the message is sent,
// then the function immediately checks whether the thread is still running
// (which it is) and thus the thread isn't restarted. The function completes,
// and finally the thread receives the message and exits.
void DemonstrateBug2(void)
{
Pause(false);
Sleep(1.0);
Pause(true);
Pause(false);
}

// Helper code for the above functions.
void Pause(bool bIsPaused)
{
if (bIsPaused)
{
PostMessage(me, "ThisRule", "Pause");
}
else if (!m_bIsThreadRunning)
{
m_bIsThreadRunning = true;
StartThread();
}
}
thread void StartThread(void)
{
while (true)
{
wait ()
{
on "ThisRule", "Pause":
break;
...
}
m_bIsThreadRunning = false;
}
</pre></code>

== Multiple Messages in Flight ==
It's possible to post multiple identical messages. This can be useful, but if you're expecting only one then it can be a source of errors.

In the following pseudocode, each call to SetProperties() will place an additional "Timer", "Tick" message into the cycle, effectively increasing the rate at which the IdleFunction is called. This will seem to be working for a single call to SetProperties(), which may be all that is called during a trivial testcase. It will probably give reasonable results for a few calls to SetProperties(), although if the function is time-sensitive then the results might be different to expectations. After a larger number of calls to SetProperties(), the object's message queue may become full, causing it to lose messages at random (perhaps the tick messages, or perhaps other unrelated messages that are more problematic).

<code><pre>
void Init(void)
{
inherited();

AddHandler(me, "Timer", "Tick", "IdleFunction");
}

void EnterIdleState(void)
{
IdleFunction();
}

void IdleFunction(void)
{
PostMessage(me, "Timer", "Tick", 1.0);
.. do something here ..
}

void SetProperties(Soup soup)
{
inherited(soup);

EnterIdleState();
}

</pre></code>

A similar problem can occur if you start new threads rather than post new messages.

== Thread Guard Variables ==
It's common to prevent a singleton thread from being started twice by using a boolean guard variable. Care must be taken to ensure that the guard variable is set and cleared at the correct locations, or they may be ineffective.

The following pseudocode demonstrates one such correct usage. The key points to note are:
* We set 'm_bIsThreadedFunctionRunning' prior to calling the threaded function. Setting it within the threaded function is too late; multiple threads might have already been started before the first thread reaches that point.
* We don't confuse whether the thread is actually running with whether we want the thread to be running. Once we ask a thread to start, we can't stop it starting. If we change our minds and want to stop it again, we must inform it in a way that it will realise after it finishes starting. In the worst-case scenario, we might flipflop on this multiple times before the thread actually starts.
* Similarly, we don't rely on messages to control the thread. Enqueuing a separate start or stop message with each StartThread()/StopThread() call might be possible, and we could clear any unwanted prior messages from the object's queue, but if the thread hasn't finished starting then it won't receive the messages anyway.
* We do rely on messages to wake the thread if it's waiting on messages, but we don't use those messages to imply any state - we just have it recheck the current state boolean to get the very latest info.
* We clear 'm_bIsThreadedFunctionRunning' once the decision to exit has become unconditional. At this point, even though the thread is technically still running, we'll have to start a new thread if we want the thread to continue running.

<code><pre>
bool m_bIsThreadedFunctionRunning = false;
bool m_bWantThreadedFunctionRunning = false;

void StartThread(void)
{
m_bWantThreadedFunctionRunning = true;

if (m_bIsThreadedFunctionRunning)
return;

m_bIsThreadedFunctionRunning = true;
ThreadedFunction();
}

void StopThread(void)
{
if (!m_bWantThreadedFunctionRunning)
return;

m_bWantThreadedFunctionRunning = false;
PostMessage(me, "Thread", "Touch");
}

thread void ThreadedFunction(void)
{
while (m_bWantThreadedFunctionRunning)
{
wait()
{
on "Thread", "Touch":
break;
.. whatever else..
}
}
m_bIsThreadedFunctionRunning = false;
}
</pre></code>

== Not Waiting For Messages ==
As seen above, it's possible for a thread to fail to receive posted messages because it wasn't waiting for them at the time. A more commonly problematic example follows.

<code><pre>
thread void MyThread(void)
{
wait ()
{
on "Some", "Condition":
HandleSomeCondition();
continue;
on "Thread", "Exit":
break;
}
}

void HandleSomeCondition(void)
{
wait ()
{
on "Some", "End-Condition":
break;
}
}
</pre></code>

In this example, the thread is waiting on both "Some", "Condition" and also "Thread", "Exit". Either one will be handled correctly assuming that the thread is already running at the time they are posted. Even if multiple are posted, the thread will simply queue them and run each in turn.

The problem occurs when HandleSomeCondition() is triggered and the thread begins waiting on "Some", "End-Condition". In this scenario, the thread is no longer waiting on "Thread", "Exit", and any attempt to post that message will simply be ignored. To reiterate: the message dispatch is NOT postponed until the function returns; the message is dropped entirely.

In many cases, the correct behaviour is to move HandleSomeCondition() to a new thread, although that may also carry gotchas that you will need to be careful of (eg. you'll probably want to terminate the second thread at the same time as the first one, and you may need to consider whether you want multiple of the second thread to run simultaneously or not).

== Performing Actions After Being Told to Stop ==
In many cases, you may wish to perform cleanup actions when stopping your rule. If your rule is threaded, this can easily become problematic.

Consider the following pseudocode example:

<code><pre>
void Pause(bool bIsPaused)
{
if (!bIsPaused && !m_bIsThreadRunning)
{
m_bIsThreadRunning = true;
MyThread();
}
}

thread void MyThread(void)
{
BeginRule();
while (!IsPaused())
{
Sleep(0.5);
UpdateRule();
}
EndRule();
m_bIsThreadRunning = false;
}
</pre></code>

There are three immediately obvious problems:

1. That BeginRule() is called when the thread starts, even if the rule has already been paused again.

2. That UpdateRule() will be called after each sleep, even if the rule was paused during the sleep.

3. That EndRule() will be called after the rule has been paused.

This is very problematic because it likely violates a core principles of the rules system: that rules will not undertake any meaningful behaviour when paused. All three functions may be called while the rule is paused, so unless the rule does nothing meaningful at all, this is a guaranteed violation.

The best approach to resolving this may depend on exactly what these functions do, but one possible solution is as follows:

<code><pre>
void Pause(bool bIsPaused)
{
if (bIsPaused)
{
if (m_bNeedsEndRule)
{
m_bNeedsEndRule = false;
EndRule();
}
}
else
{
if (!m_bNeedsEndRule)
{
BeginRule();
m_bNeedsEndRule = true;
}
if (!m_bIsThreadRunning)
{
m_bIsThreadRunning = true;
MyThread();
}
}
}

thread void MyThread(void)
{
while (!IsPaused())
{
UpdateRule();
Sleep(0.5);
}
m_bIsThreadRunning = false;
}
</pre></code>

Session Rule Implementation

2018-11-27T17:03:39Z

Windwalkr: /* Performing Actions After Being Told to Stop */

This page seeks to clearly define expected script behavior for [[KIND Scenariobehavior|Session Rule assets]]. This focuses specifically on correct behavior from the code perspective, rather than addressing how rules should be designed for best gameplay outcomes.

= Legacy Behavior Note =
Please note that many existing rules do not behave correctly as defined here. This is considered a bug in the individual session rules. [[N3V Games]] has a policy of updating session rules to behave correctly even where that may lead to changes of function in existing [[session]] assets. Where reasonable to achieve, emulation of the existing (buggy) behavior may occur for existing rule instances in existing sessions, however any newly created rule instances will use the corrected behavior.

These expectations were codified at the end of [[TS12]] development due to an increasing inability of session rules to work together resulting from the unpredictable nature of their responses to various common use-cases. The systems as a whole, including most of the core rules discussed in this document, have existed for far longer than this document. The document does not redefine any existing systems, but simply presents the only reasonable implementation approach possible if rules are to be expected to work properly in all use-cases. In some cases we also choose to mandate specific points of behavior relating to user expectations rather than technical necessities.

Certain additional API mechanisms were introduced alongside the development of this document, to allow better communication with session authors regarding the differences in behavior between certain types of rule. The correct usage for these mechanisms is also included in this document.

= The Rule Hierarchy =
All rules within a given session form a simple tree structure.

== Rule State Flags ==
Each rule in the tree may have certain associated state flagged, including a combination of the following:

=== PAUSED ===
The rule is currently paused, meaning that it does not affect the game world in any way and does not respond to any changes in the game world. The parent rule must cause the rule to become unpaused for the rule to have any effect. It is not correct behavior for a rule to unpause itself.

=== COMPLETE ===
This flag indicates that rule has fully completed its operation (including any child rule operations) and does not affect the game world in any way. This flag is set by the rule itself, not by an outside entity such as the parent. This state should not be changed while the rule is PAUSED.

Being COMPLETE does not imply being PAUSED. In many scenarios, the parent rule may respond to a child becoming COMPLETE by causing it to also become PAUSED, however this is certainly not guaranteed in all cases, and is not guaranteed to be immediate in the cases where it does happen.

The rule may optionally respond to specific changes in the game world by deflagging the COMPLETE status. For example, a rule which specifically implements a condition check may choose to become COMPLETE when that condition is met, but return to an incomplete state when the condition is no longer met (again, remembering that a change in either direction should only happen while the rule itself is not PAUSED).

When a rule's COMPLETE state changes, a "ScenarioBehavior", "Touch" message is sent '''(TBD: BY WHAT MECHANISM?)''' to its parent rule (if any), unless the parent is in the PAUSED state. This allows the parent to react to changes in its child rules' states. It is important to note that the message indicates a possible change which the parent may be interested in, but it is the parent rule's responsibility to determine whether the state change is worth reacting to.

=== WAS COMPLETE ===
This is typically set when a rule first becomes flagged as COMPLETE, and will stay set even if the rule later flags as incomplete. This can be used by a parent which only cares that the child rule has been flagged as COMPLETE at some point, rather than caring what its current completion status is.

=== DOES COMPLETE ===
This indicates whether the rule can ever reach the COMPLETE state. Its value is constant for a given rule configuration, and does not change based on the runtime rule state or other game state. Rules which are flagged as DOES COMPLETE are expected to become complete after some discreet operations are completed. Rules which are not flagged are expected to run indefinitely unless PAUSED by an external agent (such as the parent rule).

== Initial State ==
All rules are initially in the PAUSED state when in [[Surveyor]], and only become unpaused after gameplay begins in a [[Driver]] session. Since a PAUSED rule is not permitted to unpause itself, this is a stable state which will persist until the native code takes step to begin program flow.

== Top Level Rules ==
All rules at the top level (ie. rules which are not a child of any other rule) simultaneously become unpaused after the session has loaded into Driver. Some of these rules may take initial setup steps and then become COMPLETE. Some of these rules may begin monitoring for specific game conditions before taking any further action. Some of these rules may begin taking action immediately. The rules are not sequenced against each other in any way, and it is the session author's responsibility to ensure that this does not cause any conflicts.

== Scheduling ==
Since the script VM is a cooperatively-threaded environment, it is technically true that rule evaluation will occur in an ordered manner rather than truly simultaneously. However, no guarantees are made regarding the order in which the simultaneously-running rules will perform their checks or outcomes. Since rules may wait internally rather than fulfilling their entire purpose in an atomic operation, it is also not guaranteed that a first-running rule will fully complete before some other simultaneously-executing rule begins completion. In short, if order-of-execution is critical to the correct behavior of a session, then the order should be enforced by the session creator using the rule hierarchy rather than by making assumptions about execution order of simultaneously-running rules.

(Note: with the introduction of [[Asynchronous Route Streaming]], this is even more true than previously. What may have been a near-instantaneous operation in older builds may now require a wait of several seconds while the necessary data is streamed in.)

It is important to note that some conditional rules may partially or completely rely on a polling behavior to evaluate their conditions. (An example of partial reliance is a rule which waits for an event, but then evaluates a condition to clarify whether the event should be acted upon.) In these cases, it is possible that the condition can rapidly become true and then become false again without the rule responding. This results in an uncertainty as to whether the conditional rule will correctly detect a given instance of the condition. This type of scenario should be avoided completely where possible, and should most definitely be limited to outcomes that do not significantly affect gameplay.

For a hypothetical example, if the player's train speeds for 0.5sec, and a speeding check rule was implemented that polled every second, then the overspeed event may or may not trigger on any given occurrence. A session creator should not use this outcome as a failure condition, since some players may be able to speed without penalty, whereas other players would be penalised on the first attempt. A sensible solution in this case might be to increment a counter while speeding is detected, and only take action if the counter reaches a certain threshold. If the only penalty was a warning to the player which had no actual gameplay impact, then it might be acceptable to forgo this check and simply accept that some players will receive a warning where others may not.

==Child Rules==
As with all other rules, child rules (ie. those that have parent rules in the hierarchy) start out in the PAUSED state. They do not become unpaused until the parent is ready for the children to start operating. Exactly when this occurs depends on the specific parent rule, but the general flow is the same for all rules:

1. Parent rule becomes unpaused and begins operation.
2. Parent rule configures any necessary world state changes.
3. Parent rule optionally waits for a specific condition to occur.
4. Parent rule begins executing its children. This involves unpausing one or more of the children (as discussed below in "Parent Rule Styles").
5. Parent waits for its children to complete (as discussed below in "Parent Rule Styles") and then pauses the children.
6. Parent flags itself as COMPLETE.

This process allows program control flow to pass from a top-level rule, to its immediate children, to their immediate children, and so on. As the bottom-level children become complete, completion flows back to the higher level children until finally the top-level rules become COMPLETE.

It is worth noting that there is nothing special about a top-level rule being flagged as COMPLETE. This does not indicate an end-of-session or any other fundamental gameplay mode change. Since the pausing of rules on completion is handled by the parent rule (see step 5 above), the top-level rules never become PAUSED on completion.

==Parent Rule Styles==
There are a few common techniques with which parent rules interact with their children. Rules should always fit one of these descriptions. The vast majority of rules should follow either the "Does Not Support Children" style, or the "Ordered Execution of Children" style.

=== Does Not Support Children ===
The rule is incapable of supporting children and will always ignore them.

This is used for trivial rules which perform a set function and then become permanently COMPLETE. Such rules are not conditional and do not wait for any world state changes except those which they initiate internally.
The rule should be configured to validate and/or enforce that no child rules can be added.

=== Simultaneous Execution of Children ===
When the rule is ready to begin executing children, it unpauses all children simultaneously. The rule then waits for all children to flag as WAS COMPLETE. Once this is detected, the rule pauses all children and flags itself as COMPLETE.
This is used for rules which have a specific need to simultaneously execute children, such as the "Simultaneous List" rule.

The rule editor interface should be explicit that child rules will be executed simultaneously. Child rules should be tagged appropriately in the rule editor list to denote unordered execution.

=== Ordered Execution of Children ===
When the rule is ready to begin executing children, it iterates through the children in top-to-bottom order. If the child is flagged as WAS COMPLETE, the child is paused and iteration continues. If the child is not flagged as WAS COMPLETE, the child is unpaused and iteration ends. Whenever a child state change is detected, this process is repeated from the start. Once iteration passes over all children without leaving any child unpaused, the rule flags itself as COMPLETE.

This style is used for all rules which do not explicitly fall under one of the other styles described here. Almost all third-party rules will follow this style. Implementing one of the other styles without there being a fundamental requirement to do so is considered a programming error.

Rules which follow this style should derive from ConditionalScenarioBehavior in order to avoid re-implementing the control flow logic, as it is exceedingly complex to implement correctly. Any rules which do not derive from ConditionalScenarioBehavior should be accompanied by a clear explanation of the reasons that ConditionalScenarioBehavior is an unsuitable base class for the intended behavior. Rules which do derive from ConditionalScenarioBehavior should avoid complex overrides of the default logic.

Child rules should be tagged appropriately in the rule editor list to denote execution order.

=== Controlled Selection of a Single Child ===
When the rule is ready to begin executing children, it selects a single child and unpauses it. All other children remain paused. Once the selected child becomes flagged as WAS COMPLETE, the child is paused and the rule flags itself as COMPLETE.

This style is used where complex conditional selection of child rules is required. This can be used to implement an "if-else" logic flow, a "switch-case" logic flow, or the "Random List" rule. This style should not be used to implement a simple "if" logic flow, because that would unnecessarily restrict the rule to a single child where the "Ordered Execution of Children" style would provide the same functionality while allowing multiple children.
The rule editor interface should be very explicit about how the child rules will be selected. Child rules should be tagged appropriately in the rule editor list to avoid the user attempting to fit a child rule into the wrong role.

=== Custom Execution with Multiple Children ===
This style is used for very specific custom-purpose rules, such as a passenger station stop handler. Such rules should give a clear and complete explanation of their operation and their interaction with any child rules in the rule editor interface.

Individual child rules may be executed in an ad-hoc manner by the rule in response to changes in game state. Child rules may or may not be executed simultaneously and may or may not be executed repeatedly depending on the rule; any limitations or gotchas deriving from this should be carefully explained in the rule editor interface.

Child rules should be tagged appropriately in the rule editor list to avoid the user attempting to fit a child rule into the wrong role.

= Early Termination via Pause =
A rule must accept being paused by its parent at any time. This should cause the rule to cease any game state monitoring or other direct effects. The rule must pause all child rules immediately.

In cases where the rule is maintaining some reversible effect on the game world, pausing the rule should end this effect. For example, a rule which displays a message to the user should typically hide the message upon becoming paused, and a rule which causes a rain storm in a specific area should return the weather to normal upon becoming paused. Rules which make a single permanent change to the game world and then immediately flag as COMPLETE should not attempt to reverse the change upon becoming paused. Examples of these rules include configuration of the global weather conditions, or a rule which increments the player's score or penalty counter.

It is important to note that any pause is resumable, although the parent may not choose to take advantage of this. Pausing a rule followed by unpausing it should result in the rule continuing operation where it left off. The notes on Saving and Loading Driver Sessions (below) are worth considering when evaluating techniques for implementing pause.

= Early Termination via Internal Logic =
In some cases, a rule may begin executing child rules but then make an internal decision to abort execution. This typically occurs in conditional rules where the condition may be re-evaluated as false after it has already been evaluated as true. Such behavior should be made explicit in the rule editor interface and should usually be made optional by providing a checkbox.

There are in fact several possible behavioral variants affecting how condition-deflag is interpreted:
* Once the condition is flagged, the rule starts executing child rules and no further evaluation is performed. The rule eventually flags itself as COMPLETE and does not later deflag this.
* Once the condition is flagged, the rule starts executing child rules. If the condition becomes deflagged, the child rules are paused. If the condition becomes flagged again, the child rules are continued. Once the child rules have fully completed execution, the rule flags itself as COMPLETE and does not later deflag this.
* Once the condition is flagged, the rule starts executing child rules. If the condition becomes deflagged, the child rules are paused. If the condition becomes flagged again, the children are reset and execution starts anew. The rule flags itself as COMPLETE if all children successfully complete, but it will deflag if the condition deflags.
* Once the condition is flagged, the rule starts executing child rules. If the condition becomes deflagged, the child rules continue executing. If the condition becomes flagged again, the children are reset and execution starts anew. The rule will flag as COMPLETE if all children successfully complete, but it will deflag if the condition deflags.
* Once the condition is flagged, the rule starts executing child rules. The child rules continue execution with no regard for whether the condition changes between flagged or deflagged in either direction. If the condition transitions from deflagged to flagged again after the children have completed, the children are reset and execution starts anew. The rule will flag as COMPLETE if all children successfully complete, but it will deflag itself if the condition deflags.

The complexity here derives from the fact that it is not possible to use the same set of rules multiple times concurrently for different trigger conditions. For example, if a set of rules is used to give demerit points and provide user notifications, and those rules live under a single conditional check which determines whether a train is speeding, it may be difficult to define what should happen if two trains are detected as speeding at the same time, or if a train stops speeding while the notification process is still in progress. It is not always possible to achieve a perfect solution to tracking multiple objects using a single set of rules, but correct selection from the above behaviors can minimise the possibility of serious side-effects.

It is important to note that these behaviors describe how the rule reacts to internal condition checks. The rule's reaction to being paused by its parent is discussed above under "Early Termination via Pause" and is not affected by the description here.

In short, there are many ways of handling this, and the important thing is for your (parent) rule to clearly explain which approach it is going to use.

= Rule Reset =
A rule may be ''reset'' by its parent. This causes both the COMPLETE and WAS COMPLETE states to be deflagged. Individual rules may also react to the reset by modifying their internal state to forget past or present actions. Parent rules must also cause their children to be reset in turn.

This mechanism is used to permit rules to be used in a repeating scenario, such as responding to a condition which can occur multiple times, or in a repeating loop. At some point after a rule has become flagged as WAS COMPLETE, it will typically become paused and will not be unpaused again. If the rule is to be included in some repeating behavior, this would normally prevent the behavior from operating successfully after the first run through. To avoid this, the parent rule responsible for implementing the repeating behavior will ''reset'' all children when a repeat occurs. This effectively cleans the rules back to their initial state ready to perform their roles again.

It is important to note that a reset should cause the rule to return to its configured settings. For example, if a timer value is configured and is decremented during rule operation, the timer must be reset back to its initial value during rule reset.

It is important to note that there is no requirement to pause a rule prior to resetting it.

= Saving and Loading Driver Sessions =
For better or worse, the script VM does not persist across a save/load operation. This means that each rule must correctly save both its configuration state and its runtime state, and must correctly reload those such that the state after a save/load operation is indistinguishable from the original state. The following aspects of the script state must be considered:

* Member variables in the Rule instance.
* Which threads are running on the Rule instance, and where they are up to in the code flow.
* Local variables on the stack of each running thread.
* Non-persistent changes made to the state of other script objects (such as active 'sniff' statements).
* Script Messages which might be in flight at the time of save (these are not persisted, so the net effect is that they are simply deleted between the save and the load.)

Since the game state continues normal operation after a Save, no code flow or other behavioral changes should result from the Save operation itself. Instead, the Save operation (and the design of the rule as a whole) is responsible for ensuring that sufficient data is persisted in the save file such that the Load operation is able to restore to the correct running state.

The rule base class, ScenarioBehavior, is responsible for saving and loading the rule state flags (COMPLETE, PAUSED, WAS COMPLETE, etc.) A rule which was paused at Save time will still be paused after the Load. A rule which was complete at Save time will still be complete after the Load. During a Load operation, the rule should inherit the parent class' SetProperties() method so that these flags are correctly configured, then honor the paused state during the rest of the loading process.

It is rarely appropriate for an unpaused rule to simply restart execution from the beginning. Care must be taken to ensure that execution resumes from the point that it left off at the time of saving. This process can be simplified by keeping as much state as possible in the rule member variables at all times, and only keeping reconstructible temporary values on the stack. If the member variables are correctly stored and restored, this approach will allow the loading process to detect the runtime state of the rule and resume any necessary threads, which will in turn be able to jump forward to the correct area of the code based on the stored state.

Finally, the COMPLETE, WAS COMPLETE, and PAUSED flags on child rules should be honored. This is typically sufficient information to determine the running state of child rules, so no further state will generally need to be maintained. More accurately, the child rules take care of their own state at all times, and the parent only needs to react to changes in the child state. Since no child state change occurs across a Save/Load operation, the parent does not need to become involved.

For rules which derive ConditionalScenarioBehavior, the majority of load/save logic is handled automatically. The only state information that such a rule should typically preserve is the instance-specific configuration data. The condition-monitor thread will be automatically restarted as required, and there is generally no need to distinguish between a first-startup and any subsequent startup.

= Spurious Events =
There are various events (typically script messages) that a rule may listen for in order to detect state changes. It is important to note that spurious events are often possible, and that an event handler should often be coupled with a condition check. As a specific example, the "ScenarioBehavior", "Touch" message typically indicates that a child state has changed, but the message may in fact be sent at any time. This message should prompt the rule to evaluate whether any state changes are necessary, but the rule should not simply assume that a state change is necessary without performing an evaluation.

Similarly, calls to a function such as Pause() may in some cases have no effect. For example, if a rule is already executing and its parent calls Pause(false), the rule should not pause, reset, or change state in any way at all. Similarly, if a rule is already paused and its parent calls Pause(true), the rule should not unpause, reset, fire any events, or otherwise change state in any way at all.

The short version is: do not assume that every event and every method call is supposed to achieve something meaningful. Check first, and if the event is meaningless to you then do nothing at all.

= Future Considerations =
Rules should base their functionality on the state flags such as the PAUSED state, rather than attempting to detect and vary their functionality based on the state of the game.

For example, we currently (in development builds) expose the rules editor in Driver for debugging purposes. This, or some mechanism like it, is likely to be included in public builds in the future. Rules should not assume that it is impossible to be reconfigured during gameplay. This will of course introduce some side effects, such as when an unpaused rule is modified during execution. It is the rule's responsibility to ensure that these side effects do not lead to script exceptions or to leaked state. For example, if a single thread is supposed to be running, reconfiguring the rule should not cause a second thread to run simultaneously. If a rule sniffs a target vehicle, and the target vehicle is redefined, then the rule should unsniff the original vehicle rather than now sniffing two vehicles.

Likewise, we may in future allow some form of partial state swap between Driver and Surveyor. Rules should not assume that it is impossible to change from any one game state or module to any other game state or module, just because it is not possible at the current time. APIs already exist to detect such state changes where necessary, and in most cases it's simply not necessary to care whether your rule is in Surveyor or Driver - you should act based on the PAUSED state instead. Rules should deal with the game state as they find it rather than assuming that certain states will not ever occur.

= Gotchas =
There are a few potential gotchas in the script environment that are worth considering when writing any non-trivial rule.

== Response Latency ==
Scripts tend to rely heavily on message passing and threading. In both cases, there is a delay between triggering a certain behavior (eg. posting an event, or calling a threaded function) and having the receiving code react. Other code may execute during this delay.

<code><pre>
// Calling this might be expected to start and then stop the thread; in reality it
// will likely simply start the thread and leave it running, because the message
// is sent prior to the wait() statement starting.
void DemonstrateBug1(void)
{
Pause(false);
Pause(true);
}

// In this case, we use a Sleep() statement to "ensure" that the thread has
// finished starting. This isn't actually reliable, but it works as long as the
// system isn't under too much load. We follow this up with a rapid pause-
// unpause sequence. As above, this doesn't work - the message is sent,
// then the function immediately checks whether the thread is still running
// (which it is) and thus the thread isn't restarted. The function completes,
// and finally the thread receives the message and exits.
void DemonstrateBug2(void)
{
Pause(false);
Sleep(1.0);
Pause(true);
Pause(false);
}

// Helper code for the above functions.
void Pause(bool bIsPaused)
{
if (bIsPaused)
{
PostMessage(me, "ThisRule", "Pause");
}
else if (!m_bIsThreadRunning)
{
m_bIsThreadRunning = true;
StartThread();
}
}
thread void StartThread(void)
{
while (true)
{
wait ()
{
on "ThisRule", "Pause":
break;
...
}
m_bIsThreadRunning = false;
}
</pre></code>

== Multiple Messages in Flight ==
It's possible to post multiple identical messages. This can be useful, but if you're expecting only one then it can be a source of errors.

In the following pseudocode, each call to SetProperties() will place an additional "Timer", "Tick" message into the cycle, effectively increasing the rate at which the IdleFunction is called. This will seem to be working for a single call to SetProperties(), which may be all that is called during a trivial testcase. It will probably give reasonable results for a few calls to SetProperties(), although if the function is time-sensitive then the results might be different to expectations. After a larger number of calls to SetProperties(), the object's message queue may become full, causing it to lose messages at random (perhaps the tick messages, or perhaps other unrelated messages that are more problematic).

<code><pre>
void Init(void)
{
inherited();

AddHandler(me, "Timer", "Tick", "IdleFunction");
}

void EnterIdleState(void)
{
IdleFunction();
}

void IdleFunction(void)
{
PostMessage(me, "Timer", "Tick", 1.0);
.. do something here ..
}

void SetProperties(Soup soup)
{
inherited(soup);

EnterIdleState();
}

</pre></code>

A similar problem can occur if you start new threads rather than post new messages.

== Thread Guard Variables ==
It's common to prevent a singleton thread from being started twice by using a boolean guard variable. Care must be taken to ensure that the guard variable is set and cleared at the correct locations, or they may be ineffective.

The following pseudocode demonstrates one such correct usage. The key points to note are:
* We set 'm_bIsThreadedFunctionRunning' prior to calling the threaded function. Setting it within the threaded function is too late; multiple threads might have already been started before the first thread reaches that point.
* We don't confuse whether the thread is actually running with whether we want the thread to be running. Once we ask a thread to start, we can't stop it starting. If we change our minds and want to stop it again, we must inform it in a way that it will realise after it finishes starting. In the worst-case scenario, we might flipflop on this multiple times before the thread actually starts.
* Similarly, we don't rely on messages to control the thread. Enqueuing a separate start or stop message with each StartThread()/StopThread() call might be possible, and we could clear any unwanted prior messages from the object's queue, but if the thread hasn't finished starting then it won't receive the messages anyway.
* We do rely on messages to wake the thread if it's waiting on messages, but we don't use those messages to imply any state - we just have it recheck the current state boolean to get the very latest info.
* We clear 'm_bIsThreadedFunctionRunning' once the decision to exit has become unconditional. At this point, even though the thread is technically still running, we'll have to start a new thread if we want the thread to continue running.

<code><pre>
bool m_bIsThreadedFunctionRunning = false;
bool m_bWantThreadedFunctionRunning = false;

void StartThread(void)
{
m_bWantThreadedFunctionRunning = true;

if (m_bIsThreadedFunctionRunning)
return;

m_bIsThreadedFunctionRunning = true;
ThreadedFunction();
}

void StopThread(void)
{
if (!m_bWantThreadedFunctionRunning)
return;

m_bWantThreadedFunctionRunning = false;
PostMessage(me, "Thread", "Touch");
}

thread void ThreadedFunction(void)
{
while (m_bWantThreadedFunctionRunning)
{
wait()
{
on "Thread", "Touch":
break;
.. whatever else..
}
}
m_bIsThreadedFunctionRunning = false;
}
</pre></code>

== Not Waiting For Messages ==
As seen above, it's possible for a thread to fail to receive posted messages because it wasn't waiting for them at the time. A more commonly problematic example follows.

<code><pre>
thread void MyThread(void)
{
wait ()
{
on "Some", "Condition":
HandleSomeCondition();
continue;
on "Thread", "Exit":
break;
}
}

void HandleSomeCondition(void)
{
wait ()
{
on "Some", "End-Condition":
break;
}
}
</pre></code>

In this example, the thread is waiting on both "Some", "Condition" and also "Thread", "Exit". Either one will be handled correctly assuming that the thread is already running at the time they are posted. Even if multiple are posted, the thread will simply queue them and run each in turn.

The problem occurs when HandleSomeCondition() is triggered and the thread begins waiting on "Some", "End-Condition". In this scenario, the thread is no longer waiting on "Thread", "Exit", and any attempt to post that message will simply be ignored. To reiterate: the message dispatch is NOT postponed until the function returns; the message is dropped entirely.

In many cases, the correct behaviour is to move HandleSomeCondition() to a new thread, although that may also carry gotchas that you will need to be careful of (eg. you'll probably want to terminate the second thread at the same time as the first one, and you may need to consider whether you want multiple of the second thread to run simultaneously or not).

== Performing Actions After Being Told to Stop ==
In many cases, you may wish to perform cleanup actions when stopping your rule. If your rule is threaded, this can easily become problematic.

Consider the following pseudocode example:

<code><pre>
void Pause(bool bIsPaused)
{
if (!bIsPaused && !m_bIsThreadRunning)
{
m_bIsThreadRunning = true;
MyThread();
}
}

thread void MyThread(void)
{
BeginRule();
while (!IsPaused())
{
Sleep(0.5);
UpdateRule();
}
EndRule();
m_bIsThreadRunning = false;
}
</pre></code>

There are three immediately obvious problems:

1. That BeginRule() is called when the thread starts, even if the rule has already been paused again.

2. That UpdateRule() will be called after each sleep, even if the rule was paused during the sleep.

3. That EndRule() will be called after the rule has been paused.

This is very problematic because it likely violates a core principles of the rules system: that rules will not undertake any meaningful behaviour when paused. All three functions may be called while the rule is paused, so unless the rule does nothing meaningful at all, this is a guaranteed violation.

The best approach to resolving this may depend on exactly what these functions do, but one possible solution is as follows:

<code><pre>
void Pause(bool bIsPaused)
{
if (bIsPaused)
{
if (m_bNeedsEndRule)
{
m_bNeedsEndRule = false;
EndRule();
}
}
else
{
if (!m_bNeedsEndRule)
{
BeginRule();
m_bNeedsEndRule = true;
}
if (!m_bIsThreadRunning)
{
m_bIsThreadRunning = true;
MyThread();
}
}
}

thread void MyThread(void)
{
while (!IsPaused())
{
UpdateRule();
Sleep(0.5);
}
m_bIsThreadRunning = false;
}
</pre></code>

Session Rule Implementation

2018-11-27T17:03:15Z

Windwalkr: /* Performing Actions After Being Told to Stop */

This page seeks to clearly define expected script behavior for [[KIND Scenariobehavior|Session Rule assets]]. This focuses specifically on correct behavior from the code perspective, rather than addressing how rules should be designed for best gameplay outcomes.

= Legacy Behavior Note =
Please note that many existing rules do not behave correctly as defined here. This is considered a bug in the individual session rules. [[N3V Games]] has a policy of updating session rules to behave correctly even where that may lead to changes of function in existing [[session]] assets. Where reasonable to achieve, emulation of the existing (buggy) behavior may occur for existing rule instances in existing sessions, however any newly created rule instances will use the corrected behavior.

These expectations were codified at the end of [[TS12]] development due to an increasing inability of session rules to work together resulting from the unpredictable nature of their responses to various common use-cases. The systems as a whole, including most of the core rules discussed in this document, have existed for far longer than this document. The document does not redefine any existing systems, but simply presents the only reasonable implementation approach possible if rules are to be expected to work properly in all use-cases. In some cases we also choose to mandate specific points of behavior relating to user expectations rather than technical necessities.

Certain additional API mechanisms were introduced alongside the development of this document, to allow better communication with session authors regarding the differences in behavior between certain types of rule. The correct usage for these mechanisms is also included in this document.

= The Rule Hierarchy =
All rules within a given session form a simple tree structure.

== Rule State Flags ==
Each rule in the tree may have certain associated state flagged, including a combination of the following:

=== PAUSED ===
The rule is currently paused, meaning that it does not affect the game world in any way and does not respond to any changes in the game world. The parent rule must cause the rule to become unpaused for the rule to have any effect. It is not correct behavior for a rule to unpause itself.

=== COMPLETE ===
This flag indicates that rule has fully completed its operation (including any child rule operations) and does not affect the game world in any way. This flag is set by the rule itself, not by an outside entity such as the parent. This state should not be changed while the rule is PAUSED.

Being COMPLETE does not imply being PAUSED. In many scenarios, the parent rule may respond to a child becoming COMPLETE by causing it to also become PAUSED, however this is certainly not guaranteed in all cases, and is not guaranteed to be immediate in the cases where it does happen.

The rule may optionally respond to specific changes in the game world by deflagging the COMPLETE status. For example, a rule which specifically implements a condition check may choose to become COMPLETE when that condition is met, but return to an incomplete state when the condition is no longer met (again, remembering that a change in either direction should only happen while the rule itself is not PAUSED).

When a rule's COMPLETE state changes, a "ScenarioBehavior", "Touch" message is sent '''(TBD: BY WHAT MECHANISM?)''' to its parent rule (if any), unless the parent is in the PAUSED state. This allows the parent to react to changes in its child rules' states. It is important to note that the message indicates a possible change which the parent may be interested in, but it is the parent rule's responsibility to determine whether the state change is worth reacting to.

=== WAS COMPLETE ===
This is typically set when a rule first becomes flagged as COMPLETE, and will stay set even if the rule later flags as incomplete. This can be used by a parent which only cares that the child rule has been flagged as COMPLETE at some point, rather than caring what its current completion status is.

=== DOES COMPLETE ===
This indicates whether the rule can ever reach the COMPLETE state. Its value is constant for a given rule configuration, and does not change based on the runtime rule state or other game state. Rules which are flagged as DOES COMPLETE are expected to become complete after some discreet operations are completed. Rules which are not flagged are expected to run indefinitely unless PAUSED by an external agent (such as the parent rule).

== Initial State ==
All rules are initially in the PAUSED state when in [[Surveyor]], and only become unpaused after gameplay begins in a [[Driver]] session. Since a PAUSED rule is not permitted to unpause itself, this is a stable state which will persist until the native code takes step to begin program flow.

== Top Level Rules ==
All rules at the top level (ie. rules which are not a child of any other rule) simultaneously become unpaused after the session has loaded into Driver. Some of these rules may take initial setup steps and then become COMPLETE. Some of these rules may begin monitoring for specific game conditions before taking any further action. Some of these rules may begin taking action immediately. The rules are not sequenced against each other in any way, and it is the session author's responsibility to ensure that this does not cause any conflicts.

== Scheduling ==
Since the script VM is a cooperatively-threaded environment, it is technically true that rule evaluation will occur in an ordered manner rather than truly simultaneously. However, no guarantees are made regarding the order in which the simultaneously-running rules will perform their checks or outcomes. Since rules may wait internally rather than fulfilling their entire purpose in an atomic operation, it is also not guaranteed that a first-running rule will fully complete before some other simultaneously-executing rule begins completion. In short, if order-of-execution is critical to the correct behavior of a session, then the order should be enforced by the session creator using the rule hierarchy rather than by making assumptions about execution order of simultaneously-running rules.

(Note: with the introduction of [[Asynchronous Route Streaming]], this is even more true than previously. What may have been a near-instantaneous operation in older builds may now require a wait of several seconds while the necessary data is streamed in.)

It is important to note that some conditional rules may partially or completely rely on a polling behavior to evaluate their conditions. (An example of partial reliance is a rule which waits for an event, but then evaluates a condition to clarify whether the event should be acted upon.) In these cases, it is possible that the condition can rapidly become true and then become false again without the rule responding. This results in an uncertainty as to whether the conditional rule will correctly detect a given instance of the condition. This type of scenario should be avoided completely where possible, and should most definitely be limited to outcomes that do not significantly affect gameplay.

For a hypothetical example, if the player's train speeds for 0.5sec, and a speeding check rule was implemented that polled every second, then the overspeed event may or may not trigger on any given occurrence. A session creator should not use this outcome as a failure condition, since some players may be able to speed without penalty, whereas other players would be penalised on the first attempt. A sensible solution in this case might be to increment a counter while speeding is detected, and only take action if the counter reaches a certain threshold. If the only penalty was a warning to the player which had no actual gameplay impact, then it might be acceptable to forgo this check and simply accept that some players will receive a warning where others may not.

==Child Rules==
As with all other rules, child rules (ie. those that have parent rules in the hierarchy) start out in the PAUSED state. They do not become unpaused until the parent is ready for the children to start operating. Exactly when this occurs depends on the specific parent rule, but the general flow is the same for all rules:

1. Parent rule becomes unpaused and begins operation.
2. Parent rule configures any necessary world state changes.
3. Parent rule optionally waits for a specific condition to occur.
4. Parent rule begins executing its children. This involves unpausing one or more of the children (as discussed below in "Parent Rule Styles").
5. Parent waits for its children to complete (as discussed below in "Parent Rule Styles") and then pauses the children.
6. Parent flags itself as COMPLETE.

This process allows program control flow to pass from a top-level rule, to its immediate children, to their immediate children, and so on. As the bottom-level children become complete, completion flows back to the higher level children until finally the top-level rules become COMPLETE.

It is worth noting that there is nothing special about a top-level rule being flagged as COMPLETE. This does not indicate an end-of-session or any other fundamental gameplay mode change. Since the pausing of rules on completion is handled by the parent rule (see step 5 above), the top-level rules never become PAUSED on completion.

==Parent Rule Styles==
There are a few common techniques with which parent rules interact with their children. Rules should always fit one of these descriptions. The vast majority of rules should follow either the "Does Not Support Children" style, or the "Ordered Execution of Children" style.

=== Does Not Support Children ===
The rule is incapable of supporting children and will always ignore them.

This is used for trivial rules which perform a set function and then become permanently COMPLETE. Such rules are not conditional and do not wait for any world state changes except those which they initiate internally.
The rule should be configured to validate and/or enforce that no child rules can be added.

=== Simultaneous Execution of Children ===
When the rule is ready to begin executing children, it unpauses all children simultaneously. The rule then waits for all children to flag as WAS COMPLETE. Once this is detected, the rule pauses all children and flags itself as COMPLETE.
This is used for rules which have a specific need to simultaneously execute children, such as the "Simultaneous List" rule.

The rule editor interface should be explicit that child rules will be executed simultaneously. Child rules should be tagged appropriately in the rule editor list to denote unordered execution.

=== Ordered Execution of Children ===
When the rule is ready to begin executing children, it iterates through the children in top-to-bottom order. If the child is flagged as WAS COMPLETE, the child is paused and iteration continues. If the child is not flagged as WAS COMPLETE, the child is unpaused and iteration ends. Whenever a child state change is detected, this process is repeated from the start. Once iteration passes over all children without leaving any child unpaused, the rule flags itself as COMPLETE.

This style is used for all rules which do not explicitly fall under one of the other styles described here. Almost all third-party rules will follow this style. Implementing one of the other styles without there being a fundamental requirement to do so is considered a programming error.

Rules which follow this style should derive from ConditionalScenarioBehavior in order to avoid re-implementing the control flow logic, as it is exceedingly complex to implement correctly. Any rules which do not derive from ConditionalScenarioBehavior should be accompanied by a clear explanation of the reasons that ConditionalScenarioBehavior is an unsuitable base class for the intended behavior. Rules which do derive from ConditionalScenarioBehavior should avoid complex overrides of the default logic.

Child rules should be tagged appropriately in the rule editor list to denote execution order.

=== Controlled Selection of a Single Child ===
When the rule is ready to begin executing children, it selects a single child and unpauses it. All other children remain paused. Once the selected child becomes flagged as WAS COMPLETE, the child is paused and the rule flags itself as COMPLETE.

This style is used where complex conditional selection of child rules is required. This can be used to implement an "if-else" logic flow, a "switch-case" logic flow, or the "Random List" rule. This style should not be used to implement a simple "if" logic flow, because that would unnecessarily restrict the rule to a single child where the "Ordered Execution of Children" style would provide the same functionality while allowing multiple children.
The rule editor interface should be very explicit about how the child rules will be selected. Child rules should be tagged appropriately in the rule editor list to avoid the user attempting to fit a child rule into the wrong role.

=== Custom Execution with Multiple Children ===
This style is used for very specific custom-purpose rules, such as a passenger station stop handler. Such rules should give a clear and complete explanation of their operation and their interaction with any child rules in the rule editor interface.

Individual child rules may be executed in an ad-hoc manner by the rule in response to changes in game state. Child rules may or may not be executed simultaneously and may or may not be executed repeatedly depending on the rule; any limitations or gotchas deriving from this should be carefully explained in the rule editor interface.

Child rules should be tagged appropriately in the rule editor list to avoid the user attempting to fit a child rule into the wrong role.

= Early Termination via Pause =
A rule must accept being paused by its parent at any time. This should cause the rule to cease any game state monitoring or other direct effects. The rule must pause all child rules immediately.

In cases where the rule is maintaining some reversible effect on the game world, pausing the rule should end this effect. For example, a rule which displays a message to the user should typically hide the message upon becoming paused, and a rule which causes a rain storm in a specific area should return the weather to normal upon becoming paused. Rules which make a single permanent change to the game world and then immediately flag as COMPLETE should not attempt to reverse the change upon becoming paused. Examples of these rules include configuration of the global weather conditions, or a rule which increments the player's score or penalty counter.

It is important to note that any pause is resumable, although the parent may not choose to take advantage of this. Pausing a rule followed by unpausing it should result in the rule continuing operation where it left off. The notes on Saving and Loading Driver Sessions (below) are worth considering when evaluating techniques for implementing pause.

= Early Termination via Internal Logic =
In some cases, a rule may begin executing child rules but then make an internal decision to abort execution. This typically occurs in conditional rules where the condition may be re-evaluated as false after it has already been evaluated as true. Such behavior should be made explicit in the rule editor interface and should usually be made optional by providing a checkbox.

There are in fact several possible behavioral variants affecting how condition-deflag is interpreted:
* Once the condition is flagged, the rule starts executing child rules and no further evaluation is performed. The rule eventually flags itself as COMPLETE and does not later deflag this.
* Once the condition is flagged, the rule starts executing child rules. If the condition becomes deflagged, the child rules are paused. If the condition becomes flagged again, the child rules are continued. Once the child rules have fully completed execution, the rule flags itself as COMPLETE and does not later deflag this.
* Once the condition is flagged, the rule starts executing child rules. If the condition becomes deflagged, the child rules are paused. If the condition becomes flagged again, the children are reset and execution starts anew. The rule flags itself as COMPLETE if all children successfully complete, but it will deflag if the condition deflags.
* Once the condition is flagged, the rule starts executing child rules. If the condition becomes deflagged, the child rules continue executing. If the condition becomes flagged again, the children are reset and execution starts anew. The rule will flag as COMPLETE if all children successfully complete, but it will deflag if the condition deflags.
* Once the condition is flagged, the rule starts executing child rules. The child rules continue execution with no regard for whether the condition changes between flagged or deflagged in either direction. If the condition transitions from deflagged to flagged again after the children have completed, the children are reset and execution starts anew. The rule will flag as COMPLETE if all children successfully complete, but it will deflag itself if the condition deflags.

The complexity here derives from the fact that it is not possible to use the same set of rules multiple times concurrently for different trigger conditions. For example, if a set of rules is used to give demerit points and provide user notifications, and those rules live under a single conditional check which determines whether a train is speeding, it may be difficult to define what should happen if two trains are detected as speeding at the same time, or if a train stops speeding while the notification process is still in progress. It is not always possible to achieve a perfect solution to tracking multiple objects using a single set of rules, but correct selection from the above behaviors can minimise the possibility of serious side-effects.

It is important to note that these behaviors describe how the rule reacts to internal condition checks. The rule's reaction to being paused by its parent is discussed above under "Early Termination via Pause" and is not affected by the description here.

In short, there are many ways of handling this, and the important thing is for your (parent) rule to clearly explain which approach it is going to use.

= Rule Reset =
A rule may be ''reset'' by its parent. This causes both the COMPLETE and WAS COMPLETE states to be deflagged. Individual rules may also react to the reset by modifying their internal state to forget past or present actions. Parent rules must also cause their children to be reset in turn.

This mechanism is used to permit rules to be used in a repeating scenario, such as responding to a condition which can occur multiple times, or in a repeating loop. At some point after a rule has become flagged as WAS COMPLETE, it will typically become paused and will not be unpaused again. If the rule is to be included in some repeating behavior, this would normally prevent the behavior from operating successfully after the first run through. To avoid this, the parent rule responsible for implementing the repeating behavior will ''reset'' all children when a repeat occurs. This effectively cleans the rules back to their initial state ready to perform their roles again.

It is important to note that a reset should cause the rule to return to its configured settings. For example, if a timer value is configured and is decremented during rule operation, the timer must be reset back to its initial value during rule reset.

It is important to note that there is no requirement to pause a rule prior to resetting it.

= Saving and Loading Driver Sessions =
For better or worse, the script VM does not persist across a save/load operation. This means that each rule must correctly save both its configuration state and its runtime state, and must correctly reload those such that the state after a save/load operation is indistinguishable from the original state. The following aspects of the script state must be considered:

* Member variables in the Rule instance.
* Which threads are running on the Rule instance, and where they are up to in the code flow.
* Local variables on the stack of each running thread.
* Non-persistent changes made to the state of other script objects (such as active 'sniff' statements).
* Script Messages which might be in flight at the time of save (these are not persisted, so the net effect is that they are simply deleted between the save and the load.)

Since the game state continues normal operation after a Save, no code flow or other behavioral changes should result from the Save operation itself. Instead, the Save operation (and the design of the rule as a whole) is responsible for ensuring that sufficient data is persisted in the save file such that the Load operation is able to restore to the correct running state.

The rule base class, ScenarioBehavior, is responsible for saving and loading the rule state flags (COMPLETE, PAUSED, WAS COMPLETE, etc.) A rule which was paused at Save time will still be paused after the Load. A rule which was complete at Save time will still be complete after the Load. During a Load operation, the rule should inherit the parent class' SetProperties() method so that these flags are correctly configured, then honor the paused state during the rest of the loading process.

It is rarely appropriate for an unpaused rule to simply restart execution from the beginning. Care must be taken to ensure that execution resumes from the point that it left off at the time of saving. This process can be simplified by keeping as much state as possible in the rule member variables at all times, and only keeping reconstructible temporary values on the stack. If the member variables are correctly stored and restored, this approach will allow the loading process to detect the runtime state of the rule and resume any necessary threads, which will in turn be able to jump forward to the correct area of the code based on the stored state.

Finally, the COMPLETE, WAS COMPLETE, and PAUSED flags on child rules should be honored. This is typically sufficient information to determine the running state of child rules, so no further state will generally need to be maintained. More accurately, the child rules take care of their own state at all times, and the parent only needs to react to changes in the child state. Since no child state change occurs across a Save/Load operation, the parent does not need to become involved.

For rules which derive ConditionalScenarioBehavior, the majority of load/save logic is handled automatically. The only state information that such a rule should typically preserve is the instance-specific configuration data. The condition-monitor thread will be automatically restarted as required, and there is generally no need to distinguish between a first-startup and any subsequent startup.

= Spurious Events =
There are various events (typically script messages) that a rule may listen for in order to detect state changes. It is important to note that spurious events are often possible, and that an event handler should often be coupled with a condition check. As a specific example, the "ScenarioBehavior", "Touch" message typically indicates that a child state has changed, but the message may in fact be sent at any time. This message should prompt the rule to evaluate whether any state changes are necessary, but the rule should not simply assume that a state change is necessary without performing an evaluation.

Similarly, calls to a function such as Pause() may in some cases have no effect. For example, if a rule is already executing and its parent calls Pause(false), the rule should not pause, reset, or change state in any way at all. Similarly, if a rule is already paused and its parent calls Pause(true), the rule should not unpause, reset, fire any events, or otherwise change state in any way at all.

The short version is: do not assume that every event and every method call is supposed to achieve something meaningful. Check first, and if the event is meaningless to you then do nothing at all.

= Future Considerations =
Rules should base their functionality on the state flags such as the PAUSED state, rather than attempting to detect and vary their functionality based on the state of the game.

For example, we currently (in development builds) expose the rules editor in Driver for debugging purposes. This, or some mechanism like it, is likely to be included in public builds in the future. Rules should not assume that it is impossible to be reconfigured during gameplay. This will of course introduce some side effects, such as when an unpaused rule is modified during execution. It is the rule's responsibility to ensure that these side effects do not lead to script exceptions or to leaked state. For example, if a single thread is supposed to be running, reconfiguring the rule should not cause a second thread to run simultaneously. If a rule sniffs a target vehicle, and the target vehicle is redefined, then the rule should unsniff the original vehicle rather than now sniffing two vehicles.

Likewise, we may in future allow some form of partial state swap between Driver and Surveyor. Rules should not assume that it is impossible to change from any one game state or module to any other game state or module, just because it is not possible at the current time. APIs already exist to detect such state changes where necessary, and in most cases it's simply not necessary to care whether your rule is in Surveyor or Driver - you should act based on the PAUSED state instead. Rules should deal with the game state as they find it rather than assuming that certain states will not ever occur.

= Gotchas =
There are a few potential gotchas in the script environment that are worth considering when writing any non-trivial rule.

== Response Latency ==
Scripts tend to rely heavily on message passing and threading. In both cases, there is a delay between triggering a certain behavior (eg. posting an event, or calling a threaded function) and having the receiving code react. Other code may execute during this delay.

<code><pre>
// Calling this might be expected to start and then stop the thread; in reality it
// will likely simply start the thread and leave it running, because the message
// is sent prior to the wait() statement starting.
void DemonstrateBug1(void)
{
Pause(false);
Pause(true);
}

// In this case, we use a Sleep() statement to "ensure" that the thread has
// finished starting. This isn't actually reliable, but it works as long as the
// system isn't under too much load. We follow this up with a rapid pause-
// unpause sequence. As above, this doesn't work - the message is sent,
// then the function immediately checks whether the thread is still running
// (which it is) and thus the thread isn't restarted. The function completes,
// and finally the thread receives the message and exits.
void DemonstrateBug2(void)
{
Pause(false);
Sleep(1.0);
Pause(true);
Pause(false);
}

// Helper code for the above functions.
void Pause(bool bIsPaused)
{
if (bIsPaused)
{
PostMessage(me, "ThisRule", "Pause");
}
else if (!m_bIsThreadRunning)
{
m_bIsThreadRunning = true;
StartThread();
}
}
thread void StartThread(void)
{
while (true)
{
wait ()
{
on "ThisRule", "Pause":
break;
...
}
m_bIsThreadRunning = false;
}
</pre></code>

== Multiple Messages in Flight ==
It's possible to post multiple identical messages. This can be useful, but if you're expecting only one then it can be a source of errors.

In the following pseudocode, each call to SetProperties() will place an additional "Timer", "Tick" message into the cycle, effectively increasing the rate at which the IdleFunction is called. This will seem to be working for a single call to SetProperties(), which may be all that is called during a trivial testcase. It will probably give reasonable results for a few calls to SetProperties(), although if the function is time-sensitive then the results might be different to expectations. After a larger number of calls to SetProperties(), the object's message queue may become full, causing it to lose messages at random (perhaps the tick messages, or perhaps other unrelated messages that are more problematic).

<code><pre>
void Init(void)
{
inherited();

AddHandler(me, "Timer", "Tick", "IdleFunction");
}

void EnterIdleState(void)
{
IdleFunction();
}

void IdleFunction(void)
{
PostMessage(me, "Timer", "Tick", 1.0);
.. do something here ..
}

void SetProperties(Soup soup)
{
inherited(soup);

EnterIdleState();
}

</pre></code>

A similar problem can occur if you start new threads rather than post new messages.

== Thread Guard Variables ==
It's common to prevent a singleton thread from being started twice by using a boolean guard variable. Care must be taken to ensure that the guard variable is set and cleared at the correct locations, or they may be ineffective.

The following pseudocode demonstrates one such correct usage. The key points to note are:
* We set 'm_bIsThreadedFunctionRunning' prior to calling the threaded function. Setting it within the threaded function is too late; multiple threads might have already been started before the first thread reaches that point.
* We don't confuse whether the thread is actually running with whether we want the thread to be running. Once we ask a thread to start, we can't stop it starting. If we change our minds and want to stop it again, we must inform it in a way that it will realise after it finishes starting. In the worst-case scenario, we might flipflop on this multiple times before the thread actually starts.
* Similarly, we don't rely on messages to control the thread. Enqueuing a separate start or stop message with each StartThread()/StopThread() call might be possible, and we could clear any unwanted prior messages from the object's queue, but if the thread hasn't finished starting then it won't receive the messages anyway.
* We do rely on messages to wake the thread if it's waiting on messages, but we don't use those messages to imply any state - we just have it recheck the current state boolean to get the very latest info.
* We clear 'm_bIsThreadedFunctionRunning' once the decision to exit has become unconditional. At this point, even though the thread is technically still running, we'll have to start a new thread if we want the thread to continue running.

<code><pre>
bool m_bIsThreadedFunctionRunning = false;
bool m_bWantThreadedFunctionRunning = false;

void StartThread(void)
{
m_bWantThreadedFunctionRunning = true;

if (m_bIsThreadedFunctionRunning)
return;

m_bIsThreadedFunctionRunning = true;
ThreadedFunction();
}

void StopThread(void)
{
if (!m_bWantThreadedFunctionRunning)
return;

m_bWantThreadedFunctionRunning = false;
PostMessage(me, "Thread", "Touch");
}

thread void ThreadedFunction(void)
{
while (m_bWantThreadedFunctionRunning)
{
wait()
{
on "Thread", "Touch":
break;
.. whatever else..
}
}
m_bIsThreadedFunctionRunning = false;
}
</pre></code>

== Not Waiting For Messages ==
As seen above, it's possible for a thread to fail to receive posted messages because it wasn't waiting for them at the time. A more commonly problematic example follows.

<code><pre>
thread void MyThread(void)
{
wait ()
{
on "Some", "Condition":
HandleSomeCondition();
continue;
on "Thread", "Exit":
break;
}
}

void HandleSomeCondition(void)
{
wait ()
{
on "Some", "End-Condition":
break;
}
}
</pre></code>

In this example, the thread is waiting on both "Some", "Condition" and also "Thread", "Exit". Either one will be handled correctly assuming that the thread is already running at the time they are posted. Even if multiple are posted, the thread will simply queue them and run each in turn.

The problem occurs when HandleSomeCondition() is triggered and the thread begins waiting on "Some", "End-Condition". In this scenario, the thread is no longer waiting on "Thread", "Exit", and any attempt to post that message will simply be ignored. To reiterate: the message dispatch is NOT postponed until the function returns; the message is dropped entirely.

In many cases, the correct behaviour is to move HandleSomeCondition() to a new thread, although that may also carry gotchas that you will need to be careful of (eg. you'll probably want to terminate the second thread at the same time as the first one, and you may need to consider whether you want multiple of the second thread to run simultaneously or not).

== Performing Actions After Being Told to Stop ==
In many cases, you may wish to perform cleanup actions when stopping your rule. If your rule is threaded, this can easily become problematic.

Consider the following pseudocode example:

<code><pre>
void Pause(bool bIsPaused)
{
if (!bIsPaused && !m_bIsThreadRunning)
{
m_bIsThreadRunning = true;
MyThread();
}
}

thread void MyThread(void)
{
BeginRule();
while (!IsPaused())
{
Sleep(0.5);
UpdateRule();
}
EndRule();
m_bIsThreadRunning = false;
}
</pre></code>

There are three immediately obvious problems:

1. That BeginRule() is called when the thread starts, even if the rule has already been paused again.
2. That UpdateRule() will be called after each sleep, even if the rule was paused during the sleep.
3. That EndRule() will be called after the rule has been paused.

This is very problematic because it likely violates a core principles of the rules system: that rules will not undertake any meaningful behaviour when paused. All three functions may be called while the rule is paused, so unless the rule does nothing meaningful at all, this is a guaranteed violation.

The best approach to resolving this may depend on exactly what these functions do, but one possible solution is as follows:

<code><pre>
void Pause(bool bIsPaused)
{
if (bIsPaused)
{
if (m_bNeedsEndRule)
{
m_bNeedsEndRule = false;
EndRule();
}
}
else
{
if (!m_bNeedsEndRule)
{
BeginRule();
m_bNeedsEndRule = true;
}
if (!m_bIsThreadRunning)
{
m_bIsThreadRunning = true;
MyThread();
}
}
}

thread void MyThread(void)
{
while (!IsPaused())
{
UpdateRule();
Sleep(0.5);
}
m_bIsThreadRunning = false;
}
</pre></code>

Session Rule Implementation

2018-11-27T17:02:39Z

Windwalkr:

This page seeks to clearly define expected script behavior for [[KIND Scenariobehavior|Session Rule assets]]. This focuses specifically on correct behavior from the code perspective, rather than addressing how rules should be designed for best gameplay outcomes.

= Legacy Behavior Note =
Please note that many existing rules do not behave correctly as defined here. This is considered a bug in the individual session rules. [[N3V Games]] has a policy of updating session rules to behave correctly even where that may lead to changes of function in existing [[session]] assets. Where reasonable to achieve, emulation of the existing (buggy) behavior may occur for existing rule instances in existing sessions, however any newly created rule instances will use the corrected behavior.

These expectations were codified at the end of [[TS12]] development due to an increasing inability of session rules to work together resulting from the unpredictable nature of their responses to various common use-cases. The systems as a whole, including most of the core rules discussed in this document, have existed for far longer than this document. The document does not redefine any existing systems, but simply presents the only reasonable implementation approach possible if rules are to be expected to work properly in all use-cases. In some cases we also choose to mandate specific points of behavior relating to user expectations rather than technical necessities.

Certain additional API mechanisms were introduced alongside the development of this document, to allow better communication with session authors regarding the differences in behavior between certain types of rule. The correct usage for these mechanisms is also included in this document.

= The Rule Hierarchy =
All rules within a given session form a simple tree structure.

== Rule State Flags ==
Each rule in the tree may have certain associated state flagged, including a combination of the following:

=== PAUSED ===
The rule is currently paused, meaning that it does not affect the game world in any way and does not respond to any changes in the game world. The parent rule must cause the rule to become unpaused for the rule to have any effect. It is not correct behavior for a rule to unpause itself.

=== COMPLETE ===
This flag indicates that rule has fully completed its operation (including any child rule operations) and does not affect the game world in any way. This flag is set by the rule itself, not by an outside entity such as the parent. This state should not be changed while the rule is PAUSED.

Being COMPLETE does not imply being PAUSED. In many scenarios, the parent rule may respond to a child becoming COMPLETE by causing it to also become PAUSED, however this is certainly not guaranteed in all cases, and is not guaranteed to be immediate in the cases where it does happen.

The rule may optionally respond to specific changes in the game world by deflagging the COMPLETE status. For example, a rule which specifically implements a condition check may choose to become COMPLETE when that condition is met, but return to an incomplete state when the condition is no longer met (again, remembering that a change in either direction should only happen while the rule itself is not PAUSED).

When a rule's COMPLETE state changes, a "ScenarioBehavior", "Touch" message is sent '''(TBD: BY WHAT MECHANISM?)''' to its parent rule (if any), unless the parent is in the PAUSED state. This allows the parent to react to changes in its child rules' states. It is important to note that the message indicates a possible change which the parent may be interested in, but it is the parent rule's responsibility to determine whether the state change is worth reacting to.

=== WAS COMPLETE ===
This is typically set when a rule first becomes flagged as COMPLETE, and will stay set even if the rule later flags as incomplete. This can be used by a parent which only cares that the child rule has been flagged as COMPLETE at some point, rather than caring what its current completion status is.

=== DOES COMPLETE ===
This indicates whether the rule can ever reach the COMPLETE state. Its value is constant for a given rule configuration, and does not change based on the runtime rule state or other game state. Rules which are flagged as DOES COMPLETE are expected to become complete after some discreet operations are completed. Rules which are not flagged are expected to run indefinitely unless PAUSED by an external agent (such as the parent rule).

== Initial State ==
All rules are initially in the PAUSED state when in [[Surveyor]], and only become unpaused after gameplay begins in a [[Driver]] session. Since a PAUSED rule is not permitted to unpause itself, this is a stable state which will persist until the native code takes step to begin program flow.

== Top Level Rules ==
All rules at the top level (ie. rules which are not a child of any other rule) simultaneously become unpaused after the session has loaded into Driver. Some of these rules may take initial setup steps and then become COMPLETE. Some of these rules may begin monitoring for specific game conditions before taking any further action. Some of these rules may begin taking action immediately. The rules are not sequenced against each other in any way, and it is the session author's responsibility to ensure that this does not cause any conflicts.

== Scheduling ==
Since the script VM is a cooperatively-threaded environment, it is technically true that rule evaluation will occur in an ordered manner rather than truly simultaneously. However, no guarantees are made regarding the order in which the simultaneously-running rules will perform their checks or outcomes. Since rules may wait internally rather than fulfilling their entire purpose in an atomic operation, it is also not guaranteed that a first-running rule will fully complete before some other simultaneously-executing rule begins completion. In short, if order-of-execution is critical to the correct behavior of a session, then the order should be enforced by the session creator using the rule hierarchy rather than by making assumptions about execution order of simultaneously-running rules.

(Note: with the introduction of [[Asynchronous Route Streaming]], this is even more true than previously. What may have been a near-instantaneous operation in older builds may now require a wait of several seconds while the necessary data is streamed in.)

It is important to note that some conditional rules may partially or completely rely on a polling behavior to evaluate their conditions. (An example of partial reliance is a rule which waits for an event, but then evaluates a condition to clarify whether the event should be acted upon.) In these cases, it is possible that the condition can rapidly become true and then become false again without the rule responding. This results in an uncertainty as to whether the conditional rule will correctly detect a given instance of the condition. This type of scenario should be avoided completely where possible, and should most definitely be limited to outcomes that do not significantly affect gameplay.

For a hypothetical example, if the player's train speeds for 0.5sec, and a speeding check rule was implemented that polled every second, then the overspeed event may or may not trigger on any given occurrence. A session creator should not use this outcome as a failure condition, since some players may be able to speed without penalty, whereas other players would be penalised on the first attempt. A sensible solution in this case might be to increment a counter while speeding is detected, and only take action if the counter reaches a certain threshold. If the only penalty was a warning to the player which had no actual gameplay impact, then it might be acceptable to forgo this check and simply accept that some players will receive a warning where others may not.

==Child Rules==
As with all other rules, child rules (ie. those that have parent rules in the hierarchy) start out in the PAUSED state. They do not become unpaused until the parent is ready for the children to start operating. Exactly when this occurs depends on the specific parent rule, but the general flow is the same for all rules:

1. Parent rule becomes unpaused and begins operation.
2. Parent rule configures any necessary world state changes.
3. Parent rule optionally waits for a specific condition to occur.
4. Parent rule begins executing its children. This involves unpausing one or more of the children (as discussed below in "Parent Rule Styles").
5. Parent waits for its children to complete (as discussed below in "Parent Rule Styles") and then pauses the children.
6. Parent flags itself as COMPLETE.

This process allows program control flow to pass from a top-level rule, to its immediate children, to their immediate children, and so on. As the bottom-level children become complete, completion flows back to the higher level children until finally the top-level rules become COMPLETE.

It is worth noting that there is nothing special about a top-level rule being flagged as COMPLETE. This does not indicate an end-of-session or any other fundamental gameplay mode change. Since the pausing of rules on completion is handled by the parent rule (see step 5 above), the top-level rules never become PAUSED on completion.

==Parent Rule Styles==
There are a few common techniques with which parent rules interact with their children. Rules should always fit one of these descriptions. The vast majority of rules should follow either the "Does Not Support Children" style, or the "Ordered Execution of Children" style.

=== Does Not Support Children ===
The rule is incapable of supporting children and will always ignore them.

This is used for trivial rules which perform a set function and then become permanently COMPLETE. Such rules are not conditional and do not wait for any world state changes except those which they initiate internally.
The rule should be configured to validate and/or enforce that no child rules can be added.

=== Simultaneous Execution of Children ===
When the rule is ready to begin executing children, it unpauses all children simultaneously. The rule then waits for all children to flag as WAS COMPLETE. Once this is detected, the rule pauses all children and flags itself as COMPLETE.
This is used for rules which have a specific need to simultaneously execute children, such as the "Simultaneous List" rule.

The rule editor interface should be explicit that child rules will be executed simultaneously. Child rules should be tagged appropriately in the rule editor list to denote unordered execution.

=== Ordered Execution of Children ===
When the rule is ready to begin executing children, it iterates through the children in top-to-bottom order. If the child is flagged as WAS COMPLETE, the child is paused and iteration continues. If the child is not flagged as WAS COMPLETE, the child is unpaused and iteration ends. Whenever a child state change is detected, this process is repeated from the start. Once iteration passes over all children without leaving any child unpaused, the rule flags itself as COMPLETE.

This style is used for all rules which do not explicitly fall under one of the other styles described here. Almost all third-party rules will follow this style. Implementing one of the other styles without there being a fundamental requirement to do so is considered a programming error.

Rules which follow this style should derive from ConditionalScenarioBehavior in order to avoid re-implementing the control flow logic, as it is exceedingly complex to implement correctly. Any rules which do not derive from ConditionalScenarioBehavior should be accompanied by a clear explanation of the reasons that ConditionalScenarioBehavior is an unsuitable base class for the intended behavior. Rules which do derive from ConditionalScenarioBehavior should avoid complex overrides of the default logic.

Child rules should be tagged appropriately in the rule editor list to denote execution order.

=== Controlled Selection of a Single Child ===
When the rule is ready to begin executing children, it selects a single child and unpauses it. All other children remain paused. Once the selected child becomes flagged as WAS COMPLETE, the child is paused and the rule flags itself as COMPLETE.

This style is used where complex conditional selection of child rules is required. This can be used to implement an "if-else" logic flow, a "switch-case" logic flow, or the "Random List" rule. This style should not be used to implement a simple "if" logic flow, because that would unnecessarily restrict the rule to a single child where the "Ordered Execution of Children" style would provide the same functionality while allowing multiple children.
The rule editor interface should be very explicit about how the child rules will be selected. Child rules should be tagged appropriately in the rule editor list to avoid the user attempting to fit a child rule into the wrong role.

=== Custom Execution with Multiple Children ===
This style is used for very specific custom-purpose rules, such as a passenger station stop handler. Such rules should give a clear and complete explanation of their operation and their interaction with any child rules in the rule editor interface.

Individual child rules may be executed in an ad-hoc manner by the rule in response to changes in game state. Child rules may or may not be executed simultaneously and may or may not be executed repeatedly depending on the rule; any limitations or gotchas deriving from this should be carefully explained in the rule editor interface.

Child rules should be tagged appropriately in the rule editor list to avoid the user attempting to fit a child rule into the wrong role.

= Early Termination via Pause =
A rule must accept being paused by its parent at any time. This should cause the rule to cease any game state monitoring or other direct effects. The rule must pause all child rules immediately.

In cases where the rule is maintaining some reversible effect on the game world, pausing the rule should end this effect. For example, a rule which displays a message to the user should typically hide the message upon becoming paused, and a rule which causes a rain storm in a specific area should return the weather to normal upon becoming paused. Rules which make a single permanent change to the game world and then immediately flag as COMPLETE should not attempt to reverse the change upon becoming paused. Examples of these rules include configuration of the global weather conditions, or a rule which increments the player's score or penalty counter.

It is important to note that any pause is resumable, although the parent may not choose to take advantage of this. Pausing a rule followed by unpausing it should result in the rule continuing operation where it left off. The notes on Saving and Loading Driver Sessions (below) are worth considering when evaluating techniques for implementing pause.

= Early Termination via Internal Logic =
In some cases, a rule may begin executing child rules but then make an internal decision to abort execution. This typically occurs in conditional rules where the condition may be re-evaluated as false after it has already been evaluated as true. Such behavior should be made explicit in the rule editor interface and should usually be made optional by providing a checkbox.

There are in fact several possible behavioral variants affecting how condition-deflag is interpreted:
* Once the condition is flagged, the rule starts executing child rules and no further evaluation is performed. The rule eventually flags itself as COMPLETE and does not later deflag this.
* Once the condition is flagged, the rule starts executing child rules. If the condition becomes deflagged, the child rules are paused. If the condition becomes flagged again, the child rules are continued. Once the child rules have fully completed execution, the rule flags itself as COMPLETE and does not later deflag this.
* Once the condition is flagged, the rule starts executing child rules. If the condition becomes deflagged, the child rules are paused. If the condition becomes flagged again, the children are reset and execution starts anew. The rule flags itself as COMPLETE if all children successfully complete, but it will deflag if the condition deflags.
* Once the condition is flagged, the rule starts executing child rules. If the condition becomes deflagged, the child rules continue executing. If the condition becomes flagged again, the children are reset and execution starts anew. The rule will flag as COMPLETE if all children successfully complete, but it will deflag if the condition deflags.
* Once the condition is flagged, the rule starts executing child rules. The child rules continue execution with no regard for whether the condition changes between flagged or deflagged in either direction. If the condition transitions from deflagged to flagged again after the children have completed, the children are reset and execution starts anew. The rule will flag as COMPLETE if all children successfully complete, but it will deflag itself if the condition deflags.

The complexity here derives from the fact that it is not possible to use the same set of rules multiple times concurrently for different trigger conditions. For example, if a set of rules is used to give demerit points and provide user notifications, and those rules live under a single conditional check which determines whether a train is speeding, it may be difficult to define what should happen if two trains are detected as speeding at the same time, or if a train stops speeding while the notification process is still in progress. It is not always possible to achieve a perfect solution to tracking multiple objects using a single set of rules, but correct selection from the above behaviors can minimise the possibility of serious side-effects.

It is important to note that these behaviors describe how the rule reacts to internal condition checks. The rule's reaction to being paused by its parent is discussed above under "Early Termination via Pause" and is not affected by the description here.

In short, there are many ways of handling this, and the important thing is for your (parent) rule to clearly explain which approach it is going to use.

= Rule Reset =
A rule may be ''reset'' by its parent. This causes both the COMPLETE and WAS COMPLETE states to be deflagged. Individual rules may also react to the reset by modifying their internal state to forget past or present actions. Parent rules must also cause their children to be reset in turn.

This mechanism is used to permit rules to be used in a repeating scenario, such as responding to a condition which can occur multiple times, or in a repeating loop. At some point after a rule has become flagged as WAS COMPLETE, it will typically become paused and will not be unpaused again. If the rule is to be included in some repeating behavior, this would normally prevent the behavior from operating successfully after the first run through. To avoid this, the parent rule responsible for implementing the repeating behavior will ''reset'' all children when a repeat occurs. This effectively cleans the rules back to their initial state ready to perform their roles again.

It is important to note that a reset should cause the rule to return to its configured settings. For example, if a timer value is configured and is decremented during rule operation, the timer must be reset back to its initial value during rule reset.

It is important to note that there is no requirement to pause a rule prior to resetting it.

= Saving and Loading Driver Sessions =
For better or worse, the script VM does not persist across a save/load operation. This means that each rule must correctly save both its configuration state and its runtime state, and must correctly reload those such that the state after a save/load operation is indistinguishable from the original state. The following aspects of the script state must be considered:

* Member variables in the Rule instance.
* Which threads are running on the Rule instance, and where they are up to in the code flow.
* Local variables on the stack of each running thread.
* Non-persistent changes made to the state of other script objects (such as active 'sniff' statements).
* Script Messages which might be in flight at the time of save (these are not persisted, so the net effect is that they are simply deleted between the save and the load.)

Since the game state continues normal operation after a Save, no code flow or other behavioral changes should result from the Save operation itself. Instead, the Save operation (and the design of the rule as a whole) is responsible for ensuring that sufficient data is persisted in the save file such that the Load operation is able to restore to the correct running state.

The rule base class, ScenarioBehavior, is responsible for saving and loading the rule state flags (COMPLETE, PAUSED, WAS COMPLETE, etc.) A rule which was paused at Save time will still be paused after the Load. A rule which was complete at Save time will still be complete after the Load. During a Load operation, the rule should inherit the parent class' SetProperties() method so that these flags are correctly configured, then honor the paused state during the rest of the loading process.

It is rarely appropriate for an unpaused rule to simply restart execution from the beginning. Care must be taken to ensure that execution resumes from the point that it left off at the time of saving. This process can be simplified by keeping as much state as possible in the rule member variables at all times, and only keeping reconstructible temporary values on the stack. If the member variables are correctly stored and restored, this approach will allow the loading process to detect the runtime state of the rule and resume any necessary threads, which will in turn be able to jump forward to the correct area of the code based on the stored state.

Finally, the COMPLETE, WAS COMPLETE, and PAUSED flags on child rules should be honored. This is typically sufficient information to determine the running state of child rules, so no further state will generally need to be maintained. More accurately, the child rules take care of their own state at all times, and the parent only needs to react to changes in the child state. Since no child state change occurs across a Save/Load operation, the parent does not need to become involved.

For rules which derive ConditionalScenarioBehavior, the majority of load/save logic is handled automatically. The only state information that such a rule should typically preserve is the instance-specific configuration data. The condition-monitor thread will be automatically restarted as required, and there is generally no need to distinguish between a first-startup and any subsequent startup.

= Spurious Events =
There are various events (typically script messages) that a rule may listen for in order to detect state changes. It is important to note that spurious events are often possible, and that an event handler should often be coupled with a condition check. As a specific example, the "ScenarioBehavior", "Touch" message typically indicates that a child state has changed, but the message may in fact be sent at any time. This message should prompt the rule to evaluate whether any state changes are necessary, but the rule should not simply assume that a state change is necessary without performing an evaluation.

Similarly, calls to a function such as Pause() may in some cases have no effect. For example, if a rule is already executing and its parent calls Pause(false), the rule should not pause, reset, or change state in any way at all. Similarly, if a rule is already paused and its parent calls Pause(true), the rule should not unpause, reset, fire any events, or otherwise change state in any way at all.

The short version is: do not assume that every event and every method call is supposed to achieve something meaningful. Check first, and if the event is meaningless to you then do nothing at all.

= Future Considerations =
Rules should base their functionality on the state flags such as the PAUSED state, rather than attempting to detect and vary their functionality based on the state of the game.

For example, we currently (in development builds) expose the rules editor in Driver for debugging purposes. This, or some mechanism like it, is likely to be included in public builds in the future. Rules should not assume that it is impossible to be reconfigured during gameplay. This will of course introduce some side effects, such as when an unpaused rule is modified during execution. It is the rule's responsibility to ensure that these side effects do not lead to script exceptions or to leaked state. For example, if a single thread is supposed to be running, reconfiguring the rule should not cause a second thread to run simultaneously. If a rule sniffs a target vehicle, and the target vehicle is redefined, then the rule should unsniff the original vehicle rather than now sniffing two vehicles.

Likewise, we may in future allow some form of partial state swap between Driver and Surveyor. Rules should not assume that it is impossible to change from any one game state or module to any other game state or module, just because it is not possible at the current time. APIs already exist to detect such state changes where necessary, and in most cases it's simply not necessary to care whether your rule is in Surveyor or Driver - you should act based on the PAUSED state instead. Rules should deal with the game state as they find it rather than assuming that certain states will not ever occur.

= Gotchas =
There are a few potential gotchas in the script environment that are worth considering when writing any non-trivial rule.

== Response Latency ==
Scripts tend to rely heavily on message passing and threading. In both cases, there is a delay between triggering a certain behavior (eg. posting an event, or calling a threaded function) and having the receiving code react. Other code may execute during this delay.

<code><pre>
// Calling this might be expected to start and then stop the thread; in reality it
// will likely simply start the thread and leave it running, because the message
// is sent prior to the wait() statement starting.
void DemonstrateBug1(void)
{
Pause(false);
Pause(true);
}

// In this case, we use a Sleep() statement to "ensure" that the thread has
// finished starting. This isn't actually reliable, but it works as long as the
// system isn't under too much load. We follow this up with a rapid pause-
// unpause sequence. As above, this doesn't work - the message is sent,
// then the function immediately checks whether the thread is still running
// (which it is) and thus the thread isn't restarted. The function completes,
// and finally the thread receives the message and exits.
void DemonstrateBug2(void)
{
Pause(false);
Sleep(1.0);
Pause(true);
Pause(false);
}

// Helper code for the above functions.
void Pause(bool bIsPaused)
{
if (bIsPaused)
{
PostMessage(me, "ThisRule", "Pause");
}
else if (!m_bIsThreadRunning)
{
m_bIsThreadRunning = true;
StartThread();
}
}
thread void StartThread(void)
{
while (true)
{
wait ()
{
on "ThisRule", "Pause":
break;
...
}
m_bIsThreadRunning = false;
}
</pre></code>

== Multiple Messages in Flight ==
It's possible to post multiple identical messages. This can be useful, but if you're expecting only one then it can be a source of errors.

In the following pseudocode, each call to SetProperties() will place an additional "Timer", "Tick" message into the cycle, effectively increasing the rate at which the IdleFunction is called. This will seem to be working for a single call to SetProperties(), which may be all that is called during a trivial testcase. It will probably give reasonable results for a few calls to SetProperties(), although if the function is time-sensitive then the results might be different to expectations. After a larger number of calls to SetProperties(), the object's message queue may become full, causing it to lose messages at random (perhaps the tick messages, or perhaps other unrelated messages that are more problematic).

<code><pre>
void Init(void)
{
inherited();

AddHandler(me, "Timer", "Tick", "IdleFunction");
}

void EnterIdleState(void)
{
IdleFunction();
}

void IdleFunction(void)
{
PostMessage(me, "Timer", "Tick", 1.0);
.. do something here ..
}

void SetProperties(Soup soup)
{
inherited(soup);

EnterIdleState();
}

</pre></code>

A similar problem can occur if you start new threads rather than post new messages.

== Thread Guard Variables ==
It's common to prevent a singleton thread from being started twice by using a boolean guard variable. Care must be taken to ensure that the guard variable is set and cleared at the correct locations, or they may be ineffective.

The following pseudocode demonstrates one such correct usage. The key points to note are:
* We set 'm_bIsThreadedFunctionRunning' prior to calling the threaded function. Setting it within the threaded function is too late; multiple threads might have already been started before the first thread reaches that point.
* We don't confuse whether the thread is actually running with whether we want the thread to be running. Once we ask a thread to start, we can't stop it starting. If we change our minds and want to stop it again, we must inform it in a way that it will realise after it finishes starting. In the worst-case scenario, we might flipflop on this multiple times before the thread actually starts.
* Similarly, we don't rely on messages to control the thread. Enqueuing a separate start or stop message with each StartThread()/StopThread() call might be possible, and we could clear any unwanted prior messages from the object's queue, but if the thread hasn't finished starting then it won't receive the messages anyway.
* We do rely on messages to wake the thread if it's waiting on messages, but we don't use those messages to imply any state - we just have it recheck the current state boolean to get the very latest info.
* We clear 'm_bIsThreadedFunctionRunning' once the decision to exit has become unconditional. At this point, even though the thread is technically still running, we'll have to start a new thread if we want the thread to continue running.

<code><pre>
bool m_bIsThreadedFunctionRunning = false;
bool m_bWantThreadedFunctionRunning = false;

void StartThread(void)
{
m_bWantThreadedFunctionRunning = true;

if (m_bIsThreadedFunctionRunning)
return;

m_bIsThreadedFunctionRunning = true;
ThreadedFunction();
}

void StopThread(void)
{
if (!m_bWantThreadedFunctionRunning)
return;

m_bWantThreadedFunctionRunning = false;
PostMessage(me, "Thread", "Touch");
}

thread void ThreadedFunction(void)
{
while (m_bWantThreadedFunctionRunning)
{
wait()
{
on "Thread", "Touch":
break;
.. whatever else..
}
}
m_bIsThreadedFunctionRunning = false;
}
</pre></code>

== Not Waiting For Messages ==
As seen above, it's possible for a thread to fail to receive posted messages because it wasn't waiting for them at the time. A more commonly problematic example follows.

<code><pre>
thread void MyThread(void)
{
wait ()
{
on "Some", "Condition":
HandleSomeCondition();
continue;
on "Thread", "Exit":
break;
}
}

void HandleSomeCondition(void)
{
wait ()
{
on "Some", "End-Condition":
break;
}
}
</pre></code>

In this example, the thread is waiting on both "Some", "Condition" and also "Thread", "Exit". Either one will be handled correctly assuming that the thread is already running at the time they are posted. Even if multiple are posted, the thread will simply queue them and run each in turn.

The problem occurs when HandleSomeCondition() is triggered and the thread begins waiting on "Some", "End-Condition". In this scenario, the thread is no longer waiting on "Thread", "Exit", and any attempt to post that message will simply be ignored. To reiterate: the message dispatch is NOT postponed until the function returns; the message is dropped entirely.

In many cases, the correct behaviour is to move HandleSomeCondition() to a new thread, although that may also carry gotchas that you will need to be careful of (eg. you'll probably want to terminate the second thread at the same time as the first one, and you may need to consider whether you want multiple of the second thread to run simultaneously or not).

== Performing Actions After Being Told to Stop ==
In many cases, you may wish to perform cleanup actions when stopping your rule. If your rule is threaded, this can easily become problematic.

Consider the following pseudocode example:

<code><pre>
void Pause(bool bIsPaused)
{
if (!bIsPaused && !m_bIsThreadRunning)
{
m_bIsThreadRunning = true;
MyThread();
}
}
thread void MyThread(void)
{
BeginRule();
while (!IsPaused())
{
Sleep(0.5);
UpdateRule();
}
EndRule();
m_bIsThreadRunning = false;
}
</pre></code>

There are three immediately obvious problems:

1. That BeginRule() is called when the thread starts, even if the rule has already been paused again.
2. That UpdateRule() will be called after each sleep, even if the rule was paused during the sleep.
3. That EndRule() will be called after the rule has been paused.

This is very problematic because it likely violates a core principles of the rules system: that rules will not undertake any meaningful behaviour when paused. All three functions may be called while the rule is paused, so unless the rule does nothing meaningful at all, this is a guaranteed violation.

The best approach to resolving this may depend on exactly what these functions do, but one possible solution is as follows:

<code><pre>
void Pause(bool bIsPaused)
{
if (bIsPaused)
{
if (m_bNeedsEndRule)
{
m_bNeedsEndRule = false;
EndRule();
}
}
else
{
if (!m_bNeedsEndRule)
{
BeginRule();
m_bNeedsEndRule = true;
}
if (!m_bIsThreadRunning)
{
m_bIsThreadRunning = true;
MyThread();
}
}
}
thread void MyThread(void)
{
while (!IsPaused())
{
UpdateRule();
Sleep(0.5);
}
m_bIsThreadRunning = false;
}
</pre></code>

Session Rule Implementation

2018-11-27T16:44:01Z

Windwalkr:

This page seeks to clearly define expected script behavior for [[KIND Scenariobehavior|Session Rule assets]]. This focuses specifically on correct behavior from the code perspective, rather than addressing how rules should be designed for best gameplay outcomes.

= Legacy Behavior Note =
Please note that many existing rules do not behave correctly as defined here. This is considered a bug in the individual session rules. [[N3V Games]] has a policy of updating session rules to behave correctly even where that may lead to changes of function in existing [[session]] assets. Where reasonable to achieve, emulation of the existing (buggy) behavior may occur for existing rule instances in existing sessions, however any newly created rule instances will use the corrected behavior.

These expectations were codified at the end of [[TS12]] development due to an increasing inability of session rules to work together resulting from the unpredictable nature of their responses to various common use-cases. The systems as a whole, including most of the core rules discussed in this document, have existed for far longer than this document. The document does not redefine any existing systems, but simply presents the only reasonable implementation approach possible if rules are to be expected to work properly in all use-cases. In some cases we also choose to mandate specific points of behavior relating to user expectations rather than technical necessities.

Certain additional API mechanisms were introduced alongside the development of this document, to allow better communication with session authors regarding the differences in behavior between certain types of rule. The correct usage for these mechanisms is also included in this document.

= The Rule Hierarchy =
All rules within a given session form a simple tree structure.

== Rule State Flags ==
Each rule in the tree may have certain associated state flagged, including a combination of the following:

=== PAUSED ===
The rule is currently paused, meaning that it does not affect the game world in any way and does not respond to any changes in the game world. The parent rule must cause the rule to become unpaused for the rule to have any effect. It is not correct behavior for a rule to unpause itself.

=== COMPLETE ===
This flag indicates that rule has fully completed its operation (including any child rule operations) and does not affect the game world in any way. This flag is set by the rule itself, not by an outside entity such as the parent. This state should not be changed while the rule is PAUSED.

Being COMPLETE does not imply being PAUSED. In many scenarios, the parent rule may respond to a child becoming COMPLETE by causing it to also become PAUSED, however this is certainly not guaranteed in all cases, and is not guaranteed to be immediate in the cases where it does happen.

The rule may optionally respond to specific changes in the game world by deflagging the COMPLETE status. For example, a rule which specifically implements a condition check may choose to become COMPLETE when that condition is met, but return to an incomplete state when the condition is no longer met (again, remembering that a change in either direction should only happen while the rule itself is not PAUSED).

When a rule's COMPLETE state changes, a "ScenarioBehavior", "Touch" message is sent '''(TBD: BY WHAT MECHANISM?)''' to its parent rule (if any), unless the parent is in the PAUSED state. This allows the parent to react to changes in its child rules' states. It is important to note that the message indicates a possible change which the parent may be interested in, but it is the parent rule's responsibility to determine whether the state change is worth reacting to.

=== WAS COMPLETE ===
This is typically set when a rule first becomes flagged as COMPLETE, and will stay set even if the rule later flags as incomplete. This can be used by a parent which only cares that the child rule has been flagged as COMPLETE at some point, rather than caring what its current completion status is.

=== DOES COMPLETE ===
This indicates whether the rule can ever reach the COMPLETE state. Its value is constant for a given rule configuration, and does not change based on the runtime rule state or other game state. Rules which are flagged as DOES COMPLETE are expected to become complete after some discreet operations are completed. Rules which are not flagged are expected to run indefinitely unless PAUSED by an external agent (such as the parent rule).

== Initial State ==
All rules are initially in the PAUSED state when in [[Surveyor]], and only become unpaused after gameplay begins in a [[Driver]] session. Since a PAUSED rule is not permitted to unpause itself, this is a stable state which will persist until the native code takes step to begin program flow.

== Top Level Rules ==
All rules at the top level (ie. rules which are not a child of any other rule) simultaneously become unpaused after the session has loaded into Driver. Some of these rules may take initial setup steps and then become COMPLETE. Some of these rules may begin monitoring for specific game conditions before taking any further action. Some of these rules may begin taking action immediately. The rules are not sequenced against each other in any way, and it is the session author's responsibility to ensure that this does not cause any conflicts.

== Scheduling ==
Since the script VM is a cooperatively-threaded environment, it is technically true that rule evaluation will occur in an ordered manner rather than truly simultaneously. However, no guarantees are made regarding the order in which the simultaneously-running rules will perform their checks or outcomes. Since rules may wait internally rather than fulfilling their entire purpose in an atomic operation, it is also not guaranteed that a first-running rule will fully complete before some other simultaneously-executing rule begins completion. In short, if order-of-execution is critical to the correct behavior of a session, then the order should be enforced by the session creator using the rule hierarchy rather than by making assumptions about execution order of simultaneously-running rules.

(Note: with the introduction of [[Asynchronous Route Streaming]], this is even more true than previously. What may have been a near-instantaneous operation in older builds may now require a wait of several seconds while the necessary data is streamed in.)

It is important to note that some conditional rules may partially or completely rely on a polling behavior to evaluate their conditions. (An example of partial reliance is a rule which waits for an event, but then evaluates a condition to clarify whether the event should be acted upon.) In these cases, it is possible that the condition can rapidly become true and then become false again without the rule responding. This results in an uncertainty as to whether the conditional rule will correctly detect a given instance of the condition. This type of scenario should be avoided completely where possible, and should most definitely be limited to outcomes that do not significantly affect gameplay.

For a hypothetical example, if the player's train speeds for 0.5sec, and a speeding check rule was implemented that polled every second, then the overspeed event may or may not trigger on any given occurrence. A session creator should not use this outcome as a failure condition, since some players may be able to speed without penalty, whereas other players would be penalised on the first attempt. A sensible solution in this case might be to increment a counter while speeding is detected, and only take action if the counter reaches a certain threshold. If the only penalty was a warning to the player which had no actual gameplay impact, then it might be acceptable to forgo this check and simply accept that some players will receive a warning where others may not.

==Child Rules==
As with all other rules, child rules (ie. those that have parent rules in the hierarchy) start out in the PAUSED state. They do not become unpaused until the parent is ready for the children to start operating. Exactly when this occurs depends on the specific parent rule, but the general flow is the same for all rules:

1. Parent rule becomes unpaused and begins operation.
2. Parent rule configures any necessary world state changes.
3. Parent rule optionally waits for a specific condition to occur.
4. Parent rule begins executing its children. This involves unpausing one or more of the children (as discussed below in "Parent Rule Styles").
5. Parent waits for its children to complete (as discussed below in "Parent Rule Styles") and then pauses the children.
6. Parent flags itself as COMPLETE.

This process allows program control flow to pass from a top-level rule, to its immediate children, to their immediate children, and so on. As the bottom-level children become complete, completion flows back to the higher level children until finally the top-level rules become COMPLETE.

It is worth noting that there is nothing special about a top-level rule being flagged as COMPLETE. This does not indicate an end-of-session or any other fundamental gameplay mode change. Since the pausing of rules on completion is handled by the parent rule (see step 5 above), the top-level rules never become PAUSED on completion.

==Parent Rule Styles==
There are a few common techniques with which parent rules interact with their children. Rules should always fit one of these descriptions. The vast majority of rules should follow either the "Does Not Support Children" style, or the "Ordered Execution of Children" style.

=== Does Not Support Children ===
The rule is incapable of supporting children and will always ignore them.

This is used for trivial rules which perform a set function and then become permanently COMPLETE. Such rules are not conditional and do not wait for any world state changes except those which they initiate internally.
The rule should be configured to validate and/or enforce that no child rules can be added.

=== Simultaneous Execution of Children ===
When the rule is ready to begin executing children, it unpauses all children simultaneously. The rule then waits for all children to flag as WAS COMPLETE. Once this is detected, the rule pauses all children and flags itself as COMPLETE.
This is used for rules which have a specific need to simultaneously execute children, such as the "Simultaneous List" rule.

The rule editor interface should be explicit that child rules will be executed simultaneously. Child rules should be tagged appropriately in the rule editor list to denote unordered execution.

=== Ordered Execution of Children ===
When the rule is ready to begin executing children, it iterates through the children in top-to-bottom order. If the child is flagged as WAS COMPLETE, the child is paused and iteration continues. If the child is not flagged as WAS COMPLETE, the child is unpaused and iteration ends. Whenever a child state change is detected, this process is repeated from the start. Once iteration passes over all children without leaving any child unpaused, the rule flags itself as COMPLETE.

This style is used for all rules which do not explicitly fall under one of the other styles described here. Almost all third-party rules will follow this style. Implementing one of the other styles without there being a fundamental requirement to do so is considered a programming error.

Rules which follow this style should derive from ConditionalScenarioBehavior in order to avoid re-implementing the control flow logic, as it is exceedingly complex to implement correctly. Any rules which do not derive from ConditionalScenarioBehavior should be accompanied by a clear explanation of the reasons that ConditionalScenarioBehavior is an unsuitable base class for the intended behavior. Rules which do derive from ConditionalScenarioBehavior should avoid complex overrides of the default logic.

Child rules should be tagged appropriately in the rule editor list to denote execution order.

=== Controlled Selection of a Single Child ===
When the rule is ready to begin executing children, it selects a single child and unpauses it. All other children remain paused. Once the selected child becomes flagged as WAS COMPLETE, the child is paused and the rule flags itself as COMPLETE.

This style is used where complex conditional selection of child rules is required. This can be used to implement an "if-else" logic flow, a "switch-case" logic flow, or the "Random List" rule. This style should not be used to implement a simple "if" logic flow, because that would unnecessarily restrict the rule to a single child where the "Ordered Execution of Children" style would provide the same functionality while allowing multiple children.
The rule editor interface should be very explicit about how the child rules will be selected. Child rules should be tagged appropriately in the rule editor list to avoid the user attempting to fit a child rule into the wrong role.

=== Custom Execution with Multiple Children ===
This style is used for very specific custom-purpose rules, such as a passenger station stop handler. Such rules should give a clear and complete explanation of their operation and their interaction with any child rules in the rule editor interface.

Individual child rules may be executed in an ad-hoc manner by the rule in response to changes in game state. Child rules may or may not be executed simultaneously and may or may not be executed repeatedly depending on the rule; any limitations or gotchas deriving from this should be carefully explained in the rule editor interface.

Child rules should be tagged appropriately in the rule editor list to avoid the user attempting to fit a child rule into the wrong role.

= Early Termination via Pause =
A rule must accept being paused by its parent at any time. This should cause the rule to cease any game state monitoring or other direct effects. The rule must pause all child rules immediately.

In cases where the rule is maintaining some reversible effect on the game world, pausing the rule should end this effect. For example, a rule which displays a message to the user should typically hide the message upon becoming paused, and a rule which causes a rain storm in a specific area should return the weather to normal upon becoming paused. Rules which make a single permanent change to the game world and then immediately flag as COMPLETE should not attempt to reverse the change upon becoming paused. Examples of these rules include configuration of the global weather conditions, or a rule which increments the player's score or penalty counter.

It is important to note that any pause is resumable, although the parent may not choose to take advantage of this. Pausing a rule followed by unpausing it should result in the rule continuing operation where it left off. The notes on Saving and Loading Driver Sessions (below) are worth considering when evaluating techniques for implementing pause.

= Early Termination via Internal Logic =
In some cases, a rule may begin executing child rules but then make an internal decision to abort execution. This typically occurs in conditional rules where the condition may be re-evaluated as false after it has already been evaluated as true. Such behavior should be made explicit in the rule editor interface and should usually be made optional by providing a checkbox.

There are in fact several possible behavioral variants affecting how condition-deflag is interpreted:
* Once the condition is flagged, the rule starts executing child rules and no further evaluation is performed. The rule eventually flags itself as COMPLETE and does not later deflag this.
* Once the condition is flagged, the rule starts executing child rules. If the condition becomes deflagged, the child rules are paused. If the condition becomes flagged again, the child rules are continued. Once the child rules have fully completed execution, the rule flags itself as COMPLETE and does not later deflag this.
* Once the condition is flagged, the rule starts executing child rules. If the condition becomes deflagged, the child rules are paused. If the condition becomes flagged again, the children are reset and execution starts anew. The rule flags itself as COMPLETE if all children successfully complete, but it will deflag if the condition deflags.
* Once the condition is flagged, the rule starts executing child rules. If the condition becomes deflagged, the child rules continue executing. If the condition becomes flagged again, the children are reset and execution starts anew. The rule will flag as COMPLETE if all children successfully complete, but it will deflag if the condition deflags.
* Once the condition is flagged, the rule starts executing child rules. The child rules continue execution with no regard for whether the condition changes between flagged or deflagged in either direction. If the condition transitions from deflagged to flagged again after the children have completed, the children are reset and execution starts anew. The rule will flag as COMPLETE if all children successfully complete, but it will deflag itself if the condition deflags.

The complexity here derives from the fact that it is not possible to use the same set of rules multiple times concurrently for different trigger conditions. For example, if a set of rules is used to give demerit points and provide user notifications, and those rules live under a single conditional check which determines whether a train is speeding, it may be difficult to define what should happen if two trains are detected as speeding at the same time, or if a train stops speeding while the notification process is still in progress. It is not always possible to achieve a perfect solution to tracking multiple objects using a single set of rules, but correct selection from the above behaviors can minimise the possibility of serious side-effects.

It is important to note that these behaviors describe how the rule reacts to internal condition checks. The rule's reaction to being paused by its parent is discussed above under "Early Termination via Pause" and is not affected by the description here.

In short, there are many ways of handling this, and the important thing is for your (parent) rule to clearly explain which approach it is going to use.

= Rule Reset =
A rule may be ''reset'' by its parent. This causes both the COMPLETE and WAS COMPLETE states to be deflagged. Individual rules may also react to the reset by modifying their internal state to forget past or present actions. Parent rules must also cause their children to be reset in turn.

This mechanism is used to permit rules to be used in a repeating scenario, such as responding to a condition which can occur multiple times, or in a repeating loop. At some point after a rule has become flagged as WAS COMPLETE, it will typically become paused and will not be unpaused again. If the rule is to be included in some repeating behavior, this would normally prevent the behavior from operating successfully after the first run through. To avoid this, the parent rule responsible for implementing the repeating behavior will ''reset'' all children when a repeat occurs. This effectively cleans the rules back to their initial state ready to perform their roles again.

It is important to note that a reset should cause the rule to return to its configured settings. For example, if a timer value is configured and is decremented during rule operation, the timer must be reset back to its initial value during rule reset.

It is important to note that there is no requirement to pause a rule prior to resetting it.

= Saving and Loading Driver Sessions =
For better or worse, the script VM does not persist across a save/load operation. This means that each rule must correctly save both its configuration state and its runtime state, and must correctly reload those such that the state after a save/load operation is indistinguishable from the original state. The following aspects of the script state must be considered:

* Member variables in the Rule instance.
* Which threads are running on the Rule instance, and where they are up to in the code flow.
* Local variables on the stack of each running thread.
* Non-persistent changes made to the state of other script objects (such as active 'sniff' statements).
* Script Messages which might be in flight at the time of save (these are not persisted, so the net effect is that they are simply deleted between the save and the load.)

Since the game state continues normal operation after a Save, no code flow or other behavioral changes should result from the Save operation itself. Instead, the Save operation (and the design of the rule as a whole) is responsible for ensuring that sufficient data is persisted in the save file such that the Load operation is able to restore to the correct running state.

The rule base class, ScenarioBehavior, is responsible for saving and loading the rule state flags (COMPLETE, PAUSED, WAS COMPLETE, etc.) A rule which was paused at Save time will still be paused after the Load. A rule which was complete at Save time will still be complete after the Load. During a Load operation, the rule should inherit the parent class' SetProperties() method so that these flags are correctly configured, then honor the paused state during the rest of the loading process.

It is rarely appropriate for an unpaused rule to simply restart execution from the beginning. Care must be taken to ensure that execution resumes from the point that it left off at the time of saving. This process can be simplified by keeping as much state as possible in the rule member variables at all times, and only keeping reconstructible temporary values on the stack. If the member variables are correctly stored and restored, this approach will allow the loading process to detect the runtime state of the rule and resume any necessary threads, which will in turn be able to jump forward to the correct area of the code based on the stored state.

Finally, the COMPLETE, WAS COMPLETE, and PAUSED flags on child rules should be honored. This is typically sufficient information to determine the running state of child rules, so no further state will generally need to be maintained. More accurately, the child rules take care of their own state at all times, and the parent only needs to react to changes in the child state. Since no child state change occurs across a Save/Load operation, the parent does not need to become involved.

For rules which derive ConditionalScenarioBehavior, the majority of load/save logic is handled automatically. The only state information that such a rule should typically preserve is the instance-specific configuration data. The condition-monitor thread will be automatically restarted as required, and there is generally no need to distinguish between a first-startup and any subsequent startup.

= Spurious Events =
There are various events (typically script messages) that a rule may listen for in order to detect state changes. It is important to note that spurious events are often possible, and that an event handler should often be coupled with a condition check. As a specific example, the "ScenarioBehavior", "Touch" message typically indicates that a child state has changed, but the message may in fact be sent at any time. This message should prompt the rule to evaluate whether any state changes are necessary, but the rule should not simply assume that a state change is necessary without performing an evaluation.

Similarly, calls to a function such as Pause() may in some cases have no effect. For example, if a rule is already executing and its parent calls Pause(false), the rule should not pause, reset, or change state in any way at all. Similarly, if a rule is already paused and its parent calls Pause(true), the rule should not unpause, reset, fire any events, or otherwise change state in any way at all.

The short version is: do not assume that every event and every method call is supposed to achieve something meaningful. Check first, and if the event is meaningless to you then do nothing at all.

= Future Considerations =
Rules should base their functionality on the state flags such as the PAUSED state, rather than attempting to detect and vary their functionality based on the state of the game.

For example, we currently (in development builds) expose the rules editor in Driver for debugging purposes. This, or some mechanism like it, is likely to be included in public builds in the future. Rules should not assume that it is impossible to be reconfigured during gameplay. This will of course introduce some side effects, such as when an unpaused rule is modified during execution. It is the rule's responsibility to ensure that these side effects do not lead to script exceptions or to leaked state. For example, if a single thread is supposed to be running, reconfiguring the rule should not cause a second thread to run simultaneously. If a rule sniffs a target vehicle, and the target vehicle is redefined, then the rule should unsniff the original vehicle rather than now sniffing two vehicles.

Likewise, we may in future allow some form of partial state swap between Driver and Surveyor. Rules should not assume that it is impossible to change from any one game state or module to any other game state or module, just because it is not possible at the current time. APIs already exist to detect such state changes where necessary, and in most cases it's simply not necessary to care whether your rule is in Surveyor or Driver - you should act based on the PAUSED state instead. Rules should deal with the game state as they find it rather than assuming that certain states will not ever occur.

= Gotchas =
There are a few potential gotchas in the script environment that are worth considering when writing any non-trivial rule.

== Response Latency ==
Scripts tend to rely heavily on message passing and threading. In both cases, there is a delay between triggering a certain behavior (eg. posting an event, or calling a threaded function) and having the receiving code react. Other code may execute during this delay.

<code><pre>
// Calling this might be expected to start and then stop the thread; in reality it
// will likely simply start the thread and leave it running, because the message
// is sent prior to the wait() statement starting.
void DemonstrateBug1(void)
{
Pause(false);
Pause(true);
}

// In this case, we use a Sleep() statement to "ensure" that the thread has
// finished starting. This isn't actually reliable, but it works as long as the
// system isn't under too much load. We follow this up with a rapid pause-
// unpause sequence. As above, this doesn't work - the message is sent,
// then the function immediately checks whether the thread is still running
// (which it is) and thus the thread isn't restarted. The function completes,
// and finally the thread receives the message and exits.
void DemonstrateBug2(void)
{
Pause(false);
Sleep(1.0);
Pause(true);
Pause(false);
}

// Helper code for the above functions.
void Pause(bool bIsPaused)
{
if (bIsPaused)
{
PostMessage(me, "ThisRule", "Pause");
}
else if (!m_bIsThreadRunning)
{
m_bIsThreadRunning = true;
StartThread();
}
}
thread void StartThread(void)
{
while (true)
{
wait ()
{
on "ThisRule", "Pause":
break;
...
}
m_bIsThreadRunning = false;
}
</pre></code>

== Multiple Messages in Flight ==
It's possible to post multiple identical messages. This can be useful, but if you're expecting only one then it can be a source of errors.

In the following pseudocode, each call to SetProperties() will place an additional "Timer", "Tick" message into the cycle, effectively increasing the rate at which the IdleFunction is called. This will seem to be working for a single call to SetProperties(), which may be all that is called during a trivial testcase. It will probably give reasonable results for a few calls to SetProperties(), although if the function is time-sensitive then the results might be different to expectations. After a larger number of calls to SetProperties(), the object's message queue may become full, causing it to lose messages at random (perhaps the tick messages, or perhaps other unrelated messages that are more problematic).

<code><pre>
void Init(void)
{
inherited();

AddHandler(me, "Timer", "Tick", "IdleFunction");
}

void EnterIdleState(void)
{
IdleFunction();
}

void IdleFunction(void)
{
PostMessage(me, "Timer", "Tick", 1.0);
.. do something here ..
}

void SetProperties(Soup soup)
{
inherited(soup);

EnterIdleState();
}

</pre></code>

A similar problem can occur if you start new threads rather than post new messages.

== Thread Guard Variables ==
It's common to prevent a singleton thread from being started twice by using a boolean guard variable. Care must be taken to ensure that the guard variable is set and cleared at the correct locations, or they may be ineffective.

The following pseudocode demonstrates one such correct usage. The key points to note are:
* We set 'm_bIsThreadedFunctionRunning' prior to calling the threaded function. Setting it within the threaded function is too late; multiple threads might have already been started before the first thread reaches that point.
* We don't confuse whether the thread is actually running with whether we want the thread to be running. Once we ask a thread to start, we can't stop it starting. If we change our minds and want to stop it again, we must inform it in a way that it will realise after it finishes starting. In the worst-case scenario, we might flipflop on this multiple times before the thread actually starts.
* Similarly, we don't rely on messages to control the thread. Enqueuing a separate start or stop message with each StartThread()/StopThread() call might be possible, and we could clear any unwanted prior messages from the object's queue, but if the thread hasn't finished starting then it won't receive the messages anyway.
* We do rely on messages to wake the thread if it's waiting on messages, but we don't use those messages to imply any state - we just have it recheck the current state boolean to get the very latest info.
* We clear 'm_bIsThreadedFunctionRunning' once the decision to exit has become unconditional. At this point, even though the thread is technically still running, we'll have to start a new thread if we want the thread to continue running.

<code><pre>
bool m_bIsThreadedFunctionRunning = false;
bool m_bWantThreadedFunctionRunning = false;

void StartThread(void)
{
m_bWantThreadedFunctionRunning = true;

if (m_bIsThreadedFunctionRunning)
return;

m_bIsThreadedFunctionRunning = true;
ThreadedFunction();
}

void StopThread(void)
{
if (!m_bWantThreadedFunctionRunning)
return;

m_bWantThreadedFunctionRunning = false;
PostMessage(me, "Thread", "Touch");
}

thread void ThreadedFunction(void)
{
while (m_bWantThreadedFunctionRunning)
{
wait()
{
on "Thread", "Touch":
break;
.. whatever else..
}
}
m_bIsThreadedFunctionRunning = false;
}
</pre></code>

== Not Waiting For Messages ==
As seen above, it's possible for a thread to fail to receive posted messages because it wasn't waiting for them at the time. A more commonly problematic example follows.

<code><pre>
thread void MyThread(void)
{
wait ()
{
on "Some", "Condition":
HandleSomeCondition();
continue;
on "Thread", "Exit":
break;
}
}

void HandleSomeCondition(void)
{
wait ()
{
on "Some", "End-Condition":
break;
}
}
</pre></code>

In this example, the thread is waiting on both "Some", "Condition" and also "Thread", "Exit". Either one will be handled correctly assuming that the thread is already running at the time they are posted. Even if multiple are posted, the thread will simply queue them and run each in turn.

The problem occurs when HandleSomeCondition() is triggered and the thread begins waiting on "Some", "End-Condition". In this scenario, the thread is no longer waiting on "Thread", "Exit", and any attempt to post that message will simply be ignored. To reiterate: the message dispatch is NOT postponed until the function returns; the message is dropped entirely.

Session Rule Implementation

2018-11-27T13:42:59Z

Windwalkr:

Session Rule Implementation

2018-11-27T13:09:55Z

Windwalkr: WIP transcription

Category:Validation Errors

2018-11-26T04:30:35Z

Windwalkr:

Category:Validation Errors

2018-10-16T02:13:16Z

Windwalkr:

"trainz-build" number

2018-09-04T03:12:58Z

Windwalkr:

New releases of Trainz bring new features and improved content validation techniques. This will happen for major product editions (eg. [[TS2010]], [[TS12]] and [[TANE]]) but may also occur during the larger service packs which are released for each product. The [["Trainz-build" number]] is used to differentiate these compatibility versions, and the corresponding [["Trainz-build" tag]] is used in each asset's [[Config.txt file]] to specify the minimum Trainz version required in order to use the asset.

{| border=2 cellpadding=5 cellspacing=2
|-
! colspan=2|Trainz-Build version numbers and their mapping to official Trainz release versions are as follows:
|-
!'trainz-build' || Trainz product for which the asset was designed
|-
| {{center|1.3 }} || [[Trainz SP3|Trainz SP3]]
|-
| {{center|1.5 }} || Ultimate Trainz Collection
|-
| {{center|1.6 }} || Ultimate Trainz Collection SP1
|-
| {{center|2.0 }} || [[TRS2004]]
|-
| {{center|2.1 }} || [[TRS2004]] SP1
|-
| {{center|2.2 }} || [[TRS2004]] SP2 - Passenger Pack
|-
| {{center|2.3 }} || [[TRS2004]] SP3
|-
| {{center|2.4 }} || [[TRS2004]] SP4
|-
| {{center|2.5 }} || [[TRS2006]]
|-
| {{center|2.6 }} || [[TRS2006]] SP1
|-
| {{center|2.7 }} || Trainz Classics 1&2
|-
| {{center|2.8 }} || Trainz Classics 3
|-
| {{center|2.9 }} || [[TS2009]]
|-
| {{center|3.0 }} || [[TS2009 SP1]]
|-
| {{center|3.1 }} || [[TS2009 SP2]] / [[TS2009 SP3]]
|-
| {{center|3.2 }} || [[TS2010]] / [[TS2010 SP1]]
|-
| {{center|3.3 }} || [[TS2010 SP2]] / [[TS2010 SP3]] / [[TS2009 SP4]]
|-
| {{center|3.4 }} || [[TS2010 SP4]]
|-
| {{center|3.5 }} || [[TS12]]
|-
| {{center|3.6 }} || [[TS12]] and [[Trainz Simulator Mac]]
|-
| {{center|3.7 }} || [[TS12 SP1]]
|-
| {{center|3.8 }} || [[Trainz Simulator 2]] (Mac)
|-
| {{center|3.9 }} || [[Trainz A New Era: Community Edition]] 1.0
|-
| {{center|4.0 }} || [[Trainz A New Era: Community Edition]] 1.1
|-
| {{center|4.1 }} || [[Trainz A New Era: Community Edition]] 1.2
|-
| {{center|4.2 }} || [[Trainz A New Era]]
|-
| {{center|4.3 }} || [[Trainz A New Era]] SP1
|-
| {{center|4.4 }} || [[Trainz Model Railways TMR2017]]
|-
| {{center|4.5 }} || [[Trainz A New Era]] SP2 / SP3
|-
| {{center|4.6 }} || [[TRS19]]
|}

==Obsolete Versions==

The [[Trainz Life-Cycle Policy]] defines which product releases have active support from [[N3V Games]]. While users may continue to use older products, including downloading such older content from the [[Download Station]] and even creating new content for these older versions, it is typically not possible to upload content with an unsupported [["Trainz-build" number]] to the [[Download Station]]. This ensures that older content-creation techniques are slowly phased out over time in favour of the more recent improvements.

Help:VE215

2018-06-25T08:35:30Z

Windwalkr: Created page with "'''Asset has an invalid number of LODs: $(LOD_COUNT)''' This error results when a mesh-table-based asset has an improper number of LODs. Generally speaking, only a small ..."

'''Asset has an invalid number of LODs: $(LOD_COUNT)'''

This error results when a [[mesh-table]]-based asset has an improper number of LODs. Generally speaking, only a small number of LODs (eg. 2-4) is necessary for any given asset, and performance grows worse as the number of LODs increases. Numbers heavily in excess of this range are considered faults.

[[Category:Validation Errors]]

Category:Validation Errors

2018-06-25T08:32:51Z

Windwalkr:

HowTo/Export from Blender using FBX

2018-06-06T03:29:14Z

Windwalkr:

==Introduction==

This guide provides information for the export of FilmBoX (FBX) files from Blender.

===Versions===

{| class="wikitable"

|-
|style="width:100px;"|TANE:||style="width:200px;"|4.5 or later.
|-
|Blender:|| Known to work for Blender 2.78a or later. The FBX exporter is a standard addon for Blender.
|-
|FBX format:|| Binary format only (see discussion below). FBX 2011, FBX2012, FBX2013.
|-
|Special requirements:|| None. Creators will need their preferred image editors and text editors but there are no special requirements for FBX.
|-
|Other software:|| There are free FBX viewers available on the web including {{plain link|http://www.autodesk.com/products/fbx/fbx-review|FBX Review}} and FBX Converter programs by Autodesk.
|}

===The FBX format===

A brief discussion on the FBX format history can be found {{plain link|https://en.wikipedia.org/wiki/FBX here}}. FBX can be exported, or imported, either as an ASCII (i.e. human readable) file or in binary format.

==Blender and FBX==

Blender is capable of both importing and exporting FBX formatted files. Two formats are available: ASCII FBX 6.1 and binary FBX 7.4 (Blender 2.78). Since TANE will only accept FBX versions between 7.1 (7100) and 7.5 (7500), the ASCII version cannot be used for Trainz. Note that work on the Blender ASCII importer/exporter is frozen.

The Blender exporter does not export all possible object attributes and it is likely that TANE will not recognise all those attributes that are exported.
The Blender documentation contains a {{plain link|https://wiki.blender.org/index.php/Extensions:2.6/Py/Scripts/Import-Export/Autodesk_FBX list of attributes}} that are exported.

Included in this guide is a list of attributes that have been observed as exported and treatment/acceptance by TANE. The list is incomplete and will be updated when new information is available.

N3V use the ASSIMP Open Asset Import Library to extract asset model information from the FBX file. ASSIMP Version 3.3.1 appears to be FBX version 7.3 and the Blender FBX exporter exports FBX 7.4. This results in some warnings that appear to be generated by Content Manager but actually come from the ASSIMP process. If you get warnings that you cannot correct, such as those in the warnings section below, try running the Blender generated FBX file through the Autodesk FBX Converter program and choose FBX2013 as the target. These warnings do not appear to affect the outcome so this step may not be necessary.

==TANE and the FBX Importer==
A discussion of the FBX format and general guidelines for use with TANE is discussed at this Trainz WiKi page: [[FBX file format]]

==Skills Required==
For this version of the guide, it is assumed the user has some knowledge of the use of Blender and an understanding of the Trainz asset creation process.

==Exporting a mesh object from Blender in FBX format (no animation)==

The FBX exporter addon must be enabled in User Preferences.

Select File->Export->Export FBX and the FBX export panel will show in the bottom left hand corner and should look like the following picture. The panel contents
vary significantly between the Binary export version and the ASCII export version so make sure you have Binary selected.

===The Main Menu===
[[File:Blender_FBX_Main_Menu.jpg|380px|left]]
* Ignore the Operator Presets for now.
* Ensure FBX 7.4 binary version is selected.
* The Main/Geometry/Armatures/Animation buttons provide menu options for the item selected. Select the Main option.
* Selected Objects. This option needs careful consideration. Unlike the Blender XML exporter, the FBX exporter will export all objects in all layers
which is probably undesirable in many cases and particularly if you have different LOD models in different layers. So, first select those objects within Blender
that you want to export and then select Selected Objects in this panel.
* Scale. Leave the Scale value as 1.00 and deselect the small icon to the right of the Scale value. (See note below)
* Forward and Up. Set these to the values :Y forward and Z Up.

The options below are multi select (i.e. you can select more than one). For the time being just leave Mesh selected.

* Leave the Experimental and Custom Properties as deselected.
* Leave Path Mode as Auto and Batch Mode as Off.
* Choose the FBX filename and export using the Export FBX in the top right hand corner. There is no exporter log.
{{clear}}

Note that Blender 2.79 introduced some options for scaling that need some investigation. Recommend using "FBX All" until this has been investigated.

====Tip====
You can save your preferences for a given situation by clicking on the plus button (+) next to Operator Presets and saving the preset with a name. This is particularly useful for animation. You will need to reload the preset each time you start Blender.

===The Geometry Menu===

[[File:FBX Geometry Menu.jpg|380px|left]]
* Leave these values as shown.
{{clear}}

===The Armatures and Animation Menus===

* See the [http://online.ts2009.com/mediaWiki/index.php?title=HowTo/Export_from_Blender_using_FBX&action=submit#Animation Animation Section].
{{clear}}

===Config.txt - simple model===

Setting up the CONFIG.TXT

The only changes to the config.txt are in the mesh table. The mesh entries for FBX files now have a "trainzmesh" extention as per the following example:

mesh-table {
default {
auto-create 1
mesh "my-mesh.trainzmesh"
}
}

Note that for the LM.TXT Level of Detail (LOD) you can still use the LM convention but the LM.TXT file must refer to trainzmesh files.

===Files created===

====Mesh files====

The file my-mesh.trainzmesh is created during the asset commit. Currently the FBX file is not deleted but bundled into the asset. Since the FBX format is readable by 3D modelling tools, you may want to remove any FBX files from assets uploaded to the DLS or other web sites.

====Texture.txt files====

You can provide your own texture.txt files (advisable) or let the commit process create them for you. The commit process will create suitable files, such as those required for normal maps, but you can provide your own if you have special requirements.

Warning: If you get odd effects with your textures, check the associated texture.txt file first. The FBX importer tends to add an "alpha=" line even though no alpha option has been chosen. This may be an issue with the Blender FBX exporter.

PEV's TextureTXT utility can be very useful for creating texture.txt files and its worth adding it into AssetX if you use AssetX for managing your projects.

===Double Sided Meshes===
It appears that FBX does not support double sided meshes so you need to create a metadata file as described at [[FBX file format#Mesh Metadata Files]]. Note that this is done per material. i.e. you cannot have the same material for single sided and double sided meshes.

===Self Illuminated Meshes===
Meshes that require self illumination require a separate material with the Shader->Emit value set to a value other than 0. A value of 1.0 is recommended. The Blender exporter also exports an emissive colour using the diffuse colour value. It is not known if TANE uses the emissive colour. You might also experiment with the specular values.

===General warnings and errors===
Errors and warnings starting with a T, such as T16128, are errors ouput by the ASSIMP converter and are not output by the Trainz FBX importer.

{| style="border:1px solid gray;border-collapse:collapse;background:white;font-weight:bold; " cellpadding=5px align=left width=70%
|- style="font-weight:bold; text-align:center;"
! width=40% style=" border:1px solid gray;"|Warning/Error
! width=60% style=" border:1px solid gray;"|Help/Explanation
|-
| style="border:1px solid gray;font-weight:normal;"|Warning: T16080: ...shading mode not recognised: Phong
| style="border:1px solid gray;font-weight:normal;"| You can probably ignore this warning. The warning may go away if you run the FBX file through Autodesk's FBX Converter program to the FBX2013 format.
|-
| style="border:1px solid gray;font-weight:normal;"|Warn, T15808: FBX-DOM (TOK_KEY, offset 0xnnnn) source object for connection does not exist
| style="border:1px solid gray;font-weight:normal;"| You can probably ignore this warning. The warning may go away if you run the FBX file through Autodesk's FBX Converter program to the FBX2013 format.
|-
| style="border:1px solid gray;font-weight:normal;"|Error: Unable to determine vertex format.
| style="border:1px solid gray;font-weight:normal;"|This can be caused by having multiple UV maps for the same mesh. For example, baking a painted mesh to a bake mesh requires two UV maps. Remove old maps before exporting. If you wish to keep those maps, back up the Blender file and then delete the extra maps.
|-
| style="border:1px solid gray;font-weight:normal;"|Error, T9068 Failed to triangulate polygon (no ear found). Probably not a simple polygon. This follows a previous info "All polygons triangulated"
| style="border:1px solid gray;font-weight:normal;"|The exact cause of this problem is unknown but recommend using a mesh edit tool to triangulate all polygons.
|-
| style="border:1px solid gray;font-weight:normal;"|Error, Error, T16128: FindInvalidDataProcess fails on mesh uvcoords: All vectors are identical"
| style="border:1px solid gray;font-weight:normal;"|Probably caused by having multiple UV maps for the same mesh. Not sure of the relationship between this error and the "Unable to determine vertex format" error.
|}

===Level of Detail (LOD)===

The rules for [[Level of Detail]] for FBX models are the same as indexed mesh (IM) models except for the use of the Trainzmesh suffix for mesh files.

====Mesh-Table Method====

This is a very simple scenery model of a coloured ball using three levels of LOD: [[File:6000101_-_FBX_-_LOD_mesh-table_test1.zip]].
The Blender source is provided.

====LM.TXT Method====

(TBD)

==Animation==

===Overview===

Trainz will not animate a mesh without the use of helper points using the "b.r" notation. For Blender, those helper points can be armatures (bones) or empties. Lattices are not supported by the FBX exporter.

An animation must have a root helper normally called "b.r.main" although "b.r.root" will also work. Using such names helps identify the overall parent of the animation.
Other animation helpers are called "b.r.xxx", where "xxx" can be any name. These helpers must be children of the main/root helper.

===Exporting an animated mesh object===
====The Main Menu====
[[File:Blender FBX export main-anim.jpg|380px|left]]
* Select Empty and Armature depending on how you set up your animation.
* Other options are described above.
{{clear}}

====The Armatures Menu====
[[File:FBX Armatures Menu.jpg|380px|left]]
* Use the values as shown.
{{clear}}

====The Animation Menu====
[[File:Blender FBX anim menu1.jpg|380px|left]]
* Select Baked Animation and disable the other options.

Authors note: This is completely different from the process described in the 3DS Max FBX animation export.
If Baked Animation is not ticked, then none of the other animation options are available. So far, none of those other options have been found useful.
{{clear}}

===Files created during the export and import process===

The Blender exporter creates a binary file with the name of your choosing plus an FBX suffix. For animation, the exporter creates an internal name that the TANE importer uses for an animation (KIN) file.

If you choose Baked Animation (recommended), then the animation name is comprised of the FBX name and the word "_scene". So, if you export a model called "box.fbx" with animation, then the importer creates a "box.trainsmesh" and "box_scene.fbx".

If you don't choose Baked Animation, then the TANE importer uses the name of the animation channel so you might get names like "b.r.main-b.r.mainAction.kin".

===Config.txt - Animation===

The names of mesh and KIN files may not be obvious so you may need to create some dummy names for your mesh and KIN files. After importing into TANE, open the asset for editing and look for the files created. Then go back and correct entries in the config.txt.

Sample mesh-table entry with animation:

mesh-table {
default {
auto-create 1
mesh "box.trainzmesh"
anim "box_scene.kin"
animation-loop-speed 1.00
}

===Animation warnings and errors===

{| style="border:1px solid gray;border-collapse:collapse;background:white;font-weight:bold; " cellpadding=5px align=left width=70%
|- style="font-weight:bold; text-align:center;"
! width=40% style=" border:1px solid gray;"|Warning/Error
! width=60% style=" border:1px solid gray;"|Help/Explanation
|-
| style="border:1px solid gray;font-weight:normal;"|! ... T14120: Simplified dummy tracks with just one key.
| style="border:1px solid gray;font-weight:normal;"| Not sure what this warning is about but the animation is OK.
|-
| style="border:1px solid gray;font-weight:normal;"|! ... Skipping one or more lines with the same contents
| style="border:1px solid gray;font-weight:normal;"|This is an ASSIMP message and can be ignored.
|}

===Sample animations===

The following samples are provided to demonstrate different types of Blender FBX animations. You are free to use them for any purpose - i.e. no copyright!

====Simple Animation 1 - Uses an empty as animated parent====

[[File:890045 fbx anim1 - empty.zip]]

This animation rotates a coloured cube around the X axis using an empty as parent b.r.main. The animation action, within Blender, is called b.r.mainAction. The channel has been set to linear interpolation.

When exporting, you must select Empty and Mesh.

Exported names: The Blender FBX exporter creates a file called box.fbx. On commit, TANE creates a mesh file called box.trainzmesh and an animation file called box_scene.kin.

====Simple Animation 2 - Uses an armature as animated parent====

[[File:890044 fbx anim1 - armatures.zip]]

This animation rotates a coloured cube around the X axis using an armature with a single bone as parent b.r.main. The animation rotates anti-clockwise.

This is much the same as Sample 1 but demonstrates that you can use either an empty or an armature for simple animations.

When exporting, you must select Armature and Mesh.

Exported names: The Blender FBX exporter creates a file called box.fbx. On commit, TANE creates a mesh file called box.trainzmesh and an animation file called box_scene.kin.

====Simple Animation 3 - Four animated cogs - LOD model====

[[File:4000110 - FBX - anim test 4 - four cogs.zip]]

This animation simulates four rotating cogs. There are two LOD levels. LOD0 (the high poly version) is in layer 1 and LOD1 (the low poly version) is in layer 2. Layer 11 contains the animated armatures. There are four animation tracks.

To export LOD0, select all the objects in layers 1 and 11 so the LOD0 meshes and the armatures are all selected. On export, ensure Empty, Armature and Mesh are selected and use the name "4cogs-lod0.fbx". b.r.main is an empty so Empty must be selected.

To export LOD1, select all the objects in layers 2 and 11 so the LOD1 meshes and the armatures are all selected. On export, ensure Empty, Armature and Mesh are selected and use the name "4cogs-lod1.fbx".

You can choose any names you want but a meaningful name is useful.

This is the relevant section of config.txt:

mesh-table {
gears-lod0 {
auto-create 1
mesh "4cogs-lod0.trainzmesh"
lod-level 0
anim "4cogs-lod0_scene.kin"
animation-loop-speed 1.00
}
gears-lod1 {
auto-create 1
mesh "4cogs-lod1.trainzmesh"
lod-level 1
anim "4cogs-lod1_scene.kin"
animation-loop-speed 1.00
}
}
mesh-detail-level-count 2

Note that the transition from LOD0 to LOD1 is obvious.

====More complex animations====

=====A Sample Steam Piston Animation=====
[[File:Bsa.zip]]

[[File:Circle_guided_steam_animation.jpg|380px]]

This example shows how to animate a steam piston and crankshaft using a circle to guide the location of the piston shaft. This is a variation of Torsten's sample for the XML exporter. General instructions for export are contained in the Blender file as a text object.

==Legacy Materials==

This section identifies the legacy material options used by the FBX exporter (i.e. prior to the introduction of [[TRS19]]). For detailed descriptions on how Trainz uses material types, including TRS19 PBR materials, see [[Material Types]] and the child pages detailing different Trainz material types.

The exporter treats material options based on the chosen material shader model. Even though Trainz uses its own shaders, it may be worthwhile selecting different shader models in Blender to see the effect. In particular, choosing the Phong model for the specular shader will enable the export of a number of extra material options. These may, or may not, actually result in observable changes in Trainz.

The FBX exporter uses the following material options:

{| style="border:1px solid gray;border-collapse:collapse;background:white;font-weight:bold; " cellpadding=5px align=left width=70%

|- style="font-weight:bold; text-align:center;"
! width=20% style=" border:1px solid gray;"|Material Option
! width=10% style=" border:1px solid gray;"|Shader
! width=70% style=" border:1px solid gray;"|Comment
|-
| style="border:1px solid gray;font-weight:normal;"|Diffuse -> Color
| style="border:1px solid gray;font-weight:normal;"|Any
| style="border:1px solid gray;font-weight:normal;"|Used for both diffuse and emissive colour
|-
| style="border:1px solid gray;font-weight:normal;"|Diffuse -> Intensity
| style="border:1px solid gray;font-weight:normal;"|Any
| style="border:1px solid gray;font-weight:normal;"|Factor applied to diffuse colour
|-
| style="border:1px solid gray;font-weight:normal;"|Shading -> Emit
| style="border:1px solid gray;font-weight:normal;"| Any
| style="border:1px solid gray;font-weight:normal;"|Factor applied to emissive colour
|-
| style="border:1px solid gray;font-weight:normal;"|World -> Ambient_Color
| style="border:1px solid gray;font-weight:normal;"|Any
| style="border:1px solid gray;font-weight:normal;"|Not sure what effect this may have, if any, on the exported result. See also Shading -> Ambient.
|-
| style="border:1px solid gray;font-weight:normal;"|Shading -> Ambient
| style="border:1px solid gray;font-weight:normal;"| Any
| style="border:1px solid gray;font-weight:normal;"|Amount of global ambient colour the material receives.
|-
| style="border:1px solid gray;font-weight:normal;"|Transparency
| style="border:1px solid gray;font-weight:normal;"|Any
| style="border:1px solid gray;font-weight:normal;"|Use transparency if checked.
|-
| style="border:1px solid gray;font-weight:normal;"|Transparency -> Alpha
| style="border:1px solid gray;font-weight:normal;"|Any
| style="border:1px solid gray;font-weight:normal;"|Transparency (opacity) factor.
|-
| style="border:1px solid gray;font-weight:normal;"|Specular -> Color
| style="border:1px solid gray;font-weight:normal;"|Phong
| style="border:1px solid gray;font-weight:normal;"|
|-
| style="border:1px solid gray;font-weight:normal;"|Specular -> Intensity
| style="border:1px solid gray;font-weight:normal;"|Phong
| style="border:1px solid gray;font-weight:normal;"|
|-
| style="border:1px solid gray;font-weight:normal;"|Specular -> Hardness
| style="border:1px solid gray;font-weight:normal;"|Phong
| style="border:1px solid gray;font-weight:normal;"|Shininess
|-
| style="border:1px solid gray;font-weight:normal;"|Mirror -> Color
| style="border:1px solid gray;font-weight:normal;"|Phong
| style="border:1px solid gray;font-weight:normal;"|Mirror must be checked.
|-
| style="border:1px solid gray;font-weight:normal;"|Mirror -> Reflectivity
| style="border:1px solid gray;font-weight:normal;"|Phong
| style="border:1px solid gray;font-weight:normal;"|Mirror must be checked
|}

Be wary of checking Shading->Shadeless as this stops the export of several attributes including: Specular Color, Specular Factor, Shininess Exponent, Reflection Color, Reflection Factor, Specular, and Shininess.

In summary, material values you can play with in any material include:
:* Diffuse colour
:* Diffuse specular
:* Transparency
:* Specular colour
:* Specular intensity
:* Specular hardness
:* Shading Emit
:* Mirror
:* Ambient (in World)

===Sample Assets===

====Notex====

Description: TBD

Sample asset: A notex material applied to a box. [[File:4000001- FBX paint-test-notex.zip]]

====Onetex====

Description: TBD

Sample asset: A onetex material applied to a box. [[File:4000002 - FBX paint-test-onetex.zip]]

====Reflect====

Description: This works well when an image is used to influence the material base colour. Check/tick the Mirror option in the Material panel and select the amount of reflectively you need. Start with 0.5 and experiment.
The attached example uses env_metal.tga as a reflection texture. You can set the Mapping Coordinates to either UV or Reflection. Reflection makes the model look correct in Blender but makes no difference to TANE.
In the Texture Influence->Diffuse section, check both Color and Mirror. Don't change the values of either field as the FBX exporter ignores them.

M.reflect doesn't work well with a diffuse texture. Other materials are probably better suited for that purpose.

Sample asset: A reflect material applied to a box. [[File:4000003_-_FBX_-_paint-test-reflect.zip]]

====Gloss====

Description: TBD

====Tbumptex====

Description: TBD

Sample asset: A tbumptex material applied to a box. [[File:4000004 - FBX - paint-test tbumptex.zip]]

====Tbumpgloss====

Description: TBD

====Tbumpenv====

Description: TBD

Sample asset: A tbumpenv material applied to a box. [[File:4000005 - FBX - paint-test tbumpenv.zip]]

====Transparency and Double Sided Meshes====

This asset demonstrates transparency using notex materials and a double sided mesh using a onetex material. In particular, it shows how metadata files can be used for this purpose.
[[File:6000011_-_FBX_-_transparency_test_1.zip]]

===Textures===

This section identifies the texture options used by the FBX exporter. Very few of the available options are actually exported and the only exported item relevant to normal/bump maps is the Mapping->Coordinates value. In practice, this isn't an issue as test assets using Trainz bump mapped materials work fine. You might need to provide your own texture.txt files when normal maps are required.

The FBX exporter uses the following texture slot options:

{| style="border:1px solid gray;border-collapse:collapse;background:white;font-weight:bold; " cellpadding=5px align=left width=70%

|- style="font-weight:bold; text-align:center;"
! width=20% style=" border:1px solid gray;"|Texture Option
! width=70% style=" border:1px solid gray;"|Comment
|-
| style="border:1px solid gray;font-weight:normal;"|Texture name
| style="border:1px solid gray;font-weight:normal;"|Can be any name but recommend names such as Diffuse, Normal or similar to identify purpose.
|-
| style="border:1px solid gray;font-weight:normal;"|Texture type
| style="border:1px solid gray;font-weight:normal;"|Must be "Image or movie"
|-
| style="border:1px solid gray;font-weight:normal;"|Image -> Name
| style="border:1px solid gray;font-weight:normal;"|Filename of image.
|-
| style="border:1px solid gray;font-weight:normal;"|Image -> Use Alpha
| style="border:1px solid gray;font-weight:normal;"|Tick if alpha channel is to be used.
|-
| style="border:1px solid gray;font-weight:normal;"|Image -> Alpha Mode
| style="border:1px solid gray;font-weight:normal;"|This value is exported but probably not used by Trainz so leave it as "straight".
|-
| style="border:1px solid gray;font-weight:normal;"|Mapping -> Coordinates
| style="border:1px solid gray;font-weight:normal;"|Use UV, Normal or Reflection
|-
| style="border:1px solid gray;font-weight:normal;"|Mapping -> Map
| style="border:1px solid gray;font-weight:normal;"|UV map name
|-
| style="border:1px solid gray;font-weight:normal;"|Image Mapping -> Extension
| style="border:1px solid gray;font-weight:normal;"|Use Repeat if UV wrapping required. Probably only of value within Blender since Trainz texture.txt files define image wrapping.
|}

==Return to Index==

[[HowToGuides|<< How To Guides]]

[[Category:How-to guides]]
[[Category:Modeling]]
[[Category:Content creation]]

Asset Validation

2018-06-06T03:28:19Z

Windwalkr:

All Trainz assets must be correctly formed in order to work properly across a wide range of software and hardware configurations. To aid in this process, Trainz includes asset validation functionality which checks each item of content for a range of known flaws. This validation process is performed both on your local Trainz installation, and also as part of the [[Download Station]] Upload Process. Assets which fail validation cannot be used in-game.

This page documents recent changes to the asset validation process. It is not intended as a complete list of possible failure cases, nor does it seek to provide information on how to fix each error condition. If a fault is discovered in your own content, you should review the relevant [[Content Configuration]] documents to understand the rules and restrictions which are relevant to the asset in question.

== Common Misunderstandings ==
There are two common misunderstandings that our users often have regarding asset validation:

1. That built-in content is exempt from validation, and may be faulty. This is incorrect; all built-in content is validated at the [[N3V Games]] offices using the same tools as are available to end users. We do not perform validation of built-in content on end-user machines because (1) it is slow, and (2) the content cannot be modified and was known to be good at the time it was made built-in.

:: It is important, however, to note that built-in content does not contain source textures. This means that a user who attempts to clone or edit built-in content will be faced with a faulty result unless they provide their own source textures. This does not indicate that the built-in content was faulty, but rather that the user's manipulations have left the game with a faulty copy of the asset.

2. That warnings must be fixed. Warnings are generated when the game believes that there may be reason for the content creator to review their asset. It is purely a courtesy to highlight cases which are known to be frequently problematic. This does not necessarily mean that the content is faulty, or that anything needs to be changed. Modifying your own created content to resolve warnings is encouraged, but not mandatory. Modifying content created by others to resolve warnings is strongly discouraged as it is likely to introduce compatibility issues for no benefit.

:: Note that it is also a myth that "today's warning is tomorrow's error". In some cases we warn people about errors prior to making the changes mandatory in future versions, but this is a guide not a rule.

== Validation Error Messages ==
The list of error messages that can be created during the validation process is at [[:Category:Validation_Errors|Validation Errors]].

== Recent Validation Changes ==
The following changes are reasonably new additions that many users may not yet have experience with. They are included here to highlight the requirements and to advise users that they are legitimate problems.

* Content is now loaded by the game engine during validation, in addition to the existing practice of checking the content files for known errors. This means that some number of errors which previously only occurred at runtime will now be detected during validation.
* Limited sanity checks for incorrect use of [[material sharing]] are now present.

== Recent Additions ==
The following changes are recent additions to the config format.

TBD.

HowTo/Make your first Trainz Asset

2018-06-06T03:27:23Z

Windwalkr:

'''NOTE: This information is out of date.''' While many of the techniques here are still valid, please see the [[TRS19]] page for links to the latest content creation information.

This is a step by step tutorial that will teach you how to create a 3D model, create the Level of Detail (lower resolution) versions of the model, and import it into Trainz.

== Determine what software you'll need ==

Before you start you will need:

* A copy of Trainz Simulator 12 (or technically, a copy of Trainz).

* A copy of 3DS Max studio that has a supported Trainz Exporter. We are using 3DS Max 2008 in this example. Information on all exporters can be found [[Max Exporters|here]] and the download files can be found on the [[Downloads]] page.

* To setup the exporter in 3DS Max you will want to extract the .zip file and then place the correct versions "JetExporter.dle" file into the plugins directory of your installed 3DS Max. For example, it might look like "C:\Program Files (x86)\Autodesk\3ds Max 2008\plugins"

* (OPTIONAL SOFTWARE) [http://quixel.se/ndo/ nDo2] is a Photoshop plugin that makes creating normal (or bump) maps for your models a breeze.

== How to setup the model and materials in 3DS Max ==

===Recommended Reading===

Before you start modelling you might want to read [[Modeling Trains for Trainz]] as it explains things like setting up the Unit Scale correctly to model in and a few other good pointers.

===Create Highest LOD First===
Model your object at the highest detail required to look good up close. The distance that the highest level of detail model (LOD 0) will be seen in Trainz could be from 0 up to about 40 meters away from the camera.

[[File:lod_0.jpg]]

===Additional LOD Levels===
Continue making a further 2 lower level detail models (LODs) for the exact same item you are modelling.
The 2nd highest detail model (LOD 1) is required to still look decent at 40 up to 80 meters away. You will want to remove about 50% of the original polygons found in the highest detailed model (LOD 0 - above).
The 3rd highest detail model (LOD 2) is required to still look decent at 80 up to 160 meters away. You will want to remove about 50% of the original polygons found in the 2nd highest detailed model (LOD 1).

This is an example of the LOD 0 detailed versus LOD 1 and LOD 2 detail.

[[File:lod_0_v_lod_2.jpg]] [[File:lod_0_v_lod_2_distance.jpg]]

===LOD 3 - Extremely low poly LOD===

Create an extremely low detailed model (LOD 3) to be used in the distance. In this example we are saying this model will be used 160 meters and beyond. Usually the lowest detail model which is used in the distance is a billboard (2 polygon object) or a cube type object (8 - 10 polygons). Whatever you choose, this detail must use as fewer polygons as possible.

[[File:lod_3.jpg]]

===Materials===
Setting up the materials is pretty easy but you'll need to work out what type of material (look) you want for your object. All the Trainz materials available for you to use in 3DS Max can be found [[Material Types|here]] and you'll also want to read about [[Exporting with 3D Studio Max]] for additional lighting material setup details.

You should setup your image files as .TGA files and save them as 32-bits/pixel without "Compress (RLE)" checked. We are using Photoshop in the example below:

[[File:32-bits.jpg]]

== How to create the Trainz Asset and import it into Trainz Content Manager ==
Once your models have LOD and materials applied, it's time to export from 3DS Max and get them into Trainz!

===Exporting your model===
To export into Trainz format you will want to Click File -> Export, Save as type, drop down and select Trainz format (*.IM, *.KIN)

===Creating a Trainz Config File===
When you have exported all your different LODs from 3DS Max to a folder (all your .IM and .texture.txt files, without errors), you are ready to use Content Manager to import your object into Trainz.

First you need to create a [[config.txt file]] - this file holds all the information the the Trainz code uses to manage your asset in the game. To do this, create a new file in the folder named "config.txt".

The "[[KIND TrainzBaseSpec]]" and "[[Content Configuration]]" pages give an enormous amount of information on everything to do with the config.txt options. Reading the Content Configuration pages can be very overwhelming to start with so below we have created the minimum information a config.txt file needs to get your LOD asset working in-game. (As you gain confidence, be sure to see what else Trainz can do though as it is very powerful!)

This is the very basic "scenery" object config.txt file. (Not to worry, we explain each part of this below)

kind "scenery"
username "Car_Example"
trainz-build 3.7
category-class "FT"
mesh-detail-level-count 4
mesh-table
{
default-lod0
{
mesh "car_lod_0.im"
auto-create 1
lod-level 0
}
default-lod1
{
mesh "car_lod_1.im"
auto-create 1
lod-level 1
}
default-lod2
{
mesh "car_lod_2.im"
auto-create 1
lod-level 2
}
default-lod3
{
mesh "car_lod_3.im"
auto-create 1
lod-level 3
}
}
thumbnails
{
0
{
image "screenshot.jpg"
width 240
height 180
}
}
kuid <kuid:661281:11003>

Let's break this down to understand what each part is / does.

kind "scenery"
username "Car_Example"
trainz-build 3.7
category-class "FT"
You will find these first 4 parameters in the config.txt file outlined in [[KIND TrainzBaseSpec]].

====Number of LODs====
mesh-detail-level-count 4
This parameter is set manually. This specifies the number of LODs our content will use. If you have 2 LODs in your object then you would change the 4 to a 2. Additional information can be found here in [[KIND Mesh]].

====Mesh Table Structure====
mesh-table
{
default-lod0
{
mesh "car_lod_0.im"
auto-create 1
lod-level 0
}
default-lod1
{
mesh "car_lod_1.im"
auto-create 1
lod-level 1
}
default-lod2
{
mesh "car_lod_2.im"
auto-create 1
lod-level 2
}
default-lod3
{
mesh "car_lod_3.im"
auto-create 1
lod-level 3
}
}
Let's explain what we are doing with the mesh-table section. We have a container which is 'mesh-table' with two brackets '{' and '}'. You'll notice everything contained within these brackets for the mesh-table so it knows what parameters are to be part of the mesh-table section.

Inside the first '{' bracket we find another section called default-lod0 and it too has it's own '{' and '}' brackets as it too has parameters that it controls. You will notice there are 4 'default-lod' sections that look very similar. Each of the 'default-lod' sections are a level of detail that is manually specified.

In the first section 'default-lod0' we have the 'mesh' parameter and have given it our highest detailed mesh called "car_lod_0.im". We also specify another parameter called 'auto-create' which tells Trainz to make this object visible as soon as the mesh loads, so we set this to '1'.

Following those 2 parameters we have a final parameter called 'lod-level' with the value of '0'. This means that our 'mesh' which we specified as "car_lod_0.im" is to be used as 'lod-level' 0. NOTE: LOD detail reduces the higher the lod-level number specified, e.g. 'lod-level 0' should be the highest detailed polygon model you are using. 'lod-level 1' should use the model that has significantly less polygons than the one being used in 'lod-level 0' ... and so on. You only need to specify a number of 'default-lod' sections that is equal to the number of LOD meshes you have exported. Also worth noting, the 'default-lod' section names are not used by the game itself, but they have to be unique. The 'lod-level' parameter is what determines the level of detail for that section, not the 'default-lod0' name.

The mesh-table section has a lot of parameters to choose from. Additional parameters can be found here "[[%22mesh-table%22_Container]]".

====Thumbnails====
thumbnails
{
0
{
image "screenshot.jpg"
width 240
height 180
}
}
The thumbnails section can be found here "[[KIND_TrainzBaseSpec]]".

Simply create a 240 wide by 180 high .jpg image of your object and save it in the directory where you have your .IM, .texture.txt and config.txt files.

Here is the car example:

[[File:car_screenshot.jpg]]

====Creating a KUID====

kuid <kuid:661281:11003>
This KUID is the unique ID for your Trainz Asset. The first number "661281" is your user ID (if you're not sure, see the next section on how to find your UserID). The second number "11003" is any old number we want BUT, it has to be unique to your content! A good idea is to come up with a numbering system such as having 0 - 1000 for locos, 1001 to 5000 for scenery objects and so on. For detailed information can be found on "[[KUID]]s" page.

====Finding your User ID====
In Content Manager, once you login to your [[Planet Auran account]], you'll find your User ID by going to File -> Settings, then click on the Internet tab. You will need this number to create any Trainz assets as it is used in the unique number that each asset requires (called a [[KUID]].)

[[File:your_kuid.jpg]]
===Importing Content into Trainz===

Now that you have everything in a folder ready to go, you can drag that folder onto Trainz Content Manager to start to get this content into Trainz.

[[File:folder.jpg]]

If the files exist in Content Manager already, a prompted will show asking if you want to write over the files. If you know the files existed previously because you put them there, you will always want to say "Overwrite All" but if you are not sure, best to "Skip All" and investigate which content you are actually copying over.

[[File:overwrite.jpg]]

Once you copy over the top of the content you will see a couple of warnings. You can ignore these if they are the following:
* "Asset [KUID] is already installed."
* "Replaced previously installed an open for edit asset [ASSET NAME]"

[[File:warnings.jpg]]

Once you have no errors with the import you can commit your assets by right clicking on the asset and going to "Edit" -> "Commit" or using the CTRL+M shortcut key (you will use this a lot so might be good to learn the shortcuts)

[[File:commit.jpg]]

====Import Errors====
Make sure you don't get any errors after you commit your Trainz asset. You will see the big exclamation mark icon appear if your Trainz asset has errors.

[[File:commit_with_errors.jpg]]

To find out what the errors are you right click on the Trainz asset and go to "View Errors & Warnings". You must fix all errors before the asset will appear in Trainz. If you can't work out how to solve an error, check out the "Potential Problems" section below.

[[File:commit_with_errors_view.jpg]]

== Finding the new Asset in Trainz Simulator 12 ==

Time to load up Trainz and give this content a spin! When you get into Trainz, click on Create Route to start a new route.

Depending on what asset type (kind) you have specified will determine where you will find you asset. We have created a "Scenery" type so we will find this in the "Objects" -> "Object Mode" (or hit "O" for the shortcut key). Place one of these in your scene and zoom your camera to view all the LODs change as your distance from the object changes. If you can barely notice the level of detail changing (but it does actually work!) then you have done a really good job of making the LOD models change seamlessly.

In the examples below to make it very easy for you to spot the LOD change, we have given the highest detail (LOD 0) a RED dot, the medium detail (LOD 1) an orange color and the lowest detail (LOD 3) a green color. We have skipped LOD 2 in this instance but it is recommended to have 4 LODs to a high detailed model if possible.

LOD 0 - In Trainz Surveyor

[[File:surveyor_lod_0.jpg]]

LOD 1 - In Trainz Surveyor

[[File:surveyor_lod_1.jpg]]

LOD 3 - In Trainz Surveyor

[[File:surveyor_lod_3.jpg]]

==Potential Problems==

To see additional stats while working in Surveyor to help determine potential problems with your Trainz asset or even just route creation in general using others assets, you might want to take a look here "[[Runtime_Performance_Statistics]]".

Furthermore, you can also find some really good information about content creation on the [http://forums.auran.com/trainz/blog.php?769929-Trainz-Developer-Blog Trainz Developer Blog].

If you have read all there is to read on this wiki, and are still having problems getting this tutorial or other content working, then you probably should join in the discussions on on our Trainz Community on the [http://forums.auran.com/trainz/index.php Trainz Forums]. The forums are very active and if you show you are keen to learn, the people are very helpful!

==Source Files==

You can download the source files to the Car Example (asset folder) used in this tutorial here: [[File:Carpackage.zip]] or [http://online.ts2009.com/mediaWiki/images/d/db/Carpackage.zip here]. Please note we have not referenced the same image for all 3 LODs. In this example we are changing colors to show you the different distances the LODs pop in. You should generally try and share one diffuse texture between the different LODs so that it saves on memory and performance.

If the source files you download look scary, don't worry! The Trainz Exporter for 3DS Max creates all those files except the "config.txt" file for you.

Good Luck and we can't wait to see your high detailed content for Trainz (with LODs!!!).

==Return to Index==

[[HowToGuides|<< How To Guides]]

[[Category:How-to guides]]

Content Creation

2018-06-06T03:26:49Z

Windwalkr:

These pages are intended for information-sharing between N3V employees and content creators. Information contained herein may refer to future Trainz versions or proposed functionality, and should not be construed as a promise of support. Registered users should feel free to edit content to provide additional information, or clarification and corrections to existing information. Please keep discussion to the comment areas and forums.

==Content Creation Guides==
[[HowToGuides]] - ''A list of 'How To' Guides explaining various content creation tasks.''

[[Modeling]] - ''Preparing models, textures, LOD and animation.''

[[Content Configuration]] - ''A reference manual covering all content types.''

[[Scripting]] - ''Script programming.''

[[Physics]] - ''Simulation and tuning.''

[[Terminology]] - ''A summary of Trainz terms.''

[[Route and Session Creation]] - ''Techniques relating to building a route and the associated gameplay sessions.''

[[Asset Validation]] - ''The latest information about asset validation changes and DLS uploads.''

[[Performance]] - ''The master page for all things performance-optimisation related.''

==All Things Trainz==

[[TRS19]] - ''The upcoming release of Trainz.''

[[TANE]] - ''The current release version of Trainz.''

[[Trainz Release Versions]] - ''A history of the Trainz family.''

[[Download Station]] - ''What it is, and what we're doing with it.''

[[Content Management]] - ''The zen of content management.''

[[Trainz Online]] - ''Detailing the in-game web experience.''

[[Tools]] - ''Executables which complement the Trainz game environment.''

[[Downloads]] - ''Downloadable builds and tools for development and test purposes.''

==News==
[[Special:Recentchanges|Recent changes]] to this wiki.

[[:Category:Feature Request|Feature Request Pages]]

[[Special:Search|Search]] the wiki.

[[TRS19]] Content Creator Documentation (work in progress).

==Community==
[[Content]] - ''A list of Trainz content, both released and work in progress.''

[[Routes]] - ''Planning and building routes in Surveyor.''

[[Content Creation Groups]] - ''Third party content creation groups.''

[[Content Creation Projects]] - ''Third party content creation projects.''

Want to help us improve this documentation? Check out the [[:Category:TBD]] page for a list of topics which have been flagged for attention.

Albedo map

2018-06-06T03:26:01Z

Windwalkr:

The albedo map defines the base RGB color of each [[texel]]. It is configured using a [[texture.txt file]] which is directly referenced from the material (usually within a [[mesh file]] although sometimes from the asset's [[config.txt]] directly).

The albedo map is the [[Physically Based Rendering]] equivalent of the ''diffuse map'' used in legacy materials. At a casual glance, these fill the same role and the terms can be interchanged, however to be strictly accurate the albedo is the surface color irrespective of any lighting effects, whereas the diffuse map frequently included burned-in lighting (pre-baked [[ambient occlusion]], etc.) The albedo map should never include pre-baked lighting, as that would interfere with the correct operation of the PBR equations.

= Color Space =
Unless otherwise specified by the [[Material Types|material]] in use, the RGB channels use the sRGB color space.

= Alpha Channel =
It is common for (semi-)transparent materials to store the alpha blend factor (ie. opacity level) in the albedo map's alpha channel. Materials which are fully opaque may use the albedo's alpha channel for some other purpose, or not at all.

If no alpha channel is specified, the outcome is identical to a fully white (1.0) alpha channel.

Some legacy [[Material Types|material types]] offer automatic selection of [[alpha blending]], [[alpha masking]] or opaque rendering modes based on the contents and configuration of the albedo map. This introduces uncertainties when texture replacement is used as to what material configuration will result. [[TRS19]] materials do not attempt this, and instead rely on the content creator to select the appropriate material type.

= Examples =

''TBD: See [[Normal map]] for examples.''

[[Category:Texture mapping]]

Animation

2018-06-06T03:25:27Z

Windwalkr:

Any [[mesh]] with a [[skeleton]] may have animations applied. Animations in Trainz are stored in the "*.kin" file format. These are created during [[FBX file]] import and are referenced in the [["mesh-table" Container]] etc. If a mesh has a skeleton but does not have any animation applied, it will be displayed in its [[bind pose]]. Animations are not strongly tied to the mesh from which they are initially exported; they may be reused with any compatible mesh.

= Partial Animation =
Multiple animations may be applied to a single mesh.

Each animation may affect any subset of the skeleton's bones.

Multiple animations may affect the same bones.

Any bones unaffected by animation remain in the bind pose.

= Idle Animations=
Whether an animation is actively playing/progressing or not is a separate concept from whether it is applied to the mesh. An animation which is paused but still enabled will still deform its mesh.

= Animating Multiple Meshes =
An animation file may be reused for multiple meshes. Aside from a small memory saving, this does not have any performance benefits, but can help simplify complex configurations which require multiple meshes to animate simultaneously. As an example of this, a full-body humanoid figure may be animated to walk. The animation is exported. The mesh may then be broken into separate pieces (arms, torso, legs, head) which are added to the scene individually. Finally, the single original animation is applied to each of the pieces. As long as the animation is played in sync on all of the meshes, the humanoid walks as before.

The important thing to understand here is that there are more bones in the animation than exist in any individual mesh. The animation is fully simulated for all bones, but each mesh only receives its appropriate bone transforms.

[[Category:Modeling]]
[[Category:Content creation]]

Clutter Effect Layer

2018-06-06T03:25:17Z

Windwalkr:

The [[Clutter Effect Layer]] is an [[Effect Layer]] type which is used to render small localised ground clutter (small foliage, stones, etc.) As with all effect layers, clutter is painted onto the terrain and automatically generates appropriate geometry for the area surrounding the camera.

= Modelling Configuration =

Before you start looking at creating assets for Clutter Effect Layers you should have a very good knowledge on how you go about modelling efficient meshes for each LOD level and what textures you should be using for each mesh LOD. You can find an excellent reference on how to model and texture assets under the [[Art_Recommendations#Modeling_Overview|Modelling Overview]] on the Art Recommendations Trainz wiki page.

When using a large amount of clutter objects onscreen at one time, it's best to have at least the lowest LODs (which shouldn't be very far from the camera) using a [[Texture Atlas]]. The texture atlas should be as small as it can be while maintaining good visual results (256x256 perhaps) and will hold all the images for all the assets lowest LODs. This means when the lowest LODs are showing (which should be the majority of clutter onscreen most of the time) you'll only be paying the cost of 1 material shared across all the lowest LODs.

You will also want to share as many single textures between as many assets as possible to cut-down on draw calls where possible - If you have 3 ferns all of different sizes, don't make 3 copies of the same texture.

You will want to make sure you understand how to create a Trainz [[Mesh Libraries|Mesh Library]] asset so you can utilise Texture Atlases and sharing of textures between multiple meshes.

Once you start to construct your Trainz mesh library asset be sure to use the [[m.clutter]] material for all your meshes. This will allow your clutter asset to fade in and out where required. You will also want to take note about the fadeInEndDistance and fadeOutEndDistance in your [[mesh metadata file|mesh metadata files]] to get your fade transitions correct.

== Clutter Asset Selection ==
There are several factors to consider when determining which assets you should put in a clutter layer:

1. How big is the asset? Anything that has a size of ~1 meter cubed or smaller can be considered as clutter. This is not to say it must be clutter but anything larger than that you should place with the Objects tab.

2. To get the nice fade-out transition (and fade-in if you've configured that) your clutter asset should use the material [[m.clutter]].

3. LODs are a MUST! If your asset has no LOD or poor LOD don't even consider using it for clutter as it will be very performance heavy.

= Example Usage =

[[File:clutterexample1.jpg|1000px]]

= Asset Creation =
The clutter effect layer is a pre-release feature and details of the asset creation techniques may change prior to release.

You can find all the information on creating clutter assets under [[m.clutter]].

It is strongly recommended that assets created for use in a clutter effect layer are small, relatively low polygon (100-500 polygons at highest LOD), with very efficient LOD (typically down to 5-10 polygons at lowest LOD) and using the [[m.clutter]] material type. It is possible to create very attractive and high-density scenery with well-built clutter assets. However inefficient asset creation can very quickly lead to very poor performance.

== See Also ==

[[TurfFX_Effect_Layer]]

For specific guidance how to create and paint clutter layers in Surveyor see: [[Help:Effect_Layer_Dialog]]

Back to [[Effect_Layer]]

[[Category:Modeling]]
[[Category:Content creation]]
[[Category:TRS19]]

Effect Layer

2018-06-06T03:25:07Z

Windwalkr:

[[Effect Layer]]s are a new [[TRS19]] feature which offer the ability to use Surveyor to paint various effects beyond the traditional ground height and ground texture. Each effect layer typically offers a number of configuration options, including a configurable data density so that route creators can tune the outcome to their specific requirements, dedicating performance to areas which are important to their route while lowering detail and/or flexibility in other less-important areas in order to maintain high overall performance.

= Effect Layers UI =
Effect Layers are configured per route. A new "Edit Effect Layers" menu item in the Surveyor main menu pops up an editing dialog which allows the route builder to add, remove, and edit effect layers. An effect layer type is selected when adding a new effect layer, and the type-specific properties for that layer may be adjusted repeatedly until the desired result is achieved. Effect layers are also named, for user convenience.

Most properties of the effect layer are configured on a route-wide basis, however some special properties may be configured to change across the route, using data bindings.

= Configuring Effect Layer Data Bindings =
Specific effect layer properties support data binding. This allows the route builder to paint (eg. using the ground height tools) the property onto the terrain, rather than setting it to a single value route-wide. For many effect types, this is used to configure the intensity of the effect at various locations on the route, although other properties and data types are also configurable in this manner.

There is a limited amount of data reserved in the route for effect layer data bindings. It is up to the route builder to determine how best to use the available data space to best effect. Each property which supports data binding may be configured with a set resolution (higher resolutions consume more data) and precision (higher precision consumes more data). The route builder determines which effect layer need the most precise control, and dedicates the majority of the available data space to those layers.

Adjusting data bindings is a computationally expensive operation. On a large route, this process can take a number of seconds. An uninterruptible progress indication will show during this process. It is not possible to "undo" a change to a data binding, so the route builder should save changes before editing bindings in an existing route.

= Painting Effect Layers =
Once an effect layer data binding has been configured, the route builder may begin painting in the effect layer. Surveyor's "Topology - Advanced" tab offers a new "Effect Layer" picker which allows the route builder to select either "Ground" or one of the effect layer data bindings. A button is also present in this location to quick-open the relevant Effect Layer properties. After selecting the target data binding, the route builder may use the topology tools (height up, height down, etc.) to manipulate the bound data.

As the Surveyor brush size is variable, it is possible to configure a brush which is finer than the precision of the effect layer data binding. This makes it possible to move the brush to a location where painting will have no effect (since it lies between the bound locations, rather than overlapping one or more). In this scenario, the brush will turn red to indicate that painting will have no effect. The route builder must either increase the brush size, or move the brush to a location which overlaps one of the bound locations. Alternatively, the user can consider adjusting the data bindings to have a higher resolution, at the expense of increase data usage.

= Effect Layer Types =
The current effect layer types are supported:

* [[Clutter Effect Layer]] - for ground clutter such as rocks and foliage.
* [[TurfFX Effect Layer]] - for various types of grass and grass-like flora.

[[Category:Modeling]]
[[Category:Content creation]]
[[Category:TRS19]]