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:

NaodW29-pre193f213670091e2300000001

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:

NaodW29-pre193f213670091e2300000002

NaodW29-pre193f213670091e2300000003

NaodW29-pre193f213670091e2300000004

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:

NaodW29-pre193f213670091e2300000005

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:

NaodW29-pre193f213670091e2300000006

NaodW29-pre193f213670091e2300000007

Compile and Test.

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 trhusters, while retaining them as rotation thrusters. Cut the following code chunks:

NaodW29-pre193f213670091e2300000008

NaodW29-pre193f213670091e2300000009

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 needs 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:

NaodW29-pre193f213670091e230000000A

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:

NaodW29-pre193f213670091e230000000B

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

NaodW29-pre193f213670091e230000000C

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:

NaodW29-pre193f213670091e230000000D

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 enoug, 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 unbalance of force. This kept with the philosophy of spacecraft simplicity by shifing 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 (foreward) 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 acconted for on the ground.

One more thing to remember: The legs are well below 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:

NaodW29-pre193f213670091e230000000E

Now, add the following code in its place:

NaodW29-pre193f213670091e230000000F

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:

NaodW29-pre193f213670091e2300000010

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 seperate function. This will help out later when we start jettisoning parts.

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

NaodW29-pre193f213670091e2300000011

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

NaodW29-pre193f213670091e2300000012

Now add the function body:

NaodW29-pre193f213670091e2300000013

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

NaodW29-pre193f213670091e2300000014

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:

NaodW29-pre193f213670091e2300000015

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

NaodW29-pre193f213670091e2300000016

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

NaodW29-pre193f213670091e2300000017

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:

NaodW29-pre193f213670091e2300000018

NaodW29-pre193f213670091e2300000019

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

NaodW29-pre193f213670091e230000001A

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 a screaming 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.

NaodW29-pre193f213670091e230000001B

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.

NaodW29-pre193f213670091e230000001C

Add these constants to the top of the file:

NaodW29-pre193f213670091e230000001D

Notice that the retro ISP is calculated here, unlike for the other engines. This is because there was no specifications 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

NaodW29-pre193f213670091e230000001E

Now add the body of this function:

NaodW29-pre193f213670091e230000001F

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

NaodW29-pre193f213670091e2300000020

(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:

NaodW29-pre193f213670091e2300000021

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

Now change CalcEmptyMass to this:

NaodW29-pre193f213670091e2300000022

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 its 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:

NaodW29-pre193f213670091e2300000023

Similarly create the file Surveyor_Retro.cfg:

NaodW29-pre193f213670091e2300000024

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:

NaodW29-pre193f213670091e2300000025

Zero out status near the top of clbkSetClassCaps: NaodW29-pre193f213670091e2300000026

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.

NaodW29-pre193f213670091e2300000027

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

NaodW29-pre193f213670091e2300000028

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:

NaodW29-pre193f213670091e2300000029

And their definitions below:

NaodW29-pre193f213670091e230000002A

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:

NaodW29-pre193f213670091e230000002B

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