WowAce

HalonaTools - What is it?

HalonaTools (slogan: "A collection of useful tools and utilities for smarter than average bears.") is a 'Swiss Army Knife' addon for guild officers and members. It was originally created to help the officer-team of the PVE raiding guild Halona on the Silvermoon-EU realm to minimise the number of "required addons" that they expected the guild's members to install. If a need for a tool or feature was identified that was not provided by oRA3, Omen or DBM then it was typically developed and added to HalonaTool's collection. This therefore explains the somewhat eclectic mix of tools that 'HT' provides.

HalonaTools - A Work in Progress.
HalonaTools is currently under active development and, based on our ambitions for the addon, is far from being completed. Thus, the addon is being released as an 'Open Beta' in much the same way that Google's GMail service operated under a 'Beta' tag for its first few years. We expect all 'beta' version of the addon to be properly coded and problem free but players may find that the feature-set changes between releases or that some features are introduced in a 'bit-by-bit' manner across several releases. Our aim is to identify useful features and then to develop them carefully to create a reliable and good quality addon.

NB: See the section further down this page titled "HalonaTools - Family History" to learn where the inspiration for many of HalonaTool's features derives from.

HalonaTools Features - At a Glance.
The following is a brief list of the initial features offered by HalonaTools. Full descriptions of each of the listed features is provided in the following section titled "HalonaTools Features - In Detail."

1. Buff Announcer - Announces when players put out feasts, BBQs, soul-wells and more.
   
2. Buff Monitor - Provides discreet checking of a player's flask/elixir/food buffs and advises them if any are missing. Triggers automatically when a ready-check is fired.
   
3. Busy Responder - 'Voicemail for Whispers'. Set yourself as busy/away in HT and have all incoming whispers recorded. Includes 'whitelist' exceptions for each of; Guild Members, Guild Officers, Raid Members, Party Members, Friends and Real-ID Friends.
   
4. Invitations - Lets another player whisper the word "invite" to you and have you automatically invite them into your party/raid.
   
5. Auto-Promotions - If you are a raid leader or assistant, will automatically promote guild officers that join your raid to assistant status.
   
6. Raid Invitation Announcer - Sends out an invitation period notice, triggering other guild members using HT to be offered an automatic invitation to the forthcoming raid.
   
7. Raid Queue Announcer - Sends out a raid queue notice, triggering other guild members using HT to be offered an automatic opportunity to join the queue for the currently running raid.
   
8. Recruitment Tool - Broadcasts your guild's advertisement message to the trade channel when in cities or to the local general channel in all other locations. Provides controls to detect other guild members in the same location making broadcasts to prevent over-spamming of a single advert, a lock to prevent advertising when logged onto character that does not belong to the guild being advertised and a lock to prevent advertising when in party or raid groups to ensure dungeon and raid zones are never 'spammed'.
   
9. Info Responder - Allows other players to whisper short specific requests for information (eg: "info guild" or "info raidtimes") and receive an automated response.
   
10. LibDataBroker (LDB) Support - This addon integrates into 'LDB compatible' display addons such as ChocolateBar, Fubar+Broker2FuBar, TitanPanel and many more. In each case, the display addon may display an icon for HalonaTools that will display a rich tooltip containing status information when hovered over, will run a raid-joining tool when left clicked and will display a convenient quick-access menu when right-clicked.

HalonaTools Features - In Detail.
The following is a detailed description of each of HalonaTools main features.

BuffMonitor - The BuffMonitor is a very simple tool that performs a check of the player's own buffs and informs them via the chat-window and the 'warnings/errors' section of their screen if they are missing either a flask or 'paired elixir' buff or a well-fed buff. The check can be triggered manually by the player but is also configured to trigger whenever a ready-check is performed allowing the player to immediately see if any of their "expensive consumable" buffs have fallen off.

The tool allows the player to determine whether a check will monitor flasks, elixir-pair buffs and their well-fed food buffs. The tool supports Cataclysm and Wrath categories of flasks, elixirs and food-buffs and currently considers either type acceptable.

