Avaiable since Beta-Release 3

If you need a function for a script. You may kindly ask me and i add it to the documentation if it exists. :)

For debugging and testing take a look here

For Variable Support take a look here

What are Game Scripts?

Game Scripts are the method of adding additional effects to a game. Like dialogues, spawning units or adding additionl victory conditions or some fency animations and a lot more stuff. In the editor it's recommended to have the selected script path to be relative to the Commander Wars executable.

A template for game scripts can be found in the template folder of a release

Note The name of the javascript name must be "gameScript"

var Constructor = function()
{
    this.immediateStart = function()
    {
        // called to check if the game should start immediatly
        return false;
     };

    this.victory = function()
    {
        // called when a player wins
    };
    this.gameStart = function()
    {
        // called before a game starts
    };
    this.actionDone = function()
    {
        // function called after all animations are finished
    };
    this.turnStart = function(turn, player)
    {
        // called at the start of each players turn
    };
}

Constructor.prototype = BASEGAMESCRIPT;
var gameScript = new Constructor();

Overview of the most important functions

This section shows you a list of examples on how to use the game script feature. On top you may check out the map folder or co-scripts or game action scripts for other game script examples. This section won't cover everything possible with the gamescript feature. Since all functions of units, map buildings etc. that are in the public slots: section of the heades can be used to get information about the current game state or to modify it. This is a powerfull tool to create your own map with additional features.

Start of Game functions

You could change the GameRules at any time but it's recommended to do it in the gameStart callback function.

this.gameStart = function()
{
    // called before a game starts
    //we're going to set the game rules here.
    map.getGameRules().setNoPower(true); // no co power
    map.getGameRules().setRandomWeather(false); // no random weather
    map.getGameRules().setFogMode(GameEnums.Fog_Off); // no fog of war or GameEnums.Fog_OfWar -> for on
    // map.getGameRules().changeWeatherChance("WEATHER_1SUN", 90); // sets the weather chance of sun to 90. The actual chance is the the value divided through the sum of all chances
    // here we decide how you can win the game
    map.getGameRules().addVictoryRule("VICTORYRULE_NOUNITS"); // win by destroying all units
    map.getGameRules().addVictoryRule("VICTORYRULE_NOHQ"); // win by capturing all hq's of a player
    // since not all units have the same fuel, ammo etc on each mod. It may be useful to refuel them.
    // you can do that for all units with this command.
    map.refillAll();
};

Checking for a certain turn:

// check if it's day 1
if (map.getCurrentDay() === 1)
{
}

Most times you wanna create some dialogs. This is how you can queue and create Dialog's

// moods are GameEnums.COMood_Normal, GameEnums.COMood_Happy, GameEnums.COMood_Sad
var dialog1 = GameAnimationFactory.createGameAnimationDialog(
                    qsTr("They're... They're stronger than we had anticipated..."),
                    "co_officier_bh", GameEnums.COMood_Normal, PLAYER.getDefaultColor(4));
var dialog2 = GameAnimationFactory.createGameAnimationDialog(
                    qsTr(" I don't want excuses! I want victory!"),
                    "co_random", GameEnums.COMood_Normal, PLAYER.getDefaultColor(4));
dialog1.queueAnimation(dialog2);

• Replace the text inside qsTr("My Message") with the dialog text
• Replace "co_officier_bh" with the co you want check out the co files for the id's.
• Replace COMood_Normal with the face Normal, Sad or Happy
• Replace the number inside PLAYER.getDefaultColor(4) with the Army number you want to show where: 0 = OS, 1 = BM, 2 = GE, 3 = YC and 4 = BH

Spawning units is another important thing you may come across several times. This can be done by the following function. The return value is the spawned unit which you may modify further.

// spawns a unit
// at x, y coordinates starting at 0, 0
// unit type, id of the unit checkout the unit scripts to get the id's
// player get a player from the map
// check range the unit will be spawned on an empty field that can be crossed by the unit.
// This range is the test range where the game tries to spawn the unit. From 0 to anything
var unit = map.spawnUnit(4, 4, "INFANTRY", map.getPlayer(0), 5);

