Fx Control Script Callbacks

Jump to: navigation, search

It is possible to add a script to any Fx, to receive all the events from the Fx being played. The scripter can then hook in custom systems to be fired on specific FxEvents.


Specifying a script for an Fx

The top level Fx, known as the FxGroup, has a property named Control Script. Set this to the name of your script. When the Fx is played, events generated by the Fx are also sent to this script.

Fx script callbacks

Two shared functions exist for use with playing an Fx.


shared function OnFxGroupPreStart(theFxGroup as NodeRef of Class _FxGroup)
  // -------------------------------------------------------------
  // Called just before the fx begins, passing in the entire group
  // which allows you to modify anything within however you like
  // -------------------------------------------------------------


shared function EventOccurance(eventType as Enum fxEvents, fxName as String, theFxGroup as NodeRef of Class _FxGroup)
  // ----------------------------------------------------------------
  // Each event is sent to this function with the event name, name of
  // the task which caused the event, and the top level FxGroup node


ONFXSTARTOccurs when a task is started.
ONFXSTOPOccurs when a task ends. Some tasks are instantaneous (attachers, animation commands) and do not generate this event.
ONFXTIMEOUTThe top level FxGroup and Fx container tasks can specify an interval to wait from their start, to timeout. When a timeout occurs, all children are stopped. When the top level FxGroup times out, the fx is deleted.
ONFXTICKOccurs only when the top level FxGroup or Fx container is set to timertype TICKER. This event will occur at each specified interval. A tally of the ticks is stored in the _fxTickCounter field.
ONTARGETACHIEVEDOccurs only when an FxEmitter is told to chase a target, and the emitter reaches that target.
ONCOLLIDEOccurs when a particle of particle emitter collides with mesh. Along with the event, the following information becomes available on the FxEmitter task.


Care should be taken using this event, for the event each time a particle from the emitter collides, potentially causing hundreds of events depending on the particle effect used.
ONANIMATIONNOTEOccurs only if an animation cmd is used. Any note tracks embedded in the animation being played can be listened for.
ONTRANSFORMREVERSEOccurs when an FxTransformer reverses direction (if told to do so).
ONTRANSFORMREPEATOccurs when an FxTransformer repeats its transform (when given a repeat count greater than 1)
ONTRANSFORMARCAPEXOccurs when an FxTransformArc reaches the very top middle of it's arc path.
ONMODELFADERREVERSEOccurs when and if a FxModelFader reverses its fade
ONMODELFADERREPEATOccurs when and if a FxModelFader repeats it's fade


In this example, we want to check the passed in target, and if it's a character, reposition a particle effect to appear slightly above it, where it is not a character, we leave it to appear at the target's center point.

shared function OnFxGroupPreStart(theFxGroup as NodeRef of Class _FxGroup)
  t as Class _Target = theFxGroup ._fxTarget
  targetNode as noderef of class hbnode = t._tgtID
  if targetNode["Type"] = "Character"
    var fxt = fxg.FindFxTaskByName("halo")
    if fxt <> None
      where fxt is kindof _Fx3DController      
        fxt._fxStartLocOffset = (0,0.2,0)

In this example, we want to wait for a lightning effect to end, then display a chat message.

shared function EventOccurance(eventType as Enum fxEvents, fxName as String, theFxGroup as NodeRef of Class _FxGroup)
  if eventType = ONFXSTOP and fxName = "LightningBolt"
    $CHAT._GotChatMessage("The lightning has destroyed the target.", "")
Personal tools