Attached to a ActionLayer an ActionClip control one or multiple motions based on the ClipType used to creating it. They will allow you to blend either a single Action or multiple actions linearly, in two dimension or using an arbitrary number of actions simultaneously. ActionClip can also control the machine state of the ActionLayer it is connected with by using the ClipType AnyState or ExitState.

Note: An ActionClip base is a Controller which is a global asset that can be used by multiple resources at the same time; when specifying an action connected to a motion this action will be set as a string instead of (the usual) reference. This way the Controller can be used by more than one resource.

Warning: When evaluating an ActionClip it might happen that an error occur. Errors are generate either by specifying a variable that cannot be found on the host resource connected to the Controller. Same scenario can occur with a specified action. In case an error is generated the execution of the Controller is stalled as it cannot evaluate the current/next machine state. To fix the error either call the SetVariableMotion(1d, 2d or Free) or SetMotion(1d, 2d or Free); theses functions will reset the error state.

Static Variables

Name	Description
`actionlayer`	The ActionLayer the current ActionClip belongs to.
Declaration ActionLayer actionlayer Example* Lua C/C++
`group`	Reference to the ClipGroup the ActionClip belongs to (if any).
Declaration ClipGroup *group
`type`	Represent the ClipType of the ActionClip.
Declaration ClipType type
`uid`	A unique id to identify the current ActionClip.
Declaration unsigned int uid

Variables

Name Description

name A unique name to identify the current ActionClip within its ActionLayer.

Declaration

char *name

actuators Enable or disable the use of actuators within the active motions associated to the ActionClip.

Declaration

bool actuators

flags Controls the various flags of the current ActionClip.

Declaration

int flags

Cap	Value	Description
`ACC_FLAG_SELECTED`	`bit.lshift(1,0)`	Select/deselect the current ActionClip node.
`ACC_FLAG_ERROR`	`bit.lshift(1,1)`	Determine if the current ActionClip trigger an error.
`ACC_FLAG_ACTUATORS`	`bit.lshift(1,2)`	Toggle on/off the use of the actuator associated to the connected action(s).

Functions

Name	Description
`AddMotion`	Add a new channel to the current action (up to 256).
Declaration int AddMotion( void ) 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 On success return the index of the new motion created; else return `-1`. Attention New motions can only be created if the ClipType is either: `kBlend1d`, `kBlend2d` or `kBlendFree`.
`RemoveMotion`	Remove an existing motion based on its index.
Declaration bool RemoveMotion( int index ) Parameters `index`: The motion index to remove. Return Value `true` if the motion index exists and the action ClipType is set to `kBlend1d`, `kBlend2d` or `kBlendFree` else return `false`. Warning If the `index` specified is `<0` all motions will be deleted.
`SetMotion`	Set the motion of a `kSingle` ActionClip.
Declaration bool SetMotion( const char action[32], float scale ) Parameters `action`: The name of the action to use for the current motion. `scale`: The time scale ratio to apply to the action at evaluation time. Return Value `true` if the current ActionClip is of the type `kSingle`; else return `false`.
`SetMotion1d`	Set the motions of a `kBlend1d` ActionClip.
Declaration bool SetMotion1d( unsigned char index, float position, const char action[32], float scale ) Parameters `index`: The motion index to set/update. `position`: The normalized location of the motion ranging from `-1.0` to `1.0`. `action`: The name of the action to use for the current motion. `scale`: The time scale ratio to apply to the action at evaluation time. Return Value `true` if the current ActionClip is of the type `kBlend1d` and the motion index is valid; else return `false`.
`SetVariableMotion1d`	Controls the variable that will be use to evaluate the `kBlend1d` ActionClip.
Declaration bool SetVariableMotion1d( unsigned int variable ) Parameters `variable`: An existing Variable reference defined by the Controller. This variable will be used to evaluate the linear blend tree. Return Value `true` if the current ActionClip is of the type `kBlend1`; else return `false`.
`SetMotion2d`	Set the motions of a `kBlend2d` ActionClip.
Declaration bool SetMotion2d( unsigned char index, float position_x, float position_y, const char action[32], float scale ) Parameters `index`: The motion index to set/update. `position_x`: The normalized (ranging from `-1.0` to `1.0`) location of the motion on the X axis. `position_y`: The normalized location of the motion on the Y axis. `action`: The name of the action to use for the current motion. `scale`: The time scale ratio to apply to the action at evaluation time. Return Value `true` if the current ActionClip is of the type `kBlend2d` and the motion index is valid; else return `false`.
`SetVariableMotion2d`	Controls the variables and interpolation method use when evaluating a `kBlend2d` ActionClip.
Declaration bool SetVariableMotion2d( unsigned int variable_x, unsigned int variable_y, int method ) Parameters `variable_x`: A Controller Variable reference to evaluate the two dimensional blend tree on the X axis. `variable_y`: A Controller Variable reference to evaluate the two dimensional blend tree on the Y axis. `method`: The interpolation method to use: `0` for `Cartesian` else `Radial`. Return Value `true` if the current ActionClip is of the type `kBlend2d`; else return `false`.
`SetMotionFree`	Set the motions of a `kBlendFree` ActionClip.
Declaration bool SetMotionFree( unsigned char index, unsigned int variable, const char action, float scale ) Parameters* `index`: The motion index to set/update. `variable`: The Controller variable to use to evaluate the blend free. `action`: The name of the action to use for the current motion. `scale`: The time scale ratio to apply to the action at evaluation time. Return Value `true` if the current ActionClip is of the type `kBlendFree` and the motion index is valid; else return `false`.
`SetExitState`	Controls the behavior of an `kExitState` ActionClip.
Declaration bool SetExitState( const ExitStrategy strategy, unsigned int next_state ) Parameters `strategy`: Specify the exit strategy to adopt when the state machine is set to the ActionClip. `next_state`: Have effect only if the `strategy` is set to `kGotoState`; this parameter controls which existing ActionClip the machine state should jump to. Return Value `true` if the current ActionClip is of the type `kExitState`; else return `false`.
`SortMotions`	Sort all existing motions based on their position (either on the X or XY axis).
Declaration bool SortMotions( void ) Return Value `true` if the ActionClip ClipType is `kBlend1d`, `kBlend2d` or `kBlendFree` and motions have been sorted else return `false`.

ClipType

Represent the type an ActionClip can be created with which will in turn dictate its behavior and properties.

kSingle: Provide a way to connect a single action.
kBlend1d: Can contain multiple actions that will be linearly blended based on the value of an existing controller variable.
kBlend2d: Multiple actions blended in two dimension; actions are first defined then placed on the X and Y axis.
kBlendFree: Allows you to set up multiple actions and specify how much influence each of them will have on the final mix.
kAnyState: This type is acting as a branch that will be evaluated by the system regardless of the state the tree is currently in.
kExitState: Specify the termination of the action layer; different termination strategies can be set based on your requirements.

Example

-- Access and print the value of the ClipType kBlend2d:
print( "The value of kBlend2d is " .. ActionClip.ClipType.kBlend2d )

ExitStrategy

The type of strategy to use with an ExitState ActionClip.

kBackToEntry: Return to the ActionLayer default entry ActionClip.
kRestart: Reset and restart the ActionLayer.
kTerminate: Stop evaluating the ActionLayer the ActionClip is associated with.
kGotoState: Go to an existing ActionClip contained within the same ActionLayer.

Example

-- Access and print the value of the ExitType kTerminate:
print( "The value of kTerminate is " .. ActionClip.ExitStrategy.kTerminate )