Script Filters
Scripts are custom pet filters created from Lua code. Creating them requires knowledge of the language which is beyond the scope of this guide.
When a script is active, the filtering system sets up a restricted environment to run the script for each pet. In this environment many variables are defined for each pet and some important API are exposed. The purpose of the script is to return true if the pet should be listed.
When the filtering system has finished compiling a list of pets, the restricted environment is destroyed and all variables and tables created in that environment are destroyed as well.
If the first line of a script is a --comment, the comment will be used as a tooltip for the script in the filter menu.
Pet Variables
As a script runs for each pet, these variables are defined:
Pet Variables
| Variable |
Type |
Description |
| owned |
boolean |
Whether the pet is owned by the player. |
| petID |
string |
Unique ID of an owned pet, such as "BattlePet-0-000004A98F18". |
| speciesID |
number |
Numeric ID of the pet's family. Black Tabby Cats are species 42. |
| customName |
string |
Name given to the pet by the player, or nil if the pet has not been renamed. |
| level |
number |
Level of the pet, or nil for uncollected pets. |
| xp |
number |
Amount of xp the pet has in its current level. |
| maxXp |
number |
Total amount of xp required to reach the pet's next level. |
| displayID |
number |
A numeric representation of a pet's model skin. |
| isFavorite |
boolean |
Whether the pet is favorited by the player. |
| name |
string |
The original name of the pet species. |
| icon |
number |
The numerical fileID of the pet's icon. |
| petType |
number |
Value between 1 and 10 for its type. 1=Humanoid, 2=Dragonkin, etc. |
| creatureID |
number |
The npcID of the pet when it's summoned. |
| sourceText |
string |
Formatted text describing where the species is from. |
| description |
string |
Formatted lore text of the species. |
| isWild |
boolean |
Whether the pet is a capturable wild pet. |
| canBattle |
boolean |
Whether the pet can battle. |
| tradable |
boolean |
Whether the pet can be caged. |
| unique |
boolean |
Whether no more than one of the pet can be known at a time. |
| abilityList |
table |
Ordered table of the abilityIDs used by the species. |
| levelList |
table |
Ordered table of the levels the abilityIDs are learned. |
Exposed API
The scripting environment is restricted to only common Lua and the following:
Exposed API
| API |
Type |
Description |
| C_PetJournal |
table |
Blizzard's API for the pet journal and all of its methods. |
| C_PetBattles |
table |
Blizzard's API for the battle UI and all of its methods. |
| GetBreed |
function |
Returns the numeric breed (3-12) of a given petID. |
| GetSource |
function |
Returns the numeric source (1-10) of a given speciesID. |
| IsPetLeveling |
function |
Returns whether the given petID is in the leveling queue. |
| AllSpeciesIDs |
iterator |
Returns the next speciesID of all existing unique pets. |
| AllPetIDs |
iterator |
Returns the next petID of all owned pets. |
| AllPets |
iterator |
Returns either the petID or speciesID of the next pet in the journal. |
| AllAbilities |
iterator |
Returns the next abilityID and level of the ability for a given speciesID. |
Iterator Functions
The iterator functions listed above are intended to compare the current pet against others.
For performance reasons, cache the information you're looking for on the first pass of your script. Remember your script can potentially run a thousand times or more in one filter pass!
Here's an example:
if not MyLevel1s then
MyLevel1s = {}
for petID in AllPetIDs() do
local _,_,level = C_PetJournal.GetPetInfoByPetID(petID)
if level==1 then
MyLevel1s[petID] = true
end
end
end
-- start normal portion of script
When the filter pass is done, all created tables and variables are destroyed. So the next time this script runs it will update with new information for the new filter pass.
