Class MeshObject

From TrainzOnline
Revision as of 21:37, 4 January 2021 by S301 (Talk | contribs)

Jump to: navigation, search


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.



Contents

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


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.


Code Examples

Related Methods

Categories

Personal tools