Missions - Function Reference
All of the objects that are available to use in a mission are described in the SDK documentation. Some notes, exceptions and gotchas are listed here.
Contents
- 1 Actions
- 1.1 Activate Waypoints Action
- 1.2 Adjust Payload Action
- 1.3 Attach Droppable Payload Action
- 1.4 Attach Effect Action
- 1.5 Change Object Type Action
- 1.6 Count Action
- 1.7 Custom Action
- 1.8 Dialog Action
- 1.9 Failure Action
- 1.10 Goal Resolution Action
- 1.11 Grant Reward Action
- 1.12 Object Activation Action
- 1.13 One Shot Sound Action
- 1.14 Play Animation Action
- 1.15 Play List Action
- 1.16 Point Of Interest Activation Action
- 1.17 Random Action
- 1.18 ResetTimer Action
- 1.19 Rumble Action
- 1.20 Spawn Action
- 1.21 Timer Adjust Action
- 2 AI Object
- 3 Area Definition Object
- 4 Group Object
- 5 Mission Objects
- 5.1 Camera Mission Object
- 5.2 Attached World Position Object
- 5.3 Attached World Object
- 5.4 Picture In Picture View Controller Mission Object
- 5.5 Point Of Interest Mission Object
- 5.6 Realism Overrides Mission Object
- 5.7 Ridge Lift Mission Object
- 5.8 Scenario Metadata Mission Object
- 5.9 Thermal Mission Object
- 6 Scenery Objects
- 7 Mobile Scenery Objects
- 8 Spawn List
- 9 Triggers
- 10 Goal Object
- 11 Reward Object
- 12 Disabled Traffic Airport Object
Actions
Actions will only get used when called from a Trigger.
In multiplayer mode, actions with the TargetPlayer property will affect the players specified by the property. If an action does not contain this property the action will affect only the local player, with the exception of Race Course Start Action and Race Course Activate Action which affect all players.
Activate Waypoints Action
Both AI objects and 'Living World' mobile scenery can have WaypointLists attached to them. If they do, then the model will move from one waypoint to the next. You can use this action to change the waypoints during the mission, to make these types of object react to the player's actions
Adjust Payload Action
This allows you to change the player's payload at a certain point in their aircraft. The payload station number can be found in the corresponding aircraft.cfg file for the player's aircraft, in the [WEIGHT_AND_BALANCE] section.
For example, try using a combination of #Random Actions, #Timer Triggers and AdjustPayloadActions to simulate the effect of the entire New Zealand rugby team starting a brawl in the back or your KingAir 350 just before landing.
The OPT never saves the ObjectReference field of an AdjustPayloadAction. While it's theoretically possible to add or remove payloads from AI, this means it's not really possible unless you hand-edit the XML.
Attach Droppable Payload Action
Placeholder text
Attach Effect Action
This attaches a visual effect, one of the ones provided in the Effects folder of FSX, to an AI or scenery object. However, it has some significant limitations.
Only models which have AttachPoints built in can be used with an effect. Very few do. Furthermore, if that attachpoint was created with a particular effect in mind, it can never be used with any other effect. Put simply, you can attach effects to the GEN_SceneryEffect model, which is invisible and so can be placed alongside any static visible model. It is highly unlikely that you can attach an effect to the any of the default AI models. In SP1 only (i.e. not RTM, SP2 or Acceleration) you can attach effects to the player.
Change Object Type Action
In a more complex mission you might want to make the player fly more than one kind of aircraft. Using this action, you can specify the new container title - found in the aircraft.cfg file - for the type of aircraft you want to change to.
Count Action
This adds a value to a #Counter Trigger. By setting a negative value for Count, you can subtract.
Custom Action
These are only useful when working with mission command extensions written using SimConnect. They pass the PayloadString value to the extension, which may be either an EXE or a DLL, so that it can perform some kind of action that the normal mission system doesn't support.
Dialog Action
The main way for you to interact with the mission player, this will display some text on screen and optionally play a sound file. This would typically be a recorded version of the text message.
These messages can be switched off in the simulator settings, so you can't assume that the sound file is enough. Alternatively, the player have the messages enabled but sound disabled, so you also can't assume that the text is enough. If they have both messages and sound disabled, that's their problem.
The sound file is relative to the "Sound" subfolder of the mission folder.
Do try to make your visible text and recorded speech match; mismatched subtitles get on my nerves :)
Failure Action
Some missions will simulate a system failure and expect the player to deal with it appropriately. Using this action you can make one of the player's aircraft's systems fail (by setting HealthPercent to 0), degrade (HealthPercent < 100) or restore full function (HealthPercent = 100).
Goal Resolution Action
These set the state of a #Goal Object to be one of Pending, Complete or Failed. Only goals which are activated count towards the final result of the mission though, so you can change the list of goals during the mission. When no active goals are pending, the mission finishes.
Grant Reward Action
In addition to having the mission finish successfully, you may want to issue a Reward to the player for doing something well, or for finding hidden content. Using this action along with a Reward you can add a reward to the player's flight record.
Object Activation Action
Some types of objects, typically Triggers and Scenery, can be activated and deactivated. This is important for the flow of your mission; you should only have the appropriate triggers activated to prevent the player from taking shortcuts. Using this action you can activate and deactivate other objects.
One Shot Sound Action
Very simply, this plays a recorded sound when it is called.
Play Animation Action
Placeholder text
Play List Action
Placeholder text
Point Of Interest Activation Action
The mission compass is an easy way of showing the player where they are supposed to be next. When you want to add a new Point of Interest to the compass and select it as the current one, use this action.
Random Action
This is almost two actions in one. You can set the percentage of the time that you want this action to do anything at all (ProbabilityPercent). Additionally, only one of the items in the Actions list is fired, again at random.
This can be very useful for creating 'chatter' for making transit sections of your mission a little more interesting. You can have a non-OneShot #Timer Trigger, set maybe to 45 seconds, calling a RandomAction with ProbabilityPercent of 33 and half a dozen #Dialog Actions attached.
ResetTimer Action
Mainly useful with repeating timers. If you want to check that the player has done something within a certain time, the #Timer Trigger is fine. However, if you want to use the same TimerTrigger again, the StartTime needs to be reset to 0. You can't use the #Timer Adjust Action because it has no 'set' option.
Rumble Action
This provides force-feedback in a mission, but only works with XBox rumble-controllers, and not other force-feedback joysticks.
Spawn Action
This activates a spawnlist, creating any objects it contains.
Timer Adjust Action
Allows you to add or remove (by using negative numbers) the time remaining before a #Timer Trigger fires.
AI Object
Placeholder text
AircraftAI Object
Placeholder text
TakeoffAI Object
Placeholder text
LandingAI Object
Placeholder text
TaxiAI Object
Placeholder text
GroundVehicleAI Object
Placeholder text
Waypoint List Object
Placeholder text
Waypoint Object
Placeholder text
Area Definition Object
On some systems, small AreaDefinitions can be missed by the mission system. Normally this only affects slower PCs and faster-moving aircraft. Try to make the smallest dimensions of an AreaDefinition at least 20 meters to avoid problems on slower PCs.
Group Object
Placeholder text
Mission Objects
Placeholder text
Camera Mission Object
Placeholder text
Attached World Position Object
Placeholder text
Attached World Object
Placeholder text
Picture In Picture View Controller Mission Object
Placeholder text
Point Of Interest Mission Object
Placeholder text
Realism Overrides Mission Object
Placeholder text
Ridge Lift Mission Object
Placeholder text
Scenario Metadata Mission Object
Placeholder text
Thermal Mission Object
Placeholder text
Scenery Objects
Placeholder text
Mobile Scenery Objects
Placeholder text
Spawn List
This creates new nodes during a mission. You can use it to create visual models in addition to mission actions and triggers. In FSX Acceleration, commands created by a spawnlist can refer to any other object in the mission but in all other versions, including SP2, commands created by a spawnlist must only refer to other objects in the same spawnlist.
Triggers
Triggers are used to check for event occurence during a mission. You might check that the player is above a certain altitude, or has landed at a key airport, or that a certain amount of time has elapsed.
When a trigger is active, it will fire whenever the appropriate conditions are met.
When a trigger is deactivated it is not evaluating its conditions to decide whether it should fire its actions.
In multiplayer mode, triggers with the IsGlobal property set to True will affect all other players.
If a trigger does not contain this property, or the property is set to False, the trigger will affect only the local player.
Generic Trigger Properties
All triggers can be marked as Active or Inactive using the Activated field. An inactive trigger does nothing. The usual way to make your mission storyline is to use the #Object Activation Action to enable new triggers once the player has achieved a key task.
Triggers can also be marked as OneShot, which defaults to true. This means that the trigger fires once, and once only. Normally this is what you want to happen, but there are some exceptions.
ProximityTriggers have two Action lists; OnEnterActions and OnExitActions. If it is a OneShot trigger, only one set of actions will ever be used because after the first set has fired, the trigger will be deactivated. If you want both sets of actions to be used, you have to mark the triggers as not being OneShot (that is, untick the box).
Another common use for a non-OneShot trigger is a recurring timer, where you want something to happen, say, every two minutes.
If you want to re-use a trigger after it has been fired, but still want it to disable itself after every time, you can use the #Object Activation Action to re-enable it.
Airport Landing Trigger
Checks that the player, or an AI, has landed or touched down at a specific airport. The associated RunwayFilter object doesn't seem to care which end of the named runway you touch down on; that is, runways 4 and 22 are seen to be the same.
Area Landing Trigger
Checks to see that the player, or an AI, has landed or touched down anywhere. This seems to have a lower priority than the #Airport Landing Trigger, so it's common to use this to detect off-airport landings by simply not attaching any AreaRectangle.
Counter Trigger
Simply counts up from 0 to whatever level you tell it to. Use this for things like failing the mission if the player ignores five warnings that they must do something.
Menu Prompt Trigger
This asks the player to make a choice. It's usually used to give multiple ways of completing a mission by using the different menu items to call #Object Activation Actions which activate different sets of triggers and goals.
Parking Trigger
Placeholder text
Property Trigger
One of the more useful triggers, this can check a set of predefined properties of the player or an AI for being higher, lower or equal to a constant value or another property. Properties can also be combined using And/Or/Not, but you need to hand-edit the mission XML to use these groupings.
Proximity Trigger
A simple but powerful test, this checks that the player or an AI has entered or left a defined area.
Timer Trigger
It's main purpose is to simply wait for a set time and then call an action. However, it can be used for two other things. By setting OnScreenTimer to True, you get a visible timer in the sim. This can be count-up or count-down, depending on the values of StartTime and StopTime.
Since this gives visual feedback that the mission system is working, this means it is also a very useful test. If you think that an error is preventing your mission from being loaded at all, create an active, on-screen TimerTrigger. If you get a visible timer, the mission is being run.
Goal Object
Each mission must have at least one Goal. When all active Goals are complete or failed, the mission ends. You can change which goals have to be achieved during the mission by using the #Object Activation Action to switch them on or off.
Reward Object
Rewards are used in addition to Goals. The player doesn't need to get all the rewards to finish the mission; in fact, they may not even know that rewards are available. They're just a way of saying "Hey, well done!".
Rewards are created in a separate file to the mission, and must be compiled before they can be used.
Disabled Traffic Airport Object
This tells the simulator that it should not create any AI traffic at a specific list of airports. You don't want an unplanned 747 bearing down on you when you're in the last few minutes of a two hour long mission, nursing a crippled Cessna back to earth at Heathrow. It can also affect some triggers which may be set up to fire for any aircraft.
Related
Internal
Actions will only get used when called from a Trigger.
In multiplayer mode, actions with the TargetPlayer property will affect the players specified by the property. If an action does not contain this property the action will affect only the local player, with the exception of Race Course Start Action and Race Course Activate Action which affect all players.
AI Objects overview, a multi-line explanation of the topic.
More blurb here.
Area Definition Object overview, a multi-line explanation of the topic.
More blurb here.
Group Object overview, a multi-line explanation of the topic.
More blurb here.
Mission Objects overview, a multi-line explanation of the topic.
Scenario Metadata is the only essential mission action, and must exist in all missions.
Scenery Objects overview, a multi-line explanation of the topic.
More blurb here.
Mobile Scenery Objects overview, a multi-line explanation of the topic.
More blurb here.
Spawn List overview, a multi-line explanation of the topic.
More blurb here.
Triggers are used to check for event occurence during a mission. You might check that the player is above a certain altitude, or has landed at a key airport, or that a certain amount of time has elapsed.
When a trigger is active, it will fire whenever the appropriate conditions are met.
When a trigger is deactivated it is not evaluating its conditions to decide whether it should fire its actions.
In multiplayer mode, triggers with the IsGlobal property set to True will affect all other players.
If a trigger does not contain this property, or the property is set to False, the trigger will affect only the local player.
Goal Object overview, a multi-line explanation of the topic.
More blurb here.
Reward Object overview, a multi-line explanation of the topic.
More blurb here.
Disabled Traffic Airport Object overview, a multi-line explanation of the topic.
More blurb here.
Link - Description
Link - Description
External
FS Developer - Mission development - Forum to ask & answer questions.
FS Insider - Mission Building Tips - Lots of handy tips from MS/ACES.
FSXMission.com - Useful site for Missions information.
Site page title - Description
Reference
'Reference' documents specifically related.
Function Reference - With example code.
Link - Description
Link - Description
