Creating a new unit

abc013 edited this page Sep 2, 2016 · 11 revisions
Clone this wiki locally

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