Navigation Services XML Properties

NAVIGATION SERVICES XML PROPERTIES

The <service_name>.xml file is used to define the states, behaviours and tasks that will make up the service being defined. In general, you will have one file per service. For example if you have an aircraft that has a skydiving activity then you may have two different navigation service files:

one file for passengers boarding the aircraft, moving along the aisle, then sitting down
another file for another file for passengers getting up, moving to the the side-door, and then jumping out

This file is formatted using XML and can be edited by using any text editor. The general format for the file is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<SimBase.Document Type="MissionFile" version="1.0" id="ID_NAME">
<!-- CREATE NAVIGATION SERVICE (FSM) STATES -->
    <CabinService.ServiceStateList>
    <!-- List of different states in the FSM -->
        <ServiceState Name="NS_INIT">
        <!-- Tasks in the state -->
            <Task TaskName="TN_FIRST" ParamBehaviourName="behaviour_1"/>
        </ServiceState>
        <ServiceState Name="NS_START">
            <Task TaskName="TN_SECOND" ParamBehaviourName="behaviour_2"/>
        </ServiceState>
        <!-- Further states in the FSM here-->
    </CabinService.ServiceStateList>
<!-- CREATE BEHAVIOURS -->
    <CabinService.BehaviourList>
    <!-- Create named behaviours -->
        <Behaviour Name="NAME">
            <BehaviourStateList>
            <!-- List of behaviour states for the behaviour -->
                <BehaviourState Name="BS_INIT">
                <!-- Task list for the behaviour -->
                    <AvailableTaskList>
                        <AvailableTask TaskName="TN_FIRST">
                            <Sequence StateChange="BS_BEHAVIOUR"/>
                        </AvailableTask>                    
                    </AvailableTaskList>
                </BehaviourState>
                <!-- Further behaviour states here -->
            </BehaviourStateList>
        </Behaviour>
        <!-- Further behaviours here -->
    </CabinService.BehaviourList>
</SimBase.Document>

When creating these files we recommend that you follow an established naming convention that is used by the files included in the default packages for Microsoft Flight Simulator 2024. This convention requires that the different named elements in the file are prefixed as follows:

NS_ → Navigation State
BS_ → Behaviour State
TN_ → Task Name

For example:

<CabinService.ServiceStateList>
    <ServiceState Name="NS_START">
        <Task TaskName="TN_GOTO_SIT" ParamBehaviourName="Skydiver"/>
        <Task TaskName="TN_GOTO_DOOR" ParamBehaviourName="JumpMaster"/>
    </ServiceState>
</CabinService.ServiceStateList>
<CabinService.BehaviourList>
    <Behaviour Name="JumpMaster">
        <BehaviourStateList>
            <BehaviourState Name="BS_INIT">
                <AvailableTaskList>
                    <AvailableTask TaskName="TN_GOTO_DOOR">
                    <Sequence StateChange="BS_GOTO_DOOR"/>
                </AvailableTask>                    
            </AvailableTaskList>
        </BehaviourState>
    </Behaviour>
</CabinService.BehaviourList>

As a continuation to this naming convention, we strongly suggest that each file also has a NS_INIT state for the navigation service and a BS_INIT state for the behaviours. These would be the state and behaviour that are first in the FSM when the navigation service file is first initialised.

<SimBase.Document>

This is the main parent element that is used to contain the navigation service data. This element should have the following sub-elements:

This element has the following attributes:

Attribute	Description	Type	Required
`type`	The type of SimBase file. Should always be "MissionFile".	String	Yes
`version`	The file version.	Float	No
`id`	The unique ID for the navigation service. This can be a GUID enclosed in `{}`, or a name string (alpha-numeric characters and under-scores "_", only). You can find more information on GUID's here: GUIDs	String	Yes

<CabinService.ServiceStateList>

This is is a container element that is used to list the different states within the navigation service FSM. It has no attributes and requires one or more of the following sub-element:

<ServiceState>

The following shows a complete example of a navigation service state list definition in an XML file:

