Working With SEXPs

This file explains how to use SEXPs, or symbolic expressions, to program complex behavior into your missions. (There is some debate about whether it's pronounced "ess XP" or "sex pee")

While FRED's SEXPs are easy to use, they are enormously powerful. These help files only begin to touch on the possibilities; the on-line FreeSpace 2 community will no doubt use SEXPs to do things the designers of FreeSpace 2 never imagined.

The sections of this file are:

• Introduction to SEXPs
• SEXP Operators

SEXPs are used to control the events that occur within a FreeSpace 2 mission. They are used in the Ships, Wings, Mission Objectives, Events, Briefing, Debriefing, and Campaign editors.

Most SEXPs do one of two basic things. They either make something happen (like turning a friendly ship hostile, sending a message, etc) or test to see if something has happened (which ships have been destroyed, how much time has passed, what cargo has been inspected, and so forth). This second kind can be futher split depending on what kind of information they come back with. Many of them return true or false answers (Has ship x been destroyed?) while other return numbers (What is the distance between ship x and ship y? How many missiles does the player have left?).

For example, you can tell a ship to warp in 15 seconds after the GTT Patterson departs by putting putting the SEXP below in the Arrival Cue section of the Ships editor.

This SEXP is composed of an operator (has-departed-delay) and two arguments (15 and GTT Patterson). The number of arguments can vary.

You can recognize the operator by the red op next to it. The little sheets of paper next to the other lines indicate that they are plain data. Every 5th argument is numbered to make it easier to keep track.

Here's a more complicated SEXP:

This SEXP becomes true when 75% of Beta wing has been destroyed and the SC Hastur has been disabled (for at least 0 seconds). The main operator of this SEXP is and; its arguments are themselves SEXPs, sometimes called sub-SEXPs.

If you click on the little minus sign to the left of an operator, its arguments are hidden and the minus sign turns into a plus.

Click on it again to show the arguments.

When using the Events Editor you will come across the 3rd kind of SEXP, the conditional operator. All this does is say IF x is true, DO y. Here's an example.

In this case when is the conditional. It has two parts, the trigger and the action. When the Pegasus is destroyed the trigger will now be true and the action will happen. You may have noticed the words Pegasus Destroyed above the SEXP. The Events Editor allows you to put a name above each conditional operator for easy reference. The whole things is now called an Event. Events help organise the SEXPs in your mission. You can test if events have happened quite easily too using the is-event-true-delay SEXP which helps avoid having to duplicate the entire trigger again.

Whenever you highlight an operator (by clicking on it), help appears at the bottom of the editor explaining how that operator works. Here is the help for has-departed-delay:

Has departed delay (Boolean operator) Becomes true <delay> seconds after the specified ship(s) or wing(s) have departed from the mission by warping out. If any ship was destroyed, this operator will never be true. Returns a boolean value; Takes 2 or more arguments:    1:       Time delay in seconds (see above).    Rest:  Name of ship (or wing) we want to check has departed.

You can turn SEXP help off by unchecking Show SEXP Help in the Help Menu.

To edit a line in a SEXP, right click on it. You'll see a menu like the one shown at right. Different items will be grayed out depending on the situation.

Delete Item deletes the current line and any sub-SEXPs under it. For example, if you delete an operator, its arguments will also get deleted.

Edit Data is used to edit lines containing raw data, like numbers and text strings.

Expand All shows the arguments of the current operator. It's similar to clicking on the minus sign to the left of the operator, but it also expands any sub-SEXPs.

Cut, Copy, and Paste work just as you'd expect. Add Paste adds whatever SEXP is on the clipboard (the one most recently cut or copied) as an additional argument to the current operator.

Add Operator adds a new operator as an argument to the current operator. (It gives you a huge menu of operators to choose from; more on those in a moment.) Add Data lets you add a number or string, or possibly the name of an object, event, or objective.

Insert Operator replaces this operator with a new one (such as and) and makes the current operator an argument of the new one. For example, if you had this SEXP

and then picked Insert Operator and, you'd get this one:

Replace Operator and Replace Data replace the current line (and any sub-SEXPs).

You can create variables to store information (numbers and text strings). Use Add Variable to make a new one and set its default value. Use Modify Variable to remove a variable or change its default value. (If you want to change a variable's value during the course of a mission, use the modify-variable operator.) Replace Variable replaces the current line of data with one of the variables you've defined. Variable names and string variable values cannot contain spaces.

A few words about incomplete values are in order. Some boolean SEXP operators (such as is-destroyed-delay) can return the value incomplete instead of true or false. This will change to true or false when appropriate. (is-destroyed-delay becomes true when all of the specified ships are destroyed, false when at least one of them departs.)

There are three places where this can cause trouble:

• Anything which is incomplete at the end of a mission becomes false. Therefore, the operators is-goal-incomplete and is-event-incomplete should never be used in debriefing or campaign branch SEXPs.
• Once an entire SEXP (for example, an event) returns something other than incomplete, it will not be evaluated again. (Events with a Repeat Count of more than 1 are an exception to this.)
  
• If the not operator is given incomplete as an argument, it returns true.

  Specifically, consider this SEXP:
  
  At the beginning of the mission, the is-destroyed-delay sub-SEXP returns incomplete. Therefore, the not returns true, and the event occurs immediately at the beginning of the mission!
  

There are a lot of operators in FRED2. Fortunately, the SEXP help explains what each one does when you highlight it.

When you go to pick an operator in FRED, many choices will be grayed out. This is usually because they don't return the right type of information; for example, the time-docked operator returns a number, so you can't use it as the first argument of a when, which must be boolean (i.e a true or false)..

When the original FRED documentation was written, it listed all the SEXPs that were available to you. There is little point in doing that now though. Since the source code release the number of SEXPs available to the mission designer has been vastly increased and new ones are added every month. Instead we'll cover the the major groups and subgroups that they are organised into. Most of the SEXPs are self-explanatory. If you're not sure about how to use one, create a SEXP using it, highlight it, and look at the SEXP help at the bottom of the editor.

Objectives

These operators determine if primitive events (such as ship destruction) have occurred. They return boolean values.

Time

These operators determine when (in seconds since the beginning of the mission) events happened. They return numbers.

Logical

Most of these operators combine or compare numbers or boolean values. Also included in this category are SEXPs for comparing strings against each other (a string is a sequence of letters, for instance a ship or weapon name). They return boolean values.

Arithmetic

Most of these operators combine numbers. SEXPs for generating random numbers are also in this group. They return numbers.

Status

These operators determine the state of particular ships or of the mission in general. Some of them return numbers, some return boolean values. This catagory is so big that it has been broken up into subcategories based on what these SEXPs test.

Change

These operators cause things to happen. They do not return values. Because this group is so large it has also been broken down into subcatergories.

Conditional

Before the source code was released there was only one operator in this group, when. Although still the most commonly used of all conditionals, more specialised alternatives have been added that allow you to do the same thing to multiple ships (for instance it is now possible to use a SEXP to say IF ship x,y, or z have done something DO something to the ones that have).

AI Goals

These operators affect the behavior of computer-controlled ships. They return ship goals, which can be only be used as an argument to the add-goal and remove-goal operators. Some of these goals cannot be given to certain types of ships; for example, capital ships cannot perform the ai-guard order.

The ai-chase goal is equivalent to "attack" for fighters and bombers. For larger ships, "chase" is a better word; they will try to stay near the specified ship, but they will still fire at the most threatening target in the area. If you need to choreograph capital ship fire in more detail you may want to consider having the capital ships follow waypoints instead so that you can put them exactly where you want them.

Events / Goals

These operators determine whether events have occurred or goals have been met. They return boolean values.

The "previous" operators in this group refer to things that happened in a previous mission in a campaign.

Training

These operators were used mainly in pilot training missions in Freespace 2. However they are very useful and as such have since found lots of uses in non-training missions. Some of them return boolean values, some do not return anything.