Tutorial: How to create scenarios

HOW TO CREATE SCENARIOS

Made by José Pablo Luna Sánchez. October 2005. Version 1.5
Special thanks to Tony Dunn for sharing his knowledge and patiently answering my questions on MJD issues.
Thanks to FlyingSinger and Martin Schweiger for their comments to improve this tutorial.

You are authorized to use this tutorial for non commercial purposes only.
You are not authorized to repack of modify the contents of this pack without written consent of the author.
However you may post and modify the contents of this tutorial for wiki purposes only, as long as credits are kept.

This tutorial includes an RPOS/MJD calculator.
Use it under your own risk.
There is no guarantee or support associated to this software.
You are not authorized to repack or bundle the software included in this tutorial.

This tutorial was designed to be used with Martin Schweiger's Orbiter Space Flight Simulator 2005.

Feedback: jpluna@racsa.co.cr

UNDERSTANDING SCENARIOS

What is a scenario?
We could think about it as "saved game" data that will tell Orbiter when and where are all the ships, and what was their status and configuration.

Scenarios are .SCN files located at the Orbiter SCENARIOS directory.
You can place your scenario in that directory, or you may create a subdirectory inside the SCENARIOS directory and place your .SCN file there.
You may edit scenarios using Notepad.

In this tutorial we will focus on how to add and configure ships, and we won´t cover the rest of the scenario sections very much.

A very simple scenario would look like this:

BEGIN_DESC
Mission description goes here.
END_DESC

BEGIN_ENVIRONMENT
System Sol
Date MJD 51982.6694917396
Help Quickstart,Quickstart
END_ENVIRONMENT

BEGIN_FOCUS
Ship GL-01
END_FOCUS

BEGIN_CAMERA
TARGET GL-01
MODE Cockpit
FOV 50.00
END_CAMERA

BEGIN_HUD
TYPE Surface
END_HUD

BEGIN_SHIPS
ISS:ProjectAlpha_ISS
STATUS Orbiting Earth
RPOS 4371906.67 4638652.99 -2156350.93
RVEL 5678.884 -5187.678 363.180
AROT 110.00 -10.00 80.00
PRPLEVEL 0:1.000
IDS 0:588 10 1:586 10 2:584 10 3:582 10 4:580 10
NAVFREQ 0 0
XPDR 466
END
Mir
STATUS Orbiting Earth
RPOS -5427947.72 -237037.73 -3875787.18
RVEL 4498.408 -383.038 -6269.997
AROT 0.00 -45.00 90.00
IDS 0:540 100 1:542 100 2:544 100
XPDR 482
END
Luna-OB1:Wheel
STATUS Orbiting Moon
RPOS -2103499.87 767771.95 -173.86
RVEL -507.333 -1390.014 0.226
AROT 0.00 0.00 -65.22
VROT 0.00 0.00 10.00
IDS 0:560 100 1:564 100
XPDR 494
END
GL-01:DeltaGlider
STATUS Landed Earth
POS -80.6858943 28.5906644
HEADING 330.01
RCSMODE 0
PRPLEVEL 0:0.995 1:1.000
NAVFREQ 94 524 84 114
XPDR 0
GEAR 1 1.0000
PSNGR 2 3 4
END
SH-03:ShuttleA
STATUS Landed Earth
BASE Habana:4
POS -82.3982414 23.0005396
HEADING 70.00
PRPLEVEL 0:1.000 1:1.000
NAVFREQ 0 0
XPDR 0
PODANGLE 0.0000 0.0000
DOCKSTATE 0 0.0000
AIRLOCK 0 0.0000
GEAR 0 0.0000
PAYLOAD MASS 6.1 0
END
PB-01:ShuttlePB
STATUS Landed Earth
BASE Habana:1
POS -82.4000000 22.9994604
HEADING 22.00
PRPLEVEL 0:1.000
NAVFREQ 0 0
END
GL-02:DeltaGlider
STATUS Landed Mars
BASE Olympus:3
POS -135.4300000 12.7366196
HEADING 0.00
PRPLEVEL 0:1.000 1:1.000
NAVFREQ 0 0 0 0
XPDR 0
GEAR 1 1.0000
END
SH-01:ShuttleA
STATUS Landed Moon
BASE Brighton Beach:1
POS -33.4375000 41.1184067
HEADING 0.00
PRPLEVEL 0:1.000 1:1.000
NAVFREQ 0 0
XPDR 0
PODANGLE 0.0000 0.0000
DOCKSTATE 0 0.0000
AIRLOCK 0 0.0000
GEAR 0 0.0000
PAYLOAD MASS 0.5 0
END
END_SHIPS

Does it look too complex? It´s not that complex as it seems.
We will learn how to configure your scenario easily.

The scenario has been highlighted in 2 colors.
We will call the RED text as "template" and we will call the BLUE text as "ships section".
We will need both to build a scenario, but we will analyze them separately.

To make things simple, our craft will have MFDs turned off, and you will be inside your craft, when the scenario is loaded.
Otherwise we would need to care about many other things when configuring the template.

THE SCENARIO TEMPLATE

Since we want to make scenario edition simple, let's start with this template.
After this template we would need to add the SHIPS section only.

BEGIN_DESC
Mission description goes here.
END_DESC

BEGIN_ENVIRONMENT
System Sol
Date MJD 51982.6694917396
END_ENVIRONMENT

BEGIN_FOCUS
Ship GL-01
END_FOCUS

BEGIN_CAMERA
TARGET GL-01
MODE Cockpit
FOV 50.00
END_CAMERA

BEGIN_HUD
TYPE Surface
END_HUD

The highlighted text will be replaced with the data you want:

GREEN text contains the mission description that will appear in the Orbiter Launchpad window.

BLUE text contains the time in history where your scenario takes place.
It will determine the position of all stars in the solar system.

RED text is the NAME of your current craft, the craft you are piloting.
This name will appear in the game.
It is important to include short names.
It is also important that such name appears in the SHIPS section that we will cover later.
You don't want long names when you are typing the name of your target for a rendezvous or docking procedure.

So you may copy this text and add it to your scenario, and replace the highlighted data.

