*****************************************************************
* Users' guide to the GENERIC PAYLOAD DESCRIPTION SYSTEM (GPDS) *
*                                                               *
*            by D Henderson (orbiter@aibs.org.uk)               *
*                         20/7/2004                             *
*****************************************************************


GPDS is a system for describing a payload on one line in the
Orbiter scenario file and in inter-vessel communications.

It was originally invented (GPDS1) for the standalone Ariane 5
module where it was used to describe multiple payloads and even
additional user-definable upper stages.

Slightly enhanced in the, now defunct, CVE library as GPDS2 it
has now been adopted for the cut-down CVE-lite library and is
now technically GPDS v3.



THE PAYLOAD TAG
===============

Put simply GPDS allows users of CVE-lite compatible vessels to
describe multiple payloads quickly and easily using the PAYLOAD
key in the scenario file.



PAYLOAD payloadname mesh class x y z mass xrot fuellevel



Here, "payloadname" is simply the alphanumeric name you wish the
created payload to have.

"Mesh" is the name of the mesh file, including any paths off ~/Mesh
that will represent the payload on the stack before it is
separated, minus the ".msh"

"Class" is the payload's classname, such as "deltaglider" or "module1".

"x", "y" and "z" represent floating point offsets from the launching
vessel's reference point (normally the centre of mass) that the mesh
should be drawn. An example would be "0 0 4" for four metres along
the centreline of the vessel.

"Mass" is the ALL-UP-MASS of the vessel that is to be created, INCLUDING
fuel load. If you vary the loaded fuel (see later), you really ought
to change this value here to be consistent.

"Xrot" is now sadly abandoned due to a limitation in Orbiter's
current API, simply put a zero (0) here.

"Fuellevel" is the level (0->1) of fuel you wish the spawned payload
to be equipped with. Not all vessels support the changing of their
fuel state at creation, however. Most DLL-based craft won't unless
they too are CVE-lite compatible, but most CFG-based vessels will
quite happily.




THE STAGE TAG
=============

STAGEs are broadly similar to PAYLOAD *except* they constitute
additional stages to your vessel. That is to say, if you mount a
payload above a stage (and before and ENDSTAGE -- see below) it
will separate WITH that "stage" vehicle and you may continue to
loft the payload(s) before jettionning it later. An example would
be the Soyuz launch vessel may configure a Fregat as a STAGE with
the MarsExpress as a PAYLOAD above it.


STAGE payloadname mesh class x y z mass xrot fuellevel


(definitions as for PAYLOAD)




THE ENDSTAGE TAG
================

Differing to GPDS1 and 2 here, the ENDSTAGE tag allows the user to
close-off a substage and continue stacking payloads or more stages
onto the launch vessel directly. It takes no parameters.

An example would be an Ariane 5 launching two fregats, both
containing MarsExpress orbiters as PAYLOADs.


ENDSTAGE





EXAMPLES
========
========

Some basic (and not so basic!) examples.


One Module-1 aboard a Proton-K from Baikonur.
=============================================

Proton1:protonk
  STATUS Landed Earth
  BASE Baikonur:5
  HEADING 90.00
  FUEL 1.000
  CONFIGURATION 0
  PAYLOAD UserModule module1 module1 0 0 30 15000 0 1
END


Here the module1 mesh is loaded on the launcher 30 metres above its
centre of mass. It weighs 15000. When it is jettisoned it will be
of class "module1", fully fuelled (the 1 on the end) and be
called "UserModule"


Two Module-2s
=============

  PAYLOAD UserModule1 module2 module2 0 0 27 8000 0 1
  PAYLOAD UserModule2 module2 module2 0 0 31 8000 0 1


Two Module-2s, each with their own CVE-lite fregat
==================================================

  STAGE Fregat1 fregat cvelfregat 0 0 27 7000 0 1
    PAYLOAD UserModule1 module2 module2 0 0 31 8000 0 1
  ENDSTAGE
  STAGE Fregat2 fregat cvelfregat 0 0 35 7000 0 1
    PAYLOAD UserModule2 module2 module2 0 0 39 8000 0 1
  ENDSTAGE



MarsExpress probe on a fregat and star48 upper stages
=====================================================

  STAGE Fregat1 fregat cvelfregat 0 0 27 7000 0 1
    STAGE Star1 star48 star48 0 0 30 5000 0 1
      PAYLOAD MarsExpress mars_express_stowed mars_express_deployed 0 0 33 600 0 1
    ENDSTAGE
  ENDSTAGE