Part 8: Invasions

The standard way for setting up invasions is using the classes in Tools.cs as explained on the Scripting Invasions page. The methods on this page are for advanced use only.

ClearInvasions()

This method appears to clear records of invasions previously set up in memory or in the .scn file. I've only used this to clear memory of the remnants of invasion data in a .scn file (which was causing an unscripted invasion to appear). However, it could also be used as a way of preventing any future invasions of any type.

GetEnemyCohortData(int inCohortID, out string outDbID, out RomeScriptInterfaces.BasicCohortType outBasicType)

This method obtains the cohort type (Gaul light, Greek cavalry, etc.) in the output parameter outDbID, for the given input value for CohortID - where the CohortID value has previously been obtained using the GetInvaderCohorts method). The other output parameter outBasicType identifies the cohort type, which is one of: 'Archers', 'Cavalry', 'Infantry', 'Other', or 'Siege'.

GetInvaderCohorts(ref string inInvasionName, out int[] outIDs)

This method can be used to monitor and control an ongoing invasion (as in the examples which follow). The following code snippet illustrates its use (as taken from Tools.cs):

    Int32[] enemyCohorts;
    String invasion = game.RunInvasion;
    game.GetInvaderCohorts(ref invasion, out enemyCohorts);

This code will return a set of IDs to the enemyCohorts array. These cohort IDs could then be used to manipulate an ongoing invasion, e.g. using the SetCohortOrders method as described in the example below, or it could in turn be used to obtain the cohort type using the GetEnemyCohortData as described above.

SetCohortOrders(int inCohortID, ref string inOrders)

This method can be used to set or change the orders of individual enemy cohorts, identified by their cohort ID (which is as obtained using the GetInvaderCohorts method, described above). The following example is adapted from Iceni Queen:

    String orders = "Flee";
    String invasion = "Rome1";
    Int32[] iCohorts;
    game.GetInvaderCohorts(ref invasion, out iCohorts);
    foreach (Int32 cohortID in iCohorts)
    {
        game.SetCohortOrders(cohortID, ref orders);
    }

This effectively stops the invasion by telling every invading cohort to leave the map. You might want this to happen after a certain time or if a particular condition is met. You can use any of the other possible orders given in the public structure sCohortOrders in Tools.cs, such as "Flee", "CircleCity", "AttackCohorts", "RazeBuildings", "RazeMilitaryBuildings" or "RazeGovernorVilla".

SetCohortTargets(int inCohortID, ref string[] inTargets)

This method can be used to control an invasion by directing enemy cohorts to target specific buildings. The input array inTargets consists of the string identifiers for the buildings to be targeted. See Part 10 for a complete list of building IDs that could be used (though certain types of buildings such as decorative items, aqueducts and reservoirs appear to be completely ignored by enemies). The following example is as used in the Military Tutorial:

    Int32[] enemyCohorts;
    invasion = game.RunInvasion;
    String[] sTargets = { "C4b harvester Timber miller's house",
            "C4b harvester Iron miner's house",
            "C4b harvester Marble collector's camp" }; 
    String orders = "RazeBuildings";
    game.GetInvaderCohorts(ref invasion, out enemyCohorts);
    foreach (Int32 cohortID in enemyCohorts)
    {
        game.SetCohortOrders(cohortID, ref orders);
        game.SetCohortTargets(cohortID, ref sTargets);
    }

In this example we change the behaviour of all enemy cohorts in the current invasion (identified by game.RunInvasion) by changing their orders to "Raze Buildings", and telling them (in the array sTargets) to specifically target the city's timber camps, iron mining camps, and marble quarry camps.

You should be aware that the line of code "mMilitaryAI.Update(game, 0.1);" that is normally included in the OnTick routine of many scenarios will change the enemy cohort orders and targets after a while, so if you do not want that to happen, you will have to delete (or comment out) that line of code. The scenario script can in fact take full control of the invasion. For example, code like the above can be used in OnInvasionArrival instead of the usual code, in order to set the attacker's orders and targets as soon as they arrive on the map. We used this technique in Iceni Queen and the Military Tutorial.

If you delete the "mMilitaryAI.Update(game, 0.1);" line but still wish for enemy raiders to leave the map after destroying a certain number of buildings, you can check against the game.BuildingsRazed count that is maintained by the game. If you are taking full control of the invasions and intending to use this variable, you need to remember to set this count back to zero when a new invasion appears, as handled by OnInvasionArrival.

StartInvasion(ref string inInvasionName)

This method can be used when you want to trigger an invasion as a result of a specific event. You have to set up the invasion first - it does not work on those you set up in OnBeginScenario. The following is adapted from the Iceni Queen scenario, and shows a triggered invasion comprising two Heavy Roman cohorts, one Light Roman cohort, and one Roman catapult.

    String invasion = "Rome1";
    mInvasion = new InvasionSetup(invasion, "Roman", 
                       eInvasionType.kRaid, 0, 4, 0);
    mInvasion.AddCohort("ENEMY_ROMAN", 1, 6, 6);
    mInvasion.AddCohort("ENEMY_ROMAN_SOLO_RAZE", 1, 6, 6);
    mInvasion.AddCohort("ENEMY_ROMAN_CATAPULT", 1, 6, 6);
    mInvasion.CreateInvasion(game, 3, 0);
    game.StartInvasion(ref invasion);

It should be noted that this method gives the player no warning of the attack, so it requires a separate message to be fired. Also, the invaders can only be bribed (for the value set up in nBribe - just set this value to zero if no bribe is to allowed) via the Legion Advisor screen.

StopCurrentInvasions()

This is used in Tools.cs to stop the current invasion(s) after a defined period of time, or after a specified percentage of buildings have been razed. All enemies will leave the map. You can use it in a script after specific conditions are met.

StopInvasion(ref string inInvasionName, bool inStopFutureRecurrences)

This method performs a similar function to StopCurrentInvasions, but is aimed at the invasion identified by inInvasionName. An additional effect is to stop this invasion from recurring again, by setting the boolean flag inStopFutureRecurrences as in the following example:

    String invasion = game.RunInvasion;
    game.StopInvasion(ref invasion, true);

AddCohortToInvasion(ref string inInvasionName, ref string inCohortID, uint inNumFullCohorts, uint inEntryWaypoint, uint inExitWaypoint)

This is called from the CreateInvasion method of the InvasionSetup class. It has no obvious use as it allows you to do no more than the methods available through InvasionSetup (as invoked in OnBeginScenario).

CreateInvasion(ref string inInvasionName, int inTextIndex, ref string inFaction, int inBuyoffDenarii, int inStartWeek, int inVariance, int inDuration, int inRecurrenceInterval)

This method is used in Tools.cs, being called by the CreateInvasion method of the InvasionSetup class. This suggests that invasions can be set up directly; however, there seems little point in trying to use this particular method because it offers no more functionality than the usual means of doing so, i.e. the InvasionSetup.CreateInvasion method.

< Previous: Trade & Empire map | Editor Guide | Next: Military requests >