CONFIGURING DATE MJD

Many users face a problem when editing scenarios: "How do I calculate MJD?"

MJD FOR PROGRAMMERS

If you were a programmer, you should know that MJD is calculated as

MJD = D + 15018

where MJD is a double precision variable and D is a date variable.
You could make an MJD calculator if you knew how to code.

MJD FOR COMMON USERS

But since you may NOT be a programmer, but a common user, you may download the Orbit Calculator 2.0 made by Trevor Johns, or you may use the RPOS/MJD calculator that is included in this tutorial.

CALCULATING MJD MANUALLY

If you want to calculate it manually, you will need a simpler way to calculate MJD using Windows calculator in scientific mode.
Let's see how it can be done.

Let's see the following examples:

January 1st, 2000
MJD 51544

January 1st, 2001
MJD 51910
366 days later

As you may notice, a year has 365 days but the difference between those MJD dates is 366 because year 2000 has 29 days in february (an extra day).

CALCULATING MONTH AND DAY

Now we need to find out how many days we must add so we are in the first day of a certain month.
Let's use January 1st, 2001 as reference.

January 1st, 2001
MJD 51910

February 1st, 2001
MJD 51941
31 days later

March 1st, 2001
MJD 51969
59 days later

April 1st, 2001
MJD 52000
90 days later

May 1st, 2001
MJD 52030
120 days later

June 1st, 2001
MJD 52061
151 days later

July 1st, 2001
MJD 52091
181 days later

August 1st, 2001
MJD 52122
212 days later

September 1st, 2001
MJD 52153
243 days later

October 1st, 2001
MJD 52183
273 days later

November 1st, 2001
MJD 52214
304 days later

December 1st, 2001
MJD 52244
334 days later

So if we wanted to know the MJD date for June 18th, 2001 we may have:

MJD = 51910 (January 1st, 2001) + 151 (June 1st) + 17 = 52078

As you may notice, for June 18th we added 17 days, because we already were on June 1st.

For July 4th 2005 we would have:

MJD = 51910 + 365 * 4 (4 years from 2001) + 181 (July 1st) + 3 (July 4th) + 1 (year 2004 has 29 days, so it adds an extra day) = 53555

If we calculated July 4th 2005 from January 1st, 2000 we'd have:

MJD = 51544 + 365 * 5 (5 years from 2000) + 181 (July 1st) + 3 (July 4th) + 2 (years 2000 and 2004 have 29 days) = 53555

If we had to calculate January 1st 1998, using January 1st 2000 as reference, we'd have:

MJD = 51544 - 365 * 2 = 50814

Notice that year 2000 has 29 days in february but since we go back in time, we won't have to consider it.

CALCULATING TIME

Now let's go for the time.
24 hours are 1 day, so 1 hour should be 1/24 of a day.
One minute should be 1/1440.
Once second is 1/86400

So if the time is 13:40:01 then we have:

TIME = 13/24 + 40/1440 + 01/86400 = 0.5694560185

If we had July 4th 2005, 13:40:01 then our MJD date would be

MJD = 53555 + 0.5694560185 = 53555.5694560185

TIME ZONE CONSIDERATIONS

So as you see, MJD already has time of the day.
However, that time (13:40:01) is the time in London, Greenwich time.
So if you are elsewhere on Earth, that won't be your local time.

If you are in Costa Rica, your local time would be -6 hours (07:40:01), and if you are in Argentina your local time would be -3 hours (10:40:01).
So as you see, since both Costa Rica and Argentina are to the west of Greenwich, if you have a certain local time, you must add some hours to your local time.
If you were to the east of London, you'd need to add negative hours to your local time.

Costa Rica Local Time + 6 hours = Greenwich time
Argentina Local Time + 3 hours = Greenwich time

So, before you make MJD calculations, you first need to find the time in London.

THE MJD FORMULA FOR COMMON USERS

So in general terms we have the following formula:

MJD = Reference date + years *365 + month days + (day-1) + extra days (how many february 29th days are in the middle of current and reference dates) + hours/24 + minutes/1440 + seconds/86400

Notice that if your current date is in the past from your reference date, years and extra days must be negative.

It's a bit long, but very easy.
Don't you think?
If you know how to use a spreadsheet you may automate the calculation.
If you use Windows calculator I may advise to switch it to scientific mode (select View > Scientific) before making the calculations, or your numbers could be wrong.

THE SHIPS SECTION

A typical ships section may look like this:

BEGIN_SHIPS
ISS:ProjectAlpha_ISS
STATUS Orbiting Earth
RPOS 4371906.67 4638652.99 -2156350.93
RVEL 5678.884 -5187.678 363.180
AROT 110.00 -10.00 80.00
PRPLEVEL 0:1.000
IDS 0:588 10 1:586 10 2:584 10 3:582 10 4:580 10
NAVFREQ 0 0
XPDR 466
END
Mir
STATUS Orbiting Earth
RPOS -5427947.72 -237037.73 -3875787.18
RVEL 4498.408 -383.038 -6269.997
AROT 0.00 -45.00 90.00
IDS 0:540 100 1:542 100 2:544 100
XPDR 482
END
Luna-OB1:Wheel
STATUS Orbiting Moon
RPOS -2103499.87 767771.95 -173.86
RVEL -507.333 -1390.014 0.226
AROT 0.00 0.00 -65.22
VROT 0.00 0.00 10.00
IDS 0:560 100 1:564 100
XPDR 494
END
GL-01:DeltaGlider
STATUS Landed Earth
POS -80.6858943 28.5906644
HEADING 330.01
RCSMODE 0
PRPLEVEL 0:0.995 1:1.000
NAVFREQ 94 524 84 114
XPDR 0
GEAR 1 1.0000
PSNGR 2 3 4
END
SH-03:ShuttleA
STATUS Landed Earth
BASE Habana:4
POS -82.3982414 23.0005396
HEADING 70.00
PRPLEVEL 0:1.000 1:1.000
NAVFREQ 0 0
XPDR 0
PODANGLE 0.0000 0.0000
DOCKSTATE 0 0.0000
AIRLOCK 0 0.0000
GEAR 0 0.0000
PAYLOAD MASS 6.1 0
END
PB-01:ShuttlePB
STATUS Landed Earth
BASE Habana:1
POS -82.4000000 22.9994604
HEADING 22.00
PRPLEVEL 0:1.000
NAVFREQ 0 0
END
GL-02:DeltaGlider
STATUS Landed Mars
BASE Olympus:3
POS -135.4300000 12.7366196
HEADING 0.00
PRPLEVEL 0:1.000 1:1.000
NAVFREQ 0 0 0 0
XPDR 0
GEAR 1 1.0000
END
SH-01:ShuttleA
STATUS Landed Moon
BASE Brighton Beach:1
POS -33.4375000 41.1184067
HEADING 0.00
PRPLEVEL 0:1.000 1:1.000
NAVFREQ 0 0
XPDR 0
PODANGLE 0.0000 0.0000
DOCKSTATE 0 0.0000
AIRLOCK 0 0.0000
GEAR 0 0.0000
PAYLOAD MASS 0.5 0
END
END_SHIPS

