tdBattlePetScript API (tdBPS)

In this post I will try my best to translate and describe all commands and arguments from the chinese API document on Curse. If I can add things that I learned from writing scripts lately I’ll try to share these things too. Before complaining about my translation in comments please consider that neither English nor Chinese are my mother tongue. If there are things that were already confusing when Google translated the original from Chinese to English and I have no experience from my own scripts, they will be displayed “Italic”.

An important note at start: If you plan to share scipts, please think about not using names at all (pets, abilitys, auras etc.), names won’t work for others if their client language is different from the authors’. The easiest way to get IDs for your script is to create & save the team in Rematch and then export it as string, Syntax is:


Sissix  (Team Name)
117934  (Sissix' NPC ID to check if it's targeted and then AutoLoad a team)
1975  (Pet ID of the pet in Slot 1)
1773  (ability ID for skill in Slot 1)
1758  (ability ID for skill in Slot 2)
518  (ability ID for skill in Slot 3)
...  similar for pets in Slot 2 and 3

0:0:0:0 in Rematch strings mean the level-pet slot




Using Pet Skills

tdBPS can not use skills that are not set for the 3 ability slots of a battle pet. When  a script is about to use a players’ pet skill, it will check if the active pet can act (not working while stunned etc.) and the ability is ready (off cooldown). Abilities can be identified by their name, ID or slot number.