<CabinService.ServiceStateList>
    <ServiceState Name="NS_INIT">
        <Task TaskName="TN_GO_TO_PARKING" ParamBehaviourName="BoardingRamp"/>
    </ServiceState>
    <ServiceState Name="NS_GO_TO_PLANE">
        <Task TaskName="TN_GO_TO_PLANE" ParamBehaviourName="BoardingRamp" Count="0"/>
        <Task TaskName="TN_ATTACH_TO_PLANE" ParamBehaviourName="BoardingRamp"/>
    </ServiceState>
    <ServiceState Name="NS_ATTACHED">
        <Task TaskName="TN_WAIT_BOARDING_END" ParamBehaviourName="BoardingRamp"/>
    </ServiceState>
    <ServiceState Name="NS_DETACH">
        <Task TaskName="TN_DETACH_FROM_AIRCRAFT" ParamBehaviourName="BoardingRamp"/>
    </ServiceState>
</CabinService.ServiceStateList>

<ServiceState>

This element is a sub-element of <CabinService.ServiceStateList> and is used to define a single state within the navigation service FSM. It must contain at least one of the following sub-element (but may contain more):

<Task/>

Note that by default the first <ServiceState> defined will be the "start" state of the navigation service FSM, used when the object is first initialised. See the <CabinService.ServiceStateList> section for an example of use.

This element has the following attributes:

Attribute	Description	Type	Required
`name`	The name of the state. If this is the first state in the FSM, then it should be named `NS_INIT`, otherwise use `NS_<name>`.	String	Yes
`StateChange`	This is the name of a `<ServiceState>` to move to at the end of the service state being defined currently. Note that this will only change the state for the navigation Service FSM, which may conflict with the `<AvailableTask>` of the associated behaviour, which is something to be aware of.	String	No

<Task/>

This is a self-closing sub-element of <ServiceState> which is used to define a task to be performed when the navigation service FSM reaches the state that holds the task(s). You may have multiple <Task/> elements per state. See the <CabinService.ServiceStateList> section for an example of use.

The element has the following attributes:

Attribute	Description	Type	Required
`TaskName`	The name of the task. You should use the use `TN_<name>` naming convention for this attribute.	String	Yes
`ParamBehaviourName`	This is the `name` attribute of the `<Behaviour>` that is to be used to perform the task.	String	Yes
`Count`	This defines the number of actors performing the task. Note that, by default, a navigation state requires all actors to do a given task before it is considered "validated" (completed). When a task is not validated, it can block the change to a new service state. This may be avoided by either using 0 for the count, or by "forcing" the state change using the `<ForceCabinServiceState>` element in the mission definition.	Integer	No

<CabinService.BehaviourList>

This is is a container element that is used to list the different behaviours that can be used within the tasks defined in the various navigation service FSM states. It has no attributes and requires one or more of the following sub-element:

<Behaviour>

The following shows a simple example of a behaviour state definition in an XML file:

<CabinService.BehaviourList>
    <Behaviour Name="Passenger">
        <BehaviourStateList>
            <BehaviourState Name="BS_INIT">                    
                <AvailableTaskList>
                    <AvailableTask TaskName="TN_GO_TO_SIT">
                        <Sequence StateChange="BS_GOTO_SIT"/>
                    </AvailableTask>                        
                </AvailableTaskList>
            </BehaviourState>
            <BehaviourState Name="BS_GOTO_SIT">
                <LinkedCabinStateList>
                    <LinkedCabinState>NS_SIT</LinkedCabinState>
                </LinkedCabinStateList>
                <OnSkipFrame>
                    <Sequence>
                    </Sequence>
                </OnSkipFrame>
                <OnFirstFrame>
                    <Sequence>
                        <AttachToAircraft/>
                        <TeleportToGraphNode NodeTag="SIT"/>
                        <PlayAnimation Name="Idle_Sit_01" Layer="Base" Force="TRUE"/>
                        <NotifyTaskComplete TaskName="TN_GO_TO_SIT"/>
                    </Sequence>
                </OnFirstFrame>
            </BehaviourState>
        </BehaviourStateList>
    </Behaviour>