As you may notice, it starts with BEGIN_SHIPS and it ends with END_SHIPS.
Each ship was highlighted with a different color.
Notice that each ship has END parameter at the end of the configuration.

The first line of each ship configuration follows the following format:

<Name>:<Ship Class>

Examples:

SH-01:ShuttleA
GL-02:DeltaGlider

Notice that Mir station is the only exception to this rule.

NAMES

The <Name> parameter is an arbitrary name you define for each ship.
Don't make 2 ships to have the same name, or your scenario won't work properly.
Try not to use long names. It's boring to type long names when you need to perform docking operations.

SHIP CLASS

Notice that in this scenario we have DeltaGlider, ShuttleA and ShuttlePB class ships.
Wheel and ProjectAlpha_ISS class are for space stations.

The <Ship Class> is the name of a .CFG file you must have in the CONFIG directory.
If you don't have such a file, your scenario won't work properly.

SHIP PARAMETERS

Notice that each ship have some common parameters and some parameters that are particular for each ship class.
Ships usually have parameters for:

Position
Attitude (Orientation)
Motion (Velocity, angular velocity)
Fuel/Resources
Cargo/Payload
Internal systems status
Radio frequencies (useful for targeting, landing or docking)
Other (attachments, stages, docking condition, etc)

Example:

GL-01:DeltaGlider
STATUS Landed Earth
POS -80.6858943 28.5906644
HEADING 330.01
RCSMODE 0
PRPLEVEL 0:0.995 1:1.000
NAVFREQ 94 524 84 114
XPDR 0
GEAR 1 1.0000
PSNGR 2 3 4
END

Some add ons may add parameters to known ships.
So there is not a standard way to construct the SHIPS section.
It will depend on the ship class and add ons installed.

That brings a headache to those programmers who may want to create an application to build scenarios.
So either the apps are too generic or the application may be too complex for a common user.
Also it makes that a scenario that works for you, may not work for someone else.

So the best way to build a scenario is to use a template and replace only the data you know how to handle.

You must add a SHIPS section to your scenario template if you want to have a scenario that works

Let's analyze the most common parameters you may need to configure when you build a scenario using a standard Delta Glider or a Shuttle-A spacecraft.

STATUS

It describes if your ship is LANDED or ORBITING a planet.
It's Orbiting since the moment it is moving.
Landed craft are quiet on the ground.

Notice that planets will also have a CFG file and they should be included in the system CFG file.
Usually we could see "System Sol" parameter in a scenario. It indicates that we have a SOL.CFG file that will specify what planets are present.
Each planet will also have a CFG file.
So if your scenario doesn't work it is because either your planet doesn't exist in the SOL.CFG file or there is not a CFG file for your planet, or your current system does not refer to a system that contains such planet.

Syntax

STATUS <Status> <Planet>

<Status> could be either LANDED or ORBITING.

Example:

STATUS Landed Mars
STATUS Orbiting Moon

POS

It indicates the latitude and longitude of a landed craft.

Syntax

POS <Longitude> <Latitude>

West and south coordinates are negative.
Longitude goes from -180 to 180.
Latitude goes from -90 to 90.

Example:

POS -82.3982414 23.0005396

HEADING

It indicates the heading (where the nose is pointing) of a landed craft.

Syntax

HEADING <Degrees>

<Degrees> values range from 0 to 360 where

0 is North
90 is East
180 is South
270 is West

Example:

HEADING 70.00

BASE

It indicates the pad where a craft is landed.

Syntax

BASE <Surface Base>:<Landing pad>

Example:

BASE Olympus:3
BASE Habana:1
BASE Brighton Beach:1

RPOS

Indicates the relative position in meters for a craft, measured from the center of the planet in the 3 axes.
It means that the center of the planet would be a point where.

X = 0
Y = 0
Z = 0

We may think about RPOS as a certain point in space, defined by X, Y and Z coordinates.
It is used for ships that are orbiting a planet.
Your craft must be located at some point above the planet surface, or Orbiter will place it at a default position.

Understanding RPOS and RVEL from scratch is a bit complex without a tutorial, because the concepts involved are not very intuitive for a newcomer.
So let's try to see it graphically so we get the general idea.

The +X axis is located at the point in the sky where sun would be when spring begins (approximately on March 21st).
Such point is known as Vernal point.
We might imagine a line that goes from Earth to the Sun in that particular moment.
The direction of such line would be the point where spring begins and that's where +X axis is pointing.

Such +X axis moves in time, but it moves very slow.
The motion of such point throught zodiac constellations has been used by astrologers to define an era.
Just imagine how long it takes to pass from one era to another.

Right now this +X axis point is passing from the Pisces constellation to the Aquarius.
This is how the sun would look when it passes that point.

So we would be passing from the era of Pisces to the era of Aquarius.
The boundary between constellations is unclear, so we don't know exactly if we already passed from one era to another.
As we change era, the X axis would move in the sky.

In the following picture the starboard side of the craft is pointing to +X axis in the sky.
+X axis is located along the blue line.
The blue line is the ecliptic, the imaginary line where the sun passes in the sky as Earth goes around the sun.

So as you can imagine, the axes will be oriented as shown.
Since Earth is inclined from the ecliptic about 20 degrees, north and Y axis will not bealigned, but we may think that +Y axis and north are heading to the same general direction.

The +Z axis points somewhere between the Taurus and Gemini constellation.

Since we have coordinates referred to sideral coordinates, it is a bit hard to place your craft over a certain place on Earth, because Earth is rotating and it is also going around the sun.
Also placing a craft over a certain coordinate on another planet may be a bit difficult if we try a mathematical approach.
But there is an alternate method to do that in Orbiter.
We will cover it later.

Having an idea of the real distance between your craft and the center of the Earth becomes a bit hard when you have coordinates in all 3 axes, so we use simple math.
To know the distance D between the planet and your craft we wil use the following formula.

D = SQRT( X^2 + Y^2 + Z^2 )

This distance D will appear in the Orbit MFD as "Rad" (radius).

Syntax:

RPOS <X> <Y> <Z>

Example:

RPOS -2103499.87 767771.95 -173.86

RPOS 7000000.0 0.0 0.0
This craft is located at 7000 km in the +X axis from the center of Earth, so the ship altitude above the surface of Earth will be 629 km.
The origin is the center of the Earth, or if it is orbiting another planet, the origin would be the center of such planet.
If MJD is set for the beginning of spring and your craft is orbiting Earth, then Earth, Sun and your craft would be aligned along the +X axis in this example.

RPOS FOR A GIVEN LATITUDE, LONGITUDE AND MJD

If you want to place a craft over a certain place on Earth at a given MJD, you need to do the following:

Create a scenario with the desired MJD and the craft landed on the desired latitude and longitude, using the POS parameter.
Make sure your craft has powerful enough hover engines to make it take off (the standard Delta Glider is not able to take off vertically from Earth).
Run Orbiter and load your current scenario, and make your craft to take off vertically.
Once it just left the ground (a few meters above the ground), pause the game and get the current altitude.
Exit Orbiter.
Get the current scenario RPOS coordinates.
Using Notepad, open the planet CFG file (i.e. Earth.cfg) and look for a parameter called "Size".
Determine what is the desired altitude above the planet surface you want (i.e. 300 km above sea level).
Use the following formula:

X = (Desired Altitude + Size) * X axis current scenario RPOS / (Current altitude + Size)
Y = (Desired Altitude + Size) * Y axis current scenario RPOS / (Current altitude + Size)
Z = (Desired Altitude + Size) * Z axis current scenario RPOS / (Current altitude + Size)

You may use the RPOS/MJD calculator that is included in this tutorial.
It uses the formulas stated above.

Example:

You have a Shuttle A landed on landing pad 1 on Brighton Beach, MJD 51982.6695.

We want to put the craft at 100 meters above the ground, just over that point.
Doing the math to calculate RPOS for a given altitude, latitude and longitude for a certain MJD may be quite a headache, so we put the craft landed on that latitude, longitude and MJD.

The scenario you will build will have this.

SH-01:ShuttleA
STATUS Landed Moon
BASE Brighton Beach:1
POS -33.4375000 41.1184067
HEADING 0.00
PRPLEVEL 0:1.000 1:1.000
NAVFREQ 0 0
XPDR 0
PODANGLE 0.0000 0.0000
DOCKSTATE 0 0.0000
AIRLOCK 0 0.0000
GEAR 0 0.0000
PAYLOAD MASS 1.6 0
END

When you take off from the ground, pause the game.
In this case you reached an altitude of 5.29 meters when pausing.
Take note of your current altitude before exiting the scenario.
Your current altitude is 5.29 meters above the ground.

Your current state scenario now has this.

SH-01:ShuttleA
STATUS Orbiting Moon
RPOS 1204771.63 1128727.64 543287.81
RVEL 0.254 1.430 3.936
AROT 107.32 37.24 119.46
PRPLEVEL 0:1.000 1:1.000
THLEVEL 2:0.165 3:0.165
NAVFREQ 0 0
XPDR 0
PODANGLE 1.5708 1.5708
DOCKSTATE 0 0.0000
AIRLOCK 0 0.0000
GEAR 0 0.0000
PAYLOAD MASS 1.6 0
END

Since we are on the moon, we will open Moon.cfg using notepad and we will look for the size parameter

; === Physical Parameters ===
Mass = 7.347664e+22
Size = 1.738e6 ; mean radius
SidRotPeriod = 2360591.597 ; = 27.321662 days
SidRotOffset = 0.75049 ; rotation offset at J2000.0
Obliquity = 0.02692024985275 ; rad(1.5424167)
LAN = 0 ; ascending node of equator - CHECK!

Your desired altitude is 100 meters above the surface, above landing pad 01 at Brighton Beach.

So we have the following data

MJD = 51982.6695 (from current state scenario)

Current altitude = 5.29 (from screen once game was paused)
Desired altitude = 100
X axis current scenario RPOS = 1204771.63 (from current state scenario)
Y axis current scenario RPOS = 1128727.64 (from current state scenario)
Z axis current scenario RPOS = 543287.81 (from current state scenario)
Size = 1.738e6 (from the planet cfg file)

Now let's use the formulas or the RPOS/MJD calculator that is included in this tutorial:

X = 1204837.28222887
Y = 1128789.14832532
Z = 543317.415657003

The scenario we will build, in which we put a craft at 100 meters over pad 01 at Brighton Beach, will have the following RPOS parameter.

RPOS 1204837.28 1128789.14 543317.41

Notice that if you don't know the latitude and longitude of a certain base, you may get it from the planet CFG file.
For example, if you edit Moon.cfg you will find

Brighton Beach:Tower: -33.4375 +41.125 120

Perhaps you may not know the exact location of your landing pad, but at least you know where the base is.
Don't forget to include the MJD parameter in your scenario, because a different MJD will make your craft to be flying over a different location.

Notice that you may find the radius of each planet in the Orbiter.pdf manual, page 108. Unfortunately planet moons radius are not listed there.

FINDING LATITUDE AND LONGITUDE OF A CERTAIN POINT OF A PLANET

