Lua

A standalone executable and a loadable module that embed Lua 5.4 and expose the full BUI kit API: every widget, every event. Use the bui-lua binary, or drop bui.so / bui.dll into any Lua 5.4, LuaJIT or LuaRocks install.

Build it

The Lua host is off by default. Turn it on with a CMake option:

cmake -S . -B build -DBUI_BUILD_LUA_BINDINGS=ON
cmake --build build --target bui-lua
./bui-lua app.lua
./bui-lua

CMake uses a system Lua 5.4 when it finds one. Otherwise it downloads Lua 5.4.7 at configure time and builds it with the host. The suites are registered with ctest as bui_lua_*.

Install with LuaRocks

luarocks install blenderui
lua -e 'print(require("bui").KIT_VERSION)'

The rock needs Lua 5.4, CMake and a C and C++20 compiler (on Linux also the X11 development headers, libx11-dev on Debian and Ubuntu or libX11-devel on Fedora: without them the kit has no native windows and bui.Window returns nil). It builds the C kit and the _bui module from the release tag, and installs them with the bui.lua wrapper, so require("bui") works in any Lua 5.4 program. From a checkout, luarocks make bindings/lua/blenderui-<version>-1.rockspec does the same.

A first window

local bui = require("bui")
local root = bui.Node("frame")
root:set("padding", 8)
local btn = bui.Node("button")
btn:set("text", "Click Me")
btn:on(bui.EV_CLICK, function(self) print("Clicked!") end)
root:add(btn)
btn:geom(bui.GEOM_PACK, {fill = 1})
local ctx = bui.Context(root)
local win = bui.Window(ctx, "Lua BUI", 320, 120)
win:show()
bui.run()

Widgets

frame, column, row, grid, box, panel, tabs, sidetabs, scroll, label, separator, progress, button, toggle, checkbox, decorator, text, search, hotkey, number, slider, dropdown, enum, swatch, popover, menubutton, menubar, image, video, textarea, custom, canvas, list, tree, gridview, ramp, curve, normal, histogram, radio, meter and filebrowser.

Menus

Menu items are plain Lua tables, mirroring Python’s MenuItem: text, icon (icon name or id), shortcut, checked / enabled (booleans or numbers), fn (the callback) and sub for nested menus. set_menus fills a menubutton; on a menubar it builds one menubutton child per top-level item, exactly like Python’s MenuBar. ctx:open_menu(owner, items, title, x, y) and ctx:open_pie(items, title) open popups from code. fn callbacks are registry refs retained by the kit for as long as any copy of their item lives (menu button, open popup, search filter) and released automatically when the items are replaced or the node/context is freed. See examples/menus.lua and examples/menubar.lua.

Animation

bui.gsap and bui.motion are GSAP’s and Motion’s APIs on the kit’s animation engine, the one every BUI language uses. A call’s tables are read once, into the engine, and a frame runs no Lua unless you gave a callback such as onUpdate.

local gsap, motion = bui.gsap, bui.motion

gsap.to(slider, {value = 80, duration = 0.6, ease = "power2.out", repeat_ = 1, yoyo = true})
gsap.from(progress, {factor = 0, duration = 1})
gsap.to({a, b, c}, {value = 100, stagger = {each = 0.1, from = "center"}})

local tl = gsap.timeline({defaults = {duration = 0.5, ease = "none"}})
tl:to(a, {value = 100}):to(b, {value = 100}, "<0.2"):addLabel("mid"):to(c, {value = 50}, "mid+=0.25")

motion.animate(slider, {value = {0, 100, 40}}, {duration = 1, times = {0, 0.3, 1}})
motion.animate(slider, {value = 75}, {type = "spring", stiffness = 300, damping = 20})

• Springs are real springs, solved in closed form, and an interrupted one hands its velocity to the next motion.
• Properties: value, color, backgroundColor and the numbers a node has (factor, min, max, height, padding, scroll). Kit widgets have no draw transform or opacity, so x, y, scale, rotate and opacity are errors.
• Options in GSAP’s camelCase or snake_case (repeat_ or ["repeat"] for Lua’s keyword): duration, delay, repeat, repeatDelay, yoyo, timeScale, paused, reversed, ease, overwrite, stagger, times, type (tween, spring, inertia), the spring’s stiffness, damping, mass, bounce and visualDuration, and the callbacks onStart, onUpdate, onComplete, onRepeat, onReverseComplete and onInterrupt.
• Errors at the call: an unknown ease, property or option, a value of the wrong kind, or a freed node is a Lua error that names it.
• Clock: the kit ticks animations in its frames. A host with its own clock, or a test, calls gsap.ticker.useHostClock(true) and gsap.ticker.tick(seconds).

The animation guide has the full API, testing and the limits. examples/anim.lua is a pump-driven loop with progress, color cycling and a wave slider.

Examples

27 scripts in bindings/lua/examples: hello.lua, counter.lua, todos.lua, gallery.lua, forms.lua, dashboard.lua, anim.lua, lua_table_editor.lua, editor_screenshot.lua, box.lua, canvas.lua, curve.lua, enum.lua, grid.lua, histogram.lua, listview.lua, menubar.lua, menus.lua, popover.lua, ramp.lua, split.lua, textarea.lua, color_picker.lua, filebrowser_demo.lua, image_viewer.lua, data_table.lua and ph_nutrients.lua.

Next steps