Custom preset animations setup

The following guide explains how to create your own custom preset animations for the nss_emotes resource. You can create your own animations by using the available functions in LUA and make them available in your JavaScript config files to show them in the emote menu.

We do not provide support for creating custom preset animations, but this guide should help you to get started.

Use on your own risk!

---

Basics

To create your own custom preset animations there are two important things to consider:

• First, you need to create the actual animation setup in LUA using the available functions.

• Second, you need to make the newly created animations available in your JavaScript config files.

It is helpful to have an idea how animations in REDM work. You can find more information about that in the animation presets.

---

Steps to create custom preset animations

1. Create a new file in the folder nss_emotes/animations/ named e.g. my_custom_animations.lua.

2. Add your custom animations using the available functions (see below) to the newly created file. See animation presets for available preset animations.

3. Make the new animations available in your JavaScript config file (e.g. nss_emotes/html_nss_emotes/config.js) to show them in the emote menu.

4. Restart the resource or your server to apply the changes.

5. Test your new custom animations in-game.

6. Enjoy your custom animations!

---

Simple example

1. Create a new file (if not allready exists) nss_emotes/animations/my_custom_animations.lua with the following content:

   -- Add a simple animation that can be triggered by the command 'act mywave'.
   addSimpleAnimation(
           'mywave',
           'mech_loco_m@character@dutch@fancy@unarmed@idle@_variations',
           'idle_a',
           nil,
           nil,
           3000,
           31
   )

2. Add the new animation to your JavaScript config file (e.g. nss_emotes/html_nss_emotes/config.js):

   // Add the new animation to the config file to make it available in the emote menu.
   // In this example, we add it to the root wheel with the shortcut if `addButton`.
   root_wheel.addButton(
       'My Wave', // button label
       'act mywave', // command to trigger the animation
       'mywave.png' // optional button icon
   );

3. Restart the resource or your server to apply the changes.

4. You can now trigger the animation by using the command act mywave or by selecting it in the emote menu.

5. Enjoy your custom animation!

---

Working with prefixes

It is recommended to use a prefix for your custom animation commands to avoid conflicts.

For example, if you set Config.AnimationEmotePrefix to emote-, you can define your custom animation command as emote-mywave instead of just mywave.

There are some prefixes you can choose from, e.g.:

Config.AnimationEmotePrefix = 'emote-' -- Prefix for emote animations.
Config.AnimationLoopPrefix = 'loop-' -- Prefix for loop animations.
Config.AnimationPartnerPrefix = 'partner-' -- Prefix for partner animations.

All these prefixes are used in the base command act <command> to trigger the animation. For example, if you use the emote- prefix, the full command to trigger the animation would be act emote-mywave.

Example:

addSimpleAnimation(
        Config.AnimationEmotePrefix .. 'mywave',
        'mech_loco_m@character@dutch@fancy@unarmed@idle@_variations',
        'idle_a',
        nil,
        nil,
        3000,
        31
)

---

Resources & path references

• animation presets (often used in animDict and animName parameters)

• flags documentation (often used in flags parameter)

• Custom icons for JavaScript config (e.g. nss_emotes/html_nss_emotes/config.js) must be placed in nss_emotes/html_nss_emotes/icons/ and subfolders. Consider the correct path when adding the icon in the config. If an icon is in a subfolder, the path must include the subfolder, e.g. subfolder/icon.png.

---

addSimpleAnimation

This function works like a wrapper for TaskPlayAnim native function to easily add simple animations.

---@param command string The command to trigger the animation. Ensure this command is unique and not used by other resources.
---@param animDict string
---@param animName string
---@param speed number|nil
---@param speedX number|nil Speed multiplier for the animation.
---@param duration number|nil Duration in milliseconds. Use `nil` for infinite duration.
---@param flags number|nil
---@param animType number|nil For internal usage only, do not set this parameter.
addSimpleAnimation(
        command,
        animDict,
        animName,
        speed, -- Optional
        speedX, -- Optional
        duration, -- Optional
        flags, -- Optional
        animType -- Optional
)

