FxAnimation

This module provides functions for animating node properties. To animate a node property a channel is required. To create a channel for a property, use CreateChannel. Once a channel is created, it can be identified by NodeID and NodeProperty to edit keyframes.

Load

FxAnimation = require "FxAnimation";

Functions

Function	Description
ClearChannel (NodeID, NodeProperty)	Deletes all keyframes in a channel.
CreateChannel (NodeID, NodeProperty)	Creates a channel for a property.
CreateKey (NodeID, NodeProperty, Frame)	Creates a keyframe.
DeleteChannel (NodeID, NodeProperty)	Deletes a channel.
DeleteKey (NodeID, NodeProperty, Frame)	Deletes a keyframe in a channel.
Get1b (NodeID, NodeProperty, Frame) Get1c (NodeID, NodeProperty, Frame) Get1f (NodeID, NodeProperty, Frame) Get1i (NodeID, NodeProperty, Frame) Get1s (NodeID, NodeProperty, Frame) Get2b (NodeID, NodeProperty, Frame) Get2f (NodeID, NodeProperty, Frame) Get2i (NodeID, NodeProperty, Frame) Get3b (NodeID, NodeProperty, Frame) Get3f (NodeID, NodeProperty, Frame) Get3i (NodeID, NodeProperty, Frame)	Return the interpolated value at a frame.
GetChannelEnabled (NodeID, NodeProperty)	Checks if a channel is enabled.
GetChannelInterpolation (NodeID, NodeProperty)	Returns the interpolation mode of a channel.
GetEasing (NodeID, NodeProperty, Frame)	Returns the easing function used at a frame.
GetNextKey (NodeID, NodeProperty, Frame)	Returns the frame number of the next keyframe.
GetPrevKey (NodeID, NodeProperty, Frame)	Returns the frame number of the previous keyframe.
MoveKey (NodeID, NodeProperty, FrameFrom, FrameTo)	Moves keyframes.
SetChannelEnabled (NodeID, NodeProperty, Value)	Sets the enabled state of a channel.
SetChannelInterpolation (NodeID, NodeProperty, Value)	Sets interpolation mode of a channel.
SetKey1b (NodeID, NodeProperty, Frame, Value) SetKey1c (NodeID, NodeProperty, Frame, Value) SetKey1f (NodeID, NodeProperty, Frame, Value) SetKey1i (NodeID, NodeProperty, Frame, Value) SetKey1s (NodeID, NodeProperty, Frame, Value) SetKey2b (NodeID, NodeProperty, Frame, X, Y) SetKey2f (NodeID, NodeProperty, Frame, X, Y) SetKey2i (NodeID, NodeProperty, Frame, X, Y) SetKey3b (NodeID, NodeProperty, Frame, X, Y, Z) SetKey3f (NodeID, NodeProperty, Frame, X, Y, Z) SetKey3i (NodeID, NodeProperty, Frame, X, Y, Z)	Set the values of a keyframe.
SetKeyEasing (NodeID, NodeProperty, Frame, Value)	Sets the easing function of a keyframe.

ClearChannel (NodeID, NodeProperty)

This function deletes all keyframes in a channel.

Parameters

• NodeID: NodeID
• NodeProperty: NodeProperty

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND, FX_PROPERTY_INVALID, FX_REQUIRED_CHANNEL_UNAVAILABLE

Since

Version 1.0

Example

-- delete all channel keyframes of the translate property of object1 
FxAnimation.ClearChannel("object1", "translate");

CreateChannel (NodeID, NodeProperty)

This function creates a channel for the node's property. There can be only one channel per property.

Parameters

• NodeID: NodeID
• NodeProperty: NodeProperty

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND, FX_PROPERTY_INVALID

Since

Version 1.0

Example

-- add a channel for the translate property of object1
FxAnimation.CreateChannel("object1", "translate");

CreateKey (NodeID, NodeProperty, Frame)

This function creates a keyframe at the specified frame number.

Parameters

• NodeID: NodeID
• NodeProperty: NodeProperty
• Frame: Frame number

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND, FX_PROPERTY_INVALID, FX_VALUE_INVALID

Since

Version 1.0

Example

-- add a keyframe at frame 5 to the translate property of object1 
FxAnimation.CreateKeyframe("object1", "translate", 5);

DeleteChannel (NodeID, NodeProperty)

This function deletes the channel of a node property.

