Item Objects

Item Objects give you powerful, object-oriented tools for working with items in your routine. Whether you're managing health potions, tracking tier set bonuses, or coordinating trinket usage, item objects make it all simple and organized.

Creating Item Objects

Creating an item object is straightforward - just provide the item ID:

synq.Item(itemID) -> Item Object

Example

local healthstone = synq.Item(5512)

Now healthstone contains all attributes, methods, and functions of an item object. You can use it to gather information about the Healthstone, actually use it, and set up various conditions for when to use it. Most relevant information about the item is gathered from WoW's API and presented as attributes.

Why Use Item Objects?

Item objects handle complex logic automatically. Even a simple example like a Healthstone benefits - the :Use method automatically checks:

• The item is off cooldown
• You have it equipped or in your bags
• It's actually usable right now
• And more before attempting to use it

Organization & Performance Benefits

Item objects help you organize your code in powerful ways:

• Fantastic organization - Code related to each item lives within its own item object
• Easy to digest actors - Your actor becomes a clean, item-related stack of priorities
• Major performance benefit - Code related to items only runs when the underlying item is ready to be used

Populating the Actor

Use synq.Populate to make item objects available to your routine actor and the current file's scope. This lets you reference items directly by name in your rotation:

local Unlocker, synq, example = ...
local bm = example.hunter.bm

local items = {
    healthstone = synq.Item(5512),
    healthPotion = synq.Item(171267),
}

-- Make items available to the actor and current file scope
synq.Populate(items, bm, getfenv(1))

After populating, you can call healthstone() or healthPotion() directly in your actor without needing local references. This keeps your code organized and makes item management straightforward.

Item Methods

Item objects provide useful methods that let you use items in many different ways, from simple to complex.

Quick Example

local healthstone = synq.Item(5512)

-- Simple use method - checks if item is usable and attempts to use it
if healthstone:Use() then 
    synq.alert("Using Healthstone!") 
end

-- Update method sets up automatic usage logic
healthstone:Update(function(item)
    -- Skip if item is not currently usable
    if not item:Usable() then return end
    -- Use healthstone if player health is below 50%
    if player.hp < 50 then
        return item:Use() and synq.alert("Used Healthstone!")
    end
end)

-- Call the update function - will automatically use healthstone below 50% HP when usable
healthstone()

Casting Methods

Use

Checks if the item is usable, then attempts to use it. Returns true if use was attempted.

item:Use(unit) -- params are optional

Usable

Returns true if the item is usable on the given unit.

item:Usable(unit) -- params are optional

UseAoE

Uses an AoE item at given coordinates or object location.

-- Use AoE item at specific 3D coordinates
item:UseAoE(x, y, z)

-- Or use AoE item at a SYNQ object's position
item:UseAoE(unit)

Uses the item directly at the given coordinates (or unit's position). Generally makes no modifications to the coordinates, just performs a direct use → click operation as smoothly as possible.

if resonator:UseAoE(target) then
    synq.alert("Nice!")
end

Item Attributes

Item objects have many attributes relating to information about the item. Most of this is derived from the Item ID using WoW's API, which is why you must provide the ID instead of an item name.

Basic Attributes

id - The ItemID of the item (what you provided)

name - The proper name of the item

synq.alert(item.name)

range - The max range the item can be cast at

if target.distance < item.range then
    synq.alert('In range!')
end

Timing Attributes

castTime - The cast time of the item (0 for instant cast items)

if target.magicImmunityRemains < item.castTime then
    item:Use(target)
end

cd / cooldown - Current cooldown of the item

if item.cd > 10 then
    print("Item cooldown is more than 10 seconds - will be a while before it's ready!")
end

Availability Attributes

equipped - Whether or not you have the item equipped

if not item.equipped then
    print("Item is not equipped - check your bags!")
end

numequipped - How many of the provided items you have equipped (useful for tier pieces)

local tierPieces = synq.Item({1234, 5678, 9012, 3456})

if tierPieces.numequipped < 2 then
    print("Player has less than 2 tier pieces equipped - no 2-set bonus yet!")
end

count - How many of the item you have (useful for consumables like potions)

if item.count < 10 then
    print("Item count is less than 10 - running low on consumables!")
end

usable - Whether or not the item is currently "usable"

if item.usable then
    item:Use()
end

Practical Examples

Health Management in BM Hunter Routine

Automatically use health potions when your Hunter is in danger. This example integrates seamlessly into your BM Hunter rotation:

local Unlocker, synq, example = ...
local bm = example.hunter.bm

local healthPotion = synq.Item(171267) -- Spiritual Healing Potion

healthPotion:Update(function(item)
    if player.hp < 35 and player.combat and item.count > 0 then
        return item:Use() and synq.alert("Emergency Health Potion!", item.id)
    end
end)

-- In your actor, call healthPotion() to check and use if conditions are met
synq.Populate({healthPotion = healthPotion}, bm, getfenv(1))

Then in your actor, you can add healthPotion() to your rotation priority list, and it will automatically use the potion when health drops below 35% in combat.

Tier Set Management

Track your tier set bonuses:

local tierPieces = synq.Item({
    189797, -- Helm
    189799, -- Shoulders
    189801, -- Chest
    189798, -- Gloves
    189800  -- Legs
})

if tierPieces.numequipped >= 2 then
    print("Player has 2-piece tier set bonus active!")
end

if tierPieces.numequipped >= 4 then
    print("Player has 4-piece tier set bonus active!")
end

Trinket Usage in Burst Windows

Coordinate trinket usage with your BM Hunter burst cooldowns for maximum effectiveness:

local Unlocker, synq, example = ...
local bm = example.hunter.bm

local dpsTrinket = synq.Item(184842) -- Example DPS trinket

dpsTrinket:Update(function(item)
    -- Use trinket during burst windows or when target is above 20% HP
    if target.enemy and target.hp > 20 and item.cd == 0 then
        if synq.burst or bestialWrath.active then
            return item:Use() and synq.alert("DPS Trinket Activated!", item.id)
        end
    end
end)

synq.Populate({dpsTrinket = dpsTrinket}, bm, getfenv(1))

This example shows how to coordinate trinket usage with your burst cooldowns. The trinket will activate during burst windows or when Bestial Wrath is active, maximizing damage output.

Putting It All Together

Item objects provide a clean, object-oriented approach to item management in SYNQ routines. They make consumable usage, equipment tracking, and trinket management simple and efficient. By organizing item logic within the item objects themselves, your routines stay clean and performant.

Next: Learn about Object Lists for working with groups of units and objects.