Difference between revisions of "Simulation Extensions"

From OpenRocket wiki
Jump to navigation Jump to search
(Created page with "By using OpenRocket's extension and listener mechanism, it's possible to modify the program itself to add features that are not supported by the program as distributed; some e...")
 
Line 25: Line 25:
  
 
Creating an extension for OpenRocket requires writing three classes:
 
Creating an extension for OpenRocket requires writing three classes:
- A listener, which extends <code>AbstractSimulationListener</code>,
+
 
- An extension, which extends <code>AbstractSimulationExtension</code>, and
+
* A listener, which extends <code>AbstractSimulationListener</code>.  This will be the bulk of your extension, and performs all the real work.
- A provider, which extends <code>AbstractSimulationExtensionProvider</code>.
+
 
 +
* An extension, which extends <code>AbstractSimulationExtension</code>, which inserts your listener into the simulation when it is called. Your listener can (and probably will) be private within your extension.
 +
 
 +
* A provider, which extends <code>AbstractSimulationExtensionProvider</code>, which puts your extension into the menu described above and calls the simulation.
 +
 
 +
In addition, if your extension will have a configuration GUI, you will need to write
 +
 
 +
* A configurator, which extends <code>AbstractSwingSimulationExtensionConfigurator&lt;&gt;</code>
 +
 
 +
You can either create your extension outside the source tree and insert it in OpenRocket's .jar file when compiled, or you can insert it in the source tree and compile it with OpenRocket.  Since all of OpenRocket's code is freely available, and reading the code for the existing extensions will be very helpful in writing your's, the easiest approach is to simply insert it in the source tree.  If you select this option, a very logical place to put your extension is in
 +
 
 +
<code>core/src/net/sf/openrocket/simulation/extension/example/</code>
 +
 
 +
This is where the extensions provided with OpenRocket are defined. Your configurator, if any, will logically go in
 +
 
 +
<code>swing/src/net/sf/openrocket/simulation/extension/example/</code>

Revision as of 19:19, 8 December 2022

By using OpenRocket's extension and listener mechanism, it's possible to modify the program itself to add features that are not supported by the program as distributed; some extensions that have been created already provide the ability to air-start a rocket, to add active roll control, and to calculate and save extra flight data.

This page will discuss extensions and simulations. We'll start by showing how a simulation is executed (so you can get a taste of what's possible), and then document the process of creating the extension. WARNING: writing an extension inserts new code into the program. It is entirely possible to disrupt a simulation in a way that invalidates simulation results, or can even crash the program. Be careful!

Adding an Extension to a Simulation

Extensions are added to a simulation through a menu in the "Simulation Options" tab.

  1. Open a .ork file and go to the Flight Simulations tab
  2. Click the Edit simulation button to open the Edit simulation dialog.
  3. Go to the Simulation options tab.
  4. Click the Add extension button

This will open a menu similar to the one in the following screenshot:

Extension-menu.png

Clicking on the name of an extension will add it to the simulation; if it has a configuration dialog the dialog will be opened:

Air-start-configuration.png

In the case of the air-start extension, the configuration dialog allows you to set the altitude and velocity at which your simulation will begin. After you close the configuration dialog (if any), a new panel will be added to the Simulation options pane, showing the new extension with buttons to reconfigure it, obtain information about it, or remove it from the simulation:

Air-start-pane.png

Writing Simulation Extensions and Listeners

The remainder of this page will discuss the process for writing simulation extensions and listeners. It is expected that the reader will be familiar with programming in Java.

Creating an extension for OpenRocket requires writing three classes:

  • A listener, which extends AbstractSimulationListener. This will be the bulk of your extension, and performs all the real work.
  • An extension, which extends AbstractSimulationExtension, which inserts your listener into the simulation when it is called. Your listener can (and probably will) be private within your extension.
  • A provider, which extends AbstractSimulationExtensionProvider, which puts your extension into the menu described above and calls the simulation.

In addition, if your extension will have a configuration GUI, you will need to write

  • A configurator, which extends AbstractSwingSimulationExtensionConfigurator<>

You can either create your extension outside the source tree and insert it in OpenRocket's .jar file when compiled, or you can insert it in the source tree and compile it with OpenRocket. Since all of OpenRocket's code is freely available, and reading the code for the existing extensions will be very helpful in writing your's, the easiest approach is to simply insert it in the source tree. If you select this option, a very logical place to put your extension is in

core/src/net/sf/openrocket/simulation/extension/example/

This is where the extensions provided with OpenRocket are defined. Your configurator, if any, will logically go in

swing/src/net/sf/openrocket/simulation/extension/example/