XML: Basics

A few times, you’ve seen the note that texts and such will be set in “the XML file”, rather than within the editor itself. It’s now time to take a look at that XML file in depth to see how it’s made.

A short overview of XML: it’s a way of structuring information in plain text files such that it can be retrieved in a standard way. XML looks a lot like HTML, so if you already know some HTML, XML won’t be that difficult. The easiest way to learn how to create the XML files, is by looking at the XML files of the official scenarios. Usually you can copy one of the existing files and adapt it for your own scenario.

Tools needed

To edit the XML file, you need a simple text editor. Notepad will do the job, though you might want to get a more advanced editor that can highlight XML. Notepad++ is a light-weight editor that is more than adequate for the job.

Basic structure

The basic structure of the XML file is the following:

<?xml version="1.0" encoding="utf-8"?>
    <String id="IDENTIFIER_1">some value</String>
    <String id="IDENTIFIER_2">some other value</String>

The first line is the default XML preamble, specifying the encoding used in the file. Normally this doesn’t matter much, but if you’re developing a scenario that will have non-ascii characters in it, you must save the XML as UTF-8 text file.

The second file is the start tag of the file: it can be anything, but this is usually the name of the scenario, with any non-alphanumeric characters removed from it. For example, for the scenario “Colonia Agrippina”, this would become <ColoniaAgrippina>. Make sure this tag matches the tag at the very bottom: </ScenarioName>

The <String id=“ID”>CONTENT</String> lines are the actual values. The ID is the identifier used for this piece of text, and is largely determined by the game. CONTENT is the text itself. This text can be anything, with some exceptions: some characters cannot be used directly and have to be “escaped” in the following way:

If you want: type:
< &lt;
> &gt;
& &amp;
line break \n

Basic scenario info

A very bare XML file looks like this:

<?xml version="1.0" encoding="utf-8"?>
    <String id="SCENARIONAME">[The name of the scenario]</String>
    <String id="OVERVIEW">[mission briefing/introduction]</String>
    <String id="WIN">[Victory text]</String>
    <String id="LOSE">[Lose text]</String>
    <String id="POPULATION">[value]</String>
    <String id="FAVOR">[value]</String>
    <String id="CULTURE">[value]</String>
    <String id="PROSPERITY">[value]</String>
    <String id="SECURITY">[value]</String>

The following table gives an overview of where each of the texts is displayed. The term “intro screen” refers to the screen the player sees before really loading the scenario.

  • SCENARIONAME: Shown at the top of the intro screen
  • BRIEFING: The main body of text on the intro screen
  • POPULATION, FAVOR, CULTURE, PROSPERITY, SECURITY: Shown at the bottom of the intro screen
  • WIN: the text shown on the screen the user sees when the scenario has been won
  • LOSE: the text shown on the screen the user sees when he or she loses the scenario (due to low favor or other causes)

Note that the XML only represents the text used in the game: it's possible to set the goal for FAVOR to "50" in the XML file, while the actual rating goal is set to 70. The game will then not look at the XML file to determine victory. An example of where this is used are the sandbox scenarios: the population requirement for those scenarios is set to "1,000,000" in the XML file, while there's no actual population goal set in the editor.

The next few pages deal with the rest of the XML file: the cities on the empire map, the requests, invasions, and additional events.

< Previous: victory conditions | Editor Home | Next: XML: empire sites and requests >