Roblox Animation Systems

When implementing animations, follow these patterns for smooth, performant character and object animations.

Animation Basics

Loading and Playing Animations

local function setupAnimations(character) local humanoid = character:WaitForChild("Humanoid") local animator = humanoid:WaitForChild("Animator")

-- Create animation instance
local walkAnim = Instance.new("Animation")
walkAnim.AnimationId = "rbxassetid://123456789"

-- Load animation track
local walkTrack = animator:LoadAnimation(walkAnim)

-- Configure track
walkTrack.Priority = Enum.AnimationPriority.Movement
walkTrack.Looped = true

-- Play with parameters
walkTrack:Play(
    0.1,  -- Fade in time
    1,    -- Weight (0-1)
    1     -- Speed multiplier
)

return walkTrack

end

Animation Priorities

-- Priority order (lowest to highest): -- Core < Idle < Movement < Action < Action2 < Action3 < Action4

local function setAnimationPriority(track, priority) track.Priority = priority end

-- Example priority usage idleTrack.Priority = Enum.AnimationPriority.Idle walkTrack.Priority = Enum.AnimationPriority.Movement attackTrack.Priority = Enum.AnimationPriority.Action -- Action always overrides Movement, Movement overrides Idle

Animation Events (Keyframe Markers)

-- Add markers in Animation Editor, then listen: local function setupAnimationEvents(track) -- Listen for specific marker track:GetMarkerReachedSignal("Footstep"):Connect(function(paramValue) playFootstepSound() end)

track:GetMarkerReachedSignal("DamageFrame"):Connect(function()
    applyDamage()
end)

track:GetMarkerReachedSignal("SpawnVFX"):Connect(function(vfxName)
    spawnEffect(vfxName)
end)

end

-- Animation completion track.Stopped:Connect(function() print("Animation stopped or completed") end)

-- Check if playing if track.IsPlaying then -- Animation is active end

Animation Controller

State-Based Animation Controller

local AnimationController = {} AnimationController.__index = AnimationController

function AnimationController.new(character) local self = setmetatable({}, AnimationController)

self.character = character
self.humanoid = character:WaitForChild("Humanoid")
self.animator = self.humanoid:WaitForChild("Animator")
self.tracks = {}
self.currentState = "Idle"
self.stateAnimations = {}

return self

end

function AnimationController:loadAnimation(name, animationId, config) config = config or {}

local animation = Instance.new("Animation")
animation.AnimationId = animationId

local track = self.animator:LoadAnimation(animation)
track.Priority = config.priority or Enum.AnimationPriority.Movement
track.Looped = config.looped or false

self.tracks[name] = track
return track

end

function AnimationController:setState(stateName, fadeTime) fadeTime = fadeTime or 0.1

if self.currentState == stateName then return end

-- Stop current state animation
local currentTrack = self.tracks[self.currentState]
if currentTrack and currentTrack.IsPlaying then
    currentTrack:Stop(fadeTime)
end

-- Play new state animation
local newTrack = self.tracks[stateName]
if newTrack then
    newTrack:Play(fadeTime)
end

self.currentState = stateName

end

function AnimationController:playOneShot(name, fadeTime, weight, speed) local track = self.tracks[name] if track then track:Play(fadeTime or 0.1, weight or 1, speed or 1) end return track end

-- Usage local controller = AnimationController.new(character) controller:loadAnimation("Idle", "rbxassetid://idle", {looped = true, priority = Enum.AnimationPriority.Idle}) controller:loadAnimation("Walk", "rbxassetid://walk", {looped = true, priority = Enum.AnimationPriority.Movement}) controller:loadAnimation("Attack", "rbxassetid://attack", {priority = Enum.AnimationPriority.Action})

controller:setState("Idle") -- When moving: controller:setState("Walk") -- Attack (plays on top): controller:playOneShot("Attack")

Movement-Based Animation Selection

local function setupMovementAnimations(character) local humanoid = character:WaitForChild("Humanoid") local animator = humanoid:WaitForChild("Animator") local hrp = character:WaitForChild("HumanoidRootPart")

local animations = {
    idle = loadAnimation(animator, "rbxassetid://idle"),
    walk = loadAnimation(animator, "rbxassetid://walk"),
    run = loadAnimation(animator, "rbxassetid://run"),
    jump = loadAnimation(animator, "rbxassetid://jump"),
    fall = loadAnimation(animator, "rbxassetid://fall")
}

-- Set looping
animations.idle.Looped = true
animations.walk.Looped = true
animations.run.Looped = true
animations.fall.Looped = true

local currentAnim = nil

local function updateAnimation()
    local velocity = hrp.AssemblyLinearVelocity
    local horizontalSpeed = Vector3.new(velocity.X, 0, velocity.Z).Magnitude
    local isGrounded = humanoid.FloorMaterial ~= Enum.Material.Air

    local targetAnim

    if not isGrounded then
        if velocity.Y > 1 then
            targetAnim = animations.jump
        else
            targetAnim = animations.fall
        end
    elseif horizontalSpeed < 0.5 then
        targetAnim = animations.idle
    elseif horizontalSpeed < 12 then
        targetAnim = animations.walk
        -- Adjust speed based on movement
        animations.walk:AdjustSpeed(horizontalSpeed / 8)
    else
        targetAnim = animations.run
        animations.run:AdjustSpeed(horizontalSpeed / 16)
    end

    if targetAnim ~= currentAnim then
        if currentAnim then
            currentAnim:Stop(0.2)
        end
        targetAnim:Play(0.2)
        currentAnim = targetAnim
    end
end

RunService.Heartbeat:Connect(updateAnimation)

end

Animation Blending

Weight-Based Blending

local BlendedAnimator = {}

function BlendedAnimator.new(animator) return { animator = animator, layers = {} } end

function BlendedAnimator:addLayer(name, animationId, priority) local animation = Instance.new("Animation") animation.AnimationId = animationId

local track = self.animator:LoadAnimation(animation)
track.Priority = priority or Enum.AnimationPriority.Movement
track.Looped = true

self.layers[name] = {
    track = track,
    weight = 0,
    targetWeight = 0
}

track:Play(0, 0)  -- Start at weight 0
return track

end

function BlendedAnimator:setLayerWeight(name, weight, blendTime) local layer = self.layers[name] if not layer then return end

layer.targetWeight = math.clamp(weight, 0, 1)

if blendTime and blendTime > 0 then
    -- Smooth blend
    local startWeight = layer.weight
    local startTime = os.clock()

    local conn
    conn = RunService.Heartbeat:Connect(function()
        local elapsed = os.clock() - startTime
        local t = math.min(elapsed / blendTime, 1)

        layer.weight = startWeight + (layer.targetWeight - startWeight) * t
        layer.track:AdjustWeight(layer.weight)

        if t >= 1 then
            conn:Disconnect()
        end
    end)
else
    layer.weight = layer.targetWeight
    layer.track:AdjustWeight(layer.weight)
end

end

-- Usage: Blend between walk and limp local blender = BlendedAnimator.new(animator) blender:addLayer("Walk", "rbxassetid://walk", Enum.AnimationPriority.Movement) blender:addLayer("Limp", "rbxassetid://limp", Enum.AnimationPriority.Movement)

-- Normal walking blender:setLayerWeight("Walk", 1, 0.3) blender:setLayerWeight("Limp", 0, 0.3)

-- Injured (blend to limp) blender:setLayerWeight("Walk", 0.3, 0.5) blender:setLayerWeight("Limp", 0.7, 0.5)

Additive Animation Blending

-- Additive animations add on top of base animation local function setupAdditiveBlending(animator) local baseWalk = loadAnimation(animator, "rbxassetid://walk") local leanLeft = loadAnimation(animator, "rbxassetid://lean_left") local leanRight = loadAnimation(animator, "rbxassetid://lean_right")

baseWalk.Looped = true
leanLeft.Looped = true
leanRight.Looped = true

baseWalk:Play()
leanLeft:Play(0, 0)  -- Start at 0 weight
leanRight:Play(0, 0)

-- Update lean based on input
local function updateLean(turnAmount)
    -- turnAmount: -1 (left) to 1 (right)
    if turnAmount < 0 then
        leanLeft:AdjustWeight(math.abs(turnAmount))
        leanRight:AdjustWeight(0)
    else
        leanLeft:AdjustWeight(0)
        leanRight:AdjustWeight(turnAmount)
    end
end

return updateLean

end

Procedural Animation

Procedural Head Look

local function setupHeadLook(character, target) local neck = character:FindFirstChild("Neck", true) if not neck then return end

local originalC0 = neck.C0

RunService.RenderStepped:Connect(function()
    if not target then
        neck.C0 = originalC0
        return
    end

    local headPos = neck.Part1.Position
    local targetPos = target.Position
    local direction = (targetPos - headPos).Unit

    -- Convert to local space
    local torsoLook = neck.Part0.CFrame.LookVector
    local torsoCFrame = neck.Part0.CFrame

    local localDirection = torsoCFrame:VectorToObjectSpace(direction)

    -- Calculate angles
    local yaw = math.atan2(localDirection.X, -localDirection.Z)
    local pitch = math.asin(localDirection.Y)

    -- Clamp to prevent unnatural rotation
    yaw = math.clamp(yaw, math.rad(-70), math.rad(70))
    pitch = math.clamp(pitch, math.rad(-40), math.rad(40))

    -- Apply rotation
    local lookCFrame = CFrame.Angles(pitch, yaw, 0)
    neck.C0 = originalC0 * lookCFrame
end)

end

Procedural Breathing

local function setupBreathing(character) local torso = character:FindFirstChild("UpperTorso") or character:FindFirstChild("Torso") if not torso then return end

local waist = character:FindFirstChild("Waist", true)
if not waist then return end

local originalC0 = waist.C0
local breathSpeed = 2  -- Cycles per second
local breathIntensity = 0.02

local time = 0

RunService.RenderStepped:Connect(function(dt)
    time = time + dt

    local breathOffset = math.sin(time * breathSpeed * math.pi * 2) * breathIntensity

    waist.C0 = originalC0 * CFrame.new(0, breathOffset, 0)
end)

end

Procedural Tail/Cape Physics

local function setupProceduralChain(parts, config) config = config or {} local stiffness = config.stiffness or 0.5 local damping = config.damping or 0.3 local gravity = config.gravity or Vector3.new(0, -10, 0)

local velocities = {}
local restOffsets = {}

-- Store rest positions
for i, part in ipairs(parts) do
    velocities[i] = Vector3.new()
    if i > 1 then
        restOffsets[i] = parts[i-1].CFrame:ToObjectSpace(part.CFrame)
    end
end

RunService.Heartbeat:Connect(function(dt)
    for i = 2, #parts do
        local part = parts[i]
        local parent = parts[i-1]

        -- Target position (relative to parent)
        local targetCFrame = parent.CFrame * restOffsets[i]
        local targetPos = targetCFrame.Position

        -- Current position
        local currentPos = part.Position

        -- Spring force toward target
        local displacement = targetPos - currentPos
        local springForce = displacement * stiffness

        -- Apply gravity
        local totalForce = springForce + gravity

        -- Update velocity with damping
        velocities[i] = velocities[i] * (1 - damping) + totalForce * dt

        -- Update position
        local newPos = currentPos + velocities[i]

        -- Maintain distance constraint
        local toParent = parent.Position - newPos
        local distance = toParent.Magnitude
        local restDistance = restOffsets[i].Position.Magnitude

        if distance > restDistance then
            newPos = parent.Position - toParent.Unit * restDistance
        end

        -- Apply
        part.CFrame = CFrame.new(newPos) * (targetCFrame - targetCFrame.Position)
    end
end)

end

Inverse Kinematics (IK)

Two-Bone IK (Arms/Legs)

local function solveTwoBoneIK(upperBone, lowerBone, target, pole) local upperLength = (lowerBone.Position - upperBone.Position).Magnitude local lowerLength = (target - lowerBone.Position).Magnitude

local origin = upperBone.Position
local targetPos = target
local polePos = pole or (origin + Vector3.new(0, 0, 1))

-- Calculate distance to target
local targetDistance = (targetPos - origin).Magnitude
local totalLength = upperLength + lowerLength

-- Clamp target to reachable distance
if targetDistance > totalLength * 0.999 then
    targetDistance = totalLength * 0.999
end

-- Law of cosines to find angles
local a = upperLength
local b = lowerLength
local c = targetDistance

-- Angle at upper joint
local upperAngle = math.acos(
    math.clamp((a*a + c*c - b*b) / (2*a*c), -1, 1)
)

-- Angle at lower joint (elbow/knee)
local lowerAngle = math.acos(
    math.clamp((a*a + b*b - c*c) / (2*a*b), -1, 1)
)

-- Direction to target
local directionToTarget = (targetPos - origin).Unit

-- Calculate pole plane
local poleDirection = (polePos - origin).Unit
local cross = directionToTarget:Cross(poleDirection)
local normal = cross:Cross(directionToTarget).Unit

-- Apply rotations
local upperRotation = CFrame.fromAxisAngle(cross, -upperAngle)
local elbowPosition = origin + upperRotation:VectorToWorldSpace(directionToTarget) * upperLength

return elbowPosition, lowerAngle

end

-- Foot IK for terrain local function setupFootIK(character) local humanoid = character:WaitForChild("Humanoid") local hrp = character:WaitForChild("HumanoidRootPart")

local leftFoot = character:FindFirstChild("LeftFoot")
local rightFoot = character:FindFirstChild("RightFoot")
local leftLeg = character:FindFirstChild("LeftLowerLeg")
local rightLeg = character:FindFirstChild("RightLowerLeg")

local rayParams = RaycastParams.new()
rayParams.FilterDescendantsInstances = {character}

RunService.RenderStepped:Connect(function()
    if humanoid.FloorMaterial == Enum.Material.Air then return end

    -- Raycast for each foot
    for _, footData in ipairs({{leftFoot, leftLeg}, {rightFoot, rightLeg}}) do
        local foot, lowerLeg = footData[1], footData[2]

        local result = workspace:Raycast(
            foot.Position + Vector3.new(0, 1, 0),
            Vector3.new(0, -2, 0),
            rayParams
        )

        if result then
            local targetY = result.Position.Y
            local offset = targetY - foot.Position.Y + 0.1

            -- Apply IK offset (simplified)
            -- In practice, you'd solve the full IK chain
        end
    end
end)

end

Custom Rigs

Motor6D Setup for Custom Rigs

local function createCustomRig(model) local root = model.PrimaryPart local parts = {}

for _, part in ipairs(model:GetDescendants()) do
    if part:IsA("BasePart") and part ~= root then
        table.insert(parts, part)
    end
end

-- Create Motor6Ds
local motors = {}

for _, part in ipairs(parts) do
    local motor = Instance.new("Motor6D")
    motor.Name = part.Name

    -- Find parent part (closest connected part toward root)
    local parentPart = findParentPart(part, root, parts)

    motor.Part0 = parentPart
    motor.Part1 = part

    -- Calculate C0 and C1 (joint positions)
    local jointPos = (parentPart.Position + part.Position) / 2
    motor.C0 = parentPart.CFrame:ToObjectSpace(CFrame.new(jointPos))
    motor.C1 = part.CFrame:ToObjectSpace(CFrame.new(jointPos))

    motor.Parent = parentPart
    motors[part.Name] = motor
end

return motors

end

-- Animate custom rig local function animateCustomRig(motors, animationData) -- animationData: {motorName = {CFrame sequence}}

local time = 0
local duration = animationData.duration or 1

RunService.RenderStepped:Connect(function(dt)
    time = (time + dt) % duration
    local t = time / duration

    for motorName, keyframes in pairs(animationData.motors or {}) do
        local motor = motors[motorName]
        if motor then
            -- Interpolate between keyframes
            local transform = interpolateKeyframes(keyframes, t)
            motor.Transform = transform
        end
    end
end)

end

Humanoid Description for NPCs

local function applyHumanoidDescription(character, description) local humanoid = character:FindFirstChildOfClass("Humanoid") if not humanoid then return end

-- Create or modify description
local desc = description or Instance.new("HumanoidDescription")

-- Body parts
desc.Head = 123456789  -- Asset ID
desc.Torso = 123456789
desc.LeftArm = 123456789
desc.RightArm = 123456789
desc.LeftLeg = 123456789
desc.RightLeg = 123456789

-- Animations
desc.IdleAnimation = 123456789
desc.WalkAnimation = 123456789
desc.RunAnimation = 123456789
desc.JumpAnimation = 123456789
desc.FallAnimation = 123456789

-- Body scales
desc.HeadScale = 1
desc.BodyTypeScale = 0.5
desc.ProportionScale = 1
desc.WidthScale = 1
desc.HeightScale = 1
desc.DepthScale = 1

humanoid:ApplyDescription(desc)

end

Animation Performance

Animation Caching

local AnimationCache = {} AnimationCache.cache = {}

function AnimationCache.load(animator, animationId) local cacheKey = tostring(animator) .. "_" .. animationId

if AnimationCache.cache[cacheKey] then
    return AnimationCache.cache[cacheKey]
end

local animation = Instance.new("Animation")
animation.AnimationId = animationId

local track = animator:LoadAnimation(animation)
AnimationCache.cache[cacheKey] = track

return track

end

function AnimationCache.clear(animator) local prefix = tostring(animator) .. "_"

for key, track in pairs(AnimationCache.cache) do
    if string.sub(key, 1, #prefix) == prefix then
        track:Stop()
        track:Destroy()
        AnimationCache.cache[key] = nil
    end
end

end

LOD for Animations

local AnimationLOD = {}

function AnimationLOD.setup(character, camera) local animator = character:WaitForChild("Humanoid"):WaitForChild("Animator") local hrp = character:WaitForChild("HumanoidRootPart")

local LOD_DISTANCES = {50, 100, 200}
local UPDATE_RATES = {1, 0.5, 0.25, 0.1}  -- Animation update rate

local lastUpdate = 0
local currentLOD = 1

RunService.Heartbeat:Connect(function()
    local distance = (hrp.Position - camera.CFrame.Position).Magnitude

    -- Determine LOD level
    local lodLevel = 1
    for i, threshold in ipairs(LOD_DISTANCES) do
        if distance > threshold then
            lodLevel = i + 1
        end
    end

    -- Update animation rate based on LOD
    if lodLevel ~= currentLOD then
        currentLOD = lodLevel

        -- Adjust all playing animations
        for _, track in ipairs(animator:GetPlayingAnimationTracks()) do
            -- Distant characters: slower animation updates
            -- This is a simplified approach; Roblox handles this internally
        end
    end
end)

end

Pooled Animation Tracks

local TrackPool = {} TrackPool.pools = {}

function TrackPool.getTrack(animator, animationId) local poolKey = animationId

if not TrackPool.pools[poolKey] then
    TrackPool.pools[poolKey] = {
        available = {},
        inUse = {}
    }
end

local pool = TrackPool.pools[poolKey]

-- Check for available track
local track = table.remove(pool.available)

if not track then
    -- Create new track
    local animation = Instance.new("Animation")
    animation.AnimationId = animationId
    track = animator:LoadAnimation(animation)
end

table.insert(pool.inUse, track)
return track

end

function TrackPool.releaseTrack(animationId, track) local pool = TrackPool.pools[animationId] if not pool then return end

track:Stop(0)

local index = table.find(pool.inUse, track)
if index then
    table.remove(pool.inUse, index)
end

table.insert(pool.available, track)

end

Animation Tools

Animation Recording

local AnimationRecorder = {}

function AnimationRecorder.record(character, duration) local humanoid = character:FindFirstChildOfClass("Humanoid") local motors = {}

-- Find all Motor6Ds
for _, motor in ipairs(character:GetDescendants()) do
    if motor:IsA("Motor6D") then
        table.insert(motors, motor)
    end
end

local keyframes = {}
local startTime = os.clock()
local recording = true

-- Record at 30 fps
local frameTime = 1/30
local lastFrame = 0

local conn
conn = RunService.Heartbeat:Connect(function()
    local elapsed = os.clock() - startTime

    if elapsed >= duration then
        recording = false
        conn:Disconnect()
        return
    end

    if elapsed - lastFrame >= frameTime then
        lastFrame = elapsed

        local frame = {
            time = elapsed,
            poses = {}
        }

        for _, motor in ipairs(motors) do
            frame.poses[motor.Name] = {
                C0 = motor.C0,
                C1 = motor.C1,
                Transform = motor.Transform
            }
        end

        table.insert(keyframes, frame)
    end
end)

-- Return promise-like
return {
    getKeyframes = function()
        while recording do
            task.wait()
        end
        return keyframes
    end
}

end

Animation Playback from Data

local function playRecordedAnimation(character, keyframes) local motors = {}

for _, motor in ipairs(character:GetDescendants()) do
    if motor:IsA("Motor6D") then
        motors[motor.Name] = motor
    end
end

local duration = keyframes[#keyframes].time
local startTime = os.clock()

local conn
conn = RunService.Heartbeat:Connect(function()
    local elapsed = os.clock() - startTime

    if elapsed >= duration then
        conn:Disconnect()
        return
    end

    -- Find surrounding keyframes
    local prevFrame, nextFrame
    for i, frame in ipairs(keyframes) do
        if frame.time <= elapsed then
            prevFrame = frame
            nextFrame = keyframes[i + 1]
        end
    end

    if not prevFrame or not nextFrame then return end

    -- Interpolate
    local t = (elapsed - prevFrame.time) / (nextFrame.time - prevFrame.time)

    for motorName, motor in pairs(motors) do
        local prevPose = prevFrame.poses[motorName]
        local nextPose = nextFrame.poses[motorName]

        if prevPose and nextPose then
            motor.Transform = prevPose.Transform:Lerp(nextPose.Transform, t)
        end
    end
end)

return conn

end

Procedural KeyframeSequence Generation

This section covers creating animations entirely from code without using the Animation Editor.

KeyframeSequence Structure

KeyframeSequences contain Keyframes, which contain hierarchical Poses matching the rig structure.

--[[ KeyframeSequence Structure:

KeyframeSequence
├── Keyframe (Time = 0.0)
│   └── Pose "HumanoidRootPart"
│       └── Pose "LowerTorso"
│           ├── Pose "UpperTorso"
│           │   ├── Pose "Head"
│           │   ├── Pose "LeftUpperArm"
│           │   │   └── Pose "LeftLowerArm"
│           │   │       └── Pose "LeftHand"
│           │   └── Pose "RightUpperArm"
│           │       └── Pose "RightLowerArm"
│           │           └── Pose "RightHand"
│           ├── Pose "LeftUpperLeg"
│           │   └── Pose "LeftLowerLeg"
│           │       └── Pose "LeftFoot"
│           └── Pose "RightUpperLeg"
│               └── Pose "RightLowerLeg"
│                   └── Pose "RightFoot"
├── Keyframe (Time = 0.5)
│   └── ... (same hierarchy)
└── Keyframe (Time = 1.0)
    └── ... (same hierarchy)

]]

R15 Rig Hierarchy

The pose hierarchy MUST match the R15 rig structure for animations to work:

local R15_HIERARCHY = { HumanoidRootPart = { LowerTorso = { UpperTorso = { Head = {}, LeftUpperArm = { LeftLowerArm = { LeftHand = {} } }, RightUpperArm = { RightLowerArm = { RightHand = {} } }, }, LeftUpperLeg = { LeftLowerLeg = { LeftFoot = {} } }, RightUpperLeg = { RightLowerLeg = { RightFoot = {} } }, } } }

Motor6D Locations in R15

Motor6Ds are stored in the CHILD part, not the parent:

Motor6D Name Located In Connects

Root LowerTorso HumanoidRootPart → LowerTorso

Waist UpperTorso LowerTorso → UpperTorso

Neck Head UpperTorso → Head

LeftShoulder LeftUpperArm UpperTorso → LeftUpperArm

RightShoulder RightUpperArm UpperTorso → RightUpperArm

LeftElbow LeftLowerArm LeftUpperArm → LeftLowerArm

RightElbow RightLowerArm RightUpperArm → RightLowerArm

LeftWrist LeftHand LeftLowerArm → LeftHand

RightWrist RightHand RightLowerArm → RightHand

LeftHip LeftUpperLeg LowerTorso → LeftUpperLeg

RightHip RightUpperLeg LowerTorso → RightUpperLeg

LeftKnee LeftLowerLeg LeftUpperLeg → LeftLowerLeg

RightKnee RightLowerLeg RightUpperLeg → RightLowerLeg

LeftAnkle LeftFoot LeftLowerLeg → LeftFoot

RightAnkle RightFoot RightLowerLeg → RightFoot

R15 Motor6D Rotation Directions (Verified)

CRITICAL: These rotation directions were verified through actual testing. All rotations are in radians.

RightShoulder (in RightUpperArm)

• X+: Forward/down (arm rotates forward toward chest)

• X-: Back/up (arm rotates backward)

• Y+: Twist arm inward (palm faces down)

• Y-: Twist arm outward (palm faces up)

• Z+: Raise arm sideways (abduction)

• Z-: Lower arm (adduction)

LeftShoulder (in LeftUpperArm)

• X+: Forward/down

• X-: Back/up

• Y+: Twist outward

• Y-: Twist inward

• Z+: Lower arm

• Z-: Raise arm sideways

RightElbow (in RightLowerArm)

• X+: Bend elbow (forearm toward bicep)

• X-: Extend elbow (straighten arm)

LeftElbow (in LeftLowerArm)

• X+: Bend elbow

• X-: Extend elbow

Waist (in UpperTorso)

• X+: Lean forward (bow)

• X-: Lean backward

• Y+: Twist left

• Y-: Twist right

• Z+: Tilt left

• Z-: Tilt right

RightHip (in RightUpperLeg)

• X+: Leg backward (behind body)

• X-: Leg forward (kick forward)

• Z+: Leg outward (spread)

• Z-: Leg inward

LeftHip (in LeftUpperLeg)

• X+: Leg backward

• X-: Leg forward

• Z+: Leg inward

• Z-: Leg outward

RightKnee (in RightLowerLeg)

• X+: Bend knee (foot toward buttocks)

• X-: Extend knee (straighten leg)

LeftKnee (in LeftLowerLeg)

• X+: Bend knee

• X-: Extend knee

Neck (in Head)

• X+: Look down

• X-: Look up

• Y+: Turn left

• Y-: Turn right

• Z+: Tilt head left

• Z-: Tilt head right

Building KeyframeSequence Programmatically

local function rad(d) return math.rad(d) end

local function buildPoseHierarchy(hierarchy, rotations, parentPose) for jointName, children in pairs(hierarchy) do local pose = Instance.new("Pose") pose.Name = jointName pose.Weight = 1

    local rot = rotations[jointName]
    if rot then
        -- rot = {X, Y, Z} in degrees
        pose.CFrame = CFrame.Angles(rad(rot[1]), rad(rot[2]), rad(rot[3]))
    else
        pose.CFrame = CFrame.new()
    end

    pose.Parent = parentPose

    if children and next(children) then
        buildPoseHierarchy(children, rotations, pose)
    end
end

end

local function createKeyframeSequence(name, priority, keyframes) local sequence = Instance.new("KeyframeSequence") sequence.Name = name sequence.Loop = false sequence.Priority = priority or Enum.AnimationPriority.Action

for _, kfData in ipairs(keyframes) do
    local keyframe = Instance.new("Keyframe")
    keyframe.Time = kfData.time
    buildPoseHierarchy(R15_HIERARCHY, kfData.poses, keyframe)
    sequence:AddKeyframe(keyframe)
end

return sequence

end

Example: Sword Slash Animation

local slashSequence = createKeyframeSequence("SwordSlash", Enum.AnimationPriority.Action, { -- Wind up: rotate torso left, arm back { time = 0.0, poses = { UpperTorso = {0, -30, 0}, -- Twist right (wind up) RightUpperArm = {-90, -45, -90}, -- Arm back and raised RightLowerArm = {-45, 0, 0}, -- Elbow bent }}, -- Mid swing { time = 0.15, poses = { UpperTorso = {0, 45, 0}, -- Twist left (swing through) RightUpperArm = {-45, 90, -90}, -- Arm coming down RightLowerArm = {0, 0, 0}, -- Elbow extending }}, -- Follow through { time = 0.3, poses = { UpperTorso = {0, 60, 0}, -- Full twist left RightUpperArm = {30, 90, -45}, -- Arm across body RightLowerArm = {0, 0, 0}, }}, -- Return to neutral { time = 0.5, poses = { UpperTorso = {0, 0, 0}, RightUpperArm = {0, 0, 0}, RightLowerArm = {0, 0, 0}, }}, })

Playing Animations Without Publishing (Studio Testing)

Use KeyframeSequenceProvider:RegisterKeyframeSequence() to create temporary animation IDs for testing in Studio without needing to publish:

local KeyframeSequenceProvider = game:GetService("KeyframeSequenceProvider")

local function playProceduralAnimation(animator, sequence) -- Register returns a temporary hash ID like "rbxassetid://12345" local hashId = KeyframeSequenceProvider:RegisterKeyframeSequence(sequence)

local animation = Instance.new("Animation")
animation.AnimationId = hashId

local track = animator:LoadAnimation(animation)
track:Play()

return track

end

-- Usage local character = player.Character local humanoid = character:WaitForChild("Humanoid") local animator = humanoid:FindFirstChildOfClass("Animator") if not animator then animator = Instance.new("Animator") animator.Parent = humanoid end

local track = playProceduralAnimation(animator, slashSequence)

Complete Tool Animation Example

A complete example that creates tools and plays animations on activation:

--[[ Complete Animation Tool - Place in StarterPlayerScripts as LocalScript ]]

local Players = game:GetService("Players") local KeyframeSequenceProvider = game:GetService("KeyframeSequenceProvider")

local player = Players.LocalPlayer

local function rad(d) return math.rad(d) end

local R15_HIERARCHY = { HumanoidRootPart = { LowerTorso = { UpperTorso = { Head = {}, LeftUpperArm = { LeftLowerArm = { LeftHand = {} } }, RightUpperArm = { RightLowerArm = { RightHand = {} } }, }, LeftUpperLeg = { LeftLowerLeg = { LeftFoot = {} } }, RightUpperLeg = { RightLowerLeg = { RightFoot = {} } }, } } }

local function buildPoseHierarchy(hierarchy, rotations, parentPose) for jointName, children in pairs(hierarchy) do local pose = Instance.new("Pose") pose.Name = jointName pose.Weight = 1 local rot = rotations[jointName] if rot then pose.CFrame = CFrame.Angles(rad(rot[1]), rad(rot[2]), rad(rot[3])) else pose.CFrame = CFrame.new() end pose.Parent = parentPose if children and next(children) then buildPoseHierarchy(children, rotations, pose) end end end

local function createAnimation(name, priority, keyframes) local sequence = Instance.new("KeyframeSequence") sequence.Name = name sequence.Loop = false sequence.Priority = priority for _, kf in ipairs(keyframes) do local keyframe = Instance.new("Keyframe") keyframe.Time = kf.time buildPoseHierarchy(R15_HIERARCHY, kf.poses, keyframe) sequence:AddKeyframe(keyframe) end return sequence end

-- Define animations with verified rotations local punchSequence = createAnimation("Punch", Enum.AnimationPriority.Action, { { time = 0.0, poses = { UpperTorso = {0, -20, 0}, RightUpperArm = {-45, -30, -45}, RightLowerArm = {-90, 0, 0} }}, { time = 0.1, poses = { UpperTorso = {0, 30, 0}, RightUpperArm = {-90, 60, -90}, RightLowerArm = {-10, 0, 0} }}, { time = 0.2, poses = { UpperTorso = {0, 45, 0}, RightUpperArm = {-90, 90, -90}, RightLowerArm = {0, 0, 0} }}, { time = 0.4, poses = { UpperTorso = {0, 0, 0}, RightUpperArm = {0, 0, 0}, RightLowerArm = {0, 0, 0} }}, })

local function setup() local character = player.Character or player.CharacterAdded:Wait() local humanoid = character:WaitForChild("Humanoid") local animator = humanoid:FindFirstChildOfClass("Animator") if not animator then animator = Instance.new("Animator") animator.Parent = humanoid end

-- Register and load animation
local hashId = KeyframeSequenceProvider:RegisterKeyframeSequence(punchSequence)
local animation = Instance.new("Animation")
animation.AnimationId = hashId
local track = animator:LoadAnimation(animation)

-- Create tool
local tool = Instance.new("Tool")
tool.Name = "Punch"
tool.RequiresHandle = true
tool.CanBeDropped = false

local handle = Instance.new("Part")
handle.Name = "Handle"
handle.Size = Vector3.new(1, 1, 1)
handle.Transparency = 1
handle.Parent = tool

tool.Parent = player:WaitForChild("Backpack")

local debounce = false
tool.Activated:Connect(function()
    if debounce then return end
    debounce = true
    track:Play()
    task.wait(0.5)
    debounce = false
end)

end

player.CharacterAdded:Connect(function() task.wait(1) setup() end) if player.Character then setup() end

Smooth Animation with Many Keyframes

For fluid animations, use 20-30 keyframes with small incremental changes:

-- Generates a smooth punch animation with 26 frames local function generateSmoothPunch() local frames = {} local totalTime = 0.7

-- Phase 1: Wind up (0.0 - 0.15s)
for i = 0, 5 do
    local t = i / 5 * 0.15
    local progress = i / 5
    table.insert(frames, {
        time = t,
        poses = {
            UpperTorso = {0, -20 * progress, 0},
            RightUpperArm = {-45 * progress, -30 * progress, -45 * progress},
            RightLowerArm = {-90 * progress, 0, 0}
        }
    })
end

-- Phase 2: Strike (0.15 - 0.35s)
for i = 1, 10 do
    local t = 0.15 + (i / 10 * 0.2)
    local progress = i / 10
    table.insert(frames, {
        time = t,
        poses = {
            UpperTorso = {0, -20 + 65 * progress, 0},
            RightUpperArm = {-45 - 45 * progress, -30 + 120 * progress, -45 - 45 * progress},
            RightLowerArm = {-90 + 90 * progress, 0, 0}
        }
    })
end

-- Phase 3: Recovery (0.35 - 0.7s)
for i = 1, 10 do
    local t = 0.35 + (i / 10 * 0.35)
    local progress = i / 10
    table.insert(frames, {
        time = t,
        poses = {
            UpperTorso = {0, 45 * (1 - progress), 0},
            RightUpperArm = {-90 * (1 - progress), 90 * (1 - progress), -90 * (1 - progress)},
            RightLowerArm = {0, 0, 0}
        }
    })
end

return createAnimation("SmoothPunch", Enum.AnimationPriority.Action, frames)

end

Animation Easing Functions

Apply easing for natural movement:

local Easing = {}

function Easing.easeInOut(t) return t < 0.5 and 2 * t * t or 1 - (-2 * t + 2)^2 / 2 end

function Easing.easeOut(t) return 1 - (1 - t)^3 end

function Easing.easeIn(t) return t * t * t end

-- Apply to keyframe generation local function interpolateWithEasing(startValue, endValue, t, easingFunc) local easedT = easingFunc(t) return startValue + (endValue - startValue) * easedT end