UI API¶

Draw your own menus, overlays and HUDs. Every drawing function lives on the Asterion global and runs against an immediate-mode renderer.

Conventions¶

Coordinates are in pixels from the top-left of the screen.
Colors are four channels r, g, b, a, each 0–255. a is opacity.
[ ] marks an optional argument; its default is noted per function.
All drawing happens inside a tick callback (see SetTickCallback), between BeginFrame and SubmitFrame.

Asterion.SetTickCallback(function()
    if not Asterion.MenuOpen() then return end

    Asterion.BeginFrame()

    local w, h = Asterion.ScreenSize()
    Asterion.DrawRectFilled(40, 40, 260, 120, 15, 15, 15, 235, 10)
    Asterion.DrawBorderRect(40, 40, 260, 120, 232, 178, 121, 255, 1, 10)
    Asterion.DrawText(56, 58, "Asterion", 20, 232, 178, 121, 255)

    Asterion.SubmitFrame()
end)

Frame control¶

Every draw call must happen between BeginFrame and SubmitFrame.

`Asterion.BeginFrame`¶

Begins a new UI frame. Call once before any draw call.

Asterion.BeginFrame()

`Asterion.SubmitFrame`¶

Submits the frame for rendering. Call once after all draw calls.

Asterion.SubmitFrame()

Draw primitives¶

Asterion.DrawLine(x1, y1, x2, y2, r, g, b, a [, thickness])
Asterion.DrawRect(x, y, w, h, r, g, b, a [, thickness [, rounding]])
Asterion.DrawRectFilled(x, y, w, h, r, g, b, a [, rounding])
Asterion.DrawRoundedRect(x, y, w, h, rounding, r, g, b, a [, thickness])
Asterion.DrawRoundedRectFilled(x, y, w, h, rounding, r, g, b, a)
Asterion.DrawRectGradient(x, y, w, h, r1, g1, b1, a1, r2, g2, b2, a2, horizontal)
Asterion.DrawCircle(cx, cy, radius, filled, r, g, b, a [, thickness [, segs]])
Asterion.DrawShadowRect(x, y, w, h, r, g, b, a [, offset [, alpha [, rounding]]])
Asterion.DrawBorderRect(x, y, w, h, r, g, b, a [, thickness [, rounding]])
Asterion.DrawText(x, y, text, font_size, r, g, b, a)
Asterion.DrawImage(id, x, y, w, h [, r, g, b, a [, rounding [, u0, v0, u1, v1]]])

Function	Description
`DrawLine`	Line from `(x1,y1)` to `(x2,y2)`. `thickness` default `1`.
`DrawRect`	Rectangle outline. Optional `rounding` for rounded corners.
`DrawRectFilled`	Filled rectangle, optional corner `rounding`.
`DrawRoundedRect`	Rounded-corner outline with explicit `rounding` radius.
`DrawRoundedRectFilled`	Filled rounded rectangle.
`DrawRectGradient`	Two-color gradient fill; `horizontal` is a boolean.
`DrawCircle`	Circle at `(cx,cy)`. `filled` boolean; `segs` sets smoothness.
`DrawShadowRect`	Drop shadow behind a rect. `offset`/`alpha`/`rounding` optional.
`DrawText`	Text at `(x,y)` in the current font at `font_size`.
`DrawImage`	Draw an image by `id`; optional tint, `rounding`, UV crop.

Tint an image

Pass 255,255,255,255 as the tint to draw an image unchanged; lower the alpha to fade it, or set an RGB tint to recolor it.

Clip rects¶

Restrict drawing to a rectangular region — useful for scroll areas and lists.

Asterion.PushClipRect(x, y, w, h [, intersect])
Asterion.PopClipRect()

Function	Description
`PushClipRect`	Clip following draws to `(x,y,w,h)`. `intersect` (default `true`) intersects with the current clip instead of replacing it.
`PopClipRect`	Restore the previous clip region. Pair every push with a pop.

Fonts¶

id     = Asterion.LoadFont(path, size [, icon_mode])
id     = Asterion.LoadTTFCloud(url, size [, icon_mode])
ok     = Asterion.IsFontReady(id)
         Asterion.PushFont(id)
         Asterion.PopFont()
