Skip to content

API

Jump to bottom
Bernd Lörwald edited this page Sep 22, 2025 · 1 revision

General definitions

locale independent identifiers

Entities like pets and abilities have different names depending on client language. When sharing scripts with other users, this is not a reliable way to identify them.

To avoid that, it is preferred to use unique numerical IDs instead. For example, instead of Bite, use 110. As that’s harder to read, there can be an optional text part separated by a colon: 110:Bite. The scripts addon first tries to match the numeric id, then the text if it didn’t work. Because of that, you can also just use any semantic text you want instead (as you shouldn’t rely on it matching anyway, client language is random). For example, you can use 110:filler or 227:stun.

pet identifier

Pets use locale independent identifiers. Additionally, they can be identified by their slot in the team:

  • by slot: #1, #2, #3
  • by locale independent identifier: the numeric identifier is using the species id (e.g. 39:Mechanical Squirrel, 121 (Gurky)).
  • (if you insist: by locale dependent name: Quietschklirr, Clique-Bielle, Creakclank)

ability identifier

Abilities use locale independent identifiers. Additionally, they can be identified by their slot in the active pet’s ability selection:

  • by slot: #1, #2, #3
  • by locale independent identifier: the numeric identifier is using the ability id (e.g. 190:Cyclone, 110 (Bite)).
  • (if you insist: by locale dependent name: Vague de magma, Magma Wave, Магматическая волна)

Actions

ability(…), use(…)

Uses a pet ability.

The ability must be available, i.e. on the ability bar and not on cooldown or locked out by a silence.

  • Arguments: ability identifier

Examples

  • Use whatever ability is chosen in the active pet’s slot 1
