Skip to content

mod.ui

HUD widgets, buttons and panels drawn with the game’s own panels, pixel font and colours. Client only; on the server these calls are accepted and ignored.

client

A small panel in a HUD corner. Widgets in one corner stack away from it. A draw callback that errors 3 times, or runs over 3 ms for 30 frames in a row, is switched off. All mod UI hides while the game is paused or the upgrade tree is open.

Parameter Type
id string [a-z][a-z0-9_]*, unique in your mod.
anchor string? top_left (default), top_right, bottom_left, bottom_right.
w number 8 to 160.
h number 8 to 80.
draw function draw(g), every frame. See the drawing object below.
visible function? Return false to hide.
order number? Lower sits nearer the corner.

Returns a key (string)

Raises

  • expected a plain table of options
  • expected a table of options
  • id must be [a-z][a-z0-9_]*
  • anchor must be top_left, top_right, bottom_left or bottom_right
  • w must be 8 to 160
  • h must be 8 to 80
  • draw must be a function
  • visible must be a function
  • order must be a number
  • register UI while the mod loads
  • ' already used by this mod
mod.ui.widget({
id = "clock",
anchor = "bottom_left",
w = 60, h = 14,
draw = function(g)
g.text(string.format("%.0f S", mod.time()), 4, 4, mod.ui.colors.dim)
end,
})

client

A button in the MODS strip at the right edge of the HUD.

Parameter Type
id string [a-z][a-z0-9_]*.
label string 12 characters at most.
on_click function Called on a click.
visible function? Return false to hide.

Returns a key (string)

Raises

  • label is required (12 characters or fewer)
  • must be text of
  • on_click must be a function
mod.ui.button({
id = "hello",
label = "HELLO",
on_click = function()
mod.game.toast("HELLO THERE")
end,
})

client

A window, opened by its own button in the MODS strip.

Parameter Type
id string [a-z][a-z0-9_]*.
title string 20 characters at most.
label string? Button text, default the title cut to 12.
w number 60 to 260.
h number 40 to 180.
draw function draw(g) for the window body.

Returns a key (string)

Raises

  • title is required (20 characters or fewer)
  • w must be 60 to 260
  • h must be 40 to 180
mod.ui.panel({
id = "stats",
title = "MY STATS",
w = 120, h = 50,
draw = function(g)
g.text("BEST TIER " .. tostring(mod.game.best_tier() or 1), 6, 6)
end,
})

client table

The HUD palette as { r, g, b } tables. Pass them to the g calls.

local gold = mod.ui.colors.gold -- { 255, 202, 84 }

A draw(g) callback gets g, clipped to its rectangle. Coordinates are pixels from the top left of the widget or panel body. A call that would leave the rectangle draws nothing. Colours are { r, g, b } or { r, g, b, a }.

Call Does
g.w, g.h Size of the area in pixels.
g.text(text, x, y, color?, scale?, align?) Pixel-font text, 40 characters at most. scale 1 or 2. align "left" (default), "center" or "right": x is then the left, middle or right edge. Not drawn if it would leave the area.
g.measure(text, scale?) Width of the text in pixels.
g.fill(x, y, w, h, color?) A solid rectangle. Default colour: text.
g.bar(x, y, w, h, fraction, color?) A filled bar, 0 to 1. Default colour: gold.
g.panel(x, y, w, h, style?) A game panel: "glass" (default), "gold", "bad", "raised", "dim".
g.sprite(name, x, y, scale?) One of your sprites, scale 1 to 4.
g.button(id, x, y, w, h, label, style?) Draws a button; returns true on the frame it is clicked.
Name Value
mod.ui.colors.accent [110, 168, 255]
mod.ui.colors.bad [255, 94, 98]
mod.ui.colors.dim [160, 170, 190]
mod.ui.colors.edge [200, 214, 236]
mod.ui.colors.gold [255, 202, 84]
mod.ui.colors.good [88, 214, 141]
mod.ui.colors.ink [8, 10, 18]
mod.ui.colors.panel [18, 26, 42]
mod.ui.colors.raised [28, 38, 58]
mod.ui.colors.stroke [64, 80, 110]
mod.ui.colors.text [240, 236, 226]