13.5 - Event Examples

By: CafeDave

Index of Events

Briefing Event

The briefing event is the first event that comes up when a scenario is started. There can only be one briefing event in a scenario and it must use the frequency of 'CheckFrequencyBriefing' for the game to recognize it as a briefing event. This should be set to 'AlwaysTrue' to ensure it triggers. The setting 'ExecuteOnlyOnce' is optional since it should only fire at the start, but I always include it anyway. Note that the directory and event names can be anything you want.

Normally, you can put the briefing message in the main briefing event along with any effects you want to happen at the beginning of the game. However, I have settled on the method below using a main event as the briefing event and calling the other events from that event. This allows splitting the briefing into multiple messages or having other secondary setup effects and also ensures that the events fire in the sequence you want them to. Note that if you have a message in the main briefing event and a message in an event called by the main briefing, the called event message will show up first. That is why I prefer to use the sequence shown to avoid this and allow additional briefing events to be added or removed as needed.

Tip: If you have a problem with your briefing event not showing up, it is likely because you did not save the game file with the editor mode turned on. See the Map Generation section of the Game Guide for further information on this. The only solution is to go back to the game file and resave it.

See my Wooden Limbs events below for examples:

Almanac and Scoring Events

Besides a briefing, the other event that is present in most scenarios is the almanac event. This is optional, however, and if you leave it out, the scenario will play like a normal random map game and have the normal scoring page. The Isla de Foresta and Senora Regula scenarios are good examples of this.

If it is present, an almanac event replaces the normal scoring page in the annual almanac with an information page set up by you. Usually this page contains a reminder of the goals of your scenario and an update on how you are doing. To be recognized as an almanac event, it must have a frequency of 'CheckFrequencyAlmanacScore' and should be set to 'AlwaysTrue' unless for some reason you want the page only to show up after a condition is met.

You can incorporate up to nine variables to give information on various conditions that affect your goals and even give a current score if you want. To do this, you must set the event and group variables to the conditions desired with a GeneralEffect statement, usually in the almanac event itself since the event can be called at any time using the 'A' key or almanac button. The ninth variable can be set using a Condition statement. These values are included in the message using the text replacement codes given in the editor documentation. See below for the Wooden Limbs almanac event.

Win/Lose Events

If your scenario has goals that must be met by the player, you will also need win/lose events to determine whether the player has reached the goal or if the time limit is up. The importance of these working properly cannot be overemphasized since it is very frustrating for a player to play a full scenario and meet the goals but still lose due to a faulty win event! So make sure you test, test, test.

The win event checks for the conditions given as the goal of the scenario. Make sure you check for all the required conditions if there are more than one. I prefer to make the frequency at month end so the player does not need to wait out the full year to find out he/she has won. If you do make it year end, make sure it will fire before the lose event or move the lose event to the beginning of the next year. My Wooden Limbs scenario has a complicated three-stage optional win sequence so I won't bore you with the details but you can see the events in the Score directory of that scenario. Here is a simple example from the Sucio scenario (with bug fixed in one of the conditions):

Tip: Note that you do not need to specify a message type for win/lose events. The message is given in the win/lose screen automatically.

The loss event is usually a very simple test for the time limit given for the scenario and a message indicating that you lose. This is normally checked at the end of the year given, but can be any time. You don't need to check for any win conditions since the win event should pick them out before the loss event triggers. A simple example is shown below from Sucio. Note the use of 1 after the GameLost setting. I'm not sure if this is required or not but most scenarios have it. Also note the use of >= to check the year, which is a good idea to ensure that the event is eventually triggered even if the player tries to cheat and bumps the date past the original end date.

Warning Events

Most of the PopTop scenarios include some warning events to inform you when you are getting close to the deadline for the scenario. These are a good idea but of course are optional. For some reason PopTop chose to always make these warnings two-stage events with the first stage checking conditions and the second event called to display the message. This may have been to allow the use of a condition to use as a [TRIGGER] text replacement value, but all warning events I have looked at use the Event Variables instead so this is not necessary. In my opinion it's better to keep things simple and have only one event unless you need to check further conditions or use looping for example, which would require a call event.

Here are the five-year warning events from the Fruitas scenario:

One-Time Events

The simplest type of event is a one-time event that happens at a certain time or under certain conditions. Obviously you will want to set it to 'ExecuteOnlyOnce'. The only other choices are the frequency to check and the conditions to meet, usually a time such as year, month, week or day but can also be any of the valid conditions or a combination.

Here is an example from the Club Tropico scenario for the bungalow event. Note from this example that you can have check frequency at month end but condition as year. This event would trigger at the end of January, 1953.

Choice Events

Choice events offer the player up to five choices of outcomes. Each choice has a choice message and an optional choice effect. The choice effect can either call another event or have an effect right in the choice event. Typically a choice event is used to make an offer to a player to buy something or make a choice between two or more alternatives.

Here is an example of a choice event from the Los Exconvictos scenario that calls a different event for each choice:

Using Group Variables as Flags

If you want to preserve the choice made by a player for later use, you will need to use a group variable to set a flag. Subsequent events can then check for this variable. This must be a group variable, not an event variable, to be accessible by other events in the same group.

Here is an example of a choice event from Wooden Limbs that sets GroupVariable1 to 1 if the player chooses option 1. This variable is then used to make an annual payment for three years and to trigger the final event three years later. Note that the final event adds 1 to GroupVariable1 to stop the payments.

Saving Group Variables

