Scripting: the basics

Some of the more exciting things possible in Caesar IV are set up using the script file. These pages only cover the basic possibilities of scripting, intended for people without any programming knowledge. For more advanced scripting, I refer you to the Scripting Guide by Hieronymus, which lists all methods available to the script to hook into the game.

The script files that belong to the scenarios shipped with the game are also a good reference of what can be
done. If you want to do more with the script file, you might want to take a look at the script files for the
tutorial (Kingdom) missions, since scripting is used extensively there to track and guide the user’s progress.

The script

The script that belongs to the scenario should have the same filename as the scenario, with a “.cs” extension. If the scenario is saved as “Colonia Agrippina.scn”, the script file that belongs to it should be saved as “Colonia Agrippina.cs”. CS stands for “C-Sharp” (C#), the programming language in which the script is written.

This file is a plain text file. You can edit it with a text editor such as Notepad, though I recommend using Notepad++ for easier editing.

To get your script up and running using these pages, you don’t need programming knowledge, though you should know a few things:

  • Lines starting with two slashes (//) are comments: they are just for the programmer to add notes.
  • Throughout the scripting pages, I will use the term “code” to refer to a few lines within the script

The Script Skeleton

The following code is the basic “skeleton” for the script. When you start writing the script, you should copy this and save it as .cs file:

using System;
using RomeScriptInterfaces;
using Scripts;

namespace Scripts
{
  [Serializable]
  public class <SCENARIO_NAME> : ScriptServer.IScript
  {
    // Variables section. Add new variables below this line
    
    // End of variables section
    
    // This is the main script loop
    public void Run(object gameInterface)
    {
      IGameQueryInterface gameQueryInterface =
        (IGameQueryInterface)gameInterface;
      switch (gameQueryInterface.RunReason)
      {
        case RunReason.kTick:
          OnTick(gameQueryInterface);
          break;

        case RunReason.kOnBeginScenario:
          OnBeginScenario(gameQueryInterface);
          break;

        case RunReason.kOnLoadScenario:
          OnScenarioLoad(gameQueryInterface);
          break;
      }
    }
    
    void OnScenarioLoad(IGameQueryInterface game)
    {
      game.ScriptDone = true;
    }

    void OnBeginScenario(IGameQueryInterface game)
    {
      // OnBeginScenario() method
      
      // End of OnBeginScenario() method
    }

    void OnTick(IGameQueryInterface game)
    {
      // OnTick() method
      
      // End of OnTick() method
    }
  }
}

This skeleton has one ‘placeholder’: <SCENARIO_NAME>. If you see a name surrounded by < and > in pieces of code, it means you have to replace it (including the < and >) with something else. In this case, you should put the scenario’s name here, but without any spaces or other characters that are not letters or numbers.

This skeleton doesn’t do anything and you won’t notice anything in the game. To make the script do something, you will need to add code to various places in the file. On the following pages, I will instruct you to add code to either “the variables section” or “the XYZ method”.

The variables section
To add variables, locate the comment near the top of the script saying “Variables section. Add new variables below this line”. To add the variables, just add them below that line. If you need to add multiple variables (one for the earthquake, and one for the standard wages, for example), just place them below each other: the order in which you place them doesn’t matter.

The XYZ method
… where XYZ is either “OnTick()” or “OnBeginScenario()”. These two methods are clearly marked in the skeleton by two comments: add the code between these two comments. Again, if you need to add multiple pieces of code to the same method, just place them below each other.

You now know enough to start with the first simple additions to the script on the next page!

< Previous: XML: invasions and events | Editor Home | Next: scripting events >