[edit] Document Structure

The WagonX Tutorial set is written over several pages. This page is a base reference for using WagonX config containers, their properties and the values for those properties. Other pages in the series are:

1. How to use the WagonX library
   
2. WagonX Examples and Basic Tutorials
   
3. WagonX Traincar Tutorial
   
4. WagonX Locomotive Tutorial
   

[edit] The WagonX Reference

This page contains details of the WagonX extension container and sub-containers. Links to examples of use will be provided when available.

[edit] Restricted Characters

The characters in the list below cannot be used for some property tag values as they are used by the script to parse or identify values such as list items and other information. They can be used in name and description tags. Use of these characters in tag values is identified in the properties descriptions that follow. See also display-values.

• Comma ( , )
• Semicolon ( ; )
• Backtick/Grave ( ` )
• Colon ( : )
• Caret ( ^ )
• Round brackets ( and )

[edit] Using commas and semi-colons in a list

WagonX uses commas to identify items in a list. Some examples might be "1,2,3,4"for a list of four integers, "Rita, Rose, Ruth" of three nameboards for a Pullman car, and "0,1" for a list of booleans (false and true).
Semi-colons are used to items in a set, where sets are items in a list. Le's say we have three sets each consisting of integer numbers,then we might use something like "1;2;3;4,9;3;6;5,13;12;15;16". The first set is 1,2,3 and 4, the second set 9,3,6 and 5, and the last 13,12,15 and 16.
This notation is common where we might want apply some value to items in a set. For example, our sets might each consist of four meshes for a car to which we want to apply a particular livery. List such as these are commonly used in the values tag.
See also Using semicolons to set multiple values in one property.

[edit] Using the grave symbol in a list

The backtick or grave symbol allows you to set multiple variables on a single function in one property. It's typically used to set the value for all the parameters in the pfx emitter functions. It's also used for mest-attachment-type mesh-translation-orientation parameters. For example, if you want to set the start color with these values (0,0,128,128,128,64), but you want each of those variables to be set in one property then use "0`0`128`128`128`64". You can also use this symbol to populate your set of parameters with variables such as "veh_velocity|/|2`veh_velocity|+2`veh_velocity|-|loc_abs_reverser". In simple english that means the first parameter is the vehicle velocity divided by 2, the second parameter is the vehicle velocity plus 2, and the final parameter is the vehicle length minus the absolute value of the loco reverser. Hmm, that doesn't make a lot of sense but its only an example.

[edit] Other special characters

Caret - The caret/circumflex symbol (^) is a math power operator. It can be used in variables.
Round Brackets - Round brackets are used to group mesh vectors translation and orientation. In this instance, colons are used to separate the vectors. For example, "(0`2`4):(1.2`2`2),(0`0`0):(0`0`0)". See values.
Colon - See Round Brackets above.

[edit] WagonX Properties

There are currently four standard or "top level" WagonX containers that define properties for Marker Lights,text-x, a variation of ACSLib and Misc (miscellaneous). In addition to the standard containers, you can define zero or more additonal property containers that are identified by integer value names starting from 0. Each of these containers are defined below.

[edit] ACS

For help on creating the acs extensions and setting up the acs mesh-table objects, see Naming ACS mesh-table attachments.
Each tag is shown here with sample values. There are no default values.

acs
{
  animated                            1
  use-jbv-animation                   1
  duration                            1.0
}

• animated (1 = true, 0=false)

This determines whether to use animations to move between the coupled and uncoupled state, or use individual static assets for each state.

• use-jbv-animation (1 = true, 0=false)

An animation system the author (DunDun92) made for compressing buffers and dynamic couplings and hoses, which is now being phased out due to performance problems. leave it at 0, unless you are using the JBV BR Mesh Library or BR class 101 mesh library, or any of his other libraries.

• duration (a floating point value)

The time, in seconds, that the mesh animation will take to move between the two states. If animated is set to 0, this will determine the fade duration when switching between meshes (fade duration on mesh objects in trainzbuild 5.0 + can get buggy)

• buffer-length-front float

The distance between a.couple0 and a.limfront in meters. To be used with the jbv animation system. Requires the ‘use-jbv-animation’ tag to be set to 1

• buffer-length-back float

The distance between a.couple1 and a.limback in meters. To be used with the jbv animation system. Requires the ‘use-jbv-animation’ tag to be set to 1

[edit] text-x

WagonX V1.2 or greater. (description yet to be included - ARN and/or headcodes? - validation required)

• controller string

Determines how the property will be controlled. Can be controlled by the user, the running number, or a custom range.

• user
• arn
• range

• range string

Defines the range of values the for the text proprety. It will choose a random index to start

• value string

The default value for the text property. This can be formated in two ways. For texture files with single-character identifiers, each character can be written together (e.g. “a12d”). For texture files with multiple-character identifiers, each identifier needs to be separated by a comma (e.g. “dot,3,dash,k”).

• font int

The default font index for the text property, these values can be changeed by adding a “config-edit” property to the browser-properties.

• files-path string

An optional tag that shortens the number of characters that need to be written to the “values“ tag, assuming they all share the same path or asset library and extension. The path and extension can be specified here (e.g. files-path “images/left/.texture”), where images/left is the path, and .texture is the extension for all the files.

• textures string

The list of texture files to use. The ‘#’ symbol is used by the script as a placeholder identifier for the value input. For example, if it is set to ‘alpha_digit-#’, each letter and number will go where the ‘#’, e.g. If the first chartcher in the value tag is ‘a’, it will look for the texture ‘images/alpha_digit-a.texture’, to use for the first texture effect digit. Each comma separated value coorispinds to the font to use at each index.

• effects string

The texture replacement effects to use for displaying the text.

Each tag is shown here with sample values.

text-x
{
 text-properties
 {
   headcode
   {
   controller                "user"
   range                     "null"
   value                     "2,5,dots,2"
   font                      0
   files-path                "images/,.texture"
   textures                  "fd-#"
   effects                   "fdigit-1,fdigit-2,fdigit-3,fdigit-4"
   }
 }
}

[edit] Misc

The misc container currently contains times, in seconds, for industry loading and unloading. Usually, these times are used to enable animations to run before or after loading/unloading.

Each available tag is shown here with sample values. There are no defaults.

misc
{
  begin-load-time                   5.0
  begin-unload-time                 5.0
  end-load-time                     1.0
  end-unload-time                   1.0
}

• mobile float (added in v1.2)

Setting this to 1 indicates this asset is indended for use on trainz mobile platforms. This will disable and/or compromise certain script features to reduce complexity and improve performance for mobile devices.

• update-frequency float (added in v1.2)

The frequency, in seconds, at which certain event triggered browser-properties are updated. This has a huge impact on performance, and it is best kept as high as possible, ideally 5 or more secconds. The minimum allowed value is 1. If the moible tag is set to 1, the minumum allowed value is 3 secconds.

• begin-load-time (a floating point value)

The time it takes for the wagon to load at an industry

• begin-unload-time (a floating point value)

The time it takes for the wagon to unloading at an industry

• end-load-time (a floating point value)

The time it takes for the wagon end loading at an industry

• end-unload-time (a floating point value)

The time it takes for the wagon to end unloading at an industry

[edit] Marker-Lights

The Marker-Lights container is used to show or hide light meshes that are identied by entries in the config mesh-table.

Each tag is shown here with sample values. There are no defaults.

marker-lights
{
  enabled                             1
  car-minimum-count                   1
  require-locomotive                  1
  night-only                          0
  front
  {
    head
    {
      mesh                            "null"
    }
    tail
    {
      mesh                            "lamp-front-red"
    }
  }
  back
  {
    head
    {
      mesh                            "lamp-back-white"
    }
    tail
    {
      mesh                            "lamp-back-red"
    }
  }
}

• enabled (1 = true, 0=false)

Whether or not the marker lights are active on this asset.

• car-minimum-count (an integer number)

The minimum number of cars that must be present in the consist for the marker-lights to activate.

• require-locomotive (1 = true, 0=false)

If set to 1, a traincar of Class locomotive will need to be present in the consist for the marker-lights to activate.

• night-only (1 = true, 0=false)

If set to 1, the lamps will only be visible at night, otherwise they will be displayed 24/7.

• Front/back head/tail containers

These containers identify the mesh to use for the front, back, head, and tail lamps. These meshes must be in the config mesh-table.

[edit] Browser-Properties

• The browser-properties container is a set of zero or more property containers that hold settings for a property such as a smoke effect, an attachment or even texture replacement. They are quite flexible and suitable most any traincar/loco property.
• A property can have sub properties that are activated with their parent.
• A property container has a number of tags with values. Many are common to different property types but some are unique to a property.
• A container need not contain all available tags.
• We start with a sample of two properties: one for a texture replacement (skin) and the second for a handbrake activation. These are representative only and may not be suitable for your asset,

 browser-properties
 {
   0
   {
     enabled                    1
     property-visibility        1
     name                       "Skin: "
     property-id                "p_skin"
     consist-property-sync      1
     description                "Sets the weathering type"
     kind                       "fx-replacement"
     fx-replacement-type        "texture-replacement"
     meshes                     "null"
     effects                    "texture-albedo,texture-parameter"
     asset                      "texturelib"
     files-path                 "null"
     values                     "0;3,1;4,2;5"
     default-index              -1
     trigger                    "user"
     display-type               "link"
     display-values             "Clean,Weathered,Dirty"
   }
   1
   {
     enabled                    1
     property-visibility        0
     name                       "Handbrake State: "
     property-id                "p_handbrake"
     description                "Toggle the handbrake"
     kind                       "mesh-attachment"
     mesh-attachment-type       "mesh-animation-frame"
     meshes                     "handbrake-lever,braking-system"
     values                     "0;0,30;30"
     events                     "handbrake-release,handbrake-apply"
     duration                   3.2
     default-index              0
     trigger                    "both"
     display-type               "link"
     display-values             "release,apply"
   }
 }

[edit] Supported Tags

Tag explanations. Some examples are included in the definition and, for others, see above for sample of usage.

[edit] asset

Type: String

Example: asset "texturelib"

Compulsory: No

Default: None

Desc: The kuid-table asset to be used by the property. Use this for cases where you need to reference another asset, such as a texture-replacement library. Use this tag, the effects tag, the meshes tag, or the particle-effects tag, but not more than one.

[edit] child-properties

Type: A string of numbers separated by commas.

Compulsory: No

Default: None

Desc: The list of properties that will activate when this property is activated. They will activate at the same index as the parent, similar to consist-property-sync. The property-visibility tag for the child properties should be set to 0. The child properties cannot have their own child-properties tag, and the property-visibility of the child-property must be 0, else it will not activate. You cannot set the child-property to yourself either.

Example: child-properties "2,4,5"

[edit] conditions

(added in v1.2)

Type: String - (a list of strings)

Compulsory: No

Default: None

Desc: For trigger kind “condition”. An array of conditional event(s) that must take place for the property value at the index to activate. Can be one of the following (separated by forward slashes and commas to save space).

The format in each comma-separated condition is a basic comparison operation with a left side, an operator, and a right side. The left and right sides can either be a variable (listed below), or a number (integer or float). The three parts are separated by a vertical bar. You can add more comparison operations to the same condition by adding an “&” (and) symbol after the first condition, then adding the second comparison operator (shown in the default conditions example above in black)(this is separate from the comma separation). You can add as many “&”s as you want to the operation, however it will get very long very quickly. The operators used are “==” (equals), “>” (greater than), “<” (less than), “>=” (greater than or equal to), “<=” (less than or equal to), and “!=” (not equal to), and must follow that format.

• veh

Contains functions used within Class Vehicle. Subclasses can be any of the listed ones below. All of these are derived from Class Vehicle. Please refer to that page for information on function behavior and usage.

example 1: veh_velocity|>=|5&veh_mass>1500 -> in plain English this reads, “If vehicle velocity is greater than or equal to 5 m/s and the mass is greater then 1500, then…. do something.

example 2: veh_engine-param_main-reservoir-pressure|<|0.5 -> in plain English this reads, “If the vehicles engine parameter, ‘main-reservoir-pressure’ is greater than 0.5, then…. do something.

For float:

• velocity (float)
• abs-velocity (float)

The absolute value of the velocity, this is useful because moving in reverse will give negative inputs for “velocity”, but positive for “abs-velocity”

• mass (float)
• length (float)
• load-time (float)
• odometer-distance (float)
• trip-meter-distance (float)
• track-gradient (float)
• maximum-tractive-effort (float)
• default-maximum-tractive-effort (float)
• wheelslip-traction-multiplier (float)
• traction-multiplier (float)
• aux-reservoir-pressure (float)
• brake-cylinder-pressure (float)
• brake-pipe-pressure (float)
• cabin-sway-amount (float)
• coupling-stress (float)
• default-cabin-sway-amount (float)
• default-maximum-coupler-compression-stress (float)
• default-maximum-coupler-expansion-stress (float)
• maximum-coupler-compression-stress (float)
• maximum-coupler-expansion-stress (float)
• maximum-couple-velocity (float)
• default-maximum-couple-velocity (float)

For bool:

• coupler-breakage-enabled (bool)
• direction-relative-to-train (bool)
• drain-cocks (bool)
• random-automatic-running-number-support (bool)
• automatic-running-number (bool)
• high-beams (bool)
• is-ditch-flashing (bool)
• automatic-fireman-state (bool)
• interior-light (bool)
• interior-light-state (bool)
• bell-state (bool)
• has-bell (bool)
• in-tunnel (bool)
• on-bridge (bool)
• derailed (bool)
• loaded-this-stop (bool)
• unloaded-this-stop (bool)

For integer:

• engine-type (int)
• vehicle-type-flags (int)

For string:

• running-number (string)

And the engine parameter string:

• engine-param

The main engine parameter strings you can use with this method are:

• applied-force
• brake-cylinder-pressure
• brake-pipe-pressure
• current-drawn
• equaliser-pressure
• flow
• horn
• main-reservoir-pressure
• max-te
• no3-pipe-pressure
• wheelslip

Values that refer only to steam engines:

• coal-mass
• engine-force
• fire-temperature
• max-coal-mass
• max-fire-temperature
• steam-boiler-liquid-percent
• steam-boiler-pressure
• steam-piston-cycle

• loc

Contains functions used within Class Locomotive. Subclasses can be any of the listed ones below. All of these are derived for Class Locomotive. Please refer to that page for information on function behavior and usage.

• engine-setting

• The engine setting, currently the only one for the parent class ‘loc’.
• dynamic-brake
• headlight
• horn
• injector
• loco-auto-brake
• pantograph
• regulator
• reverser
• abs-reverser
• steam-blower
• throttle
• train-auto-brake
• train-lap-brake
• script-brake-pressure

• tra

For class Train

For float:

• smoothed-velocity (float)
• train-velocity (float)
• abs-smoothed-velocity (float)
• abs-train-velocity (float)
• dcc-throttle (float)
• train-brakes (float)
• speed-limit (float)
• advisory-limit (float)
• advisory-limit-2 (float)
• ai-train-max-speed (float)

For integer:

• autopilot-mode (int)
• reverser (int)
• pantograph-state (int)
• classification-signal (int)
• train-priority-number (int)
• frontmost-locomotive (int-bool)

For bool:

• allows-user-control (bool)
• headlight-state (bool)
• ditchlight-state (bool)
• bell-state (bool)

For string:

• train-display-name (string)
• owning-client (string)

• wor

For class World

For float:

• camera-yaw
• camera-pitch
• camera-zoom
• game-time
• game-season

For integer:

• weather-type
• weather-changeability
• camera-mode
• camera-flags
• game-time
• game-year
• game-month
• game-date
• game-session
• current-module

For string:

• local-player-name (string)

For bool:

• restart-stuck-ai (bool)
• asset-restriction-in-effect (bool)

[edit] consist-property-sync

Type: Integer - (0 off, 1 on (button), 2 on (automatic)

Compulsory: No

Default: None

Desc: Whether or not to sync the property within the consist, if a tag with the same property-sync-id exists in the other assets. Omitting or setting the tag to 0 disables this. Setting it to 1 will create a button to the right of the property that can be clicked on to sync the property. Setting it to 2 will automatically sync the property across the consist whenever a change in the property is detected.

[edit] default-index

Type: Integer (-1 = random)

Example: default-index 0

Compulsory: No

Default: 0

Desc: The default index for the property to start at. This will be 0 if the tag is left out. If it is -1, it will choose a random index to start at.

Warning: If you have a list of values such as "1,2,3,4" and you want to set a default, then you should subtract 1 from the preferred value. For example if you want the first in the list then set the default to 0. This is because the browser counts the list entries from 0 and not 1.

[edit] description

Type: String

Compulsory: No

Default: None

Desc: The description of this attachment as it will appear in the Properties Browser.

[edit] display-type

Type: String

Example: display-type "link"

Compulsory: No

Default: None

Desc: For trigger type “user” and “event” only. The type of button this will be. It can be any of the trainz property browser value types, plus “manual”, but not map-object or asset-list. For trainzbuild 5.1 and 5.0, only link is supported for the View Details page. Omitting this tag in combination with property-visibility set to 0 is useful for non-user triggers, such as world or train events.

• string
• int
• float
• list
• link

[edit] display-values

Type: String - (a list of strings)

Example: display-values "Clean,Weathered,Dirty"

Compulsory: No

Default: None

Desc: For trigger type “user” and “event” only, and required for trigger type “user” properties to work, but optional for trigger type “event”. A list of comma-separated values which will be displayed in the view details page for the respective property. The number of values here must match the number of values in the “values” tag.

[edit] duration

Type: Float

Compulsory: No

Default: None

Desc: For kind mesh-animation and mesh-toggle. This tag determines the time to transition to the next state for the value. If it is 0, the transition will occur instantaneously. (There may be issues with using this tag with mesh-toggle.)

Example: duration 3.2

[edit] effects

Type: String - (a list of texture names (i.e. texture.txt names without the .txt) each separated by a comma)

Example: effects "texture-albedo,texture-parameter"

Compulsory: No

Default: None

Desc: The comma-separated effect(s) to be modified by the property. Only use this tag if you are using kind fx-replacement. Use this tag, the mesh tag, or the asset tag, but not more than one.

[edit] enabled

Type: Boolean (1 = true, 0=false)

Compulsory: No

Default: No default.

Desc: Whether or not this property is active. This is useful for debugging, or if you want to disable it without removing everything.

[edit] events

Type: String - (a list of strings)

Example: events "handbrake-release,handbrake-apply"

Compulsory: No

Default: None

Desc: For trigger kind “event” only. An array of the event(s) that must take place for the property value at the index to activate. Can be one of the following (separated by forward slashes and commas to save space).

• begin-load/end-load/begin-unload/end-unload
• started-moving/stopped-moving (added in v1.2)
• handbrake-apply/handbrake-release
• trainbrake-apply/trainbrake-release
• headlight-on, headlight-off
• throttle-changed (added in v1.2)
• front-coupled/back-coupled,front-uncoupled/back-uncoupled (added in v1.2)
• view-internal, view-external, view-tracking, view-roaming (added in v1.2)
• horn
• bell
• sanding
• pantograph-state-0/1/2/3 (see GetPantographState)
• weather-0/1/2/3/4/5/6/7 (see GetWeatherType)
• world-day/world-night
• priority-number-(0 - ∞) (e.g. priority-number-2) (added in v1.2)
• arn-(0 -∞ ) (e.g. arn-92220, arn-844) (added in v1.2)
• queue-(0 - ∞)- loaded/empty (e.g. queue-0-loaded, queue-1-empty)