PetEmote Custom Emotes Tutorial

Welcome to the PetEmote Custom Emotes Tutorial. This guide will teach you how to set up your own random emotes for your favourite pet family or even your faithful companion.

Some Words About Pet Emotes

To write high quality pet emotes, you need to know how PetEmote works. As PetEmote doesn’t need any hidden channels to send its output, it uses a trick called masking. That means, what really goes out to other players is something similar to PlayerName ’s PetFamily PetName does a fine emote. It is nothing else than a simple custom emote that anyone could write using the /me command. And this is, where the trick comes into play: PetEmote detects all emotes sent by itself or other PetEmote users out there and cuts off the part in front of the pet’s name.

For that reason, players who have no PetEmote installed, will always see the uncut version of the emote beginning with the player’s name followed by the pet family and name. As you can imagine, there are more players without PetEmote than those who use it. This is why you should always keep in mind, that your pet emotes start with your character’s name – so never use your own Name in your pet emotes! Otherwise most players will read something like that:

Jorna’s Bear Mad sniffs at Jorna’s bag for some food.

Does it sound good? No, it doesn’t. So don’t do it. Whenever you need to refer to yourself, do it from a third person view:

Jorna’s Bear Mad sniffs at its mistress’ bag for some food.

Now let’s head for some random emotes configuration.

How PetEmote Generates Random Emotes

The problem in automatically generated emotes or text messages is always the same: they are repeating once in a while. The intention of PetEmote is, to minimize repetition as good as possible. Of course, things that pets can do (described in an emote) is limited by player’s fancy. This is what hand-written emotes are for; unfortunately, most good emotes are out of place in any situation. Thus random emotes are rather limited by aiming for neutrality.

PetEmote tries to bring alternation into its emotes. This is done by splitting emotes into small pieces of text, which are chosen at random. When defining emotes, those pieces are chosen well to prevent bad grammar and word order. Additionally, PetEmote takes one, two or even three of those random sentences and joins them using a comma or the word and.

It gives us the charm of many different emotes, while defining only a few words and rules. Of course, that way repetition is not fully cut off. But it feels like you never know what your pet is doing next.

How to Get Your Changes to Show in the Game

After you changed anything in your configuration and saved the file, this won’t affect the active game session. On the other hand, you will not have to quit the game and restart it. Just type /console reloadui and your interface will reload completely, especially all addons including PetEmote. Whatever you changed will then work – if you didn’t make any misstakes.

Using the PetEmote Editor

You can use the PetEmote Editor, which is located in the PetEmote addon directory, to write your own emotes. The Editor only runs on Windows systems and needs Microsoft .NET Framework 3.5 to start. If you do not have the framework installed, you will receive an error message on starting the program.

The Editor relieves you of the pedestrian work of writing LUA source code. All you have to do is write, save, reload your interface. The following instructions are related to writing emotes in the source code — without the Editor. However, it can be useful to read on, to get a feeling for how emotes are created. The Editor is based on that structure.

Where to Define Your Custom Emotes

In your PetEmote installation folder (which should be /World of Warcraft/Interface/AddOns/PetEmote) you will find a file named default-emotes.lua. Create a copy of that file and rename it to custom-emotes.lua. Edit this file with some kind of better text editor – that means, do not use Windows Notepad or Wordpad. The editor must support UTF-8 encoding, because World of Warcraft needs all files like that. Otherwise you will receive an error message telling you, that all chat text needs to be sent in UTF-8. If you don’t know what a better text editor ist, try Notepad++ (download the latest Installer file). You can search for your pet family in this file and edit the predefined text — or you can delete anything and begin to write your own configuration as described next.

Basically any configuration starts and ends like this:

PetEmote_DefaultEmotes["PetFamily or PetName"] = {
    –– many lines of configuration
}

The part in square brackets defines, what you configuration is for. PetEmote defines many pet families by default, but you can override a family in custom-emotes.lua if you like. You can also put in the name of one of your pets, so PetEmote will use this configuration only for pets with that name (it’s your problem, if you name all your pets the same).

Instead of PetEmote_DefaultEmotes you can also create a section called PetEmote_CombatEmotes, for writing emotes that are triggered in combat. These emotes work in the same manner as default emotes. That applies to the hunter-only PetEmote_FeedingEmotes too.

Defining Emotes

Now here we go for the main work: defining emotes for your pet. If you are not familiar with LUA tables, keep close to the example code and pay attention to braces and commas.

PetEmote_DefaultEmotes["MyPet"] = {
    [1] = {
        ["text"] = "does something funny",
    },
}

This defines one emote which reads like this: MyPet does something funny. Indent your code with one more tabulator for each level as you go deeper into the configuration tree. That will make it easier to understand what you are doing.

The number 1 is the index of the emote. Each emote has its own unique number; those numbers must follow each other. So emotes are nothing more then a consecutively numbered list of items.

You may have recognized the ["text"] part, which is the key that defines the emote text. Let’s have a look which other keys exist.

Optional Text

[1] = {
    ["text"] = "does something funny",
    ["optional"] = {
        [1] = {
            ["text"] = "with its ears",
        },
        [2] = {
            ["text"] = "with its feet",
        },
    },
},

The optional-key defines another sub-array of possible emotes, which can follow their parent emote. PetEmote doesn’t have to use those optional emotes, so make sure that the parent emote works standalone as well. Now our configuration can produce the following emotes:

Continuing Text

[1] = {
    ["text"] = "does something funny",
    ["optional"] = {
        [1] = {
            ["text"] = "with its ears",
        },
        [2] = {
            ["text"] = "with its feet",
        },
    },
},
[2] = {
    ["text"] = "performs some",
    ["continues"] = {
        [1] = {
            ["text"] = "other stuff",
        },
        [2] = {
            ["text"] = "funny tricks",
        },
    },
},

The continues-key is very similar to the optional-key, with one important difference: one of the texts defined below has to be attached to the parent text. For that reason, there are only two more new emotes resulting from this part of the configuration:

Just because we used the continues-key, the configuration cannot result in an emote like MyPet performs some.

As a side note: It is possible to use the optional- and continues-keys within the same item. PetEmote will decide, if it likes to use the optional-part, and otherwise go the continues-way for sure.

Disallowing Following Emotes

To produce a wider range of different emotes, PetEmote can join some top level emotes, as long as you allow it. By default, PetEmote can join any emote configurations. This can produce very strange sentences, if some words are used twice. To prevent this, you have to define keywords with every text. PetEmote will not combine two top level emotes which both contain any keyword. Let’s see how it works:

[1] = {
    ["text"] = "does something funny",
    ["optional"] = {
        [1] = {
            ["text"] = "with its ears",
            ["keywords"] = { "ears", "ear" },
        },
        [2] = {
            ["text"] = "with its feet",
        },
    },
},
[2] = {
    ["text"] = "wags its",
    ["continues"] = {
        [1] = {
            ["text"] = "tail",
        },
        [2] = {
            ["text"] = "ears",
            ["keywords"] = { "ears", "ear" },
        },
    },
},

The keyword ears tells PetEmote, that it must not combine it with any other part of an emote, which also has a keyword ears (or ear). It also works in the other direction.

There is also an easy way to stop PetEmote from combining an emote with any other text: Just leave a dot, exclamation mark or question mark at the end of the text. PetEmote will then stop adding text to this emote guaranteed.

Using Conditions

Sooner or later you will have an idea for an emote, that cannot easily be defined in the way we learned above. For example, in a pet family configuration you cannot refer to you, the pet’s master, because you don’t know if the character is male or female. Also the pet’s gender can be interesting – more in other languages then in English. You will also need a way to ask for the players target: if he has one and if it is friendly or unfriendly. This is how it works:

[1] = {
    ["text"] = "snarls at %t",
    ["condition"] = TargetExists,
    ["continues"] = {
        [1] = {
            ["text"] = "grimly",
            ["condition"] = TargetIsUnfriendly,
        },
        [2] = {
            ["text"] = "friendly",
            ["condition"] = TargetIsFriendly,
        },
        [3] = {
            ["text"] = "loudly",
        },
    },
},

The condition-key defines a keyword, that instructs PetEmote to check if the condition is true and then allows to use this part of the configuration. So in the example above the pet will only snarl at the target, if the player has one – which makes sense if you think about your first try to use %t without having a target.

The emote above has three possible continuations: snarling grimly, friendly and loudly. The first one can only occur if the target is unfriendly, the second only if the target is friendly and the third in any case. It is important to think about which possibilities PetEmote has to choose one way. If you define continuations only for unfriendly targets, you will receive an error the first time the emote is used while you have a friendly target.

In the next example we ask for the pet’s and player’s gender. Again, we have to define both possible genders, but we can pass on defining a default text, because there is nothing more than male or female – one of it will work for sure.

[2] = {
    ["text"] = "sniffs at",
    ["continues"] = {
        [1] = {
            ["text"] = "his",
            ["condition"] = PetIsMale,
            ["continues"] = {
                [1] = {
                    ["text"] = "master's bag for some food",
                    ["condition"] = PlayerIsMale,
                },
                [2] = {
                    ["text"] = "mistress' bag for some food",
                    ["condition"] = PlayerIsFemale,
                },
            },
        },
        [2] = {
            ["text"] = "her",
            ["condition"] = PetIsFemale,
            ["continues"] = {
                [1] = {
                    ["text"] = "master's bag for some food",
                    ["condition"] = PlayerIsMale,
                },
                [2] = {
                    ["text"] = "mistress' bag for some food",
                    ["condition"] = PlayerIsFemale,
                },
            },
        },
    },
},

Here is a list of all existing conditions based on the latest version of PetEmote.

Happiness Conditions

Warlock’s pets are always unhappy, content and happy at the same time as there is no happiness for them. Using these conditions will make no difference. Check out PetEmote’s default configuration in default-emotes.lua and you will find that most hunter pet’s configurations use the happiness conditions very often, especially at the top level.

Targeting Conditions

All targeting conditions ignore the player and the pet. That means, if you are targeting yourself or your pet, PetEmote will decide that you have no target. This is an exception to ensure good emotes as you learned at the beginning of this tutorial.

Gender Conditions

Food Conditions

These conditions only work for hunter pets if they are used within a PetEmote_FeedingEmotes section.

Sentence Structure Conditions

These conditions, especially the first one, can be very useful if you like to make sure, that a text is only used at a special position within a sentence, i.e. at the beginning.

Making PetEmote Better

You see, telling PetEmote what to do is some kind of work. A good configuration for only one pet family can take hundreds of lines of code. Therefore it is not possible for one developer, to write all that alone – even if you think that nobody plays with every pet family and so nobody knows what other players are missing in their emotes.

Feel free to ask your questions about PetEmote configuration or make any suggestions for new conditions and other stuff: jorna@zirkel-des-cenarius.eu (but please, do not ask me how to install the addon, why it doesn’t work and why the game cries about syntax errors in your code). Feel also more free to send me your configuration – I will bring it into the next version of PetEmote to make the default installation more useful. Thank you!