Mage Utility

A lightweight and intuitive addon for World of Warcraft Vanilla 1.12 that consolidates Mage teleports, portals, and mana gems into a single, efficient interface.

Features

Organized Interface: All teleports, portals, and mana gems displayed in a clean, sectioned window
Rune Counter: Real-time display of available teleportation and portal runes
Smart Spell Validation: Buttons are automatically disabled if:
- The spell is not learned
- You have insufficient reagents (shows "0" counter)
- You lack sufficient mana to cast the spell
- You are in combat (teleports and portals only)
- Real-time updates as your mana changes or combat status shifts
Smart Behavior:
- Configurable window closing behavior via constants in MageUtility.lua
- By default: Window closes after casting teleports/portals, remains open for mana gems
- Easy customization: Change MageUtility.CloseOnCast values to control each spell type
Enhanced Tooltips: Display specific error messages for disabled spells (no mana, in combat, missing reagent)
Dynamic Width: Window automatically adjusts its width based on the number of spells available
Per-Character Settings: Window position is saved individually for each character
Faction Detection: Automatically displays only spells relevant to your faction (Alliance/Horde)

Installation

Method 1: Direct Download (Recommended)

Click the green <> Code button at the top of this page
Select Download ZIP
Extract the ZIP file
Rename the folder from MageUtility-main to MageUtility (if needed)
Move the MageUtility folder to World of Warcraft/Interface/AddOns/
Restart WoW or type /reload in-game

Method 2: Git Clone

Navigate to your WoW installation folder's Interface/AddOns/ directory and run:

git clone https://github.com/YourUsername/MageUtility.git

Verification

After installation, your folder structure should look like this:

World of Warcraft/
└── Interface/
    └── AddOns/
        └── MageUtility/
            ├── MageUtility.toc
            ├── MageUtility.lua
            ├── Modules/
            │   ├── Portals.lua
            │   ├── Teleports.lua
            │   └── ManaGems.lua
            └── UI/
                └── MainFrame.lua

Common Issues:

❌ AddOns/MageUtility-main/MageUtility/ (too nested)
✅ AddOns/MageUtility/ (correct!)

Usage

Commands

/mage or /mu - Toggle the Mage Utility window

Tip: Create a macro with /mage and drag it to your action bar for quick access!

Interface Controls

The window displays three sections:

Teleports - Quick access to all learned teleportation spells
Portals - All portal spells with rune counter
Mana Gems - Conjure mana gems of all available types

Button Interactions:

Left Click: Cast the spell
Hover: Display original game tooltip with spell information and status messages
Drag Title Bar: Move the window (position is saved per character)

Each button shows:

Spell icon with the original game tooltip on hover
Reagent counter (bottom-right corner) for teleports and portals
Disabled state (grayed out) when spell cannot be cast
Status messages in tooltip explaining why a spell is disabled

Spell Validation: Buttons are automatically disabled if:

The spell is not learned
You have insufficient reagents (shows "0" counter)
You don't have enough mana to cast the spell
You are in combat (for teleports and portals only)

Default Spells

Alliance

Teleports & Portals:

Horde

Teleports & Portals:

Mana Gems (Both Factions)

Mana Agate (Level 28) - 530 mana
Mana Jade (Level 38) - 800 mana
Mana Citrine (Level 48) - 1130 mana
Mana Ruby (Level 58) - 1470 mana

Customization

Window Close Behavior

You can control whether the window closes after casting spells by editing MageUtility.lua:

-- Window close behavior constants
MageUtility.CloseOnCast = {
    TELEPORTS = true,   -- Set to false to keep window open after teleporting
    PORTALS = true,     -- Set to false to keep window open after creating portals
    MANAGEMS = false    -- Set to true to close window after conjuring gems
}

Default Behavior:

Teleports: Window closes (useful for quick travel)
Portals: Window closes (useful for quick portal creation)
Mana Gems: Window stays open (useful for conjuring multiple gems quickly)

Example Use Cases:

Set all to false if you want the window to always stay open
Set MANAGEMS = true if you only conjure one gem at a time
Mix and match based on your playstyle!

Mana Cost Configuration

The addon tracks mana costs to prevent casting spells when you don't have enough mana. There are two ways mana costs are defined:

Shared Mana Costs (Teleports & Portals)

Teleports and portals use shared constants defined in MageUtility.lua:

-- Mana cost constants
MageUtility.ManaCosts = {
    TELEPORT = 120,  -- All teleports cost 120 mana
    PORTAL = 850     -- All portals cost 850 mana
}

These constants are then referenced in each spell:

-- In Teleports.lua or Portals.lua
{
    name = "Teleport: Stormwind",
    icon = "Interface\\Icons\\Spell_arcane_teleportstormwind",
    reagent = MageUtility.Reagents.TELEPORT_RUNE,
    manaCost = MageUtility.ManaCosts.TELEPORT  -- Uses the shared constant
}

