Animation-Event Message

Revision as of 16:00, 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.

Event files

• Event files contain a list of the events you wish to intercept.
• 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");

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.

See Also

• FBX file format
• List of Standard Messages