Creating a new unit

This guide was last updated 2016-09-02 and works for the 20160508 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 in parts. Lets open the rules/ships.yaml file now, and search for MSUB. Copy the first part of 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.

MSUB:
	Inherits: ^Ship
	Buildable:
		Queue: Ship
		BuildPaletteOrder: 60
		Prerequisites: ~spen, stek, ~techlevel.unrestricted
	Valued:
		Cost: 2400
	Tooltip:
		Name: Missile Submarine
		Description: Submerged anti-ground unit armed with\nlong-range ballistic missiles.\nCan detect other submarines.\n  Strong vs Buildings, Ground units\n  Weak vs Naval units, Aircraft\n  Special Ability: Submerge
	Health:
		HP: 400
	Armor:
		Type: Light
	Mobile:
		ROT: 3
		Speed: 42
	RevealsShroud:
		Range: 6c0

There we go, now to edit the code.

MSUB is the code name for the unit. This is what every trait does:

Trait	Property	Description	Link
Inherits	-	From which unit definition are traits inherited. (E.g. from ^Ship which is inside defaults.yaml.)	-
Buildable	-	The unit is buildable.	Traits#Buildable
Buildable	Queue	What tab the unit is in. (E.g. the ship/boat tab.)	^
Buildable	BuildPaletteOrder	Where the icon is in the gridview. Lower number = Top-Left, Higher number = Bottom-Right.	^
Buildable	Prerequisites	The prerequisites needed to build this unit. (Check the ProvidesPrerequisite traits inside buildings.yaml for code names.)	^
Valued	Cost	Cost of the unit. Build time depends on how much do it cost, except CustomBuildTimeValue is used.	Traits#Valued
Tooltip	Name	Name of the unit.	Traits#Tooltip
Tooltip	Description	Detailed information about the unit.	^
Health	HP	How many health points the unit has.	Traits#Health
Armor	Type	Which armor the unit has. (By default there is: None, Wood, Light, Heavy and Concrete)	Traits#Armor
Mobile	ROT	How Long does it take to rotate.	Traits#Mobile
Mobile	Speed	The speed of the Unit.	^
RevealsShroud	Range	How far the Unit can see. (See World-Coordinate-System for more information about cells.)	Traits#RevealsShroud

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

OHIOSUB:
	Inherits: ^Ship
	Buildable:
		Queue: Ship
		BuildPaletteOrder: 60
		Prerequisites: ~syrd, atek,  ~techlevel.unrestricted
	Valued:
		Cost: 240
	Tooltip:
		Name: 'Ohio'-Class Ballistic Sub
		Description: Submerged anti-ground unit armed with \nlong-range ballistic missiles.\n  Strong vs Buildings\n  Weak vs Everything\n  Special Ability: Submerge
	Health:
		HP: 2000
	Armor:
		Type: Wood
	Mobile:
		ROT: 2
		Speed: 70
	RevealsShroud:
		Range: 2c0
	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. Copy this part of MSUB and paste it below our new code.

	Targetable:
		TargetTypes: Ground, Water, Repair
		UpgradeTypes: underwater
		UpgradeMaxEnabledLevel: 0
	Targetable@UNDERWATER:
		TargetTypes: Underwater, Repair
		UpgradeTypes: underwater
		UpgradeMinEnabledLevel: 1
	Cloak:
		CloakTypes: Underwater
		InitialDelay: 0
		CloakDelay: 100
		CloakSound: subshow1.aud
		UncloakSound: subshow1.aud
		WhileCloakedUpgrades: underwater
		Palette: submerged
	Armament:
		Weapon: SubMissile
		LocalOffset: 0,-171,0, 0,171,0
		FireDelay: 2
	AttackFrontal:

Trait	Property	Description	Link
Targetable	-	The Unit is targetable.	Traits#Targetable
Targetable	TargetTypes	What can attack the Unit when this Targetable definition is active. (Repair: Mechanics can repair the Unit.)	^
Targetable	UpgradeTypes	Which Upgrade(s) is/are required that this definition is active.	^
Targetable	UpgradeMinEnabledLevel	The minimum of Upgrades needed to have this definition active.	^
Targetable@UNDERWATER	-	Basically the same as the one above. The Upgrades on this one only make it active when submerged. The definition above is active when surfaced.	^
Cloak	-	The unit is cloaked.	Traits#Cloak
Cloak	CloakTypes	The CloakType of the Unit.	^
Cloak	Initialdelay	The delay (in ticks) the unit cloaks after being built. (0 = Comes out of factory cloaked.)	^
Cloak	CloakDelay	The delay (in ticks) before the unit can re-cloak.	^
Cloak	CloakSound	Sound to use when the unit cloaks. Put custom files in bits folder (for mods) or in the map folder (for maps).	^
Cloak	UncloakSound	Sound to use when the unit uncloaks.	^
Cloak	WhileCloakedUpgrades	Which Upgrade(s) does the unit have while cloaked. (Means the Unit grants the underwater upgrade when it's cloaked which also activates the second Targetable definition.)	^
Cloak	Palette	Which (Color-)Palette is used while being cloaked.	^
Armament	-	The unit is armed.	Traits#Armament
Armament	Weapon	The weapon of the unit.	^
Armament	LocalOffset	Location where the unit fires from.	^
Armament	FireDelay	Time (in frames) until the weapon can fire again.	^
AttackFrontal	-	The unit doesn't have a turret so it needs to face the target to attack.	Traits#AttackFrontal

Please do not change things here. It'll be cloaked and it can target water and ground with the weapon we copied from MSUB.

We're going to the next part of our MSUB. Again, copy the code and paste it below the code we just added.

	SelectionDecorations:
		VisualBounds: 44,44
	AutoTarget:
		InitialStance: HoldFire
		InitialStanceAI: ReturnFire
	DetectCloaked:
		CloakTypes: Underwater
		Range: 4c0
	RenderDetectionCircle:
	Explodes:
		Weapon: UnitExplodeSubmarine
		EmptyWeapon: UnitExplodeSubmarine
	-MustBeDestroyed:

Trait	Property	Description	Link
AutoTarget	-	The unit picks targets automatically.	Traits#AutoTarget
AutoTarget	InitialStance	The Stance of the unit. (Possible values are HoldFire, ReturnFire, Defend and AttackAnything)	^
AutoTarget	InitialStanceAI	The Stance of the unit when an AI controls it.	^
SelectionDecorations	VisualBounds	The size of the unit's selection box.	Traits#SelectionDecorations
DetectCloaked	-	The unit is able to detect cloaked/submerged units.	Traits#DetectCloaked
DetectCloaked	CloakTypes	The types of cloak the unit detects.	^
DetectCloaked	Range	The radius in which the unit detects cloaked units.	^
RenderDetectionCircle	-	Shows a circle which resembles the Range of DetectCloaked.	Traits#RenderDetectionCircle
Explodes	-	The unit explodes when it dies.	Traits#Explodes
Explodes	Weapon	The "Weapon" the unit uses when it explodes (for example the artillery explosion).	^
Explodes	EmptyWeapon	The "Weapon" the unit uses when it explodes and has no ammo/is reloading.	^
-MustBeDestroyed	-	The unit doesn't have to be destroyed to end the game. (- means that we remove this trait definition we inherited from ^Ship.)	Traits#MustBeDestroyed

That's it for our code. The final code should look like this:

	OHIOSUB:
		Inherits: ^Ship
		Buildable:
			Queue: Ship
			BuildPaletteOrder: 60
			Prerequisites: ~syrd, atek, ~techlevel.medium
		Valued:
			Cost: 240
		Tooltip:
			Name: 'Ohio'-Class Ballistic Sub
			Description: Submerged anti-ground unit armed with \nlong-range ballistic missiles.\n  Strong vs Buildings\n  Weak vs Everything\n  Special Ability: Submerge
		Health:
			HP: 2000
		Armor:
			Type: Wood
		Mobile:
			ROT: 2
			Speed: 70
		RevealsShroud:
			Range: 1c0
		RenderSprites:
			Image: MSUB
		Targetable:
			TargetTypes: Ground, Water, Repair
			UpgradeTypes: underwater
			UpgradeMaxEnabledLevel: 0
		Targetable@UNDERWATER:
			TargetTypes: Underwater, Repair
			UpgradeTypes: underwater
			UpgradeMinEnabledLevel: 1
		Cloak:
			CloakTypes: Underwater
			InitialDelay: 0
			CloakDelay: 100
			CloakSound: subshow1.aud
			UncloakSound: subshow1.aud
			WhileCloakedUpgrades: underwater
			Palette: submerged
		Armament:
			Weapon: SubMissile
			LocalOffset: 0,-171,0, 0,171,0
			FireDelay: 2
		AttackFrontal:
		SelectionDecorations:
			VisualBounds: 44,44
		AutoTarget:
			InitialStance: HoldFire
			InitialStanceAI: ReturnFire
		DetectCloaked:
			CloakTypes: Underwater
			Range: 4c0
		RenderDetectionCircle:
		Explodes:
			Weapon: UnitExplodeSubmarine
			EmptyWeapon: UnitExplodeSubmarine
		-MustBeDestroyed:

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
		AlliedMissiles: false

The unit will be able to deflect missiles in a range of 20 cells.

	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:
		ROT: 7
		Offset: 341,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 7, and the turret is offsetted by 341,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 weapon. # means you comment something and the game will ignore it.

	#Armament:
	#	Weapon: SubMissile
	#	LocalOffset: 0,-171,0, 0,171,0
	#	FireDelay: 2

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 explicitely 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).

What now?

Well, we gone through two ways to add a new unit. Now it's time for you to save all the edited files and test the game!

In depth guide by HSFOutcast (Edited by abc013 & abcdefg30).