To change all teleport costs: Edit TELEPORT value in MageUtility.lua
To change all portal costs: Edit PORTAL value in MageUtility.lua

Individual Mana Costs (Mana Gems)

Mana Gems have individual costs defined directly in each spell data in ManaGems.lua:

MageUtility.ManaGems.Data = {
    {
        name = "Conjure Mana Agate",
        icon = "Interface\\Icons\\Inv_misc_gem_emerald_01",
        manaCost = 530  -- Specific cost for this gem
    },
    {
        name = "Conjure Mana Jade",
        icon = "Interface\\Icons\\Inv_misc_gem_emerald_02",
        manaCost = 800  -- Different cost
    },
    {
        name = "Conjure Mana Citrine",
        icon = "Interface\\Icons\\Inv_misc_gem_opal_01",
        manaCost = 1130
    },
    {
        name = "Conjure Mana Ruby",
        icon = "Interface\\Icons\\Inv_misc_gem_ruby_01",
        manaCost = 1470
    }
}

To change a specific gem's cost: Edit the manaCost value directly in that gem's data.

Adding Mana Costs to Custom Spells

When adding new spells, you can use either approach:

Option 1: Use a shared constant (recommended for spell groups)

-- First, add to MageUtility.lua if needed
MageUtility.ManaCosts = {
    TELEPORT = 120,
    PORTAL = 850,
    MY_CUSTOM_SPELL = 500  -- Your new constant
}

-- Then reference it in your spell
{
    name = "My Custom Spell",
    icon = "Interface\\Icons\\Spell_custom",
    manaCost = MageUtility.ManaCosts.MY_CUSTOM_SPELL
}

Option 2: Define inline (for unique spells)

{
    name = "My Unique Spell",
    icon = "Interface\\Icons\\Spell_unique",
    manaCost = 650  -- Directly specified
}

Note: The manaCost field is optional. If omitted, the spell won't check for mana requirements.

Adding New Spells

The addon is designed to be easily extensible. You can add new spells by editing the data files located in the Modules/ directory.

Adding a New Teleport

Edit Modules/Teleports.lua:

Alliance = {
    -- Existing teleports...
    {
        name = "Teleport: Moonglade",
        icon = "Interface\\Icons\\Spell_arcane_teleportmoonglade",
        reagent = MageUtility.Reagents.TELEPORT_RUNE,  -- Recommended: use predefined constant
        manaCost = MageUtility.ManaCosts.TELEPORT  -- Uses shared constant (120 mana)
    }
}

Alternative: You can also define the reagent inline:

Alliance = {
    -- Existing teleports...
    {
        name = "Teleport: Moonglade",
        icon = "Interface\\Icons\\Spell_arcane_teleportmoonglade",
        reagent = {
            id = 17031,  -- Rune of Teleportation
            name = "Rune of Teleportation",
            count = 1
        },
        manaCost = MageUtility.ManaCosts.TELEPORT
    }
}

Adding a New Portal

Edit Modules/Portals.lua:

Horde = {
    -- Existing portals...
    {
        name = "Portal: Silvermoon",
        icon = "Interface\\Icons\\Spell_arcane_portalsilvermoon",
        reagent = MageUtility.Reagents.PORTAL_RUNE,  -- Recommended: use predefined constant
        manaCost = MageUtility.ManaCosts.PORTAL  -- Uses shared constant (850 mana)
    }
}

Alternative: You can also define the reagent inline:

Horde = {
    -- Existing portals...
    {
        name = "Portal: Silvermoon",
        icon = "Interface\\Icons\\Spell_arcane_portalsilvermoon",
        reagent = {
            id = 17032,  -- Rune of Portals
            name = "Rune of Portals",
            count = 1
        },
        manaCost = MageUtility.ManaCosts.PORTAL
    }
}

Adding a New Mana Gem

Edit Modules/ManaGems.lua:

MageUtility.ManaGems.Data = {
    -- Existing gems...
    {
        name = "Conjure Mana Diamond",
        icon = "Interface\\Icons\\Inv_misc_gem_diamond_01",
        manaCost = 1800  -- Individual cost defined here
    }
}

Predefined Reagents (available in MageUtility.lua):

MageUtility.Reagents.TELEPORT_RUNE - Rune of Teleportation (ID: 17031)
MageUtility.Reagents.PORTAL_RUNE - Rune of Portals (ID: 17032)

Using predefined constants is recommended for consistency and easier maintenance.

Field Explanations:

