### Test Aurora Functions and Get Unit Info with WowLua

Source: https://docs.aurora-wow.wtf/getting-started/recommended-addons

Provides an example of using the WowLua addon to test Lua code snippets. This snippet retrieves player and target information, then prints their health and distance to each other, demonstrating in-game code execution and basic WoW API interaction.

```lua
local player = Aurora.UnitManager:Get("player")
local target = Aurora.UnitManager:Get("target")

print("Player Health: " .. player.health)
print("Target Distance: " .. target.distanceto(player))
```

--------------------------------

### Access Registered Spells, Auras, and Talents (Lua)

Source: https://docs.aurora-wow.wtf/getting-started/spells

This code shows how to access the spells, auras, and talents previously registered with the Aurora Spell System. It retrieves them from the global 'Aurora.SpellHandler.Spellbooks' table, specifying the class, spec ID, and namespace. This allows for easy programmatic access to defined abilities.

```lua
local spells = Aurora.SpellHandler.Spellbooks.warrior["3"].YourNamespace.spells  
local auras = Aurora.SpellHandler.Spellbooks.warrior["3"].YourNamespace.auras  
local talents = Aurora.SpellHandler.Spellbooks.warrior["3"].YourNamespace.talents  

```

```lua
local spells = Aurora.SpellHandler.Spellbooks.priest["1"].YourNamespace.spells  
local auras = Aurora.SpellHandler.Spellbooks.priest["1"].YourNamespace.auras  
local talents = Aurora.SpellHandler.Spellbooks.priest["1"].YourNamespace.talents  

```

--------------------------------

### Example Alerts with Icons and Sound in Lua

Source: https://docs.aurora-wow.wtf/alert/Alert%20Basics

Provides practical examples of using Aurora.alert for common scenarios such as proc alerts, custom duration messages, and level-up notifications with associated sounds. Requires the Aurora WoW addon.

```lua
-- Proc alert with spell icon
Aurora.alert("Bloodlust Active!", 2825)

-- Custom duration alert
Aurora.alert({
    string = "Boss Incoming!",
    time = 5,  -- Show for 5 seconds
}, "Interface\Icons\ability_warrior_charge")

-- Alert with sound
Aurora.alert("Level Up!", "Interface\Icons\achievement_level_80", {
    soundID = 888  -- Level up sound
})
```

--------------------------------

### Macro System API

Source: https://docs.aurora-wow.wtf/misc/Macro

This section details the core functionalities of the Macro System, including command registration and usage examples.

```APIDOC
## Macro System API

### Description
The Macro System provides a way to create and manage slash commands in the game. It allows you to register custom commands that can be executed through chat.

### Basic Usage
On first run, you'll be prompted to set a prefix via a GUI window. This preference is saved for future sessions.

```lua
local Macro = Aurora.Macro  

-- Register a simple command  
Macro:RegisterCommand("hello", function(name)  
    print("Hello, " .. (name or "stranger") .. "!")  
end, "Greets a player")  
```

## Command Registration

### RegisterCommand

#### Description
Registers a new custom slash command.

#### Method
`Macro:RegisterCommand(command, callback, description)`

#### Parameters

##### Path Parameters
* **command** (string) - Required - The name of the command to register.
* **callback** (function) - Required - The function to execute when the command is called.
* **description** (string) - Optional - A description for the command, used in help text.

### Examples

#### Basic Command

##### Description
Registers a simple 'hello' command that greets a player.

##### Code Example

```lua
-- Creates /aurora greet [name]
Macro:RegisterCommand("greet", function(name)  
    print("Hello, " .. (name or "stranger") .. "!")  
end, "Greets a player")  
```

#### Command with Arguments

##### Description
Registers a 'cast' command that allows casting a specified spell.

##### Code Example

```lua
-- Creates /aurora cast [spell]
Macro:RegisterCommand("cast", function(spell)  
    if spell then  
        Aurora.Spell:Cast(spell)  
    end  
end, "Casts the specified spell")  
```

#### Help Command

##### Description
Demonstrates how to access the built-in help command to list all registered commands and their descriptions.

##### Usage
* `/aurora` - Lists all available commands.
* `/aurora help` - Same as above.

Both commands will display a list of all registered commands with their descriptions in the format:

```
/aurora commandName - Command description  
```

## Best Practices

### Command Design
* Use clear, descriptive command names.
* Always provide a helpful description.
* Handle missing arguments gracefully.
* Keep commands simple and focused.

### Common Pitfalls
* Avoid command names that might conflict with other addons.
* Don't register commands in performance-critical code.
* Remember to handle all possible argument cases.
```

--------------------------------

### Register Spells with Aurora Spell System (Lua)

Source: https://docs.aurora-wow.wtf/getting-started/spells

This code snippet demonstrates how to register spells, auras, and talents for a specific class and specialization using Aurora's SpellHandler. It takes spell definitions, class name, spec ID, and a namespace as input. Ensure the 'NewSpell' function and 'PopulateSpellbook' are available in your Lua environment.

```lua
-- Create your spells  
local NewSpell = Aurora.SpellHandler.NewSpell  
Aurora.SpellHandler.PopulateSpellbook({
    spells = {
        AutoAttack = NewSpell(6603),
        Charge = NewSpell(100),
        ShieldSlam = NewSpell(23922),
        Ravager = NewSpell(228920, { radius = 8,}),
    },
    auras = {
        --Add Auras here  
    },
    talents = {
        --Add Talents here  
    },
}, "WARRIOR",3,"YourNamespace")  

```

--------------------------------

### Show Example Toast Notification with Dynamic Content (Lua)

Source: https://docs.aurora-wow.wtf/misc/Toast

An example of using the Toast:Show method with dynamically generated content, such as a player's name. This illustrates how to create personalized toast messages.

```lua
-- Show a welcome message
local playerName = UnitName("player")
Aurora.Toast:Show(
    string.format("Welcome, %s!", playerName),
    "Type /aurora for settings"
)
```

