Data Types¶

A "data type" in clockwork is the shape of a value a Top-Level Object hands back. Unlike MacroQuest, these are not registered types in a parser — they are plain Lua tables and values, and the pages here document their members.

Object types¶

Type	Returned by
`actor`	`mq.TLO.Target`, `mq.TLO.Spawn[...]`, `mq.TLO.Spawns()`, `EncounterMembers()`
`character`	`mq.TLO.Me` — an `actor` plus self-only members
`ability`	`Me.Ability(...)`, `Me.AbilityID(...)`, `Me.AbilityByName(...)`
`effect`	`Effects()`, `Me.Detriments()`, `Me.Maintained()`
`item`	`eq2.inventory()`, `eq2.equipped()`
`item_def`	`eq2.item_def(item_def_id)` — examine-level detail
`roster`	`mq.TLO.Group`, `mq.TLO.Raid`
`rostermember`	`Group.Member[n]`, `Raid.Members()`
`zone`	`mq.TLO.Zone`
`UiHandle`	`eq2.ui.window(...)`, `eq2.ui.find(...)`, native-UI event payloads

Lua primitives¶

The reference pages annotate each member with the plain Lua type it returns. They mean exactly what they mean in Lua:

number¶

A Lua number. Used for both integers (spawn ids, levels, percentages, icon ids) and reals (distances, coordinates, seconds).

Percentages are 0–100, not 0.0–1.0. Durations are seconds unless a member's name says otherwise (RecastDurationTenths).

string¶

A Lua string, UTF-8. Never nil — an unresolvable name reads as "".

bool¶

true or false. Never nil.

table¶

A plain Lua table with named keys, e.g. Me.Afflictions() returning { Trauma = 0, Arcane = -1, ... }.

array¶

A 1-based Lua sequence, suitable for ipairs. Empty (#t == 0) rather than nil when there is nothing to return.

Fail-soft values¶

Every accessor returns a safe zero value on failure — 0, "", false, nil, or an empty array — and never raises a Lua error, even if you are not in the world yet or a signature failed to resolve.

That means a returned value does not prove the read succeeded. Guard on the value you actually care about:

local t = mq.TLO.Target
if t.ID() ~= 0 then          -- correct: 0 means "no actor"
  ...
end

Distance() fails open

Distance() returns 0.0 when it cannot resolve a position — including when the local player read fails. Every d > radius gate therefore reads a failed lookup as "on top of me". Movement gates must require d > 0:

local d = t.Distance()
if d > 0 and d > radius then ... end

Calling convention¶

Actor, ability, and roster-member objects are tables of zero-argument functions. Call them with ., never :

mq.TLO.Me.Level()     -- correct
mq.TLO.Me:Level()     -- wrong

The one exception is UiHandle, which is a real sol2 usertype and does use colon-call syntax.