$FXSYSTEM

From HEWIKI
Jump to: navigation, search

Contents

Once you have created an FxSpec, you'll want to be able to play them from the various systems that you create. This is done via the $FXSYSTEM node.

$FXSYSTEM (client side)

The $FXSYSTEM node contains all the functions necessary to play an Fx. These functions are described below.

PlayFxFromSpec

The most basic method available to play an Fx. You need only pass it the specKey of the FxSpec you wish to play, along with two _Target classes for origin and target.

origin as class _Target
origin._tgtType = POSITION
origin._tgtPosition = "(0,0,0)"
 
destination as class _Target
destination._tgtType = POSITION
destination._tgtPosition = "(0,1,0)"
 
$FXSYSTEM.PlayFxFromSpec(1, origin, destination)

Once called, the will load the specified _FxSpec and once loaded it will be started (aka played). This is an asynchronous process. If the spec and its resources are already loaded, play will commence practically instantaneously.

Also important to note, if your Fx does not use either of the _Target classes, you still must pass them in, though they may be left uninitialized.

PlayDynFxFromSpec

Like PlayFxFromSpec with one additional parameter. With this method, you may pass in a lookuplist indexed by string of string which contains name/value pairs which are useful to your Fx. For example, if your have created an Arrow Fx which fires an arrow at a target, on the server your combat system determines if the attack is a hit or a miss and passes this data along with the request to fire an arrow. Your Fx is setup to listen for the name/value pair of HITTARGET=TRUE to play the arrow hitting its target effect, and HITTARGET=FALSE to play the arrow missing its target effect.

origin as class _Target
origin._tgtType = POSITION
origin._tgtPosition = "(0,0,0)"
 
destination as class _Target
destination._tgtType = POSITION
destination._tgtPosition = "(0,1,0)"
 
dynData as lookuplist indexed by string of string
 
dynData["HITTARGET"] = TRUE
 
$FXSYSTEM.PlayDynFxFromSpec(1, origin, destination, dynData)

PlayDelayedFxFromSpec

Like PlayFxFromSpec, with the added parameter of a delay time interval which, when called, starts a timer that waits the specified time before playing the Fx.

$FXSYSTEM.PlayDelayedFxFromSpec(1, origin, destination, 00:00:05.000) // waits 5 seconds before playing the Fx

PlayDelayedDynFxFromSpec

Like PlayDynFxFromSpec, with the added parameter of a delay time interval which, when called, starts a timer that waits the specified time before playing the Fx.

$FXSYSTEM.PlayDelayedDynFxFromSpec(1, origin, destination, dynData, 00:00:05.000) // waits 5 seconds before playing the Fx

PreloadDynFxFromSpec

This method loads the spec then loads all resources for the specified FxSpec, but does not play the Fx. This allows you to write appropriate preloader functions for those Fxs that you know will be needed soon but require quicker loading than load on demand.

A shared function is called when the Fx has completed loading. It passes in the FxGroup node created from the PreloadDynFxFromSpec call, giving you the opportunity to do stuff, then deleting the node (or not) once your are done.

scriptToCallback as scriptref = SYSTEM.INFO.THISSCRIPT
 
$FXSYSTEM.PreloadDynFxFromSpec(1, origin, destination, dynData, scriptToCallback)
 
shared function FxPreloadedFromSpec(fxg as NodeRef of Class _FxGroup) as Boolean
  // return true if you want to keep the Fxg node
  // return false to allow it to be deleted
  return false
.

Fx Handles

All of the above Play methods return an id, which is a handle that can be used to reference the FxGroup node created.

_GetFxGroupForHandle

Returns the FxGroup node for the specified Fx handle

var fxg = $FXSYSTEM._GetFxGroupForHandle(handleID)

Creation of the FxGroup node from a spec is asynchronous. It's possible to use the handle to retrieve the node before it has been created, thus getting a null node. If your script needs to guarantee it recieves a reference to the FxGroup node, the following functions may be used.

_InstantiateFxFromSpec

_InstantiateFxFromSpec will generate and return an ID for the specified FxSpec which your systems can keep track of and use to reference the FxGroup node (created asynchronously).

var handle = $FXSYSTEM._InstantiateFxFromSpec(fxSpecID, aListener)

This command does not start the Fx. It simple instantiates it. If you pass in a listener, the listener will recieve notification when the FxGroup is built (aka ready for use) passing in the FxGroup as the data node. You may then use any of the specified commands below to start the FxGroup node.

_PlayFxGroup

Allows you to start an already existing FxGroup node.

$FXSYSTEM._PlayFxGroup(fxGroupNode, theCaster, theTarget)

_PlayDynFxGroup

Allows you to start an already existing FxGroup node with the addition of passing in dynamic data.

$FXSYSTEM._PlayDynFxGroup(fxGroupNode, theCaster, theTarget, dynData)

_PlayDelayedFxGroup

Allows you to start an already existing FxGroup node after a specified time interval.

