Vessel Tutorial 2

Go back to Vessel Tutorial 1

Take out the Trash

Now it's time to clear out all the old ShuttlePB things that we don't need any more. Remember, if you are making something other than Surveyor, you may want to adapt this stuff rather than trashing it.

Aerodynamic Model

Surveyor is a pure spacecraft, so it doesn't need an aerodynamic model. I suppose the purists out there would insist on at least giving it drag in case it fell into the Earth's atmosphere after a bad launch, but I don't care about it.

Completely get rid of this block of code:

// Calculate lift coefficient [Cl] as a function of aoa (angle of attack) over -Pi ... Pi
// Implemented here as a piecewise linear function
double LiftCoeff (double aoa)
{
  const int nlift = 9;
  static const double AOA[nlift] = {-180*RAD,-60*RAD,-30*RAD,-1*RAD,15*RAD,20*RAD,25*RAD,60*RAD,180*RAD};
  static const double CL[nlift]  = {       0,      0,   -0.1,     0,   0.2,  0.25,   0.2,     0,      0};
  static const double SCL[nlift] = {(CL[1]-CL[0])/(AOA[1]-AOA[0]), (CL[2]-CL[1])/(AOA[2]-AOA[1]),
                                  (CL[3]-CL[2])/(AOA[3]-AOA[2]), (CL[4]-CL[3])/(AOA[4]-AOA[3]),
                    (CL[5]-CL[4])/(AOA[5]-AOA[4]), (CL[6]-CL[5])/(AOA[6]-AOA[5]),
                    (CL[7]-CL[6])/(AOA[7]-AOA[6]), (CL[8]-CL[7])/(AOA[8]-AOA[7])};
  for (int i = 0; i < nlift-1 && AOA[i+1] < aoa; i++);
  return CL[i] + (aoa-AOA[i])*SCL[i];
}

This code was used to provide a lift model for the ShuttlePB. It appears to make ShuttlePB a lifting body with a small amount of lift.

Now, go down to Surveyor::clbkSetClassCaps and remove the following code sections:

  SetCW (0.3, 0.3, 0.6, 0.9);
  SetWingAspect (0.7);
  SetWingEffectiveness (2.5);
  SetCrossSections (_V(10.5,15.0,5.8));
  SetRotDrag (_V(0.6,0.6,0.35));
  if (GetFlightModel() >= 1) {
    SetPitchMomentScale (1e-4);
    SetBankMomentScale (1e-4);
  }

  SetTrimScale (0.05);

  SetLiftCoeffFunc (LiftCoeff);

This removes the rest of the aerodynamic model. It also removes the aerodynamic trim capability. Compile and test, in case you forgot.

Hover engine

Surveyor uses its main engines to hover, and doesn't have a hover engine as such. So let's toss it. Get rid of this code:

  th_hover = CreateThruster (_V(0,-1.5,0), _V(0,1,0), PB_MAXHOVERTH, ph_vernier, PB_ISP);
  CreateThrusterGroup (&th_hover, 1, THGROUP_HOVER);
  AddExhaust (th_hover, 8, 1, _V(0,-1.5,1), _V(0,-1,0));
  AddExhaust (th_hover, 8, 1, _V(0,-1.5,-1), _V(0,-1,0));

Compile and test.

Fancy Exhaust

