Class MeshObject

From TrainzOnline
(Difference between revisions)
Jump to: navigation, search
(→‎SetFXAttachment)
 
(→‎HasMesh: Prcisition for what the name is.)
 
(13 intermediate revisions by 6 users not shown)
Line 1: Line 1:
−
*[[TrainzScript Langage Reference|API Hierarchy]]
+
*[[TrainzScript Library Reference|API Hierarchy]]
 
**[[Class GSObject|GSObject]]
 
**[[Class GSObject|GSObject]]
 
***[[Class GameObject|GameObject]]
 
***[[Class GameObject|GameObject]]
Line 74: Line 74:
 
{{MethodHeader|public native bool HasMesh(string mesh)}}
 
{{MethodHeader|public native bool HasMesh(string mesh)}}
 
;Parameters
 
;Parameters
−
*'''mesh''' = the name of the mesh or submesh to be queried.
+
*'''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
 
;Returned Value
−
*None
+
*True if the mesh exists, otherwise false.
 
;Syntax
 
;Syntax
 
  if (HasMesh("ventilation")) StartMeshAnimationLoop("fans");
 
  if (HasMesh("ventilation")) StartMeshAnimationLoop("fans");
Line 101: Line 101:
 
*'''asset''' = mesh asset to attach to the effect. If asset is null any existing asset will be removed and nothing will be added.
 
*'''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
 
;Returned Value
−
*Returns a reference to the MeshObject which has been attached to the named effect.
+
*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
 
;Syntax
 
  MeshObject lamp = SetFXAttachment("lamp0",redlamp);
 
  MeshObject lamp = SetFXAttachment("lamp0",redlamp);
Line 143: Line 143:
 
*None
 
*None
 
;Syntax
 
;Syntax
−
  SetFXTextureReplacement("load","loadTextures",5);  // applies texture 5 from texture-group
+
  SetFXTextureReplacement("load",loadTextures,5);  // applies texture 5 from texture-group
 
  SetFXTextureReplacement("load",null,0);            // clears the effect, reinstating the texture defined in the asset.
 
  SetFXTextureReplacement("load",null,0);            // clears the effect, reinstating the texture defined in the asset.
 
;Notes
 
;Notes
 
*Use null in the textureGroup parameter to turn texture replacement off.
 
*Use null in the textureGroup parameter to turn texture replacement off.
 +
<br>
 +
 +
==SetFXTextureReplacementTexture==
 +
{{MethodHeader|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.
 
<br>
 
<br>
  
Line 160: Line 176:
 
;Notes
 
;Notes
 
*Shows the specified mesh and hides all other meshes.
 
*Shows the specified mesh and hides all other meshes.
 +
*If fadeDuration is 0.0 the mesh transition will be instantaneous.
 +
<br>
 +
 +
==SetMeshVisible==
 +
{{MethodHeader|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.
 
*If fadeDuration is 0.0 the mesh transition will be instantaneous.
 
<br>
 
<br>
Line 195: Line 225:
 
*The original speed is multiplied by the new speed factor.
 
*The original speed is multiplied by the new speed factor.
 
*Use negative values to make the animation run in reverse.
 
*Use negative values to make the animation run in reverse.
 +
*It is ''not'' compatible with SetMeshAnimationState function for the same mesh.
 
<br>
 
<br>
  
Line 213: Line 244:
 
<br>
 
<br>
  
−
==SetMeshVisible==
+
==SetMeshOrientation==
−
{{MethodHeader|public native void SetMeshVisible(string mesh, bool visible, float fadeDuration)}}
+
{{MethodHeader|public native void SetMeshOrientation(string meshName, float x, float y, float z)}}
 
;Parameters
 
;Parameters
−
*'''mesh''' = the name of the mesh or submesh to be displayed.
+
*'''meshName''' = name of the mesh to set the visibility of.
−
*'''visible''' = true to show the mesh, false to hide it.
+
*'''x,y,z''' = rotations about each axis for the new orientation (radians).
−
*'''fadeDuration''' = period in seconds during which mesh visibility will be faded in or out.
+
 
;Returned Value
 
;Returned Value
 
*None
 
*None
 
;Syntax
 
;Syntax
−
  SetMeshVisible("driver", false, 1.0);
+
  SetMeshOrientation("controllershunt",0,0.5,0);
 
;Notes
 
;Notes
−
*If fadeDuration is 0.0 the mesh transition will be instantaneous.
+
*Sets the orientation of the specified mesh relative to the object orientation or attachment point.
 +
<br>
 +
 
 +
==SetMeshTranslation==
 +
{{MethodHeader|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.
 
<br>
 
<br>
  
Line 231: Line 274:
 
;Parameters
 
;Parameters
 
*'''texture''' = root name of ''*.texture.text'' file to query.
 
*'''texture''' = root name of ''*.texture.text'' file to query.
−
*'''r,g,b''' = red green and blue components of self illumination value to apply, range 0 .. 1 where 1 is equal to 100%.
+
*'''r,g,b''' = red green and blue components of self illumination value to apply.
 
;Returned Value
 
;Returned Value
 
*None
 
*None
Line 237: Line 280:
 
  SetTextureSelfIllumination("interior",0.5,0.5,0.5);
 
  SetTextureSelfIllumination("interior",0.5,0.5,0.5);
 
;Notes
 
;Notes
−
*Applies an emissive component to the texture using the red, green and blue components specified.
+
*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.
 
*Compatibility warning: Use of this function is not recommended, it may become non-functional in future Trainz versions.
 
<br>
 
<br>
Line 279: Line 322:
 
  SwapTextureOnMesh("left-passenger-door","gwr","lms");
 
  SwapTextureOnMesh("left-passenger-door","gwr","lms");
 
;Notes
 
;Notes
 +
*'''Obsolete: Use SetFXTextureReplacementTexture instead.'''
 
*Swap one texture against another texture on specified mesh.
 
*Swap one texture against another texture on specified mesh.
 
*Similar to texture-replacement effects, but without the need for an extra texture asset.  
 
*Similar to texture-replacement effects, but without the need for an extra texture asset.  

Latest revision as of 22:25, 25 December 2023


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

[edit] MeshObject Messages

Messages related to MeshObject assets:


[edit] 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.


[edit] 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.


[edit] 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.


[edit] 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.


[edit] HasMesh

public native bool HasMesh(string mesh)
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


[edit] 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


[edit] 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.


[edit] 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.


[edit] 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.


[edit] 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.


[edit] 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.


[edit] 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.


[edit] 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.


[edit] 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.


[edit] 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.


[edit] 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.


[edit] 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.


[edit] 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.


[edit] 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.


[edit] 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


[edit] 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.


[edit] 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.


[edit] Code Examples

[edit] Related Methods

[edit] Categories

Retrieved from "https://online.ts2009.com/mediaWiki/index.php?title=Class_MeshObject&oldid=39519"
Personal tools