SLIC Built-in variables and trigger events

[Mr Ogre]

By Joe Rumsey
About the author: CTP Programmer, a.k.a Mr Ogre on the forums

Variable concepts

Built-in variables in SLIC serve two purposes. First, they contain information about objects in the game. For example, when you have code that deals with a city, it will have access to a variable named city. To find out how many people live in the city, you can use city.population. Because you may sometimes have to deal with more than one city, an index as to which city you mean can be inserted between the container name and the member you are interested in. For example, city.1.population is the same as city.population since 1 is the default index if none is given. But city.2.population is the population of the second city in the current context. This use of indices is not specific to the city container, it works for all containers except g, clicked, and special.

The second use of built-in variables is to make triggers fire when certain events occur in the game. Often, the variables you can and can't use in a trigger or a message called from a trigger are determined by the conditions used to fire that trigger. There are other ways to gain access to some objects, however. More on that later. In general, you will write triggers like:

trigger 'AnExampleTrigger' when (city.built) {
    // city is now a valid variable.
}

The above trigger will fire whenever a city is built. Code inside the trigger can use the variable city to examine or modify the city. For example, we can modify the trigger above to plant a free warrior in every newly built city:

trigger 'AnExampleTrigger' when (city.built) {
    // Only give a warrior if there aren't already some military units
	if(city.combatunits < 1) {
	    CreateUnit(city.owner, UnitType("UNIT_WARRIOR"), city.location, 0);
	}
}

This trigger says that whenever a city is built, check to see if there are already any military units in the same square as the city. If there aren't, then create a new warrior belonging to the city's owner, at distance 0 from the city's location.

Each trigger object you create is only triggered for one type of event, even though it may contain more than one variable that can be used as a trigger event! See Trigger Priorities for a discussion of how to determine which events will cause your trigger to be run. A good way to be safe is to just put as little logic in the when(...) condition as possible, and instead move everything else to an if(...) {} inside the trigger.

Variables marked with (no value) below are only useful as trigger conditions. That is, their value is undefined outside the when(...) of a trigger.
Variable Reference

Containers

These top level built-ins are used to contain information about various objects. Some of them can also be used on their own in various places.

• g - contains global information (never useful by itself)
• city - a city.
• player - a player.
• unit - a unit.
• clicked - never useful by itself. Members only useful as trigger conditions.
• special - never useful by itself. Contains members useful as trigger conditions.
• discovery - a discovery (advance).
• wonder - a wonder.
• agreement - a diplomatic agreement.
• location - a map location.
• government - a government.
• gold - an amount of gold.
• building - a city building.
• pop - a population (worker).
• good - a trade good.
• action - contains a string passed from the game for some special purpose, not generally useful except for the specific places it's used in the main script file.
• timer - Timers can be set to go off after a specified number of seconds.

Global container

• g.year - the current turn #, the first turn of the game being 0.
• g.pollution - the current amount of pollution in the world.
• g.player - the player who is moving right now.
• g.maxscore - the base score value from the difficulty database.
• g.tutorialplayer - if the tutorial is on, which player is the tutorial player.

City Container

• city.population - the population of the city. Triggers when a city grows.
• city.food - the amount of food stored in the city.
• city.owner - the city's owner.
• city.location - the location of the city. triggers when a new city is founded.
• city.built - triggers when a new city is founded. (no value)
• city.building - triggers when a city starts building a building. The value is the index of the building in improve.txt.
• city.buildingunit - triggers when a city starts building a unit. The value is the index of the unit in units.txt.
• city.buildingendgame - triggers when a city starts building an endgame object. That is, the objects used to win scientifically. The value is the index into endgame.txt.
• city.buildingwonder - triggers when a city starts building a wonder. The value is the index into wonder.txt.
• city.happiness - the city's happiness.
• city.combatunits - the number of military units in the city's square.
• city.captured - triggers when a city is captured (no value)
• city.buildingnothing - triggers when a city builds the last thing in it's queue. (no value)
• city.selected - triggers when a city becomes selected. (no value)
• city.deselected - triggers when a city is deselected. (no value)
• city.overtimecost - the amount of gold it would take to rush buy whatever the city is currently building.
• city.pollution - the amount of pollution the city is producing each turn.
• city.queue - the number of items in the city's build queue.

