How to use tweakdefs for unit mods in beyond all reason

What tweakdefs do in bar

Tweakdefs are the BAR system that lets you modify existing unit definitions without rewriting everything from scratch. Instead of copying a full unitdef table and editing one line, you tell the game which fields to override. This keeps your mod lean and compatible with upstream balance changes.

When you work with BAR units, every unit pulls from tables like unitdefs, weapondefs, and movedefs. Tweakdefs let you target a specific nested value inside those tables. That is the practical advantage over a full clone.

Common tweakdefs mistakes

The errors players hit most often fall into three categories:

• Malformed definitions: A missing comma or bracket in your tweakdefs file silently produces a nil result. The game loads, the unit appears wrong, and the log shows nothing helpful unless you know where to look.
• Missing subtables: If you override a subtable entry, the parent table must exist first. Writing to a non-existent path just fails.
• Nil handling: Functions like tonumber() on missing customParams return nil. Always wrap these with a fallback, such as tonumber(value) or 64.

Always test one tweakdef change at a time. Apply half a dozen and then something breaks, tracking down which one is slow work.

Cloning units with tweakdefs

When you need a unit that is 90 percent identical to an existing one, start with the original table and mutate. A recursive copy function walks the unitdefs table, duplicates every nested key, and returns a fresh table you can edit without touching the original.

For example, if you want to clone a weapon from one unit onto another through tweakdefs, copy the specific weapondefs entry and remap it under the target unit. Do not rewrite every weapon parameter. Copy the full weapondefs block, then change only what differs.

Keep in mind that Spring.CreateUnit still works for game logic code like spawning unit waves. It is not deprecated for that use. But you cannot use it as a build command in a lobby script. For build orders you need Spring.GiveOrderToUnit with the negative ID of the unitdef, written as -UnitDefNames.armwin.id.

Finding spring api functions

BAR runs on the Spring engine. The Spring API surface is large and not all of it is obvious from a quick search. The key reference files are:

• The CMD module documentation at beyond-all-reason.github.io/spring/ldoc/modules/CMD.html for command constants
• The engine source under rts/Sim/Units/CommandAI for behavior details behind each command
• The keysym header at luaui/Headers/keysym.h.lua for key codes

Functions like Spring.GetUnitNearestEnemy(unitID, range) are useful for proximity triggers. The function returns nil when no enemy falls inside the range parameter. A common pattern is reading a custom parameter for range and defaulting it safely:

local triggerRange = tonumber(UnitDefs[unitDefID].customParams.detonaterange) or 64
local targetID = Spring.GetUnitNearestEnemy(unitID, triggerRange)
if targetID then
  -- fire sequence
end