$FXSYSTEM._PlayDelayedFxGroup(fxGroupNode, theCaster, theTarget, delayAmount)

_PlayDelayedDynFxGroup

Allows you to start an already existing FxGroup node with dynamic data after a specified time interval

$FXSYSTEM._PlayDelayedDynFxGroup(fxGroupNode, theCaster, theTarget, dynData, delayAmount)


Example of using InstantiateFxFromSpec

function MyFunctionToPlayAnFx(theFxSpecID as ID)
  // Create a listener so we know when the FxGroup is created
  var listener = obsSubjectClassMethods:MakeScriptListener(SYSTEM.EXEC.THISSCRIPT, false)
  // call fx system to create the fx
  var handle = $FXSYSTEM._InstantiateFxFromSpec(theFxSpecID, listener)
  // Save the handle in some system that wants it here
.
shared function EventRaisedNotify( obsSubject as NodeRef of Class ObsSubject, obsListener as NodeRef of Class ObsListener, fxg as NodeRef )
  // verify existence of our FxGroup node
  if fxg <> none
    where fxg is kindof _FxGroup
      var caster = GetOurCaster()  // get the example caster of this spell
      var target = GetOurTarget()  // get the example target of this spell
      //
      // Do anything to or check anything on the FxGroup node then lets start it up
      //
      $FXSYSTEM._PlayFxGroup(fxg, caster, target)
    .
  .
.
function StopTheFxNow()
  var handle = GetTheHandleFromWhereeverWeStoredIt()
  var fxg = $FXSYSTEM._GetFxGroupForHandle(handle)
  if fxg <> none
    fxg.StopFxEvent() // to tell the FxGroup to stop, allowing normal shutdown
                      // Alternatively, fxg.DestroyFxGroup immediately kills all
                      // nodes that are part of the FxGroup node
  .
.

_Target class

The _Target class allows you to specify several different types of targets all in one simple class.

_tgtType specifies the kind of target being specified. This types are listed below.

SINGLENODE The target is a single node which you specify inthe  _tgtID field.
MULTINODE The target is any of several possible nodes, specified in the _tgtIDList field.
POSITION The target is a specific position in the world, specified in the _tgtPosition field.
MULTIPOSITION The target is any of several possible positions in the world, specified in the _tgtPositionList field.
LINE The target is a line between two specified points, _tgtStartPoint and _tgtEndPoint.
CIRCLE The target is a circle defined by _tgtCenterPoint and _tgtRadius.

Although the _Target class allows specifying complex positions, most individual fx tasks such as particle emitters, require a single position to be placed at. Thus when complex positions are specified, but a simple position is needed, the Fx system makes the following choices:

MULTINODE - The system chooses a random node from the given list of nodes.

MULTIPOSITION - The system chooses a random position from the given list of positions.

LINE - The system chooses the starting point of the line.

CIRCLE - The system chooses a random point within the circle.

Naturally, you may use scripting to make further use of complex targets.

$FXSYSTEM (server side)

If you want to play an fx on the client from a server script, the following four methods are available (each mimic the signature of their client-side counterparts).

SendFxToClient

accountID as ID           // the account ID which will recieve the fx play request
specKey as ID             // the ID of the FxSpec to be played
caster as class _Target   // target data for the origin of the fx
target as class _Target   // target data for the destination of the fx (if any)
 
$FXSYSTEM.SendFxToClient(accountID, specKey, caster, target)

SendDynFxToClient

accountID as ID           // the account ID which will recieve the fx play request
specKey as ID             // the ID of the FxSpec to be played
caster as class _Target   // target data for the origin of the fx
target as class _Target   // target data for the destination of the fx (if any)
 
dynData as lookuplist indexed by string of string
dynData["myvariable"] = "myvalue"    // add any number of dynamic data needed for your fx
dynData["myvariable2"] = "myvalue2"
 
$FXSYSTEM.SendDynFxToClient(accountID, specKey, caster, target, dynData)

SendDelayedFxToClient

accountID as ID           // the account ID which will recieve the fx play request
specKey as ID             // the ID of the FxSpec to be played
caster as class _Target   // target data for the origin of the fx
target as class _Target   // target data for the destination of the fx (if any)
 
delay as timeinterval     // amount of time to delay the start of this fx
 
$FXSYSTEM.SendDelayedFxToClient(accountID, specKey, caster, target, delay)

SendDelayedDynFxToClient

accountID as ID           // the account ID which will recieve the fx play request
specKey as ID             // the ID of the FxSpec to be played
caster as class _Target   // target data for the origin of the fx
target as class _Target   // target data for the destination of the fx (if any)
 
dynData as lookuplist indexed by string of string
dynData["myvariable"] = "myvalue"    // add any number of dynamic data needed for your fx
dynData["myvariable2"] = "myvalue2"
 
delay as timeinterval     // amount of time to delay the start of this fx
 
 
$FXSYSTEM.SendDelayedDynFxToClient(accountID, specKey, caster, target, dynData, delay)

See also

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox