This guide is from the FSDeveloper Wiki:
Feel free to suggest changes and additions!
Creating a mission is a complex task involving a diverse use of tools & skills. Getting your first mission going is likely to cause you some headaches.
Still here? Good. Once you do have that first one running, the sky’s your limit. That basic set of rules and files that make up a mission are always the same so once you’ve got those sorted, it’s just a case of coming up with an idea and writing it.
At it’s simplest, a mission is just a scripted set of events that tell some kind of story. It may be dramatic - mountain rescue, failing aircraft, poor weather. It could just as easily be a simple flight from A to B with you pointing out areas of interest along the way, or a completely abstract challenge like finding out how many times you can touch-and-go in a 747 in five minutes.
Technically speaking, there are two main classes of things in a mission; Actions and Triggers. An Action makes something happen, and a Trigger checks to see if something’s happened and calls an Action if it has. By stringing together Actions and Triggers, you tell your story.
You’ll also need to prepare the conditions of your flight; what will be the plane, time, location, route, and weather of your mission? Are there other planes flying around or parked on the airport? And how much assistance will you give the player?
Lastly, your mission will need sound files for the mission speech and some text and images for the briefing, loading, and ending screens.
Ⅰ. Before coding
1. Come up with a basic storyline
The first step of creating a mission is coming up with a scenario and story. You can make a tutorial, emergency scenario, even a treasure hunt, but you will need to think of a mission progression. What is the start of the mission? What will you need to tell the player and what will they have to find out on their own? What are the possible ways to complete the mission? Are there branching paths? And of course, how will the mission end? Will the player receive a grade or reward?
It can help to have a written structure. Think of it as a screenplay, and follow the same three-stage layout.
The first section is your introduction. You need to get the player’s interest, explain who they are and why they’re there. You use the first bit to get everything set up so that when The Exciting Thing happens, they know why and what to do about it.
In part two, The Exciting Thing happens. It doesn’t matter what it is, but assuming you have some kind of event to which the player is supposed to react, this part details what happens. Once they’ve managed to cope with the situation and get it under control, they move on to…
Part three, the conclusion. Having successfully dealt with the engine fire/squalling brats in the back seats/condor-strike, the player gets to reflect on what they’ve done and enjoy the feeling of success for a little while. You could always throw in a last-minute plot twist of course.
Structuring like this gives you a tidy way of making your mission appear much more complex. You can easily provide different threads, or ways of achieving something, without too much extra effort. Let’s say your Introduction sees the player getting from a bush strip to the head of a particular valley. You start with them following the river, simple enough. Later on, you could add the option to fly across the peaks and save time; as long as they reach the same head of the same valley, the rest of the mission isn’t affected. If they’ve tried the mission before and failed, chances are they’ll decide to try shortcuts anyway. Wouldn’t it feel better if, having decided to cross the ridge instead of fly round, the mission reacts to that by saying “Hey, you’re going over the ridge! A bit risky in this weather but the views will be stunning”? You can issue different Rewards, or maybe even alter how the next section plays out, depending on the path they took.
In short, you can see your mission sections as leading up to choke-points, such as the head of the valley. If you have three sections, each with three different ways of achieving it, that’s nine different ways of flying a single mission.
2. Turn your story into a mission
Now comes the longest, and hopefully the most fun part; turning your idea into an immersive mission.
First, you have to clearly define the flow of the mission. You may find it easier to have a big sheet of paper and draw the mission out in pencil before you start coding. That lets you work out how it fits together logically without having to worry about whether or not you’ve got the spelling right.
For example, you know that after you take off you want to have some speech, and then there are three ways of getting from A to B, where the next section starts. OK, so that’s three boxes to draw; ‘Takeoff’, ‘Speech’ and ‘At point B’. The speech should happen 30 seconds after takeoff, so note that down next to the Speech box. Then you can draw three lines between ‘Speech’ and ‘At Point B’ to show the three paths, and the first thing to do on each path is disable the other two paths.
Already you’ve got a decent map of what happens in what order, and translating from these into actual mission-system code will be easier.
To keep the example going, you might have a PropertyTrigger checking “Altitude AGL > 10” to test for takeoff. That would start a 30-second TimerTrigger using an ObjectActivationAction which, in turn, would call a DialogAction for your “Speech” box. You would need one Trigger per potential path; they might be set to detect altitude, or heading, or more likely that the player has entered an area. Each of those would need another DialogAction (just to keep the player informed), an ObjectActivationAction to enable the Trigger that checks “At Point B” and another ObjectActivationAction to disable the other two paths.
3. Create a mission project
4. Decide on flight conditions
Next, you will have to configure the flight conditions. To start, you can create a flight plan in the worldmap or with Little Navmap. This flight plan will be shown to the player when the mission starts, so it shouldn’t spoil the unexpected parts of the flight (e.g., an emergency).
Then you decide on the starting point of the mission (e.g., at the beginning of the flight or in the air somewhere along the route).
4.1 Create the flight file
To create the flight file, load the flightplan and select the desired starting location in the worldmap. Now choose the aircraft, livery, fuel, payload, and atc options. Then choose the time, weather preset, and the multiplayer and traffic settings. Load the flight. Set up the aircraft how you want it (lights, switches, autopilot, etc.). You can customize the weather and save it as a preset. Lastly, locate the plane exactly where you want it, with the correct speed and trim settings. Then click
ESC to pause the game and then
SPACE to save the flight as a
.FLT. Move the flight file and flightplan to the mission project.
Lastly, you will have to add pictures for the mission thumbnail, and the loading, briefing, and ending screens. The names for the loading an briefing pictures are defined in the .FLT file. The thumbnail will need to be named:
Activity_Widget.jpg and the endscreen picture will need to be named:
rewardscreen.jpg. You can use the pictures in the SimpleMission project as a reference.
4.2 Define custom weather
You can customize the weather with the weather panel during flight. Save it as a new preset. You can find the .WPR file in
\AppData\Roaming\Microsoft Flight Simulator\Weather\Presets\. Move it next to the .flt file and rename it to
Weather.WPR. You can fine-tune the weather by editing the .WPR file in Notepad++. You can use the .WPR in the SimpleMission project as a reference.
5. Set up a mission script
You can set up a mission script with the SimpleMission sample project. The SimpleMission sample project contains an .xml you can use as a starting point. Download it and complete steps 1 to 3 of the guide.
Ⅱ. Coding your mission
Now you will turn your mission diagram from Chapter 2 into a mission script. For this you can use the script editor.
1. Script editor
With the project open, select your mission asset group and click load in editor:
With the built-in script editor you can create the mission with a visual representation of the script. All building blocks of the mission – such as triggers and actions – are represented by nodes (also called mission objects). Each node contains some settings specific to the building block and can be connected to other nodes.
Some of the nodes of a basic mission
Nodes have two types of connections. Connections on the right size are references to other nodes and connections on the left size means the node is referenced by other nodes.
You can use special comment nodes to clarify the working of complex missions:
2. Script Building Blocks
There are different types of nodes that you can use to make your mission.
2.1 Triggers & Actions
2.2 Mission objects
Mission objects define a range of things like mission type, goals, world traffic, camera, and thermals.
You can use calculators for more advanced logic in your mission. It can take in multiple variables and trigger different actions based on a logic. You can also use this to calculate a mission score and probably many more applications which you can explore.
3. Creating your mission script
You need to turn your mission diagram into a mission script with the script editor. For everything that happens in your mission, you need to choose and add the correct triggers and link them to actions. For each trigger you have to think: maybe you want something to happen after 10 seconds, or when the plane is at a particular location? There are many triggers too choose from, so you will need to familiarize yourself with all the triggers available to you, so you can choose the one you need.
3.1 Placing objects in the world
Before you can place objects in the world you have to start a flight and load the mission. The process for loading the mission is described in Chapter 4.
3.2 The main mission object
You use the mission object to add objectives and an ending to your mission. You can choose from different types, according to the type of mission you’re creating.
Objectives and goal nodes
You can add objectives to your mission that determine the mission ending. Each objective has a state that can determine the mission ending. If any objective is set to Failed or Aborted, the mission ends with pupup and a short message. If all objectives are set to Completed, the mission ends with a debriefing / rewardscreen.
Objectives can be Optional, which means they don’t lead to a mission ending at failure and aren’t needed to complete the mission, but they still shop up in the objectives panel.
To set and change the states of objectives, you have to link each objective with a Goal or SubGoal node. This node has the same states as objectives. You can set the starting state in the node. You have to use a (Sub)GoalResolutionAction to change the state throughout the mission.
Objectives can have steps that show up in the objectives panel:
3.3 Managing triggers
To prevent triggers from firing at unintended moments, you need to make sure triggers are only active when they are needed. Most triggers should start out deactivated and be activated with an ObjectActivationAction when the previous trigger in the mission’s flow has fired.
A trigger to warn the player of a low altitude has to be active at the appropriate time.
Triggers have a property called OneShot. If it is enabled, the trigger will deactivate itself after it has fired. But some triggers won’t fire in every playthrough, such as the llow altitude warning of the example above. If you aren’t sure the trigger will deactivate itself, you should deactivate it manually with an ObjectActivationAction when the trigger isn’t needed anymore.
3.4 Unconnected nodes
You can use the script editor to look for breaks in your mission logic. All nodes that aren’t referenced by another node are marked with a white dot:
This may be a sign of trouble. For actions this means they aren’t executed. For triggers this means they will either be active from the beginning or they will always be disabled. For some nodes such as the main mission object this isn’t an issue.
4. Testing the mission
To quickly test your mission, you can load a flight and then load your mission from a project, as described in Paragraph 4.1. However, this won’t work for all triggers (such as the intro TimerTrigger). To test your mission more reliably, you first have to build your project and then load the mission flight, as described in Paragraph 4.2.
4.1 Quickly load flight and mission
You can quickly start a flight without building your project:
- Start a flight in the right area or load your mission .FLT.
- Load the mission in the script editor.
- In the script editor, click
Game > Update.
4.2 Build project and load the mission
To test your mission more reliably, you first have to build your project and then load the mission flight:
- Build the project.
- Go to custom activities and select your mission.
4.3 How to edit the mission while it's loaded in
When the mission is loaded in, make sure
Options > World Objects is enabled.
Now you will see your areas overlayed in the world. With the script editor open you can see if the objects are loaded in the mission. If the names are white, they are loaded, but if they are red it means they are not loaded. While working on your mission, you can update the objects by clicking
Script Editor > Game > Update.
To add objects, click the plus in the overview window and select the object you want to add. If the object has a world position, it will spawn in the middle of your view. To change the location, you can move the object with the Gizmo. For gizmo options, in the script editor click
View > Gizmo.
With the Developer Camera enabled you can double click on the objects in the script editor and the camera will go to their location.
5. Debugging mission
You can’t really use the script editor to view the state of the mission during testing, so your options for debugging are limited. You can debug calculators by enabling DisplayAllowed and using
Options > Flight Object Debug.
6. Exporting the mission
To compile the mission for export, click
Clean All, then
Build All, Make sure there are no errors in the console from the building process. Then click
Build & Export, ensure the mission package is checkmarked, choose
Community Publishing, and select the Export Directory.
FSX Mission Building Tips by Paul Lange: