Custom Unit

Notice: Modding tutorials assume you know at least the basics of coding or scripting. Commander Wars uses Javascript as the Scripting Language. In case you want to learn more about Javascript, you can check the tutorial here: Derek Banas' Javascript tutorial , purchase O'Reilly's excellent book on the subject JavaScript: The Definitive Guide, or check out W3 Schools Interactive Tutorials

Setup

In this tutorial, you will learn how to create a custom Mech Unit with the movement range of Infantry and 6000g cost, with the ability to hide, which we will call 'Night Stalker'. The Night Stalker unit can only be attacked by other Infantry Units while hidden.

To start off, create a folder named nightstalker inside the mods folder of the game, and inside of it the following folder and file structure:

.
├── mod.txt
└── scripts
    ├── battleanimations
    │   └── BATTLEANIMATION_NIGHT_STALKER.js
    ├── building
    │   └── factory.js
    └── units
        └── night_stalker.js

This file structure is important as the game detects the folders to make changes to the game.

Inside the mod.txt add the following:

name=Night Stalkers
description=Custom Mech Units, created for the wiki tutorial.
version=1.0.0
compatible_mods=
incompatible_mods=
required_mods=
cosmetic=false

This makes the mod visible to the game under Options>Mods

Initializing the unit

Initialize the code of the Night Stalker by putting this inside the night_stalker.js:

  var Constructor = function()
{
    this.init = function(unit)
    {
        unit.setAmmo1(10);
        unit.setMaxAmmo1(10);
        unit.setWeapon1ID("WEAPON_MECH_MG");

        unit.setAmmo2(3);
        unit.setMaxAmmo2(3);
        unit.setWeapon2ID("WEAPON_BAZOOKA");

        unit.setFuel(70);
        unit.setMaxFuel(70);
        unit.setBaseMovementPoints(3);
        unit.setMinRange(1);
        unit.setMaxRange(1);
		unit.setVision(2);
    };
}

Constructor.prototype = UNIT;
var NIGHT_STALKER = new Constructor();

The setWeapon1ID() and setWeapon2ID() can take a string of any of the [ https://github.com/Robosturm/Commander_Wars/tree/98fb5833b1a0ab6378589e251a43d276462c66b2/resources/scripts/weapons available weapons in the game]. One can also create a custom weapon, but that will not be covered in this tutorial.

Adding the Army Data and Unit Costs

Up next we add the base costs as well as the Army data of the unit

this.getBaseCost = function()
    {
        return 6000;
    };

    this.armyData = [["os", "os"],
                     ["bm", "bm"],
                     ["ge", "ge"],
                     ["yc", "yc"],
                     ["bh", "bh"],
                     ["bg", "bg"],
                     ["ma", "ma"],
                     ["ac", "ac"],
                     ["bd", "bd"],
                     ["dm", "dm"],
                     ["gs", "gs"],
                     ["pf", "pf"],
                     ["ti", "ti"],];

    this.animationData = [["os", [1]],
                          ["bm", [1]],
                          ["ge", [1]],
                          ["yc", [1]],
                          ["bh", [1]],
                          ["bg", [2]],
                          ["ma", [2]],
                          ["ac", [2]],
                          ["bd", [2]],
                          ["dm", [2]],
                          ["gs", [2]],
                          ["pf", [2]],
                          ["ti", [2]],];

The array entries correspond to the names of the factions of the game. These can be customized as well, but won't be covered in this tutorial.

Loading Sprites

This part of the code loads the sprites of the unit. We will be using the same parameters as the sprites of the Mech unit.

this.loadSprites = function(unit)
    {
        // none neutral player
        var player = unit.getOwner();
        // get army name
        var armyName = Global.getArmyNameFromPlayerTable(player, MECH.armyData);
        // load sprites
        unit.loadSpriteV2("mech+" + armyName +"+mask", GameEnums.Recoloring_Matrix);
        unit.loadSpriteV2("mech+" + armyName, GameEnums.Recoloring_None);
    };

Movement and Actions

This code sets the movement type of the unit. You may also choose among other movement types.

 this.getMovementType = function()
    {
        return "MOVE_FEET";
    };
    this.actionList = ["ACTION_STEALTH", "ACTION_UNSTEALTH","ACTION_FIRE", "ACTION_MISSILE", "ACTION_CAPTURE", "ACTION_JOIN", "ACTION_LOAD", "ACTION_WAIT", "ACTION_CO_UNIT_0", "ACTION_CO_UNIT_1"];

The action array is the same as the original Mech unit, however by adding the ACTION_STEALTH and ACTION_UNSTEALTH these actions will be added as well to the unit in game.

Walking animation

We will also copy the Mech's walking animation, this shows when the unit is ordered to moved in game

 this.doWalkingAnimation = function(action, map)
    {
        var unit = action.getTargetUnit();
        var animation = GameAnimationFactory.createWalkingAnimation(map, unit, action);
        // none neutral player
        var player = unit.getOwner();
        // get army name
        var armyName = Global.getArmyNameFromPlayerTable(player, MECH.armyData);
        var data = Global.getDataFromTable(armyName, MECH.animationData);
        animation.loadSpriteV2("mech+" + armyName + "+walk+mask", GameEnums.Recoloring_Matrix, data[0]);
        animation.setSound("moveboots.wav", -2);
        return animation;
    };

Name and unit description

These functions set the name and unit description. The Description uses HTML syntax for highlighting

this.getName = function()
    {
        return qsTr("Night Stalker");
    };

    this.getDescription = function()
    {
        return qsTr("<r>Attack power high. Can </r><div c='#00ff00'>capture </div><r> bases and hide. </r><div c='#00ff00'>Vision +3 </div><r> when on mountains.</r>");
    };

Can move and fire

The following function defines if a unit can attack and move on the same turn. It's set to false for indirect units

this.canMoveAndFire = function()
    {
        return true;
    };

Setting the unit type

This sets the group of units it belongs to, for a list of possible units type check Unit Types

this.getUnitType = function()
    {
        return GameEnums.UnitType_Infantry;
    };