</CabinService.BehaviourList>

<Behaviour>

This element is a sub-element of <CabinService.BehaviourList> and is used to define a group of behaviours that will be used by actors. It must contain one of the following sub-element:

<BehaviourStateList>

See the <CabinService.BehaviourList> section for an example of use. This element has the following attributes:

Attribute	Description	Type	Required
`name`	The name of the behaviour.	String	Yes

<BehaviourStateList>

This is is a child of the <Behaviour> element and acts as a container element for one or more of the following element:

<BehaviourState>

Within this element you can define all the different states for the actor behaviour FSM. See the <CabinService.BehaviourList> section for an example of use.

<BehaviourState>

This is a sub-element of the <BehaviourStateList> and is used to define a single actor behaviour. This element has the following sub-elements:

This element has the following attribute:

Attribute	Description	Type	Required
`name`	The name of the behaviour state. You should use the use `BS_<name>` naming convention for this attribute.	String	Yes

Below is a simple example of this element being used:

<BehaviourState Name="BS_RESET">    
    <LinkedCabinStateList>
        <LinkedCabinState>NS_RESET</LinkedCabinState>
    </LinkedCabinStateList>                
    <OnFirstFrame>
        <Sequence StateChange="BS_GOTO_DOOR">
            <PlayAnimation Name="Idle_Stand_01" Layer="Base" Force="True"/>
            <AttachToAircraft/>
            <NotifyTaskComplete TaskName="TN_RESET"/>
        </Sequence>
    </OnFirstFrame>
</BehaviourState>

<LinkedCabinStateList>

This is a sub-element of <BehaviourState> and has no attributes. It is a container element for one or more of the following element:

<LinkedCabinState>

<LinkedCabinState>

This is a sub-element of <LinkedCabinStateList> and has no attributes. For this element you are expected to supply a navigation Service state name (as defined in <ServiceState>). This state will be used when a navigation State change has been forced.

<LinkedCabinStateList>
    <LinkedCabinState>NS_RESET</LinkedCabinState>
</LinkedCabinStateList>

The normal behaviour when a state change happens is that a new group of tasks will become available, as defined in the <CabinService.ServiceStateList>. When a behaviour has finished the current tasks, it will then look into this list of possible next tasks, and if one of these tasks is available, it will be performed and (usually) launch a state change to get to a new behaviour state for the task. However, when you force the navigation state change, you will want to bypass these available tasks, as they will not be relevant for the forced state, which is when the <LinkedCabinStateList> element is comes in. When a state change is forced, all behaviours will switch to the behaviour flagged as the first one for the new navigation state after a skip using this element.

<OnFirstFrame>

This child element of <BehaviourState> is a container element for a <Sequence>, where the sequence defines what should happen on the very first frame of the behaviour after the behaviour state has been changed to the one containing the <OnFirstFrame> element. The element has no attributes, and below you can see an example of how it would look in the XML:

<OnFirstFrame>
    <Sequence>
        <AttachToAircraft/>
        <TeleportToGraphNode NodeTag="SIT"/>
        <PlayAnimation Name="Idle_Sit_01" Layer="Base" Force="TRUE"/>
        <NotifyTaskComplete TaskName="TN_GO_TO_SIT"/>
    </Sequence>
</OnFirstFrame>

<OnLastFrame>

This child element of <BehaviourState> is a container element for a <Sequence>, where the sequence defines what should happen on the very last frame of the behaviour before the behaviour state changes to the next one. The element has no attributes, and below you can see an example of how it would look in the XML:

<OnLastFrame>
    <Sequence>
        <DetachFromAircraft />
        <NotifyTaskComplete TaskName="TN_GO_TO_PARKING"/>
    </Sequence>
</OnLastFrame>

<OnSkipFrame>

This child element of <BehaviourState> is a container element for a <Sequence>, where the sequence defines what should happen before the very first frame of the behaviour state (so before the <OnFirstFrame> element is triggered) just after a behaviour state has been skipped to the one containing the <OnSkipFrame> element.

NOTE: the <OnFirstFrame> element will still be triggered, just that it will be triggered after the <OnSkipFrame> element.

The element has no attributes, and below you can see an example of how it would look in the XML:

<OnSkipFrame>
    <Sequence>
        <AttachToAircraft/>
        <TeleportToGraphNode NodeTag="PUMP"/>
    </Sequence>
</OnSkipFrame>

<AvailableTaskList>

This is a sub-element of <BehaviourState> and has no attributes. It is a container element for one or more of the following element:

<AvailableTask>

<AvailableTask>

This element is a sub-element of <AvailableTaskList> and is used to define a task that is available as part of the behaviour state. The task being defined is named using the attribute listed below, and the sequence of events that will comprise the task itself are defined using the following sub-element:

<Sequence>

This element has the following attributes:

Attribute	Description	Type	Required
`TaskName`	The task name for the navigation service behaviour. You should use the use `TN_<name>` naming convention for this attribute.	String	Yes

Example of how it would look in the XML:

<AvailableTaskList>
    <AvailableTask TaskName="TN_JUMP">
        <Sequence StateChange="BS_JUMP">
        </Sequence>                            
    </AvailableTask>
    <AvailableTask TaskName="TN_RESET">
        <Sequence StateChange="BS_RESET">
        </Sequence>
    </AvailableTask>
</AvailableTaskList>

<Sequence>

This is a container sub-element which defines a sequence of events that should be followed when the sequence is called. The timing of the sequence will depend on the parent element where the sequence has been placed, which can be one of the following:

The element itself can contain any of the following sub-elements:

The <Sequence> element may also have the following attributes:

Attribute Description Type Required

StateChange This attribute can be used to force a behaviour state state change. The supplied string should be the name of a <BehaviourState> element. String No

Probability This attribute can be used to provide a probability that the sequence will be chosen. Value should be a Percent Over 100, and the sum of all supplied sequence probabilities for the task should be 1.0. Float No

Attribute	Description	Type	Required
`StateChange`	This attribute can be used to force a behaviour state state change. The supplied string should be the name of a `<BehaviourState>` element.	String	No
`Probability`	This attribute can be used to provide a probability that the sequence will be chosen. Value should be a Percent Over 100, and the sum of all supplied sequence probabilities for the task should be 1.0.	Float	No
`DisplayModelEntry`	This attribute can be used to change the model that is being displayed. Fore example, this can be used to switch models if you have a service worker with a headset when inside the aircraft but want to have them without the headset when outside the aircraft. If this attribute is omitted then the default model will be used.	String: "Interior" "Exterior"	No

DisplayModelEntry

This attribute can be used to change the model that is being displayed. Fore example, this can be used to switch models if you have a service worker with a headset when inside the aircraft but want to have them without the headset when outside the aircraft. If this attribute is omitted then the default model will be used.

String:

"Interior"
"Exterior"

<AttachToAircraft />

This is a self-closing element used in a <Sequence>. It has no attributes and simply tells the simulation that the object behaviour has been attached to the aircraft. Attached objects will have two effects:

Should the aircraft move, the attached object will move along with it.
The weight of the object will be added to the weight of the aircraft and affect its physics, such that if a heavy object (for example cargo) is placed in the left side of the aircraft, the aircraft will "sag" to the left.

Weight is based on the values set in the sim.cfg file for the Simple Object or the Procedural Character associated with the behaviour.

<DetachFromAircraft />

This is a self-closing element used in a <Sequence>. It has no attributes and simply tells the simulation that the object behaviour has been detached from the aircraft. Detaching an object will mean that the weight of the object will no longer be considered by the aircraft physics, and it's weight will be removed from the total aircraft weight. Weight is based on the values set in the sim.cfg file for the Simple Object or the Procedural Character associated with the behaviour.

<TaxiAIMoveToDestination />

This is a self-closing element used in a <Sequence>. It has no attributes and simply tells the simulation that the behaviour object should move along the taxiway to the stored destination using the Taxiway AI as part of the sequence. Note that this will require that the Apron Services XML has been correctly set up and the object has been linked to Apron Control.

<InteractWithNode>

This element used in a <Sequence> and allows the behaviour object to interact with the current graph node. Using this element will generate a check to see if an interaction with the name InteractionName is available, and if it exists it will call the associated XML. For more information, please see here:

Service Interaction XML Properties

This element has the following attributes:

Attribute Description Type Required

InteractionName The interaction to perform on the current graph node, as defined in the Interaction XML. String Yes

Attribute	Description	Type	Required
`InteractionName`	The interaction to perform on the current graph node, as defined in the Interaction XML.	String	Yes
`Remotely`	By default the behaviour object should be on the graph node to perform the interaction, but you can perform the interaction remotely by setting this attribute to "TRUE". Default is "FALSE".	Boolean	No

Remotely

By default the behaviour object should be on the graph node to perform the interaction, but you can perform the interaction remotely by setting this attribute to "TRUE".

Default is "FALSE".

Boolean

<MoveToGraphNode>

This element used in a <Sequence> and is used to tell the behaviour object to move to a selected graph node. The exact node that the behaviour object moves to will depend on the combination of InteractionName, NodeTag and NodeOrder attributes.

This element has the following attributes:

Attribute	Description	Type	Required
`InteractionName`	The interaction used to select the graph node to move to, as defined in the Interaction XML. The interaction XML may contain multiple nodes, so the node that is chosen will depend on the `NodeOrder` attribute. Default is "".	String	No
`NodeTag`	The interactive node tag to move to, as defined in the Interaction XML. Multiple nodes may share a tag, so the node that is chosen will depend on the `NodeOrder` attribute. Default is "".	String	No
`MoveStraight`	Sets whether to move straight to the given node ("TRUE") or whether to follow the defined path ("FALSE"). Default is "FALSE".	Boolean	No
`NodeOrder`	This attribute defines the way that nodes will be parsed to find the node that the behaviour object should move to. The nodes that will be used are defined using the `InteractionName` and/or the `NodeTag` attributes. Default is "Random".	Enum: "Random" - Choose a random node to move to "Ascending" - Choose the next node in ascending order by ID "Descending" - Choose the next node in descending order by ID "Distance" - Choose the nearest node based on distance to the behaviour object.	No
`Ratio`	This value is used to modify the maximum speed (as defined in the sim.CFG file) at which the behaviour object will move. For example, if the speed is set to 2m per second, and you set the ratio tio 0.5, the maximum speed of the object will be 1m per second. Default is 1.0.	Float	No
`TeleportOnSkip`	When this is set to "TRUE" the behaviour object will "teleport" to the selected node if the sequence is cancelled by a skip. If set to "FALSE", then it will continuing to move along the path, regardless of the skip. Default is "FALSE".	Boolean	No
`WaitAvailableToMove`	When this is set to "TRUE" the behaviour object will wait to move to a node if no free node is available. If set to "FALSE", the move action will simply be cancelled. Default value is "FALSE".	Boolean	No

<TeleportToGraphNode>

This element used in a <Sequence> and is used to tell the behaviour object to teleport directly to a selected graph node. The exact node that the behaviour object teleports to will depend on the combination of InteractionName, NodeTag and NodeOrder attributes.

This element has the following attributes:

