Motion Object Agents

 

An Item Animation LScript provides three arguments to the process() function. The first argument is an instance of a Motion Object. The second and third parameters are the integer frame number and numeric time index of the current invocation.

Data members

objID (READ-ONLY)
objID is a pointer to the Object Agent to which this particular plug-in has been assigned.

Methods

get(attribute,time)
The get(attribute,time) function will return a vector that represents the value of the specified 'attribute' at the given 'time'. 'attribute' can be one of POSITION or WPOSITION, ROTATION, or SCALING. 'time' is the time index in which you are interested. In the case of ROTATION, the values are in degrees. SCALING values are multipliers, where 1.0 indicates no change.

set(attribute,value)
The set(attribute,value) function allows you to set the specified 'attribute' (POSITION, ROTATION, SCALING) to the provided vector 'value.'

Example:

Apply this script to a bone that is targeted to another object. The script will keep the bone attached to the target object, as it moves, by employing uniform scaling of the bone.

//-----------------------------------------------
// Bone Target                                            
//

@version 2.3

myObj;

create: obj
{
   //Store Object Agent in the myObj global variable
   myObj= obj;
   setdesc("Bone Target");
}

flags
{
   return(IA_AFTERIK);
}

process: ma, frame, time
{
   // Make sure there is a goal.
   if(myObj.goal == nil)
        return;
   dist = vmag(myObj.goal.param(WPOSITION,time) –
ma.get(WPOSITION,time));

     // keep the bone from shrinking
    if((scale = (dist / myObj.restlength)) < 1.0)
        scale = 1.0;

     // Using the ma Object Agent, set SCALING attribute.
    ma.set(SCALING,<scale,scale,scale>);
}    

Layout Commands

AddPosition("<X>","<Y>","<Z>");
AddScale("<X>","<Y>","<Z>");
AddRotation("<H>","<P>","<B>");
BController("<controller>");
BLimits("<min>","<max>");
BStiffness("<stiffness>");
CreateKey("<time>"); 
DeleteKey("<time>");
EnableXH();
EnableYP();
EnableZB();
FullTimeIK();
GoalItem("<ID>");
GoalObjective(<integer>); >=9.5 only
Sets the GoalObjective of all selected items.
0 is Go to goal
1 is Point at goal
2 is X-Y Plane through goal

GoalStrength("<strength>");
HController("<controller>");
HLimits("<min>","<max>");
HStiffness("<stiffness>");
IKFKBlending("<strength>"); >=9.5 only
Controls the percentage of IK (0.0) to FK (1.0) blending of the all selected items.

IKInitialState("<integer>"); >=9.5 only
Determines the IK initial state.
0 means use the first keyframe
1 means use the most recent keyframe
2 means use the current keyframe
3 means use the chosen keyframe
The Motion Panel doesn't redraw when this is set, so you may have to close and open the Motion panel to see changes.

IKInitialStateFrame("<integer>"); >=9.5 only
Determines the IK initial state frame.
KeepGoalWithinReach();
LimitB();
Toggles the limits for Rotation in B.

LimitH();
Toggles the limits for Rotation in H.

LimitP();
Toggles the limits for Rotation in P.

LimitSX(); >=9.5 only
Toggles the limits for Scale in X.

LimitSY(); >=9.5 only
Toggles the limits for Scale in Y.

LimitSZ(); >=9.5 only
Toggles the limits for Scale in Z.

LimitX(); >=9.5 only
Toggles the limits for Position in X.

LimitY(); >=9.5 only
Toggles the limits for Position in Y.

LimitZ(); >=9.5 only
Toggles the limits for Position in Z.

LocalCoordinateSystem();
MatchGoalOrientation();
MovePathTool();
MoveTool();
ParentCoordinateSystem();
ParentInPlace();
ParentItem("<ID>");
PathAlignLookAhead("<time>");
PathAlignMaxLookSteps("<steps>");
PathAlignReliableDist("<distance>");
PController("<controller>");
PLimits("<min>","<max>");
Position("<X>","<Y>","<Z>");
PStiffness("<stiffness>");
RecordMaxAngles();
RecordMinAngles();
RecordMaxPosition();
RecordMinPosition();
RecordMaxScale();
RecordMinScale();

RecordPivotRotation();
Takes the current item's rotation and sets that to the object's pivot rotation, setting the rotation to <0,0,0>

Reset();
RotatePivotTool();
RotateTool();
Rotation("<H>","<P>","<B>");
Scale("<X>","<Y>","<Z>");
SizeTool();
SquashTool();
StretchTool();
SXLimits("<min>","<max>"); >=9.5 only
SYLimits("<min>","<max>"); >=9.5 only
SZLimits("<min>","<max>"); >=9.5 only
XLimits("<min>","<max>"); >=9.5 only
YLimits("<min>","<max>"); >=9.5 only
ZLimits("<min>","<max>"); >=9.5 only
SXStiffness("<value>"); >=9.5 only
SYStiffness("<value>"); >=9.5 only
SZStiffness("<value>"); >=9.5 only
XStiffness("<value>"); >=9.5 only
YStiffness("<value>"); >=9.5 only
ZStiffness("<value>"); >=9.5 only
SXController("<integer>"); >=9.5 only
SYController("<integer>"); >=9.5 only
SZController("<integer>"); >=9.5 only
XController("<integer>"); >=9.5 only
YController("<integer>"); >=9.5 only
ZController("<integer>"); >=9.5 only
These can be assigned any value that the rotation controllers can take, but only the Keyframe and IK settings make sense
1 = Keyframes
4 = IK

TargetItem("<ID>");

targetobject();
This function, given a source and target object identifier, along with a time index, will return the heading, pitch, and bank values required to make the source object's Z-axis normal face the target object. (This function was added to support a NewTekniques article that provided automated weapons targeting.)
Because targetobject() returns these three rotational values as a vector, its output can be piped directly into the Item Motion's set() method:

UnaffectedByIK();
WorldCoordinateSystem();