Part 7: Trade & Empire map

Many of the following methods use as input the ID of a site (city) on the Empire map, specified by the parameter inRouteIndex. Just to remind you: the site’s ID is as defined in the scenario’s XML file. For example, from the following snippet of XML, you can see that the site Lutetia has the site ID 2.

    <String id="SITE_2_LABEL">Lutetia</String>

CloseTradeRoute(uint inRouteIndex)

This method closes the trade route as identified by its world site index in the XML file. The following example will close world site #2 (which would be Lutetia in the example XML snippet given above):


You would typically use this method when a particular trigger occurs; alternatively you might use it to reflect random periodic disruptions to trade. If the site is visible on the Empire Map then the player can re-open the trade route again by paying the appropriate price. If it is not visible, then it can only be opened again by the script, using the OpenTradeRoute method described below.

An important point to note is that if you use this method to close a trade route, the closure does not take immediate effect – traders will continue to come to the player’s city for the rest of the year, or until at least a year has elapsed since the trade route was opened, whichever is the later.

OpenTradeRoute(uint inRouteIndex)

This method opens the trade route identified by its world site index in the XML file. You might want to use this to open a trade route as a “reward” for a player when a particular trigger occur – or to trigger a victory condition (which might be defined in the C4 editor). For example, if you wanted to open trade route #7 if the culture rating reaches 50 or more, you would include the following snippet of code:

    uint nCultureRating = 0;
    game.GetCultureRating(out nCulture);
    if (nCulture >= 50)

(In practice the code would be a little more complex than this, because you would want the script to “remember” that the trigger has already fired, so that the call to open the trade route is not repeated every game tick – see Note 1 below! Another variable would need to be used – typically a boolean flag – for this purpose.)

This method is the only way of opening a trade route for a city that is not visible on the Empire map. If the city is visible and the ‘Open trade’ button has not been locked, the player can always pay the cost of opening the route without meeting the conditions specified in the custom script.

The OpenTradeRoute method can also be used if an invisible city is used as a trigger for Victory or Defeat – the effect of the call is to activate the city, which can be set as a victory/defeat condition within the C4 editor.

1. If the trade depot/port is already built, this call will spawn a trader and reset the import/export counts to zero.
2. Calling this on an Enemy Camp has no effect (you cannot open trade with an enemy).

GetEmpireLevelLocked(uint inRouteIndex, out bool outLocked)

This method will return the flag outLocked as TRUE if the site is active and has not been “locked” using the LockEmpireLevelSite method. The flag will also be TRUE if the site has been “unlocked” using the UnlockEmpireLevelSite method. Otherwise the value of the flag will be FALSE.

GetIsTradeRouteOpen(uint inRouteIndex, out bool outOpen)

This method can be used to determine if the specified trade route, identified by its world site index in the XML
file, is open. Example use:

    bool isOpenLatium = false;
    game.GetIsTradeRouteOpen(0, out isOpenLatium);

This will check whether the player has already opened the trade route to Latium (defined here as site 0 in the XML file). If you input the world site index corresponding to that of the home city, then outOpen will be returned as
“true”. The method can also be used for enemy camps – in this case the returned flag will be “true” only if the site is both active and visible.

GetIsTradeRouteOpen(ref string inRouteName, out bool outOpen)

This method provides an alternative means of working out if a specified trade route is open – this time identifying the route by its name rather than the site index. The following example comes from the Genoa tutorial:

    bool isOpenCaralis = false;
    string szSiteName = "Caralis";
    game.GetIsTradeRouteOpen(ref szSiteName, out isOpenCaralis);

LockEmpireLevelSite(uint inRouteIndex)

Calling this method causes the color of the site specified by inRouteIndex to change to grey on
the Empire Map. It has no effects on trade itself – if the trade route is open, it remains open; if it is
closed, it can still be opened in the usual manner. However, the game will then consider the site to be “inactive” – this could be defined as a victory or defeat condition within the C4 editor (cf. the CloseTradeRoute method described above). Alternatively the method could simply be used to illustrate changes in the state of a site following a particular storyline (e.g. an enemy camp is taken out; a trade partner is under siege, etc.). Example use:


This will change the appearance of world site #7 as numbered in the XML file to grey, and that site would then be considered to be inactive by the game.

UnlockEmpireLevelSite(uint inRouteIndex)

Calling this method causes the color of the site specified by inRouteIndex to change to
colored on the Empire Map. It has no effects on trade itself – if trade is closed, it remains
closed. However, the game will then consider this site to be “active” – which could be defined in the C4 editor as a victory or defeat condition (cf. the OpenTradeRoute method described above). Alternatively it could be used to illustrate changes in the state of a site following a particular storyline (e.g. an enemy camp becomes active, indicating an imminent attack, or a trade partner recovers from a disaster, etc.). The following example code “unlocks” (makes “active”) world site 7 as identified in the XML file:


ClearWorldWaypointsBetween(ref string inFromMapLabel, ref string

InsertWorldWaypoint(int inWaypointNumber, int inWaypointType, ref string
inFromMapLabel, ref string inToMapLabel, int inX, int inY)

The purpose of these methods is unclear. Although their names suggests the possibility of making changes to the Empire map during a game, attempts to use them have not shown any observable effects. (It is possible that there was an intention of making some such functionality available, but that this has been disabled.)

< Previous: Other event methods | Editor Guide | Next: Invasions >