Customizing The Hekili Priority Rotation Pack APL - Hekili/hekili GitHub Wiki

Things to understand before proceeding

Terms

[!NOTE]
In this context, the terms Priority, Rotation, Pack and APL are essentially interchangeable. A rotation is the way you decide what ability to use in-game. It is often based on a priority system. In Simulationcraft, the "sims" are an Action Priority List (APL) which is a more advanced, nuanced version of the priority that involves logic and coding. Hekili translates these APLs into Packs in the addon.

Simulation Craft (SIMC) Default Priorities

The default priorities are imported from SimulationCraft profiles, meaning that they are tested in SimulationCraft (the engine behind Raidbots) to prove that they have optimal DPS benefit. Sometimes this leads to behavior that appears different from what you may see in a class guide. These differences can occur for many reasons, some good and some bad. Before making changes to the addon priority, I strongly encourage you to make changes in your sim profile and test in multiple fight styles (Patchwerk, Hectic Add Cleave, DungeonSlice for some specs) so you're aware of the benefits and risks before proceeding.

Hekili and SIMC are not 1:1 imports

There are nuances and differences between the Hekili APLs and the SIMC APLs. Attempting to simply import a SIMC APL into the Hekili addon rarely works correctly.

Let's look at an excerpt example of Shadow Priest.

SIMC Shadow Priest "Empowered Filler" sublist excerpt, October 15 2024

actions.empowered_filler=mind_spike_insanity,target_if=max:dot.devouring_plague.remains
actions.empowered_filler+=/mind_flay_insanity,target_if=max:dot.devouring_plague.remains

Hekili addon Shadow Priest "Empowered Filler" sublist excerpt, October 15 2024

actions.empowered_filler+=/mind_spike_insanity,cycle_targets=1
actions.empowered_filler+=/mind_flay_insanity,cycle_targets=1

While these 2 sections do the same thing, the syntax is different.

Default packs are overwritten on new updates

One important thing to remember is that "default" packs are written in Blizzard Blue text in the addon, and if an update is made to them any edits you have made will be lost.

If you want to make more permanent changes, you should make a copy of the default pack and then edit it. Any changes made to the default pack in the future by the developer must be manually recreated in your custom pack. No support is offered for maintaining your custom packs, it is purely a self-led endeavor.

To create a copy of the default pack:

[!NOTE]
You need to have your new custom pack "active" before it will work, be sure to click the checkbox (which is unchecked in the above screenshot) for your new pack, whose name is written in white text. You can also rename it to something more meaningful.

Understanding how the pack works

Precombat list

The addon starts with the precombat list. This is typically used for

• Pre-casting (such as Aimed Shot, or Wrath)
• Buff maintenance (Hunters Mark, Mark of the Wild, Arcane Intellect, summoning pets, etc)
• Variables
  • Variables in the pre-combat list will continue to be reevaluated during combat, even if the other spells are skipped/ignored once combat starts.

Default list

After the precombat list, the addon moves to the default list. It will start at the first item and suggest it if:

• The conditions in the box evaluate to true
• The ability is useable based on other factors such as
  • being off cooldown, having enough resources, having the required proc, etc.

If it cannot be chosen, it will continue iterating the list until it finds something that passes the checks.

Some abilities may be assigned to different displays. In the below example, Tranquilizing Shot and Counter Shot are both set to the interrupts display, which I have chosen to display separately. This means the addon will iterate both displays at once, assigning recommendations to each display as appropriate. This can stop things like an interrupt from locking up your DPS rotation.

BM Hunter default list Example

The following list translates into the screenshot below in-game.

actions+=/counter_shot
actions+=/tranquilizing_shot
actions+=/mend_pet,if=pet.health_pct<pet_healing
actions+=/call_action_list,name=cds
actions+=/call_action_list,name=trinkets
actions+=/hunters_mark,if=(settings.mark_any|target.is_boss)&active_dot.hunters_mark=0&target.time_to_pct_80>20
actions+=/call_action_list,name=st,strict=1,if=active_enemies<2|!talent.beast_cleave&active_enemies<3
actions+=/call_action_list,name=cleave,strict=1,if=active_enemies>2|talent.beast_cleave&active_enemies>1

Sub-lists

Some lines in the default list refer to another list, which I will call sub-lists here for clarity.

actions+=/call_action_list,name=st,strict=1,if=active_enemies<2|!talent.beast_cleave&active_enemies<3

This line will tell the addon to look for and enter the sub-list called st, if and only if you are fightin less than 2 enemies, or, you are fighting 1-2 enemies but don't have beast cleave talented.

