Class MeshObject

API Hierarchy
- GSObject
  - GameObject
    - PropertyObject
    - TrainzGameObject
      - MeshObject

This is a base class for Asset based game objects that have meshes, effects, animations and particles. Interface methods to deal with these are provided so things like showing or hiding a mesh, attaching a mesh to an attachment point or controlling an animation can be done from a script.

For animation Trainz interpolates between key frames. This means an intermediate animation frame is calculated dynamically to be-in-synch with the game's framerate.

Trainzscript is an interpreted scripting language intended to be used to monitor and react to events in the Trainz world, not to perform sophisticated real-time animation tasks. Using a script to start an animation in response to an event in a thread is reasonable. However trying to control animation tightly down to short intervals is likely to provide unsatisfactory results and to adversely affect overall performance of the game.

MeshObject Messages

Messages related to MeshObject assets:

GetFXAttachment

public native MeshObject GetFXAttachment(string effect)

Parameters

effect = name of the mesh effect to query.

Returned Value

Returns a reference to the MeshObject currently attached to the named effect.

Syntax

MeshObject attachment = GetFXAttachment("coupler");

Notes

The method returns null if the effect is unoccupied.

GetMeshAnimationFrame

public native float GetMeshAnimationFrame(string mesh)

Parameters

mesh = the name of the mesh or submesh container which includes the animation file to be queried.

Returned Value

Current fame of the animation file within the specified mesh container.

Syntax

float height = GetMeshAnimationFrame("zPosition")

Notes

Note that the returned value is likely to be an interpreted floating point value.

GetMeshAnimationFrameCount

public native float GetMeshAnimationFrameCount(string mesh)

Parameters

mesh = the name of the mesh or submesh container which includes the animation file to be queried.

Returned Value

The number of frames in the specified animation.

Syntax

float positions = GetMeshAnimationFrameCount("lever");

Notes

Note that the returned value is a float rather than an integer.

GetTextureSelfIlluminationState

public native bool GetTextureSelfIlluminationState(string texture)

Parameters

texture = root name of *.texture.text file to query.

Returned Value

Returns true if the specified texture has self illumination set.

Syntax

bool isEmissive = GetTextureSelfIlluminationState("texture");

Notes

Compatibility warning: Use of this function is not recommended, it may become non-functional in future Trainz versions.

HasMesh

public native bool HasMesh(string mesh)

Parameters

mesh = the name of the mesh or submesh to be queried.

Returned Value

None

Syntax

if (HasMesh("ventilation")) StartMeshAnimationLoop("fans");

Notes

SetFXAnimationState

public native void SetFXAnimationState(string effect, bool state)

Parameters

effect = name of attached-animation effect containing the animation to play.
state = true to start the animation loop, false to stop.

Returned Value

None

Syntax

if (gateClosed) SetFXAnimationState("gate",false);

Notes

SetFXAttachment

public native MeshObject SetFXAttachment(string effect, Asset asset)

Parameters

effect = effect containing the attachment to be manipulated.
asset = mesh asset to attach to the effect. If asset is null any existing asset will be removed and nothing will be added.

Returned Value

Returns a reference to the MeshObject which has been attached to the named effect. If the mesh asset isn't "kind mesh", returns null.

Syntax

MeshObject lamp = SetFXAttachment("lamp0",redlamp);

Notes

Returns null if the effect is unoccupied when the method returns.

SetFXCoronaTexture

public native void SetFXCoronaTexture(string effect, Asset texture)

Parameters

effect = effect containg the corona to be manipulated.
asset = corona texture asset to attach to the effect. If asset is null the corona will be turned off.

Returned Value

None

Syntax

SetFXCoronaTexture("stopLight",redCorona);

Notes

Other corona parameters such as frequency and size are defined in config.txt and cannot be altered by script code.

SetFXNameText

public native void SetFXNameText(string effect, string text)

Parameters

effect = effect containg the name effect to be changed.
text = new string value.

Returned Value

None

Syntax

SetFXNameText("home","Shangri-La");

Notes

Method will not accept an empty string in the text parameter.

SetFXTextureReplacement

public native void SetFXTextureReplacement(string effect, Asset textureGroup, int index)

Parameters

effect = texture-replacement effect to be changed.
textureGroup = reference to texture group asset which is the source of the texture to be applied.
index = index into textures table of texture-group indicating which texture to apply.

Returned Value

None

Syntax

SetFXTextureReplacement("load",loadTextures,5);   // applies texture 5 from texture-group
SetFXTextureReplacement("load",null,0);             // clears the effect, reinstating the texture defined in the asset.

Notes

Use null in the textureGroup parameter to turn texture replacement off.

SetFXTextureReplacementTexture

public native void SetFXTextureReplacementTexture(string effectName, string textureName)

Parameters

effectName = the name of the texture-replacement effect that is in the effects container of the mesh.
textureName = the *.texture.txt file that will replace the current texture being used on the mesh.

Returned Value

None

Syntax

SetFXTextureReplacementTexture("fk_parameter","lms_p3_fk_body/fk_parameter.texture");

Notes

This should replace any instance of SwapTextureOnMesh.
Unlike SwapTextureOnMesh, there is no need to mention what the previous texture being used was. Simply telling Trainz to load the new texture is all that is needed for this to work.
Swap one texture against another texture on specified mesh.
Similar to texture-replacement effects, but without the need for an extra texture asset.

SetMesh

public native void SetMesh(string mesh, float fadeDuration)

Parameters

mesh = the name of the mesh or submesh to be displayed.
fadeDuration = period in seconds during which mesh visibility will be faded in or out.

