Announcement

**Solver** · July 30, 2007, 17:23

CIV4EventTriggers.xml

So that’s it as far as event descriptions go in the XML. However, that is only one side of the event description. The other side are triggers. Triggers are described in Assets\XML\Civ4EventTriggerInfos.xml. In essence, every trigger is a set of conditions. If these conditions are true, then events tied to that particular trigger can occur (some have extra Python checks, that’s in the Python section). Events that are tied to a trigger are also described in this file. Predictably enough, the SDK class for event triggers is CvEventTriggerInfo.
So, here are the tags describing triggers.

Type- this is the trigger type identifier. Takes the form of EVENTTRIGGER_NAME

WorldNewsTexts- is a text string identifier, which spiecifies the text to be displayed to all players when the event occurs.

TriggerTexts- text string identifiers can be specified for additional trigger messages, in particular, texts tied to an era. For instance, the Ruins effect:
[xml]

TXT_KEY_EVENT_TRIGGER_CITY_RUINS_ANCIENT_1
ERA_ANCIENT

TXT_KEY_EVENT_TRIGGER_CITY_RUINS_ANCIENT_1
ERA_CLASSICAL

TXT_KEY_EVENT_TRIGGER_CITY_RUINS_ANCIENT_1
ERA_MEDIEVAL

TXT_KEY_EVENT_TRIGGER_CITY_RUINS_ANCIENT_1
ERA_RENAISSANCE

TXT_KEY_EVENT_TRIGGER_CITY_RUINS_INDUSTRIAL_1
ERA_INDUSTRIAL

TXT_KEY_EVENT_TRIGGER_CITY_RUINS_INDUSTRIAL_1
ERA_MODERN

TXT_KEY_EVENT_TRIGGER_CITY_RUINS_INDUSTRIAL_1
ERA_FUTURE

[/xml]
Here, separate text is being given for every era, so that the correct text would appear at the appropriate time.

bSinglePlayer- can be either 0 or 1. If set to 1, the event can only trigger in singleplayer games.

iPercentGamesActive- is a number from 0 to 100. When you start a new game, not all events will be in it. This number determines the probability of this event trigger being included in a new game. Thus you can create events that will be rarely seen – or, on the contrary, be eligible to occur in every game.

iWeight- is a number that affects the probability of this trigger triggering. Applies to events that are active in this game only (as does everything else). Set to -1 if the trigger needs to always occur if the other conditions are met (for example, triggers that determine quest completion should be with -1).

bProbabilityUnitMultiply- can be either 0 or 1. If set to 1, the trigger probability increases as the player builds more units.

bProbabilityBuildingMultiply- can be either 0 or 1. If set to 1, the trigger probability increases as the player builds more buildings.

Civic- is a civic identifier, NONE for no civic. If used, specifies the civic required for the trigger to activate.

iMinTreasury - is a number. Specifies the minimum amount of gold in the player’s treasury for the trigger to activate.

iMinPopulation- is a number. Specifies the minimum total population that a player must have for the trigger to activate.

iMaxPopulation- is a number. Specifies the maximum total population that a player is allowed to have for the trigger to activate.

iMinMapLandmass- is a number. Specifies the minimum amount of land areas that must be on the map for the trigger to activate. Can be used, essentially, to specify the minimum amount of continents required.

iMinOurLandmass- is a number. Specifies the minimum amount of land areas that must be under player’s control (specifically, have cities on them) for the trigger to activate.

iMaxOurLandmass- is a number. Specifies the maximum amount of land areas that the player is allowed to control for the trigger to activate. Use -1 to have no restrictions.

MinDifficulty- is a difficulty level specifier, NONE for no difficulty. If used, specifies the minimum difficulty level required for the event trigger to activate,

iAngry- is a number. Specifies the minimum anger level (unhappiness – happiness) in a city for the trigger to activate. Applies to triggers that target a city.

iUnhealthy- is a number. Specifies the minimum unhealthiness level (bad health – good health) in a city for the trigger to activate. Applies to triggers that target a city.

UnitsRequired- if non-empty, contains information about required units to trigger. So, if specified, events can only be triggered for the listed unit classes. Example:
[xml]

UNITCLASS_GALLEY
UNITCLASS_TRIREME
UNITCLASS_CARAVEL
UNITCLASS_GALLEON
UNITCLASS_PRIVATEER
UNITCLASS_FRIGATE
UNITCLASS_SHIP_OF_THE_LINE
UNITCLASS_IRONCLAD
UNITCLASS_TRANSPORT
UNITCLASS_DESTROYER
UNITCLASS_STEALTH_DESTROYER
UNITCLASS_BATTLESHIP
UNITCLASS_MISSILE_CRUISER
UNITCLASS_SUBMARINE
UNITCLASS_ATTACK_SUBMARINE
UNITCLASS_CARRIER
[/xml]
Such a trigger would make the event only affect the listed naval units.

iNumUnits- is a number. Specifies the amount of unts that must be on a plot for the trigger to activate – used for events which pick a plot. If used in conjunction with , only units of the listed classes will be counted.

iNumUnitsGlobal- is a number. Specifies the amount of units that the player must have for the trigger to activate. If used in conjunction with , only units of the listed classes will be counted.

iUnitDamagedWeight- is a number. Denotes the probability of the trigger activating for wounded units. Set to 1 for event triggers that you wish to deal with damaged units.

iUnitDistanceWeight- is a number. For events that affect a plot, increases the probability (if set to 1) of the trigger activating if a unit is far away from the plot.

iUnitExperienceWeight- is a number. When set to 1, increases the probability of triggering for a highly-experienced unit.

bUnitsOnPlot- can be either 0 or 1. When set to 1, means that the trigger checks for the presence of units (listed in ) on the affected plot.

BuildingsRequired- if non-empty, contains informations about the buildings required to trigger. Example:
[xml]

BUILDINGCLASS_FORGE
[/xml]
That would denote that a Forge is required for the trigger.

iNumBuildings- is a number used in conjunction with . Set to 1 to indicate that 1 building of that type is required in a city, for city-picking events.

iNumBuildingsGlobal- is a number. Specifies the minimum amount of buildings listed in that the player must have in total for the trigger to activate.

iNumPlotsRequired- is a number. Should be set to 1 for triggers that require a plot that meets specific conditions. See below for tags that specify these conditions.

bOwnPlot- can be either 0 or 1. If set to 1, specifies that the plot must be owned by the affected player to meet conditions.

iPlotType- is a number. Specifies the plot type that the plot must have to meet the condition. Set to -1 to ignore plot type. Unless otherwise modded, 0 stands for peaks (PLOT_PEAK), 1 for hills (PLOT_HILLS), 2 for land plots (PLOT_LAND) and 3 for ocean plots (PLOT_OCEAN). The enumeration listing plot types is PlotTypes in the SDK and Python.

FeaturesRequired- if non-empty, specifies the features that the plot must have to meet the condition. For example:
[xml]

FEATURE_FOREST
[/xml]
That is to require a plot to have Forest. Note that you can also explicitly require a plot not to have any features as follows:
[xml]

NONE
[/xml]
Please note that flood plains also count as a feature and the above example would exclude any floodplain plots.

TerrainsRequired- if non-empty, specifies the terrain type that the plot must have to meet the condition. For example:
[xml]

TERRAIN_GRASS
TERRAIN_PLAINS
[/xml]
to indicate that Grasslands or Plains plots are eligible for the trigger.

ImprovementsRequired- if non-empty, specifies the improvements that the plot must have to meet the condition. As an example:
[xml]

IMPROVEMENT_PLANTATION
[/xml]
That is to require a Plantation. Note that you can, just like with Features, set the variable to NONE to explicitly require no improvement to be present.

BonusesRequired- if non-empty, specifies the bonus (resource) types that the plot must have to meet the condition. So,
[xml]

BONUS_INCENSE
[/xml]
Requires Incense in the plot. And again, setting the variable to NONE will explicitly require no bonus to be present.

RoutesRequired- the last variable specifying plot conditions. If non-empty, specifies the route types that the plot must have to meet the condition.
[xml]

ROUTE_ROAD
ROUTE_RAILROAD
[/xml]
The above requires either a road or a railroad in the plot.

ReligionsRequired- if non-empty, specifies the religions required for the trigger to activate. For triggers that affect a city, the religions must be present in the city. For triggers not affecting a city, the religion must be present anywhere in the civilization. Hence:
[xml]

RELIGION_BUDDHISM
RELIGION_CONFUCIANISM
RELIGION_TAOISM
[/xml]
That code would check for the presence of Buddhism, Confucianism and Taoism. It’s used in conjunction with the next variable, see below.

iNumReligions- is a number. Specifies how many of the religions listed in must be present for the trigger to activate. If has been left empty, then any religions will do. For example, for a trigger that affects a city, if is empty and is 2, then cities with at least different 2 religions in them will be eligible for the trigger.

CorporationsRequired- if non-empty, specifies the corporations required for the trigger to activate. For triggers that affect a city, the religions must be present in the city. For triggers not affecting a city, the religion must be present anywhere in the civilization.
[xml]

CORPORATION_1
[/xml]
That would require the first corporation, which is Cereal Mills. Just like , this is used in combination with the next variable.

iNumCorporations- is a number. Works exactly like , but for corporations instead of religions. Specifies how many of the corporations listed in must be present for the trigger to activate. If has been left empty, then any corporation will do.

bPickReligion- can be either 0 or 1. If set to 1, then the trigger will pick a religion for the events that it activates. Which religion is picked can be further specified by the next variables.

bStateReligion- can be either 0 or 1. If set to 1 and is 1, then the affected player’s state religion will be picked.

bHolyCity- can be either 0 or 1. If set to 1 and is 1, then the player must own the religion’s holy city in order for it to be picked. If the trigger also picks a city, then the picked city must be the religion’s holy city. For example, if , , are all 1 and the trigger picks a city ( is also 1), then the city picked will be the holy city of the player’s state religion, provided he owns that city.

bPickCorporation- can be either 0 or 1. If set to 1, then a corporation will be picked by the trigger. The corporation must be present in the player’s civilization to be picked.

bHeadquarters- can be either 0 or 1. If set to 1 and is 1 then the player must own the corporation’s headquarters in order for it to be picked. If the trigger also picks a city, then the picked city must be the corporation headquarters. Works like does for religions.

Events- this, ladies and gentlemen, is the holy grail of the trigger XML file. Here event identifiers from Civ4EventInfos.xml are listed that denote the events triggered by this particular trigger. Note that each choice is also technically an event – therefore, for events that have choices, multiple identifiers will be listed. Take a look at the slave revolt event example:
[xml]

EVENT_SLAVE_REVOLT_1
EVENT_SLAVE_REVOLT_2
EVENT_SLAVE_REVOLT_3
[/xml]
The code means that, when the trigger activates, the player will be allowed to choose between three events. So in-game, a popup with three options will appear. The effects of every choice are, of course, specified in Civ4EventInfos.xml. Triggers that do not have a choice associated with them simply list one event:
[xml]

EVENT_TORNADO_1
[/xml]
Here the player will have no choice but to accept what happened.

PrereqEvents- another fun field, this lists the events that must have already happened for this trigger to possibly activate. There are two main uses. One is to simply specify conditional triggers. For example, EVENTTRIGGER_DUSTBOWL_CONT has
[xml]

EVENT_DUSTBOWL_2
[/xml]
That means that the trigger can only activate if the EVENT_DUSTBOWL_2 event has occurred previously.
The second use is for quest done triggers. When creating quests, each quest needs a trigger that checks whether its conditions have been fulfilled. However, a quest can only be completed if it’s been given. Therefore, for example, EVENTTRIGGER_HORSE_WHISPERING_DONE, which fires when you complete the Horse Whispering quest, has:
[xml]

EVENT_HORSE_WHISPERING_1
[/xml]
That code makes sure that the trigger only activates if the EVENT_HORSE_WHISPERING_1 event has occurred, that being the event which assigns the Horse Whispering quest.

bPrereqEventPlot- can be either 0 or 1. For triggers that have PrereqEvents specified, if set to 1, means that the trigger will fire on the same plot where the prerequisite events fired. This is used with triggers such as continuing slave revolts or dustbowls – if the prerequisite event has fired, dustbowl or revolts will, if triggered, happen again in the same place where they did before.

OrPreReqs- if non-empty, lists technologies that player must have for the trigger to activate. These requirements are Or requirements – that is, only one technology of the listed ones is required. Example:
[xml]

TECH_STEAM_POWER
TECH_STEEL
TECH_SCIENTIFIC_METHOD
TECH_ARTILLERY
[/xml]
That allows the trigger to activate if the player has Steam Power or Steel or Scientific Method or Artillery.

AndPreReqs- if non-empty, lists technologies that the player must have for the trigger to activate. These are And requirements – the player must have all the listed technologies for the trigger. Example:
[xml]

TECH_RIFLING
TECH_STEEL
[/xml]
This trigger can only fire when the player has both Rifling and Steel technologies.

ObsoleteTechs- if non-empty, lists technologies that obsolete the trigger, making it ineligible to activate. If multiple technologies are listed, having any of those will invalidate the trigger for that player.
[xml]

TECH_RIFLING
TECH_RAILROAD
TECH_ECONOMICS
[/xml]
These settings would obsolete the trigger for any player who has Rifling or Railroad or Economics.

bRecurring- can be either 0 or 1. If set to 1, the trigger can activate multiple times throughout the game for the same player. If set to 0, it can only activate once per player. Note that the field in event description can reset events, making the game forget they have occurred.

bTeam- can be either 0 or 1. If set to 1, the trigger applies to all players on the same team. Not used in any of the events shipping in BtS.

bGlobal- can be either 0 or 1. If set to 1, applies to all players. That means that, when triggered for one player, it’s cosidered to have triggered for all players. Combined with set to 0, it will result in triggers that can only happen once per game.

bPickPlayer- can be either 0 or 1. If set to 1, then the trigger will pick another player to affect by the event. This is how events that give stuff to other players or affect relations with them are created. The specific player who gets selected can be further narrowed down by the next six tags.

bOtherPlayerWar- can be either 0 or 1. If set to 1, then the trigger can activate when the affected player and the other player are at war. When set to 1, the trigger activates for player pairs at peace.

bOtherPlayerHasReligion- can be either 0 or 1. If set to 1, then the other player must have the religion picked by the trigger (see ). If is 0, then the other player must have the religion somewhere in his empire. If is 1, then the other player must have the same state religion.

bOtherPlayerHasOtherReligion- can be either 0 or 1. Works opposite to the previous variable. If set to 1, the other player must have a different religion than the picked one. If is 1, then the other player’s state religion must be different.

bOtherPlayerAI- can be either 0 or 1. If set to 1, then the other player must be an AI player.

