CCG/Other Regularly Used Containers

From TrainzOnline
< CCG
Revision as of 10:01, 6 June 2011 by Pev (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Contents

Other Regularly Used Containers

Some containers are not present in every single kind, but appear across a number of different common kinds. The most common of these are detailed in this section.

Mesh Table

This is the preferred method of asset mesh reference for most mesh asset types. It gives good control over mesh placement, usage and animations.

There are some asset types that cannot use a Mesh Table. These include all Bridges, Tunnels, Rails, Pantographs and other Spline Objects (eg. Fences or Caternaries).

Important Note: Any asset that uses a mesh-table will not be compatible with pre-TRS 2004 versions of Trainz i.e. Ultimate Trainz Collection (UTC). TRS will of course still read UTC assets. Just remember that as with most major software releases, backwards compatibility is usually achievable, while forwards compatibility is often impossible.


Mesh tables allow you to specify main meshes (parent) and submeshes that may be attached to the main mesh, eg. night meshes. Attached meshes are placed at the origin of the parent mesh by default unless you specify an attachment point in the parent mesh, and reference it in the sub mesh entries - see below. Mesh Tables may contain the following tags and subcontainers:

anim
The animation file (.kin) exported from 3dsmax or gmax. This may include a sub-path. Refer to Chapter 8for more information.
auto-create
The mesh is generated (shown in Trainz) automatically when placed in a map or route. In some instances you don't want the mesh visible (as this may be controlled through script). If auto-create is 0, or the tag is missing, the mesh will not be visible when placed.
animation-loop-speed
This tag must be used 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. Different speed multiplying factors may be used, eg. 2, 0.5.
critical-animation
When enabled, this forces the animation to continue playing when off screen. It impacts on performance when enabled (can degrade frame rate).
use-parent-bounds
Specifies that the mesh should use the bounds of the parent object for visibility culling. Use with caution. Refer to Page 87 for more information.
att
The mesh (and animation if present) is inserted at a mesh attachment point rather than the origin of the parent mesh (default insertion point).
att-parent
The insertion attachment point is located within the mesh specified by `name' in this tag.
opacity
Controls the opacity of the mesh.
Zero (0 =invisible, not recommended) or one (1 = solid).
light
Sets lighting to be used for the object to be ambient or directional. 0 sets ambient lighting and object is lit by general light value, (uniformly lit). 1 sets directional light which is affected by the position of the sun, and the asset shows shaded faces, but not ground shadows.
test-collisions
This is an interior-specific mesh-table tag. When disabled, it prevents the mesh from obstructing the mouse (eg. if a mesh overlays a lever and should not be tested when the user clicks on a lever mesh for example). Enabled by default.
mesh
The `main' mesh name. This may include a sub-path (file within a subdirectory). i.e: mesh "nightwindows/nightwindows.im".
night-mesh-base
This night mesh is linked to the default mesh and is visible only when the `default' mesh is visible.
radius
radius for notches display, used for levers.
collision-parent
For collision-proxy meshes in an interior mesh-table, this specifies the parent object to be proxied (a substitute mesh that is not visible, but reacts to the mouse buttons to create an effect or animation - firebox doors opening for example).


Effects (optional mesh variables)

The effects containers are a subset of the Mesh Table Container. At the time of writing there are 4 distinct types of effects which are:

Name Effect, Corona Effect, Attachment Effect, and Animation Effect.

Name Effect

Some assets may have editable signs. When you set or change an asset's name in surveyor through the Edit Properties icon (`?' icon) the signage used as part of the model can be set-up to automatically update to the new name. The variables can be set for each sign.

kind
The effect kind.
att
The Sign Text insertion point (part of the mesh). See below for correct orientation of the point axis:
name
The default text when placed. If not used it will default to the config.txt `block' name and will not be editable. When "name name" is specified in the tag, it uses the asset's changeable name functions. If "name Coalmine" were used for instance, the name Coalmine would appear on the model and be unchangeable. font: The name of the font, default Arial. Other fonts are not functional at this time.
fontsize
The size of the sign text.
fontcolor
The colour of the sign text in r.g.b.


Corona Effect

A corona is a 'glow' light effect. It is a simple texture that is inserted at an attachment point within the mesh. Corona's can be added to any asset that uses a mesh-table.

Examples of coronas used in-game can be seen on the "Airport" and "Airport Basic" assets. The Jumbo Jet, the Cessna and the Airport tower all use flashing corona's.

kind
The effect kind.
att
The corona insertion point and centre (part of the mesh), eg a.light0, a.light1 for example.
directional
The default for coronas is to be aligned to the attachment point to face the NEGATIVE Z direction. This is especially useful for Traincars. Directional causes the effect to always face the user in Driver, and is therefore always visible.
frequency
This variable specifies the frequency in Hz (or `flashes' per second), eg. 1 for once per second, 0.5 for once every 2 seconds, 2 for twice in a second.
max-distance
Maximum distance to which the effect is visible.
object-size
Size of the corona on the object when viewed up close. Defaults to 0.15 (ie . 0.15m).
texture-kuid
Add this tag only when you want to specify your own texture for the corona. It specifies the KUID of a kind texture asset. If the texture-kuid tag is not present the corona will use the default yellow/orange texture in TRS. Alternatively, specify one of the Auran corona
textures
Yellow/orange corona Default (if no texture-kuid specified)
Green corona <KUID:-3:10110>
White corona <KUID:-3:10111>
Red corona <KUID:-3:10112>
wave-shift
Affects the flashing intensity pattern on the corona.


Texture Replacement Effect

This effect was created for rollingstock items to swap the visible texture of bulk loads (such as coal or woodchips). If a coal car is set up to take any bulk load (which includes woodchips) the `coal' texture on the load mesh will update to a `woodchips' texture when it loads woodchips.

kind
The effect kind.
texture
The replacement texture, for example gravel.tga.


Attachment Effect

In TRS we have the ability to attach a mesh into another mesh by referencing it's kuid through a mesh table. An example is the in-built fixed-track assets, where Red arrows visible in Surveyor indicate the ends of the fixed track segment. Rather than having an arrow mesh in each fixed-track asset directory, a lot of memory space is saved by making the fixed track asset reference the red arrow mesh kuid, and it only needs to be cached once. Using attached meshes should only be for kind scenery or kind mesh.

WARNING: Never cross-reference a kind attachment kuid with the assets own kuid, or an instant fatal error will occur.

kind
The effect kind.
att
The insertion point of the attached mesh, by default, the insertion point of the `default' mesh, a.mesh0 for example.
default-mesh
The KUID of the attached mesh.
surveyor-only
Adding this tag means the attached mesh will be only visible in Surveyor and not Driver.


Animation Effect

This effect is used when a mesh has a variety of animations. Usually the animations will be controlled by a script related to the asset.

An example of the kind animation effect is the PB15 interior Coalman. The script for this ties in the animations with the coal requirements of the steam locomotive.

kind
The effect kind.
anim
Reference to the animation file (name.kin).
looped
Use only if the animation is looping. Default 0 (i.e. not looped).1= looped.
speed
Speed factor of the animation. Default 1. 2 = Double speed.


Kinds that use the Mesh Table Container:

bogey, buildable, drivercharacter, fixedtrack, industry, interior, mesh, mocrossing, mojunction, mosignal, mospeedboard, pantograph, product, scenery-trackside, scenery, traincar, turntable.


Tracksound Container

The tracksound container stores information regarding custom tracksounds that can be attached to certain assets. These will play when a traincar crosses the specified track, or uses a specified bogey. The tracksound container contains the following tags:

track-sound
The kuid of the tracksound object to be used.
priority
The priority of the sound versus other sounds to be played. Lower values indicate a higher priority.
track
The track type to which this sound will apply.
track-parent
The parent (eg. bridge/industry/tunnel) of the track to which this sound will apply.
bogey
The bogey to which this sound will apply.

Kinds that use the Tracksound Container:

bogey, bridge, chunky-track, double-track, mesh-reducing-track, track, tunnel.

Refer also to the traincar tag disable-extra-track-sounds which disables the "click-clack" tracksounds, Page 87.


Soundscript Container

Soundscripts give ambient or directional sounds to objects. They cannot be used on track, bridge or spline objects. Wav files should be located within the same directory as the config.txt file.

The Soundscript Container contains the following tags and sub-containers:

repeat-delay
1 or 2 numbers (min, max, in seconds), time to delay between the end of the sound playing, and playing it again, randomised between (min .. max).
Default min = 0, default max = min distance value below.
distance
Two numbers (in meters). The first number is the distance at which the sound is played at 100%. The second number is the cut-off distance. It doesn't affect the volume of the sound. Default: 50m, 150m.
ambient
Ambient sounds have no 3d "position" and may be stereo. Non-ambient (positional) sounds are positioned on the object and must be mono.
attachment
Attachment point on the object to attach the sound to, a.sound0 for example.
nostartdelay
If not set, the sound will have a short delay before playing. This stops flanging (an objectionable sound caused when several copies of the same sound are played at once).
trigger
Currently used only for levers. The sound doesn't play until the trigger message happens.
value-range
Two numbers, currently used only for day/night sound effects. Midnight is 0.5, midday = 0.0 or 1.0. Where the numbers are not the same, this sets the start and end times for the sound to play. Default 0,0 (off).
volume
Gain of the sound. Default 1.0 = 100%.
sound
Filename (.wav file) of the sound to be played.


Kinds that use the Soundscript Container:

buildable, fixedtrack, industry, interior, mocrossing, mojunction, mosignal, mospeedboard, scenery-trackside, scenery, traincar, turntable.


Queue Container

The queues container states which product or products the industry can use. It contains the size of each product, the initial count when placed, and can refer to it's visual load state whether through a load animation or attachment.

Any load animations are set-up within the mesh-table.

The queue container contains the following tags:

size
Size of queue.
animated-mesh
Animated mesh which changes as the queue becomes full.
custom-attachments
Not used.
initial_count
The initial number of items or quantity in the queue.
passenger-queue
Not used.
product-kuid
The product type used to fill `initial-count'.
allowed products
The allowed products KUIDs in this queue.
conflicts-with-queues
This queue and the conflicting queue(s) cannot be used simultaneously.
attachment-points
List of attachment points for this queue on which products are visualised, use this, OR animated-mesh.
allowed-categories
The allowed product categories in this queue.


Kinds that use the Queue Container:

buildable, fixedtrack, industry, mocrossing, mojunction, mosignal, mospeedboard, scenery-trackside, scenery, traincar, turntable.


Smoke Container

More information on smoke and particle effects can be found in Chapter 10.

The Smoke Container allows the following tags:

attachment
The attachment point (stored in the mesh file) to place the smoke effect, a.smoke0 for example.
mode
Describes the mode or type of this smoke effect. This affects how start and period are interpreted. (time | speed | anim | timeofday|stack|lowpressurevalve).
color
Four values, the R,G,B colour value, and opacity, of the effect.


rate
The rate of emission in particles per second for modes time, speed, and timeofday, or the number of particles to emit over the animation period for anim mode. Default is 4.


velocity
The initial speed of emitted smoke particles. Default is 1.


lifetime
Time in seconds that smoke particles exist. Default is 3.
minsize
Start size of smoke particles. Default is 0.
maxsize
End size of smoke particles. Default is 3.
accel
Acceleration. A vector pointing in the direction of the sum of all forces affecting this smoke effect. Essentially, <z> describes gravity, and <x>, <y> describe the force of wind. Default is 0,0,0.
conesize
Conesize is a float array that can contain 1, 2 or 3 float values. It will define the size of the cone along the x y z axis. Imagine if the cone fitted in a cube, if you only use 1 float, it will assign that value to both x and y axis. If you use 2 values, it will use the different values for x, and y, and if you use 3 it will use all of them for the three axes x, y, z.

direction: The vector at which the smoke travels.

enabled
Specifies whether the effect is enabled or not.
endcolor
The final colour the smoke effect shifts to.
faces
The direction the smoke effect faces. (camera, motion, down)
file
The twinkle file to be used (optional).
inherit-velocity
A float for a smoke cone or steam emitter. This is to tell the particle that it will inherit the velocity of the emitter.
interpolate
A bool which is used for the steam emitter (refer to Chapter 3 for explanations of float and bool).
loop
Time in seconds to loop the smoke sequence. Only valid if mode is set to time.
loopdelay
Delay (in seconds) before the effect is played again.
maxrate
The maximum rate at which particles are emitted.
maxspeedkph
For a cone emitter, this will set the maximum velocity of the particles, in kph. When a particle is generated, it is set to a random velocity between minspeed and maxspeed or 0 and maxspeed.
minrate
The minimum rate at which particles are emitted.
period
The usage of period depends on the value of the mode tag. If the mode is set to time, period is the duration of time this effect will remain active. If mode is set to anim, period is a value from 0.0 to 1.0 that describes the duration over which the effect is active. Start + period must not exceed 1.0. In all modes, period can be set to -1 (default) to imply the phase is active until the next phase begins.
scale
For the emitter is the scale of the emitter or the scale of the particle.
shift
Speeds up the age of the particle (how old they are which makes them die/disappear faster).
start
The usage of start depends on the value of the mode tag. If the mode is set to time, start is a set of time values in seconds after the creation of this effect's parent object when this phase of the effect will start.
If the mode is set to speed, start is a speed in meters per second (m/s) and period is not used. (Note: 1 m/s =3.6 km/hr.) All other sequence attributes (rate, velocity, lifetime, minsize, maxsize) are interpolated as there are smooth transitions between phases.
If the mode is set to anim, start is a value from 0.0 to 1.0 which describes the start time into the object's animation cycle.
If the mode is set to timeofday, start is a value from 0.0 to 1.0 which describes the time of day when this effect will start.
Values range as follow:
0 - midnight, 0.25 - 6am, 0.5 - midday, 0.75 6pm, 1.0 - midnight.
texture
Kuid of the texture to be used for the effect.

Kinds that use the Smoke Container:

buildable, fixedtrack, industry, mocrossing, mojunction, mosignal, mospeedboard, scenery-trackside, scenery, traincar, turntable.

Refer to Chapter 10 for further explanation and examples of smoke container use.


Return to CCG Index

Content Creator's Guide

Personal tools