Writing Pet Battle Scripts

1. Requirements

For this guide, it is necessary to install the addon Pet Battle Scripts.
It is assumed that installation and setup are already done, and teams are set or easy to set by you.

2. How it works

Basically the addon selects the required ability following instructions written in the script. E.g.:

use(Nature's Ward:574) [!self.aura(Nature's Ward:820).exists]
use(Alpha Strike:504)
This set of lines result in the following actions:
round 1: it casts Dodge
round 2: it tries to cast Dodge, but since it is on CD, it goes to the next line and casts Nature's Ward
round 3: it tries to cast Dodge, but since it is on CD, it tries the next line. Since aura Nature's Ward is active, it goes to the next line and casts Alpha Strike, and so on.

To summarize: each line is read sequentially until it finds a command that can be executed. The challenge here is writing scripts able to cast the spells according to the desired strategy.

3. Script creation

3.1 The editor

The easiest way to write a script is when you are doing a pet battle with a team previously saved on Rematch.
After starting the fight, open Rematch, right click over the corresponding team and select 'Write script'.
It will open a new window, the 'Script editor'. During the battle, and while the script editor is active it is possible to write a script using the auto-complete feature.

With the script editor opened and during a fight, start typing the desired action and it will soon show an dropdown list.

After selecting an action (type Enter or click over the action) a new list with the abilities available to the active pet will be shown.

Again, select the desired ability and if needed add the conditions when this action will be executed. Start by typing a bracket '[' followed by the first letter of the condition. Options are a target (self, enemy) or weather.

Anyway, a new list will be shown, it there is any.

In case there are additional required parameters, as with auras, a new list will be shown. As before, select the appropriate option.

Once you are familiar with the commands, you might just type the command followed by a dot to activate the dropdownlist with the available options. Remember to close the condition with a bracket: ']'.

Writing and editing a script is not difficult itself since the addon makes it very easy with the dropdown lists. Good luck!

3.2 Actions

ability/use: casts an ability
change: changes active pets
catch: catches a pet, if possible
standby: pass a round
quit: quits the fight

3.3 Conditions

Conditions are written between brackets ([condition]):
if & endif

3.4 Target

self: checks a condition on your own pets
enemy: checks for a condition on your enemy's pet

3.5 Functions

dead (boolean)
exists (boolean)
hp (compare)
hp.can_explode (boolean)
hp.full (boolean)
hp.high (boolean)
hp.low (boolean)
hpp (compare)
aura.exists (boolean)
aura.duration (compare)
weather (boolean)
weather.duration (compare)
active (boolean)
ability.usable (boolean)
ability.duration (compare)
ability.strong (boolean)
ability.weak (boolean)
ability.type (equality)
round (boolean)
played (boolean)
speed (compare)
speed.fast (boolean)
speed.slow (boolean)
level (compare)
level.max (boolean)
power (compare)
type (equality)
quality (compare)
id (equality)
is (boolean)

4. Pratical examples

Although the script helps a lot with its auto-complete feature, it won't be enough to write good scripts. It is a good idea to choose a fight and play with the script editor until you feel more confident with the commands and becomes able to write more complex scripts. Below there will be some examples taken from pet battlers using specific strategies. It is assumed that the team is loaded, the abilities are the ones mentioned on the strategy guide, and that the recommended pet is being used, not an equivalent.

4.1 Wailing Critters

The Wailing Critters dungeon offers a nice opportunity to start improving your skills. Until you win the last fight the dungeon is repeatable and you might leave the dungeon, heal, and restart. There is also some random pets in the back row, but only a few families and abilities. The first 3 fights require only one pet with a fixed set of abilities, turning it into a nice place to practice your skills. The script might work for most of the fight where the same pet+abilities are being used, making it a very useful script. The link for the strategy is here.
The strategy:
Prio 1: Keep Emerald Presence active
Prio 2: Use Emerald Dream when you drop below ~1000 health
Prio 3: Emerald Bite