w, h   = Asterion.CalcTextSize(text, font_size [, font_id])

Function	Returns	Description
`LoadFont`	`id`	Load a TTF from a local `path` at `size`. `icon_mode` treats the glyphs as icons.
`LoadTTFCloud`	`id`	Load a TTF from a `url` (async — check with `IsFontReady`).
`IsFontReady`	`boolean`	Whether a font `id` has finished loading.
`PushFont`	—	Use `id` for following text; pair with `PopFont`.
`PopFont`	—	Restore the previous font.
`CalcTextSize`	`w, h`	Measured pixel size of `text`. Optional explicit `font_id`.

Built-in font IDs¶

Constant	Value	Font
`Asterion.FONT_TITLE`	`1`	Title
`Asterion.FONT_WIDGET`	`2`	Widget / body
`Asterion.FONT_ICON`	`3`	Codicon (large)
`Asterion.FONT_ICON_SM`	`4`	Codicon (small)

Asterion.PushFont(Asterion.FONT_TITLE)
Asterion.DrawText(20, 20, "Menu", 22, 240, 240, 240, 255)
Asterion.PopFont()

Images¶

id = Asterion.LoadImage(path)
id = Asterion.LoadImageFromUrl(url)
ok = Asterion.IsImageReady(id)

Function	Returns	Description
`LoadImage`	`id`	Load an image from a local `path`.
`LoadImageFromUrl`	`id`	Load an image from a `url` (async). Animated GIFs are supported.
`IsImageReady`	`boolean`	Whether an image `id` has finished loading.

Draw a loaded image with DrawImage.

local logo = Asterion.LoadImageFromUrl("https://asterion.pub/gold_bull_logo.svg")

-- later, inside the frame:
if Asterion.IsImageReady(logo) then
    Asterion.DrawImage(logo, 48, 48, 32, 32)
end

Input¶

x, y = Asterion.MousePos()
dz   = Asterion.MouseWheel()
ok   = Asterion.IsMouseDown([btn])
ok   = Asterion.IsKeyDown(vk)
ok   = Asterion.IsKeyPressed(vk)

       Asterion.EnableMouseControl()
       Asterion.DisableMouseControl()
ok   = Asterion.IsMouseControlEnabled()

Function	Returns	Description
`MousePos`	`x, y`	Cursor position in screen pixels.
`MouseWheel`	`dz`	Wheel delta this frame.
`IsMouseDown`	`boolean`	Button held. `btn`: `0` = left, `1` = right, `2` = middle. Only reports while mouse control is active.
`IsKeyDown`	`boolean`	Virtual-key `vk` held.
`IsKeyPressed`	`boolean`	`vk` went down this frame (one-shot).
`EnableMouseControl`	—	Capture the mouse for the UI (cursor drives the menu).
`DisableMouseControl`	—	Release the mouse back to the game.
`IsMouseControlEnabled`	`boolean`	Whether the UI currently owns the mouse.

Click detection

Use IsKeyPressed / a one-shot check for buttons so a single click fires once, not every frame it stays held.

State & misc¶

w, h = Asterion.ScreenSize()
ok   = Asterion.MenuOpen()
dt   = Asterion.DeltaTime()
       Asterion.SetTickCallback(fn)
       Asterion.Log(msg)
       Asterion.LogClear()

Function	Returns	Description
`ScreenSize`	`w, h`	Render resolution in pixels.
`MenuOpen`	`boolean`	Whether the Asterion menu is currently open.
`DeltaTime`	`dt`	Seconds since the last frame — use for animations.
`SetTickCallback`	—	Register `fn` to run every frame. Do all drawing here.
`Log`	—	Write a line to the Asterion log console.
`LogClear`	—	Clear the log console.

Constants¶

Constant	Description
`Asterion.MenuKey`	Virtual-key code of the menu toggle key.
`Asterion.MenuKeyName`	Human-readable key name, e.g. `"INSERT"`.
`Asterion.FONT_TITLE` / `FONT_WIDGET` / `FONT_ICON` / `FONT_ICON_SM`	Built-in font IDs.