Moonlight Lua API

Callbacks API

Register Lua functions that the C++ host will call at specific times (paint, rescan).

callbacks.paint(function)

Registers a function that runs every frame during the render pass.

callbacks.paint(function()
    draw.addtext(50, 50, 1, 255, 255, 255, 255, "Hello, World!")
end)

callbacks.rescan(function)

Registers a function that runs when the C++ layer triggers a rescan event.

callbacks.rescan(function()
    print("Rescan triggered!")
end)

Draw API

The Draw API uses ImGui's background draw list to render 2D elements on-screen. Coordinates are in pixels.

draw.addtext(x, y, size, r, g, b, a, text)

Draws text with an outline. size selects a font scale preset. Alpha ranges 0–255.

draw.addtext(200, 100, 2, 255, 255, 255, 255, "FPS: 144")

draw.calculatetextsize(text)

Returns width and height of text in pixels.

local w, h = draw.calculatetextsize("Hello")

draw.screensize()

Returns screen width and height (uses host OS metrics).

local w, h = draw.screensize()

draw.addrect(x, y, width, height, r, g, b [, thickness])

Outlined rectangle. thickness defaults to 1.0.

draw.addrect(100, 100, 200, 100, 255, 0, 0, 2)

draw.addrectfilled(x, y, width, height, r, g, b [, a])

Filled rectangle. Alpha defaults to 255.

draw.addrectfilled(50, 50, 150, 75, 0, 128, 255, 180)

draw.addgradient(x, y, width, height, r1,g1,b1,a1, r2,g2,b2,a2, r3,g3,b3,a3, r4,g4,b4,a4)

Gradient rectangle with per-corner colors (TL, TR, BL, BR).

draw.addgradient(
0, 0, 300, 60,
20,20,20,255,
40,40,40,255,
10,10,10,255,
25,25,25,255
)

draw.WorldToScreen(x, y, z)

Converts a 3D point to 2D screen coordinates. Returns (x, y) or (nil, nil) if invalid.

local sx, sy = draw.WorldToScreen(0, 10, 0)
if sx then
  draw.addtext(sx, sy, 1, 255, 255, 0, 255, "Target")
end

Globals API

Helpers exposing environment data.

globals.username()

Returns the username string provided by the host.

local user = globals.username()
draw.addtext(10, 10, 1, 255, 255, 255, 255, "User: " .. user)

globals.GetLocalBone(boneName)

Returns the local player's bone position as x,y,z. Use with draw.WorldToScreen.

local x, y, z = globals.GetLocalBone("Head")
if x then
  local sx, sy = draw.WorldToScreen(x, y, z)
  if sx then
    draw.addtext(sx, sy - 10, 1, 255, 0, 0, 255, "HEAD")
  end
end

globals.GetPlayers()

Returns a table of all cached players. Each entry has: name, health, enemy, team, x, y, z.

local players = globals.GetPlayers()
for _, p in pairs(players) do
  if p.enemy and p.health > 0 then
    print(p.name .. " @ " .. p.x .. "," .. p.y .. "," .. p.z)
  end
end

globals.ReadMemory(address, type)

Reads memory at address. type: 1=int, 2=float, 3=bool.

local value = globals.ReadMemory(0xDEADBEEF, 2)
if value then print("Float: " .. value) end

Example Script

Draws a header bar with title and username.

callbacks.paint(function()
  local w, h = draw.screensize()
  draw.addgradient(0, 0, w, 40,
    15,15,15,255, 25,25,25,255, 20,20,20,255, 30,30,30,255)
  local title = "Moonlight Overlay Example"
  local tw, th = draw.calculatetextsize(title)
  draw.addtext(w/2 - tw/2, 10, 2, 255,255,255,255, title)
  local user = globals.username()
  draw.addtext(10, h - 25, 1, 180,180,180,255, "User: " .. user)
end)