--------------------------------

### Aurora Keybind Format Examples

Source: https://docs.aurora-wow.wtf/hooks/keyboard

Illustrates the different formats for defining keybinds in Aurora's system, including simple keys, keys with modifiers, and mouse buttons.

```Lua
"A"                    -- Simple key  
"Shift+A"              -- Modifier + key  
"Button4"              -- Mouse button 4  
"Shift+Button5"        -- Modifier + mouse button  
"MiddleButton"         -- Middle mouse button  

```

--------------------------------

### Lua Unit and Target Management with Aurora API

Source: https://docs.aurora-wow.wtf/unit-properties/Unit%20-%20Properties

Demonstrates how to get player and target units using Aurora.UnitManager, perform basic checks like existence, enemy status, and health, and interact with target positioning and facing. It also shows how to check for specific auras, their remaining duration, stack counts, and presence from a list. Finally, it includes examples for checking casting status, interruptibility, and distance for combat actions.

```lua
-- All property accesses are actually method calls through metatables
local target = Aurora.UnitManager:Get("target")
local player = Aurora.UnitManager:Get("player")

-- Basic target checks
if target.exists and target.enemy and target.alive then
    if target.hp < 20 and target.distanceto(player) < 30 then
        -- Execute logic here
    end
end

-- Example showing type checks and positioning
if target.ishumanoid and not target.ismechanical then
    if target.playerfacing then
        -- Use frontal cone melee ability on humanoid target
    end
end

-- Aura examples
if target.exists then
    -- Check for a specific debuff
    local hasDeBuff = target.aura(12345)
    if hasDeBuff then
        local remaining = target.auraremains(12345)
        if remaining < 3 then
            -- Refresh debuff before it expires
        end
    end

    -- Check aura stacks
    local stacks = target.auracount(67890)
    if stacks >= 5 then
        -- Use ability that consumes stacks
    end

    -- Check for any aura from a list
    local auraList = {12345, 67890, 11223}
    if target.aurafrom(auraList) then
        -- Unit has at least one of the auras
    end
end

-- Combat and casting checks
if target.exists and target.casting then
    if target.castinginterruptible and target.castingpct > 50 then
        if player.distanceto(target) < 30 then
            -- Interrupt the cast
        end
    end
end

```

--------------------------------

### Draw Unit Markers Example

Source: https://docs.aurora-wow.wtf/misc/Draw

An example demonstrating how to register a callback to draw red circles around enemy units that are alive. It utilizes `Draw:GetColor` for color management and `canvas:Circle` for drawing.

```lua
Draw:RegisterCallback("unitMarkers", function(canvas, unit)
    if unit.enemy and unit.alive then
        -- Draw red circle for enemies
        local r, g, b, a = Draw:GetColor("Red", 70)
        canvas:SetColor(r, g, b, a)
        canvas:Circle(unit.position.x, unit.position.y, unit.position.z, 1)
    end
end, "units")
```

--------------------------------

### Create Directory Structure - Shell

Source: https://docs.aurora-wow.wtf/index

This command utilizes `mkdir -p` to create the necessary directory structure for your Aurora Framework project. It ensures that the `scripts/AuroraRoutines` directory is created, including any necessary parent directories, facilitating a clean and organized project layout.

```shell
mkdir -p scripts/AuroraRoutines  
```

--------------------------------

### Example: Adding Class-Specific Toggles

Source: https://docs.aurora-wow.wtf/status-frame/basic-usage

An example showcasing how to add class-specific toggles, such as 'Burst' and 'Defensive' modes, to the rotation system within the global status frame.

```Lua
    Aurora.Rotation.BurstToggle = Aurora:AddGlobalToggle({
        label = "Burst",
        var = "my_burst_toggle",
        icon = "Interface/Icons/Ability_Warrior_BattleShout",
        tooltip = "Enable burst mode rotation"
    })
    Aurora.Rotation.DefensiveToggle = Aurora:AddGlobalToggle({
        label = "Defensive",
        var = "my_defensive_toggle",
        icon = "Interface/Icons/Ability_Warrior_DefensiveStance",
        tooltip = "Use defensive cooldowns"
    })
end

if Aurora.Rotation.DefensiveToggle:GetValue() then
    -- Do Defensives
end  
```

--------------------------------

### Example: Monitor Interrupts - Lua

Source: https://docs.aurora-wow.wtf/misc/CombatLogReader

Demonstrates registering an event handler for `SPELL_INTERRUPT`. This example extracts information about who interrupted which spell cast by whom, using the `eventData.params`.

```lua
EventHandler:RegisterEvent("SPELL_INTERRUPT", function(eventData)  
    local _, _, _, extraSpellId, extraSpellName = unpack(eventData.params)  
    print(string.format("%s interrupted %s's %s",   
        eventData.source.name,
        eventData.dest.name,
        extraSpellName))
end)

```

--------------------------------

### Multiple GUI Settings Configuration

Source: https://docs.aurora-wow.wtf/interface/config-integration

An example showcasing how to configure multiple GUI elements (Checkbox, Slider, Dropdown) within categories and tabs, each with a unique 'key' for persistence. This demonstrates structured UI configuration for graphics settings.

```lua
gui:Category("Graphics")
   :Tab("Quality")
   :Checkbox({
        text = "Enable Shadows",
        key = "graphics.shadows",
        default = true
   })
   :Slider({
        text = "View Distance",
        key = "graphics.viewDistance",
        min = 1,
        max = 10,
        default = 5
   })
   :Dropdown({
        text = "Texture Quality",
        key = "graphics.textures",
        options = {
            { text = "Low", value = "low" },
            { text = "High", value = "high" }
        },
        default = "high"
   })
```

--------------------------------

### Basic Item Usage Example

Source: https://docs.aurora-wow.wtf/item-handler/item-functions