The ShuttlePB defines all sorts of fancy particle streams, which only are used in atmospheric flight. Since we are not in an atmosphere, let's ditch these. Your spacecraft may want to customize these instead. Get rid of these code blocks:

  // ***************** thruster definitions *******************

  PARTICLESTREAMSPEC contrail_main = {
    0, 5.0, 16, 200, 0.15, 1.0, 5, 3.0, PARTICLESTREAMSPEC::DIFFUSE,
    PARTICLESTREAMSPEC::LVL_PSQRT, 0, 2,
    PARTICLESTREAMSPEC::ATM_PLOG, 1e-4, 1
  };
  PARTICLESTREAMSPEC contrail_hover = {
    0, 5.0, 8, 200, 0.15, 1.0, 5, 3.0, PARTICLESTREAMSPEC::DIFFUSE,
    PARTICLESTREAMSPEC::LVL_PSQRT, 0, 2,
    PARTICLESTREAMSPEC::ATM_PLOG, 1e-4, 1
  };
  PARTICLESTREAMSPEC exhaust_main = {
    0, 2.0, 20, 200, 0.05, 0.1, 8, 1.0, PARTICLESTREAMSPEC::EMISSIVE,
    PARTICLESTREAMSPEC::LVL_SQRT, 0, 1,
    PARTICLESTREAMSPEC::ATM_PLOG, 1e-5, 0.1
  };
  PARTICLESTREAMSPEC exhaust_hover = {
    0, 2.0, 10, 200, 0.05, 0.05, 8, 1.0, PARTICLESTREAMSPEC::EMISSIVE,
    PARTICLESTREAMSPEC::LVL_SQRT, 0, 1,
    PARTICLESTREAMSPEC::ATM_PLOG, 1e-5, 0.1
  };

  AddExhaustStream (th_hover, _V(0,-3, 1), &contrail_hover);
  AddExhaustStream (th_hover, _V(0,-3,-1), &contrail_hover);
  AddExhaustStream (th_vernier, _V(0,0.3,-10), &contrail_main);
  AddExhaustStream (th_hover, _V(0,-2, 1), &exhaust_hover);
  AddExhaustStream (th_hover, _V(0,-2,-1), &exhaust_hover);
  AddExhaustStream (th_vernier, _V(0,0.3,-5), &exhaust_main);

Compile and Test.

Docking Port

Surveyor has no docking point, so delete the definition of it:

  SetDockParams (_V(0,1.3,-1), _V(0,1,0), _V(0,0,-1));

Translation RCS

Many modern and historical spacecraft have only limited translational capability. For example, the Cassini orbiter only has translation forward. Surveyor had no translation RCS at all. Instead it relies on the vernier engines. So let's ditch the translation thruster groups. We will leave the thrusters, but just remove the capability to use them as translation thrusters, while retaining them as rotation thrusters. Cut the following code chunks:

  th_group[0] = th_rcs[0];
  th_group[1] = th_rcs[4];
  th_group[2] = th_rcs[2];
  th_group[3] = th_rcs[6];
  CreateThrusterGroup (th_group, 4, THGROUP_ATT_UP);

  th_group[0] = th_rcs[1];
  th_group[1] = th_rcs[5];
  th_group[2] = th_rcs[3];
  th_group[3] = th_rcs[7];
  CreateThrusterGroup (th_group, 4, THGROUP_ATT_DOWN);

  th_group[0] = th_rcs[8];
  th_group[1] = th_rcs[10];
  CreateThrusterGroup (th_group, 2, THGROUP_ATT_LEFT);

  th_group[0] = th_rcs[9];
  th_group[1] = th_rcs[11];
  CreateThrusterGroup (th_group, 2, THGROUP_ATT_RIGHT);

  CreateThrusterGroup (th_rcs+12, 1, THGROUP_ATT_FORWARD);
  CreateThrusterGroup (th_rcs+13, 1, THGROUP_ATT_BACK);

Compile and test. Now when you fly, you can switch to translational engines, but they don't do anything.

Propellant Resources

ShuttlePB had only one fuel tank, filled with hyperthrustium fuel. Surveyor has three completely separate fuel systems:

1. Vernier fuel and oxidizer
2. RCS nitrogen
3. Main retro solid fuel

Notice that even though in reality the vernier fuel and oxidizer need to be kept in separate tanks (they are hypergolic), in Orbiter, they are both treated as "propellant" and are both kept in the same propellant resource. This is because each engine can only use one propellant resource at a time.

First, let's recycle the ShuttlePB fuel tank as the vernier propellant tanks. We already did this above when we replaced hpr with ph_vernier. We will, however, change the mass of propellant in it. Find the line which defines ph_vernier, and change it like this:

  PROPELLANT_HANDLE ph_vernier = CreatePropellantResource (VERNIER_PROP_MASS);

