Basic modding guide

Important

When playing in a public lobby, make sure the players actually want to play with mods. Not everyone does, and not everyone can be convinced. In addition, you will need to be the lobby boss to be able to set modoptions and/or apply tweaks.

Get started

If you are new to the game's files, the first two steps may be the most cumbersome:

Find the unit's internal def name. Search the units.json file in your language (here it is in English) for the unit name to find its "internal" name. For example, the Pawn is named armpw.
- The other language files are in their own folders on github.
Check the unit's base stats. Find the file matching the unit's internal name in the unit directory. Read over the entire file before deciding on your changes. For example, the Pawn's def file is armpw.lua.
- You can search for a file by pressing t while browsing the BAR repository on github.
- To dive deeper into unit stats, you can reference the SpringRTS wiki.
- To dive deeper into weapon stats, use the new RecoilEngine docs instead.
Decide on your format. You can create your mod as either a tweakunits or a tweakdefs. Relatively few, focused changes are better off using tweakunits, which shows individual changes very clearly. Large numbers of changes belong in a tweakdefs, which can make mass edits via code.

Tweakunits: Make specific changes to specific units

This is the most simple, open, and direct way to mod in Beyond All Reason.

Create a file containing a Lua table. Lua's table syntax is simple but picky, so ask for help if you get stuck. For now, here is a primer containing all you need to know:

A table is a collection of data inside braces with named keys that are assigned values, like { key = value }. Tables can act like values, too, meaning that tables can contain other tables. For example, in { a = 1, b = {} }, the key b is assigned its own, empty table.

You make changes to a unit by listing their internal name and assigning it a table containing the new values you want. For example, let's change the Pawn's metal cost to 10:
```
{
  armpw = { metalcost = 10 }
}
```
To make multiple changes, you need to add commas to separate each assigned value. It is good practice to add trailing commas after every table and key-value pair inside the main, outer table, like so:
```
{
  armpw = { metalcost = 10, energycost = 10, },
  corak = { metalcost = 10, energycost = 10, },
}
```
If you don't have much experience with modding, ask for help in the modding channel on BAR's Discord server.
Encode the table. Copy and paste your tweak into the top field on base64encode.org. Tick the box labeled "Perform URL-safe encoding", then press the button labeled Encode.
Become the lobby boss. When playing online on a multiplayer server, you need to do this step. Type !boss in the lobby chat/console and press Enter to send the command.
Apply the tweakunits. Copy the encoded result (it will look like gibberish) you got from base64encode.org. Type !bset tweakunits <your encoded text> in the lobby chat/console, replacing <your encoded text> (do not include the brackets) with the copied text. Hit enter to send the command to the server.

Tweakdefs: Make mass changes very efficiently

This type of tweak requires basic knowledge of the Lua programming language (and, in rare cases, the oddities of Beyond All Reason's inner workings). Once you are used to these things, though, tweakdefs become a powerful tool for rapid iteration.

Download more computer. Download a code editor like VS Code and add a Lua language extension to identify basic syntax errors and help you to correct them. This is exceedingly easy to do even for non-developers. You have no excuse. Please do this step. The human brain is oblivious to its own typos. It needs the assistance of the computer.
Write the shortest possible Lua file to test. You can loop through every single unit definition, filter for the ones that you want, and make changes. For your first attempt, that is plenty.

For example, we can set the metal cost of all units to 10 unless they are tech-level 3:
```
for name, unitDef in pairs(UnitDefs) do
  -- If the sub-table does not exist, then nor do any of its values. QED.
  if not unitDef.customparams or unitDef.customparams.techlevel ~= 3 then
      unitDef.metalcost = 10
  end
end
```
Encode the script. Copy and paste your tweak into the top field on base64encode.org. Tick the box labeled "Perform URL-safe encoding", then press the button labeled Encode.
Become the lobby boss. When playing online on a multiplayer server, you need to do this step. Type !boss in the lobby chat/console and press Enter to send the command.
Apply the tweakdefs. Copy the encoded result (it will look like gibberish) you got from base64encode.org. Type !bset tweakdefs <your encoded text> in the lobby chat/console, replacing <your encoded text> (do not include the brackets) with the copied text. Hit enter to send the command to the server.

Multiple tweaks

You can change the final step in the previous sections slightly to apply more than one tweak:

Apply multiple tweaks. Using the console method and the !bset command, you can enter up to nine distinct tweakunits (and/or tweakdefs). To do so, add an increasing number after tweakunits (or tweakdefs) for each additional tweak. For example, tweakunits1 and tweakunits2, or tweakdefs1 and tweakdefs2.
Advanced multi-tweak drifting. You can prepare your commands ahead of time and enter them quickly by placing each !bset command on its own line. The server knows how to split on newlines and parse each tweak separately. You still need to number them and encode the text properly, of course.

Additional References

Guides

ZK Guide

Examples

Tweaks by @badosu:

Reduce arty dmg by 10%: tweakunits
Make t2 more expensive but stronger: tweakdefs
Decrease efficiency of energy conversion by 20%: tweakdefs

Tweaks by @efrec:

DUST-UP T1, a horribly over-wrought tweakdefs

efrec/how-to-tweak.md