Utility Boxhud 04/06/2024

Overview

This Lua script provides an alternative to a similar MQ2HUD/MQ2NetBots based HUD. Instead, it uses observed properties from MQ2DanNet to watch various bits of information about all your peers. It can also still use NetBots properties as well, though that is less tested.

The instructions and FAQ tabs, as well as the Configuration section further down on this page provide details on how to customize Boxhud. More info is also available here.

Default Configuration

The default configuration comes with 3 tabs of information: General, Macros and XP.

General Tab
- Name -- Character names in green if in same zone as the character running Boxhud, in ( ) if invis, or in red if not in same zone.
- HP% -- with % threshold based coloring, red < 35, yellow < 70, green > 70
- Mana% -- with % threshold based coloring, red < 35, yellow < 70, green > 70
- Endurance% -- with % threshold based coloring, red < 35, yellow < 70, green > 70
- Distance -- if the character is in same zone, displays distance away from the character running Boxhud. green if dist < 100, yellow < 200, red > 200
- Target -- if character is in same zone, displays the name of their target.
- Spell/Disc -- Name of spell currently being cast or current running disc

Ex. Green names are in the same zone as the character running the HUD. Red names are in different zones.

Macro Tab
- Macro Name -- the name of the currently running macro
- Paused -- shows PAUSED if the currently running macro is paused
- Pause macro button -- sends `/dex name /mqp` to the character
- End macro button -- sends `/dex name /end` to the character

Ex. Extended the default configuration to also include "CWTN Mode" on the Macros tab.

XP tab
- Exp -- current level experience value (out of 100,000)
- AA Unspent -- current number of unspent AAs


The Name column, regardless of what tab its on, includes the following functions:
- Left click -- Brings the character to the foreground with /dex charactername /foreground.
- Right click -- Opens a context menu with several random actions to perform against that character. Entering text into the "Send Command" input will do: /dex charactername <text input>.
These button actions are more just to play around with the capabilities we have now with an interactive window like this.


The ImGui table API also allows some customization like editing what columns are displayed, and drag/drop columns to rearrange them.

Ex. Show or hide columns from the table.

Ex. Drag columns around to rearrange them.


Requirements

- MQ
- MQ2Lua
- MQ2DanNet OR MQ2EQBC/MQ2NetBots, depending on where you want to get box info from.

Installation

Extract the boxhud-x.y.z.zip and add the boxhud folder to the lua folder of your MQ directory.

NOTE: If the script errors loading lfs.dll, then you may need to install the VC Redist package from Microsoft

Usage

Run Boxhud with the following command:

If MQ says that it failed to parse the command, then do /plugin lua load.

Setup Boxhud to run at login for a given character:

If you want Boxhud to start automatically when you enter the game, this can be accomplished by creating a configuration file for your character:

1. If you don't already have a character config file for the character which will run Boxhud, create a file in your mq/config folder like servername_Charactername.cfg, for example, rizlona_Aquietone.cfg
2. Add the following line to the file:

Stop Boxhud with the following command:


Toggle the window with the following command:


Show help with the following command:


Hide character names in the Name column with the following command:

NOTE: This only applies to the Name column, mostly for the purpose of taking screenshots. Names in other spots like the Target column or on the admin tab are not removed.


Configuration
Boxhud configuration is stored in a separate Lua file per character, within the Boxhud folder. It shouldn't be necessary to open the file for anything, as all the configuration can be done in game, but if you want to keep a backup or your settings, or find it easier to edit the file to add configuration, it is stored in lua/boxhud/settings/boxhud-settings-charactername.lua.

By default, boxhud-settings.lua is included with the script. Upon startup, it will be copied to the character specific file boxhud-settings-charactername.lua.
An existing boxhud-settings-charactername.lua will always take precedence over boxhud-settings.lua.

Configuration is recommended to be done using the Configuration tab in the HUD. All options can be edited in the appropriate settings Lua file for a character, but its easier to visualize the settings in game.

When editing settings in the configuration tab, each individual item (column, property or tab) is saved immediately to the settings file when clicking the save button for the item.

Onto the options...

Boxhud configuration is broken up into 4 main sections: Properties, Columns, Tabs and Windows.
- Properties define what data you want to watch in the HUD. These can include DanNet observed properties, NetBots properties and Spawn properties.
- Columns define the display settings for a given property, such as whether it should only show for characters in the same zone as you, or whether it is a percentage value. They can also be used to define value mappings to display different text based on the value returned for a property.
- Tabs define a group of columns to be displayed together.
- Windows define the UI windows that will be drawn. By default, there is only one window, but more windows can be added which each can watch different DanNet peer groups or include different tabs.

