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!
