Animation-Event Message

From TrainzOnline
(Difference between revisions)
Jump to: navigation, search
(Rework to remove references to IM files and some clarification)
(Removed duplicated information)
 
Line 1: Line 1:
Animation events are used to initiate some action, such as smoke effects, during an animation cycle that can be detected by script. This is a different mechanism from Sound_Event, which interfaces with a ''soundscript'' container in config.txt and does not require scripting.
+
Animation events are used to initiate some action, such as smoke effects, during an animation cycle that can be detected by script. This is a different mechanism from Sound_Event, which interfaces with a [["Soundscript" container]] in config.txt and does not require scripting.
 
When an animation event occurs, the game engine will post a message in the form:
 
When an animation event occurs, the game engine will post a message in the form:
 
"<major>, <minor>"  
 
"<major>, <minor>"  
 
where the major part of the message is always "Animation-Event" and the minor part is a message of your choice.
 
where the major part of the message is always "Animation-Event" and the minor part is a message of your choice.
  
Event files  
+
The structure and format of event files can be found here: [[FBX file format]]
  
* Event files contain a list of the events you wish to intercept.
+
To use the posted message you should define a handler using:
* The name of the event file must match the name of an animation (kin) file and are plain text files with an ".evt" extension.
+
* The file should contain one or more event lines in the form:
+
 
+
::<frame number> “Generic_Event” <minor message> 
+
::<frame number> “Generic_Event” <minor message>
+
 
+
* Some 3D Editors may be capable of producing of producing event files automatically.
+
 
+
* The first item is a frame number that should be in the range 000..999.
+
* The second item is a name such as "Generic_Event".  This value appears to be ignored by Trainz.
+
* The third item will be the minor part of the message and the identifier used in your script as shown below.
+
 
+
Sample event file:
+
 
+
002 Generic_Event animstart
+
045 Generic_Event do-something
+
089 Generic_Event animstop
+
 
+
* This example will result in the messages:
+
:: ''Animation-Event, animstart'' being sent by the game whenever the animation plays past frame 2.
+
:: ''Animation-Event, do-something'' whenever the animation plays past frame 45; and
+
:: ''Animation-Event, animstop'' whenever the animation plays past frame 89.
+
 
+
* It is best to avoid issuing events on the first or last frames since these are not always converted reliably into messages.
+
 
+
* To use the posted message you should define a handler using:
+
  
 
  AddHandler(me,"Animation-Event","","AnimationHandler");
 
  AddHandler(me,"Animation-Event","","AnimationHandler");
Line 45: Line 19:
 
  }
 
  }
  
* In practice the game engine often issues duplicate messages so you will need to ensure that you are not responding more often than necessary. One way of doing this is to use a boolean variable to keep track of what your script is doing and use this to ignore duplicating script actions.
+
In practice the game engine often issues duplicate messages so you will need to ensure that you are not responding more often than necessary. One way of doing this is to use a boolean variable to keep track of what your script is doing and use this to ignore duplicating script actions.
  
  

Latest revision as of 16:18, 3 July 2020

Animation events are used to initiate some action, such as smoke effects, during an animation cycle that can be detected by script. This is a different mechanism from Sound_Event, which interfaces with a "Soundscript" container in config.txt and does not require scripting. When an animation event occurs, the game engine will post a message in the form: "<major>, <minor>" where the major part of the message is always "Animation-Event" and the minor part is a message of your choice.

The structure and format of event files can be found here: FBX file format

To use the posted message you should define a handler using:

AddHandler(me,"Animation-Event","","AnimationHandler");
void AnimationHandler(Message msg) {
   if (msg.minor == "animstart") 
     Interface.Print("Animation has started");   //action for the animstart event
   else if (msg.minor == "do-something") 
     Interface.Print("Do something here");      //action for the do-something event
   else if (msg.minor == "animstop") 
     Interface.Print("Animation has completed"); //action for the animstop event
}

In practice the game engine often issues duplicate messages so you will need to ensure that you are not responding more often than necessary. One way of doing this is to use a boolean variable to keep track of what your script is doing and use this to ignore duplicating script actions.


[edit] See Also

Personal tools