Skip to content

README.md

Latest commit

 

History

History
284 lines (213 loc) · 7.24 KB

README.md

File metadata and controls

284 lines (213 loc) · 7.24 KB
Raw

🎨 WotLK Atlas System

Bring Retail's Atlas API to WotLK 3.3. 5a

License: AGPL v3 WoW Version Made with Lua PRs Welcome

Stop hardcoding texture coordinates. Start using atlases like it's 2026.

Features • Installation • Usage • API • Contributing

🤔 The Problem

Ever written code like this?

texture:SetTexture("Interface\\Glues\\CharacterCreate\\UI-CharacterCreate-Classes")
texture:SetTexCoord(0, 0.25, 0, 0.25)  -- warrior...  I think?  🤷
texture:SetSize(64, 64)

Yeah, we've all been there. It's 2026 and we're still manually calculating texture coordinates like it's 2004.

✨ The Solution

SetAtlas(texture, "class-warrior", true)

That's it. One line. Clean, readable, maintainable.

🚀 Features

🎯 Simple API

SetAtlas(texture, "class-mage", true)

🌐 Universal

Works in FrameXML and GlueXML

📦 Installation

Quick Start

  • Download the latest release
  • Copy AtlasHelper.lua and AtlasInfo.lua to Interface/FrameXML/
  • Add to your FrameXML.toc, AtlasHelper.lua and AtlasInfo.lua
  • Reload UI (/reload)

Installation structure

World of Warcraft/
└── Data/
    └── Patch-{4-9/a-z}.MPQ/
        └── Interface/
            ├── FrameXML/
            │   ├── FrameXML.toc          ← Add atlas files here
            │   ├── AtlasHelper.lua       ← Copy this
            │   └── AtlasInfo.lua         ← Copy this
            └── GlueXML/
                ├── GlueXML. toc          ← (Optional) For login screen
                ├── AtlasHelper.lua       ← Copy if using Glue
                └── AtlasInfo.lua         ← Copy if using Glue

💡 Usage

Lua Example

local frame = CreateFrame("Frame", nil, UIParent)
frame:SetSize(128, 128)
frame:SetPoint("CENTER")

local texture = frame:CreateTexture(nil, "ARTWORK")
texture:SetAllPoints()

-- ✨ Magic happens here
SetAtlas(texture, "groupfinder-icon-class-warrior", true)

frame:Show()

XML Example

<Frame name="MyFrame" parent="UIParent">
    <Size x="400" y="300"/>
    <Anchors>
        <Anchor point="CENTER"/>
    </Anchors>
    <Layers>
        <Layer level="ARTWORK">
            <Texture name="$parentIcon" parentKey="Icon">
                <Size x="64" y="64"/>
                <Anchors>
                    <Anchor point="CENTER"/>
                </Anchors>
            </Texture>
        </Layer>
    </Layers>
    <Scripts>
        <!-- 🔥 New way -->
        <OnLoad>
            SetAtlas(self.Icon, "class-warrior", true)
        </OnLoad>
    </Scripts>
</Frame>

⚠️ Important Note

The file="atlas:name" attribute syntax does NOT work in XML files due to WoW's XML parser creating textures before Lua hooks are installed.

Always use SetAtlas() in OnLoad scripts for XML-defined textures.

🛠️ API Reference

C_Texture.LoadAtlasData(atlasTable)

Loads atlas coordinate data.

Parameters:

  • atlasTable (table) - Atlas data structure

Returns:

  • (number) - Number of atlases loaded

Example:

local myAtlases = {
    ["Interface/MyAddon/Icons"]={
        ["my-icon"]={64, 64, 0, 1, 0, 1, false, false, "1x"},
    },
}

C_Texture.LoadAtlasData(myAtlases)  -- Returns:  1

C_Texture.GetAtlasInfo(name)

Gets atlas metadata.

Parameters:

  • name (string) - Atlas name (case-insensitive)

Returns:

  • (table|nil) - Atlas info or nil if not found

Example:

local info = C_Texture.GetAtlasInfo("class-mage")
--[[
{
    width = 256,
    height = 256,
    left = 0. 25,
    right = 0.5,
    top = 0,
    bottom = 0.25,
    file = "Interface/Glues/CharacterCreate/UI-CharacterCreate-Classes"
}
]]

C_Texture.SetAtlas(texture, name, useSize)

Applies atlas to a texture.

Parameters:

  • texture (Texture) - Texture object
  • name (string) - Atlas name
  • useSize (boolean) - Auto-resize to atlas dimensions

Returns:

  • (boolean) - Success status

Example:

SetAtlas(myTexture, "class-warrior", true)  -- Returns: true

📚 Atlas Data Format

Atlas definitions follow Retail's format:

["path/to/texture/file"]={
    ["atlas-name"]={width, height, left, right, top, bottom, tilesH, tilesV, scale},
}

Parameters

Index Name Type Description
1 width number Atlas width in pixels
2 height number Atlas height in pixels
3 left number Left UV coordinate (0-1)
4 right number Right UV coordinate (0-1)
5 top number Top UV coordinate (0-1)
6 bottom number Bottom UV coordinate (0-1)
7 tilesH boolean Tiles horizontally
8 tilesV boolean Tiles vertically
9 scale string Texture scale ("1x", "2x")

Example

["Interface/Glues/CharacterCreate/UI-CharacterCreate-Classes"]={
    ["class-warrior"]={256, 256, 0, 0.25, 0, 0.25, false, false, "1x"},
    ["class-mage"]={256, 256, 0.25, 0.5, 0, 0.25, false, false, "1x"},
}

🤝 Contributing

We love contributions!

🐛 Found a bug?

Open an issue

💡 Have an idea?

Open an issue (yes, again)

🔨 Want to code?

  1. Fork the repo
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📜 License

🆓 Code (AGPL-3.0)

All original code is licensed under AGPL-3.0.

🎮 Data (Blizzard)

Atlas coordinate data is extracted from WoW and remains property of Blizzard Entertainment.

Source: Townlong Yak

🙏 Credits

Who What
🎮 Blizzard Entertainment Original atlas system & data
📚 Townlong Yak FrameXML extraction & docs
👨‍💻 iThorgrim WotLK port & implementation

⚠️ Disclaimer

This project is not affiliated with, endorsed by, or supported by Blizzard Entertainment. World of Warcraft® and Blizzard Entertainment® are registered trademarks of Blizzard Entertainment, Inc.

Use at your own risk. This is a community project for educational purposes.

💖 Made with love for the WotLK community

⬆ Back to top

*If this project helped you, consider giving it a ⭐! *