Next, create the RCS propellant resource. Whenever there are multiple propellant resources, the order in which they are created is important. The first one created is referenced as prop resource zero, the next one is one, and so on. This order matters because when the scenario is loaded or saved, the propellant levels in each tank are referenced by this number. So, add the following line below the line which creates the vernier prop resource:

  PROPELLANT_HANDLE ph_rcs     = CreatePropellantResource(RCS_PROP_MASS);

Add the constants which define the RCS to near the top of the file:

const double RCS_PROP_MASS=2;
const double RCS_ISP = 630.0;
const double RCS_THRUST = 0.25;
const double RCS_RAD = 1;
const double RCS_STA = -0.5;
const double RCS_SPACE = 0.1;

We will worry about the retro propellant when we define the retro engine.

In order to put fuel into the RCS fuel tank, edit the PRPLEVEL line for Surveyor in your scenario file:

  PRPLEVEL 0:1.000 1:1.000 2:1.000  

This fills resource zero, the vernier tanks, and resource one, the RCS tank. It also fills resource 2, the main retro solid fuel grain, but we haven't created this yet. No worries, since Orbiter ignores propellant resources which we don't have.

Compile and test.

Surveyor RCS

Surveyor carried a number of cold-gas thrusters for reaction control. These just used high-pressure nitrogen. These engines are weak and inefficient, but extremely simple and safe. No flammable fuel is needed for them, only a high-pressure gas tank.

It is a fundamental principle of attitude control that you need a minimum of two thrusters for each control direction. This is so that the linear forces of each thruster cancel out and only the torques remain. For a total of three axes (pitch, yaw, roll), and two control directions for each (plus and minus), you would seem to need 2*3*2=12 thrusters at a minimum for rotational RCS.

Surveyor only has six.

This is because the designers of Surveyor were primarily concerned with simplicity on board the spacecraft. They put on one thruster for plus roll and one for minus roll. These engines were installed up on Leg 1, pointing to +X and -X (left and right). Using one of these engines creates both a roll torque and a linear force. Burn one of these engines long enough, and you may deflect your landing site or miss the moon completely. Back in the day, the guys on the ground calculating the mid-course correction had to take into account this imbalance of force. This kept with the philosophy of spacecraft simplicity by shifting the complexity to the big, room-sized computers on the ground. Fortunately since the RCS is weak, this force is small. Also, once the spacecraft settles into a particular attitude, one would expect to use about the same amount of + and - control to keep it stable. Thus, the linear forces mostly cancel out anyway.

Surveyor has two thrusters on Leg 2 and two on Leg 3. Both pairs have one member pointing at +Z (forward) and one at -Z (back). These are used to control pitch and yaw. To yaw, one +Z engine on one leg and one -Z engine on the other leg are fired. These are balanced, resulting in a perfect yaw control system. To pitch, either both +Z or both -Z engines are fired. This generates a pitch torque, but also a linear thrust, which again must be accounted for on the ground.

One more thing to remember: The legs are well behind the spacecraft center of mass. Because of this, the roll jets will induce a certain amount of yaw, as well as roll.

So, let's install these thrusters. First, get rid of the old ShuttlePB thrusters:

  th_rcs[ 0] = CreateThruster (_V( 1,0, 3), _V(0, 1,0), PB_MAXRCSTH, ph_vernier, PB_ISP);
  th_rcs[ 1] = CreateThruster (_V( 1,0, 3), _V(0,-1,0), PB_MAXRCSTH, ph_vernier, PB_ISP);
  th_rcs[ 2] = CreateThruster (_V(-1,0, 3), _V(0, 1,0), PB_MAXRCSTH, ph_vernier, PB_ISP);
  th_rcs[ 3] = CreateThruster (_V(-1,0, 3), _V(0,-1,0), PB_MAXRCSTH, ph_vernier, PB_ISP);
  th_rcs[ 4] = CreateThruster (_V( 1,0,-3), _V(0, 1,0), PB_MAXRCSTH, ph_vernier, PB_ISP);
  th_rcs[ 5] = CreateThruster (_V( 1,0,-3), _V(0,-1,0), PB_MAXRCSTH, ph_vernier, PB_ISP);
  th_rcs[ 6] = CreateThruster (_V(-1,0,-3), _V(0, 1,0), PB_MAXRCSTH, ph_vernier, PB_ISP);
  th_rcs[ 7] = CreateThruster (_V(-1,0,-3), _V(0,-1,0), PB_MAXRCSTH, ph_vernier, PB_ISP);
  th_rcs[ 8] = CreateThruster (_V( 1,0, 3), _V(-1,0,0), PB_MAXRCSTH, ph_vernier, PB_ISP);
  th_rcs[ 9] = CreateThruster (_V(-1,0, 3), _V( 1,0,0), PB_MAXRCSTH, ph_vernier, PB_ISP);
  th_rcs[10] = CreateThruster (_V( 1,0,-3), _V(-1,0,0), PB_MAXRCSTH, ph_vernier, PB_ISP);
  th_rcs[11] = CreateThruster (_V(-1,0,-3), _V( 1,0,0), PB_MAXRCSTH, ph_vernier, PB_ISP);
  th_rcs[12] = CreateThruster (_V( 0,0,-3), _V(0,0, 1), PB_MAXRCSTH, ph_vernier, PB_ISP);
  th_rcs[13] = CreateThruster (_V( 0,0, 3), _V(0,0,-1), PB_MAXRCSTH, ph_vernier, PB_ISP);

  th_group[0] = th_rcs[0];
  th_group[1] = th_rcs[2];
  th_group[2] = th_rcs[5];
  th_group[3] = th_rcs[7];
  CreateThrusterGroup (th_group, 4, THGROUP_ATT_PITCHUP);

  th_group[0] = th_rcs[1];
  th_group[1] = th_rcs[3];
  th_group[2] = th_rcs[4];
  th_group[3] = th_rcs[6];
  CreateThrusterGroup (th_group, 4, THGROUP_ATT_PITCHDOWN);

  th_group[0] = th_rcs[0];
  th_group[1] = th_rcs[4];
  th_group[2] = th_rcs[3];
  th_group[3] = th_rcs[7];
  CreateThrusterGroup (th_group, 4, THGROUP_ATT_BANKLEFT);

  th_group[0] = th_rcs[1];
  th_group[1] = th_rcs[5];
  th_group[2] = th_rcs[2];
  th_group[3] = th_rcs[6];
  CreateThrusterGroup (th_group, 4, THGROUP_ATT_BANKRIGHT);

  th_group[0] = th_rcs[8];
  th_group[1] = th_rcs[11];
  CreateThrusterGroup (th_group, 2, THGROUP_ATT_YAWLEFT);

  th_group[0] = th_rcs[9];
  th_group[1] = th_rcs[10];
  CreateThrusterGroup (th_group, 2, THGROUP_ATT_YAWRIGHT);

Now, add the following code in its place:

  //Roll (Leg1) jets
  th_rcs[ 0] = CreateThruster (_V(-RCS_SPACE,RCS_RAD,RCS_STA), _V( 1,0,0), RCS_THRUST, ph_rcs, RCS_ISP);
  th_rcs[ 1] = CreateThruster (_V( RCS_SPACE,RCS_RAD,RCS_STA), _V(-1,0,0), RCS_THRUST, ph_rcs, RCS_ISP);

  //Leg2 jets
  th_rcs[ 2] = CreateThruster (_V( sqrt(3.0)/2*RCS_RAD,-0.5*RCS_RAD,RCS_STA-RCS_SPACE), _V(0, 0, 1), RCS_THRUST, ph_rcs, RCS_ISP);
  th_rcs[ 3] = CreateThruster (_V( sqrt(3.0)/2*RCS_RAD,-0.5*RCS_RAD,RCS_STA+RCS_SPACE), _V(0, 0,-1), RCS_THRUST, ph_rcs, RCS_ISP);

  //Leg3 jets
  th_rcs[ 4] = CreateThruster (_V(-sqrt(3.0)/2*RCS_RAD,-0.5*RCS_RAD,RCS_STA-RCS_SPACE), _V(0, 0, 1), RCS_THRUST, ph_rcs, RCS_ISP);
  th_rcs[ 5] = CreateThruster (_V(-sqrt(3.0)/2*RCS_RAD,-0.5*RCS_RAD,RCS_STA+RCS_SPACE), _V(0, 0,-1), RCS_THRUST, ph_rcs, RCS_ISP);

  th_group[0] = th_rcs[3];
  th_group[1] = th_rcs[5];
  CreateThrusterGroup (th_group, 2, THGROUP_ATT_PITCHDOWN);

  th_group[0] = th_rcs[2];
  th_group[1] = th_rcs[4];
  CreateThrusterGroup (th_group, 2, THGROUP_ATT_PITCHUP);

  th_group[0] = th_rcs[0];
  CreateThrusterGroup (th_group, 1, THGROUP_ATT_BANKRIGHT);

  th_group[0] = th_rcs[1];
  CreateThrusterGroup (th_group, 1, THGROUP_ATT_BANKLEFT);

  th_group[0] = th_rcs[3];
  th_group[1] = th_rcs[4];
  CreateThrusterGroup (th_group, 2, THGROUP_ATT_YAWRIGHT);

  th_group[0] = th_rcs[2];
  th_group[1] = th_rcs[5];
  CreateThrusterGroup (th_group, 2, THGROUP_ATT_YAWLEFT);

This creates the six thrusters. The geometry is similar to the vernier engines. The difference is that there is also a constant RCS_SPACE, which spaces them a certain distance apart from the other thruster on the same leg. It also organizes them into control groups. With these groupings, all the rotational controls will work, and so should rotational autopilots like killrot, prograde, etc.

These are cold gas jets, and so are invisible, but you may want to add exhaust flames just for debugging purposes. The next, totally optional block, will add them. If you want, add the following code block after the previous one:

  for (int i=0;i<6;i++) {
    AddExhaust(th_rcs[i],0.1,0.05);
  }

Compile and test, and see that now the spacecraft turns very slowly. The real Surveyor had a turn rate of 0.5deg/sec, or 12 full minutes to turn a circle. It takes several seconds of thrusting to get up to even this slow rate.

If you turn the verniers on, note that the spacecraft becomes much more maneuverable. This is because the vernier engines are providing a power assist to the RCS. Also note that the rotation autopilots use the verniers just as well as you can use them manually.

Spacecraft Empty Mass

The total mass of the spacecraft is continually tracked by Orbiter, and consists of the declared empty mass of the spacecraft and the total mass in all the propellant resources. The empty mass is normally constant, but things like jettisons will change the mass. Let's put the mass determination into a separate function. This will help out later when we start jettisoning parts.

Add the following code to the class definition, to define the new method

  double CalcEmptyMass();

Add the following constants near the top to define the empty masses:

const double LANDER_EMPTY_MASS = 289.10; //Basic bus plus payload minus AMR minus retro case
const double RETRO_EMPTY_MASS = 64.88;
const double AMR_MASS = 3.82;

Now add the function body:

double Surveyor::CalcEmptyMass() {
  double EmptyMass=0;
  EmptyMass+=LANDER_EMPTY_MASS;
  return EmptyMass;
} 

Call it from Surveyor::clbkPreStep . Add the following line to the top of that method:

  SetEmptyMass(CalcEmptyMass());

So, why are we making such a simple function? Why is it more complicated than it needs to be? And why are we setting the mass at every time step? All these and more will be answered when we get to jettisoning parts.

Compile and test. You may notice that the spacecraft is a little bit more maneuverable now. A little.

Other physical parameters

Let's put the actual gear under the visual landing pads, so that when we land, the spacecraft will be sitting upright on its legs.

Find the SetTouchdownPoints line in clbkSetClassCaps function. Change it as follows:

  SetTouchdownPoints( _V( 0,LEG_RAD,LEG_STA), _V( sqrt(3.0)/2*LEG_RAD,-0.5*LEG_RAD,LEG_STA), _V(-sqrt(3.0)/2*LEG_RAD,-0.5*LEG_RAD,LEG_STA));