Demonstrates a practical application of item handling, specifically using a health potion when the player's health is low. It combines item creation, usability checks, and item usage in a conditional scenario.

```lua
-- Create and use a health potion
local potion = Aurora.ItemHandler.NewItem(33447)

if player.hp < 50 and potion:usable(player) then
    potion:use(player)
end
```

--------------------------------

### Example: Track Player Spells - Lua

Source: https://docs.aurora-wow.wtf/misc/CombatLogReader

An example of registering a combat log event handler for `SPELL_CAST_SUCCESS`. It specifically checks if the player is the source of the spell cast and prints the spell name and ID.

```lua
EventHandler:RegisterEvent("SPELL_CAST_SUCCESS", function(eventData)  
    if eventData.source.guid == UnitGUID("player") then  
        local spellId, spellName = unpack(eventData.params)  
        print(string.format("Cast %s (ID: %d)", spellName, spellId))
    end  
end)

```

--------------------------------

### Access Missile Unit and Target Properties

Source: https://docs.aurora-wow.wtf/missiles/properties

Retrieve information about the units associated with the missile, such as the creator unit, the target unit, and the source GUID.

```Lua
missile.creator  -- Unit that created the missile
missile.target   -- Target unit of the missile
missile.source   -- Source GUID
```

--------------------------------

### Organize Configuration Keys Hierarchically in Lua

Source: https://docs.aurora-wow.wtf/interface/config-system

Demonstrates the best practice of organizing configuration keys hierarchically using dots (.). This improves readability and maintainability compared to flat key structures. Example shows organizing healing settings for different group types.

```lua
-- Good: Organized and clear
Aurora.Config:Write("healing.tanks.minHealth", 60)
Aurora.Config:Write("healing.raid.minHealth", 80)

-- Avoid: Flat and unclear
Aurora.Config:Write("tankMinHealth", 60)
Aurora.Config:Write("raidMinHealth", 80)
```

--------------------------------

### Position and Movement Checks

Source: https://docs.aurora-wow.wtf/unit-properties/Unit%20Methods

Provides examples for checking unit positions and movement relative to other units. This includes verifying if a unit is behind another and checking distance combined with line of sight.

```Lua
local target = Aurora.UnitManager:Get("target")
local player = Aurora.UnitManager:Get("player")

-- Check if player is behind target
if player.behind(target) then
    -- Use backstab ability
end

-- Check distance and line of sight
if target.distanceto(player) < 30 and target.haslos(player) then
    -- Cast ranged ability
end
```

--------------------------------

### Register a Command with Arguments

Source: https://docs.aurora-wow.wtf/misc/Macro

Illustrates how to register a command that accepts arguments. This example shows a 'cast' command that takes a spell name and uses it to cast the spell via Aurora.Spell:Cast().

```lua
-- Creates /aurora cast [spell]
Macro:RegisterCommand("cast", function(spell)
    if spell then
        Aurora.Spell:Cast(spell)
    end
end, "Casts the specified spell")
```

--------------------------------

### Get All Configuration Settings in Lua

Source: https://docs.aurora-wow.wtf/interface/config-system

Retrieves all currently saved configuration settings. This function returns a table containing all key-value pairs of the configuration, which can then be iterated over to process all settings.

```lua
-- Get all settings
local allSettings = Aurora.Config:GetAll()
for key, value in pairs(allSettings) do
    print(key, value)
end
```

--------------------------------

### Aurora WoW Spell Casting Examples

Source: https://docs.aurora-wow.wtf/spell

Demonstrates creating spell objects for single-target spells (like Fireball) and AOE spells (like Blizzard), and then casting them. Includes checks for castability and optimal AOE positioning.

```lua
-- Create a new spell object for Fireball  
local fireball = Aurora.SpellHandler.NewSpell(133, {  
})
  
-- Check if we can cast Fireball on our target  
if fireball:castable("target") then  
    -- Cast Fireball  
    fireball:cast("target")  
end  
  
-- Create an AOE spell like Blizzard  
local blizzard = Aurora.SpellHandler.NewSpell(190356, {  
    isSkillshot = true,  
    radius = 8  
})
  
-- Cast Blizzard optimally on groups of enemies  
blizzard:smartaoe("target", {  
    offsetMax = 30,  
    filter = function(unit, distance, position)  
        return unit.enemy and not unit.dead  
    end  
})
```

--------------------------------

### Event Handler API Documentation

Source: https://docs.aurora-wow.wtf/misc/CombatLogReader

This section details the Event Handler API, including how to register combat log and normal WoW events, structure of event data, filtering capabilities, and provides examples.

```APIDOC
## Event Handler API

### Description
The Event Handler provides a streamlined way to handle both combat log events and normal WoW events. It offers filtering capabilities and structured event data.

### Basic Usage
```lua
local EventHandler = Aurora.EventHandler

-- Register a combat log event handler
EventHandler:RegisterEvent("SPELL_CAST_SUCCESS", function(eventData)
    if eventData.source.guid == UnitGUID("player") then
        print(string.format("You cast %s", C_Spell.GetSpellLink(eventData.params[1])))
    end
end)

