TrainzOnline - User contributions [en]

Help:VE189

2026-09-05T03:36:36Z

Pcas1986: Added link to HowTo/Configure a spline for collsions

'''Collision data exceeds 64KB and has been simplified. Consider using a different generation method or a simplified mesh.'''

The asset contains complex geometry for which the selected (or default) collision geometry generation technique generated excessively complex results. This would increase memory usage and decrease performance, and as such is prevented by the game- a simplified collision geometry is used instead. This may be harmless, but it also may result in collision detection behaviour from differing from the creator's expectations. Either way, it costs unnecessary performance when installing or validating the asset, and emits undesirable warning messages.

Resolving this message may involve one or more of:

1. Lowering the amount of detail in the mesh in question. If this can be achieved without degrading the visual quality of the asset, then this is a win both from the perspective of removing the collision data problems, and also from the perspective of rendering performance. This approach is not recommended if visual detail needs to be sacrificed.

2. Overriding the [["mesh-table" container#collision-data-generation-mode|collision generation settings]] for the mesh-table entry in question to select a more efficient method. This is suitable in scenarios where a simplified collision data technique can be used on the mesh without compromising physical responses (such as PFX collisions) to any significant degree. This does not have any effect on the visuals.

3. Using the [["mesh-table" container#collision-mesh|collision-mesh tag]] to specify a separate lower-detail mesh to use for collision purposes. This approach offers the ultimate in manual control at the expense of having to maintain an additional mesh purely for collision purposes.

'''Additional Help''': See also this article about splines and collision data: [[HowTo/Configure a spline for collisions]]

[[Category:Validation Errors]]

"mesh-table" container

2026-09-05T03:32:33Z

Pcas1986: /* collision-data-generation-mode */ Added link to HowTo/Configure a spline for collisions

{{ORP-top}}
==KIND Hierarchy==
The "mesh-table" container is a top-level [[config.txt file]] entry used by various [[Content_Configuration#Content_Types|Content Types]].

The mesh-table is a list of mesh subcontainers with no standalone tags. Each mesh subcontainer uses the following format. Tags are parsed in a standardised format, but not all [[Content_Configuration#Content_Types|Content Types]] support the full range of tags listed below. Each mesh derives its name from the subcontainer's tag name. These names are used to refer to specific meshes from within the mesh-table and also from script.

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

==Known Dependent Parent Types==
:''Main article, see: [[KIND Mesh]]''
The Content Types listed here use the mesh-table container as part of their definition.

* [[KIND Industry]]
* [[KIND MOJunction]]
* [[KIND Pantograph]]
* [[KIND Scenery]]
* [[KIND Track]]
* [[KIND Traincar]]

The following config containers also reference back to their Asset's mesh-table container in some fashion:
* [["junction-vertices" container]]
* [["track-lod-tree" container]]

'''See also'''{{bullR}} [[Modeling Guidelines]] {{bull}} [[Modeling Scenery]]

==Level of Detail (LOD)==

For discussions of LOD see [[Level of Detail]], [[LOD Example]], [[mesh-table LOD]] and [[LM.txt file]]

==Mesh subcontainer==
Each mesh subcontainer supports the following tags. Each tag is shown here with its default value.

{| border=0
|+
|-
| anim
| ""
|-
| animation-loop-speed
| 0
|-
| att
| ""
|-
| att-parent
| ""
|-
| auto-create
| 0
|-
| collision-data-generation-mode
| "default"
|-
| collision-mesh
| ""
|-
| critical-animation
| 1
|-
| does-cast-shadows
| 1
|-
| effects
| {
|-
| }
|-
| lod-level
| 255
|-
| mesh
| ""
|-
| mesh-asset
| <NULLKUID>
|-
| mesh-scale
| 0,0,0
|-
| mesh-season
| 255
|-
| night-mesh-base
| ""
|-
| opacity
| 1.0
|-
| orientation
| 0,0,0
|-
| position
| 0,0,0
|-
| should-respond-to-clicks
| 1
|-
| use-parent-bounds
| 0
|}

<big>*</big> The att-parent defaults to "default" which is the parent mesh. The att-parent tag can include a path.

==Supported Tags==
Each mesh subcontainer supports the following tags.

===anim===
:Type: File
:Default: ""
:Compulsory: No
:Desc: The animation file (.kin) exported from the 3D modelling tool and/or [[Trainz_Mesh_Importer|TrainzMeshImporter]]. This may include a sub-path.

===animation-loop-speed===
:Type: Float
:Default: 0
:Compulsory: No
:Desc: This tag must be present if the asset is to animate when placed. If this tag is not present when placed the animation will not play by default, but may play if controlled by script. A different value (e.g. 0.5, 2.0) may be used in the tag to play the animation at a different speed from that created in the 3D modelling tool.

===att===
:Type: Attachment point
:Default: ""
:Compulsory: No
:Desc: The mesh (and animation if present) is inserted at a mesh attachment point rather than the origin (without this line the mesh is placed relative to the origin of the parent model).

===att-parent===
:Type: Mesh name
:Default: Defaults to "default" which is the parent mesh
:Compulsory: No
:Desc: The tag tells Trainz in which mesh the attachment point is located. The insertion attachment point is located within the mesh ‘name’ , as listed in the config.txt.

===auto-create===
:Type: Bool
:Default: 0
:Compulsory No
:Desc: The model is generated automatically when placed, or when you load a map which includes the model. In some instances you don’t want the mesh visible (as this may be controlled through script). If auto-create is 0 the mesh will not be visible when placed.

===collision-data-generation-mode===
:Type: Collision mode
:Default: "default"
:Compulsory No
:Desc: Determines the method to use to generate collision data for this mesh. Collision data is used to select and move the asset in surveyor, and for physics simulation when necessary.
:Supported collision data generation modes:
:* "default" - use game's default value (in general "collated", but can vary in specific cases)
:* "disabled" - completely discard this sub-mesh for collision data generation purposes. Causes the sub-mesh to be fully ignored for asset picking and physics simulation.
:* "collated" - the geometry of this sub-mesh will be added to that of the other sub-meshes selecting this option (within the asset), and one collision object will be generated for the resulting conglomerate.
:* "separate-shape-convex-hull" - this sub-mesh will generate its own individual collision object, as a convex hull.
:* "separate-shape-triangle-mesh" - this sub-mesh will generate its own individual collision object, as a triangle mesh. This is the most accurate option but also the most costly in terms of performance, only use when specifically needed.

If you get the error "Failed to generate collision data". This will be because one of your meshes must have collision in order for Trainz to generate the collision data from it. If your mesh isn't suitable for collision generation then look at using a collision mesh. See [[%22mesh-table%22_container#Mesh-Table_Example_.28with_collision.29|Mesh-Table Example (with collision)]] at the bottom of this page on how to do this. See also this article discussing splines and collision data. [[HowTo/Configure a spline for collisions]]

===collision-mesh===
:Type: Mesh name
:Default: ""
:Compulsory No
:Desc: Specifies a mesh to use instead of this mesh to generate collision data - must be an entry of this mesh-table. The method used to generate the collision data (through the "[[%22mesh-table%22_container#collision-data-generation-mode|collision-data-generation-mode]]" tag) is the one specified on this entry, which is allowed to be different from that of the referenced mesh.

===critical-animation===
:Type: Bool
:Default: 1 (TBD: surely this should be false (0))
:Compulsory: No
:Desc: "critical-animation" indicates that this mesh's animation generates events which are critical to the script system's behavior. If your asset is not scripted, does not use scripted animation events, or only uses the events for display purposes and will not break if the occasional event is missed, this tag should be set to ''false (0)''. Leaving this flag set to ''true (1)'' is a '''significant''' performance penalty.

====custom-render-plugin====
:Type: [[KUID]]
:Default: ""
:Compulsory: No
:Desc: TBD

===does-cast-shadows===
:Type: Bool
:Default: 1
:Compulsory: No
:Desc: "does-cast-shadows" determines if this mesh will cast shadows when the user has shadows enabled in the settings. Setting this tag to ''false (0)'' means the mesh will not cast shadows. Setting this tag to ''true (1)'' means the mesh will cast shadows.
:Trainz build 4.4

===effects===
:Type: [[Corona Effect]] | [[Name Effect]] | [[Attachment Effect]] | [[Animation Effect]] | [[Texture-Replacement Effect]]
:Default {}
:Compulsory: No
:Desc: The effects container can contain a list of effect subcontainers. The effect subcontainers support the following generic tags.

: kind ""
: name ""

:Each effect subcontainer supports additional tags depending on the effect kind. The following effect kinds are supported:

:* [[Corona Effect]]
:* [[Name Effect]]
:* [[Attachment Effect]]
:* [[Animation Effect]]
:* [[Texture-Replacement Effect]]

===lod-level===
:Type: Int (0-8)
:Default: 255
:Compulsory: No
:Desc: The [[mesh-table LOD]] level at which this mesh is displayed. The default value (255) indicates that this mesh is visible at all detail levels. See also [[KIND Mesh]] for the 'mesh-detail-level' tag.

===mesh===
:Type: Mesh name
:Default: "" (will raise error if null)
:Compulsory: Yes (3.4)
:Desc: The ‘main’ mesh name. This may include a sub-path. ie: mesh nightwindows/nightwindows.im, where the file nightwindows.im has been placed in the subdirectory nightwindows. Use .im files or reference an [[LM.txt_file]] file if you wish your asset to have ‘Level of Detail’ mesh reduction.
:The mesh name can also refer to an IM file or an [[LM.txt_file]] file in a mesh asset library if the mesh-asset tag is specified. The LM.TXT file should be in the mesh asset library.

===mesh-asset===
:Type: [[KUID]]
:Default: <NULLKUID>
:Compulsory: No
:Desc: Specifies a mesh asset to be used in conjunction with the 'mesh' tag when the mesh is not contained within the current asset. The mesh name specified in the 'mesh' tag must be located in the mesh asset as Content Manager does not check for the existence of the mesh and will not report an error if it is missing. If the mesh is not located in the root folder of the mesh asset then the mesh name in the 'mesh' tag must include the path to the folder.

<div style="background-color: #ddf5eb;border-style: dotted; width:800px; overflow:auto; ">
NOTE: There may be several different versions of the mesh asset installed, with different meshes. The mesh asset KUID number must be the version of the asset in which the mesh in the 'mesh' tag exists.

Example: If the mesh in the 'mesh' tag was added in kuid2:12345:9876:2 and does not exist in earlier versions, then this is the kuid number you must specify in the mesh-asset tag; specifying an older revision number (ie kuid:12345:9876 or kuid2:12345:9876:1) will result in errors. This applies even if the only change between versions is that the mesh is in a different folder.
</div>

===mesh-scale===
:Type: Floatlist
:Default: 1.0,1.0
:Compulsory: No
:Desc: This tag defines a minimum and maximum scaling value for the mesh, where 1.0 is the size as modelled. Each instance of the mesh that exists in the world will randomise within this range. Randomisation will not change between runs or between Trainz editions, but may change based on factors such as the position of the mesh in the world. This tag is currently only supported on SpeedTree assets; attempts to use this tag on other assets results in undefined behaviour.

===mesh-season===
:Type: Int (0-250)
:Default: 255
:Compulsory: No
:Desc: The season index for which this mesh is displayed. The default value (255) indicates that this mesh is visible in all seasons. See also [["Season-selector" container]].

===night-mesh-base===
:Type: Mesh name
:Default: ""
:Compulsory: No
:Desc: Defines this mesh as a "nightmode" mesh. This mesh is visible only at "night" (the exact meaning of which is defined by the [[KIND Scenery#nightmode|nightmode]] tag in the top level of this asset's [[config.txt file]]. This mesh becomes invisible if the specified base mesh is invisible. Prior to [["Trainz-build" tag|v4.3]], nightmode meshes have a [[material emissive color]] (currently 2.0, 2.0, 2.0) forcibly applied to them. From v4.3 upward, it is expected that the creator will set any necessary emissive coloration in the [[IM files|mesh file]] itself.

===opacity===
:Type: Float (0.0 - 1.0)(See below)
:Default: 1.0
:Compulsory: No
:Desc: Specifies the overall transparency of the mesh. Values other than 0.0 or 1.0 employ alpha blending and a value of 0.0 has the same effect as hiding the mesh. Note that this tag is buggy in TS2009 prior to SP4.

===orientation===
:Type: Floatlist (radians)
:Default: 0,0,0
:Compulsory: No
:Desc: Orientation of X,Y,Z axes. Allows a submesh to be rotated relative to its insertion point. To reverse a mesh by 180 degrees about the Z axis, add the tag: orientation 0,0,3.14159

===position===
:Type: Floatlist (metres)
:Default: 0,0,0
:Compulsory: No
:Desc: Position of the mesh using X,Y,Z axes relative to its insertion point.

===radius===
:Type: Float
:Default: TBD
:Compulsory: No
:Desc: TBD (should this be in [["mesh-table"_container_(interior_version)]]?)

===should-respond-to-clicks===
:Type: Bool
:Default: True(1)
:Compulsory: No
:Desc: If set to false (0) on a mesh that is part of an asset, it will remove that mesh from the calculation of the 'bounding box' that will be used to check whether the user clicked on that particular asset. This is useful for light ray effects or animations which are significantly outside the normal bounding volume, and may cause movement to focus on the wrong asset. For instance, a traincar may need a mesh marked with should-respond-to-clicks set to false in order to ensure that the click is detected for the correct traincar when it is part of a consist. First introduced with TS12 SP1 HF4 (build 61388). Default value (True) is the prior behaviour (the mesh ''will'' be considered part of the bounding box for the purpose of registering clicks).

===test-collisions===
:Type: Bool
:Default: TBD
:Compulsory: No
:Desc: TBD (should this be in [["mesh-table"_container_(interior_version)]]?)

===use-parent-bounds===
:Type: Bool
:Default: False(0)
:Compulsory: No
:Desc: When enabled, this tag indicates that render culling should occur using the whole object's bounding box rather than this mesh's bounding box. Bounding boxes on individual meshes may not update correctly when animation moves the object's geometry any significant distance from the bind position. This flag can help mitigate such effects, at a tiny performance penalty.

==Mesh-Table Example==
The following is an example of a simple mesh-table which implements two levels of detail.

mesh-table
{
default-lod0
{
mesh "example-lod0.im"
auto-create 1
lod-level 0
}
default-lod1
{
mesh "example-lod1.im"
auto-create 1
lod-level 1
}
}

==Mesh-Table Example (with collision)==
The following is an example of a mesh table with a separate collision mesh. For this, we are using a low polygon collision mesh with no material (null.m.notex) in place of any collision the game would generate for us. It's important to put the collision-data-generation-mode to "disabled" for every other mesh that is not the collision mesh. Otherwise, the game will assume the mesh can be used for collision and create unwanted results.

mesh-table
{
default
{
mesh "example.lm"
auto-create 1
collision-data-generation-mode "disabled"
collision-mesh "collision"
}
collision
{
mesh "collision.trainzmesh"
collision-data-generation-mode "separate-shape-triangle-mesh"
}
}

[[Category:Config Container|mesh-table container]]
{{ORP-bot|mesh-table container}}

TrainzScript Message Reference

2026-08-31T02:53:02Z

Pcas1986: Replaced example with one that works without obsolete functions.

==What are Messages and how can they be used?==

Messages:
* Are internal communications between objects within Trainz.
* Are completely hidden from the normal user, who won't be aware of their existence.
* Provide notification of events within the Trainz script environment.
* Provide a means of opening direct communications between objects.
* Provide a means of sending instructions from one script to another.
* Provide a means of timing scripted actions.

Messages are managed by the ''Router'', a sort of internal post office, and can be exchanged between any objects which descend from ''[[GameObject]]'', this includes driver commands, rules and libraries as well as almost all mesh based scriptable objects.

Scripts can:
* Listen for messages and use them to take appropriate actions in response to events and instructions.
* Use the message to extract information about the object sending or receiving the message.
* Define and issue their own messages.
* Listen in to messages intended for other objects.
* Send messages to themselves, to arrive after a specified delay, as a 'reminder' to do something at a future time.

Messages are small data objects containing five pieces of information:
* ''msg.major'': A string identifying the message type.
* ''msg.minor'': A string containing the message subtype or additional information.
* ''msg.src'': A reference to the object that sent the message.
* ''msg.dst'': The intended recipient. May be null if the message was ''broadcast'' (legacy behavior, no longer supported).
* ''msg.paramSoup'': A Soup object containing extra data about the message (may be null).

==How to listen for Messages==

There are three techniques you can use:

* ''[[GameObject#AddHandler|AddHandler()]]'' This is the simplest listening device and is most useful when you know that you will always be interested in this type of message. ''[[GameObject#AddHandler|AddHandler()]]'' is usually set up in the ''Init()'' method of a script. Hint: omit any optional spaces in statements that include an AddHandler function, as including them causes the function to be ignored without notification in TRS2004 and perhaps other versions as well.
* A ''[[TrainzScript Keywords#wait|wait()]]'' loop. This needs to run in a separate thread and allows for a temporary arrangement where you want to know about messages for a shorter period or under a specified set of conditions.
* ''[[GameObject#Sniff|Sniff()]]''. This allows you to 'eavesdrop' on messages being sent to another object.

==When and how to send Messages==

You might consider issuing messages of your own under the following circumstances:

* When an event has taken place in your script and other objects might need to know about it.
* When you want to make your object available to other scripts to allow them to call your methods directly.
* When you need to issue instructions to another object to carry out a particular task and you know that the target object will be able to understand your message.
* When you want your own script to take an action at some time in the future, or at regular intervals.

There are three routines you can use to issue messages:

* [[GameObject#SendMessage|SendMessage()]] dispatches the message immediately. Do not use SendMessage() within a message handler and use PostMessage() instead. A message handler is a static thread and using SendMessage() within a static thread will raise an exception.
* [[GameObject#PostMessage|PostMessage()]] dispatches the message via the Router with a specified delay (which can be zero). The message will be executed on the next Router update after the delay has elapsed.
* [[Class Router#PostMessage|Router.PostMessage()]] allows messages to be dispatched even if the object you are scripting doesn't have its own messaging capabilities.

If the message destination is entered as ''me'' (meaning the current object) the message will be sent to the object which owns the script. If the destination is ''null'' the message will be ''broadcast'' and therefore available to any object in the session. Message broadcasting is obsolete as of TRS19 however, and may result in script exceptions or silent failures (depending on the local players compatibility setting).

If you have a reference to the message target (or if you know its name or id) you should consider the following:

* If you know which methods to use it might be more appropriate to call the other script directly.
* You should always avoid broadcasting messages if it is possible to send them directly to the intended recipient.

==Never Assume Anything==

The messaging system contains many traps for the unwary. If you are working with a junction for instance you will receive an ''Object,Enter'' message whenever a train enters your object's trigger zone. It is not safe however to assume that a subsequent ''Object,Leave'' means that the train has crossed the junction and left on the other side. Any of the following would also produce ''Object,Leave'':
* The train might have stopped and reversed away from your object.
* An intervening junction might have been toggled so that the train is no longer visible to your object.
* The train might have coupled to another (and therefore ceased to exist) before reaching your object.
It is usually necessary to treat a message as an indication that the event you are interested in could have happened and to use other tests to confirm.

==Example==

Listening for messages and using message handler methods

include "World.gs"
include "gstracksearch.gs"
// include this in your config.txt
// script-include-table
// {
// 0 <kuid2:388413:439002:5>
// }
include "traintools.gs"
// script can be attached to any scenery object
// enable the message window to view the output in Driver mode
class Messenger isclass Buildable {
// Global
Train train;
// Function prototypes
thread void GetATrainAndJunctions(void);

public void Init(Asset asset) {
inherited(asset);
int module = World.GetCurrentModule();
Interface.Log("Messenger->Init - current module is " + module);
// see world.gs for module defines
if (module == World.NO_MODULE) {return;} // do nothing
AddHandler(Interface,"World","ModuleInit","ModuleInitHandler");
}

// Listens for trigger messages activated by a train.
// Listening terminates if a train stops within the trigger radius.
thread void TriggerMonitor(void) {
// Trigger messages will be passed to us as a result of the
// Sniff() call in GetATrainAndJunctions
Interface.Log("Messenger->TriggerMonitor - started");
Message msg;
wait() {
// listen for Trigger,Enter, print a message when heard, continue listening
on "Trigger","Enter",msg: {
Interface.Log("Messenger->TriggerMonitor - a train has entered a trigger");
continue;
}
// listen for Trigger,Stopped, print a message when heard and then quit the thread
on "Trigger","Stopped",msg: {
Interface.Log("Messenger->TriggerMonitor - a train has stopped on a trigger");
Interface.Log("Messenger->TriggerMonitor - trigger monitoring discontinued");
break;
}
}
}

// A function to take some action when a message "Junction, Toggled" is sent.
void ToggleHandler(Message msg) {
// print a message whenever Junction,Toggled is broadcast
Interface.Log("Messenger->ToggleHandler - a junction has been toggled");
}

// Seaches for train in the session and returns the first in the list.
// The search uses the asynchonous method that replaces the now obsolete "World.GetTrainList()"
thread void GetATrainAndJunctions(void) {
// get a train and wait for a result
NamedObjectInfo[] searchResults;
AsyncObjectSearchResult searchObject = World.GetNamedObjectList(AssetCategory.Consist, "");
Sniff(searchObject, "ObjectSearch", "", true);
// and wait
Message msg;
wait()
{
on "ObjectSearch", "", msg:
if (msg.src == searchObject) {
break;
}
}
Sniff(searchObject, "ObjectSearch", "", false); // stop listening
// proceed if no errors
if (searchObject.GetSearchErrorCode() == AsyncObjectSearchResult.ERROR_NONE) {
searchResults = searchObject.GetResults(); // get list of trains (consists)
if (searchResults.size() > 0) {
train = cast <Train> searchResults[0].objectRef; // could be null if a train isn't loaded
// This can return the name of the consist or the driver name.
Interface.Log("Messenger->GetATrainAndJunctions-> got " + train.GetTrainDisplayName());
}
}
else {
train = null; // default anyway
Interface.Log("Messenger->GetATrainAndJunctions-> could not get a train");
}
if (train) {
Sniff(train,"Trigger","",true); // listen for trigger messages sent to the train
TriggerMonitor(); // and monitor those messages
}
// Now find some junctions and add handlers for them.
// Note that the tracksearch will stop when the track is broken, such as a junction point,
// or at 8000 metres.
if (train) {
// get some junctions for the test
Vehicle vehicle = TrainTools.GetFrontVehicle(train);
GSTrackSearch gst = vehicle.BeginTrackSearch(TrainTools.VehicleToTrainDriveDirection(vehicle, true)); // Start track search in the driving direction of vehicle
Junction junction;
MapObject obj = gst.SearchNext(); // prime the search
while (obj) {
if(gst.GetDistance() > 8000.0) break;
junction = cast <Junction> obj;
if(junction) {
AddHandler(junction,"Junction","","ToggleHandler");
Interface.Log("Messenger->GetATrainAndJunctions-> found junction-> " + junction.GetLocalisedName());
}
obj = gst.SearchNext();
}
}
else {
Interface.Log("Messenger->GetATrain-> can't start trigger monitor as there is no train.");
}
}

void ModuleInitHandler(Message msg) {
Interface.Log("Messenger->ModuleInitHandler-> module is " + World.GetCurrentModule());
if (World.GetCurrentModule() == World.DRIVER_MODULE) {
GetATrainAndJunctions();
}
}
};

==See Also==
* [[List of Standard Messages]]
* [[Animation-Event Message]]
* [[Browser Messages]]
* [[Camera Messages]]
* [[Interface Messages]]
* [[MapObject Messages]]
* [[ModuleInit Message]]
* [[Object Messages]]
* [[pfx Message]]
* [[Signal Messages]]
* [[Train Messages]]
* [[Vehicle Messages]]
* [[GameObject]]

ModuleInit Message

2026-08-31T02:13:09Z

Pcas1986: Changed the target object in the AddHandler() call to Interface.

Switching directly from Surveyor to Driver mode via the ^F2 shortcut or the ''Quick Drive'' button allows a Driver session to be launched directly from from Surveyor.

However Trainz carries out initialisation tasks for scripted objects when they are loaded into Surveyor and many of these do not need to be repeated when the user switches to Driver mode. Some tasks, such as monitoring threads, will be started by the game if Driver is the first module called, but not otherwise. In consequence these tasks will not run if Driver is launched via ^F2.

The message ''World,ModuleInit'' is provided to allow this issue to be overcome.

If this handler is added in ''Init()''

public void Init(void) {
inherited();
AddHandler(Interface, "World", "ModuleInit", "ModuleInitHandler");
}

It will be possible to track the change between Driver and Surveyor and take any necessary corrective measures in the ModuleInitHandler method.

void ModuleInitHandler(Message msg) {
if (World.GetCurrentModule() == World.DRIVER_MODULE) {
InitialiseDriverTasks();
}
}

[[Class World#GetCurrentModule|''World.GetCurrentModule()'']] allows the current module to be queried from script.

==See Also==
* [[List of Standard Messages]]
* [[TrainzScript Message Reference]]

User:Zahlebme1z

2026-04-10T01:15:16Z

Pcas1986: Replaced content with "Content deleted - spam"

Content deleted - spam

User:Nettikasinot33

2026-02-10T11:10:13Z

Pcas1986: Replaced content with "Content deleted. Spam/possible phishing."

Content deleted. Spam/possible phishing.

Help:ContentManager:Getting Started

2026-01-15T07:19:51Z

Pcas1986: Undo revision 45798 by Alimagdy (talk)

=Getting Started with Content Manager=
Content Manager provides a range of tools to manage, download, and export content in Trainz.

[[File:content-manager-main-view.jpg|300px]]

==The Content Menu==
The top menu in Content Manager shows the same menu options as on the [[Help:TRS19_Launcher|Launcher Screen]], with an additional menu called the Content menu.

The Content menu provides access to all of the options you need for editing, submitting, and managing your content.

===Show Asset Details (CTRL + I)===
Will open a window showing the thumbnail, description, and other details for the selected asset.

===Download===
Will download the selected asset from the Download Station. If a newer version of the asset is available, then that version will be downloaded.

===Download this Version===
Will download the selected version of the asset from the Download Station. Will ignore any newer versions that may be available for download.

===Upload to DLS===
Will upload the selected asset, if it has your UserID number, to the Download Station. Note, if you have modified another person's content then you MUST obtain permission directly from that person before uploading. Some assets may have restrictions, or permissions, outlined in the License of the asset's config.txt file.

===Clone (CTRL + D)===
Will clone the selected asset. The cloned asset will have the 'KUID' number updated to your UserID number, and the next available AssetID number for your UserID.

===Create New Version===
Only available for content under your UserID number. This will create a new version/revision of the asset (ie an asset with the AssetID number <kuid:12345:9876> will become <kuid2:12345:9876:1>).

===Automatically generate Thumbnail(s)===
Will automatically generate a thumbnail for the selected asset.

===Disable===
Will disable the selected asset. This will prevent the asset from appearing in the content lists/tabs in Surveyor. However it will still be fully functional for any routes/sessions/other assets that have it as a dependency.

===Delete (CTRL + Delete)===
Deletes the currently selected asset.

===Open...===
Will show the 'Open' list for assets, which allows you to open for edit or view assets in Trainz from the Content Manager tool.

====Open for editing====
Will open the selected asset for editing. This will place the selected asset in the 'Editing' folder of your LocalData.

====Show in Explorer====
Will open the selected asset for editing, and then open an Explorer or Finder window with the asset's folder in the Editing folder of your LocalData shown.

====Edit Config File Text====
Will open the selected asset for edit, and then open the asset's 'config.txt' file in your computer's default text editor (ie Notepad on Windows, unless another is set as default).

====Edit Primary Script====
Will open the selected asset for edit, and then open the asset's primary 'script' file (ie the '.gs' file) in your computer's default text editor (ie Notepad on Windows, unless another is set as default). Note that some assets may not have a script, or may have a non editable encrypted script file.

====Open Asset in Surveyor====
This option is only available for Route and Session assets. This will open the selected route or session for editing in Surveyor (the same as the Edit Route option from the Driver/Surveyor menu).

====Open Asset in Driver====
This option is only available for Route and Session assets. This will open the selected route or session into Driver mode (the same as the Drive Session option from the Driver/Surveyor menu).

====Preview Asset====
Will display the selected asset in the Asset Preview window. This provides a range of content performance information, and allows you to preview any installed asset in an 'in-game' environment. Will only display the selected asset, no other content is shown in this view.

===Revert Unsubmitted Edits===
If an asset has been opened for edit, this will revert the asset back to it's previous state, reverting any edits performed since it was last opened for edit.

===Revert if Unchanged===
If an asset has been opened for edit, and has not been modified, then this will revert it back to it's previous state.

===Revert to Original===
This option only applies to Built-in or Payware content. If an asset has been opened for edit, and has been modified and then submitted, this will revert it back to it's originally installed state.

===Submit Edits (CTRL + Shift + E)===
If an asset has been opened for edit, then this will submit the asset with any edits that have been made. Note that for built-in and Download Station content, this will result in the asset as being shown as 'modified'.

===View Errors and Warnings===
This will show any applicable warnings or errors for the selected asset.

If an asset has errors, then it will be marked as 'faulty' and will not work in Trainz.
If an asset has warnings, then this indicates that it may have issues that may impact on performance, or may cause it to operate in unexpected ways, but it should still function in Trainz.

===List Dependencies===
Lists the dependencies of the selected asset. Dependencies are other assets required for the selected asset to function (ie the dependencies of a route will include all ground textures, track splines, etc on the route).

===List Dependencies Recursively===
Lists the dependencies of the selected asset, and the dependencies of the asset's dependencies, and so on. In many cases, an asset used on a route (such as an industry object) may have it's own dependencies (ie the attached track, and the commodities used by the industry, and other assets); this option will display the dependencies of any assets used by the selected asset.

===List Dependants===
Lists any assets that depend on the selected asset. For example, if you select a route asset, and click on 'List Dependants', it will show the sessions that require that route to function.

===List Asset Versions===
Lists all versions/revisions of the selected asset. For example if an asset has had an update released on the Download Station, this list will show the available update.

===List Assets in New Window===
If you have selected several assets from a larger list in Content Manager, this will list the selected asset in a new window.

===Add to Pick List===
Allows you to add the selected asset to either the Default Pick List, a custom Pick List, or to a New Pick List.

See [[Help/Content_Search_Filter#Pick_List|Pick Lists]] for further information on Pick Lists in Trainz.

===Edit Pick Lists===
Allows you to edit the Pick Lists in Trainz.

See [[Help/Content_Search_Filter#Pick_List|Pick Lists]] for further information on Pick Lists in Trainz.

==Content Filters==
The Content Filters system in Content Manager provides a very powerful system to search for content that is installed, or available from the Download Station.

===The Filters Tool===
To open the Filters tool, click on the grey 'arrow' icon to the right of 'Filter:'.

===Changing the Filter===
By default, the filter shown will be 'Installed = True'. To change this, click on the left hand drop down box and select the filter you would like.

To change the setting or option for the filter, either enter the desired text into the right hand box, or select the desired option from the right hand drop down box. Different filters will use either a text input, or a drop down box, depending on the type of filter.

===Adding a New Filter===
To add a new filter, click on the '+' button at the right hand end of the filters list.

===Removing a Filter===
To remove a filter from the filters list, click on the '-' button at the right hand end of the filters list.

===Predefined Filters===
Content Manager includes several Predefined Filters. To select one, click on the drop down box to the right of "Filters:" and then click on the filter you would like.

===Saving a new Predefined Filter===
If you have create a custom set of filters that you would like to set as a Predefined Filter, click on the Save button to the right of the Predefined Filters drop down box. You will then need to name, then save, the Predefined Filer.

==The Search Box==
At the right hand side of the Content Manager screen is the Search box. This allows you to enter a Keyword search into Content Manager to search/filter the current Asset List.

==The Asset List==
The Asset list is the main portion of the Content Manager screen, and the content that meets the current filter set.

==Asset List Columns==
The Asset List is separated into several columns which show details for each asset. By clicking on the header of each column, you can sort the order of the column (ie by clicking on the 'Upload Date' column, you can sort the assets by the date they were uploaded).

To add columns, right click on any of the column headers, then go to "Insert Column", then click on the column you wish to insert.

To remove columns, right click on the header of the column you wish to remove, then click on 'Remove Column'.

You can adjust the width of each column by clicking on the dividing line between column headers, and then dragging to the width you require.

You can move columns by clicking and dragging the column header.

Return To: [[Help:Content_Manager|Content Manager Help]]

[[Category:Help|Content Manager]]

Help:VE39

2025-09-18T03:27:20Z

Pcas1986: Update for TRS22 SP6 - assuming that the changes required are still relevant

"'''The texture ''texture-filename'' is a uniform color.'''"

or

"'''The texture ''texture-filename'' is unnecessarily large given it is a uniform color.'''"

These messages indicates that the entirety of the specified texture file is the same color. The second error message was introduced with TRS22 SP6.

This is an error for content at [[trainz-build]] 3.6 and up, which is larger than 64 texels in area (eg. 8x8 texels.) This condition is an error because the asset in question is wasting disk space, loading performance, video memory, and runtime performance for no benefit.

Smaller textures generate a warning, since it is frequently pointless to use a texture which contains no detail.

The error is suppressed on older (3.5 and below) content to avoid breaking older content which did not show this error when it was created. The issue is still a performance problem for older content, and should be fixed when feasible.

The most obvious fix for the error is to reduce the texture to an 8x8 square. Since the texture contains no distinguishing features, this will not affect the visual result.

To get rid of the warning entirely, you may wish to consider avoiding a uniform texture. Depending on your specific usage, a variety of alternative techniques exist, including:
* If the texture is a diffuse, consider using a [[Material_Types#m.notex|m.notex]] material.
* If the texture is a normal, consider switching to a material which does not require a normal map.
* If the texture is used only for a small part of the asset, consider combining the texture into one of the other textures used in the asset.
* If the texture is used for a large part or all of the asset, consider whether you can provide a more meaningful texture. Uniform-color textures typically produce an unrealistic visual result for most uses.

While it is possible to avoid this error by simply introducing a minor variation into the texture, it is strongly recommended that you avoid this approach: you are simply hiding the issue from validation rather than fixing it. The performance issues will remain.

[[Category:Validation Errors]]

TrainzScript Message Reference

2025-06-28T04:31:42Z

Pcas1986: Added warning about using SendMessage() within a message handler (static thread).

==What are Messages and how can they be used?==

Messages:
* Are internal communications between objects within Trainz.
* Are completely hidden from the normal user, who won't be aware of their existence.
* Provide notification of events within the Trainz script environment.
* Provide a means of opening direct communications between objects.
* Provide a means of sending instructions from one script to another.
* Provide a means of timing scripted actions.

Messages are managed by the ''Router'', a sort of internal post office, and can be exchanged between any objects which descend from ''[[GameObject]]'', this includes driver commands, rules and libraries as well as almost all mesh based scriptable objects.

Scripts can:
* Listen for messages and use them to take appropriate actions in response to events and instructions.
* Use the message to extract information about the object sending or receiving the message.
* Define and issue their own messages.
* Listen in to messages intended for other objects.
* Send messages to themselves, to arrive after a specified delay, as a 'reminder' to do something at a future time.

Messages are small data objects containing five pieces of information:
* ''msg.major'': A string identifying the message type.
* ''msg.minor'': A string containing the message subtype or additional information.
* ''msg.src'': A reference to the object that sent the message.
* ''msg.dst'': The intended recipient. May be null if the message was ''broadcast'' (legacy behavior, no longer supported).
* ''msg.paramSoup'': A Soup object containing extra data about the message (may be null).

==How to listen for Messages==

There are three techniques you can use:

* ''[[GameObject#AddHandler|AddHandler()]]'' This is the simplest listening device and is most useful when you know that you will always be interested in this type of message. ''[[GameObject#AddHandler|AddHandler()]]'' is usually set up in the ''Init()'' method of a script. Hint: omit any optional spaces in statements that include an AddHandler function, as including them causes the function to be ignored without notification in TRS2004 and perhaps other versions as well.
* A ''[[TrainzScript Keywords#wait|wait()]]'' loop. This needs to run in a separate thread and allows for a temporary arrangement where you want to know about messages for a shorter period or under a specified set of conditions.
* ''[[GameObject#Sniff|Sniff()]]''. This allows you to 'eavesdrop' on messages being sent to another object.

==When and how to send Messages==

You might consider issuing messages of your own under the following circumstances:

* When an event has taken place in your script and other objects might need to know about it.
* When you want to make your object available to other scripts to allow them to call your methods directly.
* When you need to issue instructions to another object to carry out a particular task and you know that the target object will be able to understand your message.
* When you want your own script to take an action at some time in the future, or at regular intervals.

There are three routines you can use to issue messages:

* [[GameObject#SendMessage|SendMessage()]] dispatches the message immediately. Do not use SendMessage() within a message handler and use PostMessage() instead. A message handler is a static thread and using SendMessage() within a static thread will raise an exception.
* [[GameObject#PostMessage|PostMessage()]] dispatches the message via the Router with a specified delay (which can be zero). The message will be executed on the next Router update after the delay has elapsed.
* [[Class Router#PostMessage|Router.PostMessage()]] allows messages to be dispatched even if the object you are scripting doesn't have its own messaging capabilities.

If the message destination is entered as ''me'' (meaning the current object) the message will be sent to the object which owns the script. If the destination is ''null'' the message will be ''broadcast'' and therefore available to any object in the session. Message broadcasting is obsolete as of TRS19 however, and may result in script exceptions or silent failures (depending on the local players compatibility setting).

If you have a reference to the message target (or if you know its name or id) you should consider the following:

* If you know which methods to use it might be more appropriate to call the other script directly.
* You should always avoid broadcasting messages if it is possible to send them directly to the intended recipient.

==Never Assume Anything==

The messaging system contains many traps for the unwary. If you are working with a junction for instance you will receive an ''Object,Enter'' message whenever a train enters your object's trigger zone. It is not safe however to assume that a subsequent ''Object,Leave'' means that the train has crossed the junction and left on the other side. Any of the following would also produce ''Object,Leave'':
* The train might have stopped and reversed away from your object.
* An intervening junction might have been toggled so that the train is no longer visible to your object.
* The train might have coupled to another (and therefore ceased to exist) before reaching your object.
It is usually necessary to treat a message as an indication that the event you are interested in could have happened and to use other tests to confirm.

==Example==

Listening for messages and using message handler methods

include "MapObject.gs"

<font color=#808080>// script can be attached to any scenery object
// enable the message window to view the output in Driver mode</font>
class Messenger isclass MapObject {

public void Init(void) {
inherited();
<font color=#808080>// listen for Junction and World,ModuleInit messages</font>
AddHandler(me,"Junction","","ToggleHandler");
AddHandler(me,"World","ModuleInit","ModuleInitHandler");
}

thread void TriggerMonitor(void) {
<font color=#808080>// Trigger messages will be passed to us as a result of the
// Sniff() call in ModuleInitHandler</font>
Message msg;
wait() {
<font color=#808080>// listen for Trigger,Enter, print a message when heard, continue listening</font>
on "Trigger","Enter",msg: {
Interface.Print("A train has entered a trigger");
continue;
}
<font color=#808080>// listen for Trigger,Stopped, print a message when heard and then quit the thread</font>
on "Trigger","Stopped",msg: {
Interface.Print("A train has stopped on a trigger");
Interface.Print("Trigger monitoring discontinued");
break;
}
}
}

void ToggleHandler(Message msg) {
<font color=#808080>// print a message whenever Junction,Toggled is broadcast</font>
Interface.Print("A junction has been toggled");
}

void ModuleInitHandler(Message msg) {
if (World.GetCurrentModule() == World.DRIVER_MODULE) {
<font color=#808080>// attach a handler to the first train on the map instructing it
// to copy any Trigger messages to us</font>
Sniff(World.GetTrainList()[0],"Trigger","",true);
<font color=#808080>// start monitoring Trigger messages</font>
TriggerMonitor();
}
}

};

==See Also==
* [[List of Standard Messages]]
* [[Animation-Event Message]]
* [[Browser Messages]]
* [[Camera Messages]]
* [[Interface Messages]]
* [[MapObject Messages]]
* [[ModuleInit Message]]
* [[Object Messages]]
* [[pfx Message]]
* [[Signal Messages]]
* [[Train Messages]]
* [[Vehicle Messages]]
* [[GameObject]]

Help:VE181

2025-01-19T02:18:46Z

Pcas1986: First version. Feel free to add to, update, or clarify.

This config tag needs at least the [["Trainz-build"_tag|Trainz-Build]] tag identified in the error message.

For example:

- <kuid2:nnnnnn:nnn:n> : VE181: The tag 'mesh-table-lod-transition-distances' requires a minimum asset version of 4.6

Help:VE275

2025-01-19T02:12:52Z

Pcas1986: First version. Feel free to add to, update, or clarify.

There are an excessive number of [[Render_chunk|chunks]] in this mesh. This may cause poor performance and should be avoided. This is an issue the asset author should address.

Excessive chunks can be avoided by:
* Reducing the number of polygons for the mesh.
* Making use of [[Normal_map|normal]] maps to reduce mesh detail.
* Reducing the number of unique materials for the mesh.
* Combining textures used for logos, and other decals used on the model.

Name Effect

2024-06-17T05:06:53Z

Pcas1986: Some clarification of usage

The Name effect kind is a [["mesh-table" Container]] effect container. The following tags are supported:

kind "name"
name ""
att ""
value "(same as name)"
font "swiss"
fontsize 12
fontcolor 0,0,0

===Explanations and default values===

Kind 'name' effect is used to place a user-defined text string on a mesh.

kind: The kind of this effects container.
:Type: Text
:Compulsory. "name"

name: A name for this effects container. Used by a script to set the value of the effect. i.e. the text displayed at the attachment point.
:Type: Text
:Optional. Default "parent".

att: The attachment point used for placing this effect. i.e. something like "a.name0".
:Type: Text
:Compulsory.

value: The text to be used for this effect.
:Type: Text
:Optional: Default (same as name)

font: The font to be used for this name.
:List item. {"arial", "console", "comic_sans", "courier", "cordia", "century_gothic", "garamond", "helvetica", "impact", "sans_serif", "swiss", "tahoma", "times_new_roman", "verdana"}
:Optional. Default "swiss".

fontsize: The font size to be used for this effect.
:Type Float
:Optional. Default 12.

fontcolor: The color to be used for this effect.
:Type: RGB triplet
:Optional. Default 0,0,0

[[Category:Config Container]]

HowTo/WagonX - Browser Properties Examples and Basic Tutorials

2024-03-05T01:00:15Z

Pcas1986: Added an example of a multiple mesh toggle with a child property.

<span style="color: red; font-weight: 700; font-size: 15px;">Please note: Much of this page still needs some validation. If you find issues then please contact PCAS1986 in the Trainz Forums or in the Trainz Discord Server.</span>

= Document Structure =
<table width=1200>
The WagonX Tutorial set is written over several pages. This page contains some example WagonX config containers and basic guidance for setting up those containers. Other pages in the series are listed below:
</table>
# [[HowTo/Use the WagonX Library]]<br>
# [[HowTo/WagonX - Technical Reference]]<br>
# [[HowTo/WagonX - Locomotive Tutorial]]<br>
# [[HowTo/WagonX - Traincar Tutorial]]<br>
# [https://docs.google.com/document/d/1jd5nZNQJI_gKQp-X2GjNCBij9fZGAwgJy_BgBiXf3_8/edit#bookmark=id.kupvwsc34hnk| The asset author's documentation]

= General Comments =
Most of the notes and examples here are for Version 1 but WagonX continues to be developed. Features and/or changes for versions later than V1 are identified in the text.

__TOC__

=Browser property tutorials=

This tutorial takes you each step of creating a simple mesh toggle example. It is for a handbrake mesh, including animation, that the user may want to show (make visible) or hide (make invisible). We will add each property tag and explain its purpose.
It may be useful to have the [[HowTo/WagonX - Technical Reference|WagonX Technical Reference]] page open in a browser to examine details of the various tags.
<table width=1200><tr><td>
==Creating a basic mesh toggle==
*Start with an empty browser-properties container like this:

browser-properties
{
}

*Add an empty property container and name it "0". The names are not used but should be unique. When we add more properties, you should name them “1”, “2”, “3”, etc.

browser-properties
{
0
{
}
}

*There is no order required for each property, but using a standard order makes it easier to follow. Each tag is hyperlinked to the browser-property, so you can see more information about it.
The first tag to add is [[HowTo/WagonX - Technical Reference#enabled|enabled]]. This determines whether or not the property is activated. Set it to 1, since we want our property to work in-game.

browser-properties
{
0
{
enabled 1
}
}

*Set the visibility of the property using [[HowTo/WagonX - Technical Reference#property-visibility|property-visibility]] and make that 1. Note this value is an integer and doesn't require quotes around it. A value of 1 makes the property visible in both Surveyor and Driver. See the reference for other available values.

browser-properties
{
0
{
enabled 1
property-visibility 1
}
}

*Set the [[HowTo/WagonX - Technical Reference#name|name]] of our property. The name will appear before the [[HowTo/WagonX - Technical Reference#display-values|display-values]], which we will get to in a moment. You also will want to add a space at the end; otherwise, the property name and display-value will appear as one word.
browser-properties
{
0
{
enabled 1
property-visibility 1
name "Toggle Mesh: "
}
}

*Set the [[HowTo/WagonX - Technical Reference#property-id|property-id]], which can be anything as long as it is unique and doesn't contain [[HowTo/WagonX - Technical Reference#Restricted_Characters|restricted characters]]. Trainz will use this to identify this property.
browser-properties
{
0
{
enabled 1
property-visibility 1
name "Toggle Mesh: "
property-id "p_meshToggle"
}
}

*Set the [[HowTo/WagonX - Technical Reference#description|description]]. This will appear as the tool-tip when you hover over a browser-property.
browser-properties
{
0
{
enabled 1
property-visibility 1
name "Toggle Mesh: "
property-id "p_meshToggle"
description "Toggles the mesh"
}
}

*Set the property [[HowTo/WagonX - Technical Reference#kind|kind]]. Since we want a mesh-attachment kind, we must also specify the [[HowTo/WagonX - Technical Reference#mesh-attachment-type|mesh-attachment-type]] which for this application is mesh-toggle.
browser-properties
{
0
{
enabled 1
property-visibility 1
name "Toggle Mesh: "
property-id "p_meshToggle"
description "Toggles the mesh"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
}
}

*Now add a [[HowTo/WagonX - Technical Reference#meshes|meshes]] tag to specify what mesh we want to toggle. The mesh name must exist in the config mesh-table. We will use the script author's prestwins handbrake lever for this demo.

Here is part of the config mesh-table:
handbrake-lever
{
mesh "mesh/handbrake.lm"
anim "mesh/handbrake_scene.kin"
auto-create 1
att-parent "default"
}

browser-properties
{
0
{
enabled 1
property-visibility 1
name "Toggle Mesh: "
property-id "p_handbrakeMeshToggle"
description "Toggles the handbrake mesh"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "handbrake-lever"
}
}

*Add the [[HowTo/WagonX - Technical Reference#values|values]] tag. This determines what the state of the object will be at each index. The values tag varies depending on the kind and, since this is a toggle, we want a true (1) or false (0) value. For kind mesh-toggle, we set it at 0 to hide the mesh, and 1 to show the mesh. Each index is comma separated, so we will set the first one at 1, and the second one at 0.
browser-properties
{
0
{
enabled 1
property-visibility 1
name "Toggle Mesh: "
property-id "p_handbrakeMeshToggle"
description "Toggles the handbrake mesh"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "handbrake-lever"
values "1,0"
}
}

*Add the [[HowTo/WagonX - Technical Reference#default-index|default-index]]. This is an integer value starting from 0 and which indicates the position in a list. 0 is the first in the list, 1 is the second, and so on. <i>(The reasons for this are somewhat historical but also based on how computers find things in memory.)</i> If we set it to 1, it will start at the second comma-separated values tag which is "0". If we set it at -1, it will pick a random index within the size of the values tag.
browser-properties
{
0
{
enabled 1
property-visibility 1
name "Toggle Mesh: "
property-id "p_handbrakeMeshToggle"
description "Toggles the handbrake mesh"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "handbrake-lever"
values "1,0"
default-index 0
}
}

*Add the [[HowTo/WagonX - Technical Reference#trigger|trigger]] tag. We want our property to activate when a user presses a button on the properties page, so we will set it to <b>user</b>. If we set it to <b>event</b>, however, we could make it activate based on an event within the train or in the world, such as handbrake apply, or enabling it when it gets dark, and disabling it when its daytime again, but for now, we will leave it at user.
browser-properties
{
0
{
enabled 1
property-visibility 1
name "Toggle Mesh: "
property-id "p_handbrakeMeshToggle"
description "Toggles the handbrake mesh"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "handbrake-lever"
values "1,0"
default-index 0
trigger "user"
}
}

*Specify the [[HowTo/WagonX - Technical Reference#display-type|display-type]]. Looking at the options, we see that <b>link</b> is what we want.
browser-properties
{
0
{
enabled 1
property-visibility 1
name "Toggle Mesh: "
property-id "p_handbrakeMeshToggle"
description "Toggles the handbrake mesh"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "handbrake-lever"
values "1,0"
default-index 0
trigger "user"
display-type "link"
}
}

*Finally, the last tag we need is the display-values tag, which we talked about earlier. Since we have two states for our property (specified in the values tag), we will create two comma-separated values for each state. We will call the first “Enabled”, and the second “Hidden”, which corresponds with the numbers we set in the values tag.
browser-properties
{
0
{
enabled 1
property-visibility 1
name "Toggle Mesh: "
property-id "p_handbrakeMeshToggle"
description "Toggles the handbrake mesh"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "handbrake-lever"
values "1,0"
default-index 0
trigger "user"
display-type "link"
display-values "Enabled,Hidden"
}
}

And that's it! Run the asset into trainz, and when you view the properties, you should see your property appear:<br>


[[File:Toggle_handbrake_mesh_in_View_Details.jpg]]

And when you click on the underlined part of your property, the property should change to “Hidden”, as we specified, and the handbrake on the underframe should disappear.<br>
[[File:Handbrake_mesh_show_%26_hide.jpg]]

</td></tr></table>

= Browser-Property Examples =
== User-Triggered Properties ==
Here are a number of examples for user triggering - i.e. in the View Details property browser. Detailed information on the property browser tags can be found on the [[HowTo/WagonX - Reference|WagonX Reference]] page.

<table width=1200><tr><td>
===Mesh-toggle property===
This property allows you to show or hide a mesh that is in the config mesh-table. The values are 0 and 1 to represent false and true. The default is 0 or hidden when first placed.

{
enabled 1
property-visibility 1
name "Toggle: "
property-id "p_toggle"
description "Hide or display the roof mesh"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "roof"
values "0,1"
duration 3
default-index 0
trigger "user"
display-type "link"
display-values "Hidden,Visible"
}
</td></tr></table>


<table width=1200><tr><td>
===texture-replacement property===
This allows the choice of a texture from either local texture files (i.e. contained within the asset), or from a texture group asset, to retexture or reskin a mesh. You could use it for swapping between clean, dirty or weathered textures, logos and also entire liveries.
</td></tr></table>
<br>


<table width=1200><tr><td>
====Texture replacement using local texture files====

For fx-replacement-type texture-replacement-texture, the comma and/or semicolon-separated values are the names of the files (ideally without the path or extension) to be referenced at that index. The values tag will contain a list of texture(.txt) files including a folder name if used. This is an example of three textures.

values "images/congleton.texture,images/burntisland.texture,images/buxton.texture,images/none.texture"

If you have the same path (and same extension) for all your files, you can greatly reduce the clutter by just specifying the path and extension once using the files-path tag. See the files-path and values usage below. Note that the display-values tag contains similar information but that is for the user to see.

0
{
enabled 1
property-visibility 1
name "Workflow Text: "
property-id "p_workflow"
description "Sets the Workflow"
kind "fx-replacement"
fx-replacement-type "texture-replacement-texture"
consist-property-sync 1
meshes "null"
effects "texture-extra"
asset "null"
files-path "images/,.texture"
values "congleton,burntisland,buxton,none"
default-index 0
trigger "user"
display-type "list"
display-values "Congleton,Burntisland,Buxton,None"
}
</td></tr></table>


<table width=1200><tr><td>
====Texture replacement using a texture-group library asset====
You will need to specify the texture group asset in the kuid-table and give it a name such as "texturelib" or "gwrtexturelib", The name should not have any spaces or other special characters.
This property container is set up to allow for three different variations of the the material used for the asset. They are named in the "display-values" tag as Skin 1, Skin 2, and Skin 3.
Since it is a PBR material there are three textures used in the materail: the albedo, parameters, and normal. The normal texture is common to all three versions so it need not be changed.
The "values" tag contains six numbers which are the numbers of the textures in the texture-group asset. For Skin 1 the "12" refers to the albedo texture, and the "15" refers to the parameter texture. "13" and "16" are the pair for Skin2, and "14" and "17" are the pair for Skin 3.
The "effects" tag contains the texture effect names for meshes in the mesh-table.
<br>

{
enabled 1
property-visibility 1
name "Weathering: "
property-id "p_skin"
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 "12;15,13;16,14;17"
default-index -1
trigger "user"
display-type "link"
display-values "Skin 1,Skin 2,Skin 3"
}
</td></tr></table>

== User-Triggered Properties with Child Properties ==
In some situations it isn't possible to make changes with just one property. WagonX can achieve multiple related changes using a child property. A parent can have one or more children but a child cannot have another child property.
The parent child relationship works by the parent passing the choice made by either the user or an event to the child. So, if a user has chosen option 2 in the parent then the value 2 is passed to the child.

Here are a number of examples:

<table width=1200><tr><td>
===Mesh-toggle property with child property===

In this instance a car has the option of three different bogies: two "4 wheel" bogies and a "6 wheel bogie". For this to work all the relevant bogie meshes must be contained in the one bogie asset.
This is the parent property:

7 {
enabled 1
property-visibility 1
name "Bogie type: "
description "Swap between Gresley, Wolverton and Pullman bogies"
property-id "p_bogey0"
child-properties "8"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
target-asset "bogey-1"
meshes "frame-0,axle0-0,axle0-1,axle0-1,frame-1,axle1-0,axle1-1,axle1-1,frame-2,axle2-0,axle2-1,axle2-2"
values "1;1;1;1;0;0;0;0;0;0;0;0, 0;0;0;0;1;1;1;1;0;0;0;0, 0;0;0;0;0;0;0;0;1;1;1;1"
default-index 0
duration 0
trigger "user"
display-type "link"
display-values "Gresley 4 wheel,Wolverton 4 wheel,Pullman 6 wheel"
}

The three choices are in the "display-values" tag.<br>
The "target-asset" tag contains an identification of the bogey concerned. This name is a special format that should consist of "bogey-" plus the index of the bogey sub containeer in the traincar bogey container. In this case this is bogey number 1.<br>
The "meshes" tag contains a list, separated by commas, of the affected meshes. The first four are related to the first choice, the second four for the second choice, and the final four are for the last choice.<br>
The "values" tag contains three sets of boolean (false/true) values that indicate whether the related meshes in the meshes tag should be shown (1) or hidden (0). For each set we need a boolean value for each mesh.<br>
The "child-properties" tag identifies the child properties by using their property id. In this case we only need one which is property 8.

This is the child property. It is virtually the same as the parent except for the target-asset, that identifies the second bogie, the trigger that uses the "parent" option, and the removal of several tags that are not needed for a child property.

8 {
enabled 1
property-visibility 0
property-id "p_bogey1"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
target-asset "bogey-0"
meshes "frame-0,axle0-0,axle0-1,axle0-1,frame-1,axle1-0,axle1-1,axle1-1,frame-2,axle2-0,axle2-1,axle2-2"
values "1;1;1;1;0;0;0;0;0;0;0;0, 0;0;0;0;1;1;1;1;0;0;0;0, 0;0;0;0;0;0;0;0;1;1;1;1"
default-index 0
duration 0
trigger "parent"
}


[[File:Swap_Bogies_in_View_Details.jpg]]
</td></tr></table>

== Event-Triggered Properties ==

<table width=1200><tr><td>
===loading-doorsProperty ===
The ‘meshes’ tag references a mesh-table asset named ‘loading-doors’, and sets the frame to 30 when begin-load is called (to open the doors), and 0 when end-load is called (to close the door). The default index is 0 (the animation frame will be at 0), and the animation duration is 1.5 seconds.
{
enabled 0
property-visibility 0
property-id "p_doors"
kind "mesh-attachment"
mesh-attachment-type "mesh-animation-frame"
meshes "loading-doors"
values "0,30"
trigger "event"
events "end-load,begin-load"
duration 1.5
default-index 0
}

An alternate way to do it is use mesh-attachment-type "mesh-animation-state", and set a bool int (0 or 1) for the values tag.
{
enabled 0
property-visibility 0
property-id "p_doors"
kind "mesh-attachment"
mesh-attachment-type "mesh-animation-state"
meshes "loading-doors"
values "0,1"
trigger "event"
events "end-load,begin-load"
default-index 0
}

If you want two doors to open at the same time, instead of creating another property, you can use a semicolon split in the values tag to change two in a single property:
{
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 "door-1,door-2"
values "0;0,30;30"
events "handbrake-release,handbrake-apply"
duration 3.0
default-index 0
trigger "both"
display-type "link"
display-values "release,apply"
}
</td></tr></table>


<table width=1200><tr><td>
===Weather-Based Texture Replacement===
The texture effect will change based on the weather. It will display a snowy texture when the weather type is 6 (medium snow), a wet, rainy texture when the weather type is 3 (rain), and a dry texture when the weather type is 0.
{
enabled 1
property-visibility 0
property-id "p_weather_skin"
kind "fx-replacement"
fx-replacement-type "texture-replacement-texture"
effects "texture-weather"
files-path "images/,.texture"
values "texture-snow,texture-rain,texture-dry"
default-index 0
trigger "event"
events "weather-6,weather-3,weather-0"
}
</td></tr></table>


<table width=1200><tr><td>
===Day and Night Light Control===
WagonX Version 1.2 or greater only.<br>
This event property controls a set of eight exteruir lights on a traincar that must turn on for night and off for day. It also requires a locomotive at the head of its train for the lights to come on.
<br>
The property is a kind fx-replacement of type corona. Turning a corona on and off requires a valid corona to be turned on and usually a null value to turn it off. In this case, instead of a null, we will use an invisible mesh, <kuid:217537:100812>, to achieve the same result. We do this because WagonX needs to obtain an asset from the asset kuid-table.<br>
There are two events to consider: the "World, Day" message represented as "world-day", and the "World, Night" message represented as "world-night".
The requirement for a loco requires a conditions tag using the logic described at (insert link when tech ref updated). The results are boolean (false or true) and the first will be true if no loco exists at the head of the train, and the second if there is a loco. So the possible results are "1;0" (no loco) or "1;0" (loco exists) using the WagonX syntax.<br>
The effects tag contains a list of the corona effects from the asset mesh-table. Each is separated by a comma.<br>
The values tag contains two sets of kuid-table mesh references. Each set is separated by a comma, and the list within each set separated by a semi-colon. The first set turns off the eight coronas when the loco doesn't exist, and the second set turns the coronas on using the same corona asset for each light. You could have different coronas.
{
enabled 1
property-visibility 0
property-id "p_exterior_lights"
kind "fx-replacement"
fx-replacement-type "corona"
duration 0
effects "leftlight-0,leftlight-1,leftlight-2,leftlight-3,rightlight-0,rightlight-1,rightlight-2,rightlight-3"
values "nl;nl;nl;nl;nl;nl;nl;nl,exla;exla;exla;exla;exla;exla;exla;exla"
trigger "multiple"
conditions "tra_frontmost-locomotive|==|0,tra_frontmost-locomotive|==|1"
events "world-day,world-night
}
...
kuid-table {
...
exla <kuid:104722:100> // a white corona
nl <kuid:217537:100812> // an invisible mesh
}
</td></tr></table>

<table width=1200><tr><td>
===Day and Night Interior Control===
WagonX Version 1.2 or greater only.<br>
This example controls the visibility of day and night traincar interiors using the "World, Day/Night" messages. The night interior will not show unless a locomotive is at the head of the traincar's train.<br>
{
enabled 1
property-visibility 0
property-id "p_interior_lighting"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "day-interior,night-interior"
values "1;0,0;1"
default-index 0
duration 0
trigger "multiple"
conditions "tra_frontmost-locomotive|==|0,tra_frontmost-locomotive|==|1"
events "world-day,world-night"
}
</td></tr></table>


<table width=1200><tr><td>
== Using semicolons to set multiple values in one property ==
When assigning values for a certain property, you will specify the mesh/effect/sound, etc that needs to be edited, and specify how you want to manipulate it (fx-replacement-type, mesh-attachment-type, etc), and set the value for a certain index. For example, In a texture replacement where a texture is being replaced by an external texture-group asset, the property would look something like this.

0
{
enabled 1
property-visibility 1
name "Skin: "
property-id "p_skin_parameter"
description "Sets The Texture"
kind "fx-replacement"
fx-replacement-type "texture-replacement"
effects "texture-albedo"
asset "texturelib"
values "1,2,3,4"
default-index -1
trigger "user"
display-type "link"
display-values "Skin1,Skin2,Skin3,Skin"
}

As you can see, the comma-separated numbers in the “values” tag indicate the index in the texture-group asset to find the texture; here are the first few lines for that. Texture indexes 0, 1, 2, and 3 are referenced for the albedo texture types, since we have 4 weathering types.

kuid <kuid2:661805:500009:0>
username "BR GrainHop Texture Group"
kind "texture-group"
trainz-build 5.0
category-class "JO"
author "dundun92"
contact-email "jbvector93@outlook.com"
description "A texture group for my GrainHop wagons"
textures
{
0 "270cgo/0albedo.texture"
1 "270cgo/1albedo.texture"
2 "270cgo/2albedo.texture"
3 "270cgo/2albedo.texture"
4 "270cgo/0parameter.texture"
5 "270cgo/1parameter.texture"
6 "270cgo/2parameter.texture"
.........
}

We specified the texture-group library in the kuid table, and referenced it in the “asset” tag.
kuid-table
{
acslib <kuid2:60850:89100>
meshlib <kuid2:661805:500002>
texturelib <kuid2:661805:500009>
lamp <kuid2:661805:500003>
enginespec <kuid2:368699:50064>
bogie <kuid2:661805:400003>
}

And then we specified the effect we wanted to change, (currently just the texture-albedo), inside the “effects” tag (this is not the effects tag below in this mesh table asset, but rather the one in the browser-properties at the top of this section!).
body
{
mesh "mesh/body.lm"
auto-create 1
att-parent "default"
effects
{
texture-albedo
{
kind "texture-replacement"
texture "covhopp-1_albedo.texture"
}
texture-normal
{
kind "texture-replacement"
texture "covhopp-1_normal.texture"
}
texture-parameter
{
kind "texture-replacement"
texture "covhopp-1_parameter.texture"
}
}
}

But say you want to replace the normal map as well. You would probably just create another browser property and specify the proper index for the normals.

0
{
enabled 1
property-visibility 1
name "Skin: "
property-id "p_skin_parameter"
description "Sets The Paramenter Texture"
kind "fx-replacement"
fx-replacement-type "texture-replacement"
effects "texture-albedo"
asset "texturelib"
values "1,2,3,4"
default-index -1
trigger "user"
display-type "link"
display-values "Skin1,Skin2,Skin3,Skin4"
}
1
{
enabled 1
property-visibility 1
name "Skin: "
property-id "p_skin_normal"
description "Sets The Normal Texture"
kind "fx-replacement"
fx-replacement-type "texture-replacement"
effects "texture-normal"
asset "texturelib"
values "7,8,9,10"
default-index -1
trigger "user"
display-type "link"
display-values "Skin1,Skin2,Skin3,Skin4"
}

But we can't forget the parameter map… that will require a third property. What's worse, we will now have three different properties in the view details page that will each have to be clicked on to change each map! Assigning properties this way can get tedious and create extra clutter in the config. Thankfully, for properties that share the same kind and type, it can all be done in a single property using semicolons:

0
{
enabled 1
property-visibility 1
name "Skin: "
property-id "p_skin"
description "Sets the weathering type"
kind "fx-replacement"
fx-replacement-type "texture-replacement"
meshes "null"
<b>effects "texture-albedo,texture-parameter,texture-normal"</b>
asset "texturelib"
files-path "null"
<b>values "0;4;8,1;5;9,2;6;10,3;7;11"</b>
default-index -1
trigger "user"
display-type "link"
<b>display-values "Clean,Weathered,Dirty,Rusty"</b>
}

Take note of the three tag entries above: the <b>effects</b>, <b>values</b> and <b>display-values</b> tags. The <b>display-values</b> tag is what the user sees and can choose from. Our interest is in the remaining two tags as shown below:

effects "texture-albedo,texture-parameter,texture-normal"
values "0;4;8,1;5;9,2;6;9,3;7;11"

There are four user options and, since each option requires three textures, the total number of textures is 12. The <b>values</b> tag contains a string of four groups of texture numbers separated by a comma. Within each texture group the texture numbers are delimited by a semi colon.

To clarify, we can list the three textures associated with each user choice:

0;4;8 -> Clean
1;5;9 -> Weathered
2;6;10 -> Dirty
3;7;11 -> Rusty

The first column of 0,1,2,3 identify the albedo textures. The second column of 4,5,6,7 identify the parameters textures, The third column of 8,9,10,11 identify the normal textures. Note that the numbers do not need to be in sequence or even consecutive. All those numbers do is to identify the correct texture in the texture-group asset.

This system works for other kinds of properties, too. In this case, we are setting the animation frame of both the handbrake-lever, and braking system at the same time using the same property (triggered by the same event).

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"
}

</td></tr></table>


<table width=1200><tr><td>
== Naming ACS mesh-table attachments ==
Please refer to this page on the ACS coupling system for setting up the “active-coupling-standard-60850” extensions container (which will be required for the ACS coupling to work): [[ACS_Coupling_System|ACS Coupling System]]

These are the mesh-table naming conventions you must use for the beginning of the name of each ACS attachment mesh. The others will vary depending on the “animated” property above. <b>You must spell them exactly as shown below</b>.

*coupler
*gangway
*airbrake
*vacbrake
*multiworking
*heating
*rch

If the “animated” tag in the acs container (see [[HowTo/WagonX_-_Technical_Reference#ACS|acs]]) is set to 1, then the naming is quite simple. It's one of the 7 callbacks above + a dash + “<i>front</i>” or “<i>back</i>”. The anim tag must be present to specify the animation for it. Frame 0 is the uncoupled state, and the last frame is the coupled state. This setup is shown below:

coupler-front
{
mesh-asset <kuid2:661805:500002>
mesh "coupler-screwlink-animated.lm"
anim "coupler-screwlink-animated_scene.kin"
auto-create 1
att "a.couple0"
att-parent "default"
}
coupler-back
{
mesh-asset <kuid2:661805:500002>
mesh "coupler-screwlink-animated.lm"
anim "coupler-screwlink-animated_scene.kin"
auto-create 1
att "a.couple1"
att-parent "default"
}
vacbrake-front
{
mesh-asset <kuid2:661805:500002>
mesh "vacbrake-single-animated.lm"
anim "vacbrake-single-animated_scene.kin"
auto-create 1
att "a.couple0"
att-parent "default"
}
vacbrake-back
{
mesh-asset <kuid2:661805:500002>
mesh "vacbrake-single-animated.lm"
anim "vacbrake-single-animated_scene.kin"
auto-create 1
att "a.couple1"
att-parent "default"
}

If, however, you do not want to use animations, but want to use separate meshes for each state (coupled and uncoupled), it gets a bit more complicated. The naming will follow the same as above at first, but you must add a third piece to it to specify the exact type of ACS attachment this is. The information on what to put there is originally from the [[ACS_Coupling_SystemACS Coupling System|ACS page]], but the 7 callbacks have been added plus the sub-callback here to make it easier (the third callback options are the ones with a delta symbol Δ ). And for the uncoupled state, the third callback is “non” (e.g. coupler-front-screwlink, and coupler-front-none).

*coupler
:*front/back
::Δ "<b>hook</b>" -- connects to screwlink/instanter/3link/hst-emergency-bar.
::Δ "<b>3link</b>" -- connects to hook.
::Δ "<b>instanter</b>" -- connects to hook.
::Δ "<b>screwlink</b>" -- connects to hook.
::Δ "<b>hst-emergency-bar</b>" -- connects to hook.
::Δ "<b>bar-full</b>" -- connects to "bar-none". Half of a handed pair for when one vehicle has the entire bar coupling.
::Δ "<b>bar-none</b>" -- connected to by "bar-full". The other half of the handed pair.
::Δ "<b>bar</b>" -- connects to self only. Used when both vehicles have half the bar coupling.
::Δ "<b>knuckle</b>" - standard knuckle coupler.
::Δ "<b>tightlock</b>" -- different from a standard knuckle, refers to a knuckle style coupler often fitted to multiple unit trains that also include electrical connections.
::Δ "<b>wedgelock</b>" -- London Underground coupler.
::Δ "<b>bsi</b>" -- Found on Sprinter DMUs and derived designs.
::Δ "<b>dellner</b>" -- Also compatible with Scharfenberg coupling.
::Δ "<b>scharfenberg</b>" -- Also compatible with dellner coupling.
::Δ "(<b>other string identifier</b>)" -- Any string that is not recognized from the above list is assumed to be a symmetrical meet-in-the-middle type of coupler.
::Δ “<b>none</b>”
::Examples: <b>coupler-front-instanter</b>, coupler-back-none

*gangway
:*front/back
::Δ <b>rubbing-plate</b>
::Δ <b>gangway</b>
::Δ <b>none</b>
::Example: <b>gangway-front-gangway</b>

*airbrake
:*front/back
::Δ <b>twin</b>
::Δ <b>single</b>
::Δ <b>none</b>
::Example: <b>airbrake-back-none</b>

*vacbrake
:*front/back
::Δ <b>twin</b>
::Δ <b>single</b>
::Δ <b>high</b>
::Δ <b>none</b>
::Example: <b>vacbrake-back-twin</b>

*multiworking
::front/back
::Δ "(color)-(shape)" -- e.g. "<b>blue-star</b>" or "<b>red-diamond</b>", etc
::Δ "<b>AAR</b>" -- as used on GM locos
::Δ "<b>SR27</b>" -- bagpipes
::Δ "(other identifier string e.g. classname)"
::Example: <b>multiworking-front-blue-square</b>

*heating
::front/back
::Δ "<b>none</b>"
::Δ "<b>steam</b>"
::Δ "<b>electric</b>"
::Δ "<b>dual</b>"
::Δ "<b>southern-electric</b>"
::Example: <b>heating-back-steam</b>

*rch
::front/back
::Δ "<b>high</b>"
::Δ "<b>low</b>"
::Δ "<b>none</b>"
::Example: <b>rch-back-high</b>

And an example how it would look inside a config.txt. The back attachments have been omitted for brevity.

coupler-front-screwlink
{
mesh-asset <kuid2:661805:500002>
mesh "coupler-screwlink-coupled.lm"
auto-create 1
att "a.couple0"
att-parent "default"
}
coupler-front-none
{
mesh-asset <kuid2:661805:500002>
mesh "coupler-screwlink-retracted.lm"
auto-create 1
att "a.couple0"
att-parent "default"
}
vacbrake-front-single
{
mesh-asset <kuid2:661805:500002>
mesh "vacbrake-single-coupled.lm"
auto-create 1
att "a.couple0"
att-parent "default"
}
vacbrake-front-none
{
mesh-asset <kuid2:661805:500002>
mesh "vacbrake-single-retracted.lm"
auto-create 1
att "a.couple0"
att-parent "default"
}

<table width=1200>
=Copyright Notice=
Much of the content on this page and child pages was derived from Dundun92's original Google Docs document. Permission was granted to use that information here.
</table>

File:Swap Bogies in View Details.jpg

2024-03-05T00:54:58Z

Pcas1986: Used in WagonX documentation examples

Used in WagonX documentation examples

HowTo/WagonX - Technical Reference

2024-03-05T00:13:04Z

Pcas1986: /* trigger */

<table width=1200><tr><td>
= 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:

# [[HowTo/Use the WagonX Library|How to use the WagonX library]]<br>
# [[HowTo/WagonX - Browser Properties Examples and Basic Tutorials|WagonX Examples and Basic Tutorials]]<br>
# [[HowTo/WagonX - Traincar Tutorial|WagonX Traincar Tutorial]]<br>
# [[HowTo/WagonX - Locomotive Tutorial|WagonX Locomotive Tutorial]]<br>
</tr></td></table>

__TOC__

<table width=1200><tr><td>
= 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.
</td></tr></table>

<table width=1200><tr valign="top"><td>
= 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|display-values]].

*Comma ( , )
*Semicolon ( ; )
*Backtick/Grave ( ` )
*Colon ( : )
*Caret ( ^ )
*Round brackets ( and )
</td></tr></table>

<table width=1200><tr valign="top"><td>
== 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).<br>
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.
<br>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|values]] tag.
<br>See also [[WagonX_-_Browser_Properties_Examples_and_Basic_Tutorials#Using_semicolons_to_set_multiple_values_in_one_property|Using semicolons to set multiple values in one property]].
</td></tr></table>

<table width=1200><tr valign="top"><td>
== 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.
</td></tr></table>

<table width=1200><tr valign="top"><td>
== Other special characters ==
Caret - The caret/circumflex symbol (^) is a math power operator. It can be used in variables.<br>
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|values]].<br>
Colon - See Round Brackets above.
</td></tr></table>

<table width=1200><tr valign="top"><td><tr>
= General Layout =

WagonX config tags are defined in the extensions container along with other extensions such as ACS Lib. The general layout of the extensions container that also includes ACS Lib might look like this:
extensions
{
max_permitted_speed-60850 "50mph"
active-coupling-standard-60850
{
...
}
wagon-x
{
...
}
}
</td></tr></table>

<table width=1200><tr valign="top"><td>
= 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.
</td></tr></table>


<table width=1200><tr><td>
== ACS ==
For help on creating the acs extensions and setting up the acs mesh-table objects, see [[HowTo/WagonX_-_Browser_Properties_Examples_and_Basic_Tutorials#Naming_ACS_mesh-table_attachments|Naming ACS mesh-table attachments]].
<br>
Each tag is shown here with sample values. There are no default values.

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

*<b>animated (1 = true, 0=false)</b>
:This determines whether to use animations to move between the coupled and uncoupled state, or use individual static assets for each state.
*<b>use-jbv-animation (1 = true, 0=false)</b>
: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.
*<b>duration (a floating point value)</b>
: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)
*<b>buffer-length-front float</b>
: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
*<b>buffer-length-back float</b>
: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
</td></tr></table>

<table width=1200><tr><td>
== text-x ==

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

*<b>controller string</b>
:Determines how the property will be controlled. Can be controlled by the user, the running number, or a custom range.
:::*user
:::*arn
:::*range
*<b>range string</b>
:Defines the range of values the for the text proprety. It will choose a random index to start<br>
*<b>value string</b>
: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”).<br>
*<b>font int</b>
:The default font index for the text property, these values can be changeed by adding a “config-edit” property to the browser-properties.
*<b>files-path string</b>
: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.<br>
*<b>textures string</b>
: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.<br>
*<b>effects string</b>
:The texture replacement effects to use for displaying the text.<br>

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"
}
}
}
</td></tr></table>


<table width=1200><tr><td>
== 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
}

*<b>mobile float</b> <b><i>(added in v1.2)</i></b>
: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.<br>
*<b>update-frequency float</b> <b><i>(added in v1.2)</i></b>
: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.
*<b>begin-load-time (a floating point value)</b>
:The time it takes for the wagon to load at an industry
*<b>begin-unload-time (a floating point value)</b>
:The time it takes for the wagon to unloading at an industry
*<b>end-load-time (a floating point value)</b>
:The time it takes for the wagon end loading at an industry
*<b>end-unload-time (a floating point value)</b>
:The time it takes for the wagon to end unloading at an industry
</td></tr></table>



<table width=1200><tr><td>
== 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"
}
}
}

*<b>enabled (1 = true, 0=false)</b>
:Whether or not the marker lights are active on this asset.
*<b>car-minimum-count (an integer number)</b>
:The minimum number of cars that must be present in the consist for the marker-lights to activate.
*<b>require-locomotive (1 = true, 0=false)</b>
:If set to 1, a traincar of Class locomotive will need to be present in the consist for the marker-lights to activate.
*<b>night-only (1 = true, 0=false)</b>
:If set to 1, the lamps will only be visible at night, otherwise they will be displayed 24/7.
*<b>Front/back head/tail containers</b>
:These containers identify the mesh to use for the front, back, head, and tail lamps. These meshes must be in the config mesh-table.
</td></tr></table>



<table width=1200><tr><td>
== 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"
}
}
</td></tr></table>


<table width=1200><tr><td>
===Supported Tags===
Tag explanations. Some examples are included in the definition and, for others, see above for sample of usage.
</td></tr></table>



<table width=1200><tr><td>
====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|effects]] tag, the [[#meshes|meshes]] tag, or the [[#particle-effects|particle-effects]] tag, but not more than one.

</td></tr></table>


<table width=1200><tr><td>
====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"
</td></tr></table>

<table width=1200><tr><td>
====conditions====
<b><i>(added in v1.2)</i></b>
: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|Class Vehicle]]. Please refer to that page for information on function behavior and usage.<br>
::::<b>example 1: veh_velocity|>=|5&veh_mass>1500 -></b> 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.
::::<b>example 2: veh_engine-param_main-reservoir-pressure|<|0.5 -></b> 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)


</td></tr></table>

<table width=1200><tr><td>
====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|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.
</td></tr></table>

<table width=1200><tr><td>

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

</td></tr></table>

<table width=1200><tr><td>
====description====
:Type: String
:Compulsory: No
:Default: None
:Desc: The description of this attachment as it will appear in the Properties Browser.
</td></tr></table>

<table width=1200><tr><td>

====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. <b>For trainzbuild 5.1 and 5.0, only link is supported for the View Details page.</b> 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

</td></tr></table>

<table width=1200><tr><td>

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

</td></tr></table>

<table width=1200><tr><td>

====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. <b>(There may be issues with using this tag with mesh-toggle.)</b>
:Example: duration 3.2

</td></tr></table>

<table width=1200><tr><td>

====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|kind]] fx-replacement. Use this tag, the mesh tag, or the asset tag, but not more than one.

</td></tr></table>

<table width=1200><tr><td>
====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.
</td></tr></table>

<table width=1200><tr><td>

====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 <b><i>(added in v1.2)</i></b>
:::*handbrake-apply/handbrake-release
:::*trainbrake-apply/trainbrake-release
:::*headlight-on, headlight-off
:::*throttle-changed <b><i>(added in v1.2)</i></b>
:::*front-coupled/back-coupled,front-uncoupled/back-uncoupled <b><i>(added in v1.2)</i></b>
:::*view-internal, view-external, view-tracking, view-roaming <b><i>(added in v1.2)</i></b>
:::*horn
:::*bell
:::*sanding
:::*pantograph-state-0/1/2/3 (see [[Class_Train#GetPantographState|<span style="color: #0080ff">GetPantographState</span>]])
:::*weather-0/1/2/3/4/5/6/7 (see [[Class_World#GetWeatherType|<span style="color: #0080ff">GetWeatherType</span>]])
:::*world-day/world-night
:::*priority-number-(0 - ∞) (e.g. priority-number-2) <b><i>(added in v1.2)</i></b>
:::*arn-(0 -∞ ) (e.g. arn-92220, arn-844) <b><i>(added in v1.2)</i></b>
:::*queue-(0 - ∞)- loaded/empty (e.g. <b>queue-0-loaded, queue-1-empty</b>)

</td></tr></table>

<table width=1200><tr><td>

====files-path====
:Type: String - (a list of two strings)
:Example: files-path "images/,.texture"
:Compulsory: No
:Default: None
:Desc: 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. <b>files-path “images/left/.texture”</b>), where images/left is the path, and .texture is the extension for all the files.

</td></tr></table>

<table width=1200><tr><td>

====fx-replacement-type====
:Type: String)(kind fx-replacement only)
:Example: kind "fx-replacement"
:::fx-replacement-type "texture-replacement"
:Compulsory: No
:Default: None
:Desc: The type of fx replacement effect this property will be if the [[#kind|kind]] tag is set to fx-replacement. Each one is hyperlinked to the corresponding trainzscript function, though it is not necessary to know them. See [[#values|values]] for instructions on how to implement these properties.
::*[[Class_MeshObject#SetFXTextureReplacement|<span style="color: #0080ff">texture-replacement</span>]]
:::Replaces a texture effect in this asset to one within a texture-group asset.
::*[[Class_MeshObject#SetFXTextureReplacementTexture|<span style="color: #0080ff">texture-replacement-texture</span>]]
:::Replaces a texture effect in this asset to one located within this asset.
::*[[Class_MeshObject#SetFXCoronaTexture|<span style="color: #0080ff">corona</span>]]
:::Replaces a corona effect in the asset.
::*[[Class_MeshObject#SetFXNameText|<span style="color: #0080ff">name</span>]]
:::Replaces a name effect in the asset.
::*[[Class_MeshObject#SetFXAttachment|<span style="color: #0080ff">attachment</span>]]
:::Replaces an attachment effect in the asset.
::*[[Class_MeshObject#SetFXAnimationState|<span style="color: #0080ff">animation</span>]]
:::Plays/Stops an animation effect in the asset.

</td></tr></table>

<table width=1200><tr><td>
====kind====
:Type: String
:Compulsory: No
:Default: None
:Desc: The type of property this will be. Can be one of the options below. Most of these are derived from [[Class MeshObject|Class_MeshObject]]. For more info on implementing these, see [[#values|values]].
::*mesh-attachment
:::Manipulate the mesh’s animation, position, visibility, etc. See mesh-attachment-type.
::*fx-replacement
:::Change an effect in the mesh. See [[#fx-replacement-type|fx-replacement-type]].
::*particle-effect
:::Activate/Deactivate/Edit a particle effect (smoke0, smoke1, etc). See [[#particle-effects|particle-effects]] and [[#particle-effect=type|particle-effect-type]].
::*sound-script
:::Used to play a sound-script sound within this asset. See [[#sound-triggers|sound-triggers]].
::*config-edit
:::Used to edit a tag in the wagon-x config soup. See paths.
</td></tr></table>

<table width=1200><tr><td>

====meshes====
:Type: String - (a list of mesh names from the mesh-table separated by commas)
:Example: meshes "handbrake-lever,braking-system"
:Compulsory: No
:Default: None
:Desc: The comma-separated mesh-table asset(s) to be modified by the property. Use this for [[#kind|kind]] mesh-toggle or kind mesh-animation. Use this tag, the effect tag, or the asset tag, but not more than one.

</td></tr></table>

<table width=1200><tr><td>

====mesh-attachment-type====
:Type: String - (kind mesh-attachment only)
:Example: kind "mesh-attachment"
:: mesh-attachment-type "mesh-animation-frame"
:Compulsory: No
:Default: None
:Desc: The type of mesh property this property will be if the kind tag is set to mesh-attachment. Each one is hyperlinked to the corresponding trainzscript function, though it is not necessary to know them. See values for instructions on how to implement these properties.
::*[[Class_MeshObject#SetMeshVisible|<span style="color: #0080ff">mesh-toggle</span>]]
:::Toggle between the mesh(s) being visible or hidden.
::*[[Class_MeshObject#SetMeshOrientation|<span style="color: #0080ff">mesh-translation-orientation</span>]]
:::Sets the translation and orientation of the mesh(es)
::*[[Class_MeshObject#SetMeshAnimationFrame|<span style="color: #0080ff">mesh-animation-frame</span>]]
:::Sets the frame(s) the meshes animation will move between. Useful for door opening and closing animations, or animations that require more than 2 states.
::*[[Class_MeshObject#StartMeshAnimationLoop|<span style="color: #0080ff">mesh-animation-loop</span>]]
:::Start or stop an animation-loop on the mesh.
::*[[Class_MeshObject#SetMeshAnimationState|<span style="color: #0080ff">mesh-animation-state</span>]]
:::Sets the state of the mesh(s) animation.
::*[[Class_MeshObject#SetMeshAnimationSpeed|<span style="color: #0080ff">mesh-animation-speed</span>]]
:::Changes the speed of the meshes animation.

</td></tr></table>

<table width=1200><tr><td>
====name====
:Type: String
:Compulsory: Yes
:Default: None
:Desc: The display name of this property, as will appear on the properties page.
</td></tr></table>


<table width=1200><tr><td>
====particle-effects====
:Type: String - (a list of integer numbers as a string)
:Example: particle-effects "0,1"
:Compulsory: No
:Default: None
:Desc: For kind particle-effect. The comma-separated list of PFX effects to be modified by the property. See kind for help on implementation. <b>There is currently no use for this tag as of yet. pfx-message doesn't need this because everything is already specified in the values tag.</b>

</td></tr></table>



<table width=1200><tr><td>
====particle-effect-type====
:Type: String (kind mesh-attachment only)
:Compulsory: No
:Default: None
:Desc: The type of PFX function this property will be if the [[#kind|kind]] tag is set to particle-effect.
Each one is hyperlinked to the corresponding trainzscript function, though it is not necessary to know them. See [[#values|values]] for instructions on how to implement these properties. Most of these are derived for the PFXEmitter properties specified in [[MapObject|Class MapObject]], with the prefix “GetPFXEmitter” omitted. All except [[MapObject#SetPFXEmitterTexture|SetPFXEmitterTexture]] are supported.
:Example: kind "particle-effect"
: particle-effect-type "pfx-message"
:Comments: Needs to be validated with examples!
::*[[pfx_Message|pfx-message]]
:::Send a message to enable/disable a particle effect.
::*[[Class_MapObject#SetPFXEmitterConeSize|cone-size <b><i>(added in v1.2)</i></b>]]
:::Update the cone size with x,y and z sizes in values tag.
::*[[Class_MapObject#SetPFXEmitterEmitParticles|emit-particles <b><i>(added in v1.2)</i></b>]]
:::Update the number of particles and time they will be created.
::*[[Class_MapObject#SetPFXEmitterEndColor|end-color <b><i>(added in v1.2)</i></b>]]
:::Update the end colour of the particles.
::*[[Class_MapObject#SetPFXEmitterStartColor|start-color <b><i>(added in v1.2)</i></b>]]
:::Update the start colour of the particles.
::*[[Class_MapObject#SetPFXEmitterLifetime|lifetime <b><i>(added in v1.2)</i></b>]]
:::Update the emitter lifetime using seconds.
::*[[Class_MapObject#SetPFXEmitterMaxRate|max-rate <b><i>(added in v1.2)</i></b>]]
:::Update the emitter maximum rate per second.
::*[[Class_MapObject#SetPFXEmitterMinRate|min-rate <b><i>(added in v1.2)</i></b><b><i>(added in v1.2)</i></b>]]
:::Update the emitter minimum rate per second.
::*[[Class_MapObject#SetPFXEmitterMaxSize|max-size <b><i>(added in v1.2)</i></b>]]
:::Update the maximum size size of particles. The size is a single float.
::*[[Class_MapObject#SetPFXEmitterMinSize|min-size <b><i>(added in v1.2)</i></b>]]
:::Update the minimum size of particles. The size is a single float.
::*[[Class_MapObject#SetPFXEmitterPhysicsDelay|physics-delay <b><i>(added in v1.2)</i></b>]]
:::Update the physics delay for the emitter. The delay value is in seconds.
::*[[Class_MapObject#SetPFXEmitterRate|rate <b><i>(added in v1.2)</i></b>]]
:::Set a new rate of particle creation per second.
::*[[Class_MapObject#SetPFXEmitterVelocity|velocity <b><i>(added in v1.2)</i></b>]]
:::Set the emitter velocity in metres per second along the direction vector.

For examples see.... (tbd)
</td></tr></table>


<table width=1200><tr><td>

====paths====
:Type: String - (a list of two strings)
:Example: paths "marker-lights/night-only""
:Compulsory: Yes
:Default: None
:Desc: For kind config-edit. A comma-separated list of paths that point to the tag in the wagon-x config to edit.

</td></tr></table>


<table width=1200><tr><td>
====property-id====
:Type: String
:Compulsory: Yes
:Default: None
:Desc: The formal name (ID) of this property, used to identify and change this property. For example, If the name is <b>Workflow</b>, it might be a good idea to call this <b>p_workflow</b>. <div style="color: #ff0080">This must be unique for each browser-property</div>.
</td></tr></table>


<table width=1200><tr><td>
====property-sync-id====
:Type: String
:Compulsory: No
:Default: None
:Desc: The ID that determines which assets will be affected when consist-property-sync is activated. Only assets that share this ID will be synced in the consist, so be sure to make it particular and unique.
:Example: property-sync-id "soundBell"
</td></tr></table>


<table width=1200><tr><td>
====property-visibility====
:Type: Integer - (0 = Hidden, 1 = Visible, 2 = Surveyor Only, 3 = Driver Only)
:Compulsory: No
:Default: 0 (hidden)
:Desc: Indicates whether the property will be visible in the Properties Browser and in what mode.
</td></tr></table>


<table width=1200><tr><td>
====sound-triggers====
:Type: String - (a list of strings)
:Example: sound-triggers "bell_1,bell_2"
:Compulsory: No
:Default: None
:Desc: For kind sound-script only. This specifies the soundscript trigger(s) (comma separated) that this property will start/stop when the property is activated.

</td></tr></table>



<table width=1200><tr><td>
====target-asset====
:Type: String
:Example: target-asset "bogey-0"
:Compulsory: No
:Default: None
:Desc: This determines which assets config this property will manipulate. This tag is currently only used for manipulating a vehicles bogey (e.g. texture replacement). The name must be “bogey-” + the index of the bogey to edit. This gives you full access to the bogeys mesh-table, allowing you to set texture replacements, mesh toggles, and other properties within the bogey. This tag can be omitted if you are not doing bogey texture replacements. <b>Only properties of kind “mesh-attachment” or “fx-replacement” can be used for properties that use this tag.</b>
</td></tr></table>



<table width=1200><tr><td>
====trigger====
:Type: String
:Example: trigger "user"
:Compulsory: No
:Default: Null (ignored)
:Desc: The event that will trigger/activate this property. Can be either an external event, such as a coal-loading animation, or a user-controlled event, or both. Setting it to none is useful if this is a [[#child-properties|child-properties]] property of another property. Possible values are:
:::*user
:::*event
:::*parent
:::*condition <b><i>(added in v1.2)</i></b>
:::*variable <b><i>(added in v1.2)</i></b>
::::multiple <b><i>(added in v1.2)</i></b>
:::*both <b><i>(obsolete as of v1.2)</i></b>
:::*none
<br>
:User: Used when the property is updated by the user in the Properties Browser.
:Event: Used when the property is to be triggering by an event initiated by Trainz such as day to night. These are generally the result of messages posted either by the system or other asset scripts.
:Parent: Used in a child property where the property is to be activated by a parent property.
:Condition: TBA
:Variable: TBA
:Multiple: TBA
:Both: TBA
:None: No trigger.
</td></tr></table>



<table width=1200><tr><td>

====update-events====
<b><i>(added in v1.2)</i></b>
:Type: String - (a list of strings)
:Compulsory: No
:Default: None
:Desc: Very similar to the ‘events’ tag, except this tag triggers a refresh of the conditional and variable events within this property based on the triggered event. By default, conditional events refresh at a certain time interval, based on the ‘update-frequency’ tag. Adding this tag will refresh the property immediately when the trigger event is activated. Can be any of the property events in the ‘events’ tag.
</td></tr></table>



<table width=1200><tr><td>
====values====
:Type: String - (a string list separated by special characters)
:Example1 values "0,15,30"
:Compulsory: No
:Default: None
:Desc: A comma-separated (and optionally semicolon-separated) list of all the files/values to be switched between. If the files-path tag is used, only include each file’s name (exclude the path and extension). This tag is required for all properties. If it is not wanted, leave the value at “1”, but keep the tag still. For booleans, use 1 for true, and 0 for false. For animations, specify the animation frames you want to toggle through. For details on using the semicolon separator to shorten properties, see [[WagonX_-_Browser_Properties_Examples_and_Basic_Tutorials#Using_semicolons_to_set_multiple_values_in_one_property|Examples and Basic Tutorials]].<br>
Each kind has its own rules for what to put here, explained below. See the [[#kind|kind]] property for more info on these.<br>

:::*For kind mesh-attachment:
::::*For mesh-attachment-type mesh-toggle, the value must be either 0 or 1 (visible/hidden) ???
::::*For mesh-attachment-type mesh-translation-orientation, the value must be a 3-dimensional vector with values separated by backticks, enclosed with round brackets for the translation, followed by a colon, then another round bracket-enclosed 3d vector for the orientation, as shown below. 0`2`4 is the translation, and 1.2`2`2 is the orientation (we have to use backticks because the comma is already used here for separating each index value).
::::Example: values "(0`2`4):(1.2`2`2),(0`0`0):(0`0`0)"

:::*For mesh-attachment-type mesh-animation-speed, the value is the speed of the animation for that index
:::*For mesh-attachment-type mesh-animation-loop, the value will be an integer bool (0 or 1) to indicate whether to start the loop, or stop it. You can create a separate property that controls the mesh-animation-speed, and link it via a [[#child-properties|child-properties]] property to control the speed of the loop.
:::*For mesh-attachment type mesh-animation-frame, the value is the frame of the animation to jump to. Setting it to -1 will put that index at the last animation frame in the mesh (see [[Class_MeshObject#GetMeshAnimationFrameCount|<span style="color: #0080ff">GetMeshAnimationFrameCount</span>]]).
::::Example: values "0,30"
:::*For mesh-attachment-type mesh-animation-loop, the value can be 0 or 1, to start/stop the loop

:::*For kind sound-script, the value can be 0 or 1, to start/stop the soundscript event

:::*For kind config-edit, the value is a string indicating the string value to assign to the config tag.

:::*For kind particle-effect:
:::*For particle-effect-type pfx-message, the value follows the same rules for [[Pfx_Message|pfx message]].
::::*particle-effect-type "pfx-message"
::::Example: values "+0+1,-1-0"

:::*For kind fx-replacement:
::::*For fx-replacement-type texture-replacement, the comma and/or. semicolon-separated values represent the index in the texture-group asset to find the texture. Setting the first value to 1 will reference the texture index 1, shown in the partial config for a textures asset below:
::::Values “0,2,1” will reference the textures in the texture container at indexes 0, 2, and 1, in that order when cycled through.
::::Example: values “0,2,1”

kuid <kuid:1234:123456>
username "test texture group asset"
trainz-build 4.6
description "test texture group"
textures
{
0 "textures\0albedo.texture"
1 "textures\1albedo.texture"
2 "textures\2albedo.texture"
3 "textures\0parameter.texture"
4 "textures\1parameter.texture"
5 "textures\2parameter.texture"
6 "textures\0normal.texture"
7 "textures\1normal.texture"
8 "textures\2normal.texture"
}

::::*For fx-replacement-type texture-replacement-texture, the comma and/or semicolon-separated values are the names of the files (ideally without the path or extension) to be referenced at that index.
::::Example: values "images/congleton.texture,images/burntisland.texture,images/buxton.texture,images/none.texture"
::::If you have the same path (and same extension) for all your files, you can greatly reduce the clutter by just specifying the path and extension once using the files-path tag. So, in this case the values entry would be:
::::Example: values "congleton,burntisland,buxton,none"

0
{
enabled 1
property-visibility 1
name "Workflow Text: "
property-id "p_workflow"
description "Sets the Workflow"
kind "fx-replacement"
fx-replacement-type "texture-replacement-texture"
consist-property-sync 1
meshes "null"
effects "texture-extra"
asset "null"
files-path "images/,.texture"
values "congleton,burntisland,buxton,none"
default-index 0
trigger "user"
display-type "list"
display-values "Congleton,Burntisland,Buxton,None"
}

::::*For fx-replacement-type attachment, the values are the names of the attachment effects to be replaced by the specified [[#asset|asset]].
::::*For fx-replacement-type corona, the values are the names of the corona effects to be replaced by the specified [[#asset|asset]].
::::*For fx-replacement-type animation, the values are the names of the animation effects to be replaced by the specified [[#asset|asset]].
::::*For fx-replacement-type name, the values are the names that will replace the current name of the specified name effect.

</td></tr></table>



<table width=1200><tr><td>
====variables====
<b><i>Added in version 1.2 (needs validation)</i></b>
:Type: String
:Compulsory: No
:Default: None
:Desc: For trigger kind “variable”. An array of variable event(s) that control the value of the property using any of the conditional values and five arithmetic operators, ‘+’ (addition), ‘-’ (subtraction), ‘*’ (multiplication), ‘/’ (division), ‘^’ (exponent). You can use as many ‘|’ separated operators as you want. The operations do not follow the standard PEMDAS order of operations but are performed in a left-to-right additive manner.
:Example1: a*b+c is the same as (a*b)+c,
:Example2: c+a*b is the same as (c+a)*b, and
:Example3: a*b+c/2 is the same as ((a*b)+c)/2
</td></tr></table>



<table width=1200><tr><td>
=Copyright Notice=
Much of the content on this page and child pages was derived from Dundun92's original Google Docs document. Permission was granted to use that information here.
</td></tr></table>

HowTo/WagonX - Technical Reference

2024-02-29T06:24:52Z

Pcas1986: Added changes for WagonX 1.2 (still in development) and some tidy up

<table width=1200><tr><td>
= 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:

# [[HowTo/Use the WagonX Library|How to use the WagonX library]]<br>
# [[HowTo/WagonX - Browser Properties Examples and Basic Tutorials|WagonX Examples and Basic Tutorials]]<br>
# [[HowTo/WagonX - Traincar Tutorial|WagonX Traincar Tutorial]]<br>
# [[HowTo/WagonX - Locomotive Tutorial|WagonX Locomotive Tutorial]]<br>
</tr></td></table>

__TOC__

<table width=1200><tr><td>
= 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.
</td></tr></table>

<table width=1200><tr valign="top"><td>
= 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|display-values]].

*Comma ( , )
*Semicolon ( ; )
*Backtick/Grave ( ` )
*Colon ( : )
*Caret ( ^ )
*Round brackets ( and )
</td></tr></table>

<table width=1200><tr valign="top"><td>
== 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).<br>
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.
<br>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|values]] tag.
<br>See also [[WagonX_-_Browser_Properties_Examples_and_Basic_Tutorials#Using_semicolons_to_set_multiple_values_in_one_property|Using semicolons to set multiple values in one property]].
</td></tr></table>

<table width=1200><tr valign="top"><td>
== 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.
</td></tr></table>

<table width=1200><tr valign="top"><td>
== Other special characters ==
Caret - The caret/circumflex symbol (^) is a math power operator. It can be used in variables.<br>
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|values]].<br>
Colon - See Round Brackets above.
</td></tr></table>

<table width=1200><tr valign="top"><td><tr>
= General Layout =

WagonX config tags are defined in the extensions container along with other extensions such as ACS Lib. The general layout of the extensions container that also includes ACS Lib might look like this:
extensions
{
max_permitted_speed-60850 "50mph"
active-coupling-standard-60850
{
...
}
wagon-x
{
...
}
}
</td></tr></table>

<table width=1200><tr valign="top"><td>
= 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.
</td></tr></table>


<table width=1200><tr><td>
== ACS ==
For help on creating the acs extensions and setting up the acs mesh-table objects, see [[HowTo/WagonX_-_Browser_Properties_Examples_and_Basic_Tutorials#Naming_ACS_mesh-table_attachments|Naming ACS mesh-table attachments]].
<br>
Each tag is shown here with sample values. There are no default values.

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

*<b>animated (1 = true, 0=false)</b>
:This determines whether to use animations to move between the coupled and uncoupled state, or use individual static assets for each state.
*<b>use-jbv-animation (1 = true, 0=false)</b>
: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.
*<b>duration (a floating point value)</b>
: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)
*<b>buffer-length-front float</b>
: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
*<b>buffer-length-back float</b>
: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
</td></tr></table>

<table width=1200><tr><td>
== text-x ==

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

*<b>controller string</b>
:Determines how the property will be controlled. Can be controlled by the user, the running number, or a custom range.
:::*user
:::*arn
:::*range
*<b>range string</b>
:Defines the range of values the for the text proprety. It will choose a random index to start<br>
*<b>value string</b>
: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”).<br>
*<b>font int</b>
:The default font index for the text property, these values can be changeed by adding a “config-edit” property to the browser-properties.
*<b>files-path string</b>
: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.<br>
*<b>textures string</b>
: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.<br>
*<b>effects string</b>
:The texture replacement effects to use for displaying the text.<br>

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"
}
}
}
</td></tr></table>


<table width=1200><tr><td>
== 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
}

*<b>mobile float</b> <b><i>(added in v1.2)</i></b>
: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.<br>
*<b>update-frequency float</b> <b><i>(added in v1.2)</i></b>
: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.
*<b>begin-load-time (a floating point value)</b>
:The time it takes for the wagon to load at an industry
*<b>begin-unload-time (a floating point value)</b>
:The time it takes for the wagon to unloading at an industry
*<b>end-load-time (a floating point value)</b>
:The time it takes for the wagon end loading at an industry
*<b>end-unload-time (a floating point value)</b>
:The time it takes for the wagon to end unloading at an industry
</td></tr></table>



<table width=1200><tr><td>
== 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"
}
}
}

*<b>enabled (1 = true, 0=false)</b>
:Whether or not the marker lights are active on this asset.
*<b>car-minimum-count (an integer number)</b>
:The minimum number of cars that must be present in the consist for the marker-lights to activate.
*<b>require-locomotive (1 = true, 0=false)</b>
:If set to 1, a traincar of Class locomotive will need to be present in the consist for the marker-lights to activate.
*<b>night-only (1 = true, 0=false)</b>
:If set to 1, the lamps will only be visible at night, otherwise they will be displayed 24/7.
*<b>Front/back head/tail containers</b>
:These containers identify the mesh to use for the front, back, head, and tail lamps. These meshes must be in the config mesh-table.
</td></tr></table>



<table width=1200><tr><td>
== 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"
}
}
</td></tr></table>


<table width=1200><tr><td>
===Supported Tags===
Tag explanations. Some examples are included in the definition and, for others, see above for sample of usage.
</td></tr></table>



<table width=1200><tr><td>
====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|effects]] tag, the [[#meshes|meshes]] tag, or the [[#particle-effects|particle-effects]] tag, but not more than one.

</td></tr></table>


<table width=1200><tr><td>
====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"
</td></tr></table>

<table width=1200><tr><td>
====conditions====
<b><i>(added in v1.2)</i></b>
: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|Class Vehicle]]. Please refer to that page for information on function behavior and usage.<br>
::::<b>example 1: veh_velocity|>=|5&veh_mass>1500 -></b> 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.
::::<b>example 2: veh_engine-param_main-reservoir-pressure|<|0.5 -></b> 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)


</td></tr></table>

<table width=1200><tr><td>
====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|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.
</td></tr></table>

<table width=1200><tr><td>

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

</td></tr></table>

<table width=1200><tr><td>
====description====
:Type: String
:Compulsory: No
:Default: None
:Desc: The description of this attachment as it will appear in the Properties Browser.
</td></tr></table>

<table width=1200><tr><td>

====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. <b>For trainzbuild 5.1 and 5.0, only link is supported for the View Details page.</b> 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

</td></tr></table>

<table width=1200><tr><td>

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

</td></tr></table>

<table width=1200><tr><td>

====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. <b>(There may be issues with using this tag with mesh-toggle.)</b>
:Example: duration 3.2

</td></tr></table>

<table width=1200><tr><td>

====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|kind]] fx-replacement. Use this tag, the mesh tag, or the asset tag, but not more than one.

</td></tr></table>

<table width=1200><tr><td>
====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.
</td></tr></table>

<table width=1200><tr><td>

====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 <b><i>(added in v1.2)</i></b>
:::*handbrake-apply/handbrake-release
:::*trainbrake-apply/trainbrake-release
:::*headlight-on, headlight-off
:::*throttle-changed <b><i>(added in v1.2)</i></b>
:::*front-coupled/back-coupled,front-uncoupled/back-uncoupled <b><i>(added in v1.2)</i></b>
:::*view-internal, view-external, view-tracking, view-roaming <b><i>(added in v1.2)</i></b>
:::*horn
:::*bell
:::*sanding
:::*pantograph-state-0/1/2/3 (see [[Class_Train#GetPantographState|<span style="color: #0080ff">GetPantographState</span>]])
:::*weather-0/1/2/3/4/5/6/7 (see [[Class_World#GetWeatherType|<span style="color: #0080ff">GetWeatherType</span>]])
:::*world-day/world-night
:::*priority-number-(0 - ∞) (e.g. priority-number-2) <b><i>(added in v1.2)</i></b>
:::*arn-(0 -∞ ) (e.g. arn-92220, arn-844) <b><i>(added in v1.2)</i></b>
:::*queue-(0 - ∞)- loaded/empty (e.g. <b>queue-0-loaded, queue-1-empty</b>)

</td></tr></table>

<table width=1200><tr><td>

====files-path====
:Type: String - (a list of two strings)
:Example: files-path "images/,.texture"
:Compulsory: No
:Default: None
:Desc: 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. <b>files-path “images/left/.texture”</b>), where images/left is the path, and .texture is the extension for all the files.

</td></tr></table>

<table width=1200><tr><td>

====fx-replacement-type====
:Type: String)(kind fx-replacement only)
:Example: kind "fx-replacement"
:::fx-replacement-type "texture-replacement"
:Compulsory: No
:Default: None
:Desc: The type of fx replacement effect this property will be if the [[#kind|kind]] tag is set to fx-replacement. Each one is hyperlinked to the corresponding trainzscript function, though it is not necessary to know them. See [[#values|values]] for instructions on how to implement these properties.
::*[[Class_MeshObject#SetFXTextureReplacement|<span style="color: #0080ff">texture-replacement</span>]]
:::Replaces a texture effect in this asset to one within a texture-group asset.
::*[[Class_MeshObject#SetFXTextureReplacementTexture|<span style="color: #0080ff">texture-replacement-texture</span>]]
:::Replaces a texture effect in this asset to one located within this asset.
::*[[Class_MeshObject#SetFXCoronaTexture|<span style="color: #0080ff">corona</span>]]
:::Replaces a corona effect in the asset.
::*[[Class_MeshObject#SetFXNameText|<span style="color: #0080ff">name</span>]]
:::Replaces a name effect in the asset.
::*[[Class_MeshObject#SetFXAttachment|<span style="color: #0080ff">attachment</span>]]
:::Replaces an attachment effect in the asset.
::*[[Class_MeshObject#SetFXAnimationState|<span style="color: #0080ff">animation</span>]]
:::Plays/Stops an animation effect in the asset.

</td></tr></table>

<table width=1200><tr><td>
====kind====
:Type: String
:Compulsory: No
:Default: None
:Desc: The type of property this will be. Can be one of the options below. Most of these are derived from [[Class MeshObject|Class_MeshObject]]. For more info on implementing these, see [[#values|values]].
::*mesh-attachment
:::Manipulate the mesh’s animation, position, visibility, etc. See mesh-attachment-type.
::*fx-replacement
:::Change an effect in the mesh. See [[#fx-replacement-type|fx-replacement-type]].
::*particle-effect
:::Activate/Deactivate/Edit a particle effect (smoke0, smoke1, etc). See [[#particle-effects|particle-effects]] and [[#particle-effect=type|particle-effect-type]].
::*sound-script
:::Used to play a sound-script sound within this asset. See [[#sound-triggers|sound-triggers]].
::*config-edit
:::Used to edit a tag in the wagon-x config soup. See paths.
</td></tr></table>

<table width=1200><tr><td>

====meshes====
:Type: String - (a list of mesh names from the mesh-table separated by commas)
:Example: meshes "handbrake-lever,braking-system"
:Compulsory: No
:Default: None
:Desc: The comma-separated mesh-table asset(s) to be modified by the property. Use this for [[#kind|kind]] mesh-toggle or kind mesh-animation. Use this tag, the effect tag, or the asset tag, but not more than one.

</td></tr></table>

<table width=1200><tr><td>

====mesh-attachment-type====
:Type: String - (kind mesh-attachment only)
:Example: kind "mesh-attachment"
:: mesh-attachment-type "mesh-animation-frame"
:Compulsory: No
:Default: None
:Desc: The type of mesh property this property will be if the kind tag is set to mesh-attachment. Each one is hyperlinked to the corresponding trainzscript function, though it is not necessary to know them. See values for instructions on how to implement these properties.
::*[[Class_MeshObject#SetMeshVisible|<span style="color: #0080ff">mesh-toggle</span>]]
:::Toggle between the mesh(s) being visible or hidden.
::*[[Class_MeshObject#SetMeshOrientation|<span style="color: #0080ff">mesh-translation-orientation</span>]]
:::Sets the translation and orientation of the mesh(es)
::*[[Class_MeshObject#SetMeshAnimationFrame|<span style="color: #0080ff">mesh-animation-frame</span>]]
:::Sets the frame(s) the meshes animation will move between. Useful for door opening and closing animations, or animations that require more than 2 states.
::*[[Class_MeshObject#StartMeshAnimationLoop|<span style="color: #0080ff">mesh-animation-loop</span>]]
:::Start or stop an animation-loop on the mesh.
::*[[Class_MeshObject#SetMeshAnimationState|<span style="color: #0080ff">mesh-animation-state</span>]]
:::Sets the state of the mesh(s) animation.
::*[[Class_MeshObject#SetMeshAnimationSpeed|<span style="color: #0080ff">mesh-animation-speed</span>]]
:::Changes the speed of the meshes animation.

</td></tr></table>

<table width=1200><tr><td>
====name====
:Type: String
:Compulsory: Yes
:Default: None
:Desc: The display name of this property, as will appear on the properties page.
</td></tr></table>


<table width=1200><tr><td>
====particle-effects====
:Type: String - (a list of integer numbers as a string)
:Example: particle-effects "0,1"
:Compulsory: No
:Default: None
:Desc: For kind particle-effect. The comma-separated list of PFX effects to be modified by the property. See kind for help on implementation. <b>There is currently no use for this tag as of yet. pfx-message doesn't need this because everything is already specified in the values tag.</b>

</td></tr></table>



<table width=1200><tr><td>
====particle-effect-type====
:Type: String (kind mesh-attachment only)
:Compulsory: No
:Default: None
:Desc: The type of PFX function this property will be if the [[#kind|kind]] tag is set to particle-effect.
Each one is hyperlinked to the corresponding trainzscript function, though it is not necessary to know them. See [[#values|values]] for instructions on how to implement these properties. Most of these are derived for the PFXEmitter properties specified in [[MapObject|Class MapObject]], with the prefix “GetPFXEmitter” omitted. All except [[MapObject#SetPFXEmitterTexture|SetPFXEmitterTexture]] are supported.
:Example: kind "particle-effect"
: particle-effect-type "pfx-message"
:Comments: Needs to be validated with examples!
::*[[pfx_Message|pfx-message]]
:::Send a message to enable/disable a particle effect.
::*[[Class_MapObject#SetPFXEmitterConeSize|cone-size <b><i>(added in v1.2)</i></b>]]
:::Update the cone size with x,y and z sizes in values tag.
::*[[Class_MapObject#SetPFXEmitterEmitParticles|emit-particles <b><i>(added in v1.2)</i></b>]]
:::Update the number of particles and time they will be created.
::*[[Class_MapObject#SetPFXEmitterEndColor|end-color <b><i>(added in v1.2)</i></b>]]
:::Update the end colour of the particles.
::*[[Class_MapObject#SetPFXEmitterStartColor|start-color <b><i>(added in v1.2)</i></b>]]
:::Update the start colour of the particles.
::*[[Class_MapObject#SetPFXEmitterLifetime|lifetime <b><i>(added in v1.2)</i></b>]]
:::Update the emitter lifetime using seconds.
::*[[Class_MapObject#SetPFXEmitterMaxRate|max-rate <b><i>(added in v1.2)</i></b>]]
:::Update the emitter maximum rate per second.
::*[[Class_MapObject#SetPFXEmitterMinRate|min-rate <b><i>(added in v1.2)</i></b><b><i>(added in v1.2)</i></b>]]
:::Update the emitter minimum rate per second.
::*[[Class_MapObject#SetPFXEmitterMaxSize|max-size <b><i>(added in v1.2)</i></b>]]
:::Update the maximum size size of particles. The size is a single float.
::*[[Class_MapObject#SetPFXEmitterMinSize|min-size <b><i>(added in v1.2)</i></b>]]
:::Update the minimum size of particles. The size is a single float.
::*[[Class_MapObject#SetPFXEmitterPhysicsDelay|physics-delay <b><i>(added in v1.2)</i></b>]]
:::Update the physics delay for the emitter. The delay value is in seconds.
::*[[Class_MapObject#SetPFXEmitterRate|rate <b><i>(added in v1.2)</i></b>]]
:::Set a new rate of particle creation per second.
::*[[Class_MapObject#SetPFXEmitterVelocity|velocity <b><i>(added in v1.2)</i></b>]]
:::Set the emitter velocity in metres per second along the direction vector.

For examples see.... (tbd)
</td></tr></table>


<table width=1200><tr><td>

====paths====
:Type: String - (a list of two strings)
:Example: paths "marker-lights/night-only""
:Compulsory: Yes
:Default: None
:Desc: For kind config-edit. A comma-separated list of paths that point to the tag in the wagon-x config to edit.

</td></tr></table>


<table width=1200><tr><td>
====property-id====
:Type: String
:Compulsory: Yes
:Default: None
:Desc: The formal name (ID) of this property, used to identify and change this property. For example, If the name is <b>Workflow</b>, it might be a good idea to call this <b>p_workflow</b>. <div style="color: #ff0080">This must be unique for each browser-property</div>.
</td></tr></table>


<table width=1200><tr><td>
====property-sync-id====
:Type: String
:Compulsory: No
:Default: None
:Desc: The ID that determines which assets will be affected when consist-property-sync is activated. Only assets that share this ID will be synced in the consist, so be sure to make it particular and unique.
:Example: property-sync-id "soundBell"
</td></tr></table>


<table width=1200><tr><td>
====property-visibility====
:Type: Integer - (0 = Hidden, 1 = Visible, 2 = Surveyor Only, 3 = Driver Only)
:Compulsory: No
:Default: 0 (hidden)
:Desc: Indicates whether the property will be visible in the Properties Browser and in what mode.
</td></tr></table>


<table width=1200><tr><td>
====sound-triggers====
:Type: String - (a list of strings)
:Example: sound-triggers "bell_1,bell_2"
:Compulsory: No
:Default: None
:Desc: For kind sound-script only. This specifies the soundscript trigger(s) (comma separated) that this property will start/stop when the property is activated.

</td></tr></table>



<table width=1200><tr><td>
====target-asset====
:Type: String
:Example: target-asset "bogey-0"
:Compulsory: No
:Default: None
:Desc: This determines which assets config this property will manipulate. This tag is currently only used for manipulating a vehicles bogey (e.g. texture replacement). The name must be “bogey-” + the index of the bogey to edit. This gives you full access to the bogeys mesh-table, allowing you to set texture replacements, mesh toggles, and other properties within the bogey. This tag can be omitted if you are not doing bogey texture replacements. <b>Only properties of kind “mesh-attachment” or “fx-replacement” can be used for properties that use this tag.</b>
</td></tr></table>



<table width=1200><tr><td>
====trigger====
:Type: String
:Example: trigger "user"
:Compulsory: No
:Default: Null (ignored)
:Desc: The event that will trigger/activate this property. Can be either an external event, such as a coal-loading animation, or a user-controlled event, or both. Setting it to none is useful if this is a [[#child-properties|child-properties]] property of another property. Possible values are:
:::*user
:::*event
:::*condition <b><i>(added in v1.2)</i></b>
:::*variable <b><i>(added in v1.2)</i></b>
::::multiple <b><i>(added in v1.2)</i></b>
:::*both <b><i>(obsolete as of v1.2)</i></b>
:::*none
</td></tr></table>



<table width=1200><tr><td>
====update-events====
<b><i>(added in v1.2)</i></b>
:Type: String - (a list of strings)
:Compulsory: No
:Default: None
:Desc: Very similar to the ‘events’ tag, except this tag triggers a refresh of the conditional and variable events within this property based on the triggered event. By default, conditional events refresh at a certain time interval, based on the ‘update-frequency’ tag. Adding this tag will refresh the property immediately when the trigger event is activated. Can be any of the property events in the ‘events’ tag.
</td></tr></table>



<table width=1200><tr><td>
====values====
:Type: String - (a string list separated by special characters)
:Example1 values "0,15,30"
:Compulsory: No
:Default: None
:Desc: A comma-separated (and optionally semicolon-separated) list of all the files/values to be switched between. If the files-path tag is used, only include each file’s name (exclude the path and extension). This tag is required for all properties. If it is not wanted, leave the value at “1”, but keep the tag still. For booleans, use 1 for true, and 0 for false. For animations, specify the animation frames you want to toggle through. For details on using the semicolon separator to shorten properties, see [[WagonX_-_Browser_Properties_Examples_and_Basic_Tutorials#Using_semicolons_to_set_multiple_values_in_one_property|Examples and Basic Tutorials]].<br>
Each kind has its own rules for what to put here, explained below. See the [[#kind|kind]] property for more info on these.<br>

:::*For kind mesh-attachment:
::::*For mesh-attachment-type mesh-toggle, the value must be either 0 or 1 (visible/hidden) ???
::::*For mesh-attachment-type mesh-translation-orientation, the value must be a 3-dimensional vector with values separated by backticks, enclosed with round brackets for the translation, followed by a colon, then another round bracket-enclosed 3d vector for the orientation, as shown below. 0`2`4 is the translation, and 1.2`2`2 is the orientation (we have to use backticks because the comma is already used here for separating each index value).
::::Example: values "(0`2`4):(1.2`2`2),(0`0`0):(0`0`0)"

:::*For mesh-attachment-type mesh-animation-speed, the value is the speed of the animation for that index
:::*For mesh-attachment-type mesh-animation-loop, the value will be an integer bool (0 or 1) to indicate whether to start the loop, or stop it. You can create a separate property that controls the mesh-animation-speed, and link it via a [[#child-properties|child-properties]] property to control the speed of the loop.
:::*For mesh-attachment type mesh-animation-frame, the value is the frame of the animation to jump to. Setting it to -1 will put that index at the last animation frame in the mesh (see [[Class_MeshObject#GetMeshAnimationFrameCount|<span style="color: #0080ff">GetMeshAnimationFrameCount</span>]]).
::::Example: values "0,30"
:::*For mesh-attachment-type mesh-animation-loop, the value can be 0 or 1, to start/stop the loop

:::*For kind sound-script, the value can be 0 or 1, to start/stop the soundscript event

:::*For kind config-edit, the value is a string indicating the string value to assign to the config tag.

:::*For kind particle-effect:
:::*For particle-effect-type pfx-message, the value follows the same rules for [[Pfx_Message|pfx message]].
::::*particle-effect-type "pfx-message"
::::Example: values "+0+1,-1-0"

:::*For kind fx-replacement:
::::*For fx-replacement-type texture-replacement, the comma and/or. semicolon-separated values represent the index in the texture-group asset to find the texture. Setting the first value to 1 will reference the texture index 1, shown in the partial config for a textures asset below:
::::Values “0,2,1” will reference the textures in the texture container at indexes 0, 2, and 1, in that order when cycled through.
::::Example: values “0,2,1”

kuid <kuid:1234:123456>
username "test texture group asset"
trainz-build 4.6
description "test texture group"
textures
{
0 "textures\0albedo.texture"
1 "textures\1albedo.texture"
2 "textures\2albedo.texture"
3 "textures\0parameter.texture"
4 "textures\1parameter.texture"
5 "textures\2parameter.texture"
6 "textures\0normal.texture"
7 "textures\1normal.texture"
8 "textures\2normal.texture"
}

::::*For fx-replacement-type texture-replacement-texture, the comma and/or semicolon-separated values are the names of the files (ideally without the path or extension) to be referenced at that index.
::::Example: values "images/congleton.texture,images/burntisland.texture,images/buxton.texture,images/none.texture"
::::If you have the same path (and same extension) for all your files, you can greatly reduce the clutter by just specifying the path and extension once using the files-path tag. So, in this case the values entry would be:
::::Example: values "congleton,burntisland,buxton,none"

0
{
enabled 1
property-visibility 1
name "Workflow Text: "
property-id "p_workflow"
description "Sets the Workflow"
kind "fx-replacement"
fx-replacement-type "texture-replacement-texture"
consist-property-sync 1
meshes "null"
effects "texture-extra"
asset "null"
files-path "images/,.texture"
values "congleton,burntisland,buxton,none"
default-index 0
trigger "user"
display-type "list"
display-values "Congleton,Burntisland,Buxton,None"
}

::::*For fx-replacement-type attachment, the values are the names of the attachment effects to be replaced by the specified [[#asset|asset]].
::::*For fx-replacement-type corona, the values are the names of the corona effects to be replaced by the specified [[#asset|asset]].
::::*For fx-replacement-type animation, the values are the names of the animation effects to be replaced by the specified [[#asset|asset]].
::::*For fx-replacement-type name, the values are the names that will replace the current name of the specified name effect.

</td></tr></table>



<table width=1200><tr><td>
====variables====
<b><i>Added in version 1.2 (needs validation)</i></b>
:Type: String
:Compulsory: No
:Default: None
:Desc: For trigger kind “variable”. An array of variable event(s) that control the value of the property using any of the conditional values and five arithmetic operators, ‘+’ (addition), ‘-’ (subtraction), ‘*’ (multiplication), ‘/’ (division), ‘^’ (exponent). You can use as many ‘|’ separated operators as you want. The operations do not follow the standard PEMDAS order of operations but are performed in a left-to-right additive manner.
:Example1: a*b+c is the same as (a*b)+c,
:Example2: c+a*b is the same as (c+a)*b, and
:Example3: a*b+c/2 is the same as ((a*b)+c)/2
</td></tr></table>



<table width=1200><tr><td>
=Copyright Notice=
Much of the content on this page and child pages was derived from Dundun92's original Google Docs document. Permission was granted to use that information here.
</td></tr></table>

HowTo/WagonX - Browser Properties Examples and Basic Tutorials

2024-02-28T01:22:25Z

Pcas1986: Added some more examples and some updates for WagonX 1.2

<span style="color: red; font-weight: 700; font-size: 15px;">Please note: Much of this page still needs some validation. If you find issues then please contact PCAS1986 in the Trainz Forums or in the Trainz Discord Server.</span>

= Document Structure =
<table width=1200>
The WagonX Tutorial set is written over several pages. This page contains some example WagonX config containers and basic guidance for setting up those containers. Other pages in the series are listed below:
</table>
# [[HowTo/Use the WagonX Library]]<br>
# [[HowTo/WagonX - Technical Reference]]<br>
# [[HowTo/WagonX - Locomotive Tutorial]]<br>
# [[HowTo/WagonX - Traincar Tutorial]]<br>
# [https://docs.google.com/document/d/1jd5nZNQJI_gKQp-X2GjNCBij9fZGAwgJy_BgBiXf3_8/edit#bookmark=id.kupvwsc34hnk| The asset author's documentation]

= General Comments =
Most of the notes and examples here are for Version 1 but WagonX continues to be developed. Features and/or changes for versions later than V1 are identified in the text.

__TOC__

=Browser property tutorials=

This tutorial takes you each step of creating a simple mesh toggle example. It is for a handbrake mesh, including animation, that the user may want to show (make visible) or hide (make invisible). We will add each property tag and explain its purpose.
It may be useful to have the [[HowTo/WagonX - Technical Reference|WagonX Technical Reference]] page open in a browser to examine details of the various tags.
<table width=1200><tr><td>
==Creating a basic mesh toggle==
*Start with an empty browser-properties container like this:

browser-properties
{
}

*Add an empty property container and name it "0". The names are not used but should be unique. When we add more properties, you should name them “1”, “2”, “3”, etc.

browser-properties
{
0
{
}
}

*There is no order required for each property, but using a standard order makes it easier to follow. Each tag is hyperlinked to the browser-property, so you can see more information about it.
The first tag to add is [[HowTo/WagonX - Technical Reference#enabled|enabled]]. This determines whether or not the property is activated. Set it to 1, since we want our property to work in-game.

browser-properties
{
0
{
enabled 1
}
}

*Set the visibility of the property using [[HowTo/WagonX - Technical Reference#property-visibility|property-visibility]] and make that 1. Note this value is an integer and doesn't require quotes around it. A value of 1 makes the property visible in both Surveyor and Driver. See the reference for other available values.

browser-properties
{
0
{
enabled 1
property-visibility 1
}
}

*Set the [[HowTo/WagonX - Technical Reference#name|name]] of our property. The name will appear before the [[HowTo/WagonX - Technical Reference#display-values|display-values]], which we will get to in a moment. You also will want to add a space at the end; otherwise, the property name and display-value will appear as one word.
browser-properties
{
0
{
enabled 1
property-visibility 1
name "Toggle Mesh: "
}
}

*Set the [[HowTo/WagonX - Technical Reference#property-id|property-id]], which can be anything as long as it is unique and doesn't contain [[HowTo/WagonX - Technical Reference#Restricted_Characters|restricted characters]]. Trainz will use this to identify this property.
browser-properties
{
0
{
enabled 1
property-visibility 1
name "Toggle Mesh: "
property-id "p_meshToggle"
}
}

*Set the [[HowTo/WagonX - Technical Reference#description|description]]. This will appear as the tool-tip when you hover over a browser-property.
browser-properties
{
0
{
enabled 1
property-visibility 1
name "Toggle Mesh: "
property-id "p_meshToggle"
description "Toggles the mesh"
}
}

*Set the property [[HowTo/WagonX - Technical Reference#kind|kind]]. Since we want a mesh-attachment kind, we must also specify the [[HowTo/WagonX - Technical Reference#mesh-attachment-type|mesh-attachment-type]] which for this application is mesh-toggle.
browser-properties
{
0
{
enabled 1
property-visibility 1
name "Toggle Mesh: "
property-id "p_meshToggle"
description "Toggles the mesh"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
}
}

*Now add a [[HowTo/WagonX - Technical Reference#meshes|meshes]] tag to specify what mesh we want to toggle. The mesh name must exist in the config mesh-table. We will use the script author's prestwins handbrake lever for this demo.

Here is part of the config mesh-table:
handbrake-lever
{
mesh "mesh/handbrake.lm"
anim "mesh/handbrake_scene.kin"
auto-create 1
att-parent "default"
}

browser-properties
{
0
{
enabled 1
property-visibility 1
name "Toggle Mesh: "
property-id "p_handbrakeMeshToggle"
description "Toggles the handbrake mesh"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "handbrake-lever"
}
}

*Add the [[HowTo/WagonX - Technical Reference#values|values]] tag. This determines what the state of the object will be at each index. The values tag varies depending on the kind and, since this is a toggle, we want a true (1) or false (0) value. For kind mesh-toggle, we set it at 0 to hide the mesh, and 1 to show the mesh. Each index is comma separated, so we will set the first one at 1, and the second one at 0.
browser-properties
{
0
{
enabled 1
property-visibility 1
name "Toggle Mesh: "
property-id "p_handbrakeMeshToggle"
description "Toggles the handbrake mesh"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "handbrake-lever"
values "1,0"
}
}

*Add the [[HowTo/WagonX - Technical Reference#default-index|default-index]]. This is an integer value starting from 0 and which indicates the position in a list. 0 is the first in the list, 1 is the second, and so on. <i>(The reasons for this are somewhat historical but also based on how computers find things in memory.)</i> If we set it to 1, it will start at the second comma-separated values tag which is "0". If we set it at -1, it will pick a random index within the size of the values tag.
browser-properties
{
0
{
enabled 1
property-visibility 1
name "Toggle Mesh: "
property-id "p_handbrakeMeshToggle"
description "Toggles the handbrake mesh"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "handbrake-lever"
values "1,0"
default-index 0
}
}

*Add the [[HowTo/WagonX - Technical Reference#trigger|trigger]] tag. We want our property to activate when a user presses a button on the properties page, so we will set it to <b>user</b>. If we set it to <b>event</b>, however, we could make it activate based on an event within the train or in the world, such as handbrake apply, or enabling it when it gets dark, and disabling it when its daytime again, but for now, we will leave it at user.
browser-properties
{
0
{
enabled 1
property-visibility 1
name "Toggle Mesh: "
property-id "p_handbrakeMeshToggle"
description "Toggles the handbrake mesh"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "handbrake-lever"
values "1,0"
default-index 0
trigger "user"
}
}

*Specify the [[HowTo/WagonX - Technical Reference#display-type|display-type]]. Looking at the options, we see that <b>link</b> is what we want.
browser-properties
{
0
{
enabled 1
property-visibility 1
name "Toggle Mesh: "
property-id "p_handbrakeMeshToggle"
description "Toggles the handbrake mesh"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "handbrake-lever"
values "1,0"
default-index 0
trigger "user"
display-type "link"
}
}

*Finally, the last tag we need is the display-values tag, which we talked about earlier. Since we have two states for our property (specified in the values tag), we will create two comma-separated values for each state. We will call the first “Enabled”, and the second “Hidden”, which corresponds with the numbers we set in the values tag.
browser-properties
{
0
{
enabled 1
property-visibility 1
name "Toggle Mesh: "
property-id "p_handbrakeMeshToggle"
description "Toggles the handbrake mesh"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "handbrake-lever"
values "1,0"
default-index 0
trigger "user"
display-type "link"
display-values "Enabled,Hidden"
}
}

And that's it! Run the asset into trainz, and when you view the properties, you should see your property appear:<br>


[[File:Toggle_handbrake_mesh_in_View_Details.jpg]]

And when you click on the underlined part of your property, the property should change to “Hidden”, as we specified, and the handbrake on the underframe should disappear.<br>
[[File:Handbrake_mesh_show_%26_hide.jpg]]

</td></tr></table>

= Browser-Property Examples =
== User-Triggered Properties ==
Here are a number of examples for user triggering - i.e. in the View Details property browser. Detailed information on the property browser tags can be found on the [[HowTo/WagonX - Reference|WagonX Reference]] page.

<table width=1200><tr><td>
===Mesh-toggle property===
This property allows you to show or hide a mesh that is in the config mesh-table. The values are 0 and 1 to represent false and true. The default is 0 or hidden when first placed.

{
enabled 1
property-visibility 1
name "Toggle: "
property-id "p_toggle"
description "Hide or display the roof mesh"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "roof"
values "0,1"
duration 3
default-index 0
trigger "user"
display-type "link"
display-values "Hidden,Visible"
}
</td></tr></table>


<table width=1200><tr><td>
===texture-replacement property===
This allows the choice of a texture from either local texture files (i.e. contained within the asset), or from a texture group asset, to retexture or reskin a mesh. You could use it for swapping between clean, dirty or weathered textures, logos and also entire liveries.
</td></tr></table>
<br>


<table width=1200><tr><td>
====Texture replacement using local texture files====

For fx-replacement-type texture-replacement-texture, the comma and/or semicolon-separated values are the names of the files (ideally without the path or extension) to be referenced at that index. The values tag will contain a list of texture(.txt) files including a folder name if used. This is an example of three textures.

values "images/congleton.texture,images/burntisland.texture,images/buxton.texture,images/none.texture"

If you have the same path (and same extension) for all your files, you can greatly reduce the clutter by just specifying the path and extension once using the files-path tag. See the files-path and values usage below. Note that the display-values tag contains similar information but that is for the user to see.

0
{
enabled 1
property-visibility 1
name "Workflow Text: "
property-id "p_workflow"
description "Sets the Workflow"
kind "fx-replacement"
fx-replacement-type "texture-replacement-texture"
consist-property-sync 1
meshes "null"
effects "texture-extra"
asset "null"
files-path "images/,.texture"
values "congleton,burntisland,buxton,none"
default-index 0
trigger "user"
display-type "list"
display-values "Congleton,Burntisland,Buxton,None"
}
</td></tr></table>


<table width=1200><tr><td>
====Texture replacement using a texture-group library asset====
You will need to specify the texture group asset in the kuid-table and give it a name such as "texturelib" or "gwrtexturelib", The name should not have any spaces or other special characters.
This property container is set up to allow for three different variations of the the material used for the asset. They are named in the "display-values" tag as Skin 1, Skin 2, and Skin 3.
Since it is a PBR material there are three textures used in the materail: the albedo, parameters, and normal. The normal texture is common to all three versions so it need not be changed.
The "values" tag contains six numbers which are the numbers of the textures in the texture-group asset. For Skin 1 the "12" refers to the albedo texture, and the "15" refers to the parameter texture. "13" and "16" are the pair for Skin2, and "14" and "17" are the pair for Skin 3.
The "effects" tag contains the texture effect names for meshes in the mesh-table.
<br>

{
enabled 1
property-visibility 1
name "Weathering: "
property-id "p_skin"
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 "12;15,13;16,14;17"
default-index -1
trigger "user"
display-type "link"
display-values "Skin 1,Skin 2,Skin 3"
}
</td></tr></table>

== Event-Triggered Properties ==

<table width=1200><tr><td>
===loading-doorsProperty ===
The ‘meshes’ tag references a mesh-table asset named ‘loading-doors’, and sets the frame to 30 when begin-load is called (to open the doors), and 0 when end-load is called (to close the door). The default index is 0 (the animation frame will be at 0), and the animation duration is 1.5 seconds.
{
enabled 0
property-visibility 0
property-id "p_doors"
kind "mesh-attachment"
mesh-attachment-type "mesh-animation-frame"
meshes "loading-doors"
values "0,30"
trigger "event"
events "end-load,begin-load"
duration 1.5
default-index 0
}

An alternate way to do it is use mesh-attachment-type "mesh-animation-state", and set a bool int (0 or 1) for the values tag.
{
enabled 0
property-visibility 0
property-id "p_doors"
kind "mesh-attachment"
mesh-attachment-type "mesh-animation-state"
meshes "loading-doors"
values "0,1"
trigger "event"
events "end-load,begin-load"
default-index 0
}

If you want two doors to open at the same time, instead of creating another property, you can use a semicolon split in the values tag to change two in a single property:
{
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 "door-1,door-2"
values "0;0,30;30"
events "handbrake-release,handbrake-apply"
duration 3.0
default-index 0
trigger "both"
display-type "link"
display-values "release,apply"
}
</td></tr></table>


<table width=1200><tr><td>
===Weather-Based Texture Replacement===
The texture effect will change based on the weather. It will display a snowy texture when the weather type is 6 (medium snow), a wet, rainy texture when the weather type is 3 (rain), and a dry texture when the weather type is 0.
{
enabled 1
property-visibility 0
property-id "p_weather_skin"
kind "fx-replacement"
fx-replacement-type "texture-replacement-texture"
effects "texture-weather"
files-path "images/,.texture"
values "texture-snow,texture-rain,texture-dry"
default-index 0
trigger "event"
events "weather-6,weather-3,weather-0"
}
</td></tr></table>


<table width=1200><tr><td>
===Day and Night Light Control===
WagonX Version 1.2 or greater only.<br>
This event property controls a set of eight exteruir lights on a traincar that must turn on for night and off for day. It also requires a locomotive at the head of its train for the lights to come on.
<br>
The property is a kind fx-replacement of type corona. Turning a corona on and off requires a valid corona to be turned on and usually a null value to turn it off. In this case, instead of a null, we will use an invisible mesh, <kuid:217537:100812>, to achieve the same result. We do this because WagonX needs to obtain an asset from the asset kuid-table.<br>
There are two events to consider: the "World, Day" message represented as "world-day", and the "World, Night" message represented as "world-night".
The requirement for a loco requires a conditions tag using the logic described at (insert link when tech ref updated). The results are boolean (false or true) and the first will be true if no loco exists at the head of the train, and the second if there is a loco. So the possible results are "1;0" (no loco) or "1;0" (loco exists) using the WagonX syntax.<br>
The effects tag contains a list of the corona effects from the asset mesh-table. Each is separated by a comma.<br>
The values tag contains two sets of kuid-table mesh references. Each set is separated by a comma, and the list within each set separated by a semi-colon. The first set turns off the eight coronas when the loco doesn't exist, and the second set turns the coronas on using the same corona asset for each light. You could have different coronas.
{
enabled 1
property-visibility 0
property-id "p_exterior_lights"
kind "fx-replacement"
fx-replacement-type "corona"
duration 0
effects "leftlight-0,leftlight-1,leftlight-2,leftlight-3,rightlight-0,rightlight-1,rightlight-2,rightlight-3"
values "nl;nl;nl;nl;nl;nl;nl;nl,exla;exla;exla;exla;exla;exla;exla;exla"
trigger "multiple"
conditions "tra_frontmost-locomotive|==|0,tra_frontmost-locomotive|==|1"
events "world-day,world-night
}
...
kuid-table {
...
exla <kuid:104722:100> // a white corona
nl <kuid:217537:100812> // an invisible mesh
}
</td></tr></table>

<table width=1200><tr><td>
===Day and Night Interior Control===
WagonX Version 1.2 or greater only.<br>
This example controls the visibility of day and night traincar interiors using the "World, Day/Night" messages. The night interior will not show unless a locomotive is at the head of the traincar's train.<br>
{
enabled 1
property-visibility 0
property-id "p_interior_lighting"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "day-interior,night-interior"
values "1;0,0;1"
default-index 0
duration 0
trigger "multiple"
conditions "tra_frontmost-locomotive|==|0,tra_frontmost-locomotive|==|1"
events "world-day,world-night"
}
</td></tr></table>


<table width=1200><tr><td>
== Using semicolons to set multiple values in one property ==
When assigning values for a certain property, you will specify the mesh/effect/sound, etc that needs to be edited, and specify how you want to manipulate it (fx-replacement-type, mesh-attachment-type, etc), and set the value for a certain index. For example, In a texture replacement where a texture is being replaced by an external texture-group asset, the property would look something like this.

0
{
enabled 1
property-visibility 1
name "Skin: "
property-id "p_skin_parameter"
description "Sets The Texture"
kind "fx-replacement"
fx-replacement-type "texture-replacement"
effects "texture-albedo"
asset "texturelib"
values "1,2,3,4"
default-index -1
trigger "user"
display-type "link"
display-values "Skin1,Skin2,Skin3,Skin"
}

As you can see, the comma-separated numbers in the “values” tag indicate the index in the texture-group asset to find the texture; here are the first few lines for that. Texture indexes 0, 1, 2, and 3 are referenced for the albedo texture types, since we have 4 weathering types.

kuid <kuid2:661805:500009:0>
username "BR GrainHop Texture Group"
kind "texture-group"
trainz-build 5.0
category-class "JO"
author "dundun92"
contact-email "jbvector93@outlook.com"
description "A texture group for my GrainHop wagons"
textures
{
0 "270cgo/0albedo.texture"
1 "270cgo/1albedo.texture"
2 "270cgo/2albedo.texture"
3 "270cgo/2albedo.texture"
4 "270cgo/0parameter.texture"
5 "270cgo/1parameter.texture"
6 "270cgo/2parameter.texture"
.........
}

We specified the texture-group library in the kuid table, and referenced it in the “asset” tag.
kuid-table
{
acslib <kuid2:60850:89100>
meshlib <kuid2:661805:500002>
texturelib <kuid2:661805:500009>
lamp <kuid2:661805:500003>
enginespec <kuid2:368699:50064>
bogie <kuid2:661805:400003>
}

And then we specified the effect we wanted to change, (currently just the texture-albedo), inside the “effects” tag (this is not the effects tag below in this mesh table asset, but rather the one in the browser-properties at the top of this section!).
body
{
mesh "mesh/body.lm"
auto-create 1
att-parent "default"
effects
{
texture-albedo
{
kind "texture-replacement"
texture "covhopp-1_albedo.texture"
}
texture-normal
{
kind "texture-replacement"
texture "covhopp-1_normal.texture"
}
texture-parameter
{
kind "texture-replacement"
texture "covhopp-1_parameter.texture"
}
}
}

But say you want to replace the normal map as well. You would probably just create another browser property and specify the proper index for the normals.

0
{
enabled 1
property-visibility 1
name "Skin: "
property-id "p_skin_parameter"
description "Sets The Paramenter Texture"
kind "fx-replacement"
fx-replacement-type "texture-replacement"
effects "texture-albedo"
asset "texturelib"
values "1,2,3,4"
default-index -1
trigger "user"
display-type "link"
display-values "Skin1,Skin2,Skin3,Skin4"
}
1
{
enabled 1
property-visibility 1
name "Skin: "
property-id "p_skin_normal"
description "Sets The Normal Texture"
kind "fx-replacement"
fx-replacement-type "texture-replacement"
effects "texture-normal"
asset "texturelib"
values "7,8,9,10"
default-index -1
trigger "user"
display-type "link"
display-values "Skin1,Skin2,Skin3,Skin4"
}

But we can't forget the parameter map… that will require a third property. What's worse, we will now have three different properties in the view details page that will each have to be clicked on to change each map! Assigning properties this way can get tedious and create extra clutter in the config. Thankfully, for properties that share the same kind and type, it can all be done in a single property using semicolons:

0
{
enabled 1
property-visibility 1
name "Skin: "
property-id "p_skin"
description "Sets the weathering type"
kind "fx-replacement"
fx-replacement-type "texture-replacement"
meshes "null"
<b>effects "texture-albedo,texture-parameter,texture-normal"</b>
asset "texturelib"
files-path "null"
<b>values "0;4;8,1;5;9,2;6;10,3;7;11"</b>
default-index -1
trigger "user"
display-type "link"
<b>display-values "Clean,Weathered,Dirty,Rusty"</b>
}

Take note of the three tag entries above: the <b>effects</b>, <b>values</b> and <b>display-values</b> tags. The <b>display-values</b> tag is what the user sees and can choose from. Our interest is in the remaining two tags as shown below:

effects "texture-albedo,texture-parameter,texture-normal"
values "0;4;8,1;5;9,2;6;9,3;7;11"

There are four user options and, since each option requires three textures, the total number of textures is 12. The <b>values</b> tag contains a string of four groups of texture numbers separated by a comma. Within each texture group the texture numbers are delimited by a semi colon.

To clarify, we can list the three textures associated with each user choice:

0;4;8 -> Clean
1;5;9 -> Weathered
2;6;10 -> Dirty
3;7;11 -> Rusty

The first column of 0,1,2,3 identify the albedo textures. The second column of 4,5,6,7 identify the parameters textures, The third column of 8,9,10,11 identify the normal textures. Note that the numbers do not need to be in sequence or even consecutive. All those numbers do is to identify the correct texture in the texture-group asset.

This system works for other kinds of properties, too. In this case, we are setting the animation frame of both the handbrake-lever, and braking system at the same time using the same property (triggered by the same event).

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"
}

</td></tr></table>


<table width=1200><tr><td>
== Naming ACS mesh-table attachments ==
Please refer to this page on the ACS coupling system for setting up the “active-coupling-standard-60850” extensions container (which will be required for the ACS coupling to work): [[ACS_Coupling_System|ACS Coupling System]]

These are the mesh-table naming conventions you must use for the beginning of the name of each ACS attachment mesh. The others will vary depending on the “animated” property above. <b>You must spell them exactly as shown below</b>.

*coupler
*gangway
*airbrake
*vacbrake
*multiworking
*heating
*rch

If the “animated” tag in the acs container (see [[HowTo/WagonX_-_Technical_Reference#ACS|acs]]) is set to 1, then the naming is quite simple. It's one of the 7 callbacks above + a dash + “<i>front</i>” or “<i>back</i>”. The anim tag must be present to specify the animation for it. Frame 0 is the uncoupled state, and the last frame is the coupled state. This setup is shown below:

coupler-front
{
mesh-asset <kuid2:661805:500002>
mesh "coupler-screwlink-animated.lm"
anim "coupler-screwlink-animated_scene.kin"
auto-create 1
att "a.couple0"
att-parent "default"
}
coupler-back
{
mesh-asset <kuid2:661805:500002>
mesh "coupler-screwlink-animated.lm"
anim "coupler-screwlink-animated_scene.kin"
auto-create 1
att "a.couple1"
att-parent "default"
}
vacbrake-front
{
mesh-asset <kuid2:661805:500002>
mesh "vacbrake-single-animated.lm"
anim "vacbrake-single-animated_scene.kin"
auto-create 1
att "a.couple0"
att-parent "default"
}
vacbrake-back
{
mesh-asset <kuid2:661805:500002>
mesh "vacbrake-single-animated.lm"
anim "vacbrake-single-animated_scene.kin"
auto-create 1
att "a.couple1"
att-parent "default"
}

If, however, you do not want to use animations, but want to use separate meshes for each state (coupled and uncoupled), it gets a bit more complicated. The naming will follow the same as above at first, but you must add a third piece to it to specify the exact type of ACS attachment this is. The information on what to put there is originally from the [[ACS_Coupling_SystemACS Coupling System|ACS page]], but the 7 callbacks have been added plus the sub-callback here to make it easier (the third callback options are the ones with a delta symbol Δ ). And for the uncoupled state, the third callback is “non” (e.g. coupler-front-screwlink, and coupler-front-none).

*coupler
:*front/back
::Δ "<b>hook</b>" -- connects to screwlink/instanter/3link/hst-emergency-bar.
::Δ "<b>3link</b>" -- connects to hook.
::Δ "<b>instanter</b>" -- connects to hook.
::Δ "<b>screwlink</b>" -- connects to hook.
::Δ "<b>hst-emergency-bar</b>" -- connects to hook.
::Δ "<b>bar-full</b>" -- connects to "bar-none". Half of a handed pair for when one vehicle has the entire bar coupling.
::Δ "<b>bar-none</b>" -- connected to by "bar-full". The other half of the handed pair.
::Δ "<b>bar</b>" -- connects to self only. Used when both vehicles have half the bar coupling.
::Δ "<b>knuckle</b>" - standard knuckle coupler.
::Δ "<b>tightlock</b>" -- different from a standard knuckle, refers to a knuckle style coupler often fitted to multiple unit trains that also include electrical connections.
::Δ "<b>wedgelock</b>" -- London Underground coupler.
::Δ "<b>bsi</b>" -- Found on Sprinter DMUs and derived designs.
::Δ "<b>dellner</b>" -- Also compatible with Scharfenberg coupling.
::Δ "<b>scharfenberg</b>" -- Also compatible with dellner coupling.
::Δ "(<b>other string identifier</b>)" -- Any string that is not recognized from the above list is assumed to be a symmetrical meet-in-the-middle type of coupler.
::Δ “<b>none</b>”
::Examples: <b>coupler-front-instanter</b>, coupler-back-none

*gangway
:*front/back
::Δ <b>rubbing-plate</b>
::Δ <b>gangway</b>
::Δ <b>none</b>
::Example: <b>gangway-front-gangway</b>

*airbrake
:*front/back
::Δ <b>twin</b>
::Δ <b>single</b>
::Δ <b>none</b>
::Example: <b>airbrake-back-none</b>

*vacbrake
:*front/back
::Δ <b>twin</b>
::Δ <b>single</b>
::Δ <b>high</b>
::Δ <b>none</b>
::Example: <b>vacbrake-back-twin</b>

*multiworking
::front/back
::Δ "(color)-(shape)" -- e.g. "<b>blue-star</b>" or "<b>red-diamond</b>", etc
::Δ "<b>AAR</b>" -- as used on GM locos
::Δ "<b>SR27</b>" -- bagpipes
::Δ "(other identifier string e.g. classname)"
::Example: <b>multiworking-front-blue-square</b>

*heating
::front/back
::Δ "<b>none</b>"
::Δ "<b>steam</b>"
::Δ "<b>electric</b>"
::Δ "<b>dual</b>"
::Δ "<b>southern-electric</b>"
::Example: <b>heating-back-steam</b>

*rch
::front/back
::Δ "<b>high</b>"
::Δ "<b>low</b>"
::Δ "<b>none</b>"
::Example: <b>rch-back-high</b>

And an example how it would look inside a config.txt. The back attachments have been omitted for brevity.

coupler-front-screwlink
{
mesh-asset <kuid2:661805:500002>
mesh "coupler-screwlink-coupled.lm"
auto-create 1
att "a.couple0"
att-parent "default"
}
coupler-front-none
{
mesh-asset <kuid2:661805:500002>
mesh "coupler-screwlink-retracted.lm"
auto-create 1
att "a.couple0"
att-parent "default"
}
vacbrake-front-single
{
mesh-asset <kuid2:661805:500002>
mesh "vacbrake-single-coupled.lm"
auto-create 1
att "a.couple0"
att-parent "default"
}
vacbrake-front-none
{
mesh-asset <kuid2:661805:500002>
mesh "vacbrake-single-retracted.lm"
auto-create 1
att "a.couple0"
att-parent "default"
}

<table width=1200>
=Copyright Notice=
Much of the content on this page and child pages was derived from Dundun92's original Google Docs document. Permission was granted to use that information here.
</table>

HowTo/WagonX - Technical Reference

2024-02-23T05:02:46Z

Pcas1986: /* default-index */ added a warning about setting a default value.

= Document Structure =
<table width=1200>
<tr><td>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 listed below:
</td></tr>
</table>
# [[HowTo/Use the WagonX Library]]<br>
# [[HowTo/WagonX - Browser Properties Examples and Basic Tutorials]]<br>
# [[HowTo/WagonX - Traincar Tutorial]]<br>
# [[HowTo/WagonX - Locomotive Tutorial]]<br>
<br>

__TOC__

= The WagonX Reference =
<table width=1200>
<tr><td>This page contains details of the WagonX extension container and sub-containers. Practical examples of usage can be found in the tutorials listed above.
</td></tr>
</table>
<br>
= Restricted Characters =
<table width=1200>
<tr valign="top">
<td>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. Tutorial sections give examples of use. See also [[HowTo/WagonX - Technical Reference#display-values|display-values]].
</td>
</tr>

<tr>
<td>
*Comma ( , )
*Semicolon ( ; )
*Backtick ( ` )
*Colon ( : )
</td>
</tr>
</table>
<br>
= General Layout =
<table width=1200>
<tr valign="top">
<td>WagonX config tags are defined in the extensions container along with other extensions such as ACS Lib. The general layout of the extensions container that also includes ACS Lib might look like this:
</td>
</tr>
<tr><td>
extensions
{
max_permitted_speed-60850 "50mph"
active-coupling-standard-60850
{
...
}
wagon-x
{
...
}
}
</td></tr>
</table>
<br>

= WagonX Properties =
<table width=1200>
<tr valign="top">
<td>There are currently three standard or "top level" WagonX containers that define properties for Marker Lights, 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.
</td>
</tr>
</table>
== ACS ==

<table width=1200>
For help on creating the acs extensions and setting up the acs mesh-table objects, see [[HowTo/WagonX_-_Browser_Properties_Examples_and_Basic_Tutorials#Naming_ACS_mesh-table_attachments|Naming ACS mesh-table attachments]].
<br>
Each tag is shown here with sample values. There are no default values.
<tr><td>
acs
{
animated 1
use-jbv-animation 1
duration 1.0
}

*<b>animated (1 = true, 0=false)</b>
:This determines whether to use animations to move between the coupled and uncoupled state, or use individual static assets for each state.
*<b>use-jbv-animation (1 = true, 0=false)</b>
: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.
*<b>duration (a floating point value)</b>
: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)
</td></tr>
</table> 
<br>

== Misc ==

<table width=1200>

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.
<tr><td>
misc
{
begin-load-time 5.0
begin-unload-time 5.0
end-load-time 1.0
end-unload-time 1.0
}

*<b>begin-load-time (a floating point value)</b>
:The time it takes for the wagon to load at an industry
*<b>begin-unload-time (a floating point value)</b>
:The time it takes for the wagon to unloading at an industry
*<b>end-load-time (a floating point value)</b>
:The time it takes for the wagon end loading at an industry
*<b>end-unload-time (a floating point value)</b>
:The time it takes for the wagon to end unloading at an industry
</td></tr>
</table>


== Marker-Lights ==

<table width=1200>
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.
<tr><td>
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"
}
}
}

*<b>enabled (1 = true, 0=false)</b>
:Whether or not the marker lights are active on this asset.
*<b>car-minimum-count (an integer number)</b>
:The minimum number of cars that must be present in the consist for the marker-lights to activate.
*<b>require-locomotive (1 = true, 0=false)</b>
:If set to 1, a traincar of Class locomotive will need to be present in the consist for the marker-lights to activate.
*<b>night-only (1 = true, 0=false)</b>
:If set to 1, the lamps will only be visible at night, otherwise they will be displayed 24/7.
*<b>Front/back head/tail containers</b>
:These containers identify the mesh to use for the front, back, head, and tail lamps. These meshes must be in the config mesh-table.
</td></tr></table>


== Browser-Properties ==

<table width=1200>
<tr><td>
*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,
</td></tr>

<tr><td>
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"
}
}
</td></tr>
</table>

<table width=1200><tr><td>
===Supported Tags===
Tag explanations. Some examples are included in the definition and, for others, see above for sample of usage.
</td></tr></table>

<table width=1200><tr><td>
====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.
</td></tr></table>

<table width=1200><tr><td>
====property-visibility====
:Type: Integer - (0 = Hidden, 1 = Visible, 2 = Surveyor Only, 3 = Driver Only)
:Compulsory: No
:Default: 0 (hidden)
:Desc: Indicates whether the property will be visible in the Properties Browser and in what mode.
</td></tr></table>

<table width=1200><tr><td>
====name====
:Type: String
:Compulsory: Yes
:Default: None
:Desc: The display name of this property, as will appear on the properties page.
</td></tr></table>

<table width=1200><tr><td>
====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"
</td></tr></table>

<table width=1200><tr><td>
====property-id====
:Type: String
:Compulsory: Yes
:Default: None
:Desc: The formal name (ID) of this property, used to identify and change this property. For example, If the name is <b>Workflow</b>, it might be a good idea to call this <b>p_workflow</b>. <div style="color: #ff0080">This must be unique for each browser-property</div>.
</td></tr></table>

<table width=1200><tr><td>
====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 [[HowTo/WagonX - Technical Reference#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.
</td></tr></table>

<table width=1200><tr><td>
====property-sync-id====
:Type: String
:Compulsory: No
:Default: None
:Desc: The ID that determines which assets will be affected when consist-property-sync is activated. Only assets that share this ID will be synced in the consist, so be sure to make it particular and unique.
:Example: property-sync-id "soundBell"
</td></tr></table>

<table width=1200><tr><td>
====description====
:Type: String
:Compulsory: No
:Default: None
:Desc: The description of this attachment as it will appear in the Properties Browser.
</td></tr></table>

<table width=1200><tr><td>
====kind====
:Type: String
:Compulsory: No
:Default: None
:Desc: The type of property this will be. Can be one of the options below. Most of these are derived from [[Class MeshObject|Class_MeshObject]]. For more info on implementing these, see [[HowTo/WagonX - Technical Reference#values]].
::*mesh-attachment
:::Manipulate the mesh’s animation, position, visibility, etc. See mesh-attachment-type.
::*fx-replacement
:::Change an effect in the mesh. See [[HowTo/WagonX - Technical Reference#fx-replacement-type]].
::*particle-effect
:::Activate/Deactivate/Edit a particle effect (smoke0, smoke1, etc). See [[HowTo/WagonX - Technical Reference#particle-effects]] and [[HowTo/WagonX - Technical Reference#particle-effect-type]].
::*sound-script
:::Used to play a sound-script sound within this asset. See [[HowTo/WagonX - Technical Reference#sound-triggers]].
::*config-edit
:::Used to edit a tag in the wagon-x config soup. See paths.

====particle-effect-type====
:Type: String (kind mesh-attachment only)
:Compulsory: No
:Default: None
:Desc: The type of PFX function this property will be if the [[HowTo/WagonX - Technical Reference#kind]] tag is set to particle-effect. Each one is hyperlinked to the corresponding trainzscript function, though it is not necessary to know them. See [[HowTo/WagonX - Technical Reference#values]] for instructions on how to implement these properties. Currently, only pfx-message is supported.
:Example: kind "particle-effect"
: particle-effect-type "pfx-message"
::*[[pfx_Message|<span style="color: #0080ff">pfx-message</span>]]
:::Send a message to enable/disable a particle effect.
</td></tr></table>

<table width=1200><tr><td>

====mesh-attachment-type====
:Type: String - (kind mesh-attachment only)
:Example: kind "mesh-attachment"
:: mesh-attachment-type "mesh-animation-frame"
:Compulsory: No
:Default: None
:Desc: The type of mesh property this property will be if the kind tag is set to mesh-attachment. Each one is hyperlinked to the corresponding trainzscript function, though it is not necessary to know them. See values for instructions on how to implement these properties.
::*[[Class_MeshObject#SetMeshVisible|<span style="color: #0080ff">mesh-toggle</span>]]
:::Toggle between the mesh(s) being visible or hidden.
::*[[Class_MeshObject#SetMeshOrientation|<span style="color: #0080ff">mesh-translation-orientation</span>]]
:::Sets the translation and orientation of the mesh(es)
::*[[Class_MeshObject#SetMeshAnimationFrame|<span style="color: #0080ff">mesh-animation-frame</span>]]
:::Sets the frame(s) the meshes animation will move between. Useful for door opening and closing animations, or animations that require more than 2 states.
::*[[Class_MeshObject#StartMeshAnimationLoop|<span style="color: #0080ff">mesh-animation-loop</span>]]
:::Start or stop an animation-loop on the mesh.
::*[[Class_MeshObject#SetMeshAnimationState|<span style="color: #0080ff">mesh-animation-state</span>]]
:::Sets the state of the mesh(s) animation.
::*[[Class_MeshObject#SetMeshAnimationSpeed|<span style="color: #0080ff">mesh-animation-speed</span>]]
:::Changes the speed of the meshes animation.

</td></tr></table>

<table width=1200><tr><td>

====fx-replacement-type====
:Type: String)(kind fx-replacement only)
:Example: kind "fx-replacement"
:::fx-replacement-type "texture-replacement"
:Compulsory: No
:Default: None
:Desc: The type of fx replacement effect this property will be if the [[HowTo/WagonX - Technical Reference#kind]] tag is set to fx-replacement. Each one is hyperlinked to the corresponding trainzscript function, though it is not necessary to know them. See [[HowTo/WagonX - Technical Reference#values]] for instructions on how to implement these properties.
::*[[Class_MeshObject#SetFXTextureReplacement|<span style="color: #0080ff">texture-replacement</span>]]
:::Replaces a texture effect in this asset to one within a texture-group asset.
::*[[Class_MeshObject#SetFXTextureReplacementTexture|<span style="color: #0080ff">texture-replacement-texture</span>]]
:::Replaces a texture effect in this asset to one located within this asset.
::*[[Class_MeshObject#SetFXCoronaTexture|<span style="color: #0080ff">corona</span>]]
:::Replaces a corona effect in the asset.
::*[[Class_MeshObject#SetFXNameText|<span style="color: #0080ff">name</span>]]
:::Replaces a name effect in the asset.
::*[[Class_MeshObject#SetFXAttachment|<span style="color: #0080ff">attachment</span>]]
:::Replaces an attachment effect in the asset.
::*[[Class_MeshObject#SetFXAnimationState|<span style="color: #0080ff">animation</span>]]
:::Plays/Stops an animation effect in the asset.

</td></tr></table>

<table width=1200><tr><td>

====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. <b>(There may be issues with using this tag with mesh-toggle.)</b>
:Example: duration 3.2

</td></tr></table>

<table width=1200><tr><td>

====meshes====
:Type: String - (a list of mesh names from the mesh-table separated by commas)
:Example: meshes "handbrake-lever,braking-system"
:Compulsory: No
:Default: None
:Desc: The comma-separated mesh-table asset(s) to be modified by the property. Use this for [[HowTo/WagonX - Technical Reference#kind]] mesh-toggle or kind mesh-animation. Use this tag, the effect tag, or the asset tag, but not more than one.

</td></tr></table>

<table width=1200><tr><td>

====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 [[HowTo/WagonX - Technical Reference#kind]] fx-replacement. Use this tag, the mesh tag, or the asset tag, but not more than one.

</td></tr></table>

<table width=1200><tr><td>

====particle-effects====
:Type: String - (a list of integer numbers as a string)
:Example: particle-effects "0,1"
:Compulsory: No
:Default: None
:Desc: For kind particle-effect. The comma-separated list of PFX effects to be modified by the property. See kind for help on implementation. <b>There is currently no use for this tag as of yet. pfx-message doesn't need this because everything is already specified in the values tag.</b>

</td></tr></table>

<table width=1200><tr><td>

====target-asset====
:Type: String
:Example: target-asset "bogey-0"
:Compulsory: No
:Default: None
:Desc: This determines which assets config this property will manipulate. This tag is currently only used for manipulating a vehicles bogey (e.g. texture replacement). The name must be “bogey-” + the index of the bogey to edit. This gives you full access to the bogeys mesh-table, allowing you to set texture replacements, mesh toggles, and other properties within the bogey. This tag can be omitted if you are not doing bogey texture replacements. <b>Only properties of kind “mesh-attachment” or “fx-replacement” can be used for properties that use this tag.</b>

</td></tr></table>

<table width=1200><tr><td>

====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 outside of this, such as a texture-replacement library. Use this tag, the [[HowTo/WagonX - Technical Reference#effects]] tag, the [[HowTo/WagonX - Technical Reference#meshes]] tag, or the [[HowTo/WagonX - Technical Reference#particle-effects]] tag, but not more than one.

</td></tr></table>

<table width=1200><tr><td>

====files-path====
:Type: String - (a list of two strings)
:Example: files-path "images/,.texture"
:Compulsory: No
:Default: None
:Desc: 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. <b>files-path “images/left/.texture”</b>), where images/left is the path, and .texture is the extension for all the files.

</td></tr></table>

<table width=1200><tr><td>


====paths====
:Type: String - (a list of two strings)
:Example: paths "marker-lights/night-only""
:Compulsory: Yes
:Default: None
:Desc: For kind config-edit. A comma-separated list of paths that point to the tag in the wagon-x config to edit.

</td></tr></table>

<table width=1200><tr><td>

====values====
:Type: String - (a string list separated by special characters)
:Example1 values "0,15,30"
:Compulsory: No
:Default: None
:Desc: A comma-separated (and optionally semicolon-separated) list of all the files/values to be switched between. If the files-path tag is used, only include each file’s name (exclude the path and extension). This tag is required for all properties. If it is not wanted, leave the value at “1”, but keep the tag still. For booleans, use 1 for true, and 0 for false. For animations, specify the animation frames you want to toggle through. For details on using the semicolon separator to shorten properties, see [[HowTo/WagonX - Browser Properties Examples and Basic Tutorials#Using Semicolons to set multiple values in one property]].
:<b>Each kind has its own rules for what to put here, explained below. See the [[HowTo/WagonX - Technical Reference#kind]] property for more info on these.</b>

:::*For kind mesh-attachment:
::::*For mesh-attachment-type mesh-toggle, the value must be either 0 or 1 (visible/hidden) ???
::::*For mesh-attachment-type mesh-translation-orientation, the value must be a 3-dimensional vector with values separated by backticks, enclosed with round brackets for the translation, followed by a colon, then another round bracket-enclosed 3d vector for the orientation, as shown below. 0`2`4 is the translation, and 1.2`2`2 is the orientation (we have to use backticks because the comma is already used here for separating each index value).
::::Example: values "(0`2`4):(1.2`2`2),(0`0`0):(0`0`0)"

:::*For mesh-attachment-type mesh-animation-speed, the value is the speed of the animation for that index
:::*For mesh-attachment-type mesh-animation-loop, the value will be an integer bool (0 or 1) to indicate whether to start the loop, or stop it. You can create a separate property that controls the mesh-animation-speed, and link it via a [[HowTo/WagonX - Technical Reference#child-properties]] property to control the speed of the loop.
:::*For mesh-attachment type mesh-animation-frame, the value is the frame of the animation to jump to. Setting it to -1 will put that index at the last animation frame in the mesh (see [[Class_MeshObject#GetMeshAnimationFrameCount|<span style="color: #0080ff">GetMeshAnimationFrameCount</span>]]).
::::Example: values "0,30"
:::*For mesh-attachment-type mesh-animation-loop, the value can be 0 or 1, to start/stop the loop

:::*For kind sound-script, the value can be 0 or 1, to start/stop the soundscript event

:::*For kind config-edit, the value is a string indicating the string value to assign to the config tag.

:::*For kind particle-effect:
:::*For particle-effect-type pfx-message, the value follows the same rules for [[pfx message|<span style="color: #0080ff">pfx messages</span>]].
::::*particle-effect-type "pfx-message"
::::Example: values "+0+1,-1-0"

:::*For kind fx-replacement:
::::*For fx-replacement-type texture-replacement, the comma and/or. semicolon-separated values represent the index in the texture-group asset to find the texture. Setting the first value to 1 will reference the texture index 1, shown in the partial config for a textures asset below:
::::Values “0,2,1” will reference the textures in the texture container at indexes 0, 2, and 1, in that order when cycled through.
::::Example: values “0,2,1”

kuid <kuid:1234:123456>
username "test texture group asset"
trainz-build 4.6
description "test texture group"
textures
{
0 "textures\0albedo.texture"
1 "textures\1albedo.texture"
2 "textures\2albedo.texture"
3 "textures\0parameter.texture"
4 "textures\1parameter.texture"
5 "textures\2parameter.texture"
6 "textures\0normal.texture"
7 "textures\1normal.texture"
8 "textures\2normal.texture"
}

::::*For fx-replacement-type texture-replacement-texture, the comma and/or semicolon-separated values are the names of the files (ideally without the path or extension) to be referenced at that index.
::::Example: values "images/congleton.texture,images/burntisland.texture,images/buxton.texture,images/none.texture"
::::If you have the same path (and same extension) for all your files, you can greatly reduce the clutter by just specifying the path and extension once using the files-path tag. So, in this case the values entry would be:
::::Example: values "congleton,burntisland,buxton,none"

0
{
enabled 1
property-visibility 1
name "Workflow Text: "
property-id "p_workflow"
description "Sets the Workflow"
kind "fx-replacement"
fx-replacement-type "texture-replacement-texture"
consist-property-sync 1
meshes "null"
effects "texture-extra"
asset "null"
files-path "images/,.texture"
values "congleton,burntisland,buxton,none"
default-index 0
trigger "user"
display-type "list"
display-values "Congleton,Burntisland,Buxton,None"
}

::::*For fx-replacement-type attachment, the values are the names of the attachment effects to be replaced by the specified [[HowTo/WagonX - Technical Reference#asset]].
::::*For fx-replacement-type corona, the values are the names of the corona effects to be replaced by the specified [[HowTo/WagonX - Technical Reference#asset]].
::::*For fx-replacement-type animation, the values are the names of the animation effects to be replaced by the specified [[HowTo/WagonX - Technical Reference#asset]].
::::*For fx-replacement-type name, the values are the names that will replace the current name of the specified name effect.

</td></tr></table>

<table width=1200><tr><td>

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

</td></tr></table>

<table width=1200><tr><td>


====sound-triggers====
:Type: String - (a list of strings)
:Example: sound-triggers "bell_1,bell_2"
:Compulsory: No
:Default: None
:Desc: For kind sound-script only. This specifies the soundscript trigger(s) (comma separated) that this property will start/stop when the property is activated.

</td></tr></table>

<table width=1200><tr><td>

====trigger====
:Type: String
:Example: trigger "user"
:Compulsory: No
:Default: Null (ignored)
:Desc: The event that will trigger/activate this property. Can be either an external event, such as a coal-loading animation, or a user-controlled event, or both. Setting it to none is useful if this is a [[HowTo/WagonX - Technical Reference#child-properties]] property of another property. Possible values are:
:::*user
:::*event
:::*both
:::*none

</td></tr></table>

<table width=1200><tr><td>

====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
:::*handbrake-apply/handbrake-release
:::*trainbrake-apply/trainbrake-release
:::*headlight-on, headlight-off
:::*horn
:::*bell
:::*sanding
:::*pantograph-state-0/1/2/3 (see [[Class_Train#GetPantographState|<span style="color: #0080ff">GetPantographState</span>]])
:::*weather-0/1/2/3/4/5/6/7 (see [[Class_World#GetWeatherType|<span style="color: #0080ff">GetWeatherType</span>]])
:::*world-day/world-night
:::*queue-(0 - ?)- loaded/empty (e.g. <b>queue-0-loaded, queue-1-empty</b>)

</td></tr></table>

<table width=1200><tr><td>

: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. <b>For trainzbuild 5.1 and 5.0, only link is supported for the View Details page.</b> 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

</td></tr></table>

<table width=1200><tr><td>

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

</td></tr></table>

<table width=1200>
=Copyright Notice=
Much of the content on this page and child pages was derived from Dundun92's original Google Docs document. Permission was granted to use that information here.
</table>

HowTo/WagonX - Technical Reference

2024-02-21T05:01:57Z

Pcas1986: Corrected some broken links

= Document Structure =
<table width=1200>
<tr><td>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 listed below:
</td></tr>
</table>
# [[HowTo/Use the WagonX Library]]<br>
# [[HowTo/WagonX - Browser Properties Examples and Basic Tutorials]]<br>
# [[HowTo/WagonX - Traincar Tutorial]]<br>
# [[HowTo/WagonX - Locomotive Tutorial]]<br>
<br>

__TOC__

= The WagonX Reference =
<table width=1200>
<tr><td>This page contains details of the WagonX extension container and sub-containers. Practical examples of usage can be found in the tutorials listed above.
</td></tr>
</table>
<br>
= Restricted Characters =
<table width=1200>
<tr valign="top">
<td>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. Tutorial sections give examples of use. See also [[HowTo/WagonX - Technical Reference#display-values|display-values]].
</td>
</tr>

<tr>
<td>
*Comma ( , )
*Semicolon ( ; )
*Backtick ( ` )
*Colon ( : )
</td>
</tr>
</table>
<br>
= General Layout =
<table width=1200>
<tr valign="top">
<td>WagonX config tags are defined in the extensions container along with other extensions such as ACS Lib. The general layout of the extensions container that also includes ACS Lib might look like this:
</td>
</tr>
<tr><td>
extensions
{
max_permitted_speed-60850 "50mph"
active-coupling-standard-60850
{
...
}
wagon-x
{
...
}
}
</td></tr>
</table>
<br>

= WagonX Properties =
<table width=1200>
<tr valign="top">
<td>There are currently three standard or "top level" WagonX containers that define properties for Marker Lights, 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.
</td>
</tr>
</table>
== ACS ==

<table width=1200>
For help on creating the acs extensions and setting up the acs mesh-table objects, see [[HowTo/WagonX_-_Browser_Properties_Examples_and_Basic_Tutorials#Naming_ACS_mesh-table_attachments|Naming ACS mesh-table attachments]].
<br>
Each tag is shown here with sample values. There are no default values.
<tr><td>
acs
{
animated 1
use-jbv-animation 1
duration 1.0
}

*<b>animated (1 = true, 0=false)</b>
:This determines whether to use animations to move between the coupled and uncoupled state, or use individual static assets for each state.
*<b>use-jbv-animation (1 = true, 0=false)</b>
: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.
*<b>duration (a floating point value)</b>
: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)
</td></tr>
</table> 
<br>

== Misc ==

<table width=1200>

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.
<tr><td>
misc
{
begin-load-time 5.0
begin-unload-time 5.0
end-load-time 1.0
end-unload-time 1.0
}

*<b>begin-load-time (a floating point value)</b>
:The time it takes for the wagon to load at an industry
*<b>begin-unload-time (a floating point value)</b>
:The time it takes for the wagon to unloading at an industry
*<b>end-load-time (a floating point value)</b>
:The time it takes for the wagon end loading at an industry
*<b>end-unload-time (a floating point value)</b>
:The time it takes for the wagon to end unloading at an industry
</td></tr>
</table>


== Marker-Lights ==

<table width=1200>
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.
<tr><td>
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"
}
}
}

*<b>enabled (1 = true, 0=false)</b>
:Whether or not the marker lights are active on this asset.
*<b>car-minimum-count (an integer number)</b>
:The minimum number of cars that must be present in the consist for the marker-lights to activate.
*<b>require-locomotive (1 = true, 0=false)</b>
:If set to 1, a traincar of Class locomotive will need to be present in the consist for the marker-lights to activate.
*<b>night-only (1 = true, 0=false)</b>
:If set to 1, the lamps will only be visible at night, otherwise they will be displayed 24/7.
*<b>Front/back head/tail containers</b>
:These containers identify the mesh to use for the front, back, head, and tail lamps. These meshes must be in the config mesh-table.
</td></tr></table>


== Browser-Properties ==

<table width=1200>
<tr><td>
*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,
</td></tr>

<tr><td>
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"
}
}
</td></tr>
</table>

<table width=1200><tr><td>
===Supported Tags===
Tag explanations. Some examples are included in the definition and, for others, see above for sample of usage.
</td></tr></table>

<table width=1200><tr><td>
====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.
</td></tr></table>

<table width=1200><tr><td>
====property-visibility====
:Type: Integer - (0 = Hidden, 1 = Visible, 2 = Surveyor Only, 3 = Driver Only)
:Compulsory: No
:Default: 0 (hidden)
:Desc: Indicates whether the property will be visible in the Properties Browser and in what mode.
</td></tr></table>

<table width=1200><tr><td>
====name====
:Type: String
:Compulsory: Yes
:Default: None
:Desc: The display name of this property, as will appear on the properties page.
</td></tr></table>

<table width=1200><tr><td>
====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"
</td></tr></table>

<table width=1200><tr><td>
====property-id====
:Type: String
:Compulsory: Yes
:Default: None
:Desc: The formal name (ID) of this property, used to identify and change this property. For example, If the name is <b>Workflow</b>, it might be a good idea to call this <b>p_workflow</b>. <div style="color: #ff0080">This must be unique for each browser-property</div>.
</td></tr></table>

<table width=1200><tr><td>
====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 [[HowTo/WagonX - Technical Reference#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.
</td></tr></table>

<table width=1200><tr><td>
====property-sync-id====
:Type: String
:Compulsory: No
:Default: None
:Desc: The ID that determines which assets will be affected when consist-property-sync is activated. Only assets that share this ID will be synced in the consist, so be sure to make it particular and unique.
:Example: property-sync-id "soundBell"
</td></tr></table>

<table width=1200><tr><td>
====description====
:Type: String
:Compulsory: No
:Default: None
:Desc: The description of this attachment as it will appear in the Properties Browser.
</td></tr></table>

<table width=1200><tr><td>
====kind====
:Type: String
:Compulsory: No
:Default: None
:Desc: The type of property this will be. Can be one of the options below. Most of these are derived from [[Class MeshObject|Class_MeshObject]]. For more info on implementing these, see [[HowTo/WagonX - Technical Reference#values]].
::*mesh-attachment
:::Manipulate the mesh’s animation, position, visibility, etc. See mesh-attachment-type.
::*fx-replacement
:::Change an effect in the mesh. See [[HowTo/WagonX - Technical Reference#fx-replacement-type]].
::*particle-effect
:::Activate/Deactivate/Edit a particle effect (smoke0, smoke1, etc). See [[HowTo/WagonX - Technical Reference#particle-effects]] and [[HowTo/WagonX - Technical Reference#particle-effect-type]].
::*sound-script
:::Used to play a sound-script sound within this asset. See [[HowTo/WagonX - Technical Reference#sound-triggers]].
::*config-edit
:::Used to edit a tag in the wagon-x config soup. See paths.

====particle-effect-type====
:Type: String (kind mesh-attachment only)
:Compulsory: No
:Default: None
:Desc: The type of PFX function this property will be if the [[HowTo/WagonX - Technical Reference#kind]] tag is set to particle-effect. Each one is hyperlinked to the corresponding trainzscript function, though it is not necessary to know them. See [[HowTo/WagonX - Technical Reference#values]] for instructions on how to implement these properties. Currently, only pfx-message is supported.
:Example: kind "particle-effect"
: particle-effect-type "pfx-message"
::*[[pfx_Message|<span style="color: #0080ff">pfx-message</span>]]
:::Send a message to enable/disable a particle effect.
</td></tr></table>

<table width=1200><tr><td>

====mesh-attachment-type====
:Type: String - (kind mesh-attachment only)
:Example: kind "mesh-attachment"
:: mesh-attachment-type "mesh-animation-frame"
:Compulsory: No
:Default: None
:Desc: The type of mesh property this property will be if the kind tag is set to mesh-attachment. Each one is hyperlinked to the corresponding trainzscript function, though it is not necessary to know them. See values for instructions on how to implement these properties.
::*[[Class_MeshObject#SetMeshVisible|<span style="color: #0080ff">mesh-toggle</span>]]
:::Toggle between the mesh(s) being visible or hidden.
::*[[Class_MeshObject#SetMeshOrientation|<span style="color: #0080ff">mesh-translation-orientation</span>]]
:::Sets the translation and orientation of the mesh(es)
::*[[Class_MeshObject#SetMeshAnimationFrame|<span style="color: #0080ff">mesh-animation-frame</span>]]
:::Sets the frame(s) the meshes animation will move between. Useful for door opening and closing animations, or animations that require more than 2 states.
::*[[Class_MeshObject#StartMeshAnimationLoop|<span style="color: #0080ff">mesh-animation-loop</span>]]
:::Start or stop an animation-loop on the mesh.
::*[[Class_MeshObject#SetMeshAnimationState|<span style="color: #0080ff">mesh-animation-state</span>]]
:::Sets the state of the mesh(s) animation.
::*[[Class_MeshObject#SetMeshAnimationSpeed|<span style="color: #0080ff">mesh-animation-speed</span>]]
:::Changes the speed of the meshes animation.

</td></tr></table>

<table width=1200><tr><td>

====fx-replacement-type====
:Type: String)(kind fx-replacement only)
:Example: kind "fx-replacement"
:::fx-replacement-type "texture-replacement"
:Compulsory: No
:Default: None
:Desc: The type of fx replacement effect this property will be if the [[HowTo/WagonX - Technical Reference#kind]] tag is set to fx-replacement. Each one is hyperlinked to the corresponding trainzscript function, though it is not necessary to know them. See [[HowTo/WagonX - Technical Reference#values]] for instructions on how to implement these properties.
::*[[Class_MeshObject#SetFXTextureReplacement|<span style="color: #0080ff">texture-replacement</span>]]
:::Replaces a texture effect in this asset to one within a texture-group asset.
::*[[Class_MeshObject#SetFXTextureReplacementTexture|<span style="color: #0080ff">texture-replacement-texture</span>]]
:::Replaces a texture effect in this asset to one located within this asset.
::*[[Class_MeshObject#SetFXCoronaTexture|<span style="color: #0080ff">corona</span>]]
:::Replaces a corona effect in the asset.
::*[[Class_MeshObject#SetFXNameText|<span style="color: #0080ff">name</span>]]
:::Replaces a name effect in the asset.
::*[[Class_MeshObject#SetFXAttachment|<span style="color: #0080ff">attachment</span>]]
:::Replaces an attachment effect in the asset.
::*[[Class_MeshObject#SetFXAnimationState|<span style="color: #0080ff">animation</span>]]
:::Plays/Stops an animation effect in the asset.

</td></tr></table>

<table width=1200><tr><td>

====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. <b>(There may be issues with using this tag with mesh-toggle.)</b>
:Example: duration 3.2

</td></tr></table>

<table width=1200><tr><td>

====meshes====
:Type: String - (a list of mesh names from the mesh-table separated by commas)
:Example: meshes "handbrake-lever,braking-system"
:Compulsory: No
:Default: None
:Desc: The comma-separated mesh-table asset(s) to be modified by the property. Use this for [[HowTo/WagonX - Technical Reference#kind]] mesh-toggle or kind mesh-animation. Use this tag, the effect tag, or the asset tag, but not more than one.

</td></tr></table>

<table width=1200><tr><td>

====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 [[HowTo/WagonX - Technical Reference#kind]] fx-replacement. Use this tag, the mesh tag, or the asset tag, but not more than one.

</td></tr></table>

<table width=1200><tr><td>

====particle-effects====
:Type: String - (a list of integer numbers as a string)
:Example: particle-effects "0,1"
:Compulsory: No
:Default: None
:Desc: For kind particle-effect. The comma-separated list of PFX effects to be modified by the property. See kind for help on implementation. <b>There is currently no use for this tag as of yet. pfx-message doesn't need this because everything is already specified in the values tag.</b>

</td></tr></table>

<table width=1200><tr><td>

====target-asset====
:Type: String
:Example: target-asset "bogey-0"
:Compulsory: No
:Default: None
:Desc: This determines which assets config this property will manipulate. This tag is currently only used for manipulating a vehicles bogey (e.g. texture replacement). The name must be “bogey-” + the index of the bogey to edit. This gives you full access to the bogeys mesh-table, allowing you to set texture replacements, mesh toggles, and other properties within the bogey. This tag can be omitted if you are not doing bogey texture replacements. <b>Only properties of kind “mesh-attachment” or “fx-replacement” can be used for properties that use this tag.</b>

</td></tr></table>

<table width=1200><tr><td>

====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 outside of this, such as a texture-replacement library. Use this tag, the [[HowTo/WagonX - Technical Reference#effects]] tag, the [[HowTo/WagonX - Technical Reference#meshes]] tag, or the [[HowTo/WagonX - Technical Reference#particle-effects]] tag, but not more than one.

</td></tr></table>

<table width=1200><tr><td>

====files-path====
:Type: String - (a list of two strings)
:Example: files-path "images/,.texture"
:Compulsory: No
:Default: None
:Desc: 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. <b>files-path “images/left/.texture”</b>), where images/left is the path, and .texture is the extension for all the files.

</td></tr></table>

<table width=1200><tr><td>


====paths====
:Type: String - (a list of two strings)
:Example: paths "marker-lights/night-only""
:Compulsory: Yes
:Default: None
:Desc: For kind config-edit. A comma-separated list of paths that point to the tag in the wagon-x config to edit.

</td></tr></table>

<table width=1200><tr><td>

====values====
:Type: String - (a string list separated by special characters)
:Example1 values "0,15,30"
:Compulsory: No
:Default: None
:Desc: A comma-separated (and optionally semicolon-separated) list of all the files/values to be switched between. If the files-path tag is used, only include each file’s name (exclude the path and extension). This tag is required for all properties. If it is not wanted, leave the value at “1”, but keep the tag still. For booleans, use 1 for true, and 0 for false. For animations, specify the animation frames you want to toggle through. For details on using the semicolon separator to shorten properties, see [[HowTo/WagonX - Browser Properties Examples and Basic Tutorials#Using Semicolons to set multiple values in one property]].
:<b>Each kind has its own rules for what to put here, explained below. See the [[HowTo/WagonX - Technical Reference#kind]] property for more info on these.</b>

:::*For kind mesh-attachment:
::::*For mesh-attachment-type mesh-toggle, the value must be either 0 or 1 (visible/hidden) ???
::::*For mesh-attachment-type mesh-translation-orientation, the value must be a 3-dimensional vector with values separated by backticks, enclosed with round brackets for the translation, followed by a colon, then another round bracket-enclosed 3d vector for the orientation, as shown below. 0`2`4 is the translation, and 1.2`2`2 is the orientation (we have to use backticks because the comma is already used here for separating each index value).
::::Example: values "(0`2`4):(1.2`2`2),(0`0`0):(0`0`0)"

:::*For mesh-attachment-type mesh-animation-speed, the value is the speed of the animation for that index
:::*For mesh-attachment-type mesh-animation-loop, the value will be an integer bool (0 or 1) to indicate whether to start the loop, or stop it. You can create a separate property that controls the mesh-animation-speed, and link it via a [[HowTo/WagonX - Technical Reference#child-properties]] property to control the speed of the loop.
:::*For mesh-attachment type mesh-animation-frame, the value is the frame of the animation to jump to. Setting it to -1 will put that index at the last animation frame in the mesh (see [[Class_MeshObject#GetMeshAnimationFrameCount|<span style="color: #0080ff">GetMeshAnimationFrameCount</span>]]).
::::Example: values "0,30"
:::*For mesh-attachment-type mesh-animation-loop, the value can be 0 or 1, to start/stop the loop

:::*For kind sound-script, the value can be 0 or 1, to start/stop the soundscript event

:::*For kind config-edit, the value is a string indicating the string value to assign to the config tag.

:::*For kind particle-effect:
:::*For particle-effect-type pfx-message, the value follows the same rules for [[pfx message|<span style="color: #0080ff">pfx messages</span>]].
::::*particle-effect-type "pfx-message"
::::Example: values "+0+1,-1-0"

:::*For kind fx-replacement:
::::*For fx-replacement-type texture-replacement, the comma and/or. semicolon-separated values represent the index in the texture-group asset to find the texture. Setting the first value to 1 will reference the texture index 1, shown in the partial config for a textures asset below:
::::Values “0,2,1” will reference the textures in the texture container at indexes 0, 2, and 1, in that order when cycled through.
::::Example: values “0,2,1”

kuid <kuid:1234:123456>
username "test texture group asset"
trainz-build 4.6
description "test texture group"
textures
{
0 "textures\0albedo.texture"
1 "textures\1albedo.texture"
2 "textures\2albedo.texture"
3 "textures\0parameter.texture"
4 "textures\1parameter.texture"
5 "textures\2parameter.texture"
6 "textures\0normal.texture"
7 "textures\1normal.texture"
8 "textures\2normal.texture"
}

::::*For fx-replacement-type texture-replacement-texture, the comma and/or semicolon-separated values are the names of the files (ideally without the path or extension) to be referenced at that index.
::::Example: values "images/congleton.texture,images/burntisland.texture,images/buxton.texture,images/none.texture"
::::If you have the same path (and same extension) for all your files, you can greatly reduce the clutter by just specifying the path and extension once using the files-path tag. So, in this case the values entry would be:
::::Example: values "congleton,burntisland,buxton,none"

0
{
enabled 1
property-visibility 1
name "Workflow Text: "
property-id "p_workflow"
description "Sets the Workflow"
kind "fx-replacement"
fx-replacement-type "texture-replacement-texture"
consist-property-sync 1
meshes "null"
effects "texture-extra"
asset "null"
files-path "images/,.texture"
values "congleton,burntisland,buxton,none"
default-index 0
trigger "user"
display-type "list"
display-values "Congleton,Burntisland,Buxton,None"
}

::::*For fx-replacement-type attachment, the values are the names of the attachment effects to be replaced by the specified [[HowTo/WagonX - Technical Reference#asset]].
::::*For fx-replacement-type corona, the values are the names of the corona effects to be replaced by the specified [[HowTo/WagonX - Technical Reference#asset]].
::::*For fx-replacement-type animation, the values are the names of the animation effects to be replaced by the specified [[HowTo/WagonX - Technical Reference#asset]].
::::*For fx-replacement-type name, the values are the names that will replace the current name of the specified name effect.

</td></tr></table>

<table width=1200><tr><td>

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

</td></tr></table>

<table width=1200><tr><td>

====sound-triggers====
:Type: String - (a list of strings)
:Example: sound-triggers "bell_1,bell_2"
:Compulsory: No
:Default: None
:Desc: For kind sound-script only. This specifies the soundscript trigger(s) (comma separated) that this property will start/stop when the property is activated.

</td></tr></table>

<table width=1200><tr><td>

====trigger====
:Type: String
:Example: trigger "user"
:Compulsory: No
:Default: Null (ignored)
:Desc: The event that will trigger/activate this property. Can be either an external event, such as a coal-loading animation, or a user-controlled event, or both. Setting it to none is useful if this is a [[HowTo/WagonX - Technical Reference#child-properties]] property of another property. Possible values are:
:::*user
:::*event
:::*both
:::*none

</td></tr></table>

<table width=1200><tr><td>

====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
:::*handbrake-apply/handbrake-release
:::*trainbrake-apply/trainbrake-release
:::*headlight-on, headlight-off
:::*horn
:::*bell
:::*sanding
:::*pantograph-state-0/1/2/3 (see [[Class_Train#GetPantographState|<span style="color: #0080ff">GetPantographState</span>]])
:::*weather-0/1/2/3/4/5/6/7 (see [[Class_World#GetWeatherType|<span style="color: #0080ff">GetWeatherType</span>]])
:::*world-day/world-night
:::*queue-(0 - ?)- loaded/empty (e.g. <b>queue-0-loaded, queue-1-empty</b>)

</td></tr></table>

<table width=1200><tr><td>

: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. <b>For trainzbuild 5.1 and 5.0, only link is supported for the View Details page.</b> 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

</td></tr></table>

<table width=1200><tr><td>

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

</td></tr></table>

<table width=1200>
=Copyright Notice=
Much of the content on this page and child pages was derived from Dundun92's original Google Docs document. Permission was granted to use that information here.
</table>

HowTo/WagonX - Traincar Tutorial

2024-02-20T06:33:10Z

Pcas1986: Minor format error

= Document Structure =
<table width=1200>
The WagonX Tutorial set is written over several pages. This page is a tutorial for adding WagonX capability to a passenger traincar and a goods carrying wagon. Other pages in the series are listed below:
</table>
# [[HowTo/Use the WagonX Library]]<br>
# [[HowTo/WagonX - Technical Reference]]<br>
# [[HowTo/WagonX - Browser Properties Examples and Basic Tutorials]]<br>
# [[HowTo/WagonX - Locomotive Tutorial]]<br>

__TOC__
= Adding WagonX to a Traincar =
== Setting the scene ==
A traincar can have different purposes such as a passenger vehicle such as a car or carriage, or as a wagon carrying, loading and unloading goods. WagonX can assist with both of those so two examples are included here. The first example is of a GWR carriage made by Andi Smith and repaired by the CRG. The second example will likely be a coal vehicle by Ben Dorsey. That example will follow later.
For the GWR carriage we will add the Automated Coupling System (ACS), texture swapping, and attachments that can be shown or hidden.
All of this is defined in the config.
Some of the config tag set up is rather complicated so rather than describe here the tutorial frequently refers to the [[HowTo/WagonX - Technical Reference|Technical Reference]]. It would be useful to keep a brower tab open on that page.
Mesh libraries used in these examples are available on the DLS however they may not be suitable for your application so please use whatever is appropriate for your situation.

== Setting up the config for the script, class and script-include-table ==
=== The script ===
You need a simple script called ref.gs that is in the WagonX asset. Alternatively you can easily create it yourself in any plain text editor. The contents are:

include "locowagonx.gs"
class eRef isclass WagonX {};

=== The class and script-include table ===
Include these tags in the config, where <kuid:661805:500008> is the WagonX library.

class "eRef"
script-include-table {
0 <kuid:661805:500008>
}

== Setting up the extensions container ==

The extensions container contains sub containers for ACS, if used, and WagonX. So, the general format, with no tags yet, is:

extensions {
active-coupling-standard-60850 {

}
wagon-x {

}
}

== The ACS container ==
The ACS container is fully described at [[ACS_Coupling_System]], but for our purposes we will use the following as an example. Add/change/remove as required for your vehicle.

active-coupling-standard-60850 {
version-major "2"
version-minor "0"
brakes "vac"
front {
coupler "screwlink|hook"
vacbrake "single"
heating-type "steam"
gangway "gangway"
}
back {
coupler "screwlink|hook"
vacbrake "single"
heating-type "steam"
gangway "gangway"
}

== The Wagon-X Container ==
==== The WagonX ACS sub-container ====
See the [[HowTo/WagonX_-_Technical_Reference#ACS\|WagonX ACS Technical Reference]] for details of tag usage.<br>
WagonX needs information about ACS that isn't defined in the ACS container so, within the wagon-x sub container include an acs sub container that has three tags: animate, use-jbv-animation, and duration.
Animated and use-jbv-animation are self explanatory and duration is the fade time.
extensions {
active-coupling-standard-60850 {
...
}
wagon-x
{
acs
{
animated 1
use-jbv-animation 0
duration 1.0
}
}
}

==== The Misc sub-container ====
See the [[HowTo/WagonX_-_Technical_Reference#Misc\|WagonX Misc Technical Reference]] for details of tag usage.<br>
The Misc sub-container includes times, in seconds, for loads and unloads at industries. This can be useful for effects such as smoke or dust. Since this is a passenger vehicle we will just set all values to zero.

extensions {
active-coupling-standard-60850 {
...
}
wagon-x
{
acs
{
...
}
misc {
begin-load-time 0
begin-unload-time 0
end-load-time 0
end-unload-time 0
}
}
}

==== Marker Lights ====
See the [[HowTo/WagonX_-_Technical_Reference#Marker-Lights|WagonX Marker Lights Technical Reference]] for details of tag usage.<br>
The marker-lights sub container is required even if you are not using them. If you don't need it then just set enabled to 0 and the mesh values to null.<br>
The name "front" indicates the physical front of the vehicle. i.e. where a.limfront is located. "Back" is the physical back of the vehicle.
"Head" is the direction of train travel, and "tail" is the direction from which the train has come. In other words the tail of the train. Note that Trainz always has a nominal train direction of travel even if it is stopped.<br>
If you don't need a lamp at a position then just use "null". There are some conditions on when lights are shown.<br>
The head and tail meshes are lamp meshes in the mesh-table.<br>

extensions {
active-coupling-standard-60850 {
...
}
wagon-x
{
acs
{
...
}
misc {
...
}
marker-lights {
enabled 1
car-minimum-count 2
require-locomotive 1
night-only 0
front {
head {
mesh "lamp-front-white"
}
tail {
mesh "lamp-front-red"
}
}
back {
head {
mesh "lamp-back-white"
}
tail {
mesh "lamp-back-red"
}
}
}
}
}

==== Browser-Properties ====
See the [[HowTo/WagonX_-_Technical_Reference#Browser-Properties|Browser Properties Technical Reference]] for details of tag usage.<br>
The example that follows is a relatively simple browser setup to control:
*Texture swapping
*Control of the marker lights
*Control of an interior night mesh
*Control of a "front" indicator

Each property has a number of control tags that are located in a property container and each container has a simple number id. The number of tags in a container depends on the property type. Not all properties are subject to user control and can be triggered by other events, such as changing from day to night. Each property can be disabled, however this can only be done in the config.
===== Texture Swapping =====
Texture swapping is controlled in the Properties Browser and can be configured by the user. There are six possible textures including a blank which like an underpaint coat. The default livery is number 1 which is not the first in the list as the list starts with 0 (zero).
Since the number of texture effects is 4, and the number of different textures is 6, then the values tag must contain 24 values that are indices to the actual textures in the relevant texture library.

===== Marker Lights =====
The marker lights is quite simple and just controls whether they are used only at night or also during the day as well.

===== Front Indicator =====
The front indicator is a simple tool provided by the original creator, Andi Smith, to show which end of the car is the physical front. The property is visible in the Properties Browser as a simple show or hide option.

===== Interior Lighting =====
This is an example of a property triggered by an external event. In this case changing from day to night, and night to day. WagonX intercepts the message posted on these events and that triggers a mesh swap using the event type and the values to show the correct mesh.

extensions {
active-coupling-standard-60850 {
...
}
wagon-x
{
acs
{
...
}
misc {
...
}
marker-lights {
...
}
browser-properties {
0 {
consist-property-sync 1
property-sync-id "GWRsynctexture"
enabled 1
property-visibility 1
name "Current traincar livery: "
property-id "p_livery"
description "Sets the livery for the carriage"
kind "fx-replacement"
fx-replacement-type "texture-replacement"
effects "livery-main,livery-leftdoor,livery-rightdoor,livery-crest"
asset "liveries"
values "0;0;0;0,1;1;1;5,2;2;2;6,2;2;2;7,3;3;3;8,4;4;4;8"
default-index 1
trigger "user"
display-type "link"
display-values "Blank,GWR 1922,GWR 1930,GWR 1934,Crimson Cream,Maroon"
}
1 {
enabled 1
property-visibility 1
name "Night Only: "
property-id "p_cfg"
description "Sets the Day Night"
kind "config-edit"
paths "marker-lights/night-only"
values "0,1"
default-index 0
trigger "user"
display-type "link"
display-values "False,True"
}
2 {
enabled 1
property-visibility 1
name "Front Indicator: "
property-id "p_front"
description "Large F character showing front of carriage"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "front"
values "0,1"
default-index 0
duration 2
trigger "user"
display-type "link"
display-values "Hidden, Visible"
}
3 {
enabled 1
property-visibility 0
name "Interior lighting: "
property-id "p_interior_lighting"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "day-interior,night-interior"
values "1;0,0;1"
default-index 0
duration 2
trigger "event"
events "world-day,world-night"
}
}
}
}

= Adding other effects =
You can easily add other mesh effects using the front indicator in the example above as a template. For example, some versions of a traincar may have a real life structure for different versions of the same basic car. For that just copy the front indicator container and change the tag contents as necessary.

= The final config.txt (relevant parts) =
Here is the completed config.txt for those parts covered by the example including the mesh-table:

script-include-table {
0 <kuid:661805:500008>
}
script "ref"
class "eRef"
extensions {
active-coupling-standard-60850 {
version-major "2"
version-minor "0"
brakes "vac"
front {
coupler "screwlink|hook"
vacbrake "single"
heating-type "steam"
gangway "gangway"
}
back {
coupler "screwlink|hook"
vacbrake "single"
heating-type "steam"
gangway "gangway"
}
}
wagon-x {
acs {
animated 1
use-jbv-animation 0
duration 5
}
marker-lights {
enabled 1
car-minimum-count 2
require-locomotive 1
night-only 0
front {
head {
mesh "lamp-front-white"
}
tail {
mesh "lamp-front-red"
}
}
back {
head {
mesh "lamp-back-white"
}
tail {
mesh "lamp-back-red"
}
}
}
misc {
begin-load-time 0
begin-unload-time 0
end-load-time 0
end-unload-time 0
}
browser-properties {
0 {
consist-property-sync 1
property-sync-id "GWRsynctexture"
enabled 1
property-visibility 1
name "Current traincar livery: "
property-id "p_livery"
description "Sets the livery for the carriage"
kind "fx-replacement"
fx-replacement-type "texture-replacement"
effects "livery-main,livery-leftdoor,livery-rightdoor,livery-crest"
asset "liveries"
values "0;0;0;0,1;1;1;5,2;2;2;6,2;2;2;7,3;3;3;8,4;4;4;8"
default-index 1
trigger "user"
display-type "link"
display-values "Blank,GWR 1922,GWR 1930,GWR 1934,Crimson Cream,Maroon"
}
1 {
enabled 1
property-visibility 1
name "Night Only: "
property-id "p_cfg"
description "Sets the Day Night"
kind "config-edit"
paths "marker-lights/night-only"
values "0,1"
default-index 0
trigger "user"
display-type "link"
display-values "False,True"
}
2 {
enabled 1
property-visibility 1
name "Front Indicator: "
property-id "p_front"
description "Large F character showing front of carriage"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "front"
values "0,1"
default-index 0
duration 2
trigger "user"
display-type "link"
display-values "Hidden, Visible"
}
3 {
enabled 1
property-visibility 0
name "Interior lightingr: "
property-id "p_interior_lighting"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "day-interior,night-interior"
values "1;0,0;1"
default-index 0
duration 2
trigger "event"
events "world-day,world-night"
}
}
}
}
fonts 0
mesh-table {
default {
mesh "default.lm"
auto-create 1
effects {
livery-main {
kind "texture-replacement"
texture "livery.texture"
}
livery-crest {
kind "texture-replacement"
texture "crest-crest.texture"
}
}
}
day-interior {
mesh "interior.lm"
auto-create 1
does-cast-shadows 0
lod-level 0
}
night-interior {
mesh "interior-night.lm"
auto-create 0
does-cast-shadows 0
lod-level 0
}
coupler-front {
mesh-asset <kuid:186372:900007>
mesh "screwlink.lm"
anim "screwlink.kin"
auto-create 1
att "a.couple0"
att-parent "default"
}
coupler-back {
mesh-asset <kuid:186372:900007>
mesh "screwlink.lm"
anim "screwlink.kin"
auto-create 1
att "a.couple1"
att-parent "default"
}
vacbrake-front {
mesh-asset <kuid:186372:900007>
mesh "vac_low_low.lm"
anim "vac_low_low.kin"
auto-create 1
att "a.couple0"
att-parent "default"
}
vacbrake-back {
mesh-asset <kuid:186372:900007>
mesh "vac_low_low.lm"
anim "vac_low_low.kin"
auto-create 1
att "a.couple1"
att-parent "default"
}
heating-front {
mesh-asset <kuid:186372:900007>
mesh "steamheat.lm"
anim "steamheat.kin"
auto-create 1
att "a.couple0"
att-parent "default"
}
heating-back {
mesh-asset <kuid:186372:900007>
mesh "steamheat.lm"
anim "steamheat.kin"
auto-create 1
att "a.couple1"
att-parent "default"
}
gangway-front {
mesh-asset <kuid:186372:900007>
mesh "gangway.lm"
anim "gangway.kin"
auto-create 1
att "a.couple0"
att-parent "default"
}
gangway-back {
mesh-asset <kuid:186372:900007>
mesh "gangway.lm"
anim "gangway.kin"
auto-create 1
att "a.couple1"
att-parent "default"
}
lamp-front-red {
mesh-asset <kuid:661805:500003>
mesh "oil_lamp_red.lm"
auto-create 0
att "a.taillamp0"
att-parent "default"
}
lamp-front-white {
mesh-asset <kuid:661805:500003>
mesh "oil_lamp_white.lm"
auto-create 0
att "a.taillamp0"
att-parent "default"
}
lamp-back-red {
mesh-asset <kuid:661805:500003>
mesh "oil_lamp_red.lm"
auto-create 0
att "a.taillamp1"
att-parent "default"
}
lamp-back-white {
auto-create 0
mesh-asset <kuid:661805:500003>
mesh "oil_lamp_white.lm"
att "a.taillamp1"
att-parent "default"
}
front {
att-parent "default"
att "a.limfront"
auto-create 1
mesh "extra_meshes\front.lm"
}
}

[[Category:How-to guides]]
[[Category:Modeling]]
[[Category:Content creation]]

HowTo/WagonX - Traincar Tutorial

2024-02-20T06:31:38Z

Pcas1986: First proper version. Second example, of a goods wagon, still to come.

= Document Structure =
<table width=1200>
The WagonX Tutorial set is written over several pages. This page is a tutorial for adding WagonX capability to a passenger traincar and a goods carrying wagon. Other pages in the series are listed below:
</table>
# [[HowTo/Use the WagonX Library]]<br>
# [[HowTo/WagonX - Technical Reference]]<br>
# [[HowTo/WagonX - Browser Properties Examples and Basic Tutorials]]<br>
# [[HowTo/WagonX - Locomotive Tutorial]]<br>

__TOC__
= Adding WagonX to a Traincar =
== Setting the scene ==
A traincar can have different purposes such as a passenger vehicle such as a car or carriage, or as a wagon carrying, loading and unloading goods. WagonX can assist with both of those so two examples are included here. The first example is of a GWR carriage made by Andi Smith and repaired by the CRG. The second example will likely be a coal vehicle by Ben Dorsey. That example will follow later.
For the GWR carriage we will add the Automated Coupling System (ACS), texture swapping, and attachments that can be shown or hidden.
All of this is defined in the config.
Some of the config tag set up is rather complicated so rather than describe here the tutorial frequently refers to the [[HowTo/WagonX - Technical Reference|Technical Reference]]. It would be useful to keep a brower tab open on that page.
Mesh libraries used in these examples are available on the DLS however they may not be suitable for your application so please use whatever is appropriate for your situation.

== Setting up the config for the script, class and script-include-table ==
=== The script ===
You need a simple script called ref.gs that is in the WagonX asset. Alternatively you can easily create it yourself in any plain text editor. The contents are:

include "locowagonx.gs"
class eRef isclass WagonX {};

=== The class and script-include table ===
Include these tags in the config, where <kuid:661805:500008> is the WagonX library.

class "eRef"
script-include-table {
0 <kuid:661805:500008>
}

== Setting up the extensions container ==

The extensions container contains sub containers for ACS, if used, and WagonX. So, the general format, with no tags yet, is:

extensions {
active-coupling-standard-60850 {

}
wagon-x {

}
}

== The ACS container ==
The ACS container is fully described at [[ACS_Coupling_System]], but for our purposes we will use the following as an example. Add/change/remove as required for your vehicle.

active-coupling-standard-60850 {
version-major "2"
version-minor "0"
brakes "vac"
front {
coupler "screwlink|hook"
vacbrake "single"
heating-type "steam"
gangway "gangway"
}
back {
coupler "screwlink|hook"
vacbrake "single"
heating-type "steam"
gangway "gangway"
}

== The Wagon-X Container ==
==== The WagonX ACS sub-container ====
See the [[HowTo/WagonX_-_Technical_Reference#ACS\|WagonX ACS Technical Reference]] for details of tag usage.<br>
WagonX needs information about ACS that isn't defined in the ACS container so, within the wagon-x sub container include an acs sub container that has three tags: animate, use-jbv-animation, and duration.
Animated and use-jbv-animation are self explanatory and duration is the fade time.
extensions {
active-coupling-standard-60850 {
...
}
wagon-x
{
acs
{
animated 1
use-jbv-animation 0
duration 1.0
}
}
}

==== The Misc sub-container ====
See the [[HowTo/WagonX_-_Technical_Reference#Misc\|WagonX Misc Technical Reference]] for details of tag usage.<br>
The Misc sub-container includes times, in seconds, for loads and unloads at industries. This can be useful for effects such as smoke or dust. Since this is a passenger vehicle we will just set all values to zero.

extensions {
active-coupling-standard-60850 {
...
}
wagon-x
{
acs
{
...
}
misc {
begin-load-time 0
begin-unload-time 0
end-load-time 0
end-unload-time 0
}
}
}

==== Marker Lights ====
See the [[HowTo/WagonX_-_Technical_Reference#Marker-Lights|WagonX Marker Lights Technical Reference]] for details of tag usage.<br>
The marker-lights sub container is required even if you are not using them. If you don't need it then just set enabled to 0 and the mesh values to null.<br>
The name "front" indicates the physical front of the vehicle. i.e. where a.limfront is located. "Back" is the physical back of the vehicle.
"Head" is the direction of train travel, and "tail" is the direction from which the train has come. In other words the tail of the train. Note that Trainz always has a nominal train direction of travel even if it is stopped.<br>
If you don't need a lamp at a position then just use "null". There are some conditions on when lights are shown.<br>
The head and tail meshes are lamp meshes in the mesh-table.<br>

extensions {
active-coupling-standard-60850 {
...
}
wagon-x
{
acs
{
...
}
misc {
...
}
marker-lights {
enabled 1
car-minimum-count 2
require-locomotive 1
night-only 0
front {
head {
mesh "lamp-front-white"
}
tail {
mesh "lamp-front-red"
}
}
back {
head {
mesh "lamp-back-white"
}
tail {
mesh "lamp-back-red"
}
}
}
}
}

==== Browser-Properties ====
See the [[HowTo/WagonX_-_Technical_Reference#Browser-Properties|Browser Properties Technical Reference]] for details of tag usage.<br>
The example that follows is a relatively simple browser setup to control:
*Texture swapping
*Control of the marker lights
*Control of an interior night mesh
*Control of a "front" indicator

Each property has a number of control tags that are located in a property container and each container has a simple number id. The number of tags in a container depends on the property type. Not all properties are subject to user control and can be triggered by other events, such as changing from day to night. Each property can be disabled, however this can only be done in the config.
===== Texture Swapping =====
Texture swapping is controlled in the Properties Browser and can be configured by the user. There are six possible textures including a blank which like an underpaint coat. The default livery is number 1 which is not the first in the list as the list starts with 0 (zero).
Since the number of texture effects is 4, and the number of different textures is 6, then the values tag must contain 24 values that are indices to the actual textures in the relevant texture library.

===== Marker Lights =====
The marker lights is quite simple and just controls whether they are used only at night or also during the day as well.

===== Front Indicator =====
The front indicator is a simple tool provided by the original creator, Andi Smith, to show which end of the car is the physical front. The property is visible in the Properties Browser as a simple show or hide option.

===== Interior Lighting =====
This is an example of a property triggered by an external event. In this case changing from day to night, and night to day. WagonX intercepts the message posted on these events and that triggers a mesh swap using the event type and the values to show the correct mesh.

extensions {
active-coupling-standard-60850 {
...
}
wagon-x
{
acs
{
...
}
misc {
...
}
marker-lights {
...
}
browser-properties {
0 {
consist-property-sync 1
property-sync-id "GWRsynctexture"
enabled 1
property-visibility 1
name "Current traincar livery: "
property-id "p_livery"
description "Sets the livery for the carriage"
kind "fx-replacement"
fx-replacement-type "texture-replacement"
effects "livery-main,livery-leftdoor,livery-rightdoor,livery-crest"
asset "liveries"
values "0;0;0;0,1;1;1;5,2;2;2;6,2;2;2;7,3;3;3;8,4;4;4;8"
default-index 1
trigger "user"
display-type "link"
display-values "Blank,GWR 1922,GWR 1930,GWR 1934,Crimson Cream,Maroon"
}
1 {
enabled 1
property-visibility 1
name "Night Only: "
property-id "p_cfg"
description "Sets the Day Night"
kind "config-edit"
paths "marker-lights/night-only"
values "0,1"
default-index 0
trigger "user"
display-type "link"
display-values "False,True"
}
2 {
enabled 1
property-visibility 1
name "Front Indicator: "
property-id "p_front"
description "Large F character showing front of carriage"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "front"
values "0,1"
default-index 0
duration 2
trigger "user"
display-type "link"
display-values "Hidden, Visible"
}
3 {
enabled 1
property-visibility 0
name "Interior lighting: "
property-id "p_interior_lighting"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "day-interior,night-interior"
values "1;0,0;1"
default-index 0
duration 2
trigger "event"
events "world-day,world-night"
}
}
}
}

= Adding other effects =
You can easily add other mesh effects using the front indicator in the example above as a template. For example, some versions of a traincar may have a real life structure for different versions of the same basic car. For that just copy the front indicator container and change the tag contents as necessary.

= The final config.txt (relevant parts) =
Here is the completed config.txt for those parts covered by the example including the mesh-table:

script-include-table {
0 <kuid:661805:500008>
}
script "ref"
class "eRef"
extensions {
active-coupling-standard-60850 {
version-major "2"
version-minor "0"
brakes "vac"
front {
coupler "screwlink|hook"
vacbrake "single"
heating-type "steam"
gangway "gangway"
}
back {
coupler "screwlink|hook"
vacbrake "single"
heating-type "steam"
gangway "gangway"
}
}
wagon-x {
acs {
animated 1
use-jbv-animation 0
duration 5
}
marker-lights {
enabled 1
car-minimum-count 2
require-locomotive 1
night-only 0
front {
head {
mesh "lamp-front-white"
}
tail {
mesh "lamp-front-red"
}
}
back {
head {
mesh "lamp-back-white"
}
tail {
mesh "lamp-back-red"
}
}
}
misc {
begin-load-time 0
begin-unload-time 0
end-load-time 0
end-unload-time 0
}
browser-properties {
0 {
consist-property-sync 1
property-sync-id "GWRsynctexture"
enabled 1
property-visibility 1
name "Current traincar livery: "
property-id "p_livery"
description "Sets the livery for the carriage"
kind "fx-replacement"
fx-replacement-type "texture-replacement"
effects "livery-main,livery-leftdoor,livery-rightdoor,livery-crest"
asset "liveries"
values "0;0;0;0,1;1;1;5,2;2;2;6,2;2;2;7,3;3;3;8,4;4;4;8"
default-index 1
trigger "user"
display-type "link"
display-values "Blank,GWR 1922,GWR 1930,GWR 1934,Crimson Cream,Maroon"
}
1 {
enabled 1
property-visibility 1
name "Night Only: "
property-id "p_cfg"
description "Sets the Day Night"
kind "config-edit"
paths "marker-lights/night-only"
values "0,1"
default-index 0
trigger "user"
display-type "link"
display-values "False,True"
}
2 {
enabled 1
property-visibility 1
name "Front Indicator: "
property-id "p_front"
description "Large F character showing front of carriage"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "front"
values "0,1"
default-index 0
duration 2
trigger "user"
display-type "link"
display-values "Hidden, Visible"
}
3 {
enabled 1
property-visibility 0
name "Interior lightingr: "
property-id "p_interior_lighting"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "day-interior,night-interior"
values "1;0,0;1"
default-index 0
duration 2
trigger "event"
events "world-day,world-night"
}
}
}
}
fonts 0
mesh-table {
default {
mesh "default.lm"
auto-create 1
effects {
livery-main {
kind "texture-replacement"
texture "livery.texture"
}
livery-crest {
kind "texture-replacement"
texture "crest-crest.texture"
}
}
}
day-interior {
mesh "interior.lm"
auto-create 1
does-cast-shadows 0
lod-level 0
}
night-interior {
mesh "interior-night.lm"
auto-create 0
does-cast-shadows 0
lod-level 0
}
coupler-front {
mesh-asset <kuid:186372:900007>
mesh "screwlink.lm"
anim "screwlink.kin"
auto-create 1
att "a.couple0"
att-parent "default"
}
coupler-back {
mesh-asset <kuid:186372:900007>
mesh "screwlink.lm"
anim "screwlink.kin"
auto-create 1
att "a.couple1"
att-parent "default"
}
vacbrake-front {
mesh-asset <kuid:186372:900007>
mesh "vac_low_low.lm"
anim "vac_low_low.kin"
auto-create 1
att "a.couple0"
att-parent "default"
}
vacbrake-back {
mesh-asset <kuid:186372:900007>
mesh "vac_low_low.lm"
anim "vac_low_low.kin"
auto-create 1
att "a.couple1"
att-parent "default"
}
heating-front {
mesh-asset <kuid:186372:900007>
mesh "steamheat.lm"
anim "steamheat.kin"
auto-create 1
att "a.couple0"
att-parent "default"
}
heating-back {
mesh-asset <kuid:186372:900007>
mesh "steamheat.lm"
anim "steamheat.kin"
auto-create 1
att "a.couple1"
att-parent "default"
}
gangway-front {
mesh-asset <kuid:186372:900007>
mesh "gangway.lm"
anim "gangway.kin"
auto-create 1
att "a.couple0"
att-parent "default"
}
gangway-back {
mesh-asset <kuid:186372:900007>
mesh "gangway.lm"
anim "gangway.kin"
auto-create 1
att "a.couple1"
att-parent "default"
}
lamp-front-red {
mesh-asset <kuid:661805:500003>
mesh "oil_lamp_red.lm"
auto-create 0
att "a.taillamp0"
att-parent "default"
}
lamp-front-white {
mesh-asset <kuid:661805:500003>
mesh "oil_lamp_white.lm"
auto-create 0
att "a.taillamp0"
att-parent "default"
}
lamp-back-red {
mesh-asset <kuid:661805:500003>
mesh "oil_lamp_red.lm"
auto-create 0
att "a.taillamp1"
att-parent "default"
}
lamp-back-white {
auto-create 0
mesh-asset <kuid:661805:500003>
mesh "oil_lamp_white.lm"
att "a.taillamp1"
att-parent "default"
}
front {
att-parent "default"
att "a.limfront"
auto-create 1
mesh "extra_meshes\front.lm"
}
}

[[Category:How-to guides]]
[[Category:Modeling]]
[[Category:Content creation]]

Help:VE258

2024-01-30T05:33:33Z

Pcas1986: Added link to FBX file format page

'''Unable to determine vertex format'''

Can be caused by multiple UV maps. Try removing additional maps. See [[FBX file format]]

HowTo/Export Blender FBX Animation

2024-01-10T05:09:19Z

Pcas1986: Updated to Blender 4. Example 2 still needs updating.

=Overview=
This page describes a process for exporting simple animated meshes from Blender to the [[FBX file format]]. It is intended for new content creators or those more experienced who need to migrate from older versions of Blender and Trainz animation.
You should be familiar with Blender FBX export as described here [[HowTo/Export from Blender using FBX]]<br>
This tutorial is for Trainz Build 5.3 and Blender 4.n. However, it should work for Trainz Build 4.6 and up.
==Trainz Animation==
In Blender you can animate meshes but that animation is not recognised by Trainz. Trainz only recognises animation helper objects that it calls bones. A bone, for Trainz purposes, is an animated helper object using a "b.r." prefix.
Meshes are attached to bones in a parent-child relationship where the child is the mesh. When the parent bone moves in 3D space, the child mesh moves with it. In Trainz you cannot see the animated bones but you can see the mesh.
Animation helpers in Blender can be armatures or empties. Lattices cannot be used since the standard FBX exporter doesn't recognise them.
=Examples=
Here are a number of example animations. Each example is provided with source files but only the first example is fully explained.
==Example 1 - A Revolving Sphere==
This example is a very basic animation of a sphere using an empty as the animation helper. The Blender file consists of a sphere located at grid centre and at elevation 2 (metres). The sphere has a PBR material and a simple UV map.
Your task is add the animation helper, add the rotation animation, export to FBX and import into Trainz.
===Load Example 1===
:* On your computer, create a project folder called "anim_example_1" or whatever name suits you.
:* Download the source files from here: [[File:B4 Anim Ex1 Source.zip]]
:* The source file is in zip format so extract it into the project folder. The source includes:
example1_B4_start.blend;
example1_B4_completed.blend;
ex1_albedo.png
ex1_albedo.texture.txt
ex1_normal.png
ex1_normal.texture.txt
ex1_parameter.png
ex1_parameter.texture.txt
thumbnail_0.jpg
config.txt
:* The config.txt is complete except for the KUID where you add one of your own. The Trainz Build is set to 5.3. You can use 4.6 if required.
:* Open the ex1_B4_example.blend Blender source file in Blender 4. It should look similar to the following. If the sphere is a pink/purple colour then that means Blender can't find the material textures. You should be able to correct that adding them to your Blender file location and reloading the textures withing Blender.
:* Save the file as "ex1B4_working.blend".
[[File:Ex1B4 start.jpg|1200px|thumb|left|The Start Layout]]

<table bgcolor=#000000 width=1200 cellpadding=2>
<tr valign="top">
<td>
<table bgcolor=#ffffb0 cellpadding=2>
<tr valign="top">
<td>[[image:NotePad.PNG|link=]]</td>
<td>The model is a simple UV ball with a painted metal material the author created in Substance Painter. It looks like a planet, but not Earth, with a lot of shiny water and snow covered land. In game it will look like a metal ball with chipped paint. In the top right pane you can see the scene collection which has two Level of Detail (LOD) collections and an Animation collection. The mesh names with the LOD#n complies with the requirements for building a config.txt using the N3V utilities. In this instance the LOD1 meshes are hidden.
At the bottom right you can see the material setup. You can also observe the material (PBRMetal) in the Shading Editor as a node setup.
The image shows reflections of trees due to a background image.
Blender has almost infinite permutations of layouts, colours, size, etc. Don't be concerned if yours isn't the same as the image.
</td>
</tr>
</table>
</td>
</tr>
</table>

===Add the Trainz Animation Helper===
:* Position the Blender cursor at World Origin (0,0,0). Press Shift S to bring up the Snap menu and select Cursor to World Origin.
:* Add an empty at the cursor location. Use menu Add->Empty->Arrows. Shift A should also work.
:* Double click on the new Empty in the Properties Editor and rename it to "b.r.main". The name used is not important but the prefix "b.r." is important. The convention is to use b.r.main or b.r.base.
:* Move the b.r.main helper into the Animation collection. You can either drag and drop it in the Properties Window or the menu Object->Collection->Move to Collection. Having a collection name Animation makes it easier to export different LOD meshes.
===Animate the Trainz Helper===
:* Change to the Animation Workspace and ensure the b.r.main object is selected.
:* Open the SideBar (N key) in the 3D Editor, if not already open, and select the Item tab. This shows the location, rotation, and scale of the current object. In this case it should be the b.r.main empty.
:* For this project the location and rotation values should be zero and the scale values should be 1.0. If the values are wrong then press Ctrl A and reset whatever needs changing.

<table bgcolor=#000000 width=1200 cellpadding=2>
<tr valign="top">
<td>
<table bgcolor=#ffffb0 cellpadding=2>
<tr valign="top">
<td>[[image:NotePad.PNG|link=]]</td>
<td>As you develop more advanced animation models the location values will be different. Generally, at the start of an animation the Rotation values will also be zero but this isn't mandatory.
The Scale values can cause all sorts of issues in animation and need to be checked at the start of the project. Scaling can be part of the animation although for most models in Trainz the scaling is mostly fixed. But you can animate scaling if that is a solution. Note scaling does affect material/texture mapping as the textures applied to a model will be stretched or shrunk with the scaling.
If you run into problems with animation check that the scaling is correct at the start of the animation cycle.
</td>
</tr>
</table>
</td>
</tr>
</table>

:* For animation we use keyframes (aka frames) to manage our animation. Trainz operates animations at 30 frames per second (fps) and, as we want to run this animation for two seconds, the End Frame in Timeline should be 60. Make sure the Start Frame is 1 and the Current Keyframe is 1. See the following image.

<table><tr><td>[[File:Blender402 anim example1 view1.jpg|1200px|thumb|left|B.R.Main]]</td></tr></table>

:* Select the b.r.main helper if not already selected.
:* For the start of our animation we need to set the rotation of our helper to be at 0 (zero) degrees. For this example we can just leave the helper as Blender placed it..
:* Press the I key and select Rotation. This creates a frame with just rotation data which, in this case, is 0. In the Animation Editor a number of changes will become visible.
::: The Rotation fields in the Transform will change colour. In the image below they are yellow but the colour depends on the Blender theme in use.
::: A keyframe indicator appears in the Timeline Window at the bottom of the Blender screen.
::: Entries also appear in the Dope Sheet and Graph Editors. In simple animations you are unlikely to use those editors but be aware they exist.
:* Change the Current frame in Timeline to the last keyframe (60). You can click on frame 60 in Timeline, manually change the current frame number or use the "Jump to end" icon in Timeline.
:* At the end of our animation we want the helper to have completed one full rotation of 360 degrees so select the helper and, in the Properties Window->Context, change the Z Rotation value to 360, and press the I key and select Rotation againi. The result should look like the following:
<table><tr><td>[[File:Setting the rotation to 360.jpg|600px|thumb|left|Setting the rotation]][[File:Rotation set to 360.jpg|600px|thumb|right|Rotation set to 360]]</td></tr></table>
:* Test out the animation by clicking on the Forward and Reverse icons in Timeline. When finished reset the animation by stopping it first and then selecting the Start Endpoint icon. Note that the sphere is not moving yet.
===Review===
So far we have created the helper with a name that Trainz will recognise for animation. We have set the animation to compete one full circle in the Z axis in 60 keyframes and, since we are using 30fps, the animation will run for 2 seconds.
The use of the value 360 is somewhat of a trick to make sure that Blender animates the helper through 360 degrees. Although 360 is essentially the same as 0, if you left it at 0 then no animation would take place even though keyframes exist. Try a zero value and see what happens or rather what doesn't happen.
Using the value of 360 means that the helper will rotate 360 degrees in the anti-clockwise direction. If you want clockwise motion then change the value to -360.
===Smoothing the Animation===
While watching the animation you may have noticed that the animation pauses briefly between the end and restart of the animation. There is no time gap but this indicates that the animation is not following a linear path but one using an "F curve". These pauses may be noticeable in game except for bogie animations where the animation is dynamically managed by the game engine.
Within Blender this characteristic is known as the extrapolation mode of the animation channel. By default Blender uses an F curve that resembles a Bezier curve. For many Trainz animations you may want a continuous animation and that means the Linear Extrapolation. Note that there is a Constant Animation but that may not give the same result as it essentially freezes the animation between keyframes.
:* Change the workspace to Animation if not there already.
:* In the Graph Editor or the Dope Sheet Editor, select menu Channel>Extrapolation Mode>Linear Extrapolation.
:* Run the animation again and there should be no pauses.
<table><tr><td>[[File:Linear extrapolation.jpg|800px]]<br></td></tr></table>
For more information on Blender animation channel extrapolation see [https://docs.blender.org/manual/en/latest/editors/graph_editor/fcurves/introduction.html Introduction to FCurves]
===Parenting the mesh objects===
:* As stated earlier you cannot animate the meshes directly but you can make them follow the animation helper. We do this by making the mesh a child of the helper.
:* There are two meshes to be animated: the LOD0 and LOD1 meshes.
:* Enable viewing of both the LOD0 and LOD1 mesh by ticking the two collections.
:* Select the objects sphere_lod0, sphere_lod1 and finally b.r.main. The helper bone (empty) must be selected last.
:* In the 3D window, press Ctrl P>Object (Keep Transform).
:* Test the animation by starting the animation and showing or hiding the two mesh objects.
:* Save your work.
<table><tr><td>[[File:Parenting the mesh.jpg|1200px|thumb|left|Parenting the mesh]]</td></tr></table>
<table bgcolor=#000000 width=1000 cellpadding=2>
<tr valign="top">
<td>
<table bgcolor=#ffffb0 cellpadding=2>
<tr valign="top">
<td>[[image:NotePad.PNG|link=]]</td>
<td>The picture above shows the action of parenting the two mesh objects (sphere_lod0n and sphere_lod1n) to the bone (b.r.main). The following image shows the result.
The two meshes are still in their LOD collections but are also shown as children of b.r.main in the Animation collection but in a light grey. They are not actually part of the animation collection.
</td>
</tr>
</table>
</td>
</tr>
</table>
<table><tr><td>[[File:After parenting.jpg|1000px|thumb|left|After parenting]]</td></tr></table>
===Exporting the Animation===
The animation data for the helper(s) as well as the parent/child relationships are exported within the FBX file. The Trainz FBX importer will extract the animation data and store some of it in the Trainzmesh file but the actual animation data in a KIN file. Since we have two LOD meshes this means that the importer will create two KIN files but with slightly different names. As the animation is the same for both meshes you can just use one of the KIN files and delete the other.<br>
Blender's FBX exporter will export each animation channel it finds and this can result in multiple KIN files for each mesh. This doesn't work in Trainz. The solution is to use what is called a baked animation where all the channels and keyframes are "baked" together. Baking also causes every frame to be exported even though the source may only specify two keyframes, as in our example.

====Exporting the LOD0 Animation====
:* Disable viewing of the LOD1 meshes by unclicking the LOD1 collection.
:* Enable both the LOD0 and Animation collections.
:* In the 3D Editor select all objects using the A key. You may need to press it twice.
<table><tr><td>[[File:Exporting lod0.jpg|800px|thumb|Exporting LOD0]]</td></tr></table>
:* Go to the File menu and select Export>FBX.
:* The list of options for export is quite long so they are displayed here in two images.
<table><tr><td>[[File:FBX export settings1.jpg|500px|thumb|left|Export settings 1]][[File:FBX export settings2.jpg|500px|thumb|right|Export settings 2]]</td></tr></table>
:* The options shown in these images should work for most exports. Some comments:
:* You can make presets of those settings you use most. The author has one for animation, one for mesh only, and one for mesh and empties. The last is used for meshes with attachments. Presets are very useful.
:* The Path Mode and Batch Mode can be left with default values. They may be useful for exporting models with multiple LODs but the author hasn't tried that.
:* Include: The Limit to section may be something you could consider changing depending on preferences. The author prefers Selected Objects but the other values may suit you better.
:* Include: The Object Types is important. The author works with both empties and armatures for animation so the values are set as shown. You could disable armatures if not being used.
:* Transform: The Scale value and the Apply Scalings are related. Some authors like to use different values to get the same result but the values shown will work.
:* Transform: The Forward and Up are also related so if you change one then the other may change as well. Y Forward and Z up are correct for Trainz.
:* Geometry: These values will work. Applying modifiers and Triangulating faces is something you may wish to change. This is the author's preferred set.
:* Armature: The effect of changing these values has not been tested so just use the default values.
:* Bake Animation: This must be ticked and the other values left unchecked. Leave the Sampling Rate and Simplify as 1.0.
:* In the output filename space enter ex1_lod0.fbx and click on the Export FBX icon.

====Exporting the LOD1 Animation====
:* Uncheck the LOD0 collection.
:* Check the LOD1 collection.
:* Leave the Animation collection checked.
:* Repeat the LOD0 process only changing the output name to ex1_lod1.fbx. You shouldn't need to change any of the export settings unless you restarted Blender.

===Setting up the Asset in Trainz===
:* The FBX file contains both the mesh and the b.r.main empty plus the animation data. When the FBX file is imported into Trainz, an animation file (KIN) is created in addition to the Trainzmesh file.
:* The name of the kin file depends on the options chosen within the Export FBX->Animation panel. If you choose the Baked Animation option, then the kin filename will be the mesh name plus “_scene.kin”. In this instance, the kin filenames will be “ex1_lod0_scene.kin” and “ex1_lod1_scene.kin”.
====Config.txt====
:* Create your config.txt. You can either use the config.txt provided with this tutorial remembering to change the KUID to suit one of yours, or create a config.txt from scratch or maybe use the N3V utility program at [[https://contentcreation.trainzsimulator.com/trainz-content-utilities-1-0-2/|N3V Content Utilities]].
:* For this asset the mesh table will look like this. Note that the kin file for LOD1 uses the LOD0 kin file.

mesh-table {
lod_0 {
mesh "ex1_lod0.trainzmesh"
auto-create 1
lod-level 0
anim "ex1_lod0_scene.kin"
animation-loop-speed 1.00
}
lod_1 {
mesh "ex1_lod0.trainzmesh"
auto-create 1
lod-level 1
anim "ex1_lod0_scene.kin"
animation-loop-speed 1.00
}
}

====Committing and updating the asset====
:* Getting the asset to work in game is often a two part process. The first commit will create the Trainzmesh and KIN files and a second pass may be needed to correct filenames in the config.txt.
:* Commit the asset to Trainz.
:* Open the asset for editing. If it failed the commit it will already be open.
:* Check the names of the Trainzmesh and KIN files produced. If necessary, change the config.txt mesh-table to suit the correct names.
:* If you intend to use the LOD0 KIN file then you can delete the LOD1 version.
:* Commit the asset again. Hopefully, there should be no errors.

====Warnings on commit====
:* You may get these warnings on the first export/import into Trainz. They can be ignored.
<table><tr><td>[[File:B4 anim ex1 export warnings.jpg|600px]]</td></tr></table>
===Asset in game===
This is the asset in game. Remember that animation will only work in Driver mode.<br>
The ball revolves at a constant rate. You can change the rotation speed in the config.txt using the animation-loop-speed tag.
<table><tr><td>[[File:Ex1 in game.jpg|600px]]</td></tr></table>
<br>
===Adding the animation as an animation effect===

====Original author's comments====
This tutorial was altered by another user to use an animated effect in an effects container. While this is useful, it is a bit more advanced than the intent of this tutorial so the orignal author has moved the changes here and the original tutorial structure restored.

====Animated Effects====
An animated effect can be useful if using script to control the animation as there are more options for animation control. Instead of being located in the main mesh-table, the animated object is located in an Effects container as described here: [[Animation_Effect]].
You can find the animation effect version of this tutorial at [[File:Tutorial_Rebuild_Blender_Rotatating_Earth.zip|Example 1: Tutorial Rebuild Blender Rotatating Earth]]

==Example 2 - Four revolving cogs==
(This example needs to be updated and validated)
This example shows four meshed cogs rotating together. The rotation of the cogs is controlled by four armatures and an empty is used as a parent bone.
Each cog has its own armature and two rotate clockwise and the other two rotate anticlockwise.<br />
There are two Blender files provided: one incomplete and one complete. <br />
The starting file has the four cogs UV mapped and linked to a Trainz PBR material. An armature is positioned at the centre of each cog. The four cogs are grouped into a LOD0 collection and the four armatures are grouped into an Animation collection. There is also a LOD1 collection but it is empty.<br />
Your task is to add the animation, duplicate the meshes into LOD1 and export to Trainz. Not everything is explained in detail but if you have completed Example 1 then that will help.
[[File:4 cogs in Blender.jpg|800px]]
===Source Files===
The source files can be downloaded here [[File:ex2_export.zip]]. The source includes:
ex2_start.blend;
ex2_complete.blend;
cogs_albedo.png
cogs_albedo.texture.txt
cogs_normal.png
cogs_normal.texture.txt
cogs_parameter.png
cogs_parameter.texture.txt
$screenshot$.jpg
config.txt

Updated and rebuilded tutorial files: [[File:Tutorial_Rebuild_Blender_Four_Cogs.zip|Example 2: Tutorial Rebuild Blender Four Cogs]]
Beside some adjustments the main update was to move, add and amend animation tags to a effects sub container.
Informations about Blender 3.x fbx export settings as picture one will find in [[Prequel Blender to Trainz|Prequel for this tutorial series: Blender to Trainz (with the full script)]]

===Things you need to do===
====Saving====
:* Save often. Animation can be tricky so always save when you have reached a critical point.
====Animate the cogs====
:* Set the animation range to 120 frames, start frame 1, and the current frame 1.
:* Make the four cog armatures children of the root animation helper b.r.base.
:* For each cog:
:** Make the cog mesh a child of its armature. Blender 2.8 seems to be a bit unreliable for this action so make sure the correct parent is applied. You can see this in the Properties Editor, Context Panel->Relations. The parent type should be object.[[File:Checking the cog parent.jpg|800px]]
:** Create five keyframes for each armature as detailed in the table below:
::::{| class="wikitable"
! width=15% | Armature
! width=15% | Keyframe<br />1
! width=15% | Keyframe<br />30
! width=15% | Keyframe<br />60
! width=15% | Keyframe<br />90
! width=15% | Keyframe<br />90
|-
| <center>1</center>
| <center>0</center>
| <center>-90</center>
| <center>-180</center>
| <center>-270</center>
| <center>-360</center>
|-
| <center>2</center>
| <center>0</center>
| <center>90</center>
| <center>180</center>
| <center>270</center>
| <center>360</center>
|-
| <center>3</center>
| <center>0</center>
| <center>-90</center>
| <center>-180</center>
| <center>-270</center>
| <center>-360</center>
|-
| <center>4</center>
| <center>0</center>
| <center>90</center>
| <center>180</center>
| <center>270</center>
| <center>360</center>
|}
:* Run the animation and check that the cogs rotate in the correct direction and mesh with each other. If this doesn't look right then you may have to fall back to a saved version or even the starting version.
:* For each cog:
:**Make a copy. (Shift D)
:**Move the copy to the LOD1 collection. (M key)
:**Rename the copy to "gearx-lod1" where "x" is the gear number.
:**Add a Decimate modifier. The Planar option with an angle of 10 will reduce the number of polys to a usable number. There is no need to apply the modifier since the exporter will do that on export.
:*Hide the LOD1 collection and run the animation again. This will show the LOD1 meshes animating.

====Export====
:*Select each LOD collection in turn and, together with the Animation collection, export to files called "cogs_lod0.fbx" and "cogs_lod1.fbx". For this export you must select Empty, Armature, and Mesh.
===Asset in Game===
[[file:cogs_in_game.jpg]]

==Example 3 - coming soon(ish)==

=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.
|-
| style="border:1px solid gray;font-weight:normal;"|! ... T2776: FBX: animation is applied to multiple targets
| style="border:1px solid gray;font-weight:normal;"| Might be caused by armatures, where the bones does not have names starting with "b.r.". The armature object itself does not need to have a "b.r." prefix in its name, however.
|}

=Return to Index=

[[HowToGuides|<< How To Guides]]
[[Category:How-to guides]]
[[Category:Modeling]]
[[Category:Content creation]]

File:Linear extrapolation.jpg

2024-01-10T05:07:51Z

Pcas1986: Pcas1986 uploaded a new version of "File:Linear extrapolation.jpg": Reverted to version as of 05:05, 10 January 2024

Used in Blender 2.80 FBX animation tutorial

File:Linear extrapolation.jpg

2024-01-10T05:05:57Z

Pcas1986: Pcas1986 uploaded a new version of "File:Linear extrapolation.jpg": Reverted to version as of 05:04, 10 January 2024

Used in Blender 2.80 FBX animation tutorial

File:Linear extrapolation.jpg

2024-01-10T05:05:36Z

Pcas1986: Pcas1986 uploaded a new version of "File:Linear extrapolation.jpg": Reverted to version as of 05:21, 9 January 2024

Used in Blender 2.80 FBX animation tutorial

File:Linear extrapolation.jpg

2024-01-10T05:04:20Z

Pcas1986: Pcas1986 uploaded a new version of "File:Linear extrapolation.jpg": Update to Blender 4

Used in Blender 2.80 FBX animation tutorial

File:Setting the rotation to 360.jpg

2024-01-10T04:29:36Z

Pcas1986: Setting the rotation of a bone in Blender

Setting the rotation of a bone in Blender

File:Setting the rotation.jpg

2024-01-10T04:24:58Z

Pcas1986: Pcas1986 uploaded a new version of "File:Setting the rotation.jpg": Reverted to version as of 04:09, 10 January 2024

Used in Blender 2.80 FBX animation tutorial

File:Setting the rotation.jpg

2024-01-10T04:24:18Z

Pcas1986: Pcas1986 uploaded a new version of "File:Setting the rotation.jpg": Reverted to version as of 05:19, 9 January 2024

Used in Blender 2.80 FBX animation tutorial

File:Setting the rotation.jpg

2024-01-10T04:09:21Z

Pcas1986: Pcas1986 uploaded a new version of "File:Setting the rotation.jpg": Updated to Blender 4.0

Used in Blender 2.80 FBX animation tutorial

File:Rotation set to 360.jpg

2024-01-10T04:05:13Z

Pcas1986: Shows result of setting a rotation keyframe

Shows result of setting a rotation keyframe

File:B4 Anim Ex1 Source.zip

2024-01-10T03:50:55Z

Pcas1986: Pcas1986 uploaded a new version of "File:B4 Anim Ex1 Source.zip": Reverted to version as of 03:50, 10 January 2024

Source files for Blender 4 animation exercise 1.
File includes two Blender files, config.txt, thumbnail, material textures, and texture.txt files.

File:B4 Anim Ex1 Source.zip

2024-01-10T03:50:54Z

Pcas1986: Pcas1986 uploaded a new version of "File:B4 Anim Ex1 Source.zip": Reverted to version as of 03:50, 10 January 2024

Source files for Blender 4 animation exercise 1.
File includes two Blender files, config.txt, thumbnail, material textures, and texture.txt files.

File:B4 Anim Ex1 Source.zip

2024-01-10T03:50:33Z

Pcas1986: Pcas1986 uploaded a new version of "File:B4 Anim Ex1 Source.zip": Source files for Blender 4 animation exercise 1. File includes two Blender files, config.txt, thumbnail, material textures, and texture.txt files.

Source files for Blender 4 animation exercise 1.
File includes two Blender files, config.txt, thumbnail, material textures, and texture.txt files.

File:B4 Anim Ex1 Source.zip

2024-01-10T03:50:12Z

Pcas1986: Source files for Blender 4 animation exercise 1. File includes two Blender files, config.txt, thumbnail, material textures, and texture.txt files.

Source files for Blender 4 animation exercise 1.
File includes two Blender files, config.txt, thumbnail, material textures, and texture.txt files.

File:Ex1 in game.jpg

2024-01-10T03:37:29Z

Pcas1986: Pcas1986 uploaded a new version of "File:Ex1 in game.jpg": Blender 4 animated asset ex1 in game - updated.

Used in Blender 2.80 FBX animation tutorial

File:B4 anim ex1 export warnings.jpg

2024-01-10T03:31:07Z

Pcas1986: Shows Blender 4 animation ex1 Trainz import warnings.

Shows Blender 4 animation ex1 Trainz import warnings.

File:FBX export settings2.jpg

2024-01-10T02:48:42Z

Pcas1986: Shows second part of Blender FBX animation export settings.

Shows second part of Blender FBX animation export settings.

File:FBX export settings1.jpg

2024-01-10T02:46:49Z

Pcas1986: Shows first part of Blender FBX animation export settings.

Shows first part of Blender FBX animation export settings.

File:Exporting lod0.jpg

2024-01-10T02:26:48Z

Pcas1986: Shows exporting a bone and mesh in Blender

Shows exporting a bone and mesh in Blender

File:After parenting.jpg

2024-01-10T02:04:45Z

Pcas1986: Show the result of parenting two LOD mesh objects to an animated empty (bone).

Show the result of parenting two LOD mesh objects to an animated empty (bone).

File:Parenting the mesh.jpg

2024-01-09T07:09:00Z

Pcas1986: Shows parenting meshes to a bone in Blender

Shows parenting meshes to a bone in Blender

File:Linear extrapolation.jpg

2024-01-09T05:21:51Z

Pcas1986: Pcas1986 uploaded a new version of "File:Linear extrapolation.jpg": Updated for Blender 4.02

Used in Blender 2.80 FBX animation tutorial

File:Setting the rotation.jpg

2024-01-09T05:19:55Z

Pcas1986: Pcas1986 uploaded a new version of "File:Setting the rotation.jpg": Used in the Blender FBX animation page

Used in Blender 2.80 FBX animation tutorial

File:Blender402 anim example1 view1.jpg

2024-01-09T05:16:31Z

Pcas1986: Used in Blender FBX animation page

Used in Blender FBX animation page

File:Ex1B4 start.jpg

2024-01-09T05:15:10Z

Pcas1986: Used in Blender FBX animation page

Used in Blender FBX animation page

HowTo/WagonX - Browser Properties Examples and Basic Tutorials

2023-10-01T06:25:46Z

Pcas1986: First major release. Probably still has some bugs, typos and formatting links.

<span style="color: red; font-weight: 700; font-size: 15px;">Please note: Much of this page still needs some validation. If you find issues then please contact PCAS1986 in the Trainz Forums or in the Trainz Discord Server.</span>

= Document Structure =
<table width=1200>
The WagonX Tutorial set is written over several pages. This page contains some example WagonX config containers and basic guidance for setting up those containers. Other pages in the series are listed below:
</table>
# [[HowTo/Use the WagonX Library]]<br>
# [[HowTo/WagonX - Technical Reference]]<br>
# [[HowTo/WagonX - Locomotive Tutorial]]<br>
# [[HowTo/WagonX - Traincar Tutorial]]<br>
# [https://docs.google.com/document/d/1jd5nZNQJI_gKQp-X2GjNCBij9fZGAwgJy_BgBiXf3_8/edit#bookmark=id.kupvwsc34hnk| The asset author's documentation]

__TOC__

=Browser property tutorials=

This tutorial takes you each step of creating a simple mesh toggle example. It is for a handbrake mesh, including animation, that the user may want to show (make visible) or hide (make invisible). We will add each property tag and explain its purpose.
It may be useful to have the [[HowTo/WagonX - Technical Reference|WagonX Technical Reference]] page open in a browser to examine details of the various tags.
<table width=1200><tr><td>
==Creating a basic mesh toggle==
*Start with an empty browse-properties container like this:

browser-properties
{
}

*Add an empty property container and name it "0". The names are not used but should be unique. When we add more properties, you should name them “1”, “2”, “3”, etc.

browser-properties
{
0
{
}
}

*There is no order required for each property, but using a standard order makes it easier to follow. Each tag is hyperlinked to the browser-property, so you can see more information about it.
The first tag to add is [[HowTo/WagonX - Technical Reference#enabled|enabled]]. This determines whether or not the property is activated. Set it to 1, since we want our property to work in-game.

browser-properties
{
0
{
enabled 1
}
}

*Set the visibility of the property using [[HowTo/WagonX - Technical Reference#property-visibility|property-visibility]] and make that 1. Note this value is an integer and doesn't require quotes around it. A value of 1 makes the property visible in both Surveyor and Driver. See the reference for other available values.

browser-properties
{
0
{
enabled 1
property-visibility 1
}
}

*Set the [[HowTo/WagonX - Technical Reference#name|name]] of our property. The name will appear before the [[HowTo/WagonX - Technical Reference#display-values|display-values]], which we will get to in a moment. You also will want to add a space at the end; otherwise, the property name and display-value will appear as one word.
browser-properties
{
0
{
enabled 1
property-visibility 1
name "Toggle Mesh: "
}
}

*Set the [[HowTo/WagonX - Technical Reference#property-id|property-id]], which can be anything as long as it is unique and doesn't contain [[HowTo/WagonX - Technical Reference#Restricted_Characters|restricted characters]]. Trainz will use this to identify this property.
browser-properties
{
0
{
enabled 1
property-visibility 1
name "Toggle Mesh: "
property-id "p_meshToggle"
}
}

*Set the [[HowTo/WagonX - Technical Reference#description|description]]. This will appear as the tool-tip when you hover over a browser-property.
browser-properties
{
0
{
enabled 1
property-visibility 1
name "Toggle Mesh: "
property-id "p_meshToggle"
description "Toggles the mesh"
}
}

*Set the property [[HowTo/WagonX - Technical Reference#kind|kind]]. Since we want a mesh-attachment kind, we must also specify the [[HowTo/WagonX - Technical Reference#mesh-attachment-type|mesh-attachment-type]] which for this application is mesh-toggle.
browser-properties
{
0
{
enabled 1
property-visibility 1
name "Toggle Mesh: "
property-id "p_meshToggle"
description "Toggles the mesh"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
}
}

*Now add a [[HowTo/WagonX - Technical Reference#meshes|meshes]] tag to specify what mesh we want to toggle. The mesh name must exist in the config mesh-table. We will use the script author's prestwins handbrake lever for this demo.

Here is part of the config mesh-table:
handbrake-lever
{
mesh "mesh/handbrake.lm"
anim "mesh/handbrake_scene.kin"
auto-create 1
att-parent "default"
}

browser-properties
{
0
{
enabled 1
property-visibility 1
name "Toggle Mesh: "
property-id "p_handbrakeMeshToggle"
description "Toggles the handbrake mesh"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "handbrake-lever"
}
}

*Add the [[HowTo/WagonX - Technical Reference#values|values]] tag. This determines what the state of the object will be at each index. The values tag varies depending on the kind, but looking at the values tag page, we see that for kind mesh-toggle, we set it at 0 to hide the mesh, and 1 to show the mesh. Each index is comma separated, so we will set the first one at 1, and the seccond one at 0.
browser-properties
{
0
{
enabled 1
property-visibility 1
name "Toggle Mesh: "
property-id "p_handbrakeMeshToggle"
description "Toggles the handbrake mesh"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "handbrake-lever"
values "1,0"
}
}

*Add the [[HowTo/WagonX - Technical Reference#default-index|default-index]]. This is an integer value starting from 0 and which indicates the position in a list. 0 is the first in the list, 1 is the second, and so on. <i>(The reasons for this are somewhat historical but also based on how computers find things in memory.)</i> If we set it to 1, it will start at the second comma-separated values tag which is "0". If we set it at -1, it will pick a random index within the size of the values tag.
browser-properties
{
0
{
enabled 1
property-visibility 1
name "Toggle Mesh: "
property-id "p_handbrakeMeshToggle"
description "Toggles the handbrake mesh"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "handbrake-lever"
values "1,0"
default-index 0
}
}

*Add the [[HowTo/WagonX - Technical Reference#trigger|trigger]] tag. We want our property to activate when a user presses a button on the properties page, so we will set it to <b>user</b>. If we set it to <b>event</b>, however, we could make it activate based on an event within the train or in the world, such as handbrake apply, or enabling it when it gets dark, and disabling it when its daytime again, but for now, we will leave it at user.
browser-properties
{
0
{
enabled 1
property-visibility 1
name "Toggle Mesh: "
property-id "p_handbrakeMeshToggle"
description "Toggles the handbrake mesh"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "handbrake-lever"
values "1,0"
default-index 0
trigger "user"
}
}

*Specify the [[HowTo/WagonX - Technical Reference#display-type|display-type]]. Looking at the options, we see that <b>link</b> is what we want.
browser-properties
{
0
{
enabled 1
property-visibility 1
name "Toggle Mesh: "
property-id "p_handbrakeMeshToggle"
description "Toggles the handbrake mesh"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "handbrake-lever"
values "1,0"
default-index 0
trigger "user"
display-type "link"
}
}

*Finally, the last tag we need is the display-values tag, which we talked about earlier. Since we have two states for our property (specified in the values tag), we will create two comma-separated values for each state. We will call the first “Enabled”, and the second “Hidden”, which corresponds with the numbers we set in the values tag.
browser-properties
{
0
{
enabled 1
property-visibility 1
name "Toggle Mesh: "
property-id "p_handbrakeMeshToggle"
description "Toggles the handbrake mesh"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "handbrake-lever"
values "1,0"
default-index 0
trigger "user"
display-type "link"
display-values "Enabled,Hidden"
}
}

And that's it! Run the asset into trainz, and when you view the properties, you should see your property appear:<br>


[[File:Toggle_handbrake_mesh_in_View_Details.jpg]]

And when you click on the underlined part of your property, the property should change to “Hidden”, as we specified, and the handbrake on the underframe should disappear.<br>
[[File:Handbrake_mesh_show_%26_hide.jpg]]

</td></tr></table>
= Browser-Property Examples =
== User-Triggered Properties ==
Here are a number of examples for user triggering - i.e. in the View Details property browser. Detailed information on the property browser tags can be found on the [[HowTo/WagonX - Reference|WagonX Reference]] page.

<table width=1200><tr><td>
===Mesh-toggle property===
This property allows you to show or hide a mesh that is in the config mesh-table.

{
enabled 1
property-visibility 1
name "Toggle: "
property-id "p_toggle"
description "Hide or display the roof mesh"
kind "mesh-attachment"
mesh-attachment-type "mesh-toggle"
meshes "roof"
values "0,1"
duration 3
default-index 0
trigger "user"
display-type "link"
display-values "Hidden,Visible"
}
</td></tr></table>


<table width=1200><tr><td>
===texture-replacement property===
This allows the choice of a texture from either local texture files (i.e. contained within the asset), or from a texture group asset, to retexture or reskin a mesh. You could use it for swapping between clean, dirty or weathered textures, logos and also entire liveries.
</td></tr></table>
<br>


<table width=1200><tr><td>
====Texture replacement using local texture files====

For fx-replacement-type texture-replacement-texture, the comma and/or semicolon-separated values are the names of the files (ideally without the path or extension) to be referenced at that index. The values tag will contain a list of texture(.txt) files including a folder name if used. This is an example of three textures.

values "images/congleton.texture,images/burntisland.texture,images/buxton.texture,images/none.texture"

If you have the same path (and same extension) for all your files, you can greatly reduce the clutter by just specifying the path and extension once using the files-path tag. See the files-path and values usage below. Note that the display-values tag contains similar information but that is for the user to see.

0
{
enabled 1
property-visibility 1
name "Workflow Text: "
property-id "p_workflow"
description "Sets the Workflow"
kind "fx-replacement"
fx-replacement-type "texture-replacement-texture"
consist-property-sync 1
meshes "null"
effects "texture-extra"
asset "null"
files-path "images/,.texture"
values "congleton,burntisland,buxton,none"
default-index 0
trigger "user"
display-type "list"
display-values "Congleton,Burntisland,Buxton,None"
}
</td></tr></table>


<table width=1200><tr><td>
====Texture replacement using a texture-group library asset====
You will need to specify the texture group asset in the kuid-table and give it a name such as "texturelib" or "gwrtexturelib", The name should not have any spaces or other special characters.
This property container is set up to allow for three different variations of the the material used for the asset. They are named in the "display-values" tag as Skin 1, Skin 2, and Skin 3.
Since it is a PBR material there are three textures used in the materail: the albedo, parameters, and normal. The normal texture is common to all three versions so it need not be changed.
The "values" tag contains six numbers which are the numbers of the textures in the texture-group asset. For Skin 1 the "12" refers to the albedo texture, and the "15" refers to the parameter texture. "13" and "16" are the pair for Skin2, and "14" and "17" are the pair for Skin 3.
The "effects" tag contains the texture effect names for meshes in the mesh-table.
<br>

{
enabled 1
property-visibility 1
name "Weathering: "
property-id "p_skin"
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 "12;15,13;16,14;17"
default-index -1
trigger "user"
display-type "link"
display-values "Skin 1,Skin 2,Skin 3"
}
</td></tr></table>

== Event-Triggered Properties ==

<table width=1200><tr><td>
===loading-doorsProperty ===
The ‘meshes’ tag references a mesh-table asset named ‘loading-doors’, and sets the frame to 30 when begin-load is called (to open the doors), and 0 when end-load is called (to close the door). The default index is 0 (the animation frame will be at 0), and the animation duration is 1.5 seconds.
{
enabled 0
property-visibility 0
property-id "p_doors"
kind "mesh-attachment"
mesh-attachment-type "mesh-animation-frame"
meshes "loading-doors"
values "0,30"
trigger "event"
events "end-load,begin-load"
duration 1.5
default-index 0
}

An alternate way to do it is use mesh-attachment-type "mesh-animation-state", and set a bool int (0 or 1) for the values tag.
{
enabled 0
property-visibility 0
property-id "p_doors"
kind "mesh-attachment"
mesh-attachment-type "mesh-animation-state"
meshes "loading-doors"
values "0,1"
trigger "event"
events "end-load,begin-load"
default-index 0
}

If you want two doors to open at the same time, instead of creating another property, you can use a semicolon split in the values tag to change two in a single property:
{
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 "door-1,door-2"
values "0;0,30;30"
events "handbrake-release,handbrake-apply"
duration 3.0
default-index 0
trigger "both"
display-type "link"
display-values "release,apply"
}
</td></tr></table>


<table width=1200><tr><td>
===Weather-Based Texture Replacement===
The texture effect will change based on the weather. It will display a snowy texture when the weather type is 6 (medium snow), a wet, rainy texture when the weather type is 3 (rain), and a dry texture when the weather type is 0.
{
enabled 1
property-visibility 0
property-id "p_weather_skin"
kind "fx-replacement"
fx-replacement-type "texture-replacement-texture"
effects "texture-weather"
files-path "images/,.texture"
values "texture-snow,texture-rain,texture-dry"
default-index 0
trigger "event"
events "weather-6,weather-3,weather-0"
}
</td></tr></table>


<table width=1200><tr><td>
== Using semicolons to set multiple values in one property ==
When assigning values for a certain property, you will specify the mesh/effect/sound, etc that needs to be edited, and specify how you want to manipulate it (fx-replacement-type, mesh-attachment-type, etc), and set the value for a certain index. For example, In a texture replacement where a texture is being replaced by an external texture-group asset, the property would look something like this.

0
{
enabled 1
property-visibility 1
name "Skin: "
property-id "p_skin_parameter"
description "Sets The Texture"
kind "fx-replacement"
fx-replacement-type "texture-replacement"
effects "texture-albedo"
asset "texturelib"
values "1,2,3,4"
default-index -1
trigger "user"
display-type "link"
display-values "Skin1,Skin2,Skin3,Skin"
}

As you can see, the comma-separated numbers in the “values” tag indicate the index in the texture-group asset to find the texture; here are the first few lines for that. Texture indexes 0, 1, 2, and 3 are referenced for the albedo texture types, since we have 4 weathering types.

kuid <kuid2:661805:500009:0>
username "BR GrainHop Texture Group"
kind "texture-group"
trainz-build 5.0
category-class "JO"
author "dundun92"
contact-email "jbvector93@outlook.com"
description "A texture group for my GrainHop wagons"
textures
{
0 "270cgo/0albedo.texture"
1 "270cgo/1albedo.texture"
2 "270cgo/2albedo.texture"
3 "270cgo/2albedo.texture"
4 "270cgo/0parameter.texture"
5 "270cgo/1parameter.texture"
6 "270cgo/2parameter.texture"
.........
}

We specified the texture-group library in the kuid table, and referenced it in the “asset” tag.
kuid-table
{
acslib <kuid2:60850:89100>
meshlib <kuid2:661805:500002>
texturelib <kuid2:661805:500009>
lamp <kuid2:661805:500003>
enginespec <kuid2:368699:50064>
bogie <kuid2:661805:400003>
}

And then we specified the effect we wanted to change, (currently just the texture-albedo), inside the “effects” tag (this is not the effects tag below in this mesh table asset, but rather the one in the browser-properties at the top of this section!).
body
{
mesh "mesh/body.lm"
auto-create 1
att-parent "default"
effects
{
texture-albedo
{
kind "texture-replacement"
texture "covhopp-1_albedo.texture"
}
texture-normal
{
kind "texture-replacement"
texture "covhopp-1_normal.texture"
}
texture-parameter
{
kind "texture-replacement"
texture "covhopp-1_parameter.texture"
}
}
}

But say you want to replace the normal map as well. You would probably just create another browser property and specify the proper index for the normals.

0
{
enabled 1
property-visibility 1
name "Skin: "
property-id "p_skin_parameter"
description "Sets The Paramenter Texture"
kind "fx-replacement"
fx-replacement-type "texture-replacement"
effects "texture-albedo"
asset "texturelib"
values "1,2,3,4"
default-index -1
trigger "user"
display-type "link"
display-values "Skin1,Skin2,Skin3,Skin4"
}
1
{
enabled 1
property-visibility 1
name "Skin: "
property-id "p_skin_normal"
description "Sets The Normal Texture"
kind "fx-replacement"
fx-replacement-type "texture-replacement"
effects "texture-normal"
asset "texturelib"
values "7,8,9,10"
default-index -1
trigger "user"
display-type "link"
display-values "Skin1,Skin2,Skin3,Skin4"
}

But we can't forget the parameter map… that will require a third property. What's worse, we will now have three different properties in the view details page that will each have to be clicked on to change each map! Assigning properties this way can get tedious and create extra clutter in the config. Thankfully, for properties that share the same kind and type, it can all be done in a single property using semicolons:

0
{
enabled 1
property-visibility 1
name "Skin: "
property-id "p_skin"
description "Sets the weathering type"
kind "fx-replacement"
fx-replacement-type "texture-replacement"
meshes "null"
<b>effects "texture-albedo,texture-parameter,texture-normal"</b>
asset "texturelib"
files-path "null"
<b>values "0;4;8,1;5;9,2;6;10,3;7;11"</b>
default-index -1
trigger "user"
display-type "link"
<b>display-values "Clean,Weathered,Dirty,Rusty"</b>
}

Take note of the three tag entries above: the <b>effects</b>, <b>values</b> and <b>display-values</b> tags. The <b>display-values</b> tag is what the user sees and can choose from. Our interest is in the remaining two tags as shown below:

effects "texture-albedo,texture-parameter,texture-normal"
values "0;4;8,1;5;9,2;6;9,3;7;11"

There are four user options and, since each option requires three textures, the total number of textures is 12. The <b>values</b> tag contains a string of four groups of texture numbers separated by a comma. Within each texture group the texture numbers are delimited by a semi colon.

To clarify, we can list the three textures associated with each user choice:

0;4;8 -> Clean
1;5;9 -> Weathered
2;6;10 -> Dirty
3;7;11 -> Rusty

The first column of 0,1,2,3 identify the albedo textures. The second column of 4,5,6,7 identify the parameters textures, The third column of 8,9,10,11 identify the normal textures. Note that the numbers do not need to be in sequence or even consecutive. All those numbers do is to identify the correct texture in the texture-group asset.

This system works for other kinds of properties, too. In this case, we are setting the animation frame of both the handbrake-lever, and braking system at the same time using the same property (triggered by the same event).

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"
}

</td></tr></table>


<table width=1200><tr><td>
== Naming ACS mesh-table attachments ==
Please refer to this page on the ACS coupling system for setting up the “active-coupling-standard-60850” extensions container (which will be required for the ACS coupling to work): [[ACS_Coupling_System|ACS Coupling System]]

These are the mesh-table naming conventions you must use for the beginning of the name of each ACS attachment mesh. The others will vary depending on the “animated” property above. <b>You must spell them exactly as shown below</b>.

*coupler
*gangway
*airbrake
*vacbrake
*multiworking
*heating
*rch

If the “animated” tag in the acs container (see [[HowTo/WagonX_-_Technical_Reference#ACS|acs]]) is set to 1, then the naming is quite simple. It's one of the 7 callbacks above + a dash + “<i>front</i>” or “<i>back</i>”. The anim tag must be present to specify the animation for it. Frame 0 is the uncoupled state, and the last frame is the coupled state. This setup is shown below:

coupler-front
{
mesh-asset <kuid2:661805:500002>
mesh "coupler-screwlink-animated.lm"
anim "coupler-screwlink-animated_scene.kin"
auto-create 1
att "a.couple0"
att-parent "default"
}
coupler-back
{
mesh-asset <kuid2:661805:500002>
mesh "coupler-screwlink-animated.lm"
anim "coupler-screwlink-animated_scene.kin"
auto-create 1
att "a.couple1"
att-parent "default"
}
vacbrake-front
{
mesh-asset <kuid2:661805:500002>
mesh "vacbrake-single-animated.lm"
anim "vacbrake-single-animated_scene.kin"
auto-create 1
att "a.couple0"
att-parent "default"
}
vacbrake-back
{
mesh-asset <kuid2:661805:500002>
mesh "vacbrake-single-animated.lm"
anim "vacbrake-single-animated_scene.kin"
auto-create 1
att "a.couple1"
att-parent "default"
}

If, however, you do not want to use animations, but want to use separate meshes for each state (coupled and uncoupled), it gets a bit more complicated. The naming will follow the same as above at first, but you must add a third piece to it to specify the exact type of ACS attachment this is. The information on what to put there is originally from the [[ACS_Coupling_SystemACS Coupling System|ACS page]], but the 7 callbacks have been added plus the sub-callback here to make it easier (the third callback options are the ones with a delta symbol Δ ). And for the uncoupled state, the third callback is “non” (e.g. coupler-front-screwlink, and coupler-front-none).

*coupler
:*front/back
::Δ "<b>hook</b>" -- connects to screwlink/instanter/3link/hst-emergency-bar.
::Δ "<b>3link</b>" -- connects to hook.
::Δ "<b>instanter</b>" -- connects to hook.
::Δ "<b>screwlink</b>" -- connects to hook.
::Δ "<b>hst-emergency-bar</b>" -- connects to hook.
::Δ "<b>bar-full</b>" -- connects to "bar-none". Half of a handed pair for when one vehicle has the entire bar coupling.
::Δ "<b>bar-none</b>" -- connected to by "bar-full". The other half of the handed pair.
::Δ "<b>bar</b>" -- connects to self only. Used when both vehicles have half the bar coupling.
::Δ "<b>knuckle</b>" - standard knuckle coupler.
::Δ "<b>tightlock</b>" -- different from a standard knuckle, refers to a knuckle style coupler often fitted to multiple unit trains that also include electrical connections.
::Δ "<b>wedgelock</b>" -- London Underground coupler.
::Δ "<b>bsi</b>" -- Found on Sprinter DMUs and derived designs.
::Δ "<b>dellner</b>" -- Also compatible with Scharfenberg coupling.
::Δ "<b>scharfenberg</b>" -- Also compatible with dellner coupling.
::Δ "(<b>other string identifier</b>)" -- Any string that is not recognized from the above list is assumed to be a symmetrical meet-in-the-middle type of coupler.
::Δ “<b>none</b>”
::Examples: <b>coupler-front-instanter</b>, coupler-back-none

*gangway
:*front/back
::Δ <b>rubbing-plate</b>
::Δ <b>gangway</b>
::Δ <b>none</b>
::Example: <b>gangway-front-gangway</b>

*airbrake
:*front/back
::Δ <b>twin</b>
::Δ <b>single</b>
::Δ <b>none</b>
::Example: <b>airbrake-back-none</b>

*vacbrake
:*front/back
::Δ <b>twin</b>
::Δ <b>single</b>
::Δ <b>high</b>
::Δ <b>none</b>
::Example: <b>vacbrake-back-twin</b>

*multiworking
::front/back
::Δ "(color)-(shape)" -- e.g. "<b>blue-star</b>" or "<b>red-diamond</b>", etc
::Δ "<b>AAR</b>" -- as used on GM locos
::Δ "<b>SR27</b>" -- bagpipes
::Δ "(other identifier string e.g. classname)"
::Example: <b>multiworking-front-blue-square</b>

*heating
::front/back
::Δ "<b>none</b>"
::Δ "<b>steam</b>"
::Δ "<b>electric</b>"
::Δ "<b>dual</b>"
::Δ "<b>southern-electric</b>"
::Example: <b>heating-back-steam</b>

*rch
::front/back
::Δ "<b>high</b>"
::Δ "<b>low</b>"
::Δ "<b>none</b>"
::Example: <b>rch-back-high</b>

And an example how it would look inside a config.txt. The back attachments have been omitted for brevity.

coupler-front-screwlink
{
mesh-asset <kuid2:661805:500002>
mesh "coupler-screwlink-coupled.lm"
auto-create 1
att "a.couple0"
att-parent "default"
}
coupler-front-none
{
mesh-asset <kuid2:661805:500002>
mesh "coupler-screwlink-retracted.lm"
auto-create 1
att "a.couple0"
att-parent "default"
}
vacbrake-front-single
{
mesh-asset <kuid2:661805:500002>
mesh "vacbrake-single-coupled.lm"
auto-create 1
att "a.couple0"
att-parent "default"
}
vacbrake-front-none
{
mesh-asset <kuid2:661805:500002>
mesh "vacbrake-single-retracted.lm"
auto-create 1
att "a.couple0"
att-parent "default"
}

<table width=1200>
=Copyright Notice=
Much of the content on this page and child pages was derived from Dundun92's original Google Docs document. Permission was granted to use that information here.
</table>

File:Toggle handbrake mesh in View Details.jpg

2023-10-01T05:35:07Z

Pcas1986: Used in WagonX tutorials

Used in WagonX tutorials

File:Handbrake mesh show & hide.jpg

2023-10-01T05:32:02Z

Pcas1986: Used in WagonX tutorials

Used in WagonX tutorials