Channels are basically a container that maintain the state of a Curve or Track. Each Channel is associated to a scripting command that update the value of an existing variable. Attached to an Action, channels can be used to either control a single value, like fading the audio volume or can be used to animate a SkeletalMesh by controlling the bone's transformation of an entire Skeleton hierarchy.

Each channel can have a set of triggers that can be placed at various point in time. Theses triggers are called Actuators; when the playback time of the Channel hit the actuator time the OnActuator event will be called. Using this mechanism you can then add custom logic at various point in time during a Channel playback.

In example using actuators you could, in the case of a skeletal animation, place an actuator at the point in time where the foot of the character hit the floor. Subsequently, a Script or plugin can launch a ParticleSystem emitting dust to be launched at the location of the hit. Many more similar scenarios can be handled using actuators; always remember you have them your toolbox.

Static Variables

Name	Description
`action`	The Action reference pointer where the Channel resides.
Declaration Action *action
`type`	The type of variable the Channel controls.
Declaration VariableType type
`value`	Current value evaluated by the Channel.
Declaration float value
`handler`	Container that handles the script(s) connected to the Channel.
Declaration Handler handler
`track`	Track reference pointer in the event the Channel have been set to not use its default Curve.
Declaration Track *track
`playback_time`	The active playback time of the Channel.
Declaration float playback_time
`code`	Scripting command used by the Channel to affect the value of an existing variable.
Declaration char *code
`uid`	Internal unique id used by the system to identify the Channel.
Declaration unsigned int uid
`curve`	Default Curve used by the Channel if it is not linked to a Track.
Declaration Curve *curve
`actuator_count`	The total amount of actuators connected to the active Channel.
Declaration unsigned char actuator_count

Variables

Name Description

cycle_mode The current CycleMode set for the Channel.

Declaration

CycleMode cycle_mode

name Name to identify the Channel within its parent Action.

Declaration

char *name

state Active State of the Channel which determine if it is evaluating, paused, stopped etc.

Declaration

State state

flags Bit mask holding various Channel options and setting.

Declaration

int flags

Cap	Value	Description
`CHA_FLAG_MUTE`	`bit.lshift(1,0)`	Mute the Channel.
`CHA_FLAG_CONTINUOUS`	`bit.lshift(1,1)`	Force the Channel to continuously update the value of the variable it controls.
`CHA_FLAG_NORMALIZE`	`bit.lshift(1,2)`	Normalize the key frame values ranging from `-1` to `1`.
`CHA_FLAG_COMPILED`	`bit.lshift(1,3)`	Determine wether or not the Channel have been compiled.
`CHA_FLAG_ERROR`	`bit.lshift(1,4)`	This flag is raised in the case the Channel have encountered an error.
`CHA_FLAG_VISIBLE`	`bit.lshift(1,5)`	Show/hide the Channel when its parent Action is displayed in the editor.
`CHA_FLAG_LOCKED`	`bit.lshift(1,6)`	Prevents the Channel key frames to be modified by the editor.

normalize Normalize the value evaluated by the Channel ranging from -1 to 1.

Declaration

bool normalize

visible Show/hide the Channel when its parent Action is displayed in the editor.

Declaration

bool visible

mute When enabled the Channel continues to update but the variable it controls will not be updated.

Declaration

bool mute

locked Prevent the Channel key frames to be modified by the editor.

Declaration

bool locked

continuous Force the Channel variable to be updated even if the value evaluated haven't changed.

Declaration

bool continuous

color A color to visually identify the Channel inside the editor.

Declaration

vec4 color

Functions

Name	Description
`Play`	Start increasing the playback time and evaluating the Channel value.
Declaration bool Play( void ) Return Value Return `true` if the playback start/resume else return `false` if the Channel is already playing.
`Pause`	Pause the current Channel playback.
Declaration bool Pause( void ) Return Value Return `true` if the pause operation is successful; return `false` in the event the Channel is already paused.
`Stop`	Stop the Channel playback and reset its playback time back to 0.
Declaration bool Stop( void ) Return Value Return `true` if the playback stops; else return `false` if the Channel already in the stop State.
`Seek`	Manually set the Channel playback time.
Declaration void Seek( float playback_time ) Parameters `playback_time`: Where the playback time (where 1.0 = 1sec) should jump.
`Record`	Set the Channel State to `kRecord` allowing you to save the value of the variable connected to the channel over time.
Declaration bool Record( void ) Return Value `true` if the application is not running and the active Channel is using an existing Track. Note The record state can only be assigned to channels that are using a Track asset.
`GetPlaybackTime`	Return the current channel playback time.
Declaration float GetPlaybackTime( void ) Return Value The Channel playback time.
`GetDuration`	The total amount of time covered by the default Curve or Track the Channel is using.
Declaration float GetDuration( void ) Return Value The total Channel playback duration.
`AddActuator`	Create a new actuator to be triggered at specific point in time.
Declaration void AddActuator( float playback_time, bool enabled, bool recursive ) Parameters `playback_time`: The point in time where to place the actuator. `enabled`: Determine wether or not the actuator can be triggered. `recursive`: Specify if the actuator should be triggered only once or recursively for each iteration from the channel's CycleMode.
`SortActuators`	Sort all the channel's actuators chronologically (based on their trigger time).
Declaration void SortActuators( void )
`HaveActuator`	Get the actuator index for a specific playback time.
Declaration int HaveActuator( float playback_time, float threshold ) Parameters `playback_time`: The location in time to check if an actuator exists. `threshold`: Specify a threshold (in time) that represents the acceptable time range an actuator playback time can be located in. Return Value On success returns the actuator index; else return `-1`.
`RemoveActuator`	Remove all actuators located at a specific playback time.
Declaration bool RemoveActuator( float playback_time, float threshold ) Parameters `playback_time`: The location that specify where to check if an actuator exists. `threshold`: A time threshold that represents the acceptable time range to remove all actuators located inside it. Return Value `true` if any actuators have been removed; else return `false`.
`GetActuatorPlaybackTime`	Get the trigger time of an existing actuator.
Declaration float GetActuatorPlaybackTime( unsigned char index ) Parameters `index`: The index of the actuator you wish to retrieve the playback/trigger time. Return Value If the actuator index exists; return its playback time else return `-1`.
`IsActuatorEnabled`	Check if a specific actuator pointed by an index is enabled or disabled.
Declaration bool IsActuatorEnabled( unsigned char index ) Parameters `index`: The index of the actuator you wish to retrieve the status for. Return Value `true` if the actuator is enabled; else return `false`.
`IsActuatorRecursive`	Check if a specific actuator is recursive or not.
Declaration bool IsActuatorRecursive( unsigned char index ) Parameters `index`: Index of the actuator you want to check the recursion state. Return Value `true` if the actuator is recursive; else `false`.
`SetActuatorPlaybackTime`	Modify the playback time of an existing actuator.
Declaration bool SetActuatorPlaybackTime( unsigned char index, float playback_time ) Parameters `index`: The index of the actuator you wish to retrieve the status for. `playback_time`: The new playback time to assign to the actuator. Return Value `true` if the playback time have been affected; else return `false` if the actuator pointed by the index does not exist.
`SetActuatorEnable`	Update the status of an existing actuator.
Declaration bool SetActuatorEnable( unsigned char index, bool enabled ) Parameters `index`: Index of the actuator you want to check the recursion state. `enabled`: The status to apply to the actuator located at the index provided in parameter. Return Value `true` if the status have been updated. Else return `false` if the actuator pointed by the index does not exist.
`SetActuatorRecursive`	Change the recursion state of an existing actuator using its index as key.
Declaration bool SetActuatorRecursive( unsigned char index, bool recursive ) Parameters `index`: The index of the actuator you wish to retrieve the status for. `recursive`: Recursion state to apply to the actuator. Return Value `true` if the actuator recursion state have been modified; else return `false` if the actuator pointed by the index does not exist.
`ClearActuators`	Remove all existing actuators connected to the Channel.
Declaration void ClearActuators( void )
`SetTrack`	Force the Channel to use the Curve of an existing Track asset instead of its default one.
Declaration void SetTrack( Track track ) Parameters* `track`: A valid Track asset or `nil` to disconnect any previously track set.
`GetCurve`	Get the active Curve reference pointer used by the Channel.
Declaration Curve GetCurve( void ) Return Value* The current Curve reference pointer used by the Channel (either its default curve or the curve of the Track connected to it).
`SetCode`	The scripting command for the Channel to use to update an existing variable.
Declaration void SetCode( const char code ) Parameters* `code`: A one liner that tells the internal system how to update a specific variable using the value evaluated by the Channel Curve over time.

CycleMode

Determine the behavior of the Channel when the playback time pass the last frame.

kHold: Hold the value of last keyframe.
kLoop: Reset back the playback time to 0.
kMirror: Reverse the playback direction creating a ping pong effect.
kExtrapolate: Multiply the key frame value from the amount of cycles the Channel have been accumulating.
kStandBy: Maintain the Channel playback time if it pass the end of the associate Curve time range.

Example

-- Print the kMirror cycle mode value:
print( "The value of kMirror is " .. Channel.CycleMode.kMirror )

Events

Callbacks	Description
`OnUpdate`	Triggered every time the Channel gets re-evaluated.
Declaration function OnUpdate()
`OnActuator`	Called each time the playback time trigger an existing actuator.
Declaration function OnActuator()
`OnPlay`	This callback gets called when the Channel received the signal to start playing.
Declaration function OnPlay()
`OnResume`	Triggered if the Channel was paused and then start playing again.
Declaration function OnResume()
`OnPause`	Triggered when the Channel gets paused.
Declaration function OnPause()
`OnStop`	Called when the Channel received the stop signal.
Declaration function OnStop()