-- Register a normal WoW event handler
EventHandler:RegisterNormalEvent("PLAYER_ENTERING_WORLD", function()
    print("Player entered the world")
end)
```

## Event Registration

### Combat Log Events
```lua
EventHandler:RegisterEvent(eventType, handlerFunction)
```
*   `eventType` (string) - Required - Combat log event type (e.g., "SPELL_CAST_SUCCESS")
*   `handlerFunction` (function) - Required - Function that receives the structured event data

### Normal Events
```lua
EventHandler:RegisterNormalEvent(eventType, handlerFunction)
```
*   `eventType` (string) - Required - WoW event name (e.g., "PLAYER_ENTERING_WORLD")
*   `handlerFunction` (function) - Required - Function that receives the raw event parameters

## Event Data Structure
Combat log events provide structured data. Example for `SPELL_CAST_SUCCESS`:
```lua
eventData = {
    timestamp = 1234567890,
    event = "SPELL_CAST_SUCCESS",
    source = {
        guid = "Player-1234-5678",
        name = "PlayerName",
        flags = sourceFlags,
        raidFlags = sourceRaidFlags
    },
    dest = {
        guid = "Target-1234-5678",
        name = "TargetName",
        flags = destFlags,
        raidFlags = destRaidFlags
    },
    params = { spellId, spellName, ... } -- Additional event-specific parameters
}
```

## Event Filtering
Add filters to process only specific events.
```lua
-- Only process events where the player is the source
EventHandler:AddFilter("SPELL_CAST_SUCCESS", function(eventData)
    return eventData.source.guid == UnitGUID("player")
end)
```
*   `eventType` (string) - Required - The combat log event type to add a filter for.
*   `filterFunction` (function) - Required - A function that takes `eventData` and returns `true` to process the event, or `false` to ignore it.

## Examples

### Track Player Spells
```lua
EventHandler:RegisterEvent("SPELL_CAST_SUCCESS", function(eventData)
    if eventData.source.guid == UnitGUID("player") then
        local spellId, spellName = unpack(eventData.params)
        print(string.format("Cast %s (ID: %d)", spellName, spellId))
    end
end)
```

### Monitor Interrupts
```lua
EventHandler:RegisterEvent("SPELL_INTERRUPT", function(eventData)
    local _, _, _, extraSpellId, extraSpellName = unpack(eventData.params)
    print(string.format("%s interrupted %s's %s",
        eventData.source.name,
        eventData.dest.name,
        extraSpellName))
end)
```

### Track Group Changes
```lua
EventHandler:RegisterNormalEvent("GROUP_ROSTER_UPDATE", function()
    print("Group composition changed")
end)
```

## Common Combat Log Events

### Spell Events
*   `"SPELL_CAST_START"` - When a spell cast begins
*   `"SPELL_CAST_SUCCESS"` - When a spell cast completes
*   `"SPELL_CAST_FAILED"` - When a spell cast fails
*   `"SPELL_AURA_APPLIED"` - When a buff/debuff is applied
*   `"SPELL_AURA_REMOVED"` - When a buff/debuff is removed
*   `"SPELL_INTERRUPT"` - When a spell is interrupted
*   `"SPELL_DISPEL"` - When a buff/debuff is dispelled

### Damage & Healing
*   `"SPELL_DAMAGE"` - Spell damage
*   `"SWING_DAMAGE"` - Melee damage
*   `"SPELL_HEAL"` - Healing
*   `"SPELL_PERIODIC_HEAL"` - HoT healing

### Unit Events
*   `"UNIT_DIED"` - When a unit dies
*   `"PARTY_KILL"` - When your party kills something

## Best Practices

### Performance
*   Use filters to reduce unnecessary event processing.
*   Keep event handlers lightweight.
*   Consider batching frequent events.
*   Clean up handlers when no longer needed.

### Common Pitfalls
*   Don't register too many handlers for the same event.
*   Be careful with string operations in high-frequency events.
*   Remember that some events fire very frequently.
*   Handle nil cases in event data.

### Event Processing Notes
*   Combat log events provide more structured data than normal events.
```

--------------------------------

### Tank Virtual Unit Resolution and Usage in Lua

Source: https://docs.aurora-wow.wtf/lists-and-units/VirtualUnits

Explains the resolution order for the 'tank' virtual unit and provides Lua code examples for checking its health and proximity to the player. It highlights how to safely interact with the tank unit.

```lua
local tank = Aurora.UnitManager.tank

-- Examples
if tank.exists then
    if tank.hp < 50 then
        -- Heal the tank
    end
      
    if tank.distanceto(player) < 40 then
        -- Stay close to tank
    end
end
```

--------------------------------

### Combining Distance Filtering and Unit Selection

Source: https://docs.aurora-wow.wtf/lists-and-units/Lists

Shows a practical application combining 'within' to get nearby enemies and 'first' to select the lowest health one for an attack. It also demonstrates using 'around' to count dangerous enemies near a tank.

```lua
-- Get enemies within melee range and attack the lowest health one  
local meleeEnemies = Aurora.activeenemies:within(5)  
local target = meleeEnemies:first(function(unit)  
    return unit.hp < 30  
end)  
  
-- Count dangerous enemies around the tank  
local dangerousCount, totalCount, dangerousEnemies = Aurora.activeenemies:around(tank, 10, function(unit)  
    return unit.casting or unit.channeling  
end)  
  
if dangerousCount > 2 then  
    print("Chuckles, im in Danger")  
end  
```

--------------------------------

### Controlling Toggle States Programmatically

Source: https://docs.aurora-wow.wtf/status-frame/basic-usage

Provides examples of how to programmatically interact with a toggle after it has been created. This includes getting its current value, setting its value, and updating its tooltip text.

```Lua
-- Get current value  
local isEnabled = myToggle:GetValue()  

-- Set value programmatically  
myToggle:SetValue(true)  

-- Update tooltip text  
myToggle:SetCustomText("New tooltip text")  
```

--------------------------------

### Configure Load Order - JSON

Source: https://docs.aurora-wow.wtf/index

This JSON configuration defines the order in which Aurora Framework routines are loaded. The file paths specified (without `.lua` extensions) dictate the execution sequence, ensuring that dependencies are met and the application initializes correctly. The framework automatically appends the `.lua` extension during loading.

```json
[
    "Main",
    "Routines/Warrior/Specialisation/Spellbook",
    "Routines/Warrior/Specialisation/Interface",
    "Routines/Warrior/Specialisation/Rotation"
]
```

--------------------------------

### Register a Basic 'hello' Command

Source: https://docs.aurora-wow.wtf/misc/Macro