[Feature Status: Working as intended.]
[Planned Improvements: 1: Enable player ability to choose which buff 'eras' are acceptable from Cataclysm and Wrath categories. (eg: Many teams will wish to ensure members are using only Cata-buffs and not cheaper but less powerful Wrath buffs.) 2: Group-wide checking of buffs for all raid/party members by raid leaders/assistants.]
[Planned Limitations: There are no plans to increase the range of this tool to check all buff-types. For that, there is already the excellent RaidBuffStatus addon which we recommend in such cases.]

BusyResponder - The BusyResponder is a straight-forward "voicemail for whispers" tool that the player can enable and disable at will. When enabled, each time the player is contacted via whisper the whispered message is recorded for later retrieval and viewing by the player. A message is sent back to the sender of the incoming message informing them that you are away/busy and will respond to their message when you read it later on.

Exceptions can be set to limit who the tool responds to so that a player may enable the tool but then allow one or more of the following groups to be exempt from receiving your 'voicemail' message. Guild Members, Guild Officers, Raid Members, Party Members, Friends. For example, this lets the player go raiding and be contacted by members of the raid team in the normal manner but have whispers received from strangers outside the raid group be recorded and reviewed later on.

[Feature Status: Working as intended.]
[Planned Improvements: 1: Add support for allowing 'Real-ID Friends' as an exception group. 2: Messages are only stored on a 'per-session' basis such that reloading the UI or logging out and in clears the message cache. If this proves to be an irritation, cross-session message persistence may be added later on.]
[Planned Limitations: There are no plans to extend this addon into a more fully featured chat-logging tool. For that, there is already the excellent Elephant addon which we recommend for such uses.]

Invitations - The Invitations suite of mini-tools provide several conveniences related to the organisation of raid and party groups. It shares a lot of commonality with the Raid Functions tools described below and it is likely that a future revision of HalonaTools will reorganise and re-group these two categories together for clarity and improved ease-of-understanding/use.

The first mini-tool is the 'AutoInvitation' tool that simply monitors the player's whispers for instances of the message "invite" or "inv" and sends an invitation to the whispering player when such messages are received.

The second mini-tool is the 'AutoRaidPromotion' tool which SHOULD automatically promote players to the assistant role when joining a raid if they are officers of the guild. This feature currently is incomplete and does not work.

The third mini-tool is a tool that automatically responds to Raid Invitation Announcements, processing the announcement to understand the details before offering the player an opportunity to request an invitation to the raid via a popup window. (For more on 'Raid Invitation Announcement' messages, see the raid functions section below.)

The fourth mini-tool is a tool that automatically responds to Raid Queue Announcements, processing the announcement to understand the details before offering the player an opportunity to join the raid queue via a popup window. (For more on 'Raid Queue Announcement' messages, see the raid functions section below.)

Each of these mini-tools can be enabled or disabled by the player.

[Feature Status: Working as intended with the exception of the AutoRaidPromotion tool which is not yet functionally complete.]
[Planned Improvements: Completion of the AutoRaidPromotion tool.]

Raid Functions - The raid functions are a suite of mini-tools that provide further help and assistance to the leaders and organisers of raids. These tools are based around the typical raiding practice of Halona but are of equal value to any guild that wishes to organise their raid events in a similar manner.

To best understand how these features are used, it will help to understand the basic model Halona uses to run its raid evenings.

1: All official raids are posted on a calendar/planner where members can sign-up to indicate they will be available.
2: Fifteen minutes before the scheduled raid start time, a raid invitation period is announced and all players wishing to attend the raid may request an (automated!) invitation to the initial group.
3: Shortly before the scheduled raid start time, the initial raid team is selected from the pool of players in the invitation group with priority being given to those who signed in advance.
4: At the scheduled raid start time, the raid start is announced and all players not in the initial team may join a raid queue which is organised for that raid by a single nominated player, typically an officer.

