Unit Making Guide

Before you begin:

The Primary Roadblocks to making a unit are: Idea, Model, Animation, and feasability.
Ideas is not what is lacking but rather people willing to Model and Animate them, with bots being the hardest to make due to walking animations.

BAR is currently not accepting new Units for Armada or Cortex.
BAR Legion faction while accepting Units needs units that replace current placeholders, primarly Tier 2 bots.
BAR Raptors may be accepting units, primarly models and animations as the current roster is 8 models spread over over a 100 units.
BAR Scavangers exists.

• Writen By Robert the pie (and i'm dyslexic so have fun)

---

What You Need:

Bar uses a lot of proprietary tools and file formats

To work on developing or maintaining a unit you will need:

• A local development environment, covered by this Repo's README github.com/beyond-all-reason/Beyond-All-Reason/README
• A text editor, such as Visual Studio Code (recommended) or Notepad++
  For VSCode it is recommended that you download: Lua, Lua Language Server coded by lua, By sumneko.
  In addition, go to File, Prefrences, Settings, and Search for "Lua Runtime Special", then Add Item, Key: VFS.Include, Value: require

To work on MODELS you will need:

• Blender 4.3 or newer
• Chris' Blender Extension: github.com/ChrisFloofyKitsune/s3o-blender-tools/releases
  Installation instructions are in the repo's readme
• and/or Beherith's OBJ2S3O Converter and UPSPRING (if anyone knows where to get a working copy)
• We have a Blender Template File with a shader that reads the DDS file formats to match that of the game, it can be found in our discord here: https://discord.com/channels/549281623154229250/1063217502898884701/1232098490113462323
• Alternatively you can attempt to manually create a shader that swaps Alpha to teamcolor, or remove it via another method.
• The textures for each faction can be found in your BAR.sdd folder, under unittextures, the files are:
  Armada: Arm_colour, Arm_normal, Arm_Diffuse.
  Cortex: cor_color, cor_normal, cor_diffuse.
  Legion: leg_color, leg_normal, leg_shader.

To work on ANIMATIONS you will need

• Beherith's BOS to COB compiler: github.com/beyond-all-reason/BARScriptCompiler
  Installation steps for VSCode and Notepad++ inside.
  It uses a c based programming language, with the only variable type being ints.
  You can find documentation for it here: springrts.com/wiki/Gamedev, under the heading of Animation of units, COB subheading specifically.

---

Introduction

Units are defined via a UnitDef file. This file defines the unit stats and properties, as well as references other files to put together the unit or properties that are shared across many units such as unit armour classes or for pathing meshes for specific unit sizes and traverse-ability.

A slightly outdated list of all unit defs can be found here on the old engine wiki: springrts.com/wiki/Gamedev:UnitDefs, our current version has renamed many if not all of these parameters to their lua game side equivalent unifying them (apart from captilization).

UnitDef

The general Structure of a UnitDef file is that you are to return a lua table containing tables of Unit Params that are keyed via the Unit's internal name. This file is a valid lua script, as such you can preform actual lua code in there, and even make some engine synced reads, to generate a Unit to your specifications, tho most often such setting based changes are done via BAR.sdd/gamedata/alldefs_post. To put these words into a perspective, the simplest form of a UnitDef looks like this:

return {
	internal_name = {
		-- Unit Params go here
	}
}

*old, todo: intergrate

Very draft, for now mostly a list of facets, many of these need to be expanded into specific subpages.

Ideally this should end up as more 'how to do it right' rather than 'this is how to find if you did it wrong'. Modelling in particular needs a huge writeup on considerations and practicalites.

To add later:

• Design guidelines, both role and visual.
• Initial balance considerations.
• Modelling specifics
• Loads of other things
• List of where X file actually is/what it does and why it matters
• List of outdated unitdef entries that should be linted out of new units

Hornet's Patent Unit Finalising Checklist

Modelling:

• All faces checked for front/back orientation?
• Does it have a dead model with correct textures?
• Unit model lighting added?

Unit defs:

• Does it have/need tracks?
• weapon names unique and sensible? correct target categories set?
• Is unit in all the correct categories?
• Movedef correct and added to the list in the movedef file?
• Armour defined correctly?

Animation:

• Are the death explosion animations correct?
• Does it have/need a death specific animation to transition to the wreck pose?
• Is firing animation & recoil correct? Does unit move/rock when firing?

BOS/COB:

• Is there a correct 'restore after delay' setup?
• Does the unit have/need damaged smoke states added?
• Does the unit have any idle animations, are they fully paused when it's trying to shoot? Eg, 'turret twitch' on AA
• Any shot/barrel glow lighting correctly hooked in?

Misc:

• Is unit size correctly defined in Upspring?
• Correct collision volumes, and aimpoints? (this absolutely needs a page to itself later)
• If a building, is there an AO plane made?
• If a constructor/factory, are all build options correct? Contrast with any opposing comparable units to try to be sure.

Integration:

• Sound effects correct, both in unitdef and the sound file?
• Legacy build menu order placement added and correct?
• Grid keys added?
• Unit build picture created, converted & added?
• Unit name and description defined in language definition file?
• Icon selected/created if applicable, and at correct scale?
• Does any behaviour or detailing require gadget work / any existing gadgets need to be updated with the new unit name?