Demonstrates the basic usage of the Macro system to register a simple command that prints a greeting. It shows how to provide a command name, a callback function, and an optional description.

```lua
local Macro = Aurora.Macro

-- Register a simple command
Macro:RegisterCommand("hello", function(name)
    print("Hello, " .. (name or "stranger") .. "!")
end, "Greets a player")
```

--------------------------------

### Callback Management and Best Practices

Source: https://docs.aurora-wow.wtf/functions/Frame

Guidelines for managing callbacks, including enabling/disabling, performance optimization, and memory management.

```APIDOC
## Callback Management and Best Practices

### Performance Optimization
- **Use `OnUpdate` for Non-Critical Operations**: Suitable for interface updates, status checks, and data collection.
- **Use `OnTick` for Time-Sensitive Operations**: Ideal for cast tracking, interrupt timing, and precise rotation logic.
- **Enable/Disable Callbacks as Needed**: Register callbacks with `enabled = false` and enable them only when necessary to conserve resources.

### Memory Management
- **Remove Unused Callbacks**: Always remove callbacks that are no longer needed using `Aurora:RemoveCallback` to prevent memory leaks.

### Notes
- Avoid excessive processing in update callbacks. Keep operations light and efficient to prevent frame rate drops.

### Example: Enabling/Disabling Callbacks
```lua
-- Store callback reference
local myCallbackId

-- Register with disabled state
myCallbackId = Aurora:OnUpdate(function(elapsed)
    -- Heavy processing here
end, false)

-- Enable only when needed
if inCombat then
    Aurora.updateCallbacks[myCallbackId].enabled = true
else
    Aurora.updateCallbacks[myCallbackId].enabled = false
end
```

### Example: Removing Callbacks
```lua
-- When a module is disabled or no longer needs the callback
Aurora:RemoveCallback(callbackId, true)
```
```

--------------------------------

### Creating a Dropdown Menu with Options in Lua

Source: https://docs.aurora-wow.wtf/interface/ui-elements

Illustrates how to implement a dropdown menu using `gui:Dropdown()`. The snippet shows how to define the list of `options`, set a `default` selection, and use the `key` parameter for persistence. It also includes optional parameters like `multi` for multi-select functionality and an `onChange` handler.

```lua
gui:Dropdown({	
    text = "Quality",	
    key = "graphics.quality",	
    options = {	
        { text = "Low", value = "low" },	
        { text = "Medium", value = "medium" },	
        { text = "High", value = "high" }	
    },	
    default = "medium",	
    multi = false,			-- Set to true for multi-select  
    width = 200,			-- Optional  
    tooltip = "Select quality level",	
    onChange = function(self, value)	
        print("Quality changed:", value)	
    end	
})
```

--------------------------------

### Example: Track Group Changes - Lua

Source: https://docs.aurora-wow.wtf/misc/CombatLogReader

An example of registering a normal WoW event handler for `GROUP_ROSTER_UPDATE`. This handler simply prints a message whenever the group composition changes.

```lua
EventHandler:RegisterNormalEvent("GROUP_ROSTER_UPDATE", function()  
    print("Group composition changed")
end)

```

--------------------------------

### Create Basic GUI Structure with Aurora.GuiBuilder

Source: https://docs.aurora-wow.wtf/interface/overview

This snippet demonstrates the basic usage of the Aurora.GuiBuilder to create a simple UI structure with a category, tab, header, checkbox, and slider. It utilizes a fluent interface for chaining method calls. No external dependencies beyond the Aurora framework are required.

```lua
local gui = Aurora.GuiBuilder:New()
gui:Category("My Category")
   :Tab("General")
   :Header({ text = "Settings" })
   :Checkbox({ text = "Enable Feature" })
   :Slider({ text = "Speed" })
```

--------------------------------

### Getting Fractional Spell Charges (Lua)

Source: https://docs.aurora-wow.wtf/spell

Illustrates using the `chargesleft()` method to get the current fractional charges remaining, including any partially regenerated charges. This returns a numerical value.

```lua
local fractionalCharges = spell:chargesleft() -- Returns number
```

--------------------------------

### Use Consistent Configuration Keys with Constants in Lua

Source: https://docs.aurora-wow.wtf/interface/config-system

Illustrates using constants or a table to define configuration keys. This ensures consistency across the addon when reading or writing settings, reducing the chance of typos and making refactoring easier.

```lua
-- Define keys as constants
local CONFIG_KEYS = {
    ENABLED = "feature.enabled",
    THRESHOLD = "feature.threshold"
}

-- Use constants for consistency
Aurora.Config:Read(CONFIG_KEYS.ENABLED)
Aurora.Config:Write(CONFIG_KEYS.THRESHOLD, 75)
```

--------------------------------

### Draw Class-Colored Names Example

Source: https://docs.aurora-wow.wtf/misc/Draw

An example showcasing how to draw unit names with colors corresponding to their class. It uses `Draw:GetColor` with the unit's class name and `canvas:Text` to render the name.

```lua
Draw:RegisterCallback("classNames", function(canvas, unit)
    if unit.player then
        local r, g, b, a = Draw:GetColor(unit.class2, 255)
        canvas:SetColor(r, g, b, a)
        canvas:Text(unit.name,"GameFontHighlight", unit.position.x, unit.position.y, unit.position.z + 2)
    end
end, "units")
```

--------------------------------

### Track Single Aura by ID - Lua Example

Source: https://docs.aurora-wow.wtf/unit-properties/AuraTracking

This Lua example demonstrates tracking a single aura by its ID. The callback function prints messages when the aura is added/updated or removed from a unit. The returned function can be called to stop tracking.

```lua
-- Track a single aura by ID  
local unregisterTracker = Aurora.TrackAuras(462854, function(unit, aura, event)  
    if event == "ADD_OR_UPDATE" then  
        print("Aura detected:", aura.name, "on", unit.name)  
    elseif event == "REMOVE" then  
        print("Aura removed:", aura.name, "from", unit.name)  
    end  
end)  
  
-- When you want to stop tracking:  
unregisterTracker()
```