use(#1)
  • Use bite, if the active pet has that ability.
use(110:filler)
  • If the enemy does not already have the cyclone debuff, apply it (assuming it is not on cooldown).
ability(190:cyclone) [ !enemy.aura(189:cyclone debuff).exists ]

change(…)

Change your currently active pet.

Does nothing if the selected pet is dead, or already your current pet.

  • Arguments:
    • next
    • pet identifier

Examples

  • Cycle to whatever is the next alive pet (1 -> 2, 2 -> 3, 3 -> 1)
change(next)
  • Switch to your next alive Mechanical Squirrel
change(39:squirrel)
  • If your pet in slot 3 is dead, activate slot 2
change(#2) [ self(#3).dead ]

quit

Forfeit the current battle.

  • Arguments: none

Examples

  • If your pet in slot 2 is dead, forfeit.
quit [ self(#2).dead ]
  • Give up, if the enemy team’s last pet is still alive but your first slot pet is below 10% hp
quit [ enemy(#3).alive & self(#1).hpp < 10 ]

standby

Pass in the current round, if you can.

  • Arguments: none

Examples

  • Do nothing, if decoy is currently up
standby [ self.aura(334:decoy).exists ]

catch

Try catching the enemy pet, if you can.

  • Arguments: none

Examples

  • Try catching the enemy pet (if it is low enough)
catch

test(…)

Prints the arguments to the main chat box (locally, verbatim) and does nothing.

There is a setting to stop script execution when a test() action is executed which might be useful for debugging. Note that because of this being an option, it is generally advised to not include test() in shared scripts unless it is the very last action anyway. Otherwise, execution is inconsistent!

  • Arguments: anything

Examples

  • Prints ‘Manually finish battle’
test(Manually finish battle)
  • If enemy’s health% is below 50%, prints ‘below 50’
test(below 50) [ enemy.hpp < 50 ]

Targets

self / ally

One of your current pets.

  • Selectors: Name, ID, Position (defaults to current pet if not given)
  • Examples: self, ally(Chrominius), self(1152), ally(#2)

enemy

One of the enemy pets.

  • Selectors: Name, ID, Position (defaults to current pet if not given)
  • Examples: enemy, enemy(Chrominius), enemy(1152), enemy(#2)

Abilities

ability.usable

If an ability is usable (ie not on cooldown).

  • Return: bool
  • Examples: self.ability(Moonfire).usable

ability.duration

The remaining cooldown for an ability.

  • Return: value
  • Examples: self.ability(Moonfire).duration

ability.strong

If the ability is strong against the current enemy pet.

  • Return: bool
  • Examples: self.ability(Moonfire).strong

ability.weak

If the ability is weak against the current enemy pet.

  • Return: bool
  • Examples: self.ability(Moonfire).weak

ability.type

The type of an ability.

  • Return: value
  • Examples: self.ability(Moonfire).type

Auras

aura.exists

If an aura is currently active.

  • Return: bool
  • Examples: self.aura(Dodge).exists

aura.duration

The remaining rounds of an active aura.

  • Return: value
  • Examples: self.aura(Dodge).duration

Pets

hp

A pets current HP.

  • Return: value
  • Examples: self.hp

hpp

A pets current HP (for use in comparisons).

  • Return: value
  • Examples: self.hpp

hp.full

If a pet has full hp.

  • Return: bool
  • Examples: self.hp.full

hp.can_be_exploded (or hp.can_explode)

If the damage from the opponent pet self-destructing would kill the given pet.

  • Return: bool
  • Examples: enemy.hp.can_be_exploded (will the enemy pet die if the self pet explodes?) or self.hp.can_be_exploded (will the self pet die if the enemy pet explodes?)

**Note**: You will likely always want to use use(explosion) [ enemy.hp.can_be_exploded ]. Old scripts will be using enemy.hp.can_explode which is equivalent, but should be avoided due to being harder to understand.

hp.high

If the pets hp is higher than the opponents.

  • Return: bool
  • Examples: self.hp.high

hp.low

If the pets hp is lower than the opponents.

  • Return: bool
  • Examples: self.hp.high

hp.diff

The current pet’s HP minus the current other pet HP.

  • Return: value
  • Examples: self.hp.diff > 300 (self has 300 more hp than enemy, e.g. self at 450 and enemy at 149 hp), enemy.hp.diff > 300 (enemy has 300 more hp than own, e.g. enemy at 450 hp and self at 149 hp)

hpp.diff

The current pet’s HP percentage minus the current other pet HP percentage.

  • Return: value
  • Examples: self.hpp.diff > 30 (self hp percentage is 30 points more hp percentage than enemy, e.g. self at 10% and enemy at 41%), enemy.hpp.diff > 30 (enemy hp percentage is 30 points more hp percentage than self e.g. enemy at 10% and self at 41%)

id

The pets id.

  • Return: value
  • Examples: self.id

level

The pets level.

  • Return: value
  • Examples: self.level

level.max

If the pet is at max level (25).

  • Return: value
  • Examples: self.level.max

power

The pets power.

  • Return: value
  • Examples: self.power

quality

The pets quality.

  • Return: value
  • Examples: self.quality

type

The pets family.

  • Return: value
  • Examples: self.type

speed

The pets speed.

  • Return: value
  • Examples: self.speed

speed.fast

If the pets speed is higher than the opponents.

  • Return: bool
  • Examples: self.speed.fast

speed.slow

If the pets speed is lower than the opponents.

  • Return: bool
  • Examples: self.speed.slow

collected

If the pet is in your collection.

  • Return: bool
  • Examples: enemy.collected, enemy(#2).collected, enemy(Chrominius).collected

collected.count

The number of pets in your collection

  • Return: value
  • Examples: enemy.collected.count, enemy(#2).collected.count, enemy(Chrominius).collected.count < 3

collected.max

The maximum number of pets you could have in your collection. Currently returns 1 if the pet is a companion, or 3 if the pet is wild.

  • Return: value
  • Examples: self.collected.max, enemy(#2).collected.max = 3

Status

active

If the pet is currently active.

  • Return: bool
  • Examples: self.active

dead

If the pet is currently dead.

  • Return: bool
  • Examples: self.dead

exists

If the pet exists in the battle.

  • Return: bool
  • Examples: self.exists

is

If the pet matches a selector.

  • Return: bool
  • Selectors: Name, ID, Position
  • Examples: self.is(Chrominius), self.is(1152), self.is(#2)

played

If the pet has been played.

  • Return: bool
  • Examples: self.played

trap

If the trap is usable (or potentially usable if enemy hp is low enough).

  • Return: bool
  • Examples: catch [trap & enemy.hpp < 35]

Battle

weather.exists (or weather)

If a weather effect is currently active.

  • Selectors: Name, ID
  • Return: bool
  • Examples: weather(Moonlight:596).exists or weather(Moonlight:596)

weather.duration

The number of turns remaining for a weather effect.

  • Return: value
  • Examples: weather(Moonlight).duration

round

The current round.

  • Return: value
  • Examples: round

Operations

!

Negation.

  • Type: Unary
  • Examples: !enemy.hp.full

=

Equality.

  • Type: Binary
  • Examples: self.level = 15

!=

Inequality.

  • Type: Binary
  • Examples: self.level != 15

>

Greater than.

  • Type: Binary
  • Examples: self.level > 15

>=

Greater than or equal to.

  • Type: Binary
  • Examples: self.level >= 15

<

Less than.

  • Type: Binary
  • Examples: self.level < 15

<=

Less than or equal to.

  • Type: Binary
  • Examples: self.level <= 15

~

Contains.

  • Type: Binary
  • Examples: weather ~ Mudslide, Scorched Earth, Blizzard

!~

Does not contain.

  • Type: Binary
  • Examples: weather !~ Mudslide, Scorched Earth, Blizzard

&

Logical AND.

  • Type: Binary
  • Examples: weather = Mudslide & self.level = 15

Language

--

Script comment.

  • Examples: -- Hello World!

Families

  • 1 - Humanoid
  • 2 - Dragonkin
  • 3 - Flying
  • 4 - Undead
  • 5 - Critter
  • 6 - Magic
  • 7 - Elemental
  • 8 - Beast
  • 9 - Aquatic
  • 10 - Mechanical

Quality

  • 1 - Poor
  • 2 - Common
  • 3 - Uncommon
  • 4 - Rare

Clone this wiki locally