Creating a new unit

This guide was last updated 2022-01-18 and works for the 20210321 release.

This guide will be a in depth guide on how to create a new unit. It will be in two parts, the first part (the simple part) will explain how to clone a unit, this is good in the way that you do not have to modify the sequences files at all. The second part (the not so simple way) will explain how to create a new unit from scratch. The guide was done for mods based on Red Alert, but should work well with both C&C and D2k.

Cloning a unit (The simple way)

First we need to decide to clone a unit, for this example we will create a missile submarine for the allies based on real life OHIO-class Ballistic Submarine. First of all lets take a look at the code. Lets open the mods/ra/rules/ships.yaml file from where you installed the game, and search for MSUB. Copy the code text; you can implement your unit in a map or in the whole mod. If you want to have the submarine in the whole mod, post it at the bottom of the ships.yaml file. If you want to have it in a map, open the map's map.yaml and scroll to Rules: or open the map's rules.yaml, then paste it.

Scroll up to the start of your new code and lets get to editing it.

Note: If you are running a different release, some of these values may be different. It is fine, but if you copy this next section it might not work for your release.

MSUB:
	Inherits: ^Ship
	Inherits@AUTOTARGET: ^AutoTargetAllAssaultMove
	Buildable:
		Queue: Ship
		BuildAtProductionType: Submarine
		BuildPaletteOrder: 60
		Prerequisites: ~spen, stek, ~techlevel.high
		Description: Submerged anti-ground siege unit\nwith anti-air capabilities.\nCan detect other submarines.\n  Strong vs Buildings, Ground units, Aircraft\n  Weak vs Naval units\n  Special Ability: Submerge
	Valued:
		Cost: 2000
	Tooltip:
		Name: Missile Submarine
	UpdatesPlayerStatistics:
		AddToArmyValue: true
	Health:
		HP: 40000
	Armor:
		Type: Light
	Mobile:
		TurnSpeed: 12
		Speed: 42
	RevealsShroud:
		MinRange: 5c0
		Range: 8c0
		RevealGeneratedShroud: False
	RevealsShroud@GAPGEN:
		Range: 5c0
	Targetable:
		TargetTypes: WaterActor, Ship, Submarine, Repair
		RequiresCondition: !underwater
	Targetable@UNDERWATER:
		TargetTypes: Underwater, Submarine
		RequiresCondition: underwater
	Cloak:
		CloakTypes: Underwater
		InitialDelay: 0
		CloakDelay: 100
		CloakSound: subshow1.aud
		UncloakSound: subshow1.aud
		CloakedCondition: underwater
		Palette: submerged
		PauseOnCondition: cloak-force-disabled
	GrantConditionOnDamageState@UNCLOAK:
		Condition: cloak-force-disabled
		ValidDamageStates: Critical
	Armament@PRIMARY:
		Weapon: SubMissile
		LocalOffset: 0,-171,0, 0,171,0
		FireDelay: 2
	Armament@SECONDARY:
		Weapon: SubMissileAA
		LocalOffset: 0,-171,0, 0,171,0
		FireDelay: 2
	AttackFrontal:
		TargetFrozenActors: True
		ForceFireIgnoresActors: True
	AutoTarget:
		InitialStance: HoldFire
		InitialStanceAI: ReturnFire
	DetectCloaked:
		CloakTypes: Underwater
		Range: 4c0
	RenderDetectionCircle:
	Explodes:
		Weapon: UnitExplodeSubmarine
		EmptyWeapon: UnitExplodeSubmarine
	-MustBeDestroyed:
	Selectable:
		DecorationBounds: 44,44

At first it might look overwhelming, but trust me it all makes sense.

MSUB is the code name for the unit.

Next are Traits, to know what they do see traits. This page will be your bread and butter when modding.

Example of a few of the traits:

Trait	Property	Description	Link
Inherits	-	From which unit definition are traits inherited. (E.g. from `^Ship` which is inside `defaults.yaml`.)	-
Valued	Cost	Cost of the unit. Build time depends on how much do it cost, except BuildDuration is used.	Traits#Valued
Health	HP	Hit points of a unit.	Traits#Health

Our code should be changed to this, but of course you can change the speed and cost etc.:

