A typical example to represent what an Action is would be a predefined camera path. The camera object contains a Animation structure that can contain multiple actions. You can then use a separate Action to represent different pre-recorded path such as: FlyByTower, PassUnderBridge or on existing skeleton bones to create more complex animation like: LegsRun, TorsoTurnLeft or DrawWeapon etc...

Actions can be used to control an object, properties, and entire skeleton and more. They can also be blended and mixed to create more complex non linear animation sequence to create Controller and Sequence; they can also be used in conjunction with physics, runtime user variables and more.

For each Action one or multiple Channel can be attached; each of them can control a different property based on a Curve (local curve) or Track (global curve). Each of theses curves can then be used to manage or animate a specific value at runtime. Values are expressed as a script lien which is ideal for procedural generation at runtime or to dynamically animate any other type of values.

Static Variables

Name	Description
`animation`	The Animation structure where the current Action reside. **
Declaration Animation animation Example* Lua C/C++ `-- Get the scene camera object. local obj = App:GetScene("Scene"):GetObject("Camera") -- Print the camera animation userdata. print( obj.animation )` `// Get the scene camera object. Object *obj = SceneGetObject( AppGetScene( "Scene" ), "Camera" ); // Print the camera animation userdata. printf( "%p\n", &obj->animation );`
`channel_count`	The number of channels associated with the current action. **
Declaration unsigned short channel_count Example Lua C/C++ `-- Access the Animator and request the first animation. local anm = Anm:GetAnimationAt(0) -- Get the first action. local act = anm:GetActionAt(0) if( act ~= nil ) then print( "Action: " .. act.name .. " Channel Count: " .. act.channel_count .. "." ) else print( "The animation does not contain any action." ) end` `// Access the Animator and request the first animation. Animation anm = AnmGetAnimationAt(0); // Get the first action. Action act = AnimationGetActionAt(anm,0); if( act != NULL ) { printf( "Action: %s Channel Count: %d.\n", act->id.name, act->channel_count ); } else { printf( "The animation does not contain any action." ); }`
`handler`	The Handler manage the scripting functionalities of the action.
Declaration Handler handler
`armature`	Set the Armature to use during playback to mask bones and joints. **
Declaration Armature armature Example* Lua C/C++ `-- Get the "MySkeletalMesh" object first action armature. local arm = App:GetScene("Scene"):GetObject("MySkeletalMesh").animation:GetActionAt(0).armature if( arm ) then print( arm.asset.name ) end` `// Get the "MySkeletalMesh" object first action armature. Armature *arm = AnimationGetActionAt( SceneGetObject( AppGetScene( "Scene" ), "MySkeletalMesh" ), 0 )->armature; if( arm ) { printf( "%s\n", arm->asset->name ); }`
`uid`	The internal unique id of the action.
Declaration unsigned int uid

Variables

Name	Description
`name`	A unique name to identify the action. **
Declaration char name Example* Lua C/C++ `-- Get the first action of the "Camera" object. local act = App:GetScene("Scene"):GetObject("Camera").animation:GetActionAt(0) if( act ~= nil ) then -- Rename the action. act.name = "MyAction" end` `// Get the first action of the "Camera" object. Action *act = AnimationGetActionAt( &SceneGetObject( AppGetScene( "Scene" ), "Camera" )->animation, 0 ); if( act != NULL ) { // Rename the action. ActionRename( act, "MyAction" ); }`
`fps`	Controls the update rate of the action.
Declaration unsigned char fps Range 0 to 120 Mhz Note Setting a value < 1Hz force the Action to be updated every frame.
`state`	The current playback state of the action.
Declaration State state In Lua, setting the State manually is basically the same as calling the `Play`, `Pause` or `Stop` function of the action. Warning Once an action is controlled by an ActionController the state of the Action will always be set to `Stop` by default.
`view_state`	Tell the system what to do when the object associated to the current Action is out of view.
Declaration State view_state Warning Once an action is controlled by an ActionController the state of the Action will always be set to `Stop` by default.
`build`	Force the system to resolve the memory address of the variables controlled by the channels.
Declaration bool build Building actions makes them perform alot faster at runtime; however if new channels are added they will not be resolved until the is rebuilt. Note Settings `build=true` is the equivalent as calling the `Build` function directly.
`sync_time`	Last time the Action was re-evaluated.
Declaration float sync_time

Functions

Name	Description
`AddChannel`	Add a new channel to the current action. **
Declaration Channel AddChannel( const char name, const char code, const VariableType type ) Parameters* `name`: The name to use to create the new channel. `code`: The scripting code used by the channel. `type`: The VariableType representing the kind of value the channel control. Return Value The new Channel reference. Example Lua C/C++ `-- Get the "Camera" object. local obj = App:GetScene("Scene"):GetObject("Camera") -- Get the first action from the animation structure. local act = obj.animation:GetActionAt(0) -- Add a new channel to control the Z location of the object act:AddChannel( "MyChannel", "App:GetScene(\"Untitled\"):GetObject(\"Camera\").location", Variable.VariableType.kFloat )` `// Get the "Camera" object. Object obj = SceneGetObject( AppGetScene( "Scene" ), "Camera" ); // Get the first action from the animation structure. Action act = AnimationGetActionAt( &obj->animation, 0 ); // Add a new channel to control the Z location of the object ActionAddChannel( act, "MyChannel", "App:GetScene(\"Untitled\"):GetObject(\"Camera\").location", kFloat );`
`GetChannel`	Retrieve a specific Channel a by its name. **
Declaration Channel GetChannel( const char name ) Parameters `name`: The name of the channel you want to retrieve. Return Value The Channel that matches the name received in parameter; else return `nil`. Example Lua C/C++ `-- Get the "Camera" object. local obj = App:GetScene("Scene"):GetObject("Camera") -- Get the first action from the animation structure and retrieve the channel "MyChannel" local cha = obj.animation:GetActionAt(0):GetChannel( "MyChannel" ) -- Print the channel userdata. print( cha )` `// Get the "Camera" object. Object obj = SceneGetObject( AppGetScene( "Scene" ), "Camera" ); // Get the first action from the animation structure and retrieve the channel "MyChannel" Channel cha = ActionGetChannel( AnimationGetActionAt( &obj->animation, 0 ), "MyChannel" ); // Print the channel pointer. printf( "%p\n", cha );`
`GetChannelByCode`	Retrieve a Channel using its scripting code. **
Declaration Channel GetChannelByCode( const char code ) Parameters `code`: The scripting code used by the channel. Return Value The Channel that matches the scripting code received in parameters; else return `nil`. Example Lua C/C++ `-- Get the "Camera" object. local obj = App:GetScene("Scene"):GetObject("Camera") -- Retrieve the first action from the animation structure. local act = obj.animation:GetActionAt(0) -- Get the channel matching the code in parameter. local cha = act:GetChannelByCode( "App:GetScene(\"Untitled\"):GetObject(\"Camera\").location" ) -- Print the channel userdata. print( cha )` `// Get the "Camera" object. Object obj = SceneGetObject( AppGetScene( "Scene" ), "Camera" ); // Retrieve the first action from the animation structure. Action act = AnimationGetActionAt( &obj->animation, 0 ); // Get the channel matching the code in parameter. Channel *cha = ActionGetChannelByCode( act, "App:GetScene(\"Untitled\"):GetObject(\"Camera\").location" ); // Print the channel userdata. printf( "%p\n", cha );`
`GetChannelAt`	Retrieve a certain Channel based on its index. **
Declaration Channel GetChannelAt( unsigned short index ) Parameters* `index`: The index of the channel you want to retrieve. Return Value If the index is greater or equal than the `channel_count` return `nil` instead return the Channel reference. Example Lua C/C++ `-- Get the "Camera" object. local obj = App:GetScene("Scene"):GetObject("Camera") -- Get the first action from the animation structure and extract the first channel. local cha = obj.animation:GetActionAt(0):GetChannelAt(0) -- On success print the channel code. if( cha ~= nil ) then print( "The channel code is: " .. cha.code ) end` `// Get the "Camera" object. Object obj = SceneGetObject( AppGetScene( "Scene" ), "Camera" ); // Get the first action from the animation structure and extract the first channel. Channel cha = ActionGetChannelAt( AnimationGetActionAt( &obj->animation, 0 ), 0 ); // On success print the channel code. if( cha != NULL ) { printf( "The channel code is: %s\n", cha->code ); }`
`GetChannelIndex`	Retrieve the channel index if it is contained in the source Action specified. **
Declaration int GetChannelIndex( const Channel channel ) Parameters* `channel`: The channel pointer to use in order to retrieve its index. Return Value If the Channel received in parameter is contained within the Action channel list the function will return the index else return `-1`. Example Lua C/C++ `-- Get the "Camera" object. local obj = App:GetScene("Scene"):GetObject("Camera") -- Get the first action from the animation structure and extract the first channel. local cha = obj.animation:GetActionAt(0):GetChannelAt(0) -- Print the channel index; in this case obviously 0. print( "The index of the channel is: " .. obj.animation:GetActionAt(0):GetChannelIndex( cha ) )` `// Get the "Camera" object. Object obj = SceneGetObject( AppGetScene( "Scene" ), "Camera" ); // Get the first action from the animation structure and extract the first channel. Channel cha = ActionGetChannelAt( AnimationGetActionAt( &obj->animation, 0 ), 0 ); // Print the channel index; in this case obviously 0. printf( "The index of the channel is: %d\n", ActionGetChannelIndex( AnimationGetActionAt( &obj->animation, 0 ), cha ) );`
`RemoveChannel`	Remove a specific Channel from the source Action. **
Declaration bool RemoveChannel( Channel channel ) Parameters* `channel`: The Channel to remove from the Action channel list. Return Value `true` if the Channel have been removed else return `false`. Example Lua C/C++ `-- Get the "Camera" object. local obj = App:GetScene("Scene"):GetObject("Camera") -- Get the first action. local act = obj.animation:GetActionAt(0) -- Get the first first channel. local cha = act:GetChannelAt(0) -- Print the operation result. print( "Channel removed:" .. tostring( act:RemoveChannel( cha ) ) )` `// Get the "Camera" object. Object obj = SceneGetObject( AppGetScene( "Scene" ), "Camera" ); // Get the first action. Action act = AnimationGetActionAt( &obj->animation, 0 ); // Get the first first channel. Channel *cha = ActionGetChannelAt( act, 0 ); // Print the operation result. printf( "Channel removed: %d", ActionRemoveChannel(act, cha ) );`
`RemoveChannelAt`	Remove a specific Channel contained in the source Action by its list index. **
Declaration bool RemoveChannelAt( int index ) Parameters `index`: The channel index to remove. Return Value `true` if the Channel have been removed else return `false`. Example Lua C/C++ `-- Get the "Camera" object. local obj = App:GetScene("Scene"):GetObject("Camera") -- Remove the first channel. print( "Channel 0 removed: " .. obj.animation:GetActionAt(0):GetChannelAt(0) )` `// Get the "Camera" object. Object *obj = SceneGetObject( AppGetScene( "Scene" ), "Camera" ); // Remove the first channel. printf( "Channel 0 removed: %d", ActionRemoveChannelAt( AnimationGetActionAt( &obj->animation, 0 ), 0 ) );`
`SwapChannels`	Swap two existing channels.
Declaration bool SwapChannels( unsigned short index0, unsigned short index1 ) Parameters `index0`: The first index of the Channel to swap. `index1`: The second index of the Channel to swap. Return Value `true` if the operation succeed else `false`.
`Play`	Playback an action. **
Declaration bool Play( void ) Return Value `true` if the Action starts playing; `false` if is already playing. Lua C/C++ `-- Get the "Camera" object and start playing the first action. App:GetScene("Scene"):GetObject("Camera").animation:GetActionAt(0):Play()` `// Get the "Camera" object and start playing the first action. ActionPlay( AnimationGetActionAt( &SceneGetObject( AppGetScene( "Scene" ), "Camera" )->animation, 0 ) );`
`Pause`	Pause an action.
Declaration bool Pause( void ) Return Value `true` if paused successfully else return `false` if it is already paused.
`Stop`	Stop an action.
Declaration bool Stop( void ) Parameters `index`: The channel index to pause. Return Value `true` if the Action stop else return `false` is it is already stopped.
`Seek`	Set the playback time of all Channel to a specific position.
Declaration bool Seek( float playback_time ) Parameters `playback_time`: The playback time where 1.0 = 1sec.. Return Value `true` if the Action contains Channel that can seek return `false`.
`GetDuration`	Get the total time of the Action considering all channels duration. **
Declaration float GetDuration( void ) Return Value The total duration of the Action where 1.0 = 1sec. Lua C/C++ `-- Print the duration of the "Camera" animation first action. print( string.format( "%.2f", App:GetScene("Scene"):GetObject("Camera").animation:GetActionAt(0):GetDuration() ) )` `// Print the duration of the "Camera" animation first action. printf( "%.2f\n", ActionGetDuration( AnimationGetActionAt( &SceneGetObject( AppGetScene( "Scene" ), "Camera" )->animation, 0 ) ) );`
`Cleanup`	Remove all channels that are in error.
Declaration int Cleanup( void ) Return Value The number of channels that have been removed.
`SetArmature`	Assign an armature to the current Action to mask bones/joints during playback.
Declaration bool SetArmature( Armature armature ) Return Value* `true` if the armature was successfully assigned else return `false`. Note Armature can only be attached to an Action if the underlying object data attached to the Animation where the Action resides is of the type SkeletalMesh.
`Build`	Resolve the memory address of each channel allowing the system to store the Channel result directly to it.
Declaration bool Build( void ) `true` if the Action is built successfully. Return `false` if one or more Channel generate a runtime error.
`Rebuild`	Rebuild the action.
Declaration bool Rebuild( void ) Return Value `true` if the Action was rebuilt successfully; else `false`.
`Update`	Force the system to re-evaluate the current Action and all the channels it contain.
Declaration void Update( void )
`SetSpeed`	Set the speed of all Channel Curve managed by the active Action.
Declaration void SetSpeed( float speed )
`SetReverse`	Set the reverse flag on or off to all Channel Curve managed by the Action.
Declaration void SetReverse( bool reverse )

Events

Callbacks	Description
`OnUpdate`	This callback is triggered everytime an Action gets updated. *
Declaration function OnUpdate() Example Lua `function OnUpdate() -- Get the current action name from the application event. print( "Updating the Action:" .. event.action.name ) end`
`OnPlay`	Happen everytime the Action is requested to start playing. *
Declaration function OnPlay() Example Lua `function OnPlay() -- Since the callback is specific to the Action the -- keyword "this" points directly to the event.action. -- Print the action name start playing. print( "Start playing the action:" .. this.name ) end`
`OnResume`	Triggered when the Action start playing is called and at least one Channel state is paused. *
Declaration function OnResume() Example Lua `function OnResume() print( "The Action: " .. this.name .. " is resuming." ) end`
`OnPause`	Occur when one or more Channel state is set to pause. *
Declaration function OnPause() Example Lua `function OnPause() print( "The Action: " .. this.name .. " just pause." ) end`
`OnStop`	Triggered right after the Action stop. *
Declaration function OnStop() Example Lua `function OnPause() print( "The Action: " .. this.name .. " just stop." ) end`