Icons Helper

Overview

The Icons Helper is a utility library that simplifies loading and displaying World of Warcraft icons. It automatically fetches icons from Wowhead's CDN by name, caches them to disk for fast subsequent loads, and handles all the complexity of HTTP requests and texture management.

Key Features:

• Icon by Name - Load any WoW icon using its Wowhead slug (e.g., "classicon-warlock")
• Automatic Disk Caching - Icons are saved locally after first download
• Multiple Sizes - Support for large, medium, and small icon sizes
• World Position Support - Pass vec3 world coordinates with automatic screen conversion
• Format Fallback - Automatically tries PNG and JPG formats
• Throttled Downloads - Built-in rate limiting to avoid overwhelming the CDN

Higher-Level Alternative

For the easiest experience, consider using the IZI SDK Graphics module which wraps this helper with additional convenience functions.

Importing The Module

---@type icons_helper
local icons = require("common/utility/icons_helper")

Method Access

Access functions with : (colon), not . (dot). Static members like cache and constants use . (dot).

---

Functions

icons:draw_icon

Syntax

icons:draw_icon(
    icon_name_or_url: string,
    position: vec2|vec3,
    width: number,
    height: number,
    tint?: color,
    is_for_window?: boolean,
    opts?: icons_helper_draw_opts
): boolean

Parameters

Parameter	Type	Default	Description
icon_name_or_url	string	Required	Wowhead icon slug or direct URL
position	vec2|vec3	Required	Screen position (vec2) or world position (vec3)
width	number	Required	Draw width in pixels
height	number	Required	Draw height in pixels
tint	color	White	Optional color tint
is_for_window	boolean	false	Set true if drawing inside a custom window
opts	icons_helper_draw_opts	nil	Optional drawing options

Returns

• boolean - True if the icon was drawn successfully

Description

Draws a WoW icon at the specified position. The icon is identified by its Wowhead slug name (the part after /icon/ in Wowhead URLs). On first call, the icon is downloaded from Wowhead's CDN and cached locally. Subsequent calls use the cached version.

Icon Name Format

Icon names use the Wowhead slug format:

• Class icons: classicon-warrior, classicon-paladin, classicon-warlock, etc.
• Spell icons: spell_fire_fireball02, ability_warrior_charge, etc.
• Item icons: inv_sword_04, inv_helmet_plate_raidwarrior_i_01, etc.

You can find icon names by browsing Wowhead's icon database - the slug is the last part of the URL.

Example Usage

local vec2 = require("common/geometry/vector_2")
local icons = require("common/utility/icons_helper")
local color = require("common/color")

local function on_render()
    icons:draw_icon(
        "classicon-warlock",     -- Icon name (Wowhead slug)
        vec2.new(30, 30),        -- Screen position
        64, 64,                  -- Size
        color.white(255),        -- Tint
        false,                   -- Not in a window
        {
            size = "large",      -- Icon size
            persist_to_disk = true
        }
    )
end

core.register_on_render_callback(on_render)

---

icons:clear_cache

Syntax

icons:clear_cache(): nil

Description

Clears the in-memory icon cache. Does not delete disk-cached icons. Useful if you need to force re-download of icons.

Example Usage

local icons = require("common/utility/icons_helper")

-- Clear memory cache (disk cache remains)
icons:clear_cache()

---

Constants

The icons helper exposes several constants:

Constant	Type	Description
ZAMIMG_BASE	string	Base URL for Wowhead's icon CDN
DEFAULT_SIZE	string	Default icon size ("large")
DEFAULT_DISK_CACHE_FOLDER	string	Default cache folder ("cache\\wowhead_icons")
DEFAULT_HTTP_THROTTLE_SECONDS	number	Delay between HTTP requests
DEFAULT_PROBE_THROTTLE_SECONDS	number	Delay between cache probes

---

Types

icons_helper_draw_opts

Options for customizing icon drawing behavior.

{
    size?: string,              -- "large" | "medium" | "small"
    persist_to_disk?: boolean,  -- Save to disk cache (default: true)
    disk_cache_folder?: string  -- Custom cache folder path
}

Field	Type	Default	Description
size	string	"large"	Icon size: "large" (56px), "medium" (36px), or "small" (18px)
persist_to_disk	boolean	true	Whether to save downloaded icons to disk
disk_cache_folder	string	"cache\\wowhead_icons"	Folder in scripts_data/ for disk cache

icons_helper_icon_entry

Internal cache entry for icons.

Field	Type	Description
key	string	Cache key
name	string	Icon name
size	string	Icon size
url_jpg	string	JPG download URL
url_png	string	PNG download URL
tex_id	integer|nil	GPU texture ID
w	integer|nil	Texture width
h	integer|nil	Texture height
requested	boolean	True if download initiated
error	string|nil	Error message if failed
dead	boolean	True if loading failed permanently

---

Complete Examples

Example 1: Basic Icon Drawing

local vec2 = require("common/geometry/vector_2")
local icons = require("common/utility/icons_helper")
local color = require("common/color")

local function on_render()
    -- Draw a warlock class icon
    icons:draw_icon(
        "classicon-warlock",
        vec2.new(30, 30),
        64, 64,
        color.white(255),
        false,
        {
            size = "large",
            persist_to_disk = true
        }
    )
end

core.register_on_render_callback(on_render)

Example 2: World Position Icon

local vec3 = require("common/geometry/vector_3")
local icons = require("common/utility/icons_helper")

local function on_render()
    -- Draw icon at a 3D world position (auto world-to-screen)
    local world_pos = vec3.new(123.0, 456.0, 78.0)
    icons:draw_icon(
        "classicon-warlock",
        world_pos,
        32, 32
    )
end

core.register_on_render_callback(on_render)

Example 3: Multiple Class Icons

local vec2 = require("common/geometry/vector_2")
local icons = require("common/utility/icons_helper")
local color = require("common/color")

local class_icons = {
    "classicon-warrior",
    "classicon-paladin",
    "classicon-hunter",
    "classicon-rogue",
    "classicon-priest",
    "classicon-deathknight",
    "classicon-shaman",
    "classicon-mage",
    "classicon-warlock",
    "classicon-monk",
    "classicon-druid",
    "classicon-demonhunter",
    "classicon-evoker"
}

local function on_render()
    for i, icon_name in ipairs(class_icons) do
        local x = 30 + ((i - 1) % 5) * 40
        local y = 30 + math.floor((i - 1) / 5) * 40
        
        icons:draw_icon(
            icon_name,
            vec2.new(x, y),
            36, 36,
            color.white(255),
            false,
            { size = "medium" }
        )
    end
end

core.register_on_render_callback(on_render)

Example 4: Spell Icons for Rotation Display

local vec2 = require("common/geometry/vector_2")
local icons = require("common/utility/icons_helper")
local color = require("common/color")

-- Common mage spell icons
local spell_icons = {
    { name = "spell_fire_fireball02", label = "Fireball" },
    { name = "spell_fire_firebolt02", label = "Fire Blast" },
    { name = "ability_mage_hotstreak", label = "Hot Streak" },
    { name = "spell_fire_flamebolt", label = "Pyroblast" },
}

local function on_render()
    local base_x, base_y = 100, 100
    
    for i, spell in ipairs(spell_icons) do
        local x = base_x + (i - 1) * 50
        
        -- Draw icon
        icons:draw_icon(
            spell.name,
            vec2.new(x, base_y),
            44, 44,
            color.white(255),
            false,
            { size = "large" }
        )
    end
end

core.register_on_render_callback(on_render)

---

Finding Icon Names

To find the correct icon name for a spell, item, or ability:

1. Go to Wowhead
2. Search for the spell/item/ability
3. Look at the icon on the page
4. Right-click the icon and "Copy image address"
5. The icon name is the last part of the URL (before the extension)

For example:

• URL: https://wow.zamimg.com/images/wow/icons/large/spell_fire_fireball02.jpg
• Icon name: spell_fire_fireball02

Alternatively, browse the Wowhead Icon Database to search icons by name.