AuthorTopic: Outerra Anteworld C++ Plugin API (Read 2607 times)

Want to build a C++ plugin for Outerra? Here's what you will need to get started!

Notes:

I will put the example_plugin below on GitHub soon, for now I've put links to download a .zip archive with the example_plugin VS2015 solution and project. I will also be putting the following documentation on the Outerra Wiki once the documentation has been expanded. Currently the plugin included here is a very basic example which exposes a JavaScript interface and methods to initialize and update an aircraft and a vehicle which are also provided under the downloads below. The next update will add C++ methods to play sounds and create lights on the aircraft and vehicle.

The following resources and documentation will be updated, and I will make an attempt to update it when a new Outerra version is released publicly.

Questions and comments are welcomed! And please post tips and suggestions that I may not have been covered. I apologise for any mistakes, full disclosure, I am also a major nube when it comes to C++.

Good luck and we look forward to see what you create!

The API is provided for non-commercial and non-military use only. Please read the following terms and conditions at the bottom of this post.

First you will need to clone the API repository from the the Outerra GitHub and download the additional resources above.

Unzip the example_plugin provided into the api folder you cloned: .\resources\example\

This plugin is different from the other example which will already be in this folder, igc_plugin. IGC is a singleton plugin, simply meaning only one such plugin can be loaded by outerra.exe at a time. The example_plugin however can be loaded simultaneously along with other such plugins.

Next, install the OTX with the provided example aircraft and vehicle assets. Double clicking the OTX file should install it into your user data directory under .\packages\examples\, if that doesn't work you can open the OTX as an archive and copy the folder directly into .\packages\

These assets include scripts which get the plugin's JavaScript interface which exposes a number of methods for initialisation and update calls.

Open the Microsoft Visual Studio Solution example_plugin.sln

If you are using a version of Visual Studio other than VS2015 you will have to remove the comm_static and intergen projects from the solution and add the corresponding ones for your VS version from the api .\include\comm\_build\msvc\**** folder, and then configure the solution dependencies and build order accordingly.

Dependencies and build order:

The intergen project depends on comm_static

The *****_plugin project depends on comm_static and intergen

The build order should be comm_static --> intergen --> *****_plugin

If changing VS version, make sure to set the Platform Toolset to the correct version, it is set to v140 currently for VS2015.

You must also make sure the solution only builds the Single startup project for example_plugin, if you happen to add a new plugin project to the solution this needs to be fixed or else it will try to build one of the other comm_static or intergen projects. Only for /MD Runtime Library the additional comm project is required.

All plugin DLLs must be placed in your .\Anteworld\plugins\ folder and the file name must end with _plugin.dll

In the included example, the project name is example_plugin, so it will already build example_plugin.dll, however if you have a project without plugin at the end of the name, you will need to add "_plugin" to the end of the target name, under Configuration Properties --> General --> Target Name:

Example:Target Name: $(ProjectName)_plugin

It is a good practice to made a sub-folder, for example: .\Anteworld\plugins\example_plugin\example_plugin.dll

You can set the output directory to build Debug and Release to your .\Anteworld\plugins\ sub-folder. This can be done under Configuration Properties --> General --> Target Name

You can also set the project to launch outerra.exe so when you build Debug it will automatically launch Anteworld and load the symbols so you can set break points. This can be done under Configuration Properties --> Debugging --> Command

With the Solution Platform set to Win32 (64-bit support will be coming in the future), you will now be able to build both Release and Debug, and with the DLL placed in the .\Anteworld\plugins\ directory you may now spawn one of the test entities, named Tatra T815-7 (C++ example) and Cessna 172 Mountain Air (C++ example). All that should happen is the wheels on the vehicle will be animated and you will be able to drive, steer and brake (W-A-S-D keys), and the propeller on the aircraft should spin as you increase the throttle (Page Up/Down keys). The scripts have been reduced to only the essential functionality to demonstrate what the plugin is doing and how the script gets the plugin interface and calls the initialize and update methods. This plugin will be updated in the future to provide more examples of using the API.

Part 2. Building your own project

To build your plugin, create a new folder and you will only need to copy four files from the example, these are the Microsoft Visual Studio Solution (example_plugin.sln), VC++ Project (example_plugin.vcxproj), C++ Source (plugin.cpp) and C/C++ Header (plugin.hpp). Rename all of these files and open the solution in VS. The example_plugin project will be missing, you should Remove the old one, right-click the solution and Add Existing project and select your new project. You must rename the project in the solution as well to match. In the project remove the old files and add your source and header. (if anyone knows a more efficient method of renaming all these please post below). As mentioned above, you'll need to make sure the solution is building a Single startup project and your project dependencies are comm, comm_static and intergen.

The .hpp Header Item Type must be set to intergen interface generator, under Properties --> General --> Item Type --> (drop down select). This Header is your main plugin interface header, which is included in all .cpp source files. It has the interface declaration ifc_class that is how JavaScript or C++ gets the interface from ifc_fnx(get), and then the public interface method declarations ifc_fn. This Header will generate intergen.plugin source files for C++, JS and LUA once you build the project, which are then added to the project, as well as the plugin_interface header files which are created in the .\ifc\ sub-folder, which can also be added to you project if necessary.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Sorry for not updating, but yes that worked, though I had to tell intergen where the comm lib that was created was.

Is there a good learning resource on what to do next? It's unclear on the what and how of plugin development. I can see the lists of outerra functions that are already accessible through the console in the folders referenced. Skimming through the example plugin code hasn't illuminated anything.

Mostly what Uriah wrote above. I see he also mentioned intergen project there.You can either use the public API or create your own C++ plugins that provide services for vehicles e.g your physics implementation. For now you need to pass events from vehicle script to methods exposed from your plugin.

I've never created a .dll so I'm positive it's something I'm not doing right, perhaps I'm better off going with VS2015 if the community version will allow older versions, my work computer is loaded with VS2017 so preference is to not roll backwards. Either way I'm appreciative of Uriah helping out the community as I've been anxiously awaiting to play around with Outerra!

It works with VS2017 too, but a failed dll load means either a missing dependency dll, or an exception during loading. The latter most often occurs when there's an interface version mismatch, a wrong version of the api used.