Campaigns Editor: Execution Order

### The structure of a campaign

The player's experience of the game is an alternation between two modes: player control and campaign script control. Except at the very start of the game, a campaign script gains control when its wait node triggers. From the developer's point of view, each campaign script typically (but not always) consists of two parts: wrapping up the current mission and setting up the next mission.

Usually, there's one script that's activated at the start of the campaign, and the rest are activated through wait nodes. Each of those scripts consists of a wait node (occasionally more than one) followed by a string of action nodes.

With a few exceptions, each action node can connect to just one following action node, but it isn't required to. Each node can also launch any number of wait nodes.

Each wait node can connect to any combination of action nodes and wait nodes.

### Example of single-path campaign

You'll probably have a single path through most of your campaign, with one node leading to another until you reach the final node. That part is simple, but the simplicity is perhaps misleading. That main path is almost certainly a sequence of scripts, with a new script starting at each wait node.

Using the start of the main campaign as an example:

* Script at game start: cousin talks to you, then you get mission to save DTS1504.
* Player control. Not much you can do at this point other than go save DTS1504, though.
* Script when pirate fleet destroyed: you meet Marcus and he tells you to meet him at Orion.
* Player control. Not much you can do at this point other than go to Orion, where you encounter another pirate fleet.
* Script when docked at Orion (only possible after pirate fleet destroyed): get reward (250 C) and some chatter. Most stations in the system are created.
* Player control. Undock at your pleasure.
* Script when undocked: cousin tells you to go to Green Farm to pick up transport ship.
* Player control.

### Side scripts

You can have multiple scripts active at once. Continuing with the example above:

* Script when docked at Green Farm: get T4 Gorilla ship and 250 C seed money. Other Earth stations are created.
* Player control. Undock at your pleasure.
* Side script when undocked: activate general contract offers from Delta, then the script ends.
* Player control.
* Script when cash is over 600 C: get reward of 250 C. Cousin tells you to dock at Parabellum.
* Player control.

In this case the side script easily could have been a main line script, but the side script method works and that's how the main campaign actually does it.

One of the most common uses for multiple active scripts is for multiple enemy fleets. The player can attack those fleets in whichever order they want, because all of the "when fleet destroyed" scripts are simultaneously waiting for their chance to run. Typically there'll also be a "main line" script waiting for *all* of the fleets to be destroyed. That script doesn't care which order they're destroyed in, except that it might be changing which fleet is highlighted on the map to show which of the remaining targets is top priority -- in that case it'll want to check the top priority target first and the lowest priority one last.

### Choice between scripts ("if" or "case" construct)

Sometimes you need to choose between multiple scripts rather than activate all of them at once. For that there's a special action node called "Single path." All of the wait nodes it connects to are treated as conditional tests, not as wait nodes. The "Single path" node will run the first wait node it finds that is already true and will ignore the other wait nodes. If none of them are true, none will be run; that implies that no waiting will ever occur when using a "Single path" node. If there's also an action node connected, it'll be run, too. By the way, the "Fleet alive" wait node is useful *only* as a test node, because a fleet can't be resurrected. *Note: the documentation on the "Single path" special node may be swapped with the "Toggle node state" action.*

The Dialog action node provides the ability to branch within a single script, depending on whether the player responds "Yes" or "No." No wait nodes are involved, and the player can't do anything until they make a choice. Remember that unless the player is docked, their ship makes slow left circles until they make a choice and could crash into something.

### Multiple paths to a single wait node (rejoining paths)

Sometimes you might want to diverge to more than one path, then bring them all back to the same point. This isn't a problem if they're rejoining at an action node.

If they're rejoining at a wait node, there's a complication. A wait node won't start waiting until *all* paths coming in have been activated. In other words, the player would have to have taken *all* of the paths before the wait node is functional, and before the script connected to the wait node will run.

To allow you to get around this problem, there's a special action node called "Toggle node state." In its default "Enable node" form, it will cause the connected wait node to not require that path to be executed in order for the wait node to run.

You probably don't want to use Toggle nodes on *every* path into one wait node, because in that case the wait node activates at the start of the game. You usually will want exactly one path into the wait node to be the activating path, while the others are connected through Toggle nodes.

### Loops

You can create loops easily enough. There are a couple of considerations, though.

If you're looping back to a wait node, you probably want to use a "Toggle node state" node at the connection back to the wait node, in order to let that wait node function. See the previous section.

Also, be sure that you connect the loop-back to a wait node that isn't always true. For example, if you've got a script that you want run every time the player docks at a certain station, be sure you wait for the player to undock before you loop back to the "wait for docking" node. During testing, it can be valuable to insert a Yes/No dialog node in the loop, just to allow you to break the loop if it runs away.

### Deactivating waiting nodes

Normally, once a wait node is activated, it'll wait until the end of the game (if necessary) for its condition to come true. Sometimes you don't want a particular wait node to keep waiting after something else has happened.

For that situation, it's possible to use the "Toggle node state" action node to *deactivate* a wait node. These things can be a bit tricky to set up, because the Toggle node has to link to the wait node to be deactivated, and that particular path can never move forward. Putting the deactivation nodes on separate branches, following wait nodes that are always true (for example, player has more than 0 ships) is often necessary in these cases.

Note that the "Enable node" option affects the wait node *before* it has started waiting, while the "Disable node" option affects the wait node *after* it has started waiting.

### Connections to other nodes aren't required

Nodes don't need to have connections going out to later nodes. In particular, side scripts will typically just end when they're done.

Nodes also don't need to have connections coming in from earlier nodes. All such nodes will be run at the beginning of the campaign. In particular, the starting node of your campaign won't have a connection coming in.