Thus, the first tool in the raid functions suite is the "Raid Invitation Announcement" tool. This tool sends out a message via the guild chat channel indicating the invitation period has begun and it sets the Guild Message of the Day (GMOTD) field to repeat the same message so that players that login after the announcement has gone out will still see the message. The message is typically of the form: "The Raid Invitation Period has begun. Whisper the word 'invite' to Broliant for an automatic invitation to the initial raid group."

This message, known as the RIA message for short, will be detected by the copies of HalonaTools being used by other players in the guild and if those players are not already in a raid or party then they will be offered an opportunity to request an automatic invitation via a popup window.

If a player is offline when the RIA is sent out but they login before the scheduled raid start time, their copy of HalonaTools will automatically detect that the RIA is in effect by scanning the GMOTD and will automatically ask the player via a popup window if they wish to request an invitation to join the initial raid group. If they click 'Yes' the addon whispers the raid inviter the word "invite" and receives an automatic invitation as a result.

The second tool in the raid functions suite is the "Raid Queue Announcement" tool. This tool sends out a message via the guild chat channel indicating the official raid period has begun and it sets the Guild Message of the Day (GMOTD) field to repeat the same message so that players that login after the announcement has gone out will still see the message. The message is typically of the form: "The Raid has begun. Whisper the command 'wl add' to Broliant to join the raid-queue wait list."

This message, known as the RQA message for short, will be detected by the copies of HalonaTools being used by other players in the guild and if those players are not already in a raid or party then they will be offered an opportunity to join the raid queue via a popup window.

If a player is offline when the RQA is sent out but they login before the scheduled raid start time, their copy of HalonaTools will automatically detect that the RQA is in effect by scanning the GMOTD and will automatically ask the player via a popup window if they wish to request an invitation to join the initial raid group. If they click 'Yes' the addon whispers the raid inviter the word "invite" and receives an automatic invitation as a result.

In both cases above, if the player responds to the popup window question with "no" a message is displayed in their chat window confirming the choice and informing them what to do should they change their mind later on. Additionally, if the player is running an addon that displays an icon for the HalonaTools addon (eg: ChocolateBar, FuBar, TitanPanel et-al) then left-clicking on the icon will cause the addon to perform an ad-hoc manual check of the GMOTD to see if there is a raid invitation group or raid queue to join and if so, an appropriate response is provided.

The combination of these tools and the mini-tools listed under the "Invitation Tools" described earlier make the process of joining any guild raid as easy as clicking on a single icon and responding "yes" when asked if they wish to request an invitation or join the raid queue.

In addition to the above mini-tools, the raid tools suite also provides another handy set of functions. In a normal raid which may have a typical run-time of several hours, it is common to organise a break or two within that time to allow players the opportunity to take a short break and grab a drink or a quick 'bio' etc. To help keep these breaks on track, HalonaTools offers a number of "Bio-break timers" in 5 minutes intervals from 5m to 30m. Selecting any of the timer options will, if the player is a raid assistant, cause a timer-bar to appear on the screen of each member of the team with a title of "Bio-break - X Minutes". This helps player see at a glance how much break time is left when they are checking back.

[Feature Status: Working as intended.]
[Planned Improvements: Add additional menu options to enable one player to make the RIA and RQA broadcasts but have them identify a different player as the nominated 'inviter' or 'raid queue manager.']
[Planned Limitations: HalonaTools does not provide raid-queue management functionality. For such functionality, we recommend the excellent EKWaitList addon (EKWL) which performs this task admirably.]

Recruitment Tool - The main recruitment tool included with HalonaTools is the "Recruitment Message Sender" (aka: RMS) tool and the purpose of this tool is to broadcast an advertisement message for your guild on a periodic basis.

