Skip to content

AddonChatter and SlashHelp Chat Utilities

Jump to bottom
Shadowfen edited this page Jul 30, 2026 · 14 revisions

Why Use addonChatter?

ESO addons frequently need to:

  • Print status messages to the chat window.
  • Display debug information during development.
  • Provide slash command help.
  • Maintain consistent colors and formatting.
  • Label their addon's chat messages with an addon identifier (as a prefix).

addonChatter centralizes these tasks so every addon does not need its own chat wrapper.

Recommended Usage

Purpose Function
User-visible messages systemMessage()
Frequent developer tracing d()
Explicit debug messages debugMsg()
Turn debugging on enableDebug()
Turn debugging off disableDebug()
Toggle debugging toggleDebug()
Display command help slashHelp()

addonChatteris designed so debug statements can remain in addon code while having almost no cost when debugging is disabled.

sfutil.addonChatter

addonChatter is a lightweight chat message and debug output helper for ESO addons.

It provides:

  • Consistent addon message prefixes.
  • Colored normal messages.
  • Colored debug messages.
  • Runtime enabling and disabling of debug output.
  • Slash command help display formatting.

addonChatter avoids repeated debug condition checks by replacing the debug function with an empty function when debugging is disabled.

Creating an addonChatter Object

sfutil.addonChatter:New(addonName)

Creates a new addon chat handler.

Syntax

local chat = sfutil.addonChatter:New(addonName)

Parameters

Parameter Description
addonName Name displayed in the chat message prefix.

Returns

A new addonChatter object.

Example

local chat = sfutil.addonChatter:New("MyAddon")

The object is initialized with:

Property Default
namecolor sfutil.hex.goldenrod
normalcolor sfutil.hex.mocassin
debugcolor sfutil.hex.ltskyblue
isdbgon false

Message Functions

sfutil.addonChatter:systemMessage(...)

Displays a normal addon message in ESO chat.

The message automatically receives the addon prefix and normal message color.

Syntax

chat:systemMessage(...)

Example

chat:systemMessage("Settings loaded.")

Output:

[MyAddon] Settings loaded.

sfutil.addonChatter:debugMsg(...)

Displays a debug message if debugging is enabled.

Debug messages are discarded without formatting or chat output.

Syntax

chat:debugMsg(...)

Example

chat:debugMsg("Loading profile:", profileName)

Debug Control

sfutil.addonChatter:enableDebug()

Enables debug output.

After calling this function:

chat.d(...)

will output debug messages.

Example

chat:enableDebug()

chat:debugMsg("Debug mode enabled.")

sfutil.addonChatter:disableDebug()

Disables debug output.

Debug messages are discarded while disabled.

Example

chat:disableDebug()

sfutil.addonChatter:toggleDebug()

Toggles the current debug state.

If debugging is enabled, it is disabled.

If debugging is disabled, it is enabled.

Example

chat:toggleDebug()

sfutil.addonChatter:isDebugEnabled()

Returns the current debug state.

Syntax

local enabled = chat:isDebugEnabled()

Returns

Value Meaning
true Debug output enabled.
false Debug output disabled.

Example

if chat:isDebugEnabled() then
    chat:debugMsg("Verbose logging active.")
end

sfutil.addonChatter:getDebugState()

Returns the debug state as a string.

Syntax

local state = chat:getDebugState()

Returns

Either:

"true"

or

"false"

This is useful when displaying the state in chat or UI controls.

Color Configuration

addonChatter supports customizing the colors used for:

  • Addon prefix text.
  • Normal messages.
  • Debug messages.

Normal Message Color

sfutil.addonChatter:setNormalColor(hexColor)

Changes the color used for normal messages.

Example

chat:setNormalColor(sfutil.hex.white)

Debug Message Color

sfutil.addonChatter:setDebugColor(hexColor)

Changes the color used for debug messages.

Example

chat:setDebugColor(sfutil.hex.orange)

Prefix Color

The prefix color is set during initialization but can be changed by rebuilding the prefix

chat.prefix = sfutil.initSystemMsgPrefix(
    "MyAddon",
    color
)

Direct Debug Function

The object contains a shortcut debug function:

chat.d(...)

When debugging is disabled:

chat.d(...)

does nothing.

When debugging is enabled:

chat.d(...)

outputs a colored debug message.

This allows performance-sensitive code to avoid repeatedly checking the debug state.

Example:

chat.d("Current value:", value)

instead of:

if chat:isDebugEnabled() then
    chat:debugMsg("Current value:", value)
end

Typical Usage Pattern

A common addon pattern is:

local chat = sfutil.addonChatter:New("MyAddon")

chat:systemMessage("Initialized.")

chat:enableDebug()

chat.d("Loading saved variables.")

For production releases:

chat:disableDebug()

No additional checks are required because debug calls become no-ops.

Design Notes

addonChatter uses a function replacement technique for debug output:

Disabled:

self.d = function(...)
end

Enabled:

self.d = function(...)
    -- output message
end

This avoids a conditional check every time a debug message is generated.

This makes addonChatter suitable for addons where debug calls remain in production code but should have minimal runtime overhead.

Design Notes

Debug Performance

addonChatter avoids unnecessary debug checks by replacing the debug function itself.