Use Moonfire: ability(Moonfire) use(Moonfire)
Use pet ability 595 (Moonfire): ability(595) use(595)
Use ability in slot 3: ability(#3) use(#3)

Switching Pets

To swap pets the pet you want to switch to has to be alive (and “The current pet is not targeted to the pet”). Pets can be identified by their name, ID or slot number, but using similar pets can cause problems (IDs don’t include breeds) so slot numbers are prefered.

Switch to Chrominius: change(Chrominius)
Switch to pet 1152 (Chrominius): change(1152)
Switch to the second pet: change(#2)
Switch to the next pet: change(next)

Trap / Capture Pets

There’s also a command to capture the active pet of the enemy team. It does nothing, if you can not use your Trap skill, this occurs if:

  • pet has more than 35% of its maximum Hitpoints
  • pet is controlled by a pet tamer
  • pet is controlled by other player
  • pet is epic/legendary
  • you already have 3 of the pet (or 1 for unique pets)
  • capturing the pet would exceed the collected pets limit

Use Trap to capture active enemy pet: catch

Quit Pet Battle

Sometimes pet battles can be a bit random (or maybe you started with the wrong pets) and it doesn’t make sense to continue so you want to stop a fight.

Immedialtely stop a pet battle: quit

Passing Turns

If you can’t or wan’t perform an action in a specific round of a pet battle, you can Pass it (maybe your active pet is stunned but you don’t want to swap another pet).

Pass 1 round: standby

Display Text Messages

The addon can display text in your chat window, unfortunately it has only one (case sensitive!) command that can’t be combined with other actions so it’s nearly useless. If you want to use spacing in your message make sure you quote your text.

Send text message: test(ThisIsMyMessage)   test("This Is My Message")

if / endif

Lines of scripts between if and endif are executed only when the if condition is set up. if and endif always have to appear in pairs.





All conditions can be used for both teams, to look at the player’s team we use self and for the opponent team we use enemy together with other statements. Once again, pets can be identified by their name, ID or slot number.

Player’s / Enemy’s active pet:   self   /   enemy

Player’s / Enemy’s second pet:   self(#2)   /   enemy(#2)

Player’s / Enemy’s Chrominius: self(Chrominius)   /   enemy(Chrominius)

Player’s / Enemy’s Chrominius by ID: self(1152)   /   enemy(1152)


Conditional functions fall into three categories:

  1. Boolean

Syntax: [Operator]Owner(Pet).Function

Operator: !

  1. Compare Comparison (you always have to specify the operator AND the comparison value)

Syntax: Owner(Pet).Function Operator Value

Operators:    =   !=   >   >=   <   <=   ~   !~

  1. Equality

Syntax: Owner(Pet).Function Operator Value

Operators:   =   !=   ~   !~

Operator description:
=   equal to
!=  not equal to
>   higher than
>=  higher than or equal to
<   less than
<=  less than or equal to
~   included in
!~  not included in

~ The value of the self.type ~ 飞行,小动物 multiple values, use , separate, as long as a match to return true self.type ~ 飞行,小动物


dead (Boolean)

Determine whether the target is dead or not.

Player’s active pet dead / not dead:   self.dead   /   !self.dead

Enemy’s first pet dead / not dead:   enemy(#1).dead   /   !enemy(#1).dead

Player’s second pet dead / not dead:   self(#2).dead   /   !self(#2).dead

hp (Compare)

Compare Hitpoints of a pet with the comparison value.

Player’s active pet Hitpoints less than 100:   self.hp < 100

Enemy’s second pet Hitpoints higher than 400:   enemy(#2).hp > 400

hp.full (Boolean)

Determine whether the target has full Hitpoints or not.

Enemy’s second pet has full Hitpoints:   enemy(#2).hp.full

Enemy’s active pet already lost Hitpoints:   !enemy.hp.full


hpp (Compare)

Determine the percentage of Hitpoints

Enemy’s Chrominius Hitpoints are higher than 50%:   enemy(1152).hpp > 50


aura.exists (Boolean)

To determine whether the existence of an aura (buff, debuff by name or ID).

Player’s active triggered Undead passive:   self.aura(242).exists

Enemy’s active pet has Black Claw debuff:   enemy.aura(918).exists


aura.duration (Compare)

Determine the number of turns left for a buff / debuff.

Enemy’s active pet Black Claw debuff is active more than or exactly 1 round:   enemy.aura(918).duration >= 1

Player’s  first pet is Poisoned less than 3 rounds:   self(#1).aura(379).duration < 3


Weather (Boolean)

Judge the current weather

The current weather is the moonlight weather(月光) !weather(奥术之风)

Weather.duration (Compare)

Determine the number of remaining days of the current weather

Whether the current weather is weather(月光).duration < 3 and the number of rounds is less than 3: weather(月光).duration < 3

Active (Boolean)

Judge the current activation of the pet

Whether or not the current pet is Cromanis: self(克洛玛尼斯).active

Ability.usable (Boolean)

Whether the skills are available

The enemy ‘s current pet skill is enemy.ability(钻地).usable : enemy.ability(钻地).usable

Ability.duration (Compare)

Skill to cool the remaining number of turns

Your own Nether self(虚空精灵龙).ability(月火术).duration <= 1 Less than or equal to a round: self(虚空精灵龙).ability(月火术).duration <= 1

Ability.strong (Boolean)

Whether the skills hit


Ability.weak (Boolean)

Whether the skills tap


Ability.type (Equality)

Skill type

self.ability(#1) = 魔法 self.ability(#3) !~ 魔法,亡灵

Round (Boolean)

Determine the number of rounds

  1. The total number of rounds is not specified when the target is not specified
  2. Specify the target for the current pet to play the first few rounds

round = 1 self.round < 3 enemy.round = 1

Played (Boolean)

To determine whether the pet on the track

The first two pets must be on the past

self(#3).played !enemy(泰莉).played self(#3).played !enemy(泰莉).played

This condition is very effective for changing pet

For example: change(#3) [ !self(#3).played ]

Speed ​​(Compare)

Determine the speed of the pet

self.speed < 292 (Boolean)

Determine whether the target is faster

Speed.slow (Boolean)

Determine whether the target is slower


Level (Compare)

Determine the target level

self.level < 25

Level.max (Boolean)

Determine if the target is full


Power (Compare)

Determine the target attack

self.power > 100

Type (Equality)

Determine the pet type

self(#2).type = 飞行 enemy(#2) ~ 飞行,亡灵 self.type = 2

Quality (Compare)

Judge pet quality

self.quality = 4 self.quality > 弱小


1 = human type

2 = dragon class

3 = flight

4 = souls

5 = small animals

6 = magic

7 = element

8 = beast

9 = Aquatic habitat

10 = mechanical


1 = weak

2 = normal

3 = Excellent

4 = excellent

5 = epic

6 = legend

Submit a Comment

Your email address will not be published. Required fields are marked *