﻿Hammer of Justas
by Justas ( paladin (dot) justas (at) gmail (dot) com )
version 0.96.8-Beta

IMPORTANT INFO FOR USERS OF PREVIOUS VERSIONS
---------------------------------------------
If you were using this addon with versions prior to 0.96 you may need to reconfigure your settings, as the addon variable saving was rewritten to support multiple classes.

IMPORTANT INSTALLATION NOTES
----------------------------
It is recommended you delete your existing Hammer of Justas folder and restart your WoW client when installing a new version of the addon, as new files may have been added that the WoW client will not detect until prior to a restart.

WANT SOME PRETTY PICTURES?
--------------------------
Check the downloaded archive for a PDF version of this document, or visit https://tinyurl.com/ychmlgnh to read it on Google Docs.

NEW FEATURES
------------
* Incoming damage and health tracking was completely rewritten in 0.96.7 to be more reliable through monitoring the combat log.
* Incoming spells (i.e. skills with a cast bar) are monitored and high damage spells are remembered. When these are cast again the addon will suggest mitigation skills in the cooldowns frame. This is mostly intended for Shield of the Righteous and Shield * Block, but will also trigger Shield of Vengeance.
* The addon can be toggled on and off for any supported spec in the addon settings.


SUMMARY
-------
Hammer of Justas is a DPS rotation add-on for Paladins (Retribution and Protection) and Warriors (Arms and Fury). You can think of HoJ as an AI-enabled DPS rotation helper.