Player Container

• player.gold - the amount of gold the player has. Triggers at the beginning of the player's turn.
• player.cities - the number of cities the player has. Triggers at the beginning of the player's turn.
• player.goods - How many trade goods the player has altogether. Triggers at the beginning of the player's turn.
• player.discoveries - how many advances the player has. Triggers at the beginning of the player's turn.
• player.capitol - The player's capitol city. Can be used in place of city in many places. Triggers at the beginning of the player's turn.
• player.pollution - how much pollution the player is producing. Triggers at the beginning of the player's turn.
• player.sciencerate - the player's current science setting (0-100).
• player.totalunits - the total number of units the player owns.
• player.publicworkstax - the current setting of the player's public works tax.
• player.publicworkslevel - the current amount of public works stored.
• player.government - the player's government, as an index into govern.txt.
• player.score - the player's current score.
• player.sightedunit - triggers when the player sees an enemy unit (unit will contain the unit sighted, unit.2 is the unit that sighted it.) (no value)
• player.readiness - the player's current readiness setting (0-2)
• player.messages - the number of unread messages the player has.

Unit container

• unit.location - the unit's location.
• unit.type - the unit's type as an index into units.txt.
• unit.owner - the unit's owner.
• unit.built - triggers when a unit is built (no value)
• unit.sighted - triggers when a unit is sighted. unit.2 is the unit that did the sighting. (no value)
• unit.launched - triggers when a unit is launched into space (no value)
• unit.beginturn - triggers for every unit at the beginning of the turn. Use this sparingly! It can slow things down. (no value)
• unit.dead - triggers when a unit dies.(no value)
• unit.deadnofuel - triggers when a unit dies because it ran out of fuel. (no value)
• unit.deadnosupport - triggers when a unit dies from lack of support. (no value)
• unit.deadother - triggers when a unit dies for some other reason. (no value)
• unit.moved - triggers whenever a unit moves. (no value)
• unit.donemoving - triggers whenever a unit reaches the end of a movement order.(no value)
• unit.selected - triggers whenever a unit is selected. (no value)
• unit.deselected - triggers whenever a unit is deselected (no value)
• unit.embarked - triggers when a unit boards a transport (no value)
• unit.debarked - triggers when a unit leaves a transport (no value)
• unit.fortified - triggers when a unit fortifies (no value)

Clicked Container

• clicked.unit - triggers when the user clicks on a unit. (no value)
• clicked.unexplored - triggers when the user clicks on an unexplored (black) part of the map. (no value)
• Discovery Container
• discovery.type - triggers when a player gains a new advance. The value is the index into advance.txt. player.1 is the player that discovered it.
• discovery.traded - triggers when players trade advances diplomatically. player.1 is the player receiving the advance, player.2 is the player giving it.
• Wonder Container
• wonder.started - triggers when a player starts building a wonder. player.1 is the player building it. The value is the index into wonder.txt.
• wonder.finished - triggers when a wonder is completed. The value is the index into wonder.txt.
• wonder.almostfinished - triggers when a wonder is nearly complete (the same time the messages to this effect are sent)
• Agreement Container
• agreement.broken - triggers when a diplomatic agreement is broken. player.1 is the player who broke the agreement, and player.2 is the player with whom the agreement was made.

Special Container