Following the introduction of the "GuildFinder UI" as part of Blizzard's default game UI, there is no longer a separate LookingForGuild chat channel in which to broadcast adverts. The "GuildFinder UI" is, at the time of writing, a relatively poor means for advertising one's guild. No doubt it will be improved over time if sufficient player feedback warrants it but until that time, the best means of in-game advertising remains the broadcasting of periodic messages.

To that end, HalonaTools provides the RMS tool. This tool will, when enabled, broadcast your recruitment message to either the Trade or General chat channel on a periodic repeating basis. Furthermore, several additional controls are provided to help the player avoid spamming any given chat channel more than is desired. These controls include:

- A "Guild Lock" control that, when enabled and configured, ensures that you only broadcast recruitment messages when you are logged-in on a character belonging to your chosen guild. This prevents you advertising inadvertently when logging into your unguilded or differently-guilded characters.

- A "Group Lock" control that, when enabled, ensures that you only broadcast recruitment messages when you are NOT in a party or raid. This prevents you advertising inadvertently in the general channel of a dungeon or raid zone instance where such practice is normally frowned upon. Although it is possible to be in party or raid and not be in a dungeon or raid zone, it is not possible to be in a dungeon or raid zone and not be in a party or raid and this therefore remains the single most reliable means of providing such protection. (Rather than, for example, attempting to use location information looked-up against a list of dungeon and raid zones. That system would fail if a new dungeon or raid zone was introduced before this addon was updated. It would also fail for any language zone HalonaTools was not translated into since non-English speaking realms have different location names.)

- An "Automatic Channel Selection" control that always checks which chat channels are available and selects the optimum channel to broadcast in. In cities, where the high-traffic trade channel is available, HalonaTools uses the trade channel for its broadcasts. Outside of cities where the trade channel is not available, it uses the local 'General' chat channel instead. In former times, when dedicated guild recruitment channels existed, advertising in 'Trade' or 'General' was not as accepted a practice. At the current time, where no other option is available, advertising of guilds in 'Trade' or 'General' is generally considered simply as another form of trade or general communication. Players should merely exercise good etiquette in their broadcasts, by sending clear messages at reasonable intervals. Badly composed messages broadcast every 15 seconds will win nobody any friends, let alone guild members.

- A "Zone Spam Inhibitor" control that listens for broadcasts made by other members of your guild and if it detects a broadcast made by another member whose location matches yours, will reset your broadcast timer to its current maximum value to ensure that even if multiple members of the same guild have and use HalonaTools RMS feature, they won't over-spam a single channel. This helps each player's copy of HT roughly sync-up with each other such that, as the broadcasting player either logs-off or moves to a new zone, the next player in that zone will be permitted to deliver their broadcast.

- A "Broadcast Interval" control, to allow the player to choose whether RMS messages are broadcast at 5, 10 or 15 minute intervals.

[Feature Status: Working as intended.]
[Planned Improvements: 1: Currently, the development of the HalonaTools GUI configuration screens is yet to being in earnest. A small number of settings have been exposed for editing, one of which is the recruitment message used by the RMS tool. Further configuration options will be added to the GUI in time. 2: Extension of the Zone Spam Inhibitor to also manage city broadcasts. Two players in different capital cities will have different locations and will therefore not be protected by the current inhibitor and may therefore broadcast in unison together. This is likely to be a simple update - where the broadcast channel is 'Trade', consider the location to be 'City' instead of whatever the GetZone() API would normally return.]

Guild Info Tool - As a partner to the RMS tool described above, the Guild Info Tool provides a means for other players to discover information about your guild without requiring any direct interaction with you. Typically, an advertisement message delivered by the RMS tool would be expected to contain a sign-off of the form "Whisper 'info' or see our website at www.myguildwebsite.com' for more information."

When the other player then whispers the single word "info" to you, they receive an automated response indicating further options they may whisper you for additional information on your guild. At the current time, this list is as follows:

- "info contactus" provides the other player with information on how to contact your guild with their enquiries.
- "info guild" provides the other player with further information about your guild, typically a brief history and mission statement.
- "info officerlist" provides the other player with a list of your guild's officers.
- "info raidtimes" provides the other player with a list of your scheduled raid times/days.
- "info recruitment" provides the other player with details of your guild's current recruitment policy/needs.
- "info zat" provides the other player with details of the ZAT approach to raiding.

All response messages are delivered to the other player via the whisper channel.

System Options - The system options simply provide a number of features for those interested in the HalonaTools addon itself, perhaps for development or administrative purposes. The two features of greatest use are the Debug Mode On/Off switch and the version checking tool

The first simply allows those wishing to see "behind the scenes" data messages output to the chat window as HT runs to do so. Dull stuff unless you're actively developing this addon! The second feature allows players to see whether their version is up-to-date by comparing it to the versions of HT being used by their fellow guild members. When a player logs-in with a more recent version of HT, the player should receive a message in their chat window informing them of the event.

Full LibDataBroker/LDB Plugin - HalonaTools provides support for the LDB standard and presents itself as an LDB data-object to other addons that support the viewing of LDB data objects. If this is a bit too "techy" for your ears, its meaning is fairly simply to describe. Many addons such as ChocolateBar, FuBar and TitanPanel support LDB addons like HalonaTools and can display an icon (for example) representing the addon. The player may then hover over the icon to see a rich tooltip full of useful information and left click or right click on the icon to trigger useful functions.

The LDB tooltip provided by HalonaTools displays the following useful information:

1: The addon's name and version number.
2: The player's guild name, guild rank and level.
3: The list of guild officers. Online officers are highlighted. If they are playing on a guilded alt, this is clearly shown.
4: Tool status information; Whether AutoInvitations is enabled, whether the BusyResponder is enabled, whether the Recruitment Message Sender is enabled as well as how long until the next message will be sent, plus the player's preferred guild and which broadcast channel would currently be used.

HalonaTools - What will it do in the future?
It is planned to develop HalonaTools further over time as noted above. Perhaps the most significant task on the list of features to be developed is the GUI configuration screens. HT has been created with maximum flexibility in mind and this flexibility will be provided via the GUI configuration screens. They will allow players to change the core data the addon ships with to better match their own needs within their own guilds and teams.

HalonaTools - Family History:

HalonaTools is the spiritual successor to an earlier addon called "FuBar_ConvergeFu" which was itself created for the members of the Alliance PVE raiding guild Converge of the Silvermoon-EU realm. After four solid years of raiding fun, the Converge team decided to downsize their team for the forthcoming Cataclysm expansion and to re-form the guild under a new banner - that banner was "Halona".

The original "ConvergeFu" addon was created in the era of Ace2/Dewdrop and was created as a FuBar plugin. This meant all users of ConvergeFu were required to find a way to integrate the FuBar addon into their UI and this was not always convenient for those members who had no interest in that particular addon. In the time since its development, Ace2 has been replaced by Ace3 and the creation of the LibDataBroker library has produced an eco-system of addons that can integrate themselves with a diverse range of display addons.

ConvergeFu became an essential requirement for all users of Converge but had many areas where its design was "hard-baked" restricting its usefulness to members of Converge only. Thus, when the launch of Cataclysm arrived and the idea to "update" ConvergeFu arose, a brand new addon that "learned the lessons" of its progenitor seemed the best course and from this, HalonaTools has been born. Still an addon targetted primarily at its parent guild, the intention with this development is to provide greater configurability and adaptability such that members of other guilds can take advantage of this addon as well.

ConvergeFu finds itself in a state of 'stasis' at the current time, still working because its dependent libraries (Ace2, FuBarPlugin etc) have been maintained "just enough" but likely to fail at some future date as those libraries become broken and untended.

HalonaTools has a much brighter future, being based on the contemporary framework libraries used commonly within the WoW addon community (Ace3, LDB, etc) and adhering to numerous practices of good design and programming to help other authors learn how to acheive results by examination of this addon's code.

Important Note:
At the time or writing, the above description contains a summary of features both completed and in-development.