iOtherPlayerShareBorders- is a number. Specifies the minimum amount of land plots that the affected player and the other player must have along the border (adjacent to one another).

OtherPlayerHasTech- is a technology identifier, NONE for no technology. If used, specifies the technology that the other player must have for the trigger to activate.

bPickCity- can be either 0 or 1. If set to 1, then the trigger will pick a city.

bPickOtherPlayerCity- can be either 0 or 1. If set to 1, then the trigger will pick one of the other player’s cities.

bShowPlot- can be either 0 or 1. If set to 1, then the plot in which the event happens will be visually highlighted.

iCityFoodWeight- is a number. Acts as a probability multiplier for the food stored in a city. That is, for triggers that pick a city, cities with more food stored will have a higher probability of being picked as iCityFoodWeight increases. 1 is a sane value to prioritize cities with a lot of food stored.

PythonCanDo- if specified, it’s the name of the Python function which is executed to check whether the trigger can be triggered. See the section on Python for more information.

PythonCanDoCity- if specified, it’s the name of the Python function which checks whether a city is eligible to be picked by the trigger. See the section on Python for more information.

PythonCanDoUnit- if specified, it’s the name of the Python function which checks whether a unit is eligible to be picked by the trigger. See the section on Python for more information.

PythonCallback- if specified, it’s the name of the Python function which is called when the trigger activates. Not used in any of the BtS events. Don’t confuse with in event descriptions in Civ4EventInfos.xml, which is the function which gets called when the event happens. See the section on Python for more information.

**Solver** · July 30, 2007, 17:25

Python and Events

XML tags allow a good range of possibilities for modding events and their triggers, but some of the more complicated stuff you might want to do requires the use of Python. Python modding, of course, requires a working knowledge of Python, so if you do not have that, feel free to skip this section. This article won’t teach you Python or how to use Python with Civ4 general. The Python file for event functions is Assets\Python\EntryPoints\CvRandomEventInterface.p y.

Let us first look at how Python can be used in conjuncton with the events described in Civ4EventInfos.xml. As mentioned, each event entry has four Python function tags. If these are filled, then the aproppriate Python functions are called and used in conjunction with whatever XML data has been specified. Here are, again, the tags.

PythonCallback- that’s the Python function which is called when the event actually happens. It’s used to give the event effects more complicated than are possible through raw XML. Quests are the best example of that, as their rewards are usually somewhat complicated.

Callback functions don’t need to return a value.

PythonExpireCheck- that’s the Python function which is called to see whether the event has expired. It will be called every turn for every event that has occurred. If the event has expired, it gets reset. The practical use of that is for quests. Events that set a quest should sent a Python expiration check function, which will determine the failing conditions of that quest.

Using Python expiration functions will not let you undo regular (non-quest) events. So if you have an event that, say, adds a promotion to all melee units, and add an expiration check to that event, it won’t remove the promotion when the expiration function returns true.

Expiration functions should return a true value for when the event has expired and a false value for when it hasn’t expired.

It’s important to note that expiration functions are only required if the expiration condition can not be described by XML alone. If the only expiration condition you want is, for example, a technology, then you can make the event expire by setting in Civ4EventTriggerInfos.xml. That’s the general idea of event Python functions – they complement the XML when it can’t describe what you want.

PythonCanDo- that’s the function which gets called to see if the event can be applied/selected. Again, that is required for non-trivial conditions. If the XML specifies, for example, that the event will subtract 100 gold from the treasury, people won’t be able to choose it unless they have 100 gold. But sometimes you will want to have non-trivial codition checks.

If the event can happen, the Python function should return a true value, and a false value if it can’t happen.

PythonHelp- this function will generate the help text for the event, if required. That text is displayed in mouseovers. This is primarily required for events whose text can change somewhat, such as having a different number depending on the circumstances. For example, if your event gives the player a free unit per every city, then the event’s help text should be modified according to the number of cities the player has. The function should return a text string.

Now, let’s look at some examples of these Python functions in use. The examples are from events that ship with BtS. First, you’ll notice that functions begin with retrieving data from the argsList passed to them.

Code:

def doWeddingFeud2(argsList): 
   iEvent = argsList[0] 
   kTriggeredData = argsList[1]

The first thing you should notice is the argument list that applies to event Python functions. For callback functions (), expiration () and help functions () argsList[0] will always contain the event identifier number, and argsList[1] will have an object describing the trigger data. For condition functions () argsList[0] will be the trigger object data. The type of that object is EventTriggeredData and it contains information about the data that the event was triggered with. You can get the affected player, the other player, the picked city and other things from the object.

EventTriggeredData

Here’s what you can do with the object in Python. Assume you have an assignment like

Code:

kTriggeredData = argsList[0]

Now, there’s a bunch of useful stuff to do with the object through its member variables.

kTriggeredData.ePlayer- will return the player ID for whom the event was triggered. To get a CyPlayer object out of it in Python,

Code:

player = gc.getPlayer(kTriggeredData.ePlayer)

kTriggeredData.eTrigger– will return the trigger type ID of the trigger for this event. That corresponds to an entry in Civ4EventTriggerInfos.xml