Let's guess you want to find the latitude and longitude of a certain point of a certain planet.
Let's guess we want to find where

Press CTRL F1
Press the "+" next to "Sun"
Click on the planet you wish
Press the "Apply" button
Zoom in using the mouse wheel
Move the planet until the point on that planet you wish to locate is in the center of the Orbiter screen/window.
Press the "Ground" button
Select the planet in the first dropdown list of "Ground observer location".
Press the "Current" button. The first 2 numbers you will see will be longitude and latitude.

RVEL

Indicates the relative velocity in meters per second for a craft, measured from the center of the planet in the 3 axes.
Notice that it uses the same sideral axis system used by RPOS.
It is used for ships that are orbiting a planet.

This is how it looks.
The ship is located at a certain point in orbit (RPOS) and we are travelling with a certain velocity (RVEL).
We may not want to have RPOS and RVEL vectors (they appear as arrows in the diagram) aligned, for we would be either going up vertical or falling down vertically.

In terms of axis coordinates it looks like this.

We will use the same axis reference system we used for RPOS.

As you may notice, RVEL is always tangential to your orbit.

Since Earth is inclined, north and Y axis are not aligned, but we may think that +Y axis and north are heading to the same general direction.

Notice that once you start moving your craft, Orbiter will consider it as it's orbiting the planet.
So even if you are not moving really fast when taking off, it will show a very "high" speed.
That's because of Earth rotation, you are rotating with Earth and you'd be moving around the center of Earth at a certain speed.

The velocity V of your craft relative to the center of the planet you are orbiting, can be calculated as

V = SQRT( X^2 + Y^2 + Z^2 )

This velocity V will appear in the Orbit MFD as "Vel".

When you try to build an orbit, specially a circular one, you will do it by making a combination of RPOS and RVEL.
Notice that RPOS and RVEL vectors must be closer to 90 between each other if you want to make an orbit.
If RPOS and RVEL are aligned, you will be either closing or getting away from the planet and you'd be having a ballistic trajectory, not an orbit.

We might define an orbit using RPOS and RVEL, or we might use a parameter called ELEMENTS.

You also may want your craft not to be in orbit around the planet, so it travels faster than planetary escape velocity.
You may find escape velocity data for each planet in the Orbit.pdf manual, page 108.

Syntax

RVEL <X> <Y> <Z>

Example:

In these examples our craft is placed along the +Z axis
When orbit MFD is displaying the ecliptic plane (Prj ECL), +X axis points to the right and +Z axis to the top.

RVEL 7500 0 0
Our craft is heading west, given ship's current RPOS coordinates.

RVEL 0 7500 0
Our craft is heading north, it's having a polar orbit.

RVEL 0 0 7500
Since our craft is located along the +Z axis, and velocity is aligned with RPOS, then we are going perfectly vertical, and we are having a perfectly ballistic trajectory, not an orbit.

RVEL 5303 5303 0
Given our current RPOS, our craft is heading northwest.
As we use the formula to calculate our velocity V, we find that V = 7500 so Vx = 5303 and Vy = 5303 and Vz = 0.

RVEL 0 5303 5303
Our craft is heading north with a ballistic trajectory.
We will crash on the surface of Earth because we don't have the required velocity in the proper direction to achieve orbit.
Our velocity in the Z axis is useless because our ship is located along the Z axis.
As you may notice, the Map MFD looks weird.

RVEL 5303 0 5303
We are heading west , given our current RPOS and we are having a ballistic trajectory.
Our velocity in the Z axis is useless because our ship is located along the Z axis.

AROT

It indicates the attitude (orientation of a craft that is orbiting a planet) around each axis.
It is measured in degrees.
In the diagram the direction of positive angles around each axis is shown.
It uses the same axis reference system that is being used by RPOS and RVEL.

Syntax

AROT <X> <Y> <Z>

Example:

AROT 0.00 0.00 -122.94
AROT 0.00 -45.00 90.00

VROT

It indicates the angular velocity of a craft around each axis for a craft that is orbiting a planet.
It is measured in degrees per second.

Syntax

VROT <X> <Y> <Z>

Example:

VROT 0 0 10

ELEMENTS

It is used as a replacement for RPOS and RVEL, for a craft that is orbiting a planet.

To define elements we need to understand the variables we need to include in the ELEMENTS parameter.

SEMI-MAJOR AXIS

The Semi-Major Axis is half of the longest straight line we can draw inside an ellipse.
Notice that Semi-Major Axis is different than Apoapsis (highest point in the orbit from the center of the planet).
Apoapsis is measured from the center of the planet, and the planet is located at an ellipse focus.

So indeed the Semi-Major Axis should be smaller than Apoapsis radius and bigger than Periapsis radius (lowest point in the orbit from the center of the planet).
In the Orbit MFD it appears as SMa.

If you draw lines from both focus to a given point of the ellipse, the sum of both distances (a+b in the diagram) will be always the same.
An interesting way to draw an ellipse is to put a nail in each focus, and use a piece of thread and a pencil to draw the ellipse.

ECCENTRICITY

The eccentricity (it appears as Ecc in Orbit MFD) describes the shape of the orbit.

Ecc = 0: Circle .Both focus are located at the same point.
0 < Ecc < 1: Ellipse. It has the two focus located at different positions, the center of the planet you are orbiting is located in one of them.
Ecc = 1: Parabolic shape. One of the focus points is located at an "infinite" or "too big" distance from the planet. The Apoapsis variable is gone in the Orbit MFD. The craft would pass through the periapsis once only and then it would go into deep space.
Ecc > 1: Hyperbolic shape. One of the focus points is located "beyond" infinite. The orbit shape looks more open than parabolic shape. When you do some planetary transfers, you are likely to have parabolic or hyperbolic orbits, and your apoapsis goes beyond the Sphere of Influence (SOI) of the planet, so your craft may not be able to return to the planet once it passed periapsis.

If you have SemiMajor Axis (SMa) and SemiMinor axis (SMi), you can calculate eccentricity.

Ecc = SMa-SMi/SMa

And also you can calculate the periapsis radius (PeR) of your orbit

PeR = SMa - sqr(SMa^2 - SMi^2)

