Practical BAR modding notes: weapondefs, select commands, and real documentation gaps

Practical takeaways for BAR modders working with weapon definitions, UI widgets, and the spring engine's internal command systems.

Weapon tag definitions live in the C++ source

Anyone who has tried to write a clean tweakdef runs into the same wall. The weapondefs markdown guide on the spring repository looks like the authoritative reference, but it does not cover every tag. The actual tag descriptions are baked into the engine source code at WeaponDef.cpp line 124 in the BAR105 branch.

Modders who want accurate definitions should read that file directly rather than relying solely on the external markdown documentation. Tags get parsed and validated against the C++ implementation, not the guide. When a tag behaves differently than documented, the source wins.

Categorizing weapon tags is worthwhile but becomes a manual effort. Automated generation stops being useful once the guide diverges from what the engine actually implements.

Recoil documentation gaps

Recoil parameters in weapondef files are one area where the docs and the code frequently disagree. BAR community developers have pointed out that recoil docs contain broken link placeholders and outdated examples.

When working on a unit that fires with recoil, test with live values rather than trusting the numbers in the guide. Start conservative and scale up. The spring engine clamps some recoil behavior differently than documented, and the only reliable source is running the weapon in a test skirmish.

Select command and UI widget extensions

The BAR build bar widget (gui_buildbar.lua) supports a useful pattern: right-click a factory in the dock widget to set the camera target to that factory, and hover to queue its production. This comes from the spring select-command system, documented at the spring articles page on select commands.

Modders looking to extend UI widgets should study this pattern. The select-command system lets Lua scripts bind contextual actions to interface elements without touching core engine code. Feature requests that extend existing widgets rather than building new ones land faster because the integration points already exist.

Spectator and team selection quirks

Links and references to Select Team, Spectator, and similar internal command pages in the spring documentation often point nowhere. These are engine internals that the spring docs team is still catching up on.

When a mod depends on spectator behavior or team selection logic, read the actual Lua widgets in the BAR repository. The widget code shows the real implementation, complete with edge cases that docs never cover.

Closing thoughts

BAR modding rewards people who read the source. The markdown guides help with orientation, but every tag definition, recoil quirk, and widget behavior traces back to what the engine actually does. Good modders verify against the code, test in skirmish, and share what they find so the next person does not hit the same wall.

"Having a space like here that offers a community, trainings, events, and the guarantee to not be judged or insulted by fellow members is really precious. Keeping the game safe, and more importantly, fun."

Creed of Champions member