Outerra forum
User mods, screenshots & videos => Plugins / Add-ons => Topic started by: Uriah on June 23, 2017, 10:47:18 pm
-
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 (https://github.com/Outerra)
- Outerra C++ Plugin API (https://github.com/Outerra/anteworld)
- Intergen API Documentation (https://github.com/Outerra/comm/blob/master/intergen/Readme.md)
- OpenGL Mathematics (GLM) API Documentation (https://glm.g-truc.net/0.9.4/api/files.html) & Manual (http://glm.g-truc.net/0.9.7/glm-0.9.7.pdf)
Example Plugin File Downloads: - updated 6/23/2017
- Example VS2015 solution and project: example_plugin_v0-05.zip (https://drive.google.com/open?id=0B30RzuTW0cE4WU9faWVOYmRSOGs)
- Compiled Release DLL: example_plugin.dll (https://drive.google.com/open?id=0B30RzuTW0cE4bWpJMXhOSkNpaWM)
- A test aircraft and vehicle: examples.otx (https://drive.google.com/open?id=0B30RzuTW0cE4VlREV2dtakZmZW8)
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 (https://github.com/Outerra/comm/blob/master/intergen/Readme.md).
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.
-
RESERVED
-
Here ... finally !!!
A good subject of study! :)
Thanks Uriah!
-
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
-
~
-
Figured I'd finally try my hand at this.
Downloaded anteworld-master from here
https://github.com/Outerra/anteworld
and put it in my VS2015 Projects folder. Opened example_plugins solution. Built comm_static with no problems. Tried building igc_plugin but it gives an error saying it can't find intergen.exe.
I downloaded example_plugin_v0-05.zip and unzipped it to the /example/ folder from anterworld-master, but when I load that all 3 projects simply say "load failed".
-
Please add intergen project (in comm/_build/msvc/201x/) into the solution and build it.
Also you need to use the proper API version, probably https://github.com/Outerra/anteworld/releases/tag/8099
-
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.
-
Anyone get the example working with VS2017?
I've installed the .otx, set the Project Toolset, rebuilt comm_static, intergen and vehicle_plugin, copied the vehicle_plugin.dll to the correct directory however I'm getting a few errors:
1. VS Debug indicates vehicle_plugin.dll loaded but cannot find/open PDB file
2. Outerra indicates failed to load said plugin too
3. On vehicle load Outerra indicates cannot call update for either vehicle that I load, not surprised as loading failed
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!
Thanks
-
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.
-
I am using Outerra 17.1.0, build 9848
I put examples_plugin.dll into the usual Anteworld/plugins folder and
installed the example packages in user packages folder
The c++ example t817 and c172 are in the outerra vehicle and plane menu but when spawning I get errors
INFO: loading plugin: example_plugin.dll
16:25:26.657 ERROR: [ifcreg] declining interface registration for my::example_plugin_interface@wrapper, mismatched intergen version
16:25:26.657 ERROR: [ifcreg] declining interface registration for my::example_plugin_interface.get@303365677, mismatched intergen version
16:25:26.657 ERROR: [ifcreg] declining interface registration for my::example_plugin_interface.get@creator.js, mismatched intergen version
16:25:26.657 ERROR: [ifcreg] declining interface registration for my::js::example_plugin_interface.get, mismatched intergen version
16:25:26.657 ERROR: [ifcreg] declining interface registration for my::example_plugin_interface@wrapper.js, mismatched intergen version
-
Hi @fly77,
To begin you should use the vehicle_plugin example now included in Outerra GitHub repository anteworld/examples:
https://github.com/Outerra/anteworld/tree/master/example
-
OK but since I have some difficulty in compiling example_plugins.sln in visual studio 2017 ...(see below...I am new to Visual studio) I would be glad to have a compiled dll to start ...could you post it ?
I downloaded the anteworld-master from github...put everything inside the visual studio source/repos folder. After double clicking on example_plugins.sln it seems to open the project correctly in Visual studio 2017 . then tried to compile as release for x64 (targeting for Windows SDK 10.0.17763.0)..compiles allmost all but get one error
Errore MSB3721 uscita dal comando ""C:\Users\marco\source\repos\anteworld-master\include\comm\intergen\..\bin\intergen.exe" simplugin.hpp "C:\Users\marco\source\repos\anteworld-master\include\comm\intergen\\metagen"" con codice 1. vehicle_plugin C:\Users\marco\source\repos\anteworld-master\include\comm\intergen\intergen.targets 46
-
Perhaps ( I repeat: Perhaps ) the problem lies in the x64 compilation.
I compile as "win32" and everything works for me ....
-
Thanks for the reply. As I wrote on discord I actually managed to compile and run in outerra Republic of texas's T817 vehicle plugin (yes by using 32 bit).
How about progress with your "plugin loader" menu ?
-
I had missed the fact that you had already found a solution ...
I am pleased to.
Unfortunately ... no progress ...
Every so often, with a little nostalgia, I make some adjustments to the models built in the past and I make small optimizations to the bird routines in C ++, so, just to keep myself in training ...
But I don't find the time to deepen and conclude ...
I look forward to better times ... ::)
-
Am I asking to much or would you be available to share your c++ VS solution of the birds plugin ? ...an older nonperfect one would be enough..just to learn something
-
I am pleased to publish a solution to define global data within Outerra with the ability to write and read them from any vehicle or aircraft model file in Javascript.
Obviously you must use the C ++ language and create a DLL.
I state that I am not a C ++ expert at all.
I only paused to read some manuals and learned the grammar of the language and some rudiments ...
The great fortune was the willingness of Microsoft to make available, for free, the possibility of using Visual Studio at a basic level (and without time limitations) and, above all, the publication of the Example_Plugin of our "great" Uriah (it will not be never thanked enough).
Having this complete and fully functional solution available, it is quite simple to add functions, compile everything, copy the Dll to the program's "plugins" folder and use the new functions by calling them from Javascript.
We think, for example, that we want to have global variables available, useful for transferring data between models, that represent "flags" (integers), numbers (double) and positional data (pos).
Possibly also other data, of any other type ...
In Visual Studio we add, in the plugin.hpp file, the declaration of functions:
ifc_fn int read_flag( int index);
ifc_fn double read_dat(int index);
ifc_fn double3 read_pos(int index);
ecc..ecc...
ifc_fn void wri_flag(int flag, int index);
ifc_fn void wri_dat(double dat, int index);
ifc_fn void wri_pos(double3 pos, int index);
ecc..ecc...
Then, in the plugin.cpp file we declare the global data Arrays (for example 100 variables per type):
int Global_flag [100];
double3 Global_pos [100];
double Global_dat [100];
etc. etc...
(It is useful to declare Arrays because we will retrieve the data by means of their index.)
Then we define the functions (always in plugin.cpp)
//Function read_flag
int example_plugin::read_flag(int index) {
return Global_flag[index];
}
//Function read_dat
double example_plugin::read_dat(int index) {
return Global_dat[index];
}
//Function read_pos
double3 example_plugin::read_pos(int index) {
return Global_pos[index];
}
ecc..ecc...
//Function wri_flag
void example_plugin::wri_flag(int flag,int index) {
Global_flag[index]=flag;
}
//Function wri_dat
void example_plugin::wri_dat(double dat,int index) {
Global_dat[index]=dat;
}
// Function wri_pos
void example_plugin::wri_pos(double3 pos,int index) {
Global_pos[index]=pos;
}
ecc.. ecc...
At this point, in Javascript, we call our plugin interface (within the function init_vehicle () or initialize ()):
$plugin = this.$query_interface('my::js::example_plugin_interface.get');
Within the update_frame () function we can write or read the value of our global variables with these commands:
$plugin.wri_flag(val,index);
$plugin.wri_dat(val,index);
$plugin.wri_pos(val,index);
val=$plugin.read_flag(index);
val=$plugin.read_dat(index);
val=$plugin.read_pos(index);
Extremely simple ...
So simple that it will make C ++ experts smile for its elementality.
But ... it's not my intention to do programming lessons ...
Simply share a possibility that can widely expand the interaction between the models and their playability.
Since, then, "the appetite comes with eating", once experienced the mechanism ... we will surely want to add more functions, commonly used or personal, that we will always have available.
I hope I have done something pleasant. :D
-
wow andlfy ! This is exactly what I was looking for to start toying around making a proof of concept of a simple outerra game ! :) :) :)
I remember you mentioned this possibility of a plugin to obtain global variables in one of your older posts and I wondered how to do this.
So thanks a lot....finally I can begin trying to use it..As a simple test I probably will try to get several planes on my radarscreen !
(https://i.postimg.cc/WzdMfDBM/radar.jpg) (https://postimages.org/)
-
As I said before ..." l'appetito vien mangiando "
In my plugin I added a fair number of generic personal functions on altitudes, inclinations, rotations, ECEF-LON-LAT conversions, etc. .. plus those specific on flocks of birds ...
The satisfaction of always having them available without having to rewrite them every time ... it's great.
But it is even better to think that this does not affect the normal functioning of Outerra or the functions created by the developers or the program itself, in short ... it does not bother anyone.
The plugin is loaded and the functions remain there, quiet, until you decide to use them ... and only if you know the grammar of their call.
The only precaution is to not exaggerate on the definition of global variables in order not to saturate the memory and cause a drop in performance or crashes ... but with a minimum of attention is a very remote possibility!
Best wishes for the future developments of your work!