User mods, screenshots & videos > Plugins / Add-ons
Outerra Anteworld C++ Plugin API
Uriah:
Outerra Anteworld C++ Plugin API
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! =D 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! 8)
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.
Resources: - updated 6/23/2017
* https://github.com/Outerra
* Outerra C++ Plugin API
* Intergen API Documentation
* OpenGL Mathematics (GLM) API Documentation & Manual
Example Plugin File Downloads: - updated 6/23/2017
* Example VS2015 solution and project: example_plugin_v0-05.zip
* Compiled Release DLL: example_plugin.dll
* A test aircraft and vehicle: examples.otx
Instructions & Documentation: - updated 6/23/2017
Part 1. Building the Example Plugin
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
Example:
Target Name: ..\..\..\..\bin\Anteworld\plugins\example_plugin\$(ProjectName)_plugin
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
Example:
Command: X:\Outerra\Outerra Developement\Git\bin\Anteworld\outerra.exe
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.
For more information regarding intergen please refer to the intergen documentation.
You should change the namespace, class, plugin interface declaration in the .hpp and everything coresponding in the .cpp such as the #include for your header, class for public methods, etc.
You should now be able to build Debug and Release and now you can call the publicly exposed methods from JS or another plugin! ^-^
There are many other headers in the .\include\ot\ folder that encompass what is currently available in the Outerra API. Some key ones you may want to explore are:
aircraft_physics.h, environment.h, geomob.h, sndgrp.h, vehicle_physics.h, among others.
Terms and Conditions:
The API is provided for non-commercial and non-military use only. Please email contact at outerra.com if you need a commercial license or a license for software to be used by military users.
Copyright ©Outerra 2016-2017, all rights reserved.
Included snapshots of external libraries needed for given API file. Consult individual license conditions for GLM (https://github.com/Outerra/glm/tree/0.9.4), comm (https://github.com/Outerra/comm) and V8 library (http://code.google.com/apis/v8)
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.
Uriah:
RESERVED
andfly:
Here ... finally !!!
A good subject of study! :)
Thanks Uriah!
langdon:
Hi, I tried getting the plugin to compile but it appears the API on GitHub is missing a file.
Specifically ot/sound_cfg.h
Any chance of getting that included in the src on GitHub?
Thanks,
L
SteelRat:
~
Navigation
[0] Message Index
[#] Next page
Go to full version