README

openSAM plugin for X-Plane 12

Marshaller and VDGS guidance for all sceneries
Jetway and object animation for custom sceneries

One stop destination for DGS guidance, drop in replacement for legacy SAM, support for new custom sceneries.

Installation and Support

Update from 4.x

openSAM v5.x differs in it's file layout and a fresh install is recommended in order to avoid a lot of stale files.
If you changed the configuration files bring forward your changes into planes.cfg.
AutoDGS is now included in openSAM. Copy over your airport configuration <xp_dir/Output/AutoDGS> to <xp_dir/Output/openSAM> .
In addition commands AutoDGS/... are renamed to openSAM/... so your your key and button bindings may need some rework.

Initial Installation

This plugin runs on XP12 only. If you want to use it with XP11 stick to a 4.x release

  1. Only use this link for downloading the latest release .
  2. Remove the AutoDGS plugin. It's functionality is included in openSAM.
  3. Remove the SAM plugin (but keep the embedded SAM_Library somewhere).
  4. If you already deleted SAM but use a SAM replacement library (e.g. "FlyAgi - SAM Fallback Library") remove it.
  5. If installed remove the "SAM Seasons emulator" plugin. Its functionality is included in openSAM.
  6. From the downloaded zip install
    • "openSAM_Library" into "Custom Scenery"
    • "openSAM" into "Resources/plugins"
  7. Start X-Plane into the startup menu and close it immediately.

Some sceneries (e.g. for Zero Dollar Payware, Taimodels) require the original SAM_Library

Sources of SAM_Library (if you really need it)
See the first line of this post: https://forum.aerosoft.com/index.php?/topic/167270-sam3-now-available/ .
Other options are ORBX Central or Aerosoft One (Check under Library/Dependencies/Optional).
Note (again) that the library is embedded in the SAM plugin. Don't install the SAM plugin when using openSAM. Just copy the library out of the plugin folder into "Custom Sceneries".

Keep the plugin current

After you've installed it once Skunkcrafts Updater will take care. Be sure you select the right channel PROD or BETA.
If you use BETA make sure you have fully understood how Skunkcrafts channels work.

Download link for Skunkcrafts updater .

Support

General support is on Discord only: https://discord.gg/BtDvKcUSEP .
PMs, pings etc. will be ignored. Github issues will be closed without comment.

Also refrain from submitting PRs with 'general improvements' generated by AI (e.g. VS Code Copilot).

DGS guidance

Activation of DGS

After you LAND (= some air time!) on an airport the plugin activates and searches actively for suitable stands in the direction that you are taxiing. Note that you MUST have your beacon on. Once you come closer the VDGS or the Marshaller give appropriate guidance information.

If you just want to try out the feature without prior flight you must issue the command "openSAM/activate", "Manually activate searching for DGS" through a binding or the menu.
Beacon on, of course!

Image

Image

Image

Helicopter support

For helicopters the plugin activates when you are below 10m AGL for at least 10 seconds. Note that guidance signals are the same as for fixed wing aircrafts. Image

Preselect Mode

When on ground you can preselect a stand in the GUI (e.g. after you get a stand assigned on VATSIM).
Depending on the selected stand a Marshaller appears or the VDGS lights up in "lead in" mode.

Preplan the arrival gate via simbrief OFP

Put a string ARRIVAL_STAND=<stand>; into simbrief's dispatch remarks.
When AutoDGS enters departure mode this information is picked up and the named stand is automatically selected after arrival.
Should you be assigned to a different gate later use the GUI to change to that one or use Automatic.

Boarding

When parked for departure (= beacon off, engines off, no. of pax = 0) boarding is detected when the no. of pax starts rising. The current no. of pax is displayed in the VDGS.
Currently suuports only the ToLiss fleet.

Image

Simbrief integration

With Simbrief integration the VDGS displays flight number, destination and out/off times as well.
This requires the simbrief_hub plugin to be installed.

