Getting started writing BAR widgets: callins, hooks, and documentation

Where are widget hooks documented?

Widget hooks like widget:GameFrame(n) are documented on the Spring RTS wiki. The main Lua documentation page is at springrts.com/wiki/Lua:Main. For GameFrame specifically, the callins page covers the function signature and usage patterns.

These callins are the backbone of widget development. GameFrame(n) fires every game frame, giving widgets a hook to update visual overlays, recalculate positions, or respond to game state changes. Understanding where these hooks are listed is the first step into writing effective widgets.

Example widget code locations

Beyond the wiki documentation, BAR ships with working widget examples in its repository. The luaui/widgets directory on the BAR GitHub contains dozens of real-world widgets that can serve as templates. Reading through existing widgets is often faster than starting from documentation alone.

Look for widgets that do something similar to what the player wants to build. Copy the structure, swap the logic.

Building visual overlay widgets

A common project idea is a widget that draws circles showing unit attack ranges, radar coverage, and other area effects directly on the map. This requires drawing functions from the Spring rendering API and unit property lookups to fetch each unit's current range values.

The approach is straightforward in concept: iterate over visible units on each frame, fetch their range statistics, and draw circles at their positions. Performance is the main concern, since GameFrame fires frequently and heavy computation here causes frame drops.

Caching range data and only redrawing on meaningful change events keeps overlay widgets responsive during actual gameplay.

Quick start checklist

• Start at springrts.com/wiki/Lua:Main for callin documentation
• Study existing widgets in luaui/widgets on the BAR repository
• Use GameFrame(n) for per-frame updates, but keep logic light
• Cache expensive lookups and avoid redundant drawing each frame
• Test with a minimal widget skeleton before adding complex features

Creed of Champions

Modders and widget authors share the same spirit as good teammates: they solve problems, share solutions, and make the game better for everyone. Creed of Champions welcomes players who bring that same energy into matches. Check the channel for community content.

[Crd] Gaming actually fulfills a human purpose here - cooperation, mutual upbuilding, fun and striving for greatness together. Instead of random anonymity, you meet, learn from, and enjoy real people.