# Working With SEXPs

| This file explains how to use SEXPs, or symbolic expressions, to program complex behavior into your missions. (It's pronounced "sex pee". Stop snickering!) While FRED2'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

## Introduction to SEXPs

| 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. A SEXP examines the state of the mission (which ships have been destroyed, how much time has passed, what cargo has been inspected, and so forth). Based on this information, the SEXP either does something (like turning a friendly ship hostile) or returns (computes) some value. Most SEXPs return a "boolean" true-or-false value, but some return a number or a text string. You can use this returned value to trigger events, such as radio messages and ship arrivals.

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.

Here's a more complicated one:
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.

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!

## SEXP Operators

| 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 FRED2, 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.

In order to help you find the operator you want, the operators within each category are listed below. Most of them 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.

`is-destroyed-delay is-subsystem-destroyed-delay is-disabled-delay is-disarmed-delay has-docked-delay
has-undocked-delay
has-arrived-delay`
`has-departed-delay
are-waypoints-done-delay
ship-type-destroyed
percent-ships-departed
percent-ships-destroyed
depart-node-delay
destroyed-or-departed-delay`

### Time

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

`time-ship-destroyed time-ship-arrived time-ship-departed time-wing-destroyed time-wing-arrived` | `time-wing-departed mission-time time-docked time-undocked`

### Logical

Most of these operators combine numbers or boolean values. They return boolean values.

`true false and and-in-sequence or
not`
`=
>
<
is-iff
has-time-elapsed`

### Arithmetic

Most of these operators combine numbers. They return numbers.

`+ - *` | `/ mod rand`

### Status

These operators determine the state of particular ships or of the mission in general. Some of them return numbers, some return boolean values.

`is-cargo-known-delay cap-subsys-cargo-known-delay has-been-tagged-delay is-tagged num-kills
num-type-kills
num-class-kills
shield-recharge-pct
engine-recharge-pct
weapons-recharge-pct
shield-quad-low
`
`secondary-ammo-pct
is-secondary-selected
is-primary-selected
shields-left
hits-left
hits-left-subsystem
distance
time-elapsed-last-order
skill-level-at-least
num-players
special-warp-dist`

### Change

These operators cause things happen. They do not return values. Because this group is so large, you will have to use the triangles at the top and bottom of the menu to scroll through it.

`modify-variable special-warpout-name do-nothing add-goal clear-goals
change-iff
protect-ship
unprotect-ship
beam-protect-ship
beam-unprotect-ship
send-message
self-destruct
end-campaign
sabotage-subsystem
repair-subsystem
set-subsystem-strength
invalidate-goal
validate-goal
send-random-message
transfer-cargo
exchange-cargo
good-rearm-time
allow-ship
allow-weapon
break-warp
fix-warp
never-warp
allow-warp
`
`good-secondary-time
ship-invisible
ship-visible
ship-invulnerable
ship-vulnerable
red-alert
jettison-cargo-delay
fire-beam
beam-free
beam-free-all
beam-lock
beam-lock-all
turret-free
turret-free-all
turret-lock
turret-lock-all
add-remove-escort
awacs-set-radius
send-message-list
cap-waypoint-speed
ship-guardian
ship-no-guardian
turret-tagged-only
turret-tagged-clear
subsys-set-random
supernova-start
cargo-no-deplete`

### Conditional

There is only one operator in this group, `when`. It is the top-level operator in most events ("When this happens, do these things"), and returns a boolean value.

### Debugging

This group also contains only one operator, `debug`. You probably won't need this one.

### AI Goals

These operators affect the behavior of computer-controlled ships. They return ship goals, which can be only be used as the second argument to the `add-goal` operator. 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, consider the `beam-fire` operator.

`ai-chase ai-dock ai-undock ai-warp-out ai-waypoints
ai-waypoints-once
ai-destroy-subsystem
ai-disable-ship
ai-disarm-ship`
`ai-guard
ai-chase-any
ai-evade-ship
ai-stay-near-ship
ai-keep-safe-distance
ai-ignore
ai-stay-still
ai-play-dead`

### 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.

`is-goal-incomplete is-goal-true-delay is-goal-false-delay is-event-incomplete is-event-true-delay` | `is-event-false-delay is-previous-goal-true is-previous-goal-false is-previous-event-true is-previous-event-false`

### Training

These operators are used mainly in pilot training missions. Some of them return boolean values, some do not return anything.

`key-pressed key-reset targeted speed facing
facing-waypoint
order
waypoint-missed
`
`waypoint-twice
path-flown
training-msg
flash-hud-guage
special-check
secondaries-depleted
set-training-context-fly-path
set-training-context-speed`