Reviewing Recommendations

Behind the scenes, the addon is reviewing the current state of combat: your enemies, your resources, buffs and debuffs, cooldowns, toggles, and so forth. When the addon recommends an ability, it means that the recommended ability (1) can be used, (2) has the required resources, and (3) has its conditions for usage met. It also means that 1, 2, and 3 are not true for any higher priority abilities.

If you'd like to see why you are receiving the recommendations you are seeing, you can make use of the Pause feature built into the addon.

Pause and Review

The controls for the Pause feature are accessed via the addon's Toggles screen, in the Troubleshooting subsection.

In the above screenshot, you can see that the default key combination for Pause is ALT-SHIFT-P. You can change the key combination by clicking and pressing a new combination of keys. When pressed, the addon will stop generating new recommendations. The addon's options screen does not need to be open to pause the display. You can use the key combination at any time. The icons that are shown become interactive and will show you more information when you mouse over them.

The above image shows the tooltip related to the addon's first recommendation for my Demonology Warlock. It tells us:

• The icon shown is for Shadow Bolt.
• The recommendation is the 9th entry in the addon's precombat action list.
• The recommendation is for right now (+0 seconds).
• The criteria for this action is:
  • You have fewer than 5 Soul Shards, and
  • You are not in a boss fight or Demonbolt's cast time is not instant.
• The values of the action's criteria, at the time the recommendation was generated, were:
  • Demonbolt's cast time was 3.31 seconds.
  • You were not in a boss fight.
  • You had 3 Soul Shards.

Pressing the key combination for Pause again allows the addon to start generating recommendations once again.

When to Use

The best time to use the Pause feature is when you want to know why you are seeing what you are seeing. For example:

• You do not recognize the icon you are seeking (frequently a trinket). Pause and mouse over the icon and you can see the ability's name at the top of the tooltip.
• You know there are multiple priority list entries for an ability and you want to know which one is being shown.
• You want to know why you are seeing the specific recommendation you see right now.

The biggest challenge with this feature is that its information is presented in a SimulationCraft-like syntax that may not be familiar. While the names of different variables and values are usually fairly intuitive -- action.demonbolt.cast is probably the cast time of the Demonbolt action -- some of the syntax is less familiar. Reference the SimulationCraft wiki or a Lua guide for more details about operators and syntax, if you need to do so. Some of the basics:

• & means "and."
  These are used to combine multiple conditions. soul_shards.current > 3 & boss means you have more than 3 Soul Shards and you are in a boss fight.
• | means "or."
  This lets you have multiple combinations of independent conditions. soul_shards.current > 3 | boss means you must have more than 3 Soul Shards or you must be in a boss fight, but that both conditions do not have to be met. They both can be met, but it only takes one requirement or the other to recommend.
• ! means "not."
  This operator inverts the condition that follows it. time > 10 & ! boss means more than 10 seconds of combat time have passed and you are not in a boss fight.
• ( and ) are parentheses and are used to group options.
  See the action criteria for the first screenshot to see how parentheses allow groups of options.

Snapshots

Snapshots are a more intensive feature that includes all the detail of the Pause feature, but a snapshot can also tell you why other actions were not recommended. The snapshot is a detailed log of how the addon arrived at the recommendations that were presented. In the Pause and Review screenshot, you can see that the default key combination to create a snapshot is ALT-SHIFT-[. By default, using Pause will create a snapshot as well, so you can use either. Pressing the Snapshot key combination will create a snapshot without pausing the addon.

When a snapshot is taken, the above message will appear in chat showing which displays had snapshots created.

You can access your snapshots via /hekili > Snapshots. In the above screenshot, I selected the 3rd snapshot, for my Primary display. This loaded information into the Export Snapshot field. You will not be able to read the whole snapshot in-game. To get the information, click in the Export Snapshot field. Press CTRL-A to select all the text (even hidden lines), then CTRL-C to copy the text.

For your own review, paste (CTRL-V) into your preferred text or document editor. The snapshot will have details about your character, your gear, your talents, buffs and debuffs, etc., but will also show all the action priority entries that were ruled out before arrive at what it showed. The content of the snapshot is fairly advanced. Don't get overwhelmed. It is critical information for troubleshooting, even if you're not able to interpret on your own.

For reporting issues or sharing with the developer, paste your snapshot(s) into Pastebin or a similar service. When submitting a ticket, provide the URL of your snapshot in your issue ticket.