Object Lists

Object Lists are filtered arrays of SYNQ objects. Each list automatically filters units based on specific criteria, making it easy to work with groups of enemies, friends, or objects.

Key Concepts

Performance - Lists are lazy-loaded when first referenced, then cached for the rest of the current tick.

Freshness - Always access lists fresh where you need them. Don't store them in variables outside your working scope.

-- Enemies
synq.enemies.loop(function(enemy)
    if enemy.hp < 30 then
        spell:Cast(enemy)
    end
end)

-- Enemies within 40 yards
synq.enemies.within(40).loop(function(enemy)
    spell:Cast(enemy)
end)

-- Friends
synq.friends.loop(function(friend)
    if friend.hp < 50 then
        heal:Cast(friend)
    end
end)

-- Group
synq.group.loop(function(member)
    if member.debuffCount > 0 then
        dispel:Cast(member)
    end
end)

Available Lists

group

Players in your party or raid, excluding yourself.

fgroup - Same as group but includes yourself.

enemies

Enemy units relevant to your environment:

• Arena/Battleground - Enemy players only
• PvE/Open World - Enemy units in combat or targeting players

Note: Explosives are in synq.explosives, not this list.

friends

All friendly players within render distance.

dead

All targetable dead units within render distance.

totems

Enemy totems or related objects (PvP).

explosives

M+ affix explosive objects.

objects

All objects of type GameObject.

Magic Methods

Available for every SYNQ object list. Can be added to custom arrays with synq.immerseOL(table).

around

Find units around a position within a distance.

local count, total, objects = list.around(unit, distance, criteria)

Parameters:

• unit - SYNQ object or position {x, y, z}
• distance - Number
• criteria - Optional filter function

Returns:

• count - Units that met criteria
• total - Total units around
• objects - Array of filtered objects

local bcc, total = enemies.around(player, 8, function(obj) return obj.bcc end)
if bcc == 0 and total >= 2 then
    brutalSlash:Cast()
end

filter

Creates a new list containing objects that pass the test function.

local meleeEnemies = enemies.filter(function(obj)
    return obj.role == "melee"
end)

within

Filters the list to only include units within a specified distance from the player. Chainable with other methods.

list.within(range)

synq.enemies.within(40).loop(function(enemy)
    spell:Cast(enemy)
end)

synq.friends.within(30).loop(function(friend)
    heal:Cast(friend)
end)

loop

Iterate the list, calling the function for each object. Returns truthy value to break.

Arguments passed:

• object - Current object
• index - Current index
• uptime - Time since first iteration over this object

list.loop(function(unit, i, uptime)
    if not unit.enemy or unit.distance > 40 then return end
    if unit.immuneMagic then return end
    return spell:Cast(unit)
end)

fastLoop

Minimum-overhead iterator for hot scans that run every tick. Return any truthy value to stop scanning. The callback receives only the object — no index or uptime.

list.fastLoop(function(object) ... end)

When to use:

• Interrupt scans
• Threat checks
• Finding the first valid enemy fast
• Anywhere a tick-rate scan needs the lowest possible overhead

When not to use:

• Readability-first code
• Helper chains where the path isn't actually hot
• Replacing a smaller filtered loop with a broad scan

Why it's faster: less per-iteration overhead, native early-exit support, optimised for scan-and-pick logic.

local match
synq.enemies.fastLoop(function(enemy)
    if match then return true end
    if not enemy.exists then return end
    if enemy.dist > 30 then return end
    if not enemy.los then return end

    match = enemy
    return true -- stop scanning
end)

if match then
    -- act
end

Accuracy first, optimization second — use it where it makes sense, not everywhere.

stomp

Like loop but for totems - eliminates despawning totems, only passes object and uptime (no index).

synq.totems.stomp(function(totem, uptime)
    if uptime < 0.25 then return end
    return spell:Cast(totem)
end)

sort

Sorts the list using table.sort. Use sparingly for performance.

synq.enemies.sort(function(x, y) return x.hp < y.hp end)

Custom Object Lists

Create custom lists with magic methods using synq.List:New.

synq.List:New(objectTypes, constructor)

example.rangedDPS = synq.List:New({ 5, 6 }, function(object, objectType, guid)
    return object.class2 == "HUNTER" or object.class2 == "WARLOCK"
end)

example.rangedDPS.loop(function(unit)
    print(unit.name)
end)

Note: Use list.length instead of #list to trigger population.

Next: Learn about all available Object Attributes for accessing unit information.