Why AI-enabled? Because Hammer of Justas starts with the rotation rules found on well-known and respected sites like Icy Veins (https://www.icy-veins.com) and augments those with the current game context. Hammer of Justas is constantly monitoring the game world context in order to take many additional factors into account, beyond just rotation priority lists, such as:
* Range to target.
* Current health of target.
* Current health of the player. 
* Player's historic and current DPS.
* Crowd control.
* Whether or not the player is fighting a single or multiple targets.
* Whether or not the player is in a group.
* Incoming DPS.
* Target time to live.
* Predicted player health.
* Target's active spell cast.
* Current player buffs and debuffs.
* Target buffs and debuffs.
* Current and future power levels (capping).

GENERAL FEATURES
----------------
* Rotation window with ideal and alternate skill choices.
* DPS buff timers (Inquisition, Furious Slash, Overpower, Seraphim, etc.).
* Blessing tracking and reminders (Battle Shout, Blessing of Wisdom, Blessing of Kings).
* DPS cooldown reminders (Avenging Wrath, Recklessness, Avatar, etc.).
   * Shown only when fighting a boss, a tough mob, or some mob that is predicted to take longer to die than the DPS buff duration.
* Mitigation reminders based on incoming DPS and predicted health (Enraged Regeneration, Die By the Sword, Shield of Vengeance, Heroic Leap, etc.)
* Interrupt reminders (Rebuke, Pummel, Hammer of Wrath, Storm Bolt, etc.)
* Crowd control breaking reminders.
* Mitigation suggestions based on target casts (Shield of the Righteous and Shield Block).

Paladin Features
----------------
* Highly visible Holy Power meter.
* Highly visible Templar's Verdict indicator.
* Inquisition rotation integration and buff tracking.
* Selfless Healer buff tracking.
* Consecration buff tracking (suggesting consecration when not standing in it)
* Seraphim rotation integration and buff tracking.

Warrior Features
----------------
* Rotations include healing based on current health.
* Easy maintenance of Furios Slash for Fury.
* Easy maintenance of Overpower and Colossus Smash (or Warbreaker) for Arms.
* Rotations change based on number of targets and attackers.

Customization
-------------
* Any skill can be removed from a rotation by unselecting it in the addon options.

Miscellaneous Features
----------------------
* A chat ignore system that allows silent and stealth ignoring and keeps ignored messages in a special history that can be viewed later.
* Easy-to-move invisible windows (just hold control and mouse over a window to unhide it, then click to drag it anywhere).
* Ability to toggle individual windows off if not needed or desired.
* Cooldowns that need to be refreshed are shown on a separate, clickable bar that can be placed anywhere. The add-on is smart enough to only show some of these skills when an enemy is targeted, so that it's not constantly nagging about them in towns, etc.
* Interoperable with OmniCC. If OmniCC is not available HoJ will show its own cooldown text in some places, otherwise it will let OmniCC do it.

All meters and reminder windows are easy to move around (hold control and mouse over, click to drag) so that they can be placed anywhere on the screen, and easily adjusted for different scenarios (for instance raids vs. PvP).

NOTES ON PROTECTION SPECS
-------------------------
As of 0.96.7 protection specs rotations and mitigations are still experimental.

USER INTERFACE
--------------
When the addon starts the first time, hold control and mouse over the windows in the center. Drag the windows to the desired locations while holding control. Windows can be turned on and off entirely in the addon settings.

It's a good idea to try a target using a target dummy when deciding where to place the windows.

Which skills are displayed in the bars can be toggled in the addon settings.

Window Frames
-------------
The addon adds several window frames. Each of these can be toggled on or off in the AddOn settings. When holding control and mousing over a window, the name of the windows is shown as "HoJ:" plus the window name.

In general, windows are context sensitive and will become active targeting a mob that is attackable and in range, or when the character is in combat.

Holy Power (Retribution Paladin Only)
-------------------------------------
Shows the number of Holy Power stacks as little glowing judgment masks. Note that this was made back when the only Holy Power indicator was on the player portrait frame. It's not as useful today if "Personal Resource Display" under "Names" is turned on in the WoW Interface settings.

Templar's Verdict (Retribution Paladin Only)
--------------------------------------------
Shows a large glowing judgment mask whenever 3 or more Holy Power is available. Note that this is decoupled from the rotation frame, in that it will become visible whether or not it is the best time to use Holy Power. Situationally, it can be good to know when a Holy Power skill is available. This can be considered redundant with the Holy Power Frame or Personal Resource Display option, so it can be turned off. 

Rotation
--------
Shows the icon of the best current skill in the DPS rotation. For Ret, this is currently based on the Icy Veins rotation here (https://www.icy-veins.com/wow/retribution-paladin-pve-dps-rotation-cooldowns-abilities) which looks similar to the rotation Wowhead here (https://www.wowhead.com/retribution-paladin-rotation-guide). 
* Whether or not the target is within range of the skill.
* Whether or not using the skill will overflow five Holy Power.
* If Wake of Ashes available and there is a a choice of Holy Power generators:
   * Less than 3 holy power, choose a generator that will result in 3 Holy Power
   * Then choose a Holy Power consuming skill
   * Then Wake is available without any loss of Holy Power generation.
* There may be other rules added in the future, such as inserting Divine Shield or Lay on Hands into the rotation when death appears to be imminent.

Cooldowns
----------------------
This window shows situational cooldowns. These are generally skills that are not part of the DPS rotation or enhance the DPS rotation, but have long cooldowns.

This window frame will also show mitigations based on incoming damage. The addon is continually managing the last several seconds of incoming damage and using that to predict the player's health over the next 5 - 10 seconds. If the addons sees significant incoming damage it may suggest a mitigation such as Shield of Vengeance or Ardent Defender a healing spell such as Selfless Healer, or if death is predict in the next 5 seconds, a major cooldown like Blessing of Protection, Divine Shield or Lay on Hands. Because these are not part of the rotation, the player can use their best judgment as to which mitigation to use.

For Paladin Retribution spec this window will show:
* Selfless Healer when it has 4 stacks, or if it has any stacks and character health is lower than a threshold.
* Shield of Vengeance when it is off cooldown and the character is in combat.

For Protection Paladins this window shows mitigation and healing cooldowns, based on incoming DPS and current health:
* Ardent Defender
* Guardian of Ancient Kings
* Lay on Hands
* Light / Hand of the Protector
* Gift of the Naaru
* Blessing of Protection
* Divine Shield

For both Protection and Retribution it will show:
* Interrupts when the target is casting an interruptible spell.
* Avenging Wrath / Crusade when it is off cooldown and the character is in combat.
Buffs
This window shows buffs that need to be refreshed. Currently works for Greater Blessing of Kings and Greater Blessing of Wisdom for paladins, and Battle Shout for Warriors. Buff spells can be cast by clicking the icon in the buffs bar when not in combat.

Debug
-----
The addon’s settings UI allows toggling of a debug frame. The content on this frame is generally not useful and may change but it currently shows:
* “Attackers”: the number of current attackers (this is the greater of the number of mobs attacking the player AND the number of mobs the player is damaging).
* “SDPS”: the session DPS for the player. A circular buffer storing the DPS for the last n combat sessions is used to determine the player’s DPS since the addon loaded. This is used for determining Time To Live.
* “SDPS Time”: the total time for all session DPS.
* “SDPS Hits”: the total number of attacks the player landed during combat this session.
* “DPS”: DPS during the current combat session.
* “TTL”: predicted Time To Live of the current target.
* “SPD”: player’s speed as percentage of normal speed.
* “PPS”: Power generated per second.
* “PGI”: Power gain interval. Last time between power gain.
* “PGS”: Power gain step. How much power was gained in the last power gain interval.
* “NPGT”: number of seconds in the future the next power gain is predicted to occur.

CAVEATS
-------
The author makes no claims about the fitness of this add-on for any particular purpose or for any particular player’s habits or needs. If you find that it does not suit your needs, feel free to email the author at paladin (dot) justas (at) gmail (dot) com with your suggestions on how to improve it, or post on the addon’s page at https://www.curseforge.com.

In general, all of the rotations used by this addon come from Icy Veins' (https://www.icy-veins.com) class guides. Go there for more information. In some cases the addon may do better than the Icy Veins recommendation because the addon has more context, such as whether or not the target is in range, what the player's current health is, the amount of incoming damage, the current and max health of the target, the number of targets, etc.

I only decided to finally release it because some paladins may find it useful. In particular, I have not done any raiding in BFA (not even LFG!) and that probably means the addon does something during raiding that you'll find annoying. I did raid in Legion and prior, so the addon has been tested in raids -- just not in BFA. 

Finally, almost all of my Wow playing since Vanilla has been with Paladins (with the exception of rogues in earlier expansions). Playing Warrior has been a relatively new endeavor for me. If you don't agree with the rotation, or find something is wrong with it, please email me.

However, if you feel something is wrong with a rotation or encounter any issues, please email me at paladin (dot) justas (at) gmail.com.

Azerite Traits
--------------
Azerite traits are not worked into any of the rotations. This is mostly because I didn't play WoW for about a year of BFA (mostly due to not enjoying it). With Shadowlands around the corner, I probably will not be adding azerite traits at all.
Protection Specializations
- Warrior Protection spec support is not implemented. 
- Paladin Protection spec is implemented, but is from a DPS perspective and probably not suitable for raiding. This is partly because Shield of the Righteous use is so situational and would require custom coding of every major boss skill to implement. Players will still need to figure out when to use this mitigation.

Crowd Control
-------------
Hammer of Justas will attempt to determine when the player is crowd controlled and will suggest a CC breaker like Blessing of Freedom or Berserker Rage. However, WoW does not provide any way to determine if a debuff is a slow, stun or snare. In order to be 100% accurate, the addon would need to have a huge list of all existing CC spells in the game. Other addons, like Lose Control, implement their CC detection this way. Instead, Hammer of Justas uses a simpler based on the following factors:

The player is in combat
AND (
  - the player has lost control (this can be known definitively through events)
  OR (
    - the player must have any debuff (not necessarily a CC)
    - the player's current is > 0% but < 100%
  )
)
	
This mostly works with the exception of the player moving backwards in combat. Since the addon cannot see the player's inputs, it has no way of knowing if the player is simply walking or running in the backwards direction, which is slower than walking or running forwards. However, a debuff of some sort on the debuff on the player is also required for this to trigger. If this false positive is annoying, unchecking "Show <cc skill name>" in the addon options for your calls will disable it.
Blessings
Blessings are tracked when cast on other players. However, for players not in the party, the ability to track them is limited. WoW addons cannot inspect the buffs on a player that is not in the player's party. In such a case, the addon uses the original cast time to track the blessing until such time as the buff expires or the blessing is re-cast. This could result in the addon not showing that a blessing needs to be cast if the buff is removed from a non-party player in any way other than expiring due to time.

Holy Paladins
-------------
Holy specialization is not supported and there are no plans to add it.

USING THE IGNORE LIST
---------------------
The main reason for the ignore list was so that I could stealth ignore people -- not get any message from them at all, or even a message telling me I had received a message from them, and not have WoW tell them that I was ignoring them. I could not find any other add-on that would do exactly this and still keep a history of the ignored messages for later inspection.

This predates BattleTags and RealID -- it works with toon names only right now.

Commands (always preceded by /hoj):
/hoj ignore <player name>  - ignores the player with the specified name
/hoj add <player name> - same as /ignore
/hoj unignore <player name> - removes the specified player from the ignore list
/hoj remove <player name> - same as /unignore
/hoj list -- lists all player names in the ignore list
/hoj silent -- toggle silent mode, which, when enabled, stops HoJ from printing the "Whisper from <player name> blocked." message. The only way to know if a message was received from a blocked player is by checking the ignore history.
/hoj stealth -- toggles stealth ignore. With stealth ignore on, some innocuous message will be printed when a message is received an ignored player (currently something like "Isle of Quel'Danas is under attack!"). "silent" will override this behavior. If silent is on nothing will be seen when an incoming message arrives from a blocked player.
/hoj history -- show the history of ignored messages since logging on
/hoj clear -- clear the ignore history
/hoj - show command list help

HOW THE ADDON WORKS
-------------------

Rotations
---------
All rotations use rule sets to select the current skill in the rotation. The exact rotation may change in the future. In all cases it is implicit that the talent must be selected, off cooldown, and the target must be in range of the skill / talent. The first rule to have all conditions satisfied is selected as the primary skill to use. 

The secondary skill is the next skill after the primary skill that is satisfied. Note that the optional / secondary skill is NOT the next skill to use after the primary skill. Because the addon uses context to select skills, and because some of this context (for instance, range of the target, because WoW does not allow addons to know the speed and direction of units) cannot be predicted into the future, the predicted next skill will change frequently by the time it is usable (usually by the end of the next GCD).

When no secondary skill’s rules are satisfied, no secondary skill will be shown.

If no primary skill is found (i.e. all skills are on cooldown or otherwise unusable), the next best skill that is coming off of cooldown will be shown. This skill is chosen by executing the same set of rules as normal and choosing the rule which will come off of cooldown soonest and which currently passes all other tests, e.g. range, power, etc.

If you’re further interested in how the addon works, or would like to modify the rules yourself, see the HoJ_Paladin.lua and HoJ_Warrior.lua files in the addon folder. These files contain the rule sets in tables by class, spec and other qualifiers such as single or multi-target situations.

Mitigations
-----------
The addon continually tracks the player’s health and maintains a running history for several seconds. Using this history, the addon tries to predict how much damage the player will take in the next few seconds. This, in turn, is used to predict if the player’s health is likely to go below certain thresholds (including death). This, in turn, is used to select mitigations such as damage reductions and healing.

DPS Cooldowns
-------------
DPS cooldowns with longer cooldowns like Recklessness, Avatar and Avenging Wrath are not shown in the rotation cycle. Since these skills buff other DPS skills, they generally should be cast first if they are used at all and would therefore be first choices in the rotations. However, when placed in the rotation these skills tend to consume the primary rotation slot in cases where their use is delayed for strategic purposes. Due to this, such cooldowns are generally not shown as part of the rotation.

For Paladins, DPS cooldowns that fall into this category are:
* Avenging Wrath
* Crusade

For Warriors, DPS cooldowns in this category are:
* Avatar
* Recklessness

DPS cooldowns that are refreshed regularly (Inquisition, Overpower, Colossus Smash, Furious Slash and Seraphim) do show up in the normal rotation.

TODO
----
* Enable UI customization of minor and major healing player health ratios

KNOWN ISSUES
------------
* Control is used for mousing over the windows. I'm not sure what would happen if control is bound to some skill, but it's probably not good.
* If your character is less than max level, some skills may show up when they’re not usable. Though the author did level up new characters while working on the addon refactor for 0.96.0, many new features went in around this time, and may not have been tested at all levels.
* Party-sync has been tested with Paladins and Warriors, but some of the latest features were not.
* Some crowd control breaks like Every Man for Himself and PVP trinkets are not yet considered.

HELP MAKE THIS ADDON BETTER
---------------------------
If you find the addon useful, or find it potentially useful, or just hate it and are capable of (respectfully) explaining why, you can help make it better. Hammer of Justas was mostly maintainable by just the author when it was for Retribution Paladins only. With the addition of warriors, the amount of testing that has to be undertaken for every change is already not sustainable. You can help simply by being tolerant of and reporting any issues you find. Thanks!

Special Thanks
--------------
Hubbotu - Russian translations