-- Example with prefixed command using config (recommended).
-- This ensures that the command is properly namespaced (like the internal animations).
-- Ensure that `Config.AnimationEmotePrefix` is set in your config file.
-- This will add an animation that can be triggered by the command `act emote-gentletip` if the prefix is set to `emote-`.
addSimpleAnimation(
        Config.AnimationEmotePrefix .. 'gentletip',
        'mech_loco_m@character@dutch@fancy@unarmed@idle@_variations',
        'idle_b',
        nil,
        nil,
        2500,
        31
)

---

addSimpleEmoteAnimation

Works like the native TaskPlayEmoteWithHash.

---@param command NssEmotesConfigCommand
---@param emote_hash string|number
addSimpleEmoteAnimation(
        command,
        emote_hash
)

-- Example with prefixed command using config (recommended).
-- (This example still exists in the base resource as internal animation, but shows the usage of the function.)
addSimpleEmoteAnimation(
        Config.AnimationEmotePrefix .. 'stinky',
        -166523388
)

---

addActionEmote

Adds a simple animation of type action emote (emote class 1, see emote class types for more information).

---@param command NssEmotesConfigCommand
---@param emote_anim string
addActionEmote(
        command,
        emote_anim
)

-- Example with prefixed command using config (recommended).
-- (This example still exists in the base resource as internal animation, but shows the usage of the function.)
addActionEmote(
        Config.AnimationEmotePrefix .. 'shortcarefreedance',
        'KIT_EMOTE_DANCE_CAREFREE_B_1'
)

---

addTauntEmote

Adds a simple animation of type taunt emote (emote class 2, see emote class types for more information).

---@param command NssEmotesConfigCommand
---@param emote_anim string
addTauntEmote(
        command,
        emote_anim
)

-- Example with prefixed command using config (recommended).
-- (This example still exists in the base resource as internal animation, but shows the usage of the function.)
addTauntEmote(
        Config.AnimationEmotePrefix .. 'bestshot',
        'KIT_EMOTE_TAUNT_BEST_SHOT_1'
)

---

addGreetEmote

Adds a simple animation of type greet emote (emote class 3, see emote class types for more information).

---@param command NssEmotesConfigCommand
---@param emote_anim string
addGreetEmote(
        command,
        emote_anim
)

-- Example with prefixed command using config (recommended).
-- (This example still exists in the base resource as internal animation, but shows the usage of the function.)
addGreetEmote(
        Config.AnimationEmotePrefix .. 'greetflyingkiss',
        'KIT_EMOTE_GREET_FLYING_KISS_1'
)

---

addReactionEmote

Adds a simple animation of type reaction emote (emote class 0, see emote class types for more information).

---@param command NssEmotesConfigCommand
---@param emote_anim string
addReactionEmote(
        command,
        emote_anim
)

-- Example with prefixed command using config (recommended).
-- (This example still exists in the base resource as internal animation, but shows the usage of the function.)
addReactionEmote(
        Config.AnimationEmotePrefix .. 'amazed',
        'KIT_EMOTE_REACTION_AMAZED_1'
)

---

addScenarioInPlaceHash

Adds a scenario and uses the native TaskStartScenarioInPlaceHash to start it. With TaskStartScenarioInPlaceHash smoother transitions can be achieved compared to TaskStartScenarioInPlace.

The loop prefix is recommended for scenarios that are intended to be looped.

---@param command string
---@param scenario string
---@param scenario_conditional string|nil
---@param scenario_group string|nil
addScenarioInPlaceHash(
        command,
        scenario,
        scenario_conditional, -- Optional
        scenario_group -- Optional
)

-- Example with prefixed command using config (recommended).
-- (This example still exists in the base resource as internal animation, but shows the usage of the function.)
addScenarioInPlaceHash(
        Config.AnimationLoopPrefix .. 'notebook',
        'world_human_write_notebook'
)

---

addScenarioInPlace

Adds a scenario and uses the native TaskStartScenarioInPlace to start it.

The loop prefix is recommended for scenarios that are intended to be looped.

---@param command string
---@param scenario string
---@param scenario_group string|nil
addScenarioInPlace(
        command,
        scenario,
        scenario_group -- Optional
)

-- Example with prefixed command using config (recommended).
-- (This example still exists in the base resource as internal animation, but shows the usage of the function.)
addScenarioInPlace(
        Config.AnimationLoopPrefix .. 'leanatwallright',
        'WORLD_HUMAN_LEAN_WALL_RIGHT'
)