Unfortunately, there is one drawback to using group variables due to a bug in the game that does not save group variables in a game save. Hopefully a patch or update will fix this in the future, but for my scenario, I created a workaround to take advantage of the fact that event variables are saved while group variables are not. This event uses a logical value in the first effect to only reset the GroupVariable to match the EventVariable if it is equal to zero, which it would be after a game save. Then it sets an event variable to the value of the group variable to save it for later retrieval. This event will fire only when a variable is changed by an event or when a game save is opened and has group variables set to zero.

To safeguard against losing group variables, you will need one of these for each group variable in each folder that must be preserved over time and through a game save. Here is the code to use. Rename the event according to the folder it is in since I don't think you can have two events with the same name.

Counting Events

You can also use group variables as counters for counting the number of times an event fires. This could be used as part of a time sequenced event to make a countdown or to keep track of unit or building numbers when using looping events.

The spray3 event below is an example of a looping counter. The variable GroupVariable2 is increased by one each time the event is executed to keep track of the number of lumberjacks killed. The union51 event in the Looping Events section is another example of a counting event.

Random Events

I like to use random numbers occasionally to vary the time when an event is triggered or the value of an event effect. This adds more replayability to a scenario by making each game play a little different.

Here is an example of a random number used to stop the looping for the spray3 event above. The random number will be something between 1 and 11 since it takes the random number, adds 10 and then divides by 10. This number is then saved in GroupVariable3.

If-Then-Else Events

Sometimes you may want to script an event with several possible outcomes depending on a certain value. For example, if GV1>10 do this, else do this. You cannot do this in a single event since only one condition can be evaluated at a time. But you can take advantage of the callevent effect to first set the variable, then call as many events as you want to evaluate possible outcomes.

This is illustrated in the above example with the events called by the event spray2. The next event, spray3, was described above in the Counting Events section. See below for the subsquent events.

The if-then-else sequence starts in event spray4, which is only executed if the counter GV2=1, meaning only one lumberjack died. If true, this event gives the appropriate message and effects. Then event spray5 is checked and will execute if GV2>1. Finally, spray6 will be called and will execute if GV2=0. Not that each of the evaluation conditions must be mutually exclusive so that only one of the events will trigger, unless for some strange reason you want overlapping events.

Looping Events

Looping events are used to cycle through units or buildings with the LoopThroughAllUnits or LoopThroughAllBuildings command. When the event is checked, it will loop through all units looking for the conditions specified. If the AlwaysTrue statement is included, the event will be executed on all units. You can use conditions to narrow down the units affected using the UnitType=UnitType??? or BldgType=BldgType??? commands. You can use further conditions to either stop the looping or further narrow down the action to certain units or buildings.

In general, it is more efficient to make a looping event a called event, so that you first check for the conditions under which you want the looping event to be executed and then call the looping event itself. This avoids having the event checked multiple times through all units or buildings for nothing.

An example of looping through units has already been shown in the If-Then-Else section for the spray events.

Another example of looping events, which I am particularly fond of, is the sequence of union events in my Wooden Limbs scenario. A sample of these events is shown below. Event union1 is set to execute only once at the beginning of month 9 any year after or including 1970. It loops through all buildings, checking for BldgTypeVehicleDepot (a.k.a. Teamsters Office). When it finds one, it checks if the BldgPay is less than the Caribbean Average rounded down by $1 and it will be executed as soon as at least one teamsters office meets these conditions. Then it presents the choices to the player as follows:

1. Choose to give the raise. Note that the events cannot actually raise the pay, the player has to do this manually, so this choice effect only sets a flag of GV1 = 1 to remember this choice.
2. Choose a lump sum payment. If this is chosen, the treasury is debited the $20,000 and it calls event union15. This event loops through all units and gives teamsters only a raise in job quality.
3. Choose to fire all teamsters. This sets a flag of GV3 = 1 for later use with the dockworkers union and then calls event union2. This event loops through all buildings and fires workers at each teamsters office.

If option 1 is chosen, event union3 then takes place at the end of the same month or any month up to the end of the year, since the flag GV1 is now =1. This event calls event union31 to loop through the buildings and check the pay to see if the player has raised it or not. If not, then GV1 is set to 2, setting a flag for the next event.

Tip: Note that if a looping event has a message, you do not usually want to have a message pop up for each time the event executes, i.e. for each unit or building, so it is best to set a flag using a group variable and then have the flag trigger the message event. Or have the calling event first call the looping event, then call a second event for the message to display the results of the looping event.

Event union4 is triggered by the flag GV1=2 and gives the message that the teamsters are still not happy. Note that none of these events are set to ExecuteOnlyOnce, since I want to have this sequence be checked every year to see if the average wage has changed and to ensure the player has not lowered the wages again. However, the looping event and the message will only appear once in the year since both event union31 and union4 increment the GV1 flag by 1.

Event union5 begins the year end sequence to actually take the protest action by checking if flag GV1=3, meaning the warning has been given. If it is, it calls events union51, union6 and union61. Event union51 checks the building pay again to be sure the player has not changed it since the warning, and if not, causes it to collapse. This is done for each building that is a VehicleDepot (Teamsters Office). It also increments a counter, GV2, to count how many buildings collapse. Events union6 and union61 are then used to evaluate the counter GV2 in an if-then-else manner. If GV2=1 then the message is given that one office has collapsed. If GV2>1 it tells how many have collapsed. If GV2=0, then no buildings have collapsed and no message is needed.

Finally, at the beginning of the year, the GV1 flag is reset to 1 and GV2 to 0 by event union7 so the whole sequence can start again. Wasn’t that fun!

Note that this description may vary from the actual events in my scenario since I have refined it since then based on the suggestions above for looping events. For example, I was originally using GV4 as a flag to trigger events union6 and union61. But calling them in sequence is easier and saves a variable.

Here are the examples: