13.4 - Event Scripting

By: CafeDave

General Comments on Events

Once again, before proceeding, make sure you are familiar with the basic event syntax from the event editor documentation scripting section, since I will not go over this in detail. However, these are some general comments on events and some quirks to watch out for:

There is a certain priority to the sequence of events based on frequency of checking and the type of event. The observed priority for check frequency is as follows, assuming otherwise equal conditions:

• Briefing
• YearBegin
• MonthBegin
• WeekBegin
• DayBegin
• DayEnd
• WeekEnd
• MonthEnd
• YearEnd
• AlmanacScore

For type of event, a choice event will have priority over a normal message event, at least in terms of the message dialog box.

The other factor that may affect sequencing of events is the order in which they appear in the group folder, but I am not sure on this. I name events in sequence so that they will be in the right order just for ease of editing and troubleshooting.

Most regular events should have this setting as a default just to be sure an event executes only once even if the conditions should only be true one time. This will avoid accidental repetition every year or month, for example, once a set of conditions has been met. The exceptions of course are events that you want to intentionally repeat such as looping events or periodic events.

The evaluation of general effects always takes place before a message dialog box is shown, regardless of whether the effects are listed before the message or after. This is so that effects can set variables for use in messages. Therefore, take care that if you want to use a variable in a message and then set it to something else, you should use a call event to first show the message and then another to change the variable. Of course, choice effects are not evaluated until the choice is actually made by the player.

You can use any standard mathematical expressions in the condition and effects statements with a couple of caveats. One is that the game appears not to like decimals and rounds them to the nearest integer or zero if less than 1. To get around this, instead of multiplying by 0.25, divide by 4 and the expression should work properly. Use the * and / expressions to do normal multiplication and division. Also note that the MultiplyBy function is only valid for certain variables and should be used with care.

Be very careful if using the Event Creator program, since it has a bug that does not allow expressions other than numbers in the effects. You can edit these manually once you have saved a scenario's events created with the program, but from then on, you will have to edit manually since the program will set any expressions to zero when brought into the Event Creator. Hopefully this will be fixed at some future date, but be aware of it for now.

You can also use logical expressions in conditions and effects statements to establish secondary conditions within an event without calling a second event. This is not usually necessary but could have applications somewhere. One example is my variable saver event. More on this event later.

The only special character used by the event editor is the '\n' carriage return sequence used in message text. A message must be all on one line with the '\n' used to force a line break. Put two in a row to give a blank line. If you put a normal return within a message before the final quote, Tropico will not be able to parse it and give an error.

You may have as many or few blank lines in your event as you want. They may help improve readability of the event when creating it but are ignored by the editor.

You may also use upper or lower case or mixed for any event statements. It does not seem to matter to the game. I prefer to keep it mixed case as the statements are shown in the Conditions and Effects listings for legibility.

Like most scripting languages, the event editor does allow comments to be embedded in the events as an aid to remembering why you did things a certain way or to help others understand your logic (or lack thereof!). To add a comment, just precede the line with a semi-colon and it will be ignored by the editor.

Event Checking and Execution

To understand how event scripting works, it is important to understand the difference between event checking and event execution. An event is checked at the frequency given by the mandatory CheckFrequency statement. If the frequency is set at YearEnd, the event will only be checked once at the end of each year. If set to DayBegin, it will be checked at the beginning of each day. If set to one of the special frequencies such as Briefing or AlmanacScore, the event will only be checked at the beginning of the game or when the almanac is displayed. And of course, an event set to frequency OnlyWhenCalled will only be checked when called by another event.

The important thing about checking event frequency is that your conditions must take into account when the event will be checked and what the possible conditions are at that point. For example, if you have set an event to be checked at the beginning of the month and one of your conditions is Condition Day=15, the event will never trigger since the beginning of the month will only have day=1.

Regardless of how often an event is checked, it will only be executed when the specified conditions are met or if the AlwaysTrue statement is specified in the event. Note that if AlwaysTrue is used, the event will be executed regardless of any condition statements given. This is useful for using the condition value as a [TRIGGER] text replacement value. See the Almanac Score event section below for an example. I think there is also another bug in Lord_Corwin's Event Creator that does not allow you to put both an AlwaysTrue statement and a Condition statement, so you will need to add this manually if using that editor.

Once an event has been executed, the effects given in the event will be carried out and any message displayed. Except for looping events, an event will only be executed once for any given check. However, a single event can trigger further events using the effect CallEvent. See the If-Then-Else section for an example of how useful this can be.

Unless the statement ExecuteOnlyOnce is included in an event, it will be executed each time it is checked and meets the given conditions. Therefore, it is important to always include ExecuteOnlyOnce in an event that you only want to appear once. This also helps reduce game calculations later on since once an event with this statement has been executed, it is not included in any further checks. Similarly, it is important NOT to include this for events you want to repeat, such as a yearly payment or annual notice and especially for a looping event unless you only want it to be executed for the first unit or building found. Remember, using ExecuteOnlyOnce does not affect how often an event is checked, only how often it is executed, so an event will continue to be checked at the frequency specified until it is actually executed.