Code:

trigger = gc.getEventTriggerInfo(kTriggeredData.eTrigger)

will return a trigger info object if you need one.

kTriggeredData.iTurn- will return the turn number on which the event was triggered. Useful for expiration checks – you can, for example, easily check how many turns it’s been since the event was triggered.

kTriggeredData.iCityId– will return the ID of the city that’s been picked by the event. Remember that city IDs are per-player and not global. Therefore, to get a CyCity object in Python, you would

Code:

player = gc.getPlayer(kTriggeredData.ePlayer) 
city = player.getCity(kTriggeredData.iCityId)

kTriggeredData.iPlotX– will return the X coordinate of the plot picked by the event.

kTriggeredData.iPlotY– will return the Y coordinate of the plot picked by the event.

If you want to access a CyPlot object for the event’s plot, do so by

Code:

plot = gc.getMap().plot(kTriggeredData.iPlotX,  kTriggeredData.iPlotY)

kTriggeredData.iUnitId– will return the ID of the unit that’s been picked by the event. Just like city IDs, unit IDs are per-player and not global. So, if you want to get a CyUnit object corresponding to the picked unit, do:

Code:

player = gc.getPlayer(kTriggeredData.ePlayer) 
unit = player.getUnit(kTriggeredData.iUnitId)

kTriggeredData.eOtherPlayer– returns the ID of the other player for events that pick two player. Thus:

Code:

player = gc.getPlayer(kTriggeredData.ePlayer) 
otherPlayer = gc.getPlayer(kTriggeredData.eOtherPlayer)

will make player the affected player and otherPlayer the other player, ready for manipulation through Python.

kTriggeredData.iOtherPlayerCityId– will return the ID of the other player’s city that’s been picked by the event. To get a CyCity object:

Code:

otherPlayer = gc.getPlayer(kTriggeredData.eOtherPlayer) 
otherCity = otherPlayer.getCity(kTriggeredData.iOtherPlayerCityId)

kTriggeredData.eReligion– returns the ID of the religion picked by the event.

kTriggeredData.eCorporation– returns the ID of the corporation that has been picked by the event.

kTriggeredData.eBuilding– returns the ID of the building that has been picked. A CyBuildingInfo object can be obtained:

Code:

buildingInfo = gc.getBuildingInfo(kTriggeredData.eBuilding)

The use of these properties enables you to access the information you need about the event and the way it’s been triggered. Now, a full example of a Python function that executes an event:

Code:

def doWeddingFeud2(argsList): 
   iEvent = argsList[0] 
   kTriggeredData = argsList[1] 
    
   player = gc.getPlayer(kTriggeredData.ePlayer) 
   (loopCity, iter) = player.firstCity(false) 

   while(loopCity): 
      if loopCity.isHasReligion(kTriggeredData.eReligion): 
         loopCity.changeHappinessTimer(30) 
      (loopCity, iter) = player.nextCity(iter, false) 
       
   return 1

This is a fairly straightforward function. It iterates through all cities of the affected player and gives temporary happiness to them if they have the religion that’s been picked by the event trigger. The effect is not particularly complex, but it is something that could not be accomplished purely through XML, so it’s a good example of why Python is useful in event modding.

Here’s an example of a PythonCanDo function, which checks whether the event can be selected.

Code:

def canDoWeddingFeud3(argsList): 
   iEvent = argsList[0] 
   kTriggeredData = argsList[1] 

   player = gc.getPlayer(kTriggeredData.ePlayer) 
    
   if player.getGold() - 10 * player.getNumCities() < 0: 
      return false 
       
   return true

It checks whether the affected player has at least 10 gold per each city he owns. If not, the function returns false and the event can’t happen, otherwise it returns true and allows the event.

A good example of the help-text creating functions comes with the Horse Whispering quest. One of the possible rewards gives you free Horse Archers. Their number is variable, though, meaning it couldn’t exist in the help text. Let’s look at the help text string in BtS text files:

Code:

TXT_KEY_EVENT_HORSE_WHISPERING_DONE_HELP_1 
[ICON_BULLET]Receive %d1 [COLOR_UNIT_TEXT]Horse Archers[COLOR_REVERT].

As you can see, there’s a %d1 in the text, which will be substituted by the number. That’s what the getHelpHorseWhisperingDone1 function does in Python.

Code:

def getHelpHorseWhisperingDone1(argsList): 
   iEvent = argsList[0] 
   kTriggeredData = argsList[1] 
    
   map = gc.getMap() 
    
   iNumUnits = gc.getWorldInfo(map.getWorldSize()).getDefaultPlayers() 
   szHelp = localText.getText("TXT_KEY_EVENT_HORSE_WHISPERING_DONE_HELP_1", (iNumUnits, )) 

   return szHelp

Here, iNumUnits is set to be the default number of players for the current map size and then the number is inserted into the help text string.

Now, an example of an expiration function. Let’s look at the function which checks whether the Master Blacksmith quest has expired. The quest picks a city and expires (becomes impossible to complete) if the city which was picked changes hands or is destroyed.