--------------------------------

### Initialize Namespace Object - Lua

Source: https://docs.aurora-wow.wtf/index

This code snippet demonstrates how to initialize an empty Lua table to serve as your custom namespace. Namespaces are crucial in Aurora for preventing naming conflicts and organizing your code effectively. This empty table is the foundation for all your custom routines and data.

```lua
YourNamespace = {}  
```

--------------------------------

### Handle Configuration Loading Errors Safely in Lua

Source: https://docs.aurora-wow.wtf/interface/config-system

Provides a robust method for loading configuration values by including error handling. If a configuration key fails to load (returns nil), it prints a warning and returns a specified default value, preventing potential addon errors.

```lua
local function SafeLoadConfig(key, default)
    local value = Aurora.Config:Read(key)
    if value == nil then
        print("Warning: Failed to load config for " .. key)
        return default
    end
    return value
end
```

--------------------------------

### Track Multiple Auras by ID or Name - Lua Example

Source: https://docs.aurora-wow.wtf/unit-properties/AuraTracking

This Lua example shows how to track multiple auras simultaneously using an array of spell IDs and names. The callback function is a placeholder for custom logic. The tracker can be unregistered by calling the returned function.

```lua
-- Track multiple auras  
local aurasToTrack = {  
    462854,  -- First aura ID  
    123456,  -- Second aura ID  
    "Power Word: Shield" -- Aura by name  
}  
  
local unregisterTracker = Aurora.TrackAuras(aurasToTrack, function(unit, aura, event)  
    -- Handler code  
end)
```

--------------------------------

### Example: Coordinate Pulls with Aurora

Source: https://docs.aurora-wow.wtf/hooks/bigwigs

An example Lua function illustrating how to use Aurora's Boss Mods pull timer for coordination. It checks if a pull is active and the remaining time, enabling actions such as casting pre-pull abilities at the appropriate moment.

```Lua
-- Example: Pull timer coordination  
function CheckPullStatus()  
    if Aurora.BossMod:ispulling() then  
        local remaining = Aurora.BossMod:getpulltimeremaining()  
        if remaining <= 3 then  
            -- Do pre-pull ability  
            CastPrePullAbility()  
        end  
    end  
end  
```

--------------------------------

### Keyboard Hook API Reference

Source: https://docs.aurora-wow.wtf/hooks/keyboard

Reference for the Aurora Keyboard Hook API, covering keybind formats, basic usage patterns like registering, setting, and checking keybinds, and how to integrate with configuration for saving and loading keybinds.

```APIDOC
## Keyboard Hook API Reference

### Description
This API allows developers to create custom keyboard and mouse bindings within the Aurora system. It supports standard keys, mouse buttons (Button4-Button31), and modifier keys (Shift, Ctrl, Alt, etc.).

### Keybind Format
Keybinds are defined as strings. They can be simple keys, a modifier combined with a key, or mouse buttons.

- **Simple Key**: `"A"`
- **Modifier + Key**: `"Shift+A"`
- **Mouse Button**: `"Button4"`
- **Modifier + Mouse Button**: `"Shift+Button5"`
- **Special Mouse Buttons**: `"MiddleButton"`

### Basic Usage
This section details the fundamental operations for interacting with the keybind manager.

#### Registering a Keybind
`Aurora.KeyBindManager:RegisterKeybind(keybindId, callbackFunction, description)`
- `keybindId` (string): A unique identifier for the keybind.
- `callbackFunction` (function): A function that will be called when the keybind's state changes. It receives a boolean `isPressed` argument.
- `description` (string): A human-readable description of the keybind's action.

**Example:**
```lua
Aurora.KeyBindManager:RegisterKeybind("my_ability", function(isPressed) 
    if isPressed then  
        print("Ability activated!")  
    end  
end, "My Ability")  
```

#### Setting a Keybind
`Aurora.KeyBindManager:SetKeybind(keybindId, keybindString)`
- `keybindId` (string): The ID of the keybind to set.
- `keybindString` (string): The string representation of the desired keybind (e.g., `"Button4"`, `"Shift+A"`).

**Example:**
```lua
Aurora.KeyBindManager:SetKeybind("my_ability", "Button4")  
```

#### Checking if a Keybind is Pressed
`Aurora.KeyBindManager:IsPressed(keybindId)`
- `keybindId` (string): The ID of the keybind to check.
- Returns: `boolean` - `true` if the keybind is currently pressed, `false` otherwise.

**Example:**
```lua
local isPressed = Aurora.KeyBindManager:IsPressed("my_ability")  
```

#### Getting Keybind Description
`Aurora.KeyBindManager:GetKeybindDescription(keybindString)`
- `keybindString` (string): The string representation of a keybind.
- Returns: `string` - A readable description of the keybind.

**Example:**
```lua
local desc = Aurora.KeyBindManager:GetKeybindDescription("Shift+Button4")  
-- Returns: "Shift + Mouse 4"
```

### Configuration Integration
This section demonstrates how to save and load keybinds using Aurora's configuration system.

**Example:**
```lua
-- Save/load with config  
local savedKeybind = Aurora.Config:Read("my_ability_hotkey") or "F1"  
Aurora.KeyBindManager:RegisterKeybind("my_ability", callback, "Description")  
Aurora.KeyBindManager:SetKeybind("my_ability", savedKeybind)  
```

### Error Handling
- If a `keybindId` is not registered, `IsPressed` will return `false`.
- Invalid `keybindString` formats provided to `SetKeybind` or `GetKeybindDescription` may result in unexpected behavior or errors.
```

--------------------------------

### Example: React to Specific Timer in Aurora

Source: https://docs.aurora-wow.wtf/hooks/bigwigs

