Difference between revisions of "Missions - Function Reference"

From FSDeveloper Wiki
Jump to: navigation, search
m (Reference)
m
 
(5 intermediate revisions by the same user not shown)
Line 1: Line 1:
 +
{{Infobox-Applicable-FSVersion
 +
| FSXI = false
 +
| FSXA = true
 +
| FSX = true
 +
| FS2004 = false
 +
| FS2002 = false
 +
| FS2000 = unknown
 +
| FS98 = unknown
 +
}}
 
{{:Transclusion-Missions-Oneline-Function Reference}}
 
{{:Transclusion-Missions-Oneline-Function Reference}}
 
{{:Transclusion-Missions-Overview-Function Reference}}
 
{{:Transclusion-Missions-Overview-Function Reference}}
Line 317: Line 326:
  
 
=== External ===
 
=== External ===
[http://www.fsdeveloper.com/forum/forumdisplay.php?f=59 FS Developer - Mission development] - Forum to ask & answer questions.
+
{{:Transclusion-Missions-Links-External-Common}}
  
[http://www.fsinsider.com/developers/Pages/MissionBuildingTips.aspx FS Insider - Mission Building Tips] - Lots of handy tips from MS/ACES.
+
* [http://www.yoururl.com Site page title] - Description
 
 
[http://fsxmission.com/live/index.php FSXMission.com] - Useful site for Missions information.
 
 
 
[http://www.yoururl.com Site page title] - Description
 
  
 
== Reference ==
 
== Reference ==
Line 331: Line 336:
 
{{Template:Navbox-Missions-ObjRef}}
 
{{Template:Navbox-Missions-ObjRef}}
  
[[category:FSX]]
 
 
[[category:Missions]]
 
[[category:Missions]]
 
[[Category:Mission Object Reference]]
 
[[Category:Mission Object Reference]]

Latest revision as of 10:05, 18 May 2008

Function Reference contains a reference of all the properties that apply to each of the Mission Objects.

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.

More blurb here.

This is an overview page. For expanded detail click the topic links below.


Contents

Actions

Actions are a declarative way to cause something to happen in the world. Examples of actions are playing a sound file, completing an objective, showing text in the adventure window, failing an engine, completing a goal, etc.

Generic Action Properties

Generic Action Properties are integral, and applicable, to all action types, (except where noted).

Activate Waypoints Action

Activate Waypoints Action provides one or more AI object with a new list of waypoints. Waypoints are essential for the movement of certain AI objects.

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

Adjust Payload Action is used to set, or add to, the weight on a payload station.

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

Attach Droppable Payload Action is used to change the payload that gets dropped when the user presses a key configured to drop the payload.

Attach Effect Action

Attach Effect Action attaches a single special effect (such as smoke, fire, contrail etc.) to one or more objects.

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

Change Object Type Action changes the object the user is in. For example, it can be used to change from one type of aircraft to another.

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

Count Action will add the value of the Count property to the Counter value in the given list of triggers (which should all be Counter triggers). Counter triggers will fire when a certain specified count is reached.

This adds a value to a #Counter Trigger. By setting a negative value for Count, you can subtract.

Custom Action

Custom Action is used to enable communications between a mission and a SimConnect client application.

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

Dialog Action is used to add speech to be rendered over the audio system, and/or text to be displayed on the screen.

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 :)

Disqualify Player Action

Disqualify Player Action is used to disqualify and remove usually one player from a race.

Failure Action

Failure Action is used to change the behavior of one of the aircraft's systems.

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

Goal Resolution Action is used to set whether goals have been completed or not.

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

Grant Reward Action rewards the user with a single reward, to be placed in their Pilot Records.

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

Object Activation Actions will change the state of most different types of object, Triggers, AI Objects, Scenery Objects and some Mission Objects. Do not use it for a Point Of Interest.

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

One Shot Sound Action renders a single wave file. Use this for sound effects rather than dialog (use the Dialog Action for speech audio).

Very simply, this plays a recorded sound when it is called.

Play Animation Action

Play Animation Action will initiate an animation sequence on one or more objects.

Play Flight Recording Action

Transclusion-Missions-Oneline-Play Flight Recording Action

Play List Action

Play List Action will play the specified music items on the adventure music track. Individual play list items can be set to a random position within the play list.

Point Of Interest Activation Action

Point Of Interest Activation Action will change the state of one or more Point Of Interest objects.

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

Random Action is used to initiate one randomly selected action from a list of possible actions.

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.

Race Course Start Action

Transclusion-Missions-Oneline-Race Course Start Action

Race Course Activate Action

Transclusion-Missions-Oneline-Race Course Activate Action

Refill Action

Transclusion-Missions-Oneline-Refill Action

ResetTimer Action

ResetTimer Action is used to set the current time of one or more timers back to their start times.

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

Rumble Action is used to initiate rumble in the Universal Controller (typically an XBox controller).

This provides force-feedback in a mission, but only works with XBox rumble-controllers, and not other force-feedback joysticks.

Spawn Action

Spawn Action will create all the new objects (including AI aircraft, scenery, actions and triggers) specified in a Spawn List object.

This activates a spawnlist, creating any objects it contains.

Time Penalty Action

Transclusion-Missions-Oneline-Time Penalty Action

Timer Adjust Action

Timer Adjust Action adds the DeltaTime property value to the timer trigger's internal clock.

Allows you to adjust the time remaining before a #Timer Trigger fires, by adding, or removing (negative numbers).


AI Objects

AI Objects are computer controlled vehicles, i.e. Aircraft, Boats, Ground Vehicles, or Other.

AircraftAI Object

AircraftAI Objects are referenced by AI Objects.

TakeoffAI Object

TakeoffAI Objects are referenced by AircraftAI Objects.

LandingAI Object

LandingAI Objects are referenced by AircraftAI Objects.

TaxiAI Object

TaxiAI Objects are referenced by AircraftAI Objects.

GroundVehicleAI Object

GroundVehicleAI Objects are referenced by AI Objects. Land or sea vehicles intended to follow a course of waypoints.

Waypoint List Object

Waypoint List Object contains a list of Waypoint Objects, and some other general properties for the motion of the AI object.

Waypoint Object

Waypoint Objects are referenced by Waypoint List Objects. A waypoint is a location in the world, with a set speed, that an AI object should aim for.



Area Definition Object

Area Definition Object only supports one type, RectangleArea, which defines a 3D box. The edges of the box will not appear when the mission is being played.

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

Group Object defines a single reference to one or more objects. This is helpful if a selection of objects are used a number of times. Group objects cannot refer to other group objects.



Mission Object

Mission Object There are several types of Mission Object. They have the same generic properties as Actions.

Camera

Camera will place a viewpoint in the world, which can be at a fixed location or attached to another (moving) object. The view from the camera will become the main view for the user.

Attached World Position

Attached World Position objects are referenced by Area Definition Objects, Camera, Picture In Picture View Controller, and Point Of Interest mission objects.

Attached World Object

Attached World Objects are referenced by Area Definition Objects, Camera, Picture In Picture View Controller, and Point Of Interest mission objects.

Picture In Picture View Controller

Picture In Picture View Controller object adds a small view window and is typically used for a "bomb-cam" - giving a view of or from a falling object.

Point Of Interest

Point Of Interest objects are used to highlight a location or other object. The highlight can be, for example, a vertical beam of light pointing at the object. Points of interest are displayed in the mission compass, and can be stepped through according to the cycle order.

Realism Overrides

Realism Overrides can be used to override the user's realism settings. For the specific properties: User Specified indicates that the user's settings should be used.

Ridge Lift

Ridge Lift object is used to simulate the effect of a hill slope on the wind.

Scenario Metadata

Scenario Metadata provides information that the mission system uses to place the mission appropriately in the list of missions presented to the user.

Thermal

Thermal object can be used to simulate atmospheric effects, including thermals and downdrafts. Refer also to the Weather Systems documentation.



Scenery Objects

Scenery Objects can be added to the world, to appear only when the mission is being undertaken.


Mobile Scenery Objects

Mobile Scenery Objects can be added to the world, to appear only when the mission is being undertaken.


Spawn List

Spawn List - A list of objects (AI aircraft, scenery objects, triggers, and actions) that should only appear in the mission when a certain stage in the mission has been reached.

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 initiate Actions. There are eleven different types of triggers, (3 only work in FSXA).

Generic Trigger Properties

Generic Trigger Properties are integral, and applicable, to all trigger types, (except where noted).

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

Airport Landing Trigger fires when the user's aircraft (not AI controlled aircraft) lands on a runway.

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

Area Landing Trigger fires when the user's aircraft (not AI controlled aircraft) lands on one in a specified list of areas.

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

Counter Trigger fires when it is counter reaches a specified limit. The counter is incremented by Count Actions.

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

Menu Prompt Trigger creates a menu of options for the user. For some missions this can be as simple as the option to continue, and the option to turn back.

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

Parking Trigger fires when the user has reached the parking spot assigned by the ATC at the airport specified.

Property Trigger

Property Triggers fire when one or more conditions are met. These conditions can be based on aircraft speed, altitude, failure of components, or a whole host of other simulation variables.

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

Proximity Trigger fires when the specified object, usually the users aircraft, enters a given box.

A simple but powerful test, this checks that the player or an AI has entered or left a defined area.

Timer Trigger

Timer Trigger fires when the given number of seconds has elapsed.

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

Goal Object - There is only one type of goal, and a mission can include one or more goals.

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

Reward Object one-liner about 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

Disabled Traffic Airport Object - A disabled airport will not be involved in any AI traffic, either as a starting point or a destination.

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

Mission Objects

Actions are a declarative way to cause something to happen in the world. Examples of actions are playing a sound file, completing an objective, showing text in the adventure window, failing an engine, completing a goal, etc.

AI Objects are computer controlled vehicles, i.e. Aircraft, Boats, Ground Vehicles, or Other.

Area Definition Object only supports one type, RectangleArea, which defines a 3D box. The edges of the box will not appear when the mission is being played.

Group Object defines a single reference to one or more objects. This is helpful if a selection of objects are used a number of times. Group objects cannot refer to other group objects.

Mission Object There are several types of Mission Object. They have the same generic properties as Actions.

Scenery Objects can be added to the world, to appear only when the mission is being undertaken.

Mobile Scenery Objects can be added to the world, to appear only when the mission is being undertaken.

Spawn List - A list of objects (AI aircraft, scenery objects, triggers, and actions) that should only appear in the mission when a certain stage in the mission has been reached.

Triggers initiate Actions. There are eleven different types of triggers, (3 only work in FSXA).

Goal Object - There is only one type of goal, and a mission can include one or more goals.

Reward Object one-liner about Reward Object.

Disabled Traffic Airport Object - A disabled airport will not be involved in any AI traffic, either as a starting point or a destination.

Link - Description

Link - Description

External

If you haven't found what you're looking for here, then we'd recommend, (in order of preference) -

  • AVSIM - Mission downloads (newest first).

Reference

'Reference' documents specifically related.

Link - Description