Code:

def expireMasterBlacksmith1(argsList): 
   iEvent = argsList[0] 
   kTriggeredData = argsList[1] 
   player = gc.getPlayer(kTriggeredData.ePlayer) 
   city = player.getCity(kTriggeredData.iCityId)    
   if city == None or city.getOwner() != kTriggeredData.ePlayer: 
      return true 
             
   return false

Remember, kTriggeredData.ePlayer will always contain the player for whom the event starting the quest was triggered – and kTriggeredData.iCityId will always contain the city ID. The function checks if the city is None (which happens if it’s destroyed) or if the city’s owner isn’t the player to whom the quest was given. In these cases, the function returns true, expiring the event.

Finally, about Python functions that pertain to triggers. Civ4EventTriggers.xml also has Python function tags.

PythonCanDo- acts just like the same tag for events. Checks whether the trigger can be activated.

PythonCanDoCity- checks whether a city is eligible to be picked by the trigger.

PythonCanDoUnit- checks whether a unit is eligible to be picked by the trigger.

PythonCallback- acts just like the same tag for events. Gets called if the trigger is fired.

For PythonCanDoCity functions, argsList[0] is the trigger ID, argsList[1] is the player and argsList[2] is the city ID. For PythonCanDoUnit functions, it’s the same with the exception that argsList[2] is the unit ID. Here’s an example of a PythonCanDoUnit function for the Champion Unit trigger.

Code:

def canTriggerChampionUnit(argsList): 
   eTrigger = argsList[0] 
   ePlayer = argsList[1] 
   iUnit = argsList[2] 
    
   player = gc.getPlayer(ePlayer) 
   unit = player.getUnit(iUnit) 
    
   if unit.isNone(): 
      return false 
       
   if unit.getDamage() > 0: 
      return false 
       
   if unit.getExperience() < 3: 
      return false 

   iLeadership = CvUtil.findInfoTypeNum(gc.getPromotionInfo,gc.getNumPromotionInfos(),'PROMOTION_LEADERSHIP') 
   if unit.isHasPromotion(iLeadership): 
      return false 

   return true

After finding the unit, the function checks if it’s damaged or has less than 3 experience – in these cases it returns false. If the unit had the Leadership promotion, it also returns false. If the function returns false, then the unit is not eligible to be picked by the trigger and another one will be found.

That summarizes how events in BtS interact with Python and what the different function types are. Following are examples of some events you can create via modding.

**Solver** · July 30, 2007, 17:30

Creating Events

Well, so creating events is what you probably want to do if you’re reading this guide. In this article, I will show you how to create a few example events, explaining along the way. Without further ado, let’s get straight to it.

Creating an event (assuming XML modification only) will consist of three main parts. One is the creation of a new trigger, which will outline the conditions, second is creation of the event entry itself, which outlines the effects, and then there is adding text to the proper XML file.

The Civilization event:

A somewhat tongue-in-cheek event, a new version of Civilization gets released. You will have three options to deal with it. First, “Let them play!” – boosts happiness in all your cities. Second, “Use this game in education” – will boost the research output of your Universities. Third, “Sell the franchise abroad” – will give you a considerable sum of gold.

So, first we’re going to be creating a new trigger. In Civ4EventTriggerInfos.xml, I create an EVENTTRIGGER_CIV_GAME entry, the code for which follows below.
[xml]

EVENTTRIGGER_CIV_GAME

TXT_KEY_EVENTTRIGGER_CIV_GAME

TXT_KEY_EVENT_TRIGGER_CIV_GAME
NONE

0
80
100
0
0
NONE
0
0
0
0
0
-1
NONE
0
0

0
0
0
0
0
0

0
0
0
0
-1

0

0
0
0
0
0
0

EVENT_CIV_GAME_1
EVENT_CIV_GAME_2
EVENT_CIV_GAME_3

0

TECH_COMPUTERS

0
0
0
0
0
0
0
0
0
NONE
0
0
0
0

[/xml]
Almost all tags are at their default values, which means no special conditions. The interesting part is, of course, the tag, which specifies that the trigger, when activated, will give choices between those 3 events – we will create them next. specifies that the Computers tech is required for the trigger, which makes sense given the event’s context. Nothing fancy is added – we don’t need to pick specific players, cities, plots, check for population, religion or anything like that.

Now, I go into the Civ4EventInfos.xml file and create three new events. The first one is as follows.
[xml]

EVENT_CIV_GAME_1
TXT_KEY_EVENT_CIV_GAME_1

0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
NONE

0
0
0
NONE
NONE
0
0
0
0

NONE
0

1
0
0
0
0
0
0
0
0

NONE
0
NONE
0
NONE
0
NONE
0
NONE
NONE

0
0
-1
0
0
0
0

1000
[/xml]
Once again, most tags are at their default values. Other than the name and text description tags, the one that matters is , which is set to 1. That means that we’ll get +1 happiness in all cities ( being 0).

For the second choice, I create a second event. In order to waste less screen space, I’ll only show the relevant tags below.
[xml]
EVENT_CIV_GAME_2
TXT_KEY_EVENT_CIV_GAME_2

BUILDINGCLASS_UNIVERSITY
COMMERCE_RESEARCH
3

[/xml]
Other tags being at their default values, this means that every University will provide 3 extra research beakers.

And our third event has these tags:
[xml]
EVENT_CIV_GAME_3
TXT_KEY_EVENT_CIV_GAME_3
320
80 [/xml]
That will give a base 320 gold with an extra possible 80 randomly.

The mechanics of our new event are done! Now, we only need to add text. In Civ4GameText_Events_BTS.xml (in Assets\XML\Text), I add new tags as follows.
[xml]

TXT_KEY_EVENTTRIGGER_CIV_GAME
The %s1_civ_adjective game designers have developed a new game of Civilization.
[/xml]

TXT_KEY_EVENTTRIGGER_CIV_GAME is specified as world news text in the trigger file – that is, everyone will see the above text when the trigger fires.
[xml]

TXT_KEY_EVENT_TRIGGER_CIV_GAME
Our game designers have developed a new addictive game of Civilization. How shall we proceed?
[/xml]

That’s specified under the TriggerTexts tag, and will be shown in a popup to the player who gets the event. Now, we only need to add the choice descriptions.
[xml]

TXT_KEY_EVENT_CIV_GAME_1
Send congratulations to the developers. Our people should enjoy this game.

TXT_KEY_EVENT_CIV_GAME_2
This game seems to have great educational potential. Suggest that it be used in our educational system.

TXT_KEY_EVENT_CIV_GAME_3
Computer games? They have no place in our society! Sell the franchise to foreign buyers!
[/xml]
That’s it, the event is done! It will be in when you star a new game.
Here’s a useful hint. You can test the event in-game. There is a function CvPlayer::trigger() which activates a trigger given its ID. I’ll show you how to activate the event we just created, the general idea is the same for all triggers.

Start BtS in debug mode (by setting CheatCode=chipotle in the ini file). Start a new game in the Future era. Now, press Shift+~ (tilde) to bring up the in-game Python console. You’ll need to find out the ID of the trigger you added. To do so, in the console, enter

Code:

import CvUtil 
num = CvUtil.findInfoTypeNum(gc.getEventTriggerInfo, gc.getNumEventTriggerInfos(), ‘EVENTTRIGGER_CIV_GAME’) 
print num

That will output the ID of the Civ Game trigger. It was 176 for me. You don’t have to enter the print num line, but it’s a way of checking if you did everything correctly. If it outputs -1, something went wrong. The same result can be achieved by using another function. Instead of the above, you could do

Code:

num = gc.getInfoTypeForString(“EVENTTRIGGER_CIV_GAME”) 
print num

It’s essentially the same, but I prefer the first way for reasons I can’t explain myself. Anyway, when you’ve obtained the trigger number, you need to trigger it for yourself. In the Python console, do:

Code:

p = gc.getPlayer(0) 
p.trigger(num)

In single-player, the player with an ID of 0 is always the human, so the first line will give a reference to you. After the second line, a popup should appear just as if the event happened.

It’s important to note that, while the trigger() function can be used to forcefully activate a trigger, it will only work if the requirements are met. That’s why it was important to start a Future era game to test this addition – in the Future era, you already start with Computers. If you had started an Ancient era game, nothing would have happened after using the trigger() function.

The Danthrax event:

Danthrax told me that he would like a warning displayed the first time a slave revolt occurs, with the actual effects of the slave revolt only occuring subsequently. I’ll show how to do that, but will only be inserting the relevant tags here again.

The idea is to make a trigger with the same conditions as slave revolts, and have that trigger produce an event which merely gives a warning. Then, slave revolts are modified to require that warning to have happened. So first, I add a new trigger. I copy the slave revolt trigger and modify it.
[xml]
EVENTTRIGGER_SLAVE_REVOLT_WARNING

TXT_KEY_EVENT_TRIGGER_SLAVE_REVOLT_WARNING
NONE

CIVIC_SLAVERY
4
1

EVENT_SLAVE_REVOLT_WARNING

1
0
0
1 [/xml]
We will not need any text displayed when the trigger activates. The event will show a pop-up message anyway. However, may not be empty. The trigger conditions are just like those of the slave revolt trigger. is set to 0, though, because we only want one warning. Now I make modifications to the slave revolt trigger.
[xml]
EVENTTRIGGER_SLAVE_REVOLT
100

EVENT_SLAVE_REVOLT_WARNING
[/xml]
I changed iPercentGamesActive to 100 to make the event active in all games. That’s to avoid situations when the warning appears but no slave revolts an actually happen that game. If the warning event hasn’t been activated for that particular game, slave revolts won’t occur anyway.

Now, it’s time to add the slave revolt warning event itself.
[xml]
EVENT_SLAVE_REVOLT_WARNING
TXT_KEY_EVENT_SLAVE_REVOLT_WARNING [/xml]
All tags are at their default values so that the event basically does nothing. It will, though, still display a popup with the description text. So, time for text tag addition.
[xml]

