Counting with variables

This tutorial teaches you how to combine when-argument and variables.

Prerequisites

• FreeSpace Open 3.6.12 (minimum)
• Basic knowledge of SEXPs
• Basic knowledge of variables
• Basic knowledge of mission messages

Example mission

Grab the basic mission here. Add the new events yourself, based on this tutorial.

This example mission is similar to Doomsday, but engineered for the purposes of this tutorial. The GTD Galatea deploys 8 escape pods, which must be protected. For simplicity's sake, there are no enemies, but the player can destroy the pods himself to have a better control over the mission outcome. The traitor mechanism has been disabled also.

Set up variables

The mission requires three variables. The name of the variable doesn't matter, as long as you recognize what it stands for, it will not cause a problem. All these are number variables, with a default value of 0.

• @EPDeparted: Counts how many pods escaped
• @EPDestroyed: Counts how many were destroyed
• @EPDealtWith: Counts how many pods are out of the picture (destroyed or departed). This third one is needed for the RTB directive. If you don't want to tie your RTB trigger to this, you can skip this variable.

The @ notation indicates a variable. When creating the variables, you must not include this notation.

Counting events

We need two events, one that counts how many pods were destroyed and one that counts how many departed.

This is just the event that counts the destroyed pods. The event that counts the departed pods is the same, with is-destroyed-delay changed to has-departed-delay and the variable changed to EPDeparted.

And here are the relevant notions explained one by one.

when-argument and any-of

Each line under any-of must match the name of an escape pod. This line will be furthermore referred to as an "argument." When inputting each argument, make sure there are no typos in it. To add an argument, right-click on any-of --> Add Data --> String

<argument>

This refers to the arguments below any-of. If any of the escape pods (which are the arguments) are destroyed, it will trigger the event.

modify-variable

Once the event is triggered, modify-variable is used to add 1 to a variable. If a pod is destroyed, @EPDestroyed is increased by 1; if a pod departs, @EPDeparted is increased by 1.

invalidate-argument

Removes the already activated argument from the event to make sure the same pod doesn't get counted twice. If you forget to invalidate the already triggered argument, the mission will break. Notice that by default, this SEXP's default argument is <any data>, not <argument>. Right click on <any data> --> Replace Data --> <argument>. Invalidate-argument is always at the end of the SEXP tree.

Trigger count

Trigger count must be as high as the number of arguments under any-of. Note: This is trigger count, not repeat count (see this for explanation).

Error checking

This step is optional.

You can check if your events were set up properly in-flight, through messages.

Set up this new message:

Departed: $EPDeparted Destroyed: $EPDestroyed Dealt With: $EPDealtWith

Have this message sent with each event that modifies a variable. Now, every time a variable changes, it will be communicated to you in-mission. Notice the $ symbol.

Obviously, if you don't want to work with @EPDealtWith, then remove it from the message.

RTB directive

This step is optional.

Time to put our @EPDealtWith variable to use. In this example mission, you receive the "Return to base" order once the fates of all 8 escape pods are sealed. The two variables that we have been dealing with counted the pods separately. For the RTB order, we need a variable that counts how many pods have been destroyed or departed. Once this variable hits 8, the RTB directive is triggered.

Finally

Grab the complete mission file here and juxtapose it with your version.

Exercises

Duplicate the (complete) mission file and do the exercises in a separate mission file.

1. Add the debriefing stages with the following specifications:
   1. 8 pods saved: "Excellent work. All pods have been saved."
   2. 5-7 pods saved: "A handful of escape pods survived the engagement. The survivors are being transferred to the GTD Bastion as we speak."
   3. 1-4 pods saved: "We lost many good people today."
   4. 0 pods saved: "It's incredible that you failed to save a single pod. You are responsible for hundreds of deaths today."
   5. If the player goes AWOL, only the default AWOL message must appear.
2. Add a "Protect Escape Pods" mission goal with the following specifications:
   1. The mission goal turns complete when at least 5 pods are saved.
   2. The mission goal fails when at least 4 pods are destroyed.
   3. The mission goal is only displayed once all 8 pods have been destroyed or jumped.
3. (in yet another separate file) Remove two escape pods and edit the mission events accordingly.