Service And IdleWorker Script Definitions

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

Attribute	Description	Type	Required
`name`	The name of the state.	Enum: Sleep Move_Toward_Aircraft Before_Reaching_Aircraft Reached_Aircraft Loading Unloading Finished_Operation Before_Leaving_Aircraft Move_Back_To_Parking Loading_AI Loading_User UserClosedWindowDuringLoading	Yes
`UniqueRefId`	Reference to the GUID of the corresponding service object (the `InstanceId` attribute of the corresponding `<SimContain.Container>`)	String	Yes

name

The name of the state.

Enum:

Sleep
Move_Toward_Aircraft
Before_Reaching_Aircraft
Reached_Aircraft
Loading
Unloading
Finished_Operation
Before_Leaving_Aircraft
Move_Back_To_Parking
Loading_AI
Loading_User
UserClosedWindowDuringLoading

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 Airplane Helicopter WanderBoat GroundVehicle FuelTruck PushBack SmallPushBack BaggageCart BaggageLoader CateringTruck BoardingRamp GroundPowerUnit VehicleFollower AirportAmbient IdleWorker AirplanePlayback Boat Animal FlyingAnimal Human Aircraft_Pilot Marshaller Jetway Linked_Object	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 Zombie Waypoint Takeoff Landing Taxi Working Waiting	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.

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:

<ObjectReference>