If PeR is smaller than the planet radius, then the orbit has impact point on the planet surface.

INCLINATION

Inclination is the inclination of the orbit, relative to the ecliptic, not to the planet equator.
The ecliptic is the plane of the orbit of Earth around the sun (or also you may think of it as the plane of the "apparent orbit of the sun around Earth").
Since the planet is inclined (such planet inclination is known as "oblicuity of the ecliptic"), you won't see your craft having an equatorial orbit with an inclination of 0 degrees.
Notice that a 90 degrees inclination is not a polar orbit either because planet is inclined.

If you want to know the obliquity of the ecliptic for each planet, see Orbiter.pdf manual, page 109.

LONGITUDE OF ASCENDING NODE

The longitude of the ascending node (LAN) is the angle between Vernal point (X axis) and the ascending node.

The line between the two nodes represent the intersection of ecliptic and vessel orbit planes.

LONGITUDE OF PERIAPSIS

The longitude of periapsis (LPe) is the angle between Vernal point (X axis) and the periapsis point.

MEAN LONGITUDE

The mean longitude at reference date (MnL) is the angle between Vernal point (X axis) and the craft position at reference date.

Mean longitude will only be zero in this case if the argument of periapsis is zero as well (because the periapsis then coincides with the node) or if the eccentricity is zero (because true and mean longitude are then equivalent).

Ellipses have two focus points.
As you may notice in the diagram, one focus in in the center of the planet and the other one is not.
Mean longitude is measured from the other focus using the Vernal point as reference too.

ELEMENTS AND HOW THEY LOOK IN ORBIT MFD

Ok, by now you are probably very confused, so let's see how each variable would look in Orbit MFD.

Notice that eccentricity = 0 means that you have a circle, while eccentricity = 0.5 gives you an ellipse.

LAN (Longitude of Ascending node) and LPe (Longitude of periapsis) are measured from the center of the planet.

Mean longitude (MnL) is not measured from the center of the planet when the orbit is an ellipse.
MnL is the position of the craft at a certain moment called "reference date".
When you turn a circle into an ellipse, the center splits in two focus points and things become a bit more complicated.
One of the focus point will be at the center of the planet (Focus 1), and MnL is measured from the other focus point (Focus 2).
Also notice that LAN, LPe and MnL are angles, but the point of reference to measure those angles is different for MnL.

In the following example we changed LPe and the orbits becomes inclined.
But the angle directions don´t change, only the points of reference (Focus 1 and 2) are moved.
Notice what happened with the angles measured from focus 1 and 2.
Notice how MnL is measured from Focus 2, while LAN and LPe are measured from Focus 1 located at the center of the planet.
We moved MnL to 270 which is measured from focus 2.

If the current date is different than the reference date, the object position will change according to the orbit elements, so the craft will not be at MnL.
So it means that Orbiter will calculate where the craft will be at the current date, given that reference date.

Notice that the current diagrams represent a non inclined orbit seen from above.
If we incline the orbit, it would look rotated, and the axis of rotation would be the line connecting the nodes (defined by LAN).

Notice that the planet will rotate, while our frame of reference is fixed, so we have currently no way to know where the object is relative to planet landmarks, using just wild guess.
To find that out we would need some math.

There is a way to convert RPOS and RVEL to ELEMENTS using vector operations, but it will require you to know about vector math.
Such operations are described in the Orbiter.pdf manual, page 110.
RPOS and RVEL are measured in that fixed frame of reference we are using, so the same RPOS and RVEL in different dates would be located on different places over the planet due to rotation.

Syntax

ELEMENTS <semi-major axis> <eccentricity> <inclination> <longitude of ascending node> <longitude of periapsis> <mean longitude at reference date> <reference date in MJD format>

<Semi-major axis> is measured in meters.
<Inclination>, <longitude of ascending node>, <longitude of periapsis>, and <mean longitude at reference date>, are measured in degrees.

Example:

Date MJD 51982.7319467651
...
ELEMENTS 7500000 0.01 0 0 90 45 51982.7319467651

In this case we have:

Semi-major axis (SMa) = 7500 km (from the center of the planet).
Eccentricity (Ecc) = 0.01 (an ellipse that looks almost like a circle).
Inclination (Inc) = 0 (ship orbit plane is aligned with ecliptic plane).
Longitude of ascending node (LAN) = 0 (X axis is to the right on the Orbit MFD screen, and LAN is aligned with X axis).
Longitude of periapsis = 90 (It is at the top of the Orbit MFD screen).
Mean longitude at reference date = 45 (notice that current date and reference date are the same in this example, so it is reflected in the MnL variable).

Notice that even if inclination is 0, you don't have an equatorial orbit, because you are using sideral coordinates.
Notice that Orbit MFD is displaying the ecliptic plane because our ship plane (SHP) is aligned with ecliptic plane.

Date MJD 51982.7319467651
...
ELEMENTS 75000000 0.5 0 0 90 0 51982.7319467651

In this case we have:

Semi-major axis (SMa) = 75 000 km (from the center of the planet).
Eccentricity (Ecc) = 0.5 (an ellipse that looks almost like a circle).
Mean longitude at reference date = 0

Notice that the rest of the parameters are just like the ones in the previous example.
The shape of the orbit changed, as well as the distances involved.

PRPLEVEL

Indicates the level of propellant (fuel) for the craft.
A craft may have several tanks.
Tank number 0 is the main tank and any other would be auxiliary tanks.
Don't forget to add PRPLEVEL parameter, or your craft won't have any fuel.

Syntax

PRPLEVEL <Tank ID>:<Propellant level> <Tank ID>:<Propellant level> ...

<Tank ID> are integer numbers starting from 0.
<Propellant level> ranges from 0 (empty) to 1 (full).

Example:

PRPLEVEL 0:0.995 1:1.000

NAVFREQ

It refers to the nav receiver stack.
Each number represents a NAV frequency in the COM/NAV MFD.

The frequency is not expressed explicitly.
It is shown like a frequency ID.

Frequency = 0.05 * FrequencyID + 108

It means that

FrequencyID = 20 * Frequency - 2160

