Part 1: Sending messages

There are four types of message you can send using scripting:

  1. The standard "pop-up" message you see when there are events such as wage changes or earthquakes.
  2. A variant of the standard "pop-up" message that is only recorded in the message log.
  3. A message in the style of the "tutorial" messages that appear in the tutorial missions that ship with the game.
  4. A "one-line" warning message that appears at the top of the screen.

The first three types of message are sent using the SendGameMessage method. The "one-line" message is sent using the SendWarningMessage method.

SendGameMessage(uint inCategory, uint inDisplay, ref string inTitle, ref string inText, ref string inSoundFilename)

This issues a message to the player, which is recorded in the message log, and may also be displayed on the screen.

The variable inCategory can take the following values:

   (uint)MessageCategory.kEpidemicsMessage
   (uint)MessageCategory.kFireCollapseMessage
   (uint)MessageCategory.kGodEventsMessage
   (uint)MessageCategory.kInvasionsMessage
   (uint)MessageCategory.kLocalEventMessage
   (uint)MessageCategory.kOrderRequestMessage

Usually the "Local Event Message" category will be used (testing with the other values showed no difference in the way the message was displayed).

The variable inDisplay can take the following values:

   (uint)MessageDisplay.kMessageDisplayNone
   (uint)MessageDisplay.kMessageDisplaySignificant
   (uint)MessageDisplay.kMessageDisplayStandard
   (uint)MessageDisplay.kMessageDisplayTutorial

For the sake of brevity, we will call these options "None", "Significant", "Standard" and "Tutorial".

Using the "None" option will result in the message being recorded in the message log, but not displayed on the screen. This can be handy for longer messages that don’t need to be read immediately. If using this in your scenario, however, beware of the "Message Log" bug, which causes messages to be no longer displayed past a certain point: it is therefore a good idea to use only in the early part of a scenario.

The "Significant" option is the one you will use most often. The message is both displayed to the player, and recorded in the message log. Here's an example of how it might be used for use for triggered wage change message:

   string msgTitle = "Wage_Change_Title";
   string msgText = "Wage_Change_Text";
   msgSound = "message1.mp3";
   game.SendGameMessage((uint)MessageCategory.kLocalEventMessage,
       (uint)MessageDisplay.kMessageDisplaySignificant,
        ref msgTitle, ref msgText, ref msgSound);

The title and text of the message itself are defined in the XML file, for example as follows:

   <String id="Wage_Change_Title">Change in Wage Expectations</String> 
   <String id="Wage_Change_Text">The increasing wealth of your 
     city has led to demands for higher wages amongst plebs and equites
     alike. Check with your Labor Advisor for more information.</String>

See the XML section of the Editor Tutorial for more information on the scenario XML file.

The above example will play the default message sound file (the familiar "ding" sound). However, other sound files can be played as required. By default the game will look in the "Caesar IV\Data\Audio\Voice\Tutorials" folder. However, other locations can be used. For example:

   msgSound="/../figures/praefect_15.mp3";

will play the praefect saying his "I hate arsonists..." piece.

The "Standard" option does not appear to have any use. The message is recorded in the message log, but all that is displayed to the user is a blank "warning" message.

The "Tutorial" option uses the display method as seen (as its name suggests) in the tutorials. This requires a different way of specifying the message text in the XML file. Such messages are not recorded in the Message Log, but are retained via an Instructions display. This can allow for quick and easy reference to essential information, rather than forcing the player to trawl through the message log. The following example is taken from Aramann's Military Tutorial.

   string msgTitle = "Tutorial_02_Title";
   string msgText = "Tutorial_02_Message";
   msgSound = "message1.mp3";
   game.SendGameMessage((uint)MessageCategory.kLocalEventMessage,
       (uint)MessageDisplay.kMessageDisplayTutorial, 
        ref msgTitle, ref msgText, ref msgSound);

However, it appears from testing that the variable msgTitle is not actually used by the code - so can take any value. Tutorial messages are stored in the XML file in a different way to other messages. They have to be included between the <Layouts> tags as follows:

   <Layouts>
   ...
      <Layout id="Tutorial_02_Message">
      <Header>Mess Hall</Header>
      <Text>Now that your farms are producing food (each farm will have a 
         number of wheat, for example, instead of a "0") place a mess hall 
         on or near the red X on the map.  \n\n</Text>
      <Image value="help_Mil_Mess_Hall" />
      <Text>\nPlace a granary nearby.</Text>
      </Layout>
   ...
   </Layouts>

This example also shows how you can display an image in the tutorial message: here we display a picture of the mess hall. See the HelpLayouts.xml file in the "Caesar IV\Data" folder for other pictures that you can use.

Other tutorial-style messages must similarly be placed between the two "Layouts" tags.

SendWarningMessage(ref string inMessage, ref string inSoundFilename)

This issues a one line "warning" message to the player, which appears at the top of the screen. Such messages are not recorded in the message log. Example use:

   String msgWarn = "Deploy_Cohorts";
   String msgSound = "message1.mp3";
   game.SendWarningMessage(ref msgWarn, ref msgSound);

The string variable msgWarn identifies the message text in the XML file, as below. The string variable msgSound identifies the sound file to be played when the message is sent. Unfortunately, this only works with sound files that are present in the "Caesar IV\Data\Audio\Voice\Tutorials" folder.

   <String id="Deploy_Cohorts">Deploy your cohorts now - the invaders
      will be here in 6 weeks!</String>

DebugOut(ref string inMessage)

This is included for completeness only. Its name suggests that it is intended for use when running in debug mode, although I have not tried this.

Editor Guide | Next: City ratings and other stats >