OHIOSUB:
	Inherits: ^Ship
	Inherits@AUTOTARGET: ^AutoTargetAllAssaultMove
	Buildable:
		Queue: Ship
		BuildAtProductionType: Submarine
		BuildPaletteOrder: 60
		Prerequisites: ~syrd, atek, ~techlevel.high
		Description: Submerged anti-ground siege unit\nwith anti-air capabilities.\nCan detect other submarines.\n  Strong vs Buildings, Ground units, Aircraft\n  Weak vs Naval units\n  Special Ability: Submerge
	Valued:
		Cost: 2000
	Tooltip:
		Name: 'Ohio'-Class Ballistic Sub
	UpdatesPlayerStatistics:
		AddToArmyValue: true
	Health:
		HP: 30000
	Armor:
		Type: Wood
	Mobile:
		TurnSpeed: 12
		Speed: 60
	RevealsShroud:
		MinRange: 1c0
		Range: 2c0
		RevealGeneratedShroud: False
	RevealsShroud@GAPGEN:
		Range: 5c0
	Targetable:
		TargetTypes: WaterActor, Ship, Submarine, Repair
		RequiresCondition: !underwater
	Targetable@UNDERWATER:
		TargetTypes: Underwater, Submarine
		RequiresCondition: underwater
	Cloak:
		CloakTypes: Underwater
		InitialDelay: 0
		CloakDelay: 100
		CloakSound: subshow1.aud
		UncloakSound: subshow1.aud
		CloakedCondition: underwater
		Palette: submerged
		PauseOnCondition: cloak-force-disabled
	GrantConditionOnDamageState@UNCLOAK:
		Condition: cloak-force-disabled
		ValidDamageStates: Critical
	Armament@PRIMARY:
		Weapon: SubMissile
		LocalOffset: 0,-171,0, 0,171,0
		FireDelay: 2
	Armament@SECONDARY:
		Weapon: SubMissileAA
		LocalOffset: 0,-171,0, 0,171,0
		FireDelay: 2
	AttackFrontal:
		TargetFrozenActors: True
		ForceFireIgnoresActors: True
	AutoTarget:
		InitialStance: HoldFire
		InitialStanceAI: ReturnFire
	DetectCloaked:
		CloakTypes: Underwater
		Range: 4c0
	RenderDetectionCircle:
	Explodes:
		Weapon: UnitExplodeSubmarine
		EmptyWeapon: UnitExplodeSubmarine
	-MustBeDestroyed:
	Selectable:
		DecorationBounds: 44,44
	RenderSprites:
		Image: MSUB

What did we do? We changed the codename for the unit, made the prerequisites so instead of the soviet tech center and subpen, we need the allied tech center and the naval yard. And we changed the in-game name to a very detailed one. We changed health, speed, the revealshroud-range and the armor.

But why do we need RenderSprites: Image:? That's because our OHIOSUB has no sequences, so we are using the sequences of MSUB instead. You can use almost every other unit, for example Image: JEEP.

Lets head on to the next step, shall we. The above code will work and add a ballistic submarine for the allied factions. Now there are a lot of traits that the sub does not use (and cannot use), but there are some we can use. For example:

We can add JamsMissiles: to our code:

	JamsMissiles:
		Range: 20c0
		DeflectionRelationships: Neutral, Enemy

The unit will be able to deflect missiles in a range of 20 cells. We have to change relationships for the submarine to not jam itself. By default DeflectionRelationships is set to Enemy, Neutral, Ally as you can see in JamsMissiles.

	RenderRangeCircle:

This will add a range circle around your unit so you know exactly how far your unit can fire. A nice little function.

Turret code example:

	Turreted:
		TurnSpeed: 28
		Offset: 469,0,128
	Armament@PRIMARY:
		Weapon: Stinger
		LocalOffset: 0,-100,0, 0,100,0
		LocalYaw: 64, -64
	Armament@SECONDARY:
		Weapon: DepthCharge
		LocalOffset: 0,-100,0, 0,100,0
		LocalYaw: 80, -80
	Armament@TERTIARY:
		Weapon: StingerAA
		LocalOffset: 0,-100,0, 0,100,0
		LocalYaw: 64, -64
	AttackTurreted:

In this example I've taken the code from the allied Destroyer. It has a turret, turret rotation is 28, and the turret is offsetted by 469,0,128 from the center of the unit. Its primary weapon is a Stinger and the secondary weapon is a depth charge against subs. The tertiary weapon is for airunits (AA = AntiAir). You have to delete our old weapons. # means you comment something and the game will ignore it.

	#Armament@PRIMARY:
	#	Weapon: SubMissile
	#	LocalOffset: 0,-171,0, 0,171,0
	#	FireDelay: 2
	#Armament@SECONDARY:
	#	Weapon: SubMissileAA
	#	LocalOffset: 0,-171,0, 0,171,0
	#	FireDelay: 2
	#AttackFrontal:
	#	TargetFrozenActors: True
	#	ForceFireIgnoresActors: True

You can copy most traits from units that use and add it to your unit. If you want a unit that acts in a specific way try to think of a unit that already exist and mimic that. It's ALWAYS easier to copy something that already works than to make something from scratch.

Either way you're done. Save the file and close it down, test your new unit! :)

Creating a new unit from scratch

The not so simple way to do it. If you want to do this use the above example code of the Ohio Ballistic Sub. But do not add this code:

	RenderSprites:
		Image: MSUB

Remember if you want to create a unit from scratch you will need .shp files for the ingame unit and its icon. Put these in the bits folder (maps: in the map folder) and make sure they have the same name as your unit name code (In this example OHIOSUB.shp and OHIOSUBICON.shp)

Go into your sequence folder and open the right yaml file (in this case ships.yaml)

Search for the unit you cloned. In this case I searched for msub and found this, copy and paste it at the bottom (maps: sequences). Make the last code look like this:

	msub:
		idle:
			Facings: 16
		icon: msubicon
	ohiosub:
		idle:
			Facings: 16
		icon: ohiosubicon

Note: If you don't explicitly define a frame to start the animation with (e.g. Start: 1 to start with the second frame of the .shp file), the game will automatically use the first frame (= Start: 0 is default).