The NAVFREQ may have several Frequency IDS and it will tell Orbiter how many frequencies you may set in the nav receiver stack.
Frequency range goes from 108.00 to 139.95, so frequency ID range goes from 0 to 639.

For example, if you want to set a frequency of 113.25KHz, the Frequency ID will be 105.

It is recommended that you define at least 2 nav frequencies.
You will need one for the VOR and another for runway or landing pad.
You may need them when docking too.
One to designate you target using target XPDR, and another for docking.

Syntax:

NAVFREQ <Frequency ID> <Frequency ID> <Frequency ID> <Frequency ID>

Example:

NAVFREQ 0 0 0 0

NAVFREQ 94 524 84 114

NAVFREQ 0 0

Notice that the NAVFREQ parameter uses Frequency IDs, while MFD displays the frequencies.
Notice that if you define 4 frequency IDs, you will see 4 NAVs in the COM/NAV MFD.

XPDR

It indicates the transponder transmitter frequency, using a frequency ID, just like the one used for the NAVFREQ parameter.
This transponder frequency will identify each craft.
It is useful to spot and target craft in the distance.

Will use the same formula to calculate Frequency ID.

FrequencyID = 20 * Frequency - 2160

Frequency range goes from 108.00 to 139.95, so frequency ID range goes from 0 to 639.

Notice that this frequency will appear as "XPDR Transmitter" in the COM/NAV MFD.

There is no default XPDR frequency, so if you don't add XPDR parameter, your craft won't have an XPDR frequency and you will not be able to target it.

Syntax

XPDR <Frequency ID>

Examples:

XPDR 0

XPDR 482

XPDR 494

IDS

It will specify the docking port frequencies.
IDS stands for Instrument Docking System.
Frequecy IDs are calculated in the same way they are calculated for NAVFREQ and XPDR.

Will use the same formula to calculate Frequency ID.

FrequencyID = 20 * Frequency - 2160

Frequency range goes from 108.00 to 139.95, so frequency ID range goes from 0 to 639.

There is no default IDS frequency for each docking port.
If you don't add an IDS parameter, the craft won't have IDS frequencies for docking ports, so you'd have to dock relying on visual only.

Unlike XPDR, IDS frequencies only work when you are in the proximity of the target.

Syntax

IDS <Port ID>:<Frequency ID> <Length> <Port ID>:<Frequency ID> <Length> ...

The first <Port ID> will always be 0, the second should be 1 and so on.
<Length> specifies the length in meters of the approaching path to the docking port.

Examples:

IDS 0:560 100 1:564 100
Notice that this craft has 2 docking ports (port ID 0 and 1).

IDS 0:540 100 1:542 100 2:544 100
This craft has 3 docking ports (port ID 0, 1 and 2).

DOCKINFO

There are 2 ways to dock ships.
One is to put ships with their docking ports next to another, with the ships properly oriented so they are docked.
It is a bit hard to do it that way.

The other way is to use the DOCKINFO parameter.
That's the easier way.

You just will use this with the craft that will serve as core of a superstructure composed by many ships.
Notice that such craft must be listed before the rest of the docked ships.

Syntax

DOCKINFO <Docking port 1>:<Docking port 2>,<Name of docked vessel>

<Docking port 1> belongs to the current craft which will serve as core of the superstructure.
<Docking port 2> belongs to the craft that is attached.
<Name of docked vessel> is the <Name> of the attached craft.

Example:

GL-01:DeltaGlider
STATUS Orbiting Earth
RPOS 100.0 0.0 0.0
RVEL 7500.0 0.0 0.0
RCSMODE 2
PRPLEVEL 0:0.995 1:1.000
NAVFREQ 94 524 84 114
XPDR 494
IDS 0:561 100
GEAR 0 0.5000
NOSECONE 1 1
PSNGR 3
DOCKINFO 0:0,GL-02
END
GL-02:DeltaGlider
STATUS Orbiting Earth
PRPLEVEL 0:1.000 1:1.000
NAVFREQ 0 0 0 0
XPDR 0
NOSECONE 0 0.0000
GEAR 1 1.0000
AIRLOCK 0 0.0000
RCSMODE 1
NOSECONE 1 1
END

Notice that the DOCKINFO parameter is used in the first ship (GL-01) which serves as the core of the superstructure.
The DOCKINFO parameter refers to a craft that is listed below the core craft (GL-02), which is attached to the core.
Notice also that the attached craft (GL-02) doesn't have RPOS, RVEL, AROT and VROT parameters, only the core craft.
Since both craft have 1 docking port, both have a "0" which is the first docking port identifier.
A craft with more than one docking port may have port identifiers 0, 1, 2 and so on.

WARNING: If you dock a Delta Glider III, make the craft to have it's nose cone open, or it will show nose cone damaged.

GEAR

It indicates the landing gear status.
If you don't include GEAR parameter, your craft will have a retracted gear.

Syntax

GEAR <Action> <Gear position>

<Gear position> ranges from 0 to 1 where 0 is retracted and 1 is deployed.
<Action> indicates the action that is being performed:

1 Fixed gear position
2 Retracting landing gear
3 Deploying landing gear

Example:

GEAR 2 0.8101
GEAR 1 1.0000

AIRLOCK

It indicates the airlock outer door status.
If you don't include AIRLOCK parameter, the outer door will be closed.

Syntax

AIRLOCK <Action> <Door position>

<Door position> ranges from 0 to 1 where 0 is closed and 1 is open.
<Action> indicates the action that is being performed:

1 Fixed door position
2 Closing door
3 Opening door

Example:

AIRLOCK 1 1.0000

DELTA GLIDER SPECIFIC PARAMETERS

These are parameters that are specific for a standard Delta Glider.
If you have downloaded the Delta Glider III by Dan Steph, you will notice that Delta Glider III specific parameters are different.
Even if they look similar, they are completely different.

NOSECONE

It indicated the nose cone status.
If you don't include NOSECONE parameter, your craft will have its nose cone closed.

Syntax

NOSECONE <Action> <Nose cone position>

<Nose cone position> ranges from 0 to 1 where 0 is closed and 1 is open.
<Action> indicates the action that is being performed:

