Skip to content

IKAnchor

IKAnchors are objects that can be used to control player animations. They can be used to specify the position of a specific hand, foot, or the hips of a player, and can be controlled from script to create complex animations.

Properties

Property Name Return Type Description Tags
target Player Which Player the IKAnchor is activated on. Read-Only
anchorType IKAnchorType Which socket this IKAnchor applies to. Read-Only
blendInTime number The duration over which this IKAnchor is blended when it is activated. Read-Write
blendOutTime number The duration over which this IKAnchor is blended when it is deactivated. Read-Write
weight number The amount this IKAnchor blends with the underlying animation. A value of 0 means the animation is player unchanged, and a value of 1 means the animation is ignored and the IKAnchor is used. Read-Write

Functions

Function Name Return Type Description Tags
Activate(Player) None Activates the IKAnchor on the given player. None
Deactivate() None Deactivates the IKAnchor from whatever player it is active on. None
GetAimOffset() Vector3 Returns the aim offset property. None
SetAimOffset(Vector3) None Sets the aim offset of this IKAnchor. None

Events

Event Name Return Type Description Tags
activatedEvent Event<IKAnchor ikAnchor, Player player> Fired when this IKAnchor is activated on a player. None
deactivatedEvent Event<IKAnchor ikAnchor, Player player> Fired when this IKAnchor is deactivated from a player. None

Examples

Example using:

activatedEvent

deactivatedEvent

In this example, a point light is turned on/off in response to the IK Anchor being activated/deactivated.

local POINT_LIGHT = script:GetCustomProperty("PointLight"):WaitForObject()
local IK_ANCHOR = script.parent

POINT_LIGHT.visibility = Visibility.FORCE_OFF

function OnActivated(ik, player)
    POINT_LIGHT.visibility = Visibility.INHERIT
end

function OnDeactivated(ik, player)
    POINT_LIGHT.visibility = Visibility.FORCE_OFF
end

IK_ANCHOR.activatedEvent:Connect(OnActivated)
IK_ANCHOR.deactivatedEvent:Connect(OnDeactivated)

See also: CoreObject.visibility | CoreObjectReference.WaitForObject | Event.Connect


Example using:

Activate

Deactivate

In this example, the local player is tilted forward when they run. This is done by slightly rotating a pelvis IK anchor forwards and then activating and deactivating it depending on the speed of the player.

-- Core object reference to a pelvis IK anchor
local IKAnchor = script:GetCustomProperty("IKAnchor"):WaitForObject()

-- The minimum speed the player has to be moving at for the IK anchors to be activated
local ACTIVATION_SPEED = 500

-- How many degrees forward the player will lean when running
local LEAN_ANGLE = 15

local player = Game.GetLocalPlayer()

-- Store the current activation status of the IK Anchor
local isActivated = false

local isMovingForward = false

local function OnActionPressed(player, action, value)
    if action == "Move" then
        if value.x == 1 then
            isMovingForward = true
        else
            isMovingForward = false
        end
    end
end

local function OnActionReleased(player, action)
    if action == "Move" then
        isMovingForward = false
    end
end

-- Attach the IK Anchor object to the root joint of the player so they move together
IKAnchor:AttachToPlayer(player, "pelvis")
IKAnchor:SetRotation(Rotation.New(0, -LEAN_ANGLE, 0))

function Tick(deltaTime)
-- Deactivate the IK Anchor if the player is not grounded, not pressing the "W" key, or not moving faster than the `ACTIVATION_SPEED`
    if((not player.isWalking or not isMovingForward or player:GetVelocity().size <= ACTIVATION_SPEED) and isActivated) then
        IKAnchor:Deactivate(player)
        isActivated = false
    -- Only activate the IK Anchor if the player is grounded, pressing the "W" key, and moving faster than the `ACTIVATION_SPEED`
    elseif (player.isWalking and not isActivated and isMovingForward and player:GetVelocity().size > ACTIVATION_SPEED) then
        IKAnchor:Activate(player)
        isActivated = true
    end
end

Input.actionPressedEvent:Connect(OnActionPressed)
Input.actionReleasedEvent:Connect(OnActionReleased)

See also: CoreObject.AttachToPlayer | Input.actionPressedEvent | Game.GetLocalPlayer


Example using:

anchorType

Activate

Deactivate

This example adds a layer of decision-making when activating/deactivating IK Anchors. With this approach, a more complex project, with multiple IK can be applied to players at the same time. If two anchors of the same type (for example Left Hand) are activated on the same player, then they go onto a stack and can remain consistent regardless of the order in which activate/deactivate are called. Without such an approach, multiple game systems may be fighting for the limited IK slots, with undesirable results.

function ActivateIK(player, ikAnchor)
    local stack = GetIKStack(player, ikAnchor)

    table.insert(stack, ikAnchor)

    ikAnchor:Activate(player)
end

function DeactivateIK(player, ikAnchor)
    local stack = GetIKStack(player, ikAnchor)

    for i = #stack, 1, -1 do
        if stack[i] == ikAnchor then
            table.remove(stack, i)

            if #stack == 0 then
                ikAnchor:Deactivate()

            elseif i == #stack + 1 then
                local previousIK = stack[#stack]
                previousIK:Activate(player)
            end
            return
        end
    end
end

function GetIKStack(player, ikAnchor)
    local type = ikAnchor.anchorType

    if player.clientUserData.IKStack == nil then
        player.clientUserData.IKStack = {}
    end
    if player.clientUserData.IKStack[type] == nil then
        player.clientUserData.IKStack[type] = {}
    end
    return player.clientUserData.IKStack[type]
end

See also: Player.clientUserData



Last update: April 11, 2022