• special.unitselected - triggers when a unit is selected. (no value)
• special.allunitsmoved - triggers when the current player moves the last of his units. (no value)
• special.workview - triggers when the player opens the work view.(no value)
• special.continentshared - true if the continent the player's capitol is on is shared with at least one other civ.
• special.contact - triggers when contact is made between two units. unit.1 and unit.2 are the units in question.
• special.attacked - triggers when a battle takes place. unit.1 is a unit in the attacking army, unit.2 is a unit in the defending army. (no value)
• special.tradescreen - triggers when the trade screen is opened. (no value)
• special.diplomaticscreen - triggers when the diplomacy screen is opened. (no value)
• special.createstack - triggers whenever units are grouped together. player.1 is the player that did the grouping. (no value)
• special.bombarded - triggers whenever a unit bombards another. unit.1 is the attacker, unit.2 is the defender. (no value)
• special.counterbombarded - triggers whenever a unit bombards and is then counter bombarded. unit.1 is the original attacker, unit.2 is the defender who is counter bombarding. (no value)
• special.activedefense - triggers whenever an active defender actively defends. unit.1 is the active defender, unit.2 is the unit against which it is defending. (no value)
• special.indulgences - triggers when a cleric/televangelist sells indulgences. unit.1 is the cleric, city.1 is the city to which it is selling indulgences.
• special.terrorism - triggers when various terrorist acts are done. unit.1 is the terrorist unit, city.1 is the city against which the act was made. (no value)
• special.converted - triggers when a city is converted. unit.1 is the cleric, city.1 is the city which was converted.
• special.citizenenslaved - triggers when a slaver takes a slave from a city. unit.1 is the slaver, city.1 is the city from which a slave was taken. (no value)
• special.settlerenslaved - triggers when a slaver captures a settler. unit.1 is the slaver, player.2 is the player whose settler was captured.(no value)
• special.victoryenslavement - triggers when a slaver captures a slave due to winning a battle. unit.1 is the slaver, player.2 is the player who was defeated in battle. (no value)
• special.popmoved - triggers whenever a player moves a worker. (no value)
• special.popmovedoffgood - triggers whenever a player moves a worker off a trade good. City.1 is the city to which the worker belongs. (no value)
• special.popmovedongood - triggers whenever a player moves a worker onto a trade good. good.1 is the good, city.1 is the city to which the pop belongs.
• special.buildfarm - triggers when a player starts building a farm. player.1 is the player, location.1 is the place it's being built. (no value)
• special.buildroad - triggers when a player starts building a road. player.1 is the player, location.1 is the place it's being built. (no value)
• special.buildmine - triggers when a player starts building a mine. player.1 is the player, location.1 is the place it's being built. (no value)
• special.buildinstallation - triggers when a player starts building an installation. player.1 is the player, location.1 is the place it's being built. (no value)
• special.buildtransform - triggers when a player starts a terraform. player.1 is the player, location.1 is the place it's being built. (no value)
• special.tradeoffer - triggers when a player makes a trade offer. player.1 is the player making the offer, good.1 is the good being offered, gold.1 is the amount asked for the good. (no value)
• special.traderoute - triggers when a domestic trade route is created. player.1 is the player who owns the route, city.1 is the source city, city.2 is the destination, and good.1 is the good being traded. (no value)
• special.foreigntraderoute - same as special.traderoute, except it triggers when an international trade route is created. player.2 is the other player. gold.1 will also contain the amount of gold being paid for the route. (no value)
• special.piracy - triggers when someone pirates a trade route. player.1 is the owner of the source of the route, player.2 is the owner of the destination, player.3 is the player doing the piracy, unit.1 is the unit doing the piracy, city.1 is the source city, city.2 is the destination city. (no value)
• special.pillage - triggers when someone pillages. unit.1 is the unit doing the pillaging, player.1 is the player doing the pillaging, and player.2 is the player who owns the square being pillaged. (no value)
• special.cantsettlenomovement - triggers when a unit tries to settle but can't because it's out of movement points. (no value)
• special.agechange - triggers when a player enters a new age. player.1 is the player. (no value)
• special.sentceasefire - triggers when a cease fire request is sent from player.1 to player.2. (no value)
• special.lockedstack - triggers when a player groups more than one unit together. unit.1 is one of the units involved, and player.1 is one of the players.
• special.stackedcombat - triggers when combat takes place in which at least one army has more than one unit. unit.1 is a unit in the attacking army, and unit.2 is a defender. player.1 is the attacking player, and player.2 is the defending player. (no value)
• special.tutorialdeactivated - triggers when the tutorial is deactivated (no value)
• special.singlecombat - triggers when combat occurs between two armies that each have only one unit. unit.1 is the attacker, and unit.2 is the defender.
• Gold Container
• gold.amount - an amount of gold passed in from the game to a messagebox.
• Building Container
• building.built - triggers when a building is built. Value is the index into improve.txt.

Timer Container

• timer.expired - triggers when a timer set with StartTimer() expires. (no value)

Population Container

• pop.location - the location of the pop.
• pop.type - the type of the pop, as an index into pop.txt.

Good Container

• good.type - the type of the good, as an index into goods.txt.