Properties

There are 3 types of properties: Observed, NetBots and Spawn.
Properties can be configured directly in the HUD configuration tab.

Observed properties

Observed properties define a property for which a DanNet observer should be created for each character, to monitor the value of that property from each character.
For ideas on other observed properties to add, check out the MQ TLO docs here: MacroQuest Docs

NOTE: All TLO members are case sensitive. For example, me.pcthps or Me.Pcthps or Me.PctHps will fail. Only Me.PctHPs will work. Adding observers on TLO members that don't exist can have annoying consequences. If you're unsure, /echo it first.

To add a property that should be observed on all characters, just set the property name. For example, to add Me.Level:


In the boxhud-settings.lua file, this will be added as:

Observing properties which are not defined on a character can impact running macros. To avoid this, there are some optional settings which can be added to Observed property definitions to define conditions for when to create the observer for a given character:

The above image shows how to add a property which should only be observed on certain characters, like only those classes which are running CWTN plugins.
Set the DependsOnName to Me.Class.ShortName and DependsOnValue to the list of classes which have CWTN plugins loaded.

In the boxhud-settings.lua file, this will be added as:

NetBots properties


NetBots properties define a property to get from NetBots for each character.

Spawn properties


Spawn properties define a property to read from the Spawn data for each toon. These will only work for toons that are in the same zone as only they would have Spawn data available.

Properties summary
All 3 types of properties can be mixed together, provided they have unique names. Combining the 4 example properties above, we would have:



Columns
Columns can have two types: Property or Button.

Property Columns

Each property column includes several settings, for example:

Each column lists the observed property or properties which it uses to populate its data.
More details on each setting can be found in the provided boxhud-settings.lua
Note that the Name column is treated as a special case.

Button Columns

Each button column specifies the command to run on click, for example:


The button `Action` supports replacement of the string `#botName#` with the name of the character in the row where the button exists.

Columns can be configured directly in the HUD configuration tab:




Tabs
Each tab includes a name and list of columns to be included in that tab, for example:


Tabs can be configured directly in the HUD configuration tab:




Windows
Each window defines a DanNet peer group which it will display characters from, and the list of tabs that will be displayed in the window.
Windows can be configured directly in the HUD configuration tab:



There are 4 options for the DanNet peer group which can be configured for a window:
- all -- The window will show all characters connected to DanNet, from the all peer group.
- zone -- The window will show all characters in the same zone as the character running Boxhud, from the automatically created DanNet peer group for the current zone.
- group -- The window will show all characters in the same group as the character running Boxhud, from the automatically created DanNet peer group for the group. Note that the automatically created group in DanNet relies on the group leaders name, and Boxhud is currently written to expect the character running Boxhud to be the group leader. This means that if the window is set to use "group" and your characters name is "aquietone", then the window will display characters from the group "group_myserver_aquietone".
- other -- If you want to enter your own DanNet peer group which is not covered by the above, then select other and enter your own group name.

By creating more windows, you can split out different groups if you are running multiple different teams and want to keep them separated. The windows can be docked together, kept separate, etc.:

Ex. Adding a window for another group:


3 Boxhud windows docked together as a tabbed window:


3 windows docked together vertically:



Other Configuration Options

PeerSource
This can be set to dannet or netbots to specify whether the list of peers to display in the HUD should come from MQ2DanNet or MQ2NetBots.

RefreshInterval
Configure the delay for polling observed properties. Used in mq.delay() call.
Default: 250 (0.25 seconds)

StaleDataTimeout
Configure the time in seconds before stale entries are removed from the displayed data.
Default: 60

Text Colors
The colors of various parts of the HUD are configurable under General Settings in the configuration tab:


The default color will be for any column that doesn't fall under any of the other categories.
Low, Medium and High threshold colors are for columns with number values that have 1 or 2 thresholds defined.
Name, Name invis and Name not in zone colors are for the Name column only.

Troubleshooting

The Admin tab of Boxhud contains some options to help resolve issues that may occur with DanNet observers. If characters go LD or you swap characters, or for some other reason your DanNet observed properties get screwed up, you can try to reset them from the Admin tab.



Extra notes:
- I'm far from (read: not at all) a Lua expert, so don't be too surprised if any Lua best practices haven't been followed here or things could be done in much more clean ways.
- I'm open to suggestions / improvements
- This is mostly just written as me wanting to explore some of the possibilities provided by the new Lua support