Report an Issue - Hekili/hekili GitHub Wiki

Hekili uses Github to manage issues/tickets.

Tickets can be:

• In-Game Errors: Includes error messages from BugSack/BugGrabber or /hekili > Warnings
• Priority/Recommendation Issues: You disagree with the addon's recommendations or recommendations are not shown
  • These require a snapshot that shows the recommendation you disagreed with
• Feature Request: You want to propose a new feature that doesn't exist in the addon, and it is not either of the other ticket types

Here are the simplified instructions for obtaining a snapshot.

A snapshot is not a screenshot, contrary to popular belief. But to explain a snapshot in depth, some other concepts need to be explained first.

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
3. Has its conditions for usage met

It also means that 1, 2, and 3 are not true for any higher priority abilities.

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.

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 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.

To see an example of a full snapshot, check here

Demonology; Primary - Shadow Bolt(0.00), Grimoire: Felguard(1.48), Shadow Bolt(2.58)
build: Dev-9.2.7 (20220914)
level: 60 (60)
class: WARLOCK
spec: demonology

talents: burning_rush
    demonic_calling
    demonic_consumption
    dreadlash
    from_the_shadows
    grimoire_felguard
    mortal_coil

...details clipped for space... 

New Recommendations for [ Primary ] requested at 12:36:22 ( 588567.08 ); using built-in ( Demonology ) priority.
*** START OF NEW DISPLAY: Primary ***
 - Dreadstalkers: 0, 0.00
 - Vilefiend    : 0, 0.00
 - Grim Felguard: 0, 0.00
 - Wild Imps    : 0, 0.00
 - Malicious Imp: 0, 0.00
Next Demon Exp. : 0.00

RECOMMENDATION #1 ( Offset: 0.00, GCD: 0.00, Casting: 0.00 ).

    Resources: mana[ 50000.00 / 50000.00 ], soul_shards[ 3.00 / 5.00 ]
    Checking if I'm casting ( No ) and if it is a channel ( No ).
    No whitelist.
    
    Processing precombat action list [ Demonology - precombat ].
        
        Current recommendation was NO ACTION at +10.00s.
        
        1.   fel_domination ( precombat - 1 )
        The action (fel_domination) is usable at (0.00 + 0.00).
         - the action is ready before the current recommendation (at +0.00 vs. +10.00).
         - this entry's criteria FAILS: time[0.00] > 0 & ! pet.alive[true]
        0.01 - true
        There are 1 recheck events.
        Recheck #1 ( +0.01 ) NOT MET: time[0.00] > 0 & ! pet.alive[true]
        Time spent on this action:  0.29ms
        TimeData:Demonology-precombat-1:fel_domination:0.29:Ability Known, Enabled(0.03):Post-TTR and Essential(0.10):Post Cycle(0.00):Post Usable(0.01):Post Ready/Clash(0.02):Post Stack(0.01):Pre-Script(0.00):Post-Script(0.00):Pre-Recheck(0.06):Post-Recheck Times(0.01):Pre-Recheck Loop(0.00):Recheck Loop Start(0.00):Recheck Post-Usable(0.01):Recheck Post-Stack(0.00):Recheck Post-Script(0.00):Recheck Post-Channel(0.00):Recheck Loop End(0.03):Post Recheck Loop(0.00):Post Recheck(0.00)
        
        2.   summon_pet ( precombat - 2 )
        The action (summon_pet) is unusable at (0.00 + 0.00) because cannot have an existing pet.
        Time spent on this action:  0.13ms
        TimeData:Demonology-precombat-2:summon_pet:0.13:Ability Known, Enabled(0.02):Post-TTR and Essential(0.10):Post Cycle(0.00):Post Usable(0.01)

...remainder clipped for space...

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.

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.