This uses the same geometry as the vernier and RCS engines. Add the appropriate constants to the top of the file with the rest:

const double LEG_RAD = 1.5;
const double LEG_STA =-0.6;

Surveyor is much smaller than ShuttlePB. Set its radius and moments of inertia to something smaller. Surveyor's moments of inertia are not documented, but an analysis by the OrbiterSDK ShipEdit program reveals that they are about 0.5 (normalized) and approximately equal about all three axes. Change the SetPMI and SetSize lines as follows:

  SetPMI (_V(0.50,0.50,0.50));

  SetSize (1.0);

Since the empty mass is calculated at every time step, we can delete the mass setting here:

  SetEmptyMass(500.0);

Compile and Test.

Main Retro

Can we land yet? Yes, if you are less than 15km from the surface and travelling downward at less than 200m/s. You can try to set up a scenario by flying a much more maneuverable vehicle (like, say, a ShuttlePB) to an appropriate altitude and velocity. Go up to about 15km, then use translation jets or just point nose down and use the main jets, to get to about 200m/s downward. The horizontal speed should be as close to zero as you can get it. Point the nose straight up, then quit Orbiter, edit the Current State scenario, and replace the ShuttlePB with Surveyor. Remember to set the PRPLEVEL line correctly, or you may end up without RCS fuel!

Now run Orbiter again, and start the Current State. Turn on the retrograde autopilot. Then just land it! It is theoretically possible, and with sufficient practice actually possible, to land Surveyor under these conditions. It's almost exactly like all the old lunar lander video games. Just get vertical speed to zero as altitude reaches zero. The survivable landing speed of a Surveyor is something around 5m/s downward.

This is nice, but how did they get the real Surveyor to this state of 15km and 200m/s from screaming in at 2.6km/s? With the main retro, of course.

The main retro is a large spherical solid-fueled rocket mounted in the big gap in the center of the Surveyor framework. With a fueled mass of over 600kg, the retro is by far the heaviest single component of the spacecraft, composing 2/3 of the approximately 1000kg launch mass of Surveyor. This engine is able to bring the spacecraft from over 2.4km/s to zero in its 40 second burn. When timed right, this leaves the spacecraft just hanging almost motionless (well, 200m/s is not quite motionless) less than 15km above the surface.

First lets define the main retro fuel grain. Add the following line to clbkSetClassCaps, below the other prop resource creators.

  PROPELLANT_HANDLE ph_retro   = CreatePropellantResource(RETRO_PROP_MASS);

Since it is defined after the other prop resources, it becomes prop resource 2 as far as a scenario file is concerned.

Next, add the definition for the engine itself. Add the following line to clbkSetClassCaps, below the prop resource definitions.

  th_retro = CreateThruster(_V(0.0,0.0,RETRO_STA), _V(0,0,1), RETRO_THRUST, ph_retro, RETRO_ISP);
  AddExhaust(th_retro, 2, 0.3);

Add these constants to the top of the file:

const double RETRO_PROP_MASS=560.64;
const double RETRO_THRUST = 39140;
const double RETRO_BURNTIME = 40.5;
const double RETRO_ITOT   = RETRO_THRUST*RETRO_BURNTIME;
const double RETRO_ISP   = RETRO_ITOT/RETRO_PROP_MASS;
const double RETRO_STA   = -0.75;

Notice that the retro ISP is calculated here, unlike for the other engines. This is because there was no specification in the documentation. However, the nominal average thrust and total burn time was specified.

Compile and test. Notice how much heavier the spacecraft is now. If you are in the air, you probably can't land safely anymore, and if you are on the surface, you probably can't take off. Also, the retro engine is there, ready to be fired, but what button fires it? Right now, none. You can't control the retro at all. Let's fix that. Add another method to the class definition

  int clbkConsumeBufferedKey(DWORD key, bool down, char *kstate);

Now add the body of this function:

int Surveyor::clbkConsumeBufferedKey(DWORD key, bool down, char *kstate) {
  if (!down) return 0; // only process keydown events

  if (KEYMOD_SHIFT (kstate)) {

  } else { // unmodified keys
    switch (key) {
      case OAPI_KEY_L:  // Fire Retro
        SetThrusterLevel(th_retro,1);
        return 1;
    }
  }
  return 0;
}

Change the line in the class definition which holds the thruster handle fields:

  THRUSTER_HANDLE th_vernier[3], th_retro, th_rcs[6], th_group[2];

(While we are there, we got rid of th_hover, and changed the size of the th_rcs and th_group arrays).

Compile and test. Press L to fire the retro. With a full retro, you can launch a Surveyor from the surface of the moon all the way into orbit or escape. Or you can land from 200km with a downward speed of 2.4km/s. Take your favorite maneuverable spacecraft up to above 200km, point it down, rev up to 2.4km/s, then turn retrograde. Quit and edit the current state to replace that ship with Surveyor, and make sure to fill tanks 0, 1, and 2.

Notice something incredibly important. There is no way to shut down the retro. This is like all solid-fueled rockets: They burn to depletion. No throttle-back, no shutdown.

Jettisoning Stuff (physical)

Here is the part where we change the physical mass of the spacecraft as we jettison stuff.

The AMR hardware is located inside the main retro nozzle. It is shot out like a bullet when the retro fires. Let's simulate that by only having the AMR mass count towards the total vehicle mass if the main retro has a full load of propellant in it. After the main retro burns out, it is immediately jettisoned. Let's simulate that by only having the retro casing mass count towards the total vehicle mass if the main retro has some propellant in it.

First, we have to change the propellant handle variable for the retro engine from a local in clbkSetClassCaps to a class field. Add this line to the class definition:

  PROPELLANT_HANDLE ph_vernier, ph_rcs, ph_retro;

and remove the type before these variables in clbkSetClassCaps. Now any method has access to these variables.

Now change CalcEmptyMass to this:

double Surveyor::CalcEmptyMass() {
  double EmptyMass=0;
  if(GetPropellantMass(ph_retro)>0.999*RETRO_PROP_MASS) {
    EmptyMass+=AMR_MASS;
  }
  if(GetPropellantMass(ph_retro)>1) {
    EmptyMass+=RETRO_EMPTY_MASS;
  } 
  EmptyMass+=LANDER_EMPTY_MASS;
  return EmptyMass;
}

This way, if the retro propellant grain has at least 1kg of fuel left, the mass of the retro casing is added to the mass of the spacecraft. If the retro propellant grain is more than 99.9% full, then the mass of the AMR is added to the mass of the spacecraft. In general, it is a bad idea to test floating-point numbers for exact equality to anything.

Compile and test.

The AMR is so small that it doesn't significantly affect the spacecraft center of mass. The main retro is mounted in such a way that its center of mass is at the full spacecraft center of mass. For most staged spacecraft, this is not true, and a call to ShiftCenterOfMass is necessary.

Jettisoning Stuff (Visual)

So, we dumped the AMR and retro casing, but where did they go? It would be great to see them fall away. We can do that!

First, lets prepare the new objects. Each different object has to have its own mesh and config file. In our case, we will borrow again a mesh from Surveyor1-1.zip. This time it's engine1.msh. Use the ShipEdit program to magnify this by a factor of 5, and save it as Orbiter\meshes\Surveyor-Retro.msh.

Now, the Surveyor1-1.zip file doesn't have a mesh for the AMR, so let's simulate one. Squish Surveyor-Retro.msh in the X and Y directions to 50% and the Z direction to 20%. Now rotate it around X by 180deg. Save this as Orbiter\meshes\Surveyor-AMR.msh

Create the file Surveyor_AMR.cfg in the Orbiter\config directory:

ClassName = Surveyor_AMR
MeshName = Surveyor-AMR
Size = 0.15

Mass = 3.82   ; empty mass [kg]
FuelMass = 0  ; max fuel mass [kg]
Isp = 0       ; fuel specific impulse [m/s]

MaxMainThrust = 0
MaxAttitudeThrust = 0
COG_OverGround = 0.0

Similarly create the file Surveyor_Retro.cfg:

ClassName = Surveyor_Retro
MeshName = Surveyor-Retro
Size = 0.3