TXT_KEY_EVENT_SLAVE_REVOLT_WARNING
Sir, our slaves are on the verge of revolting! As long as our society continues to use slaves, there is a possibility of them revolting!

TXT_KEY_EVENT_TRIGGER_SLAVE_REVOLT_WARNING
The slaves of %s2_city are on the verge of revolt!
[/xml]
Now that is done, too - you will get a warning before your first slave revolt.

Great Beast:

For the last example, here’s a Great Beast event. Your hunters see a beast in a hunting camp, and you are presented with choices. The trigger’s relevant parts are as follows:
[xml]
EVENTTRIGGER_GREAT_BEAST

TXT_KEY_EVENTTRIGGER_GREAT_BEAST

TXT_KEY_EVENT_GREAT_BEAST
NONE

1
1

IMPROVEMENT_CAMP

1
1

EVENT_GREAT_BEAST_1
EVENT_GREAT_BEAST_2
EVENT_GREAT_BEAST_3

TECH_HUNTING
TECH_POLYTHEISM

TECH_EDUCATION

1 [/xml]
As you can see, the trigger requires the player to have a plot with a Camp on it. In addition, Hunting and Polytheism are required, as is a state religion. The event won’t happen after the discovery of education. The first choice is simple – it merely gives +1 food in the plot.
[xml]
EVENT_GREAT_BEAST_1
TXT_KEY_EVENT_GREAT_BEAST_1

YIELD_FOOD
1

[/xml]
The second choice costs some gold and adds 1 population to a city.
[xml]
EVENT_GREAT_BEAST_2
TXT_KEY_EVENT_GREAT_BEAST_2
1
-15
1 [/xml]
The third choice is more complex, adding 1 happiness temporarily to cities of state religion.
[xml]
EVENT_GREAT_BEAST_3
TXT_KEY_EVENT_GREAT_BEAST_3
doGreatBeast3
getHelpGreatBeast3 [/xml]
The event XML code does nothing special except calling the Python functions.

Code:

def doGreatBeast3(argsList): 
   kTriggeredData = argsList[1] 
    
   player = gc.getPlayer(kTriggeredData.ePlayer) 
   (loopCity, iter) = player.firstCity(false) 

   while(loopCity): 
      if loopCity.isHasReligion(kTriggeredData.eReligion): 
         loopCity.changeHappinessTimer(25) 
      (loopCity, iter) = player.nextCity(iter, false)

This Python function is called when the event is chosen. It checks all the player’s cities for presence of the state religion (because the religion picked by the trigger will be the state religion), and adds 25 turns to the happiness timer of those cities, which results in +1 happiness for that time.

Also, the help text needs to be displayed appropriately, so here’s the PythonHelp function:

Code:

def geHelpGreatBeast3(argsList): 
   kTriggeredData = argsList[1] 
   religion = gc.getReligionInfo(kTriggeredData.eReligion) 

   szHelp = localText.getText("TXT_KEY_EVENT_GREAT_BEAST_3_HELP", (gc.getDefineINT("TEMP_HAPPY"), 25, religion.getChar())) 

   return szHelp

That takes the TXT_KEY_EVENT_GREAT_BEAST_3_HELP text tag, adding the global variable TEMP_HAPPY, the number 25 and the symbol of your state religion into it. The text tag itself looks like this:
[xml]

TXT_KEY_EVENT_GREAT_BEAST_3_HELP
[ICON_BULLET]%D1[ICON_HAPPY] in all cities with %F3_religion for %d2 [NUM2:turn:turns]
[/xml]
And finally, here’s the rest of the text for the event.
[xml]

TXT_KEY_EVENTTRIGGER_GREAT_BEAST
%s1_civ_adjective hunters have discovered a great beast lurking near one of their camps

TXT_KEY_EVENT_GREAT_BEAST
A great beast has been discovered near one of our hunting camps

TXT_KEY_EVENT_GREAT_BEAST_1
Let it breed and give offspring. Hunt sparingly.

TXT_KEY_EVENT_GREAT_BEAST_2
Looks like it could feed many people. Organize a hunting party!

TXT_KEY_EVENT_GREAT_BEAST_3
Hunt it? Are you mad? The beast is a manifestation of a divine spirit!
[/xml]
I hope this guide was useful in providing an insight into how to mod events in BtS. Remember that you can also download a small event mod from this thread, which contains the events described in the examples above, as well as a few other tweaks and new events.

Good luck with your modding, and be bold!

**greenday_234** · August 23, 2007, 03:17

Hi solver, first of all thanks for this guide! I've tried to start making my own events but I've run into a snag. When I test it through the game I can still get my event to launch despite the fact that I don't meet my civic requirement. I have the correct tags attached:

CIVIC_REPRESENTATION

but the event will still execute whether or not Im running it.

I have it placed in the eventtriggers.xml file.

What am I doing wrong?

Announcement

Solver's BtS Event modding guide

Solver's BtS Event modding guide

Comment

Comment

Comment

Comment