An example Lua function demonstrating how to react to a specific timer managed by Aurora's Boss Mods. It checks if a timer exists and its remaining time, allowing for pre-emptive actions like preparing for an ability.

```Lua
-- Example: React to specific timer  
function CheckImportantTimer()  
    if Aurora.BossMod:hastimer("Important Ability") then  
        local remaining = Aurora.BossMod:gettimerremaining("Important Ability")  
        if remaining < 5 then  
            -- Prepare for ability  
            PrepareForAbility()  
        end  
    end  
end  
```

--------------------------------

### Get Encounter Information via Lua API

Source: https://docs.aurora-wow.wtf/hooks/encounter-manager

Demonstrates how to retrieve encounter-related information using the Encounter Manager API in Lua. Includes functions to get the current encounter object, its elapsed time, and a list of active boss units.

```lua
-- Get current encounter info
local encounter = Aurora.EncounterManager:GetCurrentEncounter()

-- Get elapsed time of current encounter
local time = Aurora.EncounterManager:GetEncounterElapsedTime()

-- Get active boss units
local bosses = Aurora.EncounterManager:GetActiveBossUnits()

```

--------------------------------

### Managing Group Members with List Methods

Source: https://docs.aurora-wow.wtf/lists-and-units/Lists

Illustrates how to use the 'group' list and its 'each' method to iterate through party or raid members and apply actions, such as healing, based on their health and proximity to the player.

```lua
-- Heal group members  
group:each(function(member)  
    if member.hp < 80 and member.distanceto(player) < 40 then  
        -- Heal the group member  
        return true  
    end  
end)  
```

--------------------------------

### Count Units Affected by Debuffs - Lua Example

Source: https://docs.aurora-wow.wtf/unit-properties/AuraTracking

This advanced Lua example tracks important debuffs and counts the number of affected units. It uses a table to keep track of unique units and updates a counter based on aura events. The tracker is unregistered using the returned function.

```lua
-- Track important debuffs and count affected units  
local debuffCount = 0  
local affectedUnits = {}  
  
local unregisterTracker = Aurora.TrackAuras({12345, 67890}, function(unit, aura, event)  
    if event == "ADD_OR_UPDATE" and not affectedUnits[unit.guid] then  
        affectedUnits[unit.guid] = true  
        debuffCount = debuffCount + 1  
        print("Units affected by tracked debuffs:", debuffCount)  
    elseif event == "REMOVE" then  
        affectedUnits[unit.guid] = nil  
        debuffCount = debuffCount - 1  
    end  
end)
```

--------------------------------

### Saving and Loading GUI Element Configuration

Source: https://docs.aurora-wow.wtf/interface/config-integration

Illustrates the basic structure for saving and loading configuration for a GUI element, specifically a checkbox. Providing a 'key' ensures the element's state is automatically managed by the configuration system.

```lua
gui:Checkbox({
    text = "Enable Feature",
    key = "feature.enabled", -- Config key
    default = false         -- Default value
})
```

--------------------------------

### Advanced Damage Tracker Example - Lua

Source: https://docs.aurora-wow.wtf/hooks/state-registrar

Implements a damage tracking system using the StateExpression. It records individual hits, cleans up old hits based on a time window, and calculates the total damage taken. This example showcases event handling, periodic updates, and custom state management.

```lua
local StateExpression = Aurora.StateExpression

-- Create damage tracking state
local damageTaken = StateExpression:New("damage_taken")
damageTaken.hits = {} -- Store individual hits

-- Cleanup function for managing the hit window
local function cleanupOldHits(self, now)
    local windowStart = now - self.window
    local removed = 0

    -- Remove old hits
    while self.hits[1] and self.hits[1].time < windowStart do
        table.remove(self.hits, 1)
        removed = removed + 1
    end
      
    -- Recalculate total
    local total = 0
    for _, hit in ipairs(self.hits) do
        total = total + (tonumber(hit.amount) or 0)
    end
      
    -- Update only if changed
    if total ~= self.value then
        self.value = total
    end
      
    return removed
end

-- Setup event handling
local f = CreateFrame("Frame")
f:RegisterEvent("UNIT_COMBAT")

-- Periodic cleanup
local timerFrame = CreateFrame("Frame")
timerFrame:SetScript("OnUpdate", function(self, elapsed) 
    if #damageTaken.hits > 0 then
        cleanupOldHits(damageTaken, GetTime())
    end
end)

-- Event forwarding
f:SetScript("OnEvent", function(self, event, ...)
    damageTaken:Update(event, ...)
end)

-- Register damage handler
damageTaken:RegisterHandler("UNIT_COMBAT", function(self, now, unitTarget, event, flagText, amount, schoolMask)
    if unitTarget ~= "player" then return end

    -- Process damage amount and type
    local damageAmount = tonumber(amount) or 0
    local damageType = "Unknown"
      
    -- Map damage school types
    local schoolTypes = {
        [1] = "Physical",
        [2] = "Holy",
        [4] = "Fire",
        [8] = "Nature",
        [16] = "Frost",
        [32] = "Shadow",
        [64] = "Arcane"
    }
    damageType = schoolTypes[schoolMask] or "Unknown"
      
    -- Record hit details
    table.insert(self.hits, {
        time = now,
        amount = damageAmount,
        type = damageType,
        isCrit = flagText == "CRITICAL",
        isCrushing = flagText == "CRUSHING",
        isGlancing = flagText == "GLANCING"
    })
      
    cleanupOldHits(self, now)
end)

-- Register in global state
Aurora.state.damage_taken = damageTaken
```

--------------------------------

### Creating a Button with onClick Event in Lua

Source: https://docs.aurora-wow.wtf/interface/ui-elements

Provides a code example for creating a functional button using `gui:Button()`. It includes optional parameters like width, height, and tooltip, and demonstrates how to define an `onClick` function that executes a specified action, such as printing a message to the console.

