Getting started with BAR widget development in Lua
BAR widgets are Lua scripts that add functionality to the game UI. If you want to build your own, here is what you need to know.
Tags: BAR widgets, lua scripting, widget development, SpringRTS widgets
Widgets are Lua
There is no alternative language for BAR widget development — widgets run in Lua. The best way to learn is reading existing widgets. The BAR GitHub repository contains a full luaui/Widgets directory with working examples. The old SpringRTS wiki is still useful but increasingly outdated as BAR adds new features. Start with a simple widget, understand its structure, then build up from there.
Required subtables for tweakdefs
New tweakdefs fail silently when expected subtables are missing. The common culprits are buildoptions, customparams, weapondefs, and the weapons array. If you are editing weapon damage through tweaks, you need to navigate into the weapondefs subtable of the unit definition, not treat the top-level UnitDefs table as flat. Weapon damage lives nested inside the unit's weapon definition, which itself is an array. Loop through the weapons array and modify the damage or reload values on each weapon entry.
AI-assisted widget generation
Using AI tools to generate widget boilerplate speeds up development considerably. You can describe the widget behavior you want and get a functional starting point about half the time. The trick is having a clear specification — describe exactly what the widget should display, what events it should respond to, and what UI elements it needs. AI is good at structure but still requires human review, especially around edge cases like what happens when a unit is destroyed mid-operation or when player focus switches to a different command group.
Key reference pages
- BAR GitHub luaui/Widgets folder — real working widget examples
- SpringRTS Lua Unsynced Read reference — what widgets can query
- SpringRTS Lua Unsynced Control reference — what widgets can do
- SpringRTS Lua Callins — event system for widget lifecycle
The project is gradually moving toward the RMLUI framework for widget rendering, though documentation for that transition is still limited.
Creed of champions
Learning to build tools that help other players is the kind of contribution that strengthens the whole community. Creed of Champions values people who build useful things and share them openly. Serious RTS play without the toxic baggage.
[Crd] Before discovering Creed, I was thinking the only thing that separates BAR from the perfect RTS is a friendly and safe social environment for new players to learn and feel included.