Parameters

• NodeID: NodeID
• NodeProperty: NodeProperty

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND, FX_PROPERTY_INVALID, FX_REQUIRED_CHANNEL_UNAVAILABLE

Since

Version 1.0

Example

-- delete the channel for the translate property of object1 
FxAnimation.DeleteChannel("object1", "translate");

DeleteKey (NodeID, NodeProperty, Frame)

This function deletes a keyframe from a channel.

Parameters

• NodeID: NodeID
• NodeProperty: NodeProperty
• Frame: The frame number

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND, FX_PROPERTY_INVALID, FX_REQUIRED_CHANNEL_UNAVAILABLE, FX_VALUE_INVALID

Since

Version 1.0

Example

-- delete keyframe at frame 5 from translate channel of object1 
FxAnimation.DeleteKey("object1", "translate", 5);

Get1b (NodeID, NodeProperty, Frame)
Get1c (NodeID, NodeProperty, Frame)
Get1f (NodeID, NodeProperty, Frame)
Get1i (NodeID, NodeProperty, Frame)
Get1s (NodeID, NodeProperty, Frame)
Get2b (NodeID, NodeProperty, Frame)
Get2i (NodeID, NodeProperty, Frame)
Get2f (NodeID, NodeProperty, Frame)
Get3b (NodeID, NodeProperty, Frame)
Get3f (NodeID, NodeProperty, Frame)
Get3i (NodeID, NodeProperty, Frame)

These functions return one or more values of a channel at the specified frame number. The values are interpolated using the channel's interpolation mode. The value type of the property must match the selected Get function. For example, if the property is of type int, use get1i.

Parameters

• NodeID: Single NodeID
• NodeProperty: NodeProperty
• Frame: Frame number

Returns

Get1c returns 1 Color value
Get1s returns 1 value
Getxb returns x values
Getxi returns x values
Getxf returns x values

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND, FX_PROPERTY_INVALID, FX_REQUIRED_CHANNEL_UNAVAILABLE, FX_VALUE_INVALID

Since

Version 1.0

Example

val = FxAnimation.Get1b("object1", "visible", 4);
x y z = FxAnimation.Get3f("object1", "translate", 4);

GetChannelEnabled (NodeID, NodeProperty)

This function checks if a channel is enabled.

Parameters

• NodeID: Single NodeID
• NodeProperty: NodeProperty

Returns

Enabled state

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND, FX_PROPERTY_INVALID, FX_REQUIRED_CHANNEL_UNAVAILABLE

Since

Version 1.0

Example

-- check if translate channel of object1 is enabled
val = FxAnimation.GetChannelEnabled("object1", "translate");

GetChannelInterpolation (NodeID, NodeProperty)

This function returns the interpolation mode of a channel.

Parameters

• NodeID: Single NodeID
• NodeProperty: NodeProperty

Returns

InterpolationMode

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND, FX_PROPERTY_INVALID, FX_REQUIRED_CHANNEL_UNAVAILABLE

Since

Version 1.0

Example

-- get interpolation mode of translate channel of object1 
val = FxAnimation.GetChannelInterpolation("object1", "translate");

## GetEasing (NodeID, NodeProperty, Frame)

This function returns the easing function used at the specified frame. If the interpolation mode of the channel is not set to ease, then the result is 0 (linear).

Parameters

• NodeID: Single NodeID
• NodeProperty: NodeProperty
• Frame: Frame number

Returns

EasingFunction

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND, FX_PROPERTY_INVALID, FX_REQUIRED_CHANNEL_UNAVAILABLE, FX_VALUE_INVALID

Since

Version 1.0

Example

val = FxAnimation.GetEasing("object1", "translate", 5);

GetNextKey (NodeID, NodeProperty, Frame)

This function returns the frame number of the next keyframe after the specified frame number.

Parameters

• NodeID: Single NodeID
• NodeProperty: NodeProperty
• Frame: Frame number

Returns

Frame number of next keyframe

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND, FX_PROPERTY_INVALID, FX_REQUIRED_CHANNEL_UNAVAILABLE

Since

Version 1.0

Example

currentFrame = 5;
val = FxAnimation.GetNextKey("object1", "translate", currentFrame);

GetPrevKey (NodeID, NodeProperty, Frame)

This function returns the frame number of the previous keyframe before the specified frame number.

Parameters

