Difference between revisions of "Vessel code"

From OrbiterWiki
Jump to navigation Jump to search
(Added category.)
 
(19 intermediate revisions by 13 users not shown)
Line 3: Line 3:
 
'''--- THIS IS WORK IN PROGRESS ---'''
 
'''--- THIS IS WORK IN PROGRESS ---'''
  
This is a quick guide to create your own vessel dll with VC++. It's not suited for newbees to c++. If you are new to orbiter, make a config based vessel first, or one based on vinkas spacecraft.dll or spacecraft2.dll.
+
This is a quick guide to create your own vessel dll with VC++. It's not suited for newbies to c++. If you are new to [[Orbiter]], make a config based vessel first, or one based on vinkas spacecraft.dll or spacecraft2.dll.
You will find here wich API functions are necessary to get a project running. This is basically just a very cut down version from one of the sample ships included in Orbiter SDK.
+
You will find here which API functions are necessary to get a project running. This is basically just a very cut down version from one of the sample ships included in Orbiter SDK.
  
 
==Adding Files to your Project==
 
==Adding Files to your Project==
 
After you have set up the compiler, it's time to start setting up the actual code.
 
After you have set up the compiler, it's time to start setting up the actual code.
  
Try to settle on a name for your vessel class first. Dont choose "testship" or "spacecraft". Try a unique name, like "ProtonLV", "HeavyCruiserHC" or whatever suits you. Save the project under that name and add the following two files (with your vessels name)
+
Try to settle on a name for your vessel class first. Don't choose "testship" or "spacecraft". Try a unique name, like "ProtonLV", "HeavyCruiserHC" or whatever suits you. Save the project under that name and add the following two files (with your vessels name)
  
 
*Source *.cpp file
 
*Source *.cpp file
Line 93: Line 93:
  
 
===Example Code===
 
===Example Code===
 +
 +
<pre><nowiki>
 
#ifndef __TEMPLATE_H
 
#ifndef __TEMPLATE_H
 
#define __TEMPLATE_H
 
#define __TEMPLATE_H
Line 115: Line 117:
  
 
#endif
 
#endif
 +
</nowiki>
 +
</pre>
 +
 +
==Global variables==
 +
 +
One of the biggest causes of crashes in Orbiter modules is the use of global variables. Orbiter doesn't unload and reload the module DLL when you return to the Launchpad and start a new scenario, so any values saved in global variables will maintain their state when you start the new scenario.
 +
 +
For example, if you have a global 'abort' flag to indicate that you're aborting an automatic launch, and that was set by the scenario you were running before you quit out to the Launchpad, the abort flag will still be set when you start the new scenario and your autopilot will immediately and unexpectedly abort the launch.
 +
 +
Consequently you should only ever use global variables when you're absolutely sure they're safe, or when they're constants which therefore cannot change between runs. If you're not sure whether a variable should be global or part of your class, make it a class variable for safety.
 +
 +
[[Category: Articles]]
 +
[[Category:Tutorials]]
 +
[[Category:Add-on tutorials]]

Latest revision as of 11:51, 16 October 2022

Introduction[edit]

--- THIS IS WORK IN PROGRESS ---

This is a quick guide to create your own vessel dll with VC++. It's not suited for newbies to c++. If you are new to Orbiter, make a config based vessel first, or one based on vinkas spacecraft.dll or spacecraft2.dll. You will find here which API functions are necessary to get a project running. This is basically just a very cut down version from one of the sample ships included in Orbiter SDK.

Adding Files to your Project[edit]

After you have set up the compiler, it's time to start setting up the actual code.

Try to settle on a name for your vessel class first. Don't choose "testship" or "spacecraft". Try a unique name, like "ProtonLV", "HeavyCruiserHC" or whatever suits you. Save the project under that name and add the following two files (with your vessels name)

  • Source *.cpp file
  • Header *.h file

Example: "ProtonLV.cpp" and "ProtonLV.h"

Functions in your *.cpp file[edit]

The following text is a template for a *.cpp file. If you replace all the "Template" with your Vessel Class name (caution: use find and replace with case sensitive selected).

Example Code[edit]

#define ORBITER_MODULE

#include "Template.h"

void VLiftCoeff (double aoa, double M, double Re, double *cl, double *cm, double *cd)
{
}

void HLiftCoeff (double beta, double M, double Re, double *cl, double *cm, double *cd)
{
}

Template::Template (OBJHANDLE hObj, int fmodel)
: VESSEL2 (hObj, fmodel)
{
}


Template::~Template ()
{
}

void Template::clbkSetClassCaps (FILEHANDLE cfg)
{
}

void Template::clbkLoadStateEx (FILEHANDLE scn, void *vs)
{
}

void Template::clbkSaveState (FILEHANDLE scn)
{
}


void Template::clbkPreStep (double simt, double simdt, double mjd)
{
}

void Template::clbkPostStep (double simt, double simdt, double mjd)
{
}


int Template::clbkConsumeBufferedKey (DWORD key, bool down, char *kstate)
{
}


DLLCLBK void InitModule (HINSTANCE hModule)
{
}


DLLCLBK void ExitModule (HINSTANCE hModule)
{
}

DLLCLBK VESSEL *ovcInit (OBJHANDLE hvessel, int flightmodel)
{	
}

DLLCLBK void ovcExit (VESSEL *vessel)
{
}

Functions in your *.h file[edit]

The following text is a template for a *.h file. If you replace all the "Template" with your Vessel Class name (caution: use find and replace with case sensitive selected)

Example Code[edit]

#ifndef __TEMPLATE_H
#define __TEMPLATE_H

#define STRICT

#include "orbitersdk.h"

class Template: public VESSEL2 {
public:
	Template (OBJHANDLE hObj, int fmodel);
	~Template ();
	void clbkLoadStateEx (FILEHANDLE scn, void *vs);
	void clbkSaveState (FILEHANDLE scn);
	int  clbkConsumeBufferedKey (DWORD key, bool down, char *kstate);
	void clbkSetClassCaps (FILEHANDLE cfg);
	void clbkPreStep (double simt, double simdt, double mjd);
	void clbkPostStep (double simt, double simdt, double mjd);
	
};


#endif

Global variables[edit]

One of the biggest causes of crashes in Orbiter modules is the use of global variables. Orbiter doesn't unload and reload the module DLL when you return to the Launchpad and start a new scenario, so any values saved in global variables will maintain their state when you start the new scenario.

For example, if you have a global 'abort' flag to indicate that you're aborting an automatic launch, and that was set by the scenario you were running before you quit out to the Launchpad, the abort flag will still be set when you start the new scenario and your autopilot will immediately and unexpectedly abort the launch.

Consequently you should only ever use global variables when you're absolutely sure they're safe, or when they're constants which therefore cannot change between runs. If you're not sure whether a variable should be global or part of your class, make it a class variable for safety.