name: The exact spell name as shown in your spellbook (case-sensitive)
icon: The game texture path for the spell icon
- Look at existing examples in Modules/ files for the correct format
- Icon names can be found on Wowhead Classic - check the spell's page and look for the icon file name
- Common path format: Interface\\Icons\\Spell_arcane_teleportironforge
- Use double backslashes \\ in the path
- Icon paths are not case-sensitive in Vanilla, but use the exact name from Wowhead for consistency
reagent (optional):
- id: The item ID from Wowhead (found in URL: wowhead.com/classic/item=17031)
- name: The readable item name for tooltip display
- count: How many reagents are consumed per spell cast
manaCost (optional):
- For Teleports/Portals: Use MageUtility.ManaCosts.TELEPORT or MageUtility.ManaCosts.PORTAL
- For Mana Gems: Specify the exact mana cost as a number
- If omitted, no mana validation will be performed for that spell

Notes:

The spell name must exactly match the in-game spellbook name (including colons and capitalization).
icon should use a valid texture path from the WoW client.
Reagent info is optional for conjured or reagent-free spells (like mana gems).
The window width automatically adjusts to accommodate additional spells in each section.

Technical Details

Dynamic Width Calculation: The window width is calculated based on the section with the most spells (formula: max_buttons * 50 + padding)
Per-Character Storage: Uses SavedVariablesPerCharacter to store window position independently for each character
Efficient Bag Scanning: Reagent counts are updated on BAG_UPDATE events to minimize performance impact
Real-time Mana Tracking: Mana availability updates on UNIT_MANA events
Combat Detection: Uses PLAYER_REGEN_DISABLED and PLAYER_REGEN_ENABLED events to track combat state
No Cooldown Tracking: Simplified code as these spells have no cooldowns in Vanilla
Original Tooltips: Displays the authentic in-game spell tooltips via spellbook lookup using GetSpellID()
Enhanced Status Messages: Tooltips show specific reasons why spells are disabled

File Structure

MageUtility/
├── MageUtility.toc          # Addon manifest (defines load order)
├── MageUtility.lua           # Core initialization and utilities
├── Modules/
│   ├── Portals.lua          # Portal spell definitions
│   ├── Teleports.lua        # Teleport spell definitions
│   └── ManaGems.lua         # Mana gem spell definitions
└── UI/
    └── MainFrame.lua        # UI rendering and interaction logic

Troubleshooting

The window doesn't appear:

Check if the addon is enabled in the AddOns menu at character selection
Try /reload to refresh the UI
Verify the folder structure is correct: Interface/AddOns/MageUtility/

Buttons are grayed out:

Make sure you've learned the spell from your class trainer
Check if you have Rune of Teleportation or Rune of Portals in your bags
Verify you have enough mana to cast the spell
Ensure you're not in combat (for teleports and portals)
Verify you're the correct level for the spell (see level requirements above)
Hover over the button to see the specific reason in the tooltip

Window position resets:

The position is saved per character in SavedVariables
Make sure you exit the game properly (not Alt+F4) to save settings
The /reload command will reload but keep your saved position

Reagent counter shows "0" but I have runes:

Try closing and reopening your bags to trigger a BAG_UPDATE event
Type /reload to force a reagent count refresh

Buttons don't update when my mana changes:

Make sure the window is open when your mana changes
Try /reload if the issue persists
Check that you're running WoW 1.12.x (the addon uses UNIT_MANA events)

Requirements

Game Version: World of Warcraft 1.12.x (Vanilla)
Dependencies: None (standalone addon)

Known Limitations

Only works with WoW Vanilla 1.12.x
Spell names must match exactly as they appear in the spellbook
Icons must use valid texture paths from the game client
Does not support spell ranks or alternative versions

Changelog

v1.2.0

Mana Cost Validation: Buttons now disable when you lack sufficient mana
Combat Detection: Teleports and portals are disabled during combat
Real-time Updates: Spell availability updates dynamically with mana changes and combat state
Enhanced Tooltips: Added specific error messages for disabled spells (no mana, in combat, missing reagent)
New Events: Added UNIT_MANA, PLAYER_REGEN_DISABLED, and PLAYER_REGEN_ENABLED event handling
Mana Cost Configuration: Added MageUtility.ManaCosts constants for easier customization
Improved User Feedback: Visual and tooltip feedback for all spell status conditions

v1.1.0

Added configurable window close behavior via MageUtility.CloseOnCast constants
Users can now customize whether the window closes after casting Teleports, Portals, or Mana Gems
Improved code maintainability with centralized configuration

v1.0.0

Initial release
Support for all Vanilla teleports and portals (Alliance & Horde)
Mana gem conjuration interface
Real-time reagent tracking
Per-character saved window positions
Dynamic window width adjustment

❤️Donations

Donations are always greatly appreciated. Thank you for your support!

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
Modules		Modules
UI		UI
LICENSE		LICENSE
MageUtility.lua		MageUtility.lua
MageUtility.toc		MageUtility.toc
README.md		README.md

License

Devilquest/MageUtility

Folders and files

Latest commit

History

Repository files navigation