Writing user widgets

Writing user widgets

A user widget is a Lua file in the LuaUI/Widgets folder of your Beyond All Reason data folder. Custom widgets only load when "Allow custom widgets" is on in the settings, and then must be turned on or off in-game using the Widget Selector.

How a widget works

A widget starts as a table named widget. That table is also its code environment: Its variables and code are contained there. Widgets can share data and features with each other through the WG table, also. The game calls the functions it finds on that table as events happen in the skirmish.

A widget's layer sets its order among other widgets. Lower layers draw on top and see mouse and keyboard input first. Input functions can return true to consume that input, so other widgets after it in layer-order never see it. A MousePress that returns true also receives the mouse's movement and release events.

A widget sees only what its player can see. You may have to handle checks that fail because a known unit moved outside of vision, for example.

When a widget fails, the reason is logged in infolog.txt, in your data folder.

Where to find the APIs

• The game's own widgets are in luaui/Widgets in the game's source. Many of them share features with other widgets through WG: https://github.com/beyond-all-reason/Beyond-All-Reason
• The Recoil engine's Lua API reference lists every callin and every Spring and gl function: https://recoilengine.org/docs/lua-api/
• The engine's guide to communication between widgets covers WG and the other ways widgets share data: https://recoilengine.org/docs/guides/wupget/
• The recoil-lua-library gives editors autocompletion and type checking for the engine's API: https://github.com/beyond-all-reason/recoil-lua-library
• The BAR-widgets repository collects community widgets and accepts new ones: https://github.com/beyond-all-reason/BAR-widgets

More info

With handler = true in GetInfo, a widget gets a handler for its own callins, actions, and options.

Widgets load Lua from source. The debug table provides tracebacks and function info.

Settings a widget returns from widget:GetConfigData() are saved between games and handed back to widget:SetConfigData(data). A widget writes files only inside LuaUI/Config/ and LuaUI/Widgets/, and reads files only inside LuaUI/, plus the game's and maps' own files.

Widgets run without network access, and RmlUi is not available to them for now.

Getting help

The widget channels on the Beyond All Reason Discord are the place to ask.