1 Fixed nose cone position
2 Closing nose cone
3 Opening nose cone

Example:

NOSECONE 0 0.0000

RCSMODE

It indicates the status of the RCS/OMS system.

Syntax

RCSMODE <Mode>

Mode 0 : OFF (Disengaged)
Mode 1: ROT (Rotation)
Mode 2: LIN (Traslation)

Example:

RCSMODE 0
RCSMODE 1

PSNGR

It indicates what passenger seats are occupied.
There are only 4 passenger seats.
If you don't include PSNGR parameter, your craft won't have any passenger.

Syntax

PSNGR <Passenger seat> <Passenger seat> <Passenger seat> <Passenger seat>

Example:

PSNGR 2 3 4
PSNGR 1 2 3 4

SHUTTLE-A SPECIFIC PARAMETERS

These are parameters that are specific for Shuttle A.

If you have downloaded the Shuttle-A2 add on, you also will notice that Shuttle-A2 has different parameters.

PODANGLE

It will indicate the position of the pods.

Syntax

PODANGLE <Pod angle> <Pod angle>

<Pod angle> values are

Retrothruster: 0.0000
Hover: 1.5708
Forward: 3.1416

Example:

PODANGLE 0.0000 0.0000

DOCKSTATE

It refers to the door that covers the docking port.
It is more or less the equivalent to the nose cone of a Delta Glider.

Syntax

DOCKSTATE <Action> <Door position>

<Door position> ranges from 0 to 1 where 0 is closed and 1 is open.
<Action> indicates the action that is being performed:

1 Fixed door position
2 Closing door
3 Opening door

Example:

DOCKSTATE 1 1.0000

PAYLOAD MASS

It will add some mass to your craft and will specify the position of the "Safe" switch in your upper control panel.

Syntax

PAYLOAD MASS <Mass> <Safe switch position>

<Safe switch position> values are 0 for closed and 1 for open.

Example:

PAYLOAD MASS 0.0 1

SOME NOTES ON CREATING SCENARIOS

Every vessel in Orbiter may use different parameters.
However we have covered the most commonly used here.

ATTACHING VESSELS

Orbiter uses 3 types of attachments:

Docking ports: These are ports that are supposed to have doors so people go from one ship to another.
Attachment points: These are points where a vessel is attached to another, like a freighter and it's payload..
Grapple points: These points are useful to grab an object with a robotic arm.

Those attachment points are sometimes defined in a .cfg file and sometimes they are defined internally by the vessel DLL module.
The content of a cfg file may look like this

; === Configuration file for Leonardo mplm ===

Meshname = Leonardo_mplm
Mass = 1.8e3
Size = 6.0
Inertia = 7.7 7.7 2.3
EnableFocus = TRUE
EnableXPDR = TRUE
XPDR = 477

; === Docking ports ===
BEGIN_DOCKLIST
0.07 -0.2 -3.2 0 0 -1 0 1 0
END_DOCKLIST

; === Attachment specs ===
BEGIN_ATTACHMENT
P 0 -0.4 0 0 -1 0 0 0 1 XS
P 0.1 2.0 0.1 0 1 0 0 0 -1 GS
END_ATTACHMENT

The DOCKLIST section contains a list of the docking points.

Syntax

<PosX> <PosY> <PosZ> <DirX> <DirY> <DirZ> <RotX> <RotY> <RotZ>

Example:

0.07 -0.2 -3.2 0 0 -1 0 1 0

In this example, the red numbers insicate the position of the docking port in vessel mesh coordinates.
The blue numbers are the DIR vector that must be perpendicular to the docking port, and the ROT vector that indicates "this side up" of the docking port.
Notice that the angle between DIR and ROT must be 90 degrees and DIR and ROT vectors must have a length of 1.
If you use rotated DIR or ROT vectors you may need to use some math to calculate the components of your vectors

The ATTACHMENT SECTION works in a similar way, but it adds an attachment type.

Syntax

<PosX> <PosY> <PosZ> <DirX> <DirY> <DirZ> <RotX> <RotY> <RotZ> <Attachment type>

<Attachment type> GS for grapple points and XS for attachment points

Different addons use different ways to attach objects.
Some addons use a PAYLOAD parameter, some others may use the ATTACHED parameter.
Notice that payload objects stated in the PAYLOAD parameter don´t have to be added to the scenario as they will be created upon detaching.
ATTACHED instead requires the other vessel to be included in the scenario.

ATTACHED can be used with any vessel if the vessels have attachment points.
It is defined by the Orbiter core.

PAYLOAD can only be used if the vessel DLL module allows to use it.
It is an addon specific parameter.
It is usually present in some addons called "CVEL".

Syntax

PAYLOAD <payloadname> <mesh> <class> <x> <y> <z> <mass> <xrot> <fuellevel>

<payloadname> custom name of the payload
<mesh> 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> name of the payload's classname
<x> <y> <z> floating point offsets from the launching vessel's reference point (normally the centre of mass) that the mesh should be drawn
<mass> mass of the vessel that is to be created, INCLUDING fuel load.
<xrot> is an obsolete number, simply put a zero (0) here.
<fuellevel> is the fuel level of the payloads that will be created.

(Explanation taken from Users' guide to the GENERIC PAYLOAD DESCRIPTION SYSTEM (GPDS) by D Henderson)

Example:

PAYLOAD probe1 probe probe 0 0 0 15000 0 1

It will create a ship that will appear named as "probe1" in the simulator. It uses a mesh called "probe.msh" and its class is "probe".
It has an offset of (0,0,0) and a mass of 15000, as well as a fuel level of 1 (100% full tank).

Syntax

ATTACHED <Attachment point 1>:<Attachment point 2>,<Name of attached vessel>

It is used just like the DOCKINFO parameter, but it uses attachment points instead of docking ports.

Example:

ATTACHED 0:5,Buran-T
ATTACHED 1:3,Vessel1

This will attach the current ships attachment point 0 to Buran-T's attachment point 5.
Also this will attach the current ships attachment point 1 to Vessel1's attachment point 3.

If you want to view where attachments points are, you may download a software called Mesh Wizard at www.orbithangar.com