```lua
gui:Button({	
    text = "Click Me",	
    width = 120, 		-- Optional  
    height = 25, 		-- Optional  
    tooltip = "Click this button to do something", 	-- Optional tooltip  
    onClick = function()   
        print("clicked")   
    end	
})
```

--------------------------------

### Get Aurora Boss Mod Timers

Source: https://docs.aurora-wow.wtf/hooks/bigwigs

Retrieve and query active timers within Aurora's Boss Mods. Functions allow fetching all timers, specific timers by text match, checking for timer existence, and getting remaining time. These are essential for real-time raid awareness.

```Lua
-- Get all active timers  
local timers = Aurora.BossMod:getactivetimers()  
  
-- Get a specific timer by text match  
local timer = Aurora.BossMod:gettimer("timer text")  
  
-- Get all timers matching text  
local matchingTimers = Aurora.BossMod:gettimers("timer text")  
  
-- Check if a specific timer exists  
local exists = Aurora.BossMod:hastimer("timer text")  
  
-- Get remaining time for a specific timer  
local remaining = Aurora.BossMod:gettimerremaining("timer text")  
```

--------------------------------

### Missile Unit Properties

Source: https://docs.aurora-wow.wtf/missiles/properties

Get information about the creator, target, and source of a missile.

```APIDOC
## Missile Unit Properties

Retrieves information about the units associated with the missile.

#### Endpoint

`/websites/aurora-wow_wtf/missile/unit_properties`

#### Parameters

None

#### Response

- **creator** (string) - Unit that created the missile
- **target** (string) - Target unit of the missile
- **source** (string) - Source GUID
```

--------------------------------

### Basic Item Creation and Usage in Lua

Source: https://docs.aurora-wow.wtf/item-handler/overview

Demonstrates how to create a new item object using its ID and then check if it's usable before using it on a player. This is fundamental for integrating items into rotation logic.

```lua
-- Basic item creation  
local healthPotion = Aurora.ItemHandler.NewItem(33447)  
  
-- Using an item  
if healthPotion:usable(player) then  
    healthPotion:use(player)  
end  
```

--------------------------------

### Implementing a Color Picker with State Saving in Lua

Source: https://docs.aurora-wow.wtf/interface/ui-elements

Provides an example of how to create a color picker UI element using `gui:ColorPicker()`. It includes parameters for setting the `text`, a `key` for saving the selected color, a `default` color value, and optional `width` and `height`. The `onChange` function allows for handling color changes and applying them to other UI elements.

```lua
gui:ColorPicker({	
    text = "Text Color",	
    key = "ui.textColor", 		-- Config key for saving  
    default = {r = 1, g = 0, b = 0, a = 1},		-- Default to red  
    width = 200,			-- Optional  
    height = 20,			-- Optional  
    tooltip = "Choose the color for UI text",	
    onChange = function(self, color)	
        print("Color changed:", color.r, color.g, color.b, color.a)	
        -- Example: Apply the color  
        -- MyAddonFrame.text:SetTextColor(color.r, color.g, color.b, color.a)	
    end	
})
```

--------------------------------

### Retrieving the First Matching Unit from a List

Source: https://docs.aurora-wow.wtf/lists-and-units/Lists

Demonstrates the 'first' method, which returns the first unit in a list that matches the criteria specified in the callback function. If no unit matches, it returns nil.

```lua
local target = enemies:first(function(unit)  
    return unit.hp < 20  
end)  
```

--------------------------------

### Get Spell Cast Time

Source: https://docs.aurora-wow.wtf/spell

Retrieves the cast time of a spell in seconds. This function returns a numerical value representing the duration of the spell cast.

```lua
local castTime = spell:getcasttime() -- Returns number (seconds)  
```

--------------------------------

### Get Talent Spell Rank

Source: https://docs.aurora-wow.wtf/spell

Retrieves the current rank of a talent spell. This function returns a numerical value representing the spell's rank.

```lua
local rank = spell:rank() -- Returns number  
```

--------------------------------

### Getting Maximum Spell Charges (Lua)

Source: https://docs.aurora-wow.wtf/spell

Shows how to obtain the maximum number of charges a spell can have using the `maxcharges()` method. This returns a numerical value.

```lua
local maxCharges = spell:maxcharges() -- Returns number
```

--------------------------------

### Inspect Aurora Objects with DevTool

Source: https://docs.aurora-wow.wtf/getting-started/recommended-addons

Demonstrates how to use the DevTool addon to inspect Aurora objects, such as the player's entity, within the game. This is useful for debugging and understanding the structure of Aurora's data.

```lua
DevTool:AddData(Aurora.UnitManager:Get("player"), "PlayerEntity")
```

--------------------------------

### Access Missile Current Position Coordinates

Source: https://docs.aurora-wow.wtf/missiles/properties

Retrieve the current X, Y, and Z coordinates of a missile. The 'currentposition' property provides a convenient way to get all coordinates as a table.

```Lua
missile.cx  -- Current X coordinate
missile.cy  -- Current Y coordinate
missile.cz  -- Current Z coordinate
-- Or use:
missile.currentposition -- Returns {x, y, z} table
```

--------------------------------

### Arc Check for Cleave Spells

Source: https://docs.aurora-wow.wtf/getting-started/callbacks

An example of a callback for cleave spells that checks if any active enemies are within a specific arc and range of the player. It iterates through active enemies.

```lua
spells.Revenge:callback(function(spell, logic)
    Aurora.activeenemies:each(function(enemy)
        if enemy.inarcof(player, 8, 180) then
            return spell:cast(player)
        end
    end)
end)
```

--------------------------------

### Create New Item Instance

Source: https://docs.aurora-wow.wtf/item-handler/item-functions

Creates a new item instance in Aurora. This is the primary method for initializing an item object, which can then be used to access its properties and methods. No external dependencies are required beyond the Aurora API.

```lua
local item = Aurora.ItemHandler.NewItem(12345)
```