Skip to content

Unit Making Guide

Jump to bottom Edit New page
Oliwier edited this page Dec 1, 2024 · 7 revisions

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.

What You Need:

Bar uses a lot of proprietary tools and file formats

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

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/549282804412710925/1259641075916603494
  • 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. It is also recommended to use other unit animation Scripts as refrence material.

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
	}
}

Modeling

Bar models are stored in a proprietary file format, .S3O, but we also support (wip) the .DAE file format for skinned meshes.
S3O stores and defines not only the meshe (3d model), but also:

  • the object hierarchy (toros has arm and arm has hand)
  • ambient occlusion (cheaper pre-caculated shadows)
  • the unit's texture 1 (faction textures + teamcolor in alpha) and texture 2 (material properties: roughness, reflectiveness, and glow)
    Unit Normals unfortunately need to be pointed to in the Unit Def file in the Custom Params

TODO: write how to use these tools: starting from a unit sketch, to a blockout, to finalizing the mesh, to texturing.

Animation

BAR's Animations are more than cosmetic, they are a part of the simulation. And some unit hitboxes may be model accurate rather than an encapsulating primitive shape.
A Unit's animation script affects the following parts of the simulation:

  • Provides a weapon's aim position, fire position.
    IT may also even delay an attack (g.g to wait for turret rotation) or prevent it for additional constraint.
    Some Weapons can be set up to care for the model's orinatation.
  • Defines if a unit is capable of currently building, or for factories defining where they build a unit.
  • Firing off not only special effects but also actual attacks.
  • Some collision points may be attached to animated points. In addition COB animations can upcall to synced LUA gadget space for other effects or information (LUS may natively call synced LUA functions)

BOS (COB):

.BOS is our proprietary animating language, it is based of decyphering old Total Anihilation games. It is more limited but still very capable and useful.
Everything in BOS is an int, from variables to unit pieces being referenced starting from 0, to rotations and positions being multiplied by massive constants to achive our needed level of accuracy. It does not feature Arrays but our compiler is capable of using headers as well as conditional defines to achive some level of modularity and reusability between diffrent units.
BOS needs to be compiled into COB (COmipled BOS)

BOS documentation

The following are some useful resources for animating a Unit for BAR or the spring game engine:

*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?
Add a custom footer
Add a custom sidebar
Clone this wiki locally