[!NOTE]

• Call action list means that if the addon iterates the whole sub-list and does not find a suitable option, it will come back and continue iterating down the Default list.
• Run action list will simply stop when it reaches the end of the sub-list and fail to generate a recommendation, and is generally not recommended outside of niche use cases.
• The strict setting here means that if the list fails, it won't bother checking any individual entries inside, saving computation time.

4. The Profile tab shows what was imported from SimulationCraft to build this priority. There are often notes about changes that were made to adjust the priority to work in-game. If you are well-versed in SimulationCraft conditional expressions, you could edit this profile directly and click Accept then Import to load changes all at once. This explanation will demonstrate the Action Lists section instead.

5. Click the Action Lists tab. You will be down the first entry in the default Action List. Both default and precombat are built in lists that the addon uses internally. Before combat, the addon will review precombat list for recommendations first, then move onto the default list and any additional lists that are run/called from there. In combat, the addon will mostly ignore the precombat list, unless there are essential abilities included -- things like maintenance buffs that you wouldn't want to drop during a raid fight and then leave off for the rest of the fight.

6. Clicking the Entry dropdown gives a high level overview of the current Action List.

When reviewing the action list entries, consider a few important details:

• Action Lists are a priority list, not a chronological list. That means the addon will provide the first recommendation that has its criteria met. It would be wrong to interpret the above image to mean: use Skull Bash, then use Cat Form, then use Rake, then use Ferocious Bite. It's more accurate to say: If Skull Bash can be used and its conditions are met, use that. Otherwise, check the balance action list if its conditions are met. Otherwise, activate Cat Form if Cat Form is not activated. Otherwise, use Rake if you are in Prowl/Shadowmeld. Otherwise, go check the Cooldowns list.
• Conditions are similar to SimulationCraft, but sometimes adjusted to work in the language used by WoW addons (Lua). Use conditions from your existing priority for examples. Or refer to SimulationCraft wiki's conditional expressions.
• [Call Action List] will switch to the referenced action list, returning to the current list and continuing on, if no recommendation was identified.
• [Run Action List] will switch to that action list and never return, meaning any actions after [Run Action List] in the priority will be ignored if the conditions for [Run Action List] were met. (That means, if you we add anything after entry 10, a [Run Action List] entry without any conditions, we will never reach that entry.)

7. In this example, we are wanting to add Regrowth to our priority, so that we make use of the healing potential in PvP. We will assume that this is for Shadowlands, where Regrowth no longer interacts with the Bloodtalons talent. We are also aware that the addon itself has some extra internal code that makes it so Regrowth will not be recommended in Cat Form unless it is instant cast (from Predatory Swiftness). Since the addon handles that bit, we don't have to worry about it. However, we don't want to be forcing ourselves to cast Regrowth when we're not missing health.

8. Click the green plus sign next to the Entry dropdown.

9. Click the Up triangle to move the entry to position 8, placed before our finishers priority. I selected this position because using a 5 combo point finisher will result in proccing another Predatory Swiftness, so I am assuming that I want to use my Predatory Swiftness before that so it doesn't go to waste.

10. Check Enabled.

11. In the Action dropdown, select Regrowth.

12. In the Conditions box, type health.pct < 80 -- this expression means that your own health percentage is below 80%. You could use a different number or try other conditions. For instance, health.pct < 80 & fight_remains > 5 means that your health percentage is below 80% and you're expected to remain in combat for more than 5 additional seconds. You might not want to self-heal if you can just get the kill and get out of combat quickly.

There are a few other fields here you can interact with. Caption, if your Displays are configured to Show Captions, will place the text you provided on the icon when this ability is recommended. This can be useful for live troubleshooting.

Show Modifiers allows you to access some additional options that are more advanced. Cycle Targets refers to swapping targets if this ability applies a debuff that you want to spread to multiple targets. It requires internal support (code) to work fo rany particular ability.

Check Movement allows you to specify whether you want the addon to be used only while stationary or moving.

Use Off Global Cooldown lets the entry be recommended during the GCD (if the ability is off GCD to begin with). Otherwise, the addon tends to line up abilities with the GCD, as this also results in less wasted buff/debuff uptime.

Use While Casting sets a particular ability to be recommended while casting another spell. For instance, a Fire Mage will Fire Blast during a Fireball cast. A Shadow Priest will use Searing Nightmare during Mind Sear.

13. Test it!

In the screenshot above, I have paused the addon while Regrowth is recommended in the first recommendation slot. (The default Pause keybind is ALT-SHIFT-P.) While paused, I can mouseover and see why the recommendations I'm shown have been shown.