Simulation Extensions

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

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

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:

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<E>

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/

Simulation Listeners

Simulation listeners are methods that OpenRocket calls at specified points in the computation to either record information or modify the rocket state. These are divided into three interface classes, named SimulationListener, SimulationComputationListener, and SimulationEventListener.

All of these interfaces are implemented by the abstract class AbstractSimulationListener. This class provides empty methods for all of the methods defined in the three interfaces, which are overridden as needed when writing a listener. A typical listener method (which is actually in the Air-start listener), would be

public void startSimulation(SimulationStatus status) throws SimulationException {
    status.setRocketPosition(new Coordinate(0, 0, getLaunchAltitude()));
    status.setRocketVelocity(status.getRocketOrientationQuaternion().rotate(new Coordinate(0, 0, getLaunchVelocity())));
}

Method	When Called
startSimulation()	When the simulation is started
endSimulation()	When the simulation finishes
preStep()	Before each simulation step
postStep()	After each simulation step

() () () () () ()