• NodeID: Single NodeID
• NodeProperty: NodeProperty
• Frame: Frame number

Returns

Frame number of previous keyframe

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND, FX_PROPERTY_INVALID, FX_REQUIRED_CHANNEL_UNAVAILABLE

Since

Version 1.0

Example

currentFrame = 5;
val = FxAnimation.GetPrevKey("object1", "translate", currentFrame);

MoveKey (NodeID, NodeProperty, FrameFrom, FrameTo)

This function moves a keyframe at FrameFrom to the frame number FrameTo. If a keyframe already exists at FrameTo, it will be overwriten.

Parameters

• NodeID: Single NodeID
• NodeProperty: NodeProperty
• FrameFrom: Frame number of the keyframe
• FrameTo: Target frame number of the keyframe

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND, FX_PROPERTY_INVALID, FX_REQUIRED_CHANNEL_UNAVAILABLE, FX_VALUE_INVALID

Since

Version 1.0

Example

-- move the keyframe at frame 5 to frame 25
FxAnimation.MoveKey("object1", "translate", 5, 25);

SetChannelEnabled (NodeID, NodeProperty, Value)

This function sets the enabled state of a channel.

Parameters

• NodeID: NodeID
• NodeProperty: NodeProperty
• Value: Whether to enable channel

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND, FX_PROPERTY_INVALID, FX_REQUIRED_CHANNEL_UNAVAILABLE

Since

Version 1.0

Example

-- enable translate channel for object1
FxAnimation.SetChannelEnabled("object1", "translate", true);

SetChannelInterpolation (NodeID, NodeProperty, Value)

This function sets the interpolation mode of a channel.

Parameters

• NodeID: NodeID
• NodeProperty: NodeProperty
• Value: InterpolationMode

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND, FX_PROPERTY_INVALID, FX_VALUE_INVALID, FX_REQUIRED_CHANNEL_UNAVAILABLE

Since

Version 1.0

Example

-- set interpolation mode for translate channel of object1 to linear
FxAnimation.SetChannelInterpolation("object1", "translate", 1);

SetKey1b (NodeID, NodeProperty, Frame, Value)
SetKey1c (NodeID, NodeProperty, Frame, Value)
SetKey1f (NodeID, NodeProperty, Frame, Value)
SetKey1i (NodeID, NodeProperty, Frame, Value)
SetKey1s (NodeID, NodeProperty, Frame, Value)
SetKey2b (NodeID, NodeProperty, Frame, X, Y)
SetKey2i (NodeID, NodeProperty, Frame, X, Y)
SetKey2f (NodeID, NodeProperty, Frame, X, Y)
SetKey3b (NodeID, NodeProperty, Frame, X, Y, Z)
SetKey3f (NodeID, NodeProperty, Frame, X, Y, Z)
SetKey3i (NodeID, NodeProperty, Frame, X, Y, Z)

These functions set the value of a keyframe at the specified frame number. If there is no keyframe at that frame number then the function has no effect (no error is raised). The value type of the property must match the selected Set function. For example, if the property is of type int use set1i.

Parameters

• NodeID: NodeID
• NodeProperty: NodeProperty
• Frame: Frame number
• Value, X, Y, Z: The value(s) to set.

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND, FX_PROPERTY_INVALID, FX_VALUE_INVALID, FX_REQUIRED_CHANNEL_UNAVAILABLE

Since

Version 1.0

Example

FxAnimation.SetKey1b("object1", "visible", true);
FxAnimation.SetKey3f("object1", "translate", 2.0, 3.0, 10.0);

SetKeyEasing (NodeID, NodeProperty, Frame, Value)

This function sets the easing function of a keyframe at the specified frame number. The channel's interpolation mode must be set to ease otherwise this function will have no visible effect. If there is no keyframe at the specified frame number then the function has no effect (no error is raised).

Parameters

• NodeID: NodeID
• NodeProperty: NodeProperty
• Frame: Frame number
• Value: EasingFunction

Errors

Possible errors include FX_REQUIRED_ASSET_UNAVAILABLE, FX_NODE_NOT_FOUND, FX_PROPERTY_INVALID, FX_VALUE_INVALID, FX_REQUIRED_CHANNEL_UNAVAILABLE

Since

Version 1.0

Example

-- set keyframe easing function at frame number 5 to easeInOutQuart
FxAnimation.SetKeyEasing("object1", "translate", 5, 33);