Attribute	Description	Type	Required
`InteractionName`	The interaction used to select the graph node to move to, as defined in the Interaction XML. The interaction XML may contain multiple nodes, so the node that is chosen will depend on the `NodeOrder` attribute. Default is "".	String	No
`NodeTag`	The interactive node tag to move to, as defined in the Interaction XML. Multiple nodes may share a tag, so the node that is chosen will depend on the `NodeOrder` attribute. Default is "".	String	Yes
`NodeOrder`	This attribute defines the way that nodes will be parsed to find the node that the behaviour object should move to. The nodes that will be used are defined using the `InteractionName` and/or the `NodeTag` attributes. Default is "Random".	Enum: "Random" - Choose a random node to teleport to "Ascending" - Choose the next node in ascending order by ID "Descending" - Choose the next node in descending order by ID "Distance" - Choose the nearest node based on distance to the behaviour object.	No
`TeleportWhenNodeAvailable`	When this is set to "TRUE" the behaviour object will wait if no node is currently available, and then teleport to the node the instance one becomes available. If set to "FALSE", the behaviour object will simply do nothing. Default is "TRUE".	Boolean	No

<NotifyTaskComplete>

This element required by a <Sequence> and is used to tell the <ServiceState> FSM that the given task has been completed.

This element has the following attribute:

Attribute	Description	Type	Required
`TaskName`	The name of the task to set as being completed.	String	Yes

<PlayAnimation>

This element used in a <Sequence> and is used to tell the behaviour object to play its animation. The sequence will then wait until the animation has been completed before continuing on to the next action in the sequence. This element has the following attributes:

Attribute Description Type Required

Attribute	Description	Type	Required
`Name`	The name of the animation to use.	String	Yes
`Layer`	The name of the layer that the animation is on. If this could be any layer, then you should use "Base". Default is "Base".	String	No
`Force`	If set to "TRUE", the animation will play even if a transition exists to another state. If "FALSE" then it will not. Default is "FALSE".	Boolean	No

Name

The name of the animation to use.

String

Yes

Layer

The name of the layer that the animation is on. If this could be any layer, then you should use "Base".

Default is "Base".

String

Force

If set to "TRUE", the animation will play even if a transition exists to another state. If "FALSE" then it will not.

Default is "FALSE".

Boolean

<SetAlpha>

This element used in a <Sequence> and is used to set the transparency of the behaviour object. This element has the following attribute:

Attribute	Description	Type	Required
`Ratio`	The alpha value to use for the behaviour object, expressed as a Percent Over 100.	String	Yes

<CabinService.RegisterInteractorsToCabinServiceAction>

This is a sub-element of <WorldBase.Flight> and is not usually included as part of the navigation service XML, but instead as part of the mission XML file. It is used to register an interactive object with the navigation service controller and flag it as interactive for a specific navigation service. This element requires the following sub-elements:

This element has the following parameters:

Attribute	Description	Type	Required
`id`	The unique identifier of the object element reference.	String	Yes
`InstanceId`	The unique ID for the reference state action, as a GUID enclosed in {}. You can find more information on GUID's here: GUIDs	String	Yes

Example of how it would look in the XML:

<CabinService.RegisterInteractorsToCabinServiceAction id="RegisterGenerator" InstanceId="{C6A43E09-29B4-49EB-B163-E419D5DB545D}">
    <Descr>Register Generator as interactive to loadworker service</Descr>
    <ObjectReference id="ApronContextReference:ApronControl" InstanceId="{0B6CFBA9-4A13-44E5-BB2A-A4175277E4E0}"/>
    <CabinName>LoadWorkerService</CabinName>
    <Interactor>
        <ObjectReference id="ApronContextReference:PowerGenerator" InstanceId="{C53FE0CC-BD97-4235-9C37-136BEF7BAA90}"/>
        <NodeTag>POWER_GENERATOR_ACCESS</NodeTag>
    </Interactor>
</CabinService.RegisterInteractorsToCabinServiceAction>

<CabinName>

This sub-element of <CabinService.RegisterInteractorsToCabinServiceAction> has no attributes and is used to define the navigation service to link the interaction with.

<Interactor>

This sub-element of <CabinService.RegisterInteractorsToCabinServiceAction> has no attributes and is used to define the interactive object to assign as the interactor in the navigation service. It requires the following sub-elements:

<ObjectReference />
<NodeTag>

<NodeTag>

This element is used to supply the tag associated with one or more nodes that should be considered by the calling navigation service or calculator. It is used in the following elements: