Vessel Tutorial 1

Vessel Tutorial

This article intends to guide you through the construction of a new Vessel DLL, by using the sample code from the OrbiterSDK.

This documents my adventure transforming the stock ShuttlePB into a reasonably accurate model of the Surveyor lunar lander. There was a model on OrbitHangar, but it had wildly inaccurate mechanics.

My goal spacecraft: Surveyor

Surveyor was a series of unmanned lunar landers launched by NASA in 1965-1967, before the first Apollo. It is a particularly simple, yet interesting and highly successful design.

Functionally, Surveyor consists of a large solid-fueled main retro-rocket, three medium-sized throttleable liquid fueled vernier engines, and six cold-gas attitude control thrusters.

Surveyor is launched on top of an Atlas-Centaur rocket, on a direct impact trajectory to the moon. Impact will occur after 66 hours. Sixteen hours after launch, it performs a single mid-course correction maneuver, which aims it to precisely impact at the desired landing point.

Thirty minutes before impact, Surveyor maneuvers into a retrograde attitude. From here, its Altitude Marking Radar (AMR) will eventually be able to see the surface and measure the distance. The AMR locks on to the surface at about 200km, one minute before impact. Once the altitude reaches a pre-determined value called the Altitude Mark, it starts a short timer.

At the altitude mark, the spacecraft is hurtling towards the ground at over 2.5km/s and will impact within a minute. For Surveyor 1, the altitude mark was about 110km, and the timer was about 7 seconds. Once the timer expires, the vernier engines light up, then the main retro ignites for its 40 second burn. The main retro gets rid of 2.3km/s of speed, and leaves the spacecraft between 5km and 20km above the surface and travelling downwards at between zero and 230m/s. During this stage, the vernier engines are used to stabilize the spacecraft and compensate for any thrust misalignment in the main retro.

The spacecraft then drops the spent retro motor and continues down on the vernier engines. Using a seperate four-beam Doppler radar and a simple analog computer, it throttles the engines such that it will reach a downward velocity of about 1.3m/s about 4m above the surface. It then cuts its engines and falls the rest of the way.

Why a custom DLL

Many spacecraft can and in fact have been simulated with Vinka's spacecraft.dll. This method uses a text file to describe a spacecraft, and a general purpose DLL to interpret it.

The reason that this spacecraft must be written from scratch, and not use something like spacecraft.dll, is that when the vernier engines are on, they are used to control attitude as well as provide thrust. Two of the three engines use differential thrust to control pitch and yaw, and the third is mounted on a pivot to control roll. This effect cannot be done with spacecraft.dll, and therefore demands a custom DLL. Besides, I felt like writing a DLL, just to learn how to do it.

The Rules

1. Start with something you know works
2. Only make very small changes at a time
3. ALWAYS ALWAYS ALWAYS test each change, no matter how small
4. For historical or real vessels, get good reference material

The Starting Point

So, how do you start with something that works, if you are creating a brand new vessel? Good question. The answer is to look through the samples in OrbiterSDK\Samples for the ship which is closest to the one you have in mind.

Sometimes nothing is particularly close. It was in my case. In this case, just start with the simplest possible ship, the ShuttlePB. Make a copy of this folder, then rename it to your new vessel name. If you are using Visual C++, you probably need to do some weird stuff to rename the project and all the files in it. I use the free compiler, so the project files are no good to me. If you use it also, feel free to just delete all the files except for ShuttlePB.cpp, and rename it to a new name, like Surveyor.cpp.