• You've discovered RedGuides 📕 an EverQuest multi-boxing community 🛡️🧙🗡️. We want you to play several EQ characters at once, come join us and say hello! 👋
  • IS THIS SITE UGLY? Change the look. To dismiss this notice, click the X --->
Boxhud

Utility Boxhud 03/14/2024

Download now:  Join us with Level 2 access or earn your way in with  RedCents.
Software Requirements
MQ
MQ2Lua
MQ2DanNet
Server Type
🏢 Live 🏘️ Emu TLP Test

2021, 2022 ESA Winner
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
1637997383331.png

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

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


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


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

Ex. Show or hide columns from the table.
1637998193521.png

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:


INI:
/lua run boxhud
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:
INI:
/timed 100 /lua run boxhud

Stop Boxhud with the following command:

INI:
lua stop boxhud

Toggle the window with the following command:

INI:
/boxhud

Show help with the following command:

INI:
/bhhelp

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

INI:
/bhadmin anon
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:
1637999361340.png


In the boxhud-settings.lua file, this will be added as:
INI:
    Properties = {
        ["Me.PctHPs"] = {
            ["Type"] = "Observed";
            ["Name"] = "Me.PctHPs";
        };
    }

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:
1637999675345.png

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:
INI:
    ["Properties"] = {
        ["CWTN.Mode"] = {
            ["Inverse"] = false;
            ["DependsOnValue"] = "war,shd,clr,shm,mag,bst,mnk,ber,rog";
            ["Type"] = "Observed";
            ["DependsOnName"] = "Me.Class.ShortName";
            ["Name"] = "CWTN.Mode";
        };

NetBots properties

INI:
    Properties = {
        ['PctMana'] = {
            ["Type"] = "NetBots";
            ["Name"] = "PctMana";
        };
    }

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

Spawn properties

INI:
    Properties = {
        ["Distance3D"] = {
            ["Type"] = "Spawn";
            ["Name"] = "Distance3D";
        };
    }

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:

INI:
  Properties = {
    ['Me.PctHPs'] = { Name='Me.PctHPs', Type='Observed' },
    ['PctMana'] = { Name='PctMana', Type='NetBots' },
    ['Distance3D'] = { Name='Distance3D', Type='Spawn' },
    ['CWTN.Mode'] = {
      Name='CWTN.Mode',
      Type='Observed',
      DependsOnName='Me.Class.ShortName',
      DependsOnValue='war,shd,clr,shm,mag,bst,mnk,ber,rog',
      Inverse=false,
    }
  }


Columns
Columns can have two types: Property or Button.

Property Columns


Each property column includes several settings, for example:
INI:
        ["MP%"] = {
            Name='MP%',
            Properties={caster='Me.PctMana',melee='Me.PctEndurance'}, -- The properties to be displayed in this column
            Thresholds={35,70}, -- used for coloring text, may contain 0-2 numbers to achieve default, below, inbetween or above text colors, such as green for 100% HP and red for 0% HP.
            Percentage=true, -- will add '%' symbol after the numbers shown in the column if true
            Ascending=true, -- use true to indicate that higher numbers are "better", i.e. 100% HP is better than 0%. This will be used for coloring text based on the threshold values.
            InZone=false -- use true if this column should only be populated for characters in the same zone as the one running Boxhud.
        },

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:

INI:
        ['Pause'] = {
            Name='Pause',
            Type='button',
            Action='/dex #botName# /mqp'
        },

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:

1638000055646.png



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

INI:
    {
        Name='General',
        Columns={
            {
                Name='HP%',
                ...
            }
        }
    },

Tabs can be configured directly in the HUD configuration tab:

1638000095515.png



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:

1638000215493.png


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:
1638001090958.png


3 Boxhud windows docked together as a tabbed window:
1638000870366.png


3 windows docked together vertically:
1638000887031.png



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:

1638001012645.png

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.

1638001675353.png


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
Source Repository
https://github.com/aquietone/boxhud
[git] Automation options?
Yes
Author
aquietone
First release
Last update
Rating
4.96 star(s) 27 ratings

More resources from aquietone

Share this resource

Latest updates

  1. 03/14/2024

    2.7.1 - Truncate numbers in netbots properties
  2. 01/09/2024

    2.7.0 - Add new lock/unlock button to lock window movement and save window position and size -...
  3. 12/17/2023

    Automated update: 5bd4c43540a3245b1175bdf6e25414f146969977

Latest reviews

Great clean overview, to keep track of your party. Love it!
Wonderful lua to run on the group/raid leader to keep track of so much of what your other boxes are doing. It can even live as a tab in your MQ console, to keep your UI tidy. Fantastic resource.
Don't know how I did things before this. Incredibly useful and customizable. Appreciate the great work!
This right here is easily one of the best lazy tools I've ever used, and everyone knows I LOVE being lazy.
Another Excellent Script. Very nicely done. Haven't been in to any custom settings yet, but the base script loaded up nice and works great. Thank you for your time and sharing.
So many things to like about this LUA, the invis display, managing pausing macros, seeing what macros are running, seeing when AA's need to be spent. I have had some LUA issues where my LUA will not display and I have become so accustomed to this I can't play without it.
Excellent work. Loving this hud
Very useful, thank you
Amazing work. I added some Properties, put them in columns, added the columns to tabs and Presto! Everything worked. A Must Have for boxers!
Boxhud has been extremely helpful to keep track of my team. Being able to see the xp percentages gained and the current mode of characters is extremely helpful. Boxhud has helped eliminate tabbing between windows to check the status of each character. I can make adjustments and KNOW the status of each group member on the fly with a quick glance.
Top