Disabled:

chat.d = function()
end

Enabled:

chat.d = function(...)
    -- send debug message
end

This makes it inexpensive to leave debug statements in production code.

Slash Command Help

Typical Usage

Most addons register a primary slash command:

/myaddon

The command handler checks the requested subcommand:

/myaddon help
/myaddon reset
/myaddon debug

When no valid command is supplied, display help using slashHelp().

Purpose

slashHelp() displays a formatted list of addon slash commands in the ESO chat window.

It provides a simple way for an addon to present its available commands to users without each addon needing to implement its own formatting, coloring, and chat output handling.

Typical uses include:

  • Responding to a /addon help command.
  • Displaying available addon commands.
  • Providing in-game command documentation.
  • Keeping command descriptions consistent with addon chat formatting.

Syntax

chat:slashHelp(title, cmdstable)

Parameters

Parameter Type Description
title string Title displayed above the command list.
cmdstable table Table containing slash command definitions.

Command Table Format

The command table should contain entries in the following format:

{
    command,
    description
}

Example:

local commands =
{
    {"/myaddon help", "Display available commands"},
    {"/myaddon reset", "Reset settings"},
    {"/myaddon debug", "Toggle debug mode"},
}

Each entry contains:

Index Description
[1] Slash command text.
[2] Description displayed to the user.

Basic Example

local chat = sfutil.addonChatter:New("MyAddon")

local commands =
{
    {"/myaddon help", "Show this help message"},
    {"/myaddon reload", "Reload saved variables"},
    {"/myaddon reset", "Restore defaults"},
}

chat:slashHelp("MyAddon Commands", commands)

Output:

[MyAddon] MyAddon Commands

/myaddon help = Show this help message
/myaddon reload = Reload saved variables
/myaddon reset = Restore defaults

Using ESO Localization Strings

The description field may contain an ESO string ID instead of a text string.

Example:

local commands =
{
    {"/myaddon help", SI_MYADDON_HELP},
    {"/myaddon reset", SI_MYADDON_RESET},
}

When the description is a number, slashHelp() automatically converts it using:

GetString(description)

This allows command descriptions to support localization.

Example Slash Command Handler

A typical addon implementation:

local HELP_COMMANDS =
{
    {"/myaddon help", "Show available commands"},
    {"/myaddon debug", "Toggle debug messages"},
    {"/myaddon reset", "Reset settings"},
}


SLASH_COMMANDS["/myaddon"] = function(command)

    if command == "help" then

        chat:slashHelp(
            "MyAddon Commands",
            HELP_COMMANDS
        )

    elseif command == "debug" then

        chat:toggleDebug()

    elseif command == "reset" then

        ResetSettings()

    else

        chat:slashHelp(
            "MyAddon Commands",
            HELP_COMMANDS
        )

    end
end

Users can then enter:

/myaddon help

to display the command list.

Internal Behavior

slashHelp() performs the following operations:

  1. Displays the supplied title using systemMessage().
  2. Iterates through the command table.
  3. Formats each command entry.
  4. Applies command and description colors.
  5. Sends each line to ESO chat.

Conceptually:

for _, command in pairs(cmdstable) do
    display(
        command[1],
        command[2]
    )
end

Formatting

Each command line is formatted as:

command = description

The command portion uses the command color:

sfutil.hex.teal

The description uses the normal message color:

self.normalcolor

Recommended Usage Pattern

Define the command list once and reuse it:

local COMMANDS =
{
    {"/myaddon help", SI_MYADDON_HELP},
    {"/myaddon config", SI_MYADDON_CONFIG},
    {"/myaddon reset", SI_MYADDON_RESET},
}

Then:

chat:slashHelp(
    "MyAddon Commands",
    COMMANDS
)

This keeps the slash command implementation and user documentation synchronized.

Benefits

Consistent Appearance

All help output uses the same addon prefix and color scheme.

Localization Support

Command descriptions can use ESO string IDs.

Easy Maintenance

Adding a new command only requires adding another table entry.

Example:

{
    "/myaddon export", "Export settings"
}

No additional formatting code is required.

###Localization Support

Descriptions may use ESO string IDs.

Example:

local commands =
{
    {
        "/myaddon help",
        SI_MYADDON_HELP
    }
}

When a description is numeric, slashHelp() automatically calls:

GetString(description)

This allows command descriptions to be translated.

Recommended Slash Command Pattern

local HELP_COMMANDS =
{
    {"/myaddon help", "Show help"},
    {"/myaddon debug", "Toggle debug mode"},
    {"/myaddon reset", "Reset settings"},
}


SLASH_COMMANDS["/myaddon"] =
function(command)

    if command == "help" then

        chat:slashHelp(
            "MyAddon Commands",
            HELP_COMMANDS
        )

    elseif command == "debug" then

        chat:toggleDebug()

    else

        chat:slashHelp(
            "MyAddon Commands",
            HELP_COMMANDS
        )

    end
end

Notes

  • slashHelp() expects each command entry to contain at least two values.
  • The command table may contain any number of entries.
  • Descriptions may be normal strings or ESO string IDs.
  • Commands are displayed in the iteration order returned by pairs(). If a fixed display order is required, use an array and ipairs() instead.

Clone this wiki locally