vrtc / holyframeset (public) (License: MIT) (since 2019-12-16) (hash sha1)
A user interface extension for a game client of World of Warcraft: Wrath of the Lich King. It aims to enhance holy paladin play specifically.
No history found.

README.md:

Holy Frame Set

Holy Frame Set is an add-on for a legacy version of a popular on-line video game World of Warcraft: Wrath of the Lich King. An add-on is a modular piece of software that is a graphical user interface extension.

Specifically, this add-on specialises the button layout to fit better for players of holy paladin class. Instead of providing tools to configure the layout, the add-on is deployed with a hopefully useful preset.

Feature list

This section describes the main expected use cases for the add-on. 1. Bind keys to Holy paladin class abilities explicitly. 2. Use custom action bar optimised for Holy paladin class. 3. Track application of specific benefitial effects separately.

See corresponding subsections for possibly overly detailed explanation on each feature.

Bind keys to abilities explicitly

Bind keys to specific abilities instead of native action buttons in key bindings game menu, like any other action. Possible actions that could be bound include all paladin class abilities, some racial abilities most useful potions, some bag items, inventory trinket items and some macros with predefined names.

This allows to preserve the key bindings between character talent resets or between different characters entierly. This also hopefully provides clarity to the key binding arrangement for the player.

Use custom action bar

The custom action bar displays all holy paladin class abilities that the player might desire to acitvely track range and cooldown for.

The decision on how to arrange the button layout and which abilities to display was made by the developer entierly. No adjustemnts can be made at runtime, as they require developer intervention.

For example Cleanse ability is absent from the action bar and Holy Shock ability is present. This is because Cleanse ability range is the same as Holy Shock, therefore to check when a target is in range of the player character it is enough to check the range of Holy Shock ability and the player can be ensured that Cleanse, Flash of Light, Holy Light and most other abilities will also reach. Additionally, Cleanse ability has no specific cooldown and only subject to global cooldown and spell school locks. Therefore there is no need to track the cooldown of Cleanse ability specifically.

However Hand of Freedom and Hand of Protection abilities are displayed on the custom aciton bar since their range is shorter than other abilities and their cooldown is longer than most.

This hopefully explains the purpose of the specific button layout and justifies the rigid pre-defined settings.

Additionally, the custom action buttons display the range to target as well as focus units. Specifically, when a target unit is in range of player character, and the ability is ready to be used, letter "T" will be displayed over the button. Similarly, when a focus unit is in range, letter "F" will be displayed over the button. When both untis are in range, both letters will be displayed.

When an ability is on cooldown, the corresponding button on the action bar will display the amount of hours, minutes or seconds before the abilitiy will become available, accordingly.

In addition to the paladin class abilities the custom action bar displays buttons for the following actions. That is up to three potions for which hotkeys were bound in the native bindings key menu. As well as appropriate racial ability.

Finally the custom action bar display the inventory trinket cooldown, regardless of which trinkets are equipped. The native key bindings menu allows to bind keys to use trinkets in specific slots, instead of binding keys to trinket names or creating a macro. This hopefully eases equipment management. (It is possible to track game engineering gadgets this way as well, but this funciton is yet to be demanded by players.)

Note that the custom action bar exists simultaneously with the native action bar. The user can toggle the visibility of each kind of frame at runtime as well as use native action bar slot key bindings.

Track application of benefitial effects

The add-on displays current state of specific paladin class effects specially. Currently these specially tracked "sticky auras" include effects: "Righteous Fury", "Infusion of Light", "Light's Grace", "Judgements of the Pure", "Beacon of Light" and "Sacred Shield".

These "sticky auras" have custom indicators displayed on the screen, in addition to the native indicators. When the effect is applied, the corresponding indicator is opaque. When the effect is not yet applied, has completely expired, or was removed by another player, the indicator is partially transparent. When the effect is about to expire the indicator flashes with red tint.

The main purpose of this function is to remind the player to refresh effects that are about to expire or reapply them when they are forcefully removed by "Mass Dispel" or "Purge" abilities.

Known issue list

This section describes the known problems that an end user that is a player might encounter, as well as potential solutions and work-arounds. Some issues that are listed aren't known errors but rather missing features that the end user might expect or explanations for controversial design decisions.

  1. Only English locale that is enUS or enGB is currently supported. This is a limitation imposed by the native game API of this particular legacy interface version, rather than the add-on implementation.

  2. The add-on is poorly fit to game vehicle combat. Specifically, vehicle action buttons must be bound to the native action bar and can not be inferred from the custom action bar.

  3. When a new spell is learned or a bag item supply is exhausted or restored, the custom action bar does not update automatically. The user must use a command "/reload" to update the custom action bar.

  4. There is no keyring custom micro button. There is still the ability to display the native action bar at runtime and borwse present keys that way.

  5. There is no custom raid frame provided.

  6. There is no custom unit frame provided. Sticky aura indicators feature helps somewhat but it is still a partially implemented feature, in comparison to what a holy paladin player might expect from custom unit frames.

  7. There is no funciton to customize the layout of indicators or buttons at runtime.

Install

First, obtain a project distirbution. Most likely it is an archive named "holyframeset-1.0.0.zip". The number is the add-on's internal version. The higher number is, the newer the contents. The only supported game client interface version is 30300 or 3.3.5a.

Exit the game if it is currently run. Second, unpack the archive in the ${gamedir}/Interface/AddOns/ directory. For that is tool like 7z or Rar or unzip is required. The ${gamedir} is path to the directory where the game client is installed.

Finally ensure that ${gamedir}/Interface/AddOns/holyframeset/ directory exists. Also ensrue that that subdirectory contains the following files:

bindings.xml
holyframeset.toc
holyframeset.xml
share/Fonts/truetype/freefont/FreeMono.ttf
share/Fonts/truetype/freefont/FreeMonoBold.ttf
src/HolyFrame.lua
src/HolyStickerGroupFrame.lua

Then enable the add-on at the character selection screen in the game. When the player enters the world with the add-on installed and enabled, the changes the add-on introduces should be obvious.

Development

This section describes the project for other developers who may be interested.

Note that the project files are laid out in a manner that allows the developer to create a symbolic link to the project workspace in the deployed client Interface/AddOns/ directory, and then modify the project as expected. Simultaneously the project distirbutes all of the conditional build files together with the mandatory business Lua source code. That way it is easy to maintain the quality of the project even after the original source code repository, and potentially build files, are lost.

All of the following steps are optional for producing a working add-on. However, these are the steps that the original developer took to ensure some degree of quality and reliability of the project's source. Most importantly, no "libraries" are employed. All of the add-on's logic is implemented in a single file. There are only a few separate XML descriptors, that are specific to the purpose of this specific game user interface extension.

Build

The required software to build a distribution archive of this add-on listed further. An example for the Debian Buster distribution of GNU/Linux.

Optionally, to obtain project sources from the original Git repository, run:

apt-get install git
git clone git://git.rocketgit.com/user/vrtc/holyframeset

To build the project run:

apt-get install gradle lua5.3 luarocks libxml2-utils
luarocks install ldoc luacheck

When all prerequisites are met, change directory to the add-on's source and run:

gradle build

The produced artifacts are found in build/distributions/ subdirectory. The Lua code documentaion that is a HTML page generated from source, is found under doc/ subdirectory.

To build and skip Lua and XML validation run:

gradle -x check build

To build and skip documentation generation run:

gradle -x ldoc build

Note that LuaCheck static analysis tool is used for code validation. This tool proved to be effective at preventing logical errors, as well as to document which parts of the native game client API are used, explicitly. LuaCheck configuration settings are stored in conf/luacheckrc.lua file.

luacheck reference

Hints:
Before first commit, do not forget to setup your git environment:
git config --global user.name "your_name_here"
git config --global user.email "your@email_here"

Clone this repository using HTTP(S):
git clone https://rocketgit.com/user/vrtc/holyframeset

Clone this repository using ssh (do not forget to upload a key first):
git clone ssh://rocketgit@ssh.rocketgit.com/user/vrtc/holyframeset

Clone this repository using git:
git clone git://git.rocketgit.com/user/vrtc/holyframeset

You are allowed to anonymously push to this repository.
This means that your pushed commits will automatically be transformed into a merge request:
... clone the repository ...
... make some changes and some commits ...
git push origin main