SERVICE AND IDLEWORKER SCRIPT DEFINITIONS
You can also refer to some airport service and idle worker behaviors from mission XML files (for example the <IdleWorker />
element in the Services.xml
). These files are formatted as follows:
<?xml version="1.0" encoding="utf-8"?>
<SimBase.Document Type="MissionFile" version="1,0" id="fuel/worker">
<Title>My Mission Title</Title>
<Filename>MyServiceFile.xml</Filename>
<WorldBase.Flight>
<!-- MISSION DATA HERE (if applicable) -->
<!-- SERVICE/WORKER DATA HERE -->
</WorldBase.Flight>
</SimBase.Document>
Note that the id
attribute for <SimBase.Document>
can be either "fuel
" or "worker
", where "fuel
" refers to any service vehicle or object (not just fuel trucks) and "worker
" refers to any idle worker type (the attribute is optional and may not always be included, especially if the file is for a full mission).
Within the <WorldBase.Flight>
element you can have the following sub-elements, which are explained in detail below: <Service.GroundService>
, <SimMission.SendMessageToAIAction>
and <SimContain.Container>
.
<Service.GroundService>
This element is specific to Services, and permits you to list all the states - with associated Actions - and trigger the Actions when the service enters the corresponding state. It has not attributes and can contain a <Name>
element and a <States>
element.
<Name>
This element is used to give a common name to the ground service being defined. The name is placed between <Name>
opening and closing tags as plain text without quotes, and the element has no attributes.
<States>
This is a container element for a list of different <State>
sub-elements. The element has no atributes and you can only have one <States>
element within the <Service.GroundService>
element.
<State>
A single state for a service object, with its list of actions defined within the <ObjectReferenceList>
element. You can have multiple <State>
definitions within a single <States>
element, and they can have the following attributes:
Attribute | Description | Type | Required |
---|---|---|---|
name |
The name of the state. |
Enum: Sleep |
Yes |
UniqueRefId |
Reference to the GUID of the corresponding service object (the InstanceId attribute of the corresponding <SimContain.Container> ) |
String |
Yes |
Below is a table that shows the above listed state names and a description of what they do, along with what services they are associated with:
State Name | Description | Available AIType |
---|---|---|
Sleep |
State "at rest", ie: when the vehicle has finished its task and turns off its engine. Can also be triggered if some error occured, and the vehicle just stops its normal behavior. | BaggageLoader, BaggageCart, BoardingRamp, CateringTruck, GroundPowerUnit, Pushback, SmallPushback, FuelTruck |
Move_Toward_Aircraft |
The vehicle has been requested and starts moving towards the aircraft. Note that the FuelTruck will start taxiing accross the airport towards an aircraft and it can perform multiple requests in a row. | BaggageLoader, BaggageCart, BoardingRamp, CateringTruck, GroundPowerUnit, Pushback, SmallPushback, FuelTruck |
Before_Reaching_Aircraft |
Shortly before reaching the aircraft, the vehicle has some action to perform (BaggageLoader inclines its ramp, BoardingRamp extends its stairs, CateringTruck elevates its container). For FuelTruck, this is used to move from the parking edge to the aircraft. | BaggageLoader, BoardingRamp, CateringTruck, FuelTruck |
Reached_Aircraft |
Final state upon reaching aircraft (BaggageLoader and BoardingRamp finish moving, CateringTruck extends its bridge, GroundPowerUnit deploys its cable). | BaggageLoader, BoardingRamp, CateringTruck, GroundPowerUnit, FuelTruck |
Loading |
The vehicle is connected to the aircraft and starts doing its job. | BaggageLoader, BaggageCart, BoardingRamp, CateringTruck, GroundPowerUnit, Pushback, SmallPushback |
Unloading (future) |
Same as Loading , but aimed to take place after a flight (to unload baggages and passengers) rather that before a flight. |
BaggageLoader, BaggageCart, BoardingRamp, CateringTruck, GroundPowerUnit, Pushback, SmallPushback |
Finished_Operation |
Immediately after the Loading /Unloading state ended, the vehicle starts moving back or animating to detach from the aircraft. |
BaggageLoader, BoardingRamp, CateringTruck, GroundPowerUnit, Pushback, SmallPushback, FuelTruck |
Before_Leaving_Aircraft |
Final gathering up state before the vehicle completely leaves the aircraft (BaggageLoader moves back, BoardingRamp retracts its stairs, CateringTruck moves down its container). For FuelTruck, this is used to move from the aircraft to the parking edge. | BaggageLoader, BoardingRamp, CateringTruck, FuelTruck |
Move_Back_To_Parking |
The vehicle moves back to its initial position. Note that the FuelTruck can perform multiple requests in a row, so this may cause the truck to begin the next request before going back to parking. | BaggageLoader, BaggageCart, BoardingRamp, CateringTruck, GroundPowerUnit, Pushback, SmallPushback |
Loading_AI |
Equivalent to Loading , when connected to an AI aircraft. |
FuelTruck |
Loading_User |
Equivalent to Loading , when connected to the User aircraft. |
FuelTruck |
UserClosedWindowDuringLoading |
When the FuelTruck starts Loading_User , the refueling window appears on screen. This state is triggered if the User closes this window during the Loading state. |
FuelTruck |
<SimMission.SendMessageToAIAction>
This element can be used to send a message to the AI of an object (or multiple objects). It can contain the sub-elements <Name>
, <Descr>
and <ObjectReferenceList>
and has the following attribute:
Attribute | Description | Type | Required |
---|---|---|---|
InstanceId |
The GUID that will be used to identify this AI action. |
String |
Yes |
<Name>
This element is used to set the name of the message to be sent. A message name sent to an AI could be any string, but currently only one message has an effect, and even then, not on all AI types. The currently valid message is shown in the table below (note that the message name is placed between <Name>
opening and closing tags as plain text without quotes):
Message | Description | Available AIType |
---|---|---|
FINISHED_OPERATION |
Warns the AI that the Loading (or Unloading) phase is finished, and that this service should start its regular behavior to detach from aircraft. | BaggageLoader, BoardingRamp, CateringTruck, GroundPowerUnit, FuelTruck |
<
Descr
>
This element is used to give a brief description of the AI action being defined. The description is placed between <Descr>
opening and closing tags as plain text without quotes, and the element has no attributes.
<SimContain.Container>
The <SimContain.Container>
element is used to create a Sim Object, and can contain multiple different elements depending on the context of mission file it's being used in. However, here we'll list some of the elements that are specifically related to services and idle workers. The sub-elements we'll discuss here for <SimContain.Container>
are <HumanPilotAI>
, <IdleWorkerAI>
, and <AttachedWorldObject>
.
The <SimContain.Container>
also has the following attributes that are useful when dealing with services and idle workers:
Attribute | Description | Type | Required |
---|---|---|---|
InstanceId |
GUID of the SimObject, used in other elements of the script to reference this object | GUID | Yes |
Descr |
Informal description of the SimObject | String | Yes |
AIType |
The AI type of the SimObject. |
Enum: None |
Yes |
UseRegionContainerType |
If true and if no ContainerTitle is specified, the model used will be taken at random in the correct category (based on AIType ) from the current LivingWorld region |
Bool | No |
ContainerTitle |
Explicit title for the SimObject. Only required if UseRegionContainerType is FALSE or undefined. |
String | No |
Here is a correspondence table between AIType
and the associated category from the LivingWorld Configuration File:
AIType |
Category from LivingWorld configuration |
---|---|
FuelTruck |
<FuelTrucks> |
PushBack |
<PushbackTugs> |
SmallPushBack |
<SmallPushbacks> |
BaggageCart |
<BaggageCarts> |
BaggageLoader |
<BaggageLoaders> |
CateringTruck |
<CateringTrucks> |
BoardingRamp |
<BoardingRamps> |
GroundPowerUnit |
<GroundPowerUnits> |
VehicleFollower |
<BaggageDollies> |
AirportAmbient |
<AmbientTraffic> |
IdleWorker |
<IdleWorkers> |
GroundVehicle_Pilot |
<GroundVehiclePilots> |
Marshaller |
<Marshaller> |
WanderBoat |
<InlandBoats> (in <Boats> , not <Airport> ) |
<HumanPilotAI>
This element defines the AI parameters for objects with AIType GroundVehicle_Pilot
or Aircraft_Pilot
. The element takes no parameters and has the sub-element <HumanPilotType>
.
<HumanPilotType>
This element determines which type of pilot is for this object, and thus which parameters should be read from the *.cfg
file of the attached vehicle (attach node and default animation). The available AI types are:
Unknown
Pilot
Copilot
The AI type is placed between <HumanPilotType>
opening and closing tags as plain text without quotes, and the element has no attributes. Note that such a pilot object must have an <AttachedWorldObject>
in order to be actually attached to its vehicle.
<IdleWorkerAI>
This element defines the AI parameters for objects with AIType IdleWorker
. This is a container element and the AI is defined using the following sub-elements:
Element | Description | Type | Required |
---|---|---|---|
<Unit_Mode> |
Initial Unit Mode of the AI. Should not make any difference for IdleWorker with current version of MSFS. Default is Waypoint . |
Enum: Sleep |
No |
<GroundCruiseSpeed> |
The speed (in Knots) for this IdleWorker AI. Default is 35. | Float | No |
<GroundTurnSpeed> |
IdleWorker AI slows to this speed in Knots when making sharp turns. Default is 10. | Float | No |
<GroundTurnTime> |
IdleWorker AI attempts to make 90° turns in this amount of time. Value is in seconds and defaults to 3.5. | Float | No |
<WaypointTouchDistance> |
Distance (in meters) at which IdleWorker AI considers a waypoint to be reached. Default is 1.0. | Float | No |
<YieldToUser> |
Whether the IdleWorker will stop moving (TRUE) when getting too close to the User aircraft or not (FALSE). Default is TRUE. | Bool | No |
<KeepLastHeading> |
Whether the IdleWorker will try to reach the heading defined by its last two waypoints before reaching its last waypoint, even if that means slightly less precision on the final position. When FALSE, the IdleWorker will only focus on reaching the exact position of the last waypoint, ignoring orientation. Default is TRUE. | Bool | No |
<CanReverse> |
Whether the IdleWorker will try to maneuver backwards (TRUE) when it missed one if its waypoints, or not (FALSE). Default is TRUE. If the AI is an IdleWorker rather than a Service, this value is better set to FALSE. | Bool | No |
<WaypointList> |
List of waypoints the IdleWorker can start with. Will only be useful if the <Unit_Mode> element is set to Waypoint . Unless using simple IdleWorker scripts that do nothing except for creating an IdleWorker, we recommend not using the in the . It is usually better to initialize the IdleWorker as idle, and use scripting (such as TimerTrigger for example) to later set up various behaviors, including a WaypointList by using a ActivateWaypointsAction . |
Waypoint sub-elements | No |
Note that for each of the above listed elements (except <WaypointList>
), the required value - string, enum, etc... - is placed between the opening and closing element tags as plain text without quotes. None of the elements have attributes.
<AttachedWorldObject>
This element gives a reference to a world object that the Service or IdleWorker is "attached" to. This is a container element for the following sub-elements:
Element | Description | Type | Required |
---|---|---|---|
<OffsetXYZ> |
Offset XYZ (in meters) defining where to place this object relative it its reference. Note that the 4th value is unused, and axes X, Y, Z represent the left-right axis, upward axis, and forward axis, respectively. | 4 comma-separated Floats | No |
<Orientation> |
pbh orientation (in degrees) of this object relative to its reference. Note that currently only the heading (3rd value) is taken into account. | 3 comma-separated Floats | No |
<IsOnGround> |
Is this object placed on ground (TRUE) or not (FALSE). | Bool | No |
<NodeName> |
Name of a Node from the reference object to which this object will be attached. | String | No |
If the object has a NodeName
defined here, or if it has a <HumanPilotAI>
with a HumanPilotType
Pilot or Copilot, then it will be attached to the reference (to a specific Node, either explicit, or defined in the *.cfg
of the reference model). Otherwise, only the initial position will be used to initialize this object relative to the reference, using the <OffsetXYZ>
, <Orientation>
, and <IsOnGround>
data.
Note that for each of the above listed elements (except <WaypointList>
), the required value - string, enum, etc... - is placed between the opening and closing element tags as plain text without quotes. None of the elements have attributes.
Apart from the above optional elements, the <AttachedWorldObject>
element also requires an <ObjectReference>
to define the actual object that is being attached to. You can find out more about this element from the following link: