Play a Different Animation for a Held Weapon¶

This tutorial makes an existing move branch to a different animation while the character holds a specific weapon. For example, pressing the usual blitz input can play Knife Blitz when a Classic knife is held and keep the normal blitz for every other weapon.

This condition needs a small Lua script. Logic events can branch on frames, buttons, combos, hits, and landings, but they do not have a weapon-condition event.

Before You Start¶

You need:

the normal animation that receives the input, such as Blitz;
a finished weapon-specific animation, such as Knife Blitz;
the exact weapon entity name and its mod name.

Add the weapon-specific animation at the end of the animation list. Animation references use list positions, so inserting or reordering animations can silently change existing references. Note the number shown for the new animation; this tutorial calls it 41.

Enable Can Use Weapons under the character's Logic Settings if the character cannot already pick weapons up.

Create the Redirect Script¶

Create this file inside the editable mod:

Editor/<Your Mod>/Scripts/Knife Blitz.lua

Add:

return function()
    local character = game.this_character

    if character == nil or not character.is_player then
        return true
    end

    local weapon = character.weapon

    if weapon == nil then
        return true
    end

    if weapon.pack_name == "Classic" and weapon.name == "Knife" then
        character.set_animation(41)
        return false
    end

    return true
end

Change 41 to the editor number of your weapon-specific animation. Change Classic and Knife if the weapon comes from another mod or has a different entity name. Name comparisons are case-sensitive.

Using weapon.name is clearer and more portable than comparing a numeric entity_type. Custom entities use runtime hashes, while original entities may use legacy numeric IDs.

Attach It in the Character Editor¶

Open the character and select the normal animation that should redirect, such as Blitz.
In the Inspector, find Script & Behaviour and choose Add Script Data.
Set Mod Name to the mod containing the script.
Set Script Name to Knife Blitz. Omit the .lua extension.
Let the editor save, then launch Test Mod from the game's mod editor.
Trigger the move once without a weapon, once with a different weapon, and once with the knife.

The script's update function runs on every frame while the normal animation is active. When it finds the matching held weapon, set_animation(41) queues the alternate animation. Returning false stops the old animation's controller from continuing during that frame. Returning true in every non-matching case preserves the normal move.

If You Want Several Weapon Variants¶

Use one branch for each weapon, replacing the end of the update function:

if weapon.pack_name == "Classic" and weapon.name == "Knife" then
    character.set_animation(41)
    return false
elseif weapon.pack_name == "Classic" and weapon.name == "Pipe" then
    character.set_animation(42)
    return false
elseif weapon.pack_name == "My Weapons" and weapon.name == "Hammer" then
    character.set_animation(43)
    return false
end

return true

Keep this redirect script on the normal entry animation. Do not attach it to the target animations too, or they can continually queue themselves.

Troubleshooting¶

The normal animation always plays: check the spelling and capitalization of pack_name and name. Temporarily add print(weapon.pack_name, weapon.name) after the nil check, then read the Unity log while testing.

The wrong animation plays: the number passed to set_animation is the animation's current editor list position. Check it again after adding, removing, or reordering animations.

The target animation appears but immediately behaves like another move: select the target animation and configure its events, script, or behaviour override. The redirect only chooses the animation; it does not define that animation's controller.

The character cannot pick up the weapon: enable Can Use Weapons in Player Logic.

The weapon is drawn in the wrong place: select each target frame and configure its Weapon point, direction, and front/behind setting. See Pivots and Offsets.