Getting started in Lua 0.5
Lua 5.4 or LuaJIT, so LÖVE works too. lua-goome is one C module, goome.so (or goome.dll) with goome built in.
To start from a project that already builds, goome new my-app --lang lua makes one from the Lua template, see Templates and goome new 0.5.1.
Pick what you are making
goome.open is the overlay, goome.app a window, goome.open_offscreen a buffer with no window. end is a Lua keyword, so goome_end and goome_ui_end are g:finish(c) and ui:finish() here.
Overlay on top of everything
local goome = require("goome")
local g = assert(goome.open("my overlay"))
local running = true
while running do
for ev in g:events(16) do
if ev.type == goome.QUIT then running = false end
end
local c = g:begin(0)
if c then
c:round_rect(40, 40, 240, 50, 12, 0xE0202838)
c:text(56, 56, "on top of everything", 0xFFFFFFFF)
g:finish(c)
end
end
g:close()
More on Overlay mode.
Make a normal app
local goome = require("goome")
local app = goome.app("My app", 960, 640)
local clicks = 0
app:frame(function(ui)
if ui:button("Click me") then clicks = clicks + 1 end
ui:label("clicked " .. clicks .. " times")
end)
app:run()
More on Window mode.
Inside a game engine
local g = goome.open_offscreen(320, 200)
local c = g:begin(0)
c:round_rect(20, 20, 280, 160, 16, 0xFF6FDC5F)
g:finish(c)
local frame = g:last_frame()
upload_texture(frame:ptr(), frame.w, frame.h)
In LÖVE g:frame_copy writes straight into an ImageData:getPointer(). examples/love in the repo is a small LÖVE scene with a goome settings window on top. More on Offscreen mode.
Install
Its not on the luarocks.org server, so LuaRocks takes the rock from the releases page:
luarocks install https://github.com/goome-ui/lua-goome/releases/download/v0.5.0/goome-0.5.0-1.src.rock
Add --lua-version 5.1 for a LuaJIT tree. Or without LuaRocks:
LUA_INC=/usr/include/lua5.4 ./build.sh test
LUA_INC=/usr/include/luajit-2.1 LUA=luajit ./build.sh test
You need a C compiler and the Lua headers:
- Debian / Ubuntu:
sudo apt install build-essential liblua5.4-dev - Mac:
xcode-select --install - Windows: mingw-w64 from git bash, with
LUA_LIBpointing at yourlua54.dllorlua51.dll
On Linux and Mac the module never links Lua, one build works for any interpreter that matches the headers it was built with. For another version see Versions.
Your first overlay
local goome = require("goome")
local g, err = goome.open("my overlay")
if not g then error("no overlay here: " .. err) end
local pace = goome.pacer(60)
local running = true
while running do
for ev in g:events(pace:wait()) do
if ev.type == goome.QUIT then running = false end
if ev.type == goome.DOWN then print(string.format("clicked at %.0f,%.0f", ev.x, ev.y)) end
end
local c = g:begin(0)
if c then
c:round_rect(100, 100, 200, 80, 12, 0xE0202838)
c:text(116, 128, "click me", 0xFFFFFFFF, true)
c:hit(100, 100, 200, 80)
g:finish(c)
end
end
g:close()
Colors are 0xAARRGGBB numbers, positions are logical desktop coords, same as C. Things that can fail for a normal reason give back nil, message, code like io.open, so assert(...) works.
How it maps to C
Names are the C ones without goome_, constants without GOOME_ (goome.WIN_MOVE). Widgets dont take pointers, they hand back the new value and if it changed:
volume, changed = ui:slider("Volume", volume, 0, 1, "%.2f")
Begins and ends work like C, ui:window / ui:window_end and so on. Lists are 1 based like the rest of Lua, so ui:combo and ui:tabs use 1 for the first one. Flags add up with +.
Editors
VS Code: the Lua extension by sumneko (sumneko.lua). goome is a C module so you dont get completion on it, the API reference has the C names and they map one to one. For LÖVE theres Love2D extensions that start the game from the editor. The goome extension side panel and .goome.json preview work in a Lua project too, its snippets are only C, C#, Python and Java for now.
IntelliJ IDEA: the EmmyLua plugin does Lua there, and the goome plugin can sit next to it for the tool window and preview.
lua examples/ui_demo.lua from a clone (after build.sh) shows every widget. Set GOOME_BACKEND=test to run without touching your screen (Testing without a screen).