Skip to main content

Elite Script Cooldowns

Cooldowns control when an event may launch the same script again and when other participating powers may start. Scripts that bypass cooldowns and Lua callbacks without a cooldown check are unaffected.

Configuration Location​

Cooldowns are configured within the Cooldowns section of an elite script:

eliteScript:
  ScriptName:
    Events:
    - [event configuration]
    Actions:
    - [action configuration]
    Cooldowns:
      local: [value or range]
      global: [value or range]

The section must be named Cooldowns with that exact capitalization. Inside it, keys are case-insensitive (local, Local, LOCAL all work). Use integer tick counts or integer ranges, not decimal values. A decimal, a reversed range such as 80~40, or text that is not a number makes EliteMobs skip the whole script and log Skipped script <name> in <file>.

Note on Units: All cooldown values are specified in ticks. In Minecraft, there are 20 ticks per second, so:

  • 20 ticks = 1 second
  • 60 ticks = 3 seconds
  • 100 ticks = 5 seconds
  • 99999 ticks ≈ 83 minutes

Default Values​

If the Cooldowns section is omitted, both local and global default to 0, meaning the script bypasses the cooldown system entirely.

Cooldown Bypass​

A script is gated by the cooldown system when local or global is greater than 0. A gated script does not run while its own local cooldown is active or while the boss is in a global cooldown. If both values are missing, zero or negative, the script bypasses the cooldown gate; its event, conditions and power-suppression checks still apply. Use non-negative values in your configuration.

Either value arms the gate

Setting only local: 200 rate-limits the script to once every 200 ticks. It also makes the script wait while any other power holds the boss's global cooldown.

Setting only global: 20 holds back other participating powers for 20 ticks after the script runs. The script waits for that same global cooldown, so it cannot run again for 20 ticks either.

This bypass is deliberate -- it allows event-triggered behaviors that should always execute regardless of the boss's cooldown state.

Example:

eliteScript:
  AlwaysTeleportOnCombatEnter:
    Events:
    - EliteMobEnterCombatEvent
    Actions:
    - action: TELEPORT
      Target:
        targetType: SELF
      FinalTarget:
        targetType: SELF_SPAWN
    # No Cooldowns section - script always executes when event fires

Cooldowns have two values:

local​

local sets the time, in ticks, before the same script can happen again. Example:

Example

local: 60

Allows the power to run again after 3 seconds, provided the boss is not in a global cooldown and its other checks pass.

global​

global sets the time, in ticks, before any other script or power can happen again[1]. Example:

Example

global: 20

Blocks other participating powers from starting for 1 second.

[1] global sets a boss-wide cooldown flag. Other powers respect that flag only when their own cooldown checks participate. EliteMobs' powers are written as EliteScripts or Lua powers; a Lua power joins the same window by calling context.cooldowns:set_global(ticks) and checking context.cooldowns:global_ready() before starting. A frequently triggered script can keep slower participating powers waiting.

A local cooldown longer than the global cooldown gives other eligible powers time to run. It does not guarantee alternation: each power still needs its own event, conditions, and cooldown checks to pass.

Additionally, if your power has a specific duration during which it is active, you should use this system to prevent other powers from running simultaneously and potentially ruining your power.

Cooldowns start when the script dispatches its actions, not after their wait, repeats or duration finish. Failed script-level conditions do not start a cooldown, but individual actions that fail their own conditions can still leave the script's cooldown applied.

Each cooldown stores the tick on which it ends. Applying a cooldown again keeps whichever end tick is later, so a shorter global cooldown from another power never cuts a longer one short. Local cooldowns behave the same way when another script invokes the same script directly.

Randomization​

Both local and global cooldowns support randomization using range syntax. This allows cooldown durations to vary, adding unpredictability to boss behavior.

Example:

Cooldowns:
  local: 40~80
  global: 10~30

Sets the local cooldown to randomly be between 40 and 80 ticks (2-4 seconds) and the global cooldown to randomly be between 10 and 30 ticks (0.5-1.5 seconds).

The current implementation selects each range value when the script runtime is constructed and stores it on that power instance. It does not reroll the range every time the cooldown is applied.

Run Scripts Once with Cooldowns​

To ensure scripts trigger only once while still using an Event that may occur multiple times during a fight, set the local cooldown to a high number, such as 99999. This example demonstrates the concept:

Example
eliteScript:
  SetMeOnFireOnlyOnce:
    Events:
    - EliteMobDamagedByPlayerEvent
    Actions:
    - action: SET_ON_FIRE
      duration: 60
      Target:
        targetType: DIRECT_TARGET
    Cooldowns:
      local: 99999

In this scenario, the EliteMobDamagedByPlayerEvent triggers the SET_ON_FIRE action. Without cooldowns, the action would activate every time the player hits the mob.

With a local cooldown set to 99999, the action can trigger at most once every 99999 ticks, about 83 minutes. This usually prevents a second execution during one fight, but it is not a once-per-encounter flag: leaving and re-entering combat does not reset this timer on the same power instance.

local alone arms the gate, so this script does not need a global value. Leaving global out also means it never holds back the boss's other powers.

Troubleshooting​

Invalid Cooldown Keys

If you use an unrecognized key in the Cooldowns section, a warning will appear in the server logs:

Failed to parse cooldown entry for script name [ScriptName] in config file [FileName]

Valid keys are: local, global (case-insensitive)

Cooldown gating above applies to ordinary event dispatch. Scripts invoked by RUN_SCRIPT or a landing callback check their conditions but do not perform this same cooldown gate before running. They still apply their configured cooldowns afterward.