Skip to content

Top-Level Objects

A Top-Level Object is an entry point for reading game state. In MacroQuest these are the things you write inside ${...}; in clockwork they are members of the mq.TLO table, called as real Lua functions.

mq.TLO.Me.PctHP()          -- 87
mq.TLO.Target.Name()       -- "a decaying skeleton"
mq.TLO.Zone.Name()         -- "Antonica"

Note the trailing () on the leaf. mq.TLO.Me.PctHP without it is the function itself, not the value — a mistake that shows up as function: 0x... in your output.

There is no ${...} evaluator. Everything is read live on each call, never cached.

Objects

Me
Your own character.
Target
Your current target.
Spawn[key]
Look up any actor in the world by spawn id or by name.
Spawns()
Every actor currently loaded in your zone.
SpawnCount()
How many actors are currently loaded in your zone.
Group
Your group roster.
Raid
Your raid roster.
Zone
The zone you are currently in.
Ability helpers
Top-level shortcuts for asking about an ability by name or by id, without fetching the ability object first.

mq and eq2 are the same table

mq is an alias for eq2, so mq.TLO.Me and eq2.TLO.Me are identical. The bundled scripts use mq.TLO.* for state reads and eq2.* for actions, purely as a readability convention.

Everything fails soft

No accessor ever raises a Lua error. Out of world, mid-zone, or with a signature that failed to resolve, you get 0, "", false, nil, or an empty array.

That makes the return value no proof the read worked, so guard on the value you care about rather than on the call:

local t = mq.TLO.Target
if t.ID() ~= 0 then          -- correct
  ...
end

Two consequences worth knowing before you write your first script:

  • Distance() returns 0.0 on a failed read, so every d > radius gate treats a failure as "on top of me". Require d > 0.
  • Me.PctHP() reads as a very large number while you are dead, not 0, so low-health gates stop firing at the worst moment.

What isn't here yet

clockwork's TLO surface is smaller than MacroQuest's. Things that don't exist:

  • No spawn-search syntax — filter Spawns() in Lua instead.
  • No XTarget (EverQuest II has no such window).
  • No Merchant, Corpse, Task, AltAbility, or DynamicZone TLOs. Some of that state is reachable through the eq2.* action surface instead — see Events and Binds.
  • No Math, Time, Ini, or String helper TLOs — Lua's own standard library covers those.

See also