Returned Value

None

Syntax

SetMesh("default",0.5);

Notes

Shows the specified mesh and hides all other meshes.
If fadeDuration is 0.0 the mesh transition will be instantaneous.

SetMeshVisible

public native void SetMeshVisible(string mesh, bool visible, float fadeDuration)

Parameters

mesh = the name of the mesh or submesh to be displayed.
visible = true to show the mesh, false to hide it.
fadeDuration = period in seconds during which mesh visibility will be faded in or out.

Returned Value

None

Syntax

SetMeshVisible("driver", false, 1.0);

Notes

If fadeDuration is 0.0 the mesh transition will be instantaneous.

SetMeshAnimationFrame

public native void SetMeshAnimationFrame(string mesh, float frame)
public native void SetMeshAnimationFrame(string mesh, float frame, float period)

Parameters

mesh = the name of the mesh or submesh container which includes the animation file to be manipulated.
frame = the frame position to which the animation is to be moved, this may be an interpolated value.
period = the period over which the animation will be moved from its current position to the newly specified point.

Returned Value

None

Syntax

SetMeshAnimationFrame("default",5.0);      // move the animation to frame 5 instantaneously
SetMeshAnimationFrame("default",5.0,2.0);  // move the animation to frame 5 over 2 seconds

Notes

Moves the specified animation to the specified frame.
For the first variant the transition is instant.
For the second variant the transition will complete during the specified period.

SetMeshAnimationSpeed

public native void SetMeshAnimationSpeed(string mesh, float speed)

Parameters

mesh = the name of the mesh or submesh container which includes the animation file to be manipulated.
speed = multiplication factor to apply to the original animation speed.

Returned Value

None

Syntax

SetMeshAnimationSpeed("fans",2.0);   // run fans at double speed
SetMeshAnimationSpeed("fans",-1.0);  // run fans backwards at original speed

Notes

Modifies the speed at which the animation is played.
The original speed is multiplied by the new speed factor.
Use negative values to make the animation run in reverse.
It is not compatible with SetMeshAnimationState function for the same mesh.

SetMeshAnimationState

public native void SetMeshAnimationState(string mesh, bool state)

Parameters

mesh = the name of the mesh or submesh container which includes the animation file to be played.
state = the direction in which the file is to be played, true for forwards, false for backwards.

Returned Value

None

Syntax

SetMeshAnimationState("door",true);    // opens the door
SetMeshAnimationState("door",false);   // closes the door

Notes

This method plays animations and is best suited to those which have defined start and end points such as the opening and closing of a gate or door.
If state is true the animation plays forwards from its current position to the last frame. If the current position is already at the last frame the call has no effect.
If state is false the animation plays backwards from its current position to the first frame. If the current position is already at the first frame the call has no effect.

SetMeshOrientation

public native void SetMeshOrientation(string meshName, float x, float y, float z)

Parameters

meshName = name of the mesh to set the visibility of.
x,y,z = rotations about each axis for the new orientation (radians).

Returned Value

None

Syntax

SetMeshOrientation("controllershunt",0,0.5,0);

Notes

Sets the orientation of the specified mesh relative to the object orientation or attachment point.

SetMeshTranslation

public native void SetMeshTranslation(string meshName, float x, float y, float z)

Parameters

meshName = the name of the mesh or submesh to be displayed.
x, y, z = new position in the coordinate axis.

Returned Value

None

Syntax

SetMeshTranslation("controllershunt",0,0,0);

Notes

Sets the translation of the specified mesh relative to the object origin or attachment point.

SetTextureSelfIllumination

public native void SetTextureSelfIllumination(string texture, float r, float g, float b)

Parameters

texture = root name of *.texture.text file to query.
r,g,b = red green and blue components of self illumination value to apply.

Returned Value

None

Syntax

SetTextureSelfIllumination("interior",0.5,0.5,0.5);

Notes

Applies a material emissive color to materials that use the texture, using the red, green and blue components specified.
Compatibility warning: Use of this function is not recommended, it may become non-functional in future Trainz versions.

StartMeshAnimationLoop

public native void StartMeshAnimationLoop(string mesh)

Parameters

mesh = the name of the mesh or submesh container which includes the animation file to be played.

Returned Value

None

Syntax

StartMeshAnimationLoop("windmill");

Notes

This method plays animations and is best suited to those which are designed to run in a continuous loop.
The speed of the animation can be altered using SetMeshAnimationSpeed()
Using SetMeshAnimationSpeed() with a negative value will cause the animation to play in reverse.
StopMeshAnimation() will halt the animation.

StopMeshAnimation

public native void StopMeshAnimation(string mesh)

Parameters

mesh = the name of the mesh or submesh container which includes the animation file to be stopped.

Returned Value

None

Syntax

StopMeshAnimation("default");

Notes

Turns animation off for the specified mesh.

SwapTextureOnMesh

public native void SwapTextureOnMesh(string mesh, string oldTexture, string newTexture)

Parameters

mesh = the name of the mesh or submesh container which includes the texture to be changed.
oldTexture = the original *.texture.txt file to use as the source of the transition.
newTexture = the new *.texture.txt file to apply.

Returned Value

None

Syntax

SwapTextureOnMesh("left-passenger-door","gwr","lms");

Notes

Obsolete: Use SetFXTextureReplacementTexture instead.
Swap one texture against another texture on specified mesh.
Similar to texture-replacement effects, but without the need for an extra texture asset.
possible bug Texture names in the .im file must be lower case for this function to work properly.