Mass = 68.44  ; empty mass [kg]
FuelMass = 0  ; max fuel mass [kg]
Isp = 0       ; fuel specific impulse [m/s]

MaxMainThrust = 0
MaxAttitudeThrust = 0
COG_OverGround = 0.0

Now to jettison them. First, we need to keep track of which things are attached, and which have already been jettisoned. We will add a couple of new methods and a variable called status to the class definition:

  void SpawnObject(char* classname, char* ext, VECTOR3 ofs);
  void Jettison();
  int status;

Zero out status near the top of clbkSetClassCaps:

  status = 0;

What this variable means is as follows. Zero means that both the AMR and retro casing are still attached. One means that just the retro is attached, and two means that neither is attached, and the lander is on its own.

void Surveyor::SpawnObject(char* classname, char* ext, VECTOR3 ofs) {
  VESSELSTATUS vs;
  char name[256];
  GetStatus(vs);
  Local2Rel (ofs, vs.rpos);
  vs.eng_main = vs.eng_hovr = 0.0;
  vs.status = 0;
  strcpy (name, GetName()); strcat (name, ext);
  oapiCreateVessel (name, classname, vs);
}

void Surveyor::Jettison() {
  switch(status) {
    case 0:
      status=1;
      SpawnObject("Surveyor_AMR","-AMR",_V(0,0,-0.6));
      break;
    case 1:
      status=2;
      SpawnObject("Surveyor_Retro","-Retro",_V(0,0,-0.5));
      break;
  }
}

Now we can add some code to the clbkPreStep to check for engine firing or burnout.

  if(status == 1 && GetPropellantMass(ph_retro)<1) {
    //Jettison the spent main retro
    Jettison();
  }
  if(status == 0 && GetPropellantMass(ph_retro)<0.999*RETRO_PROP_MASS) {
    //Jettison the AMR if the retro has started burning
    Jettison();
    //Relight the retro if needed
    SetThrusterLevel(th_retro,1);
  } 

We want to do this in reaction to the thrust level of the retro engine, not in response to a keypress, because we are anticipating an autopilot which will light the retro without using a keypress, and we want the jettison to happen properly in this case.

Compile and Test! Go outside the ship and light the main retro by pressing L. You should see the AMR fall away immediately, and the Retro fall away as it burns out. But, they are still invisible while they are attached to the spacecraft...

Multiple Meshes

Let's fix that. Add the following methods to the class definition:

  void SetupMeshes();
  void AddLanderMesh();
  void AddRetroMesh();
  void AddAMRMesh();

And their definitions below:

void Surveyor::AddLanderMesh() {
  VECTOR3 ofs = _V(0,0.3,0);
  AddMesh("Surveyor-Lander",&ofs);
}
void Surveyor::AddRetroMesh() {
  VECTOR3 ofs = _V(0,0,-0.5);
  AddMesh("Surveyor-Retro",&ofs);
}
void Surveyor::AddAMRMesh() {
  VECTOR3 ofs = _V(0,0,-0.6);
  AddMesh("Surveyor-AMR",&ofs);
}

void Surveyor::SetupMeshes() {
  ClearMeshes();
  switch(status) {
    case 0:
      AddAMRMesh();
    case 1:
      AddRetroMesh();
    case 2:
      AddLanderMesh();
  }
} 

So, now we can call SetupMeshes whenever we originally set up the vehicle state in clbkSetClassCaps, and whenever the configuration changes, like in Jettison. Replace the AddMesh line there with a call to SetupMeshes:

  SetupMeshes();

Also, add this line to the bottom of the Jettison method, after the case statement.

Compile and test. Now before you light the retro, you should see the large spherical retro at the center of Surveyor.

That's it, you now have a completely functional Surveyor lunar lander! Have fun with it, and see if you can land better than 5 of 7.

Advanced topics

Deploying the landing gear and omni antenna booms (One-time animation)

Animating the solar panel and antenna (Automatically track objects)

Deploying and using the soil scooper (Keyboard-controlled animation)

Finished Source Code

Check here for the Surveyor Source Code