How to use BAR tweakunits with Base64 encoding
Step-by-step guide to modifying individual unit stats in custom BAR lobbies using tweakunits and URL-safe Base64 encoding.
Tags: bar tweakunits, base64 encoding, unit tweaking, reloadtime, tweakcommands
What tweakunits does
Tweakunits lets lobby hosts change individual unit properties without editing game files. You target a unit definition, override specific fields, and encode the result so the lobby can share it with all players. Common use cases include adjusting reload times, build distance, energy production, sight range, and worker speed for custom scenarios.
Writing your tweak definition
Each tweak is a Lua table that mirrors the unit's internal definition structure. The outer key is the unit name, followed by nested tables for the fields you want to change. For example, to slow down a Juggernaut's death gun:
```
{
corjugg = {
juggernaut_fire = {
reloadtime = 4,
},
},
}
```
You can modify multiple units in a single table. Just add more top-level entries:
```
{
legck = {
builddistance = 2000,
energymake = 500,
speed = 100,
},
legcom = {
builddistance = 2500,
workertime = 3000,
metalmake = 1000,
},
}
```
Two common mistakes trip people up. First, missing commas between entries in the same table will break the parse. Second, if you are posting code online or in chat, surround it in triple backticks so formatting does not mangle the syntax.
Lua is forgiving about trailing commas at the end of a table, so that will not cause a crash. Missing internal commas will.
Encoding and URL-safe Base64
Once the Lua table is correct, encode it as Base64. The encoding must be URL-safe, which means replacing standard Base64 characters that conflict with URLs. Some workflows also expect you to strip trailing padding characters from the encoded string.
The encoded string goes into the lobby modoptions field when setting up a custom game. Every player joining receives the same tweak configuration through this encoded payload.
Reference: Unit and weapon definitions
Finding the right field to tweak means looking at the actual unit file in the BAR codebase. Each unit lives in the units folder, and weapon definitions reference reloadtime, damage ranges, and other combat properties in weapondefs. The Spring Engine wiki also documents standard fields like reloadtime, range, and area of effect that appear across most Spring-based games.
Understanding where each field lives saves time when building tweak strings.
Some rules cannot be bypassed
Certain game rules are locked by design. Commander transport stealing, for example, is disabled through a hard modoptions flag that cannot be toggled through tweakunits. The option lives in the core modoptions configuration and controls whether transport units can carry enemy commanders. That restriction exists to prevent a specific exploit pattern and is not something tweakdefs override.