Class 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
- 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
- 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
- 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
- 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
- Parameters
- mesh = the name of the mesh or submesh to be queried. This is the tagnamestring from the configs mesh-table subsouptag for the fitting mesh.
- Returned Value
- True if the mesh exists, otherwise false.
- Syntax
if (HasMesh("ventilation")) StartMeshAnimationLoop("fans");
- Notes
SetFXAnimationState
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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, 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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.