Image

Standard scenery

The default VDGS for standard sceneries can be selected in the menu. Image

Per default all stands with jetways get a VDGS and all others get a Marshaller. This can easily be changed with the UI. First ensure that the plugin is activated then select the stand and change the setting accordingly.
See a video here -> https://www.youtube.com/watch?v=EAuWxt0DB-8
The configuration is saved in "<xp_dir>/Output/openSAM/<airport_icao>.cfg" and loaded automatically on your next visit of the airport.

Image

Custom sceneries

The scenery artist placed DGS objects (Marshaller, type of VDGS) and jetways in WED. There is no further customization option.

Jetways

Image

Custom animations / Remote Control

Image

Multiplayer support

openSAM supports

Set up your multiplayer environment as needed (e.g. connect to Vatsim and/or enable/disable MP plugins).
Then select "Toggle Multiplayer Support" in openSAM's menu.
If xPilot is connected to Vatsim that takes precedence over other installed multplayer plugins.
The menu text of "Toggle Multiplayer Support" shows which personality is enabled.

Note
xPilot and liveTraffic receive aircraft positions from other sceneries / simulators or the real world and these may not match up with your installed scenery. Your mileage will vary.

TGXP gives the visually most pleasing rendition.

Image

Image

Usage

The openSAM plugin defines commands:

The first three commands are accessible through the menu as well.

openSAM augments XP12's standard command "sim/ground_ops/jetway":

In addition openSAM exports datarefs:

"opensam/jetway/number"
    number of jetways at stand
"opensam/jetway/status"
    0 = no jetway(s)
    1 = jetway(s) present, available for docking
    2 = docked
   -1 = can't dock or jetway(s) in transit
"opensam/jetway/door/status" array per door
    0 = no jetway docked at this door
    1 = jetway docked at this door

Customize actions after docking / before undocking

openSAM calls optional commands "openSAM/post_dock" and "openSAM/pre_undock".
See a sample in the lua directory for the ToLiss fleet and more examples in the contributed directory.

Customizations for Planes

Newer VDGS perform monitoring of ramp equipment (chocks, GPU, PCA, ...). Datarefs for this task vary by plane and are configured in file planes.cfg in the plugin directory.
Example:

# Toliss A321
icao    A321
studio  ToLiss
pax_no_dref AirbusFBW/NoPax
chk_dref AirbusFBW/Chocks 1
gpu_dref AirbusFBW/EnableExternalPower 1
pca_dref AirbusFBW/GroundLPAir 1
chk_set dref AirbusFBW/Chocks 1
door_2 -1.90 0.61 -7.65

# Toliss all other planes
icao    A[0-9N]+
studio  ToLiss
pax_no_dref AirbusFBW/NoPax
chk_dref AirbusFBW/Chocks 1
gpu_dref AirbusFBW/EnableExternalPower 1
pca_dref AirbusFBW/GroundLPAir 1
chk_set dref AirbusFBW/Chocks 1

Door positions are often bogus and a docked jetway may not fit well to the door. This is in particular true for the position of a second door. openSAM picks up the position of door 1 from X-Plane datarefs (they end up there from the .acf file).
If these do not match well for a specific aircraft type you can override them in planes.cfg.

To find the (or a better) position proceed as follows:

Locate the "openSAM: plane loaded" line in Log.txt.

openSAM: plane loaded: B742, plane_cg_y: -2.44, plane_cg_z: 31.81, door 1: x: -2.93, y: 1.77, z: -22.45

Use these values as a starting point: door 2 is somewhat behind meaning z towards the tail and the correct line to enter in "acf_door_position.txt" is:

B742 2 -2.93 1.77 -14.40

Please share results so they can be included in future updates.

Support for Scenery builders with "openSAM Zero Configuration"

Zero configuration for Marshallers, VDGS and MisterX jetways

openSAM_Library contains a Marshaller, a VDGS (with or without pole) in various heights and MisterX's jetways as SAM library jetways.
Just place these assets from the openSAM folder in WED's library view.
For jetways use a proper initial orientation of the tunnel. At runtime the cabin will point perpendicular to the stand with slight random variations.

Then copy file openSAM_Library/dev-tools/sam.xml into your scenery and you are done.

Zero Configuration jetways for own jetway objects

As a scenery designer you can add your own jetway objects as library jetways

openSAM_Library/dev-tools contains example files and an example airport.
In case you want to keep your jetway objects unmodified script dev-tools/gen_libjw_from_jw.py converts your object nondestructively into a separate library object by appending _ljw to the base name.

py gen_libjw_from_jw -jwpath "<somepath>/myjetway.obj -set hotbso_1 creates a file myjetway_ljw.obj in the current directory and uses the specified set name for datarefs.

Note: all collected library jetways share a single global namespace. Hence be specific with your set names e.g. include your studio name.

Additional datarefs

You can close the canopy of a jetway using sam/jetway/canopy.
Docking: After reaching the door position this dataref changes from 0 to 1 within 5 seconds.
Undocking: Starts with setting the dataref back to 0 within 5 seconds, when below 0.5 the jetway starts driving away.

Credits

Jonathan Harris (aka Marginal) for creating Autogate
cxn0026 for explaining how Marshallers and VDGS really use guidance signals
Papickx + @cxn0026 for providing better textures and day + night lighting
zodiac1214 (aka cfanap) for creating the automated build and release system including skunkcrafts support
TwinFan for providing LTAPI
X-Codr for performance improvements
Pierre for reworking the VDGS model and giving it much more precision and details
MisterX for allowing to include his jetways as library jetways in openSAM_Library
Blender KIT for free pbr materials
William Good for imgui4xp

License

Please observe that this material is covered by various licenses.

The objects and textures and source code of Autogate by Marginal:

-- copy of license remark from https://github.com/Marginal/AutoGate ---

The plugin code in the src directory is licensed under the GNU LGPL v2.1 license.\
The rest of the kit is licensed under the Creative Commons Attribution license. In short, you can use any part of this kit (including the 3D objects and their textures) in original or modified form in a free or commerical scenery package, but you must give the author credit.

The alerting sound for jetways:

pixabay.com "8 royalty-free reverse-beep sound effects"
https://pixabay.com/sound-effects/backing-up-beepwav-14889/

LTAPI code

/// @author     Birger Hoppe
/// @copyright  (c) 2019-2025 Birger Hoppe
/// @copyright  Permission is hereby granted, free of charge, to any person obtaining a
///             copy of this software and associated documentation files (the "Software"),
///             to deal in the Software without restriction, including without limitation
///             the rights to use, copy, modify, merge, publish, distribute, sublicense,
///             and/or sell copies of the Software, and to permit persons to whom the
///             Software is furnished to do so, subject to the following conditions:\n
///             The above copyright notice and this permission notice shall be included in
///             all copies or substantial portions of the Software.\n
///             THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
///             IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
///             FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
///             AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
///             LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
///             OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
///             THE SOFTWARE.

Jetways by MisterX

See the license reproduced in Image .

PBR materials by Blender Kit

See https://www.blenderkit.com/docs/licenses/

Contributions by hotbso:

This is in parts a derived work from Autogate so the above mentioned licenses apply accordingly to the components of this project.
The VDGS "Safedock-X" and "Safedock-T2-24" are original work created by hotbso and licensed under "CC BY-NC-SA" (https://creativecommons.org/licenses/by-nc-sa/4.0/).
In addition to "CC BY-NC-SA" creators of payware sceneries are allowed to reference these files from openSAM_Library but not to distribute them with their scenery.

Other Licenses for software used by openSAM

Copyright (c) 2018-2020 Christopher Collins

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

MIT License

Copyright (c) 2020 William Good

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.