HowTo/Build Passenger Enabled Assets

Revision as of 19:26, 26 February 2013

This is a transcription of a document by Auran created in 2004 to illustrate how to make stations and traincar vehicles support passengers.

I have attempted to bring the information up-to-date. PEV.

Passenger Station and Vehicle Assets Tutorial

This tutorial provides a brief overview to an example passenger station and passenger vehicle that are compatible with the passenger features supported by Trainz. For content creators wanting to make their own vehicles and stations passenger compatible, all the basic information to get started as well as a link to download functional example assets are provided.

Note

This tutorials does not cover how to create people assets for use as passengers. It uses the existing people provided with the simulator.

Passenger Station Asset

The passenger stations are a special class of Industry asset. In addition to the normal guidelines which apply when creating Industry assets, there are some items specific to Passenger Station assets. Each passenger station is composed of one or more platforms. Each platform requires the following:

• A track, for loading and unloading onto the platform.
• A trigger or triggers for detecting the presence of trains; these should be sufficient to cover the portion of the track which is usable for loading and unloading.
• A trigger at each end of the track to allow the scripts to determine when a train is at the end of the platform.
• An "on" queue and an "off" queue.
• A "spawn" process and a "delete" process.
• A string-table entry providing the name of the platform.

The triggers should be created such that overlap is minimized. Overlap between triggers on different platforms must specifically be avoided. The center point of each trigger is defined by an attachment point in the station’s mesh.

The radius of each trigger is defined in the config file in metres.

The mesh for this asset looks like:

Config.txt file

The most important tags required for a station’s config.txt are listed and discussed here. Note that although this section does cover some non-passenger specific tags as well as everything essential for passenger support, many common tags that are not specific to passengers will not be described.

username "Station Basic Example"

This provides the human-readable name of the station. You may also provide translated usernames in the usual fashion.

kind "industry"

We are describing an Industry asset.

kuid <kuid:-18:10236>

The KUID of this particular station asset; provide one in your own KUID range.

icon-texture "icon_brickstation.tga"

An icon for this station asset, used for the 'Drive To' command and similar. This is a 64x64 texture with no alpha channel.

script "Station"
class "Station"

The script file for this asset is "Station.gs", and contains a class named "Station".

kuid-table {
   passenger <kuid:-3:10060>
}

You must reference the passenger asset from your kuid-table, it is required for the passenger station script. As mentioned earlier, this tutorial doesn’t cover the creation of passenger characters.

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

There is a single mesh file for this asset, which contains both the geometry for the station and also the attachment points which are described throughout this document.

attached-track {
  track_0 {
    track  <kuid:-1:15>
    vertices {
      0      "a.track0a"
      ...
      4      "a.track0e"
    }
  }
}

A single section of track (which can be comprised of multiple vertices) must be specified for each platform. The passenger station script will reference this track.

attached-trigger {
  trigger_track_0_a {
    att      "a.track0a"
    radius   5
    track    "track_0"
  }
}

Triggers should be specified as appropriate to fill the above requirements. The passenger station script will reference these triggers.

queues {
  passengers_on_0 {
    passenger-queue    1
    size               80
    initial-count      8
    product-kuid       <kuid:-3:10060>
    attachment-points {
      0                "a.passon01"
      ...
      79               "a.passon80"
    }
  }
  passengers_off_0 {
    ...
  }
}

The "on" and "off" queues must be provided for each platform. These are used by the "spawn" and "delete" processes, and by the loading/unloading methods in the passenger station script. These queues must be named "passengers_on_X" and "passengers_off_X" respectively where X is the platform number.

The 'size' of each queue should match the actual number of attachment points allocated to the queue. The product-kuid should be set to the passenger asset, which is <kuid:-3:10060>.

Each passenger queue should also have the 'passenger-queue' tag set to 1. This tells Trainz that it should enable the sitting/standing checks for products in this queue.

Attachment points in a passenger queue may be flagged as ‘seated’ by having a name ending in “sitNN”, where “NN” is any two characters - usually two digits. Any passenger product attached to a ‘seated’ attachment point will be shown seated. On any other attachment point, the passenger will be shown standing.

It is normal that attachment points in the “on” queue are oriented to face the passengers towards the platform track, whereas attachment points in the “off” queue are oriented to face the passengers away from the platform track. See the Industry section of the CCG for more information regarding Queues.

processes {
  passenger_spawn_0 {
    start-enabled              1
    duration                   20
    outputs {
      0 {
        amount                 1
        queue                  "passengers_on_0"
      }
    }
  }
  passenger_delete_0 {
    ...
    inputs {
      0 {
        amount                 1
        queue                  "passengers_off_0"
      }
    }
  }
}

The "spawn" and "delete" processes must be provided for each platform. The "spawn" process duration will be overridden by the station script. The "delete" process duration may be specified (in seconds) but should be kept fairly short. The "delete" process must have an amount of 1 in order to work correctly. These processes must be named "passenger_spawn_X" and "passenger_delete_X" respectively where X is the platform number.

See the CCG/Kind:_Industry section of the CCG for more information regarding Processes.

string-table {
  brickstation_platform1 "Platform 1"
}

A name must be provided for each platform track on the station; these will be used by your station script.

The full config.txt updated to TS12 for this station asset is HERE

Station Script File

The station’s script derives from the GenericPassengerStation class. The complete functionality of a passenger station is already implemented for you in this class, the functions that you provide simply describe your station’s specific configuration. The following functions must be provided by you:

bool TriggerSupportsMassStoppedLoad(Vehicle vehicle, string triggerName)

This function determines whether the train (of which ‘vehicle’ is a member) should stop at the specified trigger. This is done by checking the direction of the train’s travel relative to the platform’s track, then ensuring that the train only stops at the end trigger in the appropriate direction. To allow for manual loading and unloading, if the train comes to a complete stop, any trigger will be accepted.

void GetTrackAndSide(Vehicle vehicle, string triggerName, TrackLoadInfo retInfo)

This function returns the track name and platform number for a particular trigger, as well as determining which side of the train (left or right) is actually being loaded.

public void Init(void) 

The Init() function must inherit() the parent initialisation function, then call the InitPassengerStation() function with the number of platforms that are at this station. After this is done, and any custom initialisation that you may wish to perform is complete, you should start the station main thread by calling StationMain().

public void AppendDriverDestinations(string[] destNames, string[] destTracks)

This is the normal industry function for providing ‘Drive To’ destination tracks. This should look up the string table and return the mappings between platform tracks and human-readable names.

The full TS12 "Station.gs" script for this station asset is HERE

Passenger Vehicle Asset

Passenger vehicles are not much different from normal Trainz vehicles that support loads. The only difference is that the guidelines for a passenger vehicle can be a bit more strict than usual. The only totally essential requirement to make a vehicle work with passengers is a passenger product queue. Things like transparent windows so you can see the passengers and door animations are optional, but certainly nice extras that make for a more interesting passenger experience.

Config.txt file

The most important tags required for a passenger vehicle’s config.txt are listed and discussed here. Note that although this section does cover some non-passenger specific tags as well as everything essential for passenger support, many common tags that are not specific to passengers will not be described.

kind "traincar"

This is a vehicle asset and not much different from other vehicles, so use “traincar” as you would for any vehicle.

kuid <kuid:-3:10069>

The KUID of this particular station asset; provide one in your own KUID range.

username "BR MK1 RMB"

This provides the human-readable name of the vehicle that it will be found under in the vehicles list in the Surveyor consist panel. You may also provide translated usernames in the usual fashion.

mesh-table {
  default {
    mesh            "mk1_rmb_br_bld_custd_body/mk1_rmb_br_bld_custd_body.lm"
    auto-create     1
  }
  left-passenger-door {
    mesh            "mk1_rmb_br_bld_custd_body/left_door/left_door.im"
    anim            "mk1_rmb_br_bld_custd_body/left_door/left_door.kin"
    auto-create 1
    att             "a.doors"
    att-parent      "default"
  }
  right-passenger-door {
    ...
  }
}

First in the mesh section is the vehicle’s main mesh. If you want passenger characters to be visible in your vehicle, then attachment points for them to sit/stand on will be required. This will be examined further in the queue section below.

In addition to the vehicle’s mesh, the animated doors are also defined here.

You will need to have separate sections with mesh/animation for both the left and right side of the vehicle. Which side is left and right is based on the vehicle’s sides relative to the vehicle’s forward direction. The sections for animated doors must be named “left-passenger-door” and “right-passenger-door” to work with the stations.

queues {
  passengers {
    size                44
    initial-count	  0
    passenger-queue      1
    product-kuid         <kuid:-3:10060>
    attachment-points {
      0                  "a.sitpoint5a"
      ...
      62                 "a.standpoint14"
    }
  }
}	

So the vehicle can carry passengers, queue is needed. The name of the queue isn’t important, as long as it’s there. :What is important is that the queue is capable of storing passengers.

For the queue to be able to carry passengers, the “passenger-queue” tag is set to 1 and the passenger product KUID of <kuid:-3:10060> is declared as being the product for this queue.

As each passenger is an individual person, enough attachment points for each passenger needs to be provided for.

Like the queues on a passenger station, the queue in a passenger vehicle follow the same attachment naming convention for sitting and standing passenger.

Attachment points in a passenger queue may be flagged as 'seated' by having a name ending in "sitNN", where "NN" is any two characters - usually two digits. Any passenger product attached to a 'seated' attachment point will be shown seated. On any other attachment point, the passenger will be shown standing.

Note: Stick to the "sitNN" convention as required by specification. By not following specification, you risk making your content incompatible with future versions of Trainz.

soundscript {
  door_open {
    trigger            "door_open"
    nostartdelay       1
    repeat-delay       1,0
    distance           5,170
    sound {
      0                "start.wav"
    }
  }
  door_close {
    trigger            "door_close"
    ...
  }
}

The optional soundscript section is used to have a sound file synchronised with animation events defined in the

door animations. This doesn’t relate directly to passenger station functionality and is simply a case of the animation triggering a sound for the “door_close” and “door_open” events.

The full config.txt updated to TS12 for this vehicle asset is HERE

Passenger Vehicle Scriptlet

No script code is required for the passenger vehicle to work. If you want to create something fancier beyond what you can get with by this example, then you may need to do write your own vehicle scriptlet for the passenger car.

Example File Listings

The original TRS2004 package is no longer available for download from N3V Games. A number of us still have this package and you can get it by requesting on the forum.

At the time of placing this page on this Wiki, Vinnybarb had this available HERE

The TRS2004 package contained the following example passenger assets

custom/scenery/Station_basic/

An 'invisible station' asset.

custom/scenery/small_station/

The 'Small Station' asset from Trainz. This is not part of the tutorial as such, but provided as an extra reference.

custom/vehicles/mk1_rmb_br_bld_custd/

The 'BR MK1 RMB' passenger vehicle asset.

max_files/

The 3D Studio Max 4 source files for the assets in this tutorial.

gmax_files/

The gmax source files for the assets in this tutorial.

Return to HowToGuides