use(Emerald Presence:597)
use(Emerald Dream:598)
use(Emerald Bite:525)
As it is written, the script will cast Emerald Presence every time it is available. This ability does not have a CD, so we have to add a condition that prevents it from casting if the aura is already present.
The only conditions available are the 'aura(Emerald Presence).exists' or 'aura(Emerald Presence).duration'. The condition that seems to fit the strategy better is the first one.
After writing it, we would have use(Emerald Presence:597) [self(#1Emerald Proto-Whelp).aura(Emerald Presence).exists], which could be read as "cast Emerald Presence if my Emerald Proto-Whelp has Emerald Presence active".
We want the opposite of that, so deny the condition by using a '!' before the target: use(Emerald Presence:597) [!self(#1Emerald Proto-Whelp).aura(Emerald Presence).exists], translating into "cast Emerald Presence if my Emerald Proto-Whelp does NOT have Emerald Presence active". Yay!

use(Emerald Presence:597) [!self(Emerald Proto-Whelp).aura(Emerald Presence).exists]
Next step: as of now, the script will cast Emerald Dream on CD, which might not be required, specially at the beginning of the fight. Let's add the condition that will cast the ability once your whelp is low on health.

use(Emerald Dream:598) [self(Emerald Proto-Whelp).hp<1000]
You might choose to heal your whelp if it is below an amount expressed in percents, and not a fixed amount:

use(Emerald Dream:598) [self(Emerald Proto-Whelp).hpp<50]
This last condition will cast Emerald Dream if your Whelp is below 50% health.
The final script:

use(Emerald Presence:597) [!self(Emerald Proto-Whelp).aura(Emerald Presence).exists]
use(Emerald Dream:598) [self(Emerald Proto-Whelp).hp<1000]
use(Emerald Bite:525)
If your proto-whelp dies you may change it to another equivalent pet with the same abilities, and the script will keep working. To change pets add the following line: change(#2) [self(#1).dead] (change to pet number 2 if my pet number 1 is dead)

Now, some remarks about the way the script is written.
  • If your team has two Emerald Proto-Whelp, the script might not work as expected if you change pets. To avoid problems, instead of naming it, give it the team position, or just use the 'self' target. This will also allow you to use a different pet with the same skills, like the Dream Whelpling or the Emerald Whelpling
  • Do not use a slot number for abilities. It might cause problems if you use an alternative pet whose abilites are on different slot positions, like the Zandalari pets where the abilites Hunting Party and Black Claw sometimes are on a different tier.
  • Use either the ability's code number or both name and code. Some players might use a localized version of the game, and for them the script will not work if you use only the name of the abilities
  • You might leave only the abilities code number, which will result in a shorter script, but it is not necessary

A suggestion for all scripts (change to the appropriate team slot):

change(#2) [self(#1).dead]
use(Emerald Presence:597) [!self.aura(Emerald Presence:823).exists]
use(Emerald Dream:598) [self.hp<1000]
use(Emerald Bite:525)

4.2 Small fragments

Scripts are written for a specific strategy, but there are many common actions that can be use in many scripts. Adjust them to your needs, checking for the right conditions, and apply them when suitable.
  • Pass on first round:
standby [round=1]
  • Change pet to leveling and back (change slot numbers where appropriate):

change(#2) [self(#1).dead & !self(#2).played]
change(#3) [self(#2).active]
  • Use a dodge ability to block an enemy's ability (in this case, Burrow)

use(Deflection:490) [enemy.aura(Underground:340).exists]
  • Change the use of abilities depending on active enemy pet

If the enemy's pets are the first or second, you pet will cast Breath. Once the third pet enters the fight, your pet will cast Bombing Run on CD and Decoy if your enemy uses Burrow

if [enemy(#3).active]
use(Decoy) [enemy.aura(Underground:340).exists]
use(Bombing Run)

5. Resources


wrote on 2023-05-01 14:56:17

Must admit that I haven't quite grasped the art of script-writing yet, but nonetheless, I'm having a bash :-)

I'm trying to write a script for my 'Silence' team which is 'Eye of Corruption' in #1 spot, 'Iron Starlette' in #2 spot, and level 1 carry pet in #3 spot. It works well up until the point where I want Iron Starlette to change from Wind-up to Powerball - it just keeps on repeating Wind-Up. Could anyone please give me an idea of what's missing?

Here's the script:
use(Life Exchange:277)
use(Nether Blast:608)
change(Iron Starlette:1387)

Thanks in advance :-)

After repeatedly 'having a bash' and editing the script myself, I finally got it to work as I wanted ☺ Here's the working version:

# Pet Battle Scripts
# Version: 2
# Name: Silence
# Data: XjFeVF5TcGx1Z2luXlNSZW1hdGNoXlNrZXleTjE1NDkxMl5TZXh0cmFeU1NpbGVuY2U6NE45MDoyMjI4Mk9LOjExMjcxQkI6Wkw6XnReXg==
# Code Start
use(Life Exchange:277)
use(Nether Blast:608)
use(Wind-Up:459) [round=4]
use(Wind-Up:459) [round=5]

use(Powerball:566) [round=6]
use(Explode:282) [round=7]
# Code End

Loeve wrote on 2018-11-22 13:53:57

What is the difference between "Rematch string" and TD String" ?I see both when I look at your pet battle strategies


wrote on 2018-11-22 21:02:36

Rematch strings are copy/pasteable macros that you can import and export into and out of the addon Rematch. These strings import teams of pets to the given position in the in-game graphic for the selected opponent and also includes the abilities that have been chosen.

TDScripts work on the same principle but with a much easier to understand code. Scripts are for the actual battles themselves. They are the code the game uses to apply the moves you select.

I find it easiest to think of it as the 'TD' standing for 'Top Down', meaning the code written will read from the top line to the bottom, and as each conditional is met - i.e.; your pet does something (or doesn't, if the command was 'standby') - the script restarts at the top.

Rematch is an addon that allows for easier customisation of pets for specific battles than the standard UI;
tdBattlePetScript is a plug-in for Rematch that allows specific moves to be used in a programmed format to complete battles at the repeated press of a single button (that makes it sound boring; it isn't... It's awesome...).


wrote on 2023-01-24 21:26:32

I've spent some years wondering what was the "TD" meaning. Thanks! @Aranesh should add this ifo to this page.

Matt705 wrote on 2022-08-25 00:22:54

I'm trying to use the TDScript Editor for the first time and when I start typing an ability to use it doesn't come up with a selection for that pet. According to the instructions above, I should just be able to start typing the desired action, e.g. Use, and then a dropdown list should appear but it's not. So I now have to manually search each ability to find its ID.

Anybody else getting this? Thanks in advance.


wrote on 2022-10-02 07:37:39

I was having this issue too, until I checked again. You have to be in a fight in order for the Editor to prepopulate any details. I'm still trying to learn about how to create scripts also, and this was the first hurdle for me. (edited)


wrote on 2018-04-28 04:04:38

Will using a TD Script put your account at risk of being banned for botting?


wrote on 2018-08-02 13:34:40

No, all actions are being performed by an ingame addon using the available API. If Blizzard does not desire this behavior they will take steps (as they have proven many times during Legion to break this functionality.


wrote on 2022-08-13 12:38:10

What steps did Blizz take during Legion to break this functionality?
(I ask because I started playing WoW with Legion, so I wasn't aware of these things at the time).


wrote on 2021-11-01 21:56:04

I guess Skill's number ID is not a essential part of script.
I couldn't find ID anyway.

PhoenixFire wrote on 2022-01-01 20:54:33

If you publish a script and someone uses a different language like russian, or spanish, then the script fails if it doesn't have the Skill's number ID. In that way it is essential if you ever publish your script on xufu or anywhere else for public use.


wrote on 2021-07-05 00:44:03

nice write up.


wrote on 2020-12-29 09:06:14

Thanks for this excellent intro to scripting. This, and the link to the API, was the incentive that – finally – made me write my own scripts!


wrote on 2020-12-26 07:41:46

After using tdScript to level 300+ pets suddenly the Auto option doesn't light up for me any more. The only thing I can think of that might have broke it is that I pasted a script into wow without making the script window active first so it changed some options including turning nameplates off. Has anyone had this happen to them and do you know what dependencies to check to ensure it can enable again? I'm at a loss ...


wrote on 2020-12-26 10:26:56

I fixed my problem - there was some kind of data corruption in the Rematch.lua saved variables file. In that file there are two variables (dictionaries) RematchSaved and RematchSettings. I made a backup of the file then deleted it, the logged in, imported one team, logged out. Then I edited the newly created file to have the RematchSaved variable from my backup. Then within RematchSettings there is a dictionary entry called "TeamGroups" - I copied over that also from my backup. Finally I logged back in and found that the auto button is fully working again!


wrote on 2020-09-16 02:27:41

Could someone help me with a code?
use(Life Exchange:277)
use(Amplify Magic:488)
use(Amplify Magic:488)
use(Life Exchange:277)
change(Brilliant Spore:1540)
change(Jade Owl:845)
use(Hawk Eye:521)

this is for Pearlhusk Krawler
Pearlhusk Crawler (NPC#154914)

1: Mini Mindslayer (1,1,2)
2: Brilliant Spore (1,1,2)
3: Jade Owl (1,2,1)

So at the eyeblast step before changing to spore, sometimes mindlayer dies and sometimes lives, regardless, if you switch to the next pet, and use the abilities stated, it's still a win. However, when i run the code, it doesn't work. If mindslayer lives, I still want to switch to the spore and continue with explode. What happens is that it either doesn't change pets, or the spore is not using the ability assigned, and I don't know how to fix it. Maybe this can't be a code because of the rng? Thanks for the help.

Rubberfruit wrote on 2020-11-26 17:06:02

standby [round ~ 4, 5]
use(Life Exchange:277) [round ~ 1, 7]
use(Amplify Magic:488)
change(Brilliant Spore:1540)
change(Jade Owl:845)
use(Hawk Eye:521) [!self.aura(Hawk Eye:520).exists]

Rubberfruit wrote on 2020-11-26 16:45:55

How do you write the condition, My pet health is below the enemy pet health.
ability(id) [self.hp <= enemy.hp] does not work (edited)


wrote on 2020-11-12 00:25:33

Hey all! I've been sleeping on the site but now I'm ready to post and try to write a script.. be kind

So I'm hunting Rare's in Ice crown and I'm seeing a lot of cockroaches teams.

So what I wanna do is
have my leveling pet in slot 1 and Dart level 25 beast is slot 2
use skill 1 or pass then switch to dart and use skill 1 and when enemy pet has less then 450 HP use skill 2 devour and then back to skill 1 and so on and so on


wrote on 2020-10-28 07:49:49

Is there a way to find out how much damage a certain ability will do? I'm specifically interested in the minimum amount of damage an ability will do. (edited)

Darkironman wrote on 2020-10-17 19:29:33

Is anybody else having issues with writing scripts? I can not open the editor.


wrote on 2020-10-18 13:14:24

I am. At first when I clicked "Write Script" nothing would happen and now the option is gone.


wrote on 2020-07-31 19:01:04

Can the numerical list of pet families be added here? I'm have trouble finding the numerical indicator for critters/mech/dragonkin, etc.


wrote on 2020-07-31 21:16:23

Should be the order they come up in on the Rematch bar.

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


wrote on 2020-08-01 06:57:01

it's the order in which the families are listed in rematch


wrote on 2020-08-01 19:19:49

Thx y'all. Just what I was looking for.


wrote on 2020-07-15 13:07:57

Script to help farm rare pets

quit [enemy(#1).quality!=4 & enemy(#2).quality!=4 & enemy(#3).quality!=4]
quit [enemy(#1).quality!=4 & enemy(#2).quality!=4 & !enemy(#3).exists]
quit [enemy(#1).quality!=4 & !enemy(#2).exists & !enemy(#3).exists]
test(Rare pet found!)

Will quit on press if no rare found, if found, need to quit manually and battle with team of your choice.

Enjoy hunting (edited)


wrote on 2020-03-12 10:17:18

How do I find aura spell IDs?
For example, I need the aura ID for "Pumped Up" that striders get after using the ability "Pump" (ID:297).
I'm wanting my moths to use their Cocoon Strike (ID: 506) if "Pumped Up" is found to be an active aura on the enemy team. But Rematch doesn't put abilities IDs in auras/buffs.

Would be great if the TD Script addon could record your moves and create a script for you, somehow. :( lol

Edit/Update: I remembered that wowhead has spell IDs in its URL for spells/auras/etc.
For example, Pumped Up is ID 296, as seen in this URL:

I'd still appreciate if anyone else knows of ways to get IDs of things Rematch doesn't give. (edited)


wrote on 2020-03-12 11:03:08

usually (!) the ID of an aura comes right before the spell that applies it, like in your pump example.
the easiest way to see the ID is by just using in ingame within a script, since td will give you the auto-fill option that also adds the aura's ID by itself


wrote on 2020-03-14 10:04:42

Yeah, I've begun to notice that trend with the IDs. Thank you! :)

New Comment: