Drawing

Two coordinate systems, and they are easy to confuse.

Screen space is render pixels from the top-left. World space is game coordinates, projected with the client's own camera. Colours are 0–1 throughout, not 0–255.

-- Screen space
Nyx.Draw.Line(100, 100, 300, 100, 1, 0.2, 0.1, 1)
Nyx.Draw.Rect(100, 120, 200, 40, 0.1, 0.6, 1, 0.35, true)
Nyx.Draw.Circle(400, 300, 80, 1, 1, 0, 1)

-- World space
local player = Nyx.Objects.Player()
for _, unit in ipairs(Nyx.Objects.Nearby(30)) do
    Nyx.Draw.WorldCircle(unit.x, unit.y, unit.z, unit.combatReach, 1, 0.4, 0.2, 0.9)
    Nyx.Draw.WorldLine(player.x, player.y, player.z + 1,
                      unit.x, unit.y, unit.z + 1, 1, 0.4, 0.1, 0.7)
end

Text and health bars

Text and textures are not drawn by the engine — they are the client's own FontStrings and Textures, anchored at projected positions. That means crisp native font rendering and no font dependency in the engine.

They are pooled, so a frame has to be bracketed:

Nyx.Draw.BeginFrame()
for _, unit in ipairs(Nyx.Objects.Nearby(30)) do
    local fraction = unit.health / unit.healthMax
    Nyx.Draw.WorldHealthBar(fraction, unit.x, unit.y, unit.z + 2.6)
    Nyx.Draw.WorldText(string.format("%d%%", fraction * 100),
                      unit.x, unit.y, unit.z + 3.1)
end
Nyx.Draw.EndFrame()

EndFrame hides whatever the frame did not use. Skip it and the previous frame's text lingers.

Drawings persist until replaced

The engine keeps the last set of shapes and redraws them every frame, because Lua ticks far slower than the game renders. Consuming them per frame would show each drawing for one frame in six.

So: clear and re-issue every frame, and call Nyx.Draw.Clear() when you want something to disappear.

Projecting yourself

Nyx.Engine.w2s(x, y, z) returns screenX, screenY, onScreen in render pixels, which is what anchoring your own frames to world positions needs.

Note that GetScreenWidth() is in scaled interface units, not render pixels. Converting between them needs the frame's own effective scale — see Nyx.Draw's implementation, which does exactly this and flips the Y axis, since WoW frames measure from the bottom-left and the projection from the top-left.