---

Complex animations with steps

addGenderedAnimation

Adds a gendered animation with different animation steps for male and female characters.

It is possible that some animations are only available for one gender. In that case, you can provide only the animation steps for the available gender.

The animation steps can be different types of animation steps. Animation steps are special functions that can be chained.

The loop prefix is recommended for scenarios that are intended to be looped.

---@param command NssEmotesConfigCommand
---@param male_animation_steps NssEmotesConfigAnimationStep[]|NssEmotesConfigAnimationStep
---@param female_animation_steps NssEmotesConfigAnimationStep[]|NssEmotesConfigAnimationStep
addGenderedAnimation(
        command,
        male_animation_steps, -- Optional
        female_animation_steps -- Optional
)

-- Example with prefixed command using config (recommended).
-- (This example still exists in the base resource as internal animation, but shows the usage of the function.)
addGenderedAnimation(
        Config.AnimationLoopPrefix .. 'broomworking',
        {
            createAnimScenarioInPlaceHashStep('WORLD_HUMAN_BROOM_WORKING', nil, 'WORLD_HUMAN_BROOM_WORKING_MALE_B', 'broom'),
        },
        {
            createAnimScenarioInPlaceHashStep('WORLD_HUMAN_BROOM_WORKING', nil, 'WORLD_HUMAN_BROOM_WORKING_FEMALE_B', 'broom'),
        }
)

