101.1 — Anatomy of a blueprint ID - The-Balthazar/SupCom-Mod-Tutorials GitHub Wiki

Blueprint ID's are unique string identifiers for blueprints. In cases where they aren't unique, one will replace the other based on load order. If one has Merge set to true, then it will be loaded afterwards and will only overwrite values in the former as defined in the latter as defined in detail here.

There are three types of automatically assigned blueprint ID's in Supreme Commander, all are functionally just lowercase strings derived from the blueprint file path, and can be overwritten by defining BlueprintId in the blueprint.

Short ID's

Short ID's are used by units. They are derived from the lowercase source path of the blueprint with the regex ^.*/([^/]+)_[a-z]+%.bp$, with it falling back to the lowercase source if that fails to match. For example a blueprint with the filename UEL0001_unit.bp will have the resulting ID uel0001. The actual breakdown of the regex is:

  • ^ match the start of the string.
  • .*/ match any character (.) any number of times (*) up until (implicitly) the last / character.
  • ([^/]+) match and capture (()) anything that isn't a / ([^/]) one or more times (+).
  • _[a-z]+ match (implicitly the last instance of) the character _ followed by one or more (+) of any letter from a-z ([a-z]).
  • %.bp match the literal characters .bp.
  • $ match the end of the string.

Unit ID naming convention

It's important to note that the following is only a convention and not required for any functionality, except in some very rare cases that probably wont matter to you. So while not generally required, it is recommended if you want others to be able to easily navigate your blueprint files.

The majority of Supreme Commander unit ID's use 7 character strings that indicate a lot of information about the unit in question. In order this breaks down to:

  • Source
  • Faction
  • Motion
  • Category
  • Tech
  • Identifier

Civilian and operation units; units specific to campaign missions and scenarios, often disregard many of these.

Source

  • u: originating from the first game.
  • d: from a downloadable patch.
  • x: from Forged Alliance, internally called xpack 1.

When choosing a source character for you it is generally recommended that you pick a value that is less likely cause accidental collisions with other mods especially large or popular ones. u and x are commonly used by a lot of mods due to being common default values, s is used by BrewLAN and all of its related mods, and b is used by BlackOps.

While generally a letter, numbers and a lot of symbols are also valid and are extremely uncommon. If you do use a number or a symbol, it's important to also note that Lua variable names can't start with numbers or symbols other than underscore _, however a unit script's TypeClass value does not need to match the unit ID and can basically be any valid Lua variable name since they only exist within the scope of that units script file.

It is also recommended that when you pick a character, you use the same character for all of your mods. The reason being, it is much easier for you to ensure that non of your mods have collisions within themselves than it is for other people to cross reference all of your mods separately. A good example of this is, I, the author of BrewLAN originally had each of my separate unit mods have a different letter of the alphabet, after around my 3rd or 4th I quickly realised that this was setting up a minefield for anyone that wanted to maintain compatibility with my mods. I currently have at least 13 unit mods. If they each had a separate letter that's half the alphabet. It also meant that to maintain consistency if I moved a unit between my mods I'd have to change its ID, and that can break a lot of things internally if you miss something.

Faction

  • a: Aeon.
  • e: UEF.
  • r: Cybran.
  • s: Seraphim.

Motion

  • a: Aircraft.
  • b: Building.
  • c: Civilian.
  • l: Land.
  • s: Sea.

Category

  • 0: Factory.
  • 1: Economic.
  • 2: Weapon.
  • 3: Intelligence.
  • 4: Countermeasure.
  • 5: Miscellaneous.

Vanilla mobile units use 0, however it may be valuable to you to categorise mobile units under these as well, especially if you plan to make a lot.

Tech

  • 0: No defined tech; tech 0.
  • 1: Tech 1.
  • 2: Tech 2.
  • 3: Tech 3.
  • 4: Experimental.

Identifier

This is generally two numbers, but it's pretty arbitrary, and it's the one part of the ID that conveys no actual information on its own. There are some trends and consistencies within vanilla units, however for any identifiable rule there's several exceptions, and in places where it's not just sequential numbers it's possible that the gaps would be explained by changes in the plan after initially assigning the value.

Best advice for this is to be internally consistent. Use of letters and numbers is also recommended, as this adds to uniqueness without sacrificing any collective intelligibility.

Examples

  • uel0001: From Supreme Commander, UEF, land, no defined tech level and/or tech 0, the first numbered unit: The UEF ACU.
  • xes0307: From Forged Alliance, UEF, naval, tech 3: The Neptune Class Battlecruiser; the only UEF T3 unit added in the expansion.
  • urb3104: From Supreme Commander, Cybran, structure, intel, tech 1?: Trick question; it's actually the Cybran Omni Sensor Array; potentially indicating that radar and omni sensors were once separate structure lines, before being merged during development.
  • xrb2308: From Forged Alliance, Cybran, structure, weapon, tech 3: HARMS.
  • xrb3301: From Forged Alliance, Cybran, structure, intel, tech 3: Soothsayer.

Long ID's

Long ID's are used by mesh blueprints, and consist of the full path to the blueprint relative to the game root in lowercase, without the .bp extension. There is little to no consistency with naming conventions of predefined mesh blueprints except where following the naming conventions of what they are a mesh of.

Most mesh blueprints are generated on game launch from the Mesh section of blueprints in blueprints.lua. The resulting ID's of these blueprints are then stored at:

  • bp.Display.MeshBlueprint
  • bp.Display.MeshBlueprintWrecked
  • bp.Display.BuildMeshBlueprint

And swapped between as required. With the resulting mesh ID's, in the case of uel0001, looking like:

  • /units/uel0001/uel0001_mesh
  • /units/uel0001/uel0001_mesh_wreck
  • /units/uel0001/uel0001_mesh_build

'Backwards compatible' ID's

All other blueprint types use this longer form of ID; longer than long ID's because they also include the .bp extension. This applies to:

  • Props.
  • Projectiles.
  • Trail Emitters.
  • Emitters.
  • Beams.

For both long ID's and the even longer 'backwards compatible' ID's, given that they include the full path to them in the ID, including the /mods/ folder for mod blueprints, and are only visible in game through developer tools, having any kind of globally applied consistency is only important if you personally care.

Projectile naming conventions

Projectiles generally follow the convention of three-letter-code, name, number. The three letter code breaks down to:

  • Faction.
  • Weapon category.

Faction

It is important to note that these match script class faction letters, not unit ID faction letters:

  • a: Aeon.
  • c: Cybran.
  • s: Seraphim.
  • t: UEF.

Weapon category

  • aa: Anti-air.
  • an: Anti-naval.
  • bo: Bomb.
  • df: Direct fire.
  • if: Indirect fire.
  • im: Countermeasure.

Only Seraphim use BO; bombs from other factions use IF.

Examples

  • /effects/emitters/aeon_build_beam_01_emit.bp
  • /env/common/props/massDeposit01_prop.bp
  • /projectiles/TANAnglerTorpedo02/TANAnglerTorpedo02_proj.bp