Per frame callback

Jump to: navigation, search
See also: TIMER

Often it is desirable for the client to call one or more script functions/methods every frame. These are called per-frame callbacks.


There are two paradigms for producing a per-frame callback - as a procedural function in a script, or as a class method call on a particular node.

Procedural function

When setting up a script for per-frame callbacks, simply call the following external function.

RegisterForPerFrameCallback( s as ScriptRef )

On the following frame and each frame there after, this function will be called in the script:

function onFrameUpdate(elapsed as TimeInterval)

If the script does not contain this function, you will get per-frame script errors instead. The "elapsed" parameter that is passed in is a TimeInterval variable containing the amount of time since the last frame. In the case of the first such function call, this will be the time from when the script was registered for per frame callbacks. This callback will continue every frame until the script is unregistered:

UnregisterForPerFrameCallback( s as ScriptRef )

It's important not to leave conditions where you're done with the callbacks but they continue to happen, as this is unnecessary and can be quite resource intensive.

Method callback

Using a per-frame method call on a node is quite similar to the procedural system above. Again, we begin the callbacks with an external function:

RegisterForPerFrameMethodCallback( n as NodeRef )

Note the slight difference in function name (PerFrameCallback vs. PerFrameMethodCallback) and parameter. Note: Passing in a null noderef will do nothing, since nodes that do not exist are automatically removed.

Each frame thereafter, the node will receive the following method callback:

method onFrameUpdate(elapsed as TimeInterval)

As before, no such method on the node will result in lots of errors.

Finally, when you no longer require per-frame method calls, unregister the node:

UnRegisterForPerFrameMethodCallback( nID as ID )

If the node is destroyed without being unregistered manually, it is automatically unregistered.

Personal tools