IKControl
Specifies a control to generate a procedural animation pose using Inverse Kinematics.
Memory category | Animation |
---|
Member index 17
Removed member index 1
History | Member | |
---|---|---|
554 | AlignmentOffset: CFrame |
Description
IKControl instances generate procedural animation poses using Inverse Kinematics (IK). They allow you to make characters respond realistically to their environment.
For example, you can make a character place its hand on a door handle exactly, and the character will do so independently of its position. IKControls provide the advantage of needing to create much fewer animations for your game while giving your experience a more realistic and polished feel.
IKControls must be a child of a Humanoid or AnimationController with an Animator and have all of their required properties set properly, otherwise they don't have any effect. The required properties are Type, EndEffector, Target, ChainRoot. As soon as those are set, the IkControl modifies the pose of your character as you specify. The following code sample demonstrates how to set up your first IKControl and get started with creating more realistic animations for your game.
You can use IKControls to make a character:
- Rotate its head and torso to look at a point of interest in the world.
- Modify its feet positions to respond to dynamic terrain. Adjust its legs and feet to place them accordingly on terrain with rocks and slopes.
- Hold a gun and place its hands appropriately on the grip without needing to create animations for each gun in the game.
- Aim at a point in the world, so that the tip of the gun point exactly at what you want to shoot. Especially useful in third person shooters.
- Place its hands on the steering wheel of a car and follow it when it rotates.
- Much more!
IKControl will override the animation for all the parts between the ChainRoot and the EndEffector. You can enable/disable it using Enabled or change how much they have an effect over the underlying animation using the Weight. Be careful: if you do not set up your IKControls correctly, you might generate bad and unrealistic poses!
History 37
- 582 Change Tags of GetSmoothedFinalTarget from [NotBrowsable] to []
- 582 Change Tags of GetRawFinalTarget from [NotBrowsable] to []
- 582 Change Tags of GetNodeWorldCFrame from [NotBrowsable] to []
- 582 Change Tags of GetNodeLocalCFrame from [NotBrowsable] to []
- 568 Add GetSmoothedFinalTarget
- 568 Add GetRawFinalTarget
- 568 Add GetNodeWorldCFrame
- 568 Add GetNodeLocalCFrame
- 560 Change Tags of IKControl from [NotBrowsable] to []
- 559 Add SmoothTime
- 554 Add GetChainLength
- 554 Add GetChainCount
- 554 Add EndEffectorOffset
- 554 Remove AlignmentOffset
- 553 Change Default of Weight from to 1
- 553 Change Default of Type from to Transform
- 553 Change Default of Target from to
- 553 Change Default of Priority from to 0
- 553 Change Default of Pole from to
- 553 Change Default of Offset from to
- 553 Change Default of EndEffector from to
- 553 Change Default of Enabled from to true
- 553 Change Default of ChainRoot from to
- 553 Change Default of AlignmentOffset from to
- 548 Add Pole
- 548 Add AlignmentOffset
- 546 Remove Pole
- 543 Add Offset
- 542 Add Weight
- 542 Add Type
- 542 Add Target
- 542 Add Priority
- 542 Add Pole
- 542 Add EndEffector
- 542 Add Enabled
- 542 Add ChainRoot
- 542 Add IKControl
Members 17
ChainRoot
Type | Default | |
---|---|---|
Instance |
By specifying a ChainRoot and an EndEffector, you instruct the IKControl that it's allowed to move and rotate all parts between the two to move the EndEffector to the Target. For example, if you specify the LeftHand as EndEffector and LeftUpperArm as the ChainRoot, the control moves 3 parts: the LeftHand, the LeftLowerArm, and the LeftUpperArm. Avoid setting ChainRoot as the actual root of the character because that produces unrealistic results.
Thread safety | ReadSafe |
---|---|
Category | Behavior |
Loaded/Saved | true |
Enabled
Type | Default | |
---|---|---|
bool | true |
This property allows you to toggle the IK control on and off. It's on by default. When Enabled is false, the IK control is off and isn't resolved by the underlying solver.
Thread safety | ReadSafe |
---|---|
Category | Behavior |
Loaded/Saved | true |
EndEffector
Type | Default | |
---|---|---|
Instance |
The EndEffector describes the last part in the chain of your character that you want to affect. For example, it could be the hand when you want to move the whole arm to reach a point. It can be a BasePart on a character, that has a Motor6D as its child, a Motor6D directly, a Bone, or a Attachment. The pivot of the selected EndEffector moves to the Target, so you can use Attachments to modify which point of a BasePart should reach the Target.
Thread safety | ReadSafe |
---|---|
Category | Behavior |
Loaded/Saved | true |
History 2
- 553 Change Default of EndEffector from to
- 542 Add EndEffector
EndEffectorOffset
Type | Default | |
---|---|---|
CFrame |
The end-effector offset is an additional CFrame applied on top of the Target CFrame that produces the final CFrame used to place the EndEffector. By default, it's the identity CFrame, so if you don't set it, it has no effect and the EndEffector uses the Target CFrame directly, which is specified in the local space of the EndEffector.
Alternatively, you can use Attachments by setting an Attachment as EndEffector, which moves it to the Target instead of the parts it's attached to, effectively obtaining the same result.
You can also use EndEffectorOffset to
modify which axis of the EndEffector should
point at the Target when using LookAt
as
Type.
Thread safety | ReadSafe |
---|---|
Category | Behavior |
Loaded/Saved | true |
History 1
- 554 Add EndEffectorOffset
GetChainCount
Parameters (0) | ||
---|---|---|
No parameters. | ||
Returns (1) | ||
int |
Thread safety | Unsafe |
---|
History 1
- 554 Add GetChainCount
GetChainLength
Parameters (0) | ||
---|---|---|
No parameters. | ||
Returns (1) | ||
float |
Thread safety | Unsafe |
---|
History 1
- 554 Add GetChainLength
GetNodeLocalCFrame
Parameters (1) | ||
---|---|---|
index | int | |
Returns (1) | ||
CFrame |
Thread safety | Unsafe |
---|
History 2
- 582 Change Tags of GetNodeLocalCFrame from [NotBrowsable] to []
- 568 Add GetNodeLocalCFrame
GetNodeWorldCFrame
Parameters (1) | ||
---|---|---|
index | int | |
Returns (1) | ||
CFrame |
Thread safety | Unsafe |
---|
History 2
- 582 Change Tags of GetNodeWorldCFrame from [NotBrowsable] to []
- 568 Add GetNodeWorldCFrame
GetRawFinalTarget
Parameters (0) | ||
---|---|---|
No parameters. | ||
Returns (1) | ||
CFrame |
Thread safety | Unsafe |
---|
History 2
- 582 Change Tags of GetRawFinalTarget from [NotBrowsable] to []
- 568 Add GetRawFinalTarget
GetSmoothedFinalTarget
Parameters (0) | ||
---|---|---|
No parameters. | ||
Returns (1) | ||
CFrame |
Thread safety | Unsafe |
---|
History 2
- 582 Change Tags of GetSmoothedFinalTarget from [NotBrowsable] to []
- 568 Add GetSmoothedFinalTarget
Offset
Type | Default | |
---|---|---|
CFrame |
The offset is an additional CFrame applied on top of the Target CFrame that produces the final CFrame used to place the EndEffector. It's identity by default, so if you don't set it, it has no effect and the EndEffector will use the Target CFrame directly. You can animate it to create procedural animations such as typing on a keyboard. It's useful when the Target and EndEffector aren't aligned and you need to fix it with an additional rotation or translation.
Thread safety | ReadSafe |
---|---|
Category | Behavior |
Loaded/Saved | true |
Pole
Type | Default | |
---|---|---|
Instance |
The Pole is an optional Instance that gives you control over how intermediate parts in your character should bend. It can be anything that has a position in the world, such as BasePart, Attachment, Bone, Motor6D. It is by default nil. When you specify it, the underlying solver will make the parts bend towards it. When it is nil, the solver will try to make elbows and knees bend appropriately based on the limb of the character. The limb will be "Arm" when you select as EndEffector either the LeftHand or RightHand and as ChainRoot the corresponding LeftUpperArm or RightUpperArm, and it will be "Leg" when you select as EndEffector either the LeftFoot or RightFoot and as ChainRoot the corresponding LeftUpperLeg or RightUpperLeg. In all other cases, if you don't specify a pole, the chain might not bend as you expect.
Thread safety | ReadSafe |
---|---|
Category | Behavior |
Loaded/Saved | true |
Priority
Type | Default | |
---|---|---|
int | 0 |
When multiple controls are active on a character, the order in which they are solved by the underlying system affects the final generated pose. By changing this value, you specify the ordering in which controls are satisfied. Higher values have higher priority, and higher-priority controls are resolved later because their result might override the previous result of other controls. If you have multiple IK controls on a character and one is more important than the other, specify a lower priority for it. It is 0 by default, meaning all controls have the same priority.
Thread safety | ReadSafe |
---|---|
Category | Behavior |
Loaded/Saved | true |
SmoothTime
Type | Default | |
---|---|---|
float | 0.0500000007 |
This value specifies the average number of seconds that it takes for the EndEffector to reach the Target. The behavior is that of a critically-damped spring, where the rate of change is proportional to the distance to the target and no oscillations are present when approaching the target. Smaller values create a quicker convergence, and larger values create a slower convergence. A value of 0 disables smoothing. The default value is 0.05 to provide a very slight smoothing that makes the motion feel realistic.
Thread safety | ReadSafe |
---|---|
Category | Behavior |
Loaded/Saved | true |
History 1
- 559 Add SmoothTime
Target
Type | Default | |
---|---|---|
Instance |
The Target represents a point (CFrame) in the world that you want your EndEffector to reach. The exact behavior of reaching can be set via the Type property, and an additional Offset can be applied on top of it to modify it. If you set a Target that will be moved either by physics or a script, at each frame the IKControl will try to satisfy it, automatically updating the point to reach.
Thread safety | ReadSafe |
---|---|
Category | Behavior |
Loaded/Saved | true |
Type
Type | Default | |
---|---|---|
IKControlType | Transform |
By changing the Type, you can change the behavior of the control. These are the available options:
- Transform: it's a full 6-DoF constraint. Aligns the EndEffector CFrame to that of the Target.
- Position: aligns the EndEffector position to that of the Target.
- Rotation: aligns the EndEffector rotation to that of the Target.
- LookAt: moves and orients the whole chain to make an axis (by default the forward axis) on the EndEffector point at a position in the world specified by Target.
Thread safety | ReadSafe |
---|---|
Category | Behavior |
Loaded/Saved | true |
Weight
Type | Default | |
---|---|---|
float | 1 |
You can control how much a given control affects the character pose by using this property. Values should be in the [0, 1] range. 0 means no effect, and 1 means full effect of the IK control. Values outside this range are truncated. Smoothly varying this value allows you to blend in or out a specific control to avoid jarring motion. It is 1 by default.
The weight determines the interpolation factor between the End-Effector and the IK target. Setting the weight to 0 doesn't disable the IK Control because other factors, including the SmoothTime smoothing factor and Pole, can still change the pose. To truly disable the IK Control, turn the Enabled property to false.
Thread safety | ReadSafe |
---|---|
Category | Behavior |
Loaded/Saved | true |
Removed members 1
AlignmentOffset
Type | Default | |
---|---|---|
CFrame |
Thread safety | ReadSafe |
---|---|
Category | Behavior |
Loaded/Saved | true |
History 3
- 554 Remove AlignmentOffset
- 553 Change Default of AlignmentOffset from to
- 548 Add AlignmentOffset