Bar modding Lua modding Unitdefs Customparams

BAR modding basics: Lua unitdefs, customparams, and common pitfalls

A practical walkthrough of how to modify unit definitions in Beyond All Reason without tripping over the most frequent mistakes new modders hit.

Tags: bar modding, lua modding, unitdefs, customparams, tweakdefs, base64, modoptions

Understanding unitdef lookups in BAR Lua

BAR modding revolves around unit definitions. The engine exposes them through Lua tables, and knowing which table to query saves hours of debugging. If you are writing a widget or gadget, pull unit IDs through UnitDefNames[unitName].id. Always confirm the unit actually exists before grabbing the ID, or you will get nil crashes. When writing a tweakdef instead, use UnitDefs[unitname] directly. No IDs exist at that stage. You are working on the raw definition object.

Adding customparams with modoptions

Modoptions let you pass values into defs files. The standard pattern works like this. Check for the mod option in your all-defs post. Match the unit name. Then inject your customparams table. A common use case is adding evolution announcement text to commanders. You would include the armcom.lua file, pull the commander def, and add a customparams table with your key-value pairs. The engine reads these at load time and applies them to the unit.

Base64 encoding without the web hassle

Some moddef workflows require base64url encoding. Hitting random websites for this is slow and risky for larger payloads. A VS Code extension handles it locally. The key detail many modders miss is that BAR expects base64url format, not standard base64. Standard base64 uses + and / characters. base64url swaps those for - and _. Using the wrong variant causes silent load failures that are painful to trace back.

Debugging tweakdef problems

Most tweakdef issues boil down to two mistakes. Referencing a unit definition before the engine has loaded the corresponding file. Using standard base64 when base64url is required. Check your load order. Confirm the target unitdef exists at the point your code runs. Run BAR in debug mode and watch for nil reference logs. The Lua console in-game surfaces most errors quickly if you check it right after mod load.

A quick checklist before testing

  • Confirm UnitDefs or UnitDefNames table matches your mod type
  • Verify base64url encoding, not standard base64
  • Check customparams syntax matches the expected key names
  • Test in a fresh lobby to rule out lobby-state caching bugs
  • Read the in-game Lua console for nil errors on mod load

Join the Creed of Champions

Creed of Champions runs a friendly, teamwork-first community for RTS players who want competitive matches without the toxicity. Modding is one of the best ways to learn how BAR works under the hood, and having a patient group to share findings with accelerates that learning fast. Training sessions, team gameplay, and a large cross section of abilities and time zones make it easy to fit in. As one member put it:

"Creed of Champions is a great place to learn and play BAR in a friendly atmosphere. Training sessions, team gameplay, even some non-BAR stuff. Large cross section of abilities, time zones, and game mode interests."
Advertisement