Accessing the campaign object if the script is used during a campaign and you want to store some data for the whole campaign. For example if Neotanks are unlocked or something like that. Returns the campaign object see game/campaign.h -> public slots: for callbacks you may use mostlikely you need the game variables

map.getCampaign();

Writing Dialogs

The easiest way to write dialogs for given turns and players is: The below script calls the initDialog on turn 1 of the first player and the day2Dialog on day 2 of the first player. Change the turn and the player depending, on which days you want a dialog

this.turnStart = function(turn, player)
{
    if (turn === 1 && player === 0)
    {
        gameScript.initDialog();
    }
    else if (turn === 2 && player === 0)
    {
        gameScript.day2Dialog();
    }
};

Example initDialog:

this.initDialog = function()
{
    var playername = globals.getSettings().getUsername();
    // moods are GameEnums.COMood_Normal, GameEnums.COMood_Happy, GameEnums.COMood_Sad
    var dialog0 = GameAnimationFactory.createGameAnimationDialog(
                qsTr("Sorry to keep you waiting!"),
                "co_max", GameEnums.COMood_Normal, PLAYER.getDefaultColor(0));
    var dialog1 = GameAnimationFactory.createGameAnimationDialog(
                qsTr("Who are you?"),
                "co_andy", GameEnums.COMood_Sad, PLAYER.getDefaultColor(0));
    var dialog2 = GameAnimationFactory.createGameAnimationDialog(
                qsTr("I'm Max, a CO in the Orange Star army. I was ordered to join you and ") + playername + qsTr(", so here I am."),
                "co_max", GameEnums.COMood_Normal, PLAYER.getDefaultColor(0));
    var dialog3 = GameAnimationFactory.createGameAnimationDialog(
                qsTr("A new CO, huh? What's so special about you?"),
                "co_andy", GameEnums.COMood_Normal, PLAYER.getDefaultColor(0));
    var dialog4 = GameAnimationFactory.createGameAnimationDialog(
                qsTr("You get right to the point, don't you, pal? I'm the king of direct combat. Need someone to mix it up? I'm the best! When I really get rolling, Max Force boosts my firepower even higher."),
                "co_max", GameEnums.COMood_Happy, PLAYER.getDefaultColor(0));
    var dialog5 = GameAnimationFactory.createGameAnimationDialog(
                qsTr("Cool!"),
                "co_andy", GameEnums.COMood_Normal, PLAYER.getDefaultColor(0));
    var dialog6 = GameAnimationFactory.createGameAnimationDialog(
                qsTr("This route looks tough!"),
                "co_max", GameEnums.COMood_Sad, PLAYER.getDefaultColor(0));
    var dialog7 = GameAnimationFactory.createGameAnimationDialog(
                qsTr("Well, Max. You're here to help, too?"),
                "co_nell", GameEnums.COMood_Normal, PLAYER.getDefaultColor(0));
    var dialog8 = GameAnimationFactory.createGameAnimationDialog(
                qsTr("How you doin', Nell? Now that I'm here, what's the kid gonna do?"),
                "co_max", GameEnums.COMood_Happy, PLAYER.getDefaultColor(0));
    var dialog9 = GameAnimationFactory.createGameAnimationDialog(
                qsTr("Oh, Max. You haven't changed a bit."),
                "co_nell", GameEnums.COMood_Normal, PLAYER.getDefaultColor(0));
    var dialog10 = GameAnimationFactory.createGameAnimationDialog(
                qsTr("But I must tell you, Andy's quite a capable CO. If you're not careful, he may just pass you up. See you later. Good luck!"),
                "co_max", GameEnums.COMood_Normal, PLAYER.getDefaultColor(0));
    // doing the queueing of the dialog
    dialog1.queueAnimation(dialog2);
    dialog2.queueAnimation(dialog3);
    dialog3.queueAnimation(dialog4);
    dialog4.queueAnimation(dialog5);
    dialog5.queueAnimation(dialog6);
    dialog6.queueAnimation(dialog7);
    dialog7.queueAnimation(dialog8);
    dialog8.queueAnimation(dialog9);
    dialog9.queueAnimation(dialog10);
};