-- Another example with multiple animation steps for each gender.
-- (This example still exists in the base resource as internal animation, but shows the usage of
addGenderedAnimation(
        Config.AnimationLoopPrefix .. 'fallasleep',
        {
            createAnimStep('amb_rest@world_human_sleep_ground@arm@player_temp@enter', 'enter_right', nil, nil, 18000),
            createAnimStep('amb_rest@world_human_sleep_ground@arm@male_b@idle_c', 'idle_g'),
        },
        {
            createAnimStep('amb_rest@prop_human_sleep_leanto_tent@front@female_a@stand_enter', 'enter_front_lf', nil, nil, 11000),
            createAnimStep('amb_rest@prop_human_sleep_leanto_tent@front@female_a@trans', 'a_trans_sleep_ground_arm_a', 8.0, -8.0, 18000),
            createAnimStep('amb_rest@world_human_sleep_ground@arm@female_a@idle_a', 'idle_c', 8.0),
        }
)

-- Another example with multiple animation steps of different types.
-- (This example still exists in the base resource as internal animation, but shows the usage of the function.)
addGenderedAnimation(
        Config.AnimationLoopPrefix .. 'badass',
        {
            createAnimStep("amb_rest@world_human_badass@male_a@idle_b", 'idle_f', nil, 1.0, 6000),
            createAnimScenarioInPlaceStep('WORLD_HUMAN_BADASS'),
        },
        {
            createAnimStep('amb_rest@world_human_badass@male_a@idle_b', 'idle_f', nil, 1.0, 5500),
            createAnimStep('amb_rest@world_human_badass@male_a@idle_a', 'idle_a', nil, 1.0),
        }
)

---

addMultipleAnimations

Like addGenderedAnimation but without gender distinction.

---

addPartnerAnimation

Adds a partner animation with different animation steps for two players.

---@param command NssEmotesConfigCommand
---@param partner_a_animations NssEmotesConfigBasicAnimation
---@param partner_b_animations NssEmotesConfigBasicAnimation
addPartnerAnimation(
        command,
        partner_a_animations,
        partner_b_animations
)

-- Example with prefixed command using config (recommended).
-- Creates a partner animation with two animation steps for each partner.
-- The first partner will perform the attacker animation steps, the second partner the victim animation steps.
-- You can use as many steps as you like for each partner.
-- (This example still exists in the base resource as internal animation, but shows the usage of
addPartnerAnimation(
        partner_prefix .. 'slap1',
        createDefaultAnimation(
                createAnimStep('mech_melee@unarmed@posse@ambient@healthy@noncombat', 'slap_front_sober_vs_drunk_heavy_v1_att', null, null, 2500, 0),
                createAnimStep('mech_melee@unarmed@posse@ambient@healthy@noncombat', 'slap_front_drunk_vs_drunk_light_v1_att', null, null, 2500, 0)
        ),
        createDefaultAnimation(
                createAnimStep('mech_melee@unarmed@posse@ambient@healthy@noncombat', 'slap_front_sober_vs_drunk_heavy_v1_vic', null, null, 2500, 0),
                createAnimStep('mech_melee@unarmed@posse@ambient@healthy@noncombat', 'slap_front_drunk_vs_drunk_light_v1_vic', null, null, 2500, 0)
        )
)

createSimplePartnerAnimation

Shortcut for addPartnerAnimation for simple partner animations with only one animation step.

Important:

• This function always uses Config.AnimationPartnerPrefix as prefix for the command.

• To use this function your lua file must have to be loaded after partner_animations.lua file. You can ensure this by naming your lua file with a prefix that comes alphabetically after p, e.g. z_my_partner_animations.lua.

--- Little helper function to create a default animation object.
---@param command string
---@param anim_dict_a string
---@param anim_a string
---@param anim_dict_b string
---@param anim_b string
---@param duration_in_ms number|nil
createSimplePartnerAnimation(
        command,
        anim_dict_a,
        anim_a,
        anim_dict_b,
        anim_b,
        duration_in_ms -- Optional, default is 2500ms
)

-- Example:
-- Keep in mind that the command will be automatically prefixed with `Config.AnimationPartnerPrefix`.
createSimplePartnerAnimation(
        'slap1',
        'mech_melee@unarmed@posse@ambient@healthy@noncombat',
        'slap_front_sober_vs_drunk_heavy_v1_att',
        'mech_melee@unarmed@posse@ambient@healthy@noncombat',
        'slap_front_sober_vs_drunk_heavy_v1_vic'
)

---

Step creation functions

Important: These functions are only usable in Complex animations with steps functions.

createAnimScenarioInPlaceHashStep

Creates an animation step like addScenarioInPlaceHash but without command and returns the step.

---@param scenario string
---@param duration number|nil
---@param scenario_conditional string|nil
---@param scenario_group string|nil
---@return NssEmotesConfigAnimationStep
createAnimScenarioInPlaceHashStep(
        scenario,
        duration, -- Optional
        scenario_conditional, -- Optional
        scenario_group -- Optional
)

-- Example:
createAnimScenarioInPlaceHashStep(
        'WORLD_HUMAN_BROOM_WORKING',
        nil,
        'WORLD_HUMAN_BROOM_WORKING_MALE_B',
        'broom'
)

---

createAnimScenarioInPlaceStep

Creates an animation step like addScenarioInPlace but without command and returns the step.

---@param scenario string
---@param duration number|nil
---@param scenario_group string|nil Scenarios of same group have no transitions between.
---@return NssEmotesConfigAnimationStep
createAnimScenarioInPlaceStep(
        scenario,
        duration, -- Optional
        scenario_group -- Optional
)

-- Example:
createAnimScenarioInPlaceStep(
        'WORLD_HUMAN_BADASS'
)

---

createAnimStep

Creates an animation step like addSimpleAnimation but without command and returns the step.

---@param animDict string
---@param animName string
---@param speed number|nil
---@param speedX number|nil Speed multiplier for the animation.
---@param duration number|nil Duration in milliseconds. Use `nil` for infinite duration.
---@param flags number|nil
---@param animType number|nil For internal usage only, do not set this parameter.
---@return NssEmotesConfigAnimationStep
createAnimStep(
        animDict,
        animName,
        speed, -- Optional
        speedX, -- Optional
        duration, -- Optional
        flags, -- Optional
        animType -- Optional
)

-- Example:
createAnimStep(
        'amb_misc@world_human_door_knock@male_a@idle_c',
        'idle_g'
)

---

createEmoteHashAnimStep

Creates an animation step like addSimpleEmoteAnimation but without command and returns the step.

---@param emote_hash string|number
---@param duration number|nil
---@return NssEmotesConfigAnimationStep
createEmoteHashAnimStep(
        emote_hash,
        duration -- Optional
)

-- Example:
createEmoteHashAnimStep(
        -166523388
)

---