Outerra forum

Please login or register.

Login with username, password and session length
Advanced search  

News:

Outerra Tech Demo download. Help with graphics driver issues

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

Uriah

  • Global Moderator
  • Hero Member
  • *****
  • Posts: 568
  • We do these things not because they are easy. -JFK
Outerra Anteworld C++ Plugin API
« 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

Example Plugin File Downloads: - updated 6/23/2017


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.
« Last Edit: June 24, 2017, 02:31:03 am by Uriah »
Logged

Uriah

  • Global Moderator
  • Hero Member
  • *****
  • Posts: 568
  • We do these things not because they are easy. -JFK
Re: Outerra Anteworld C++ Plugin API
« Reply #1 on: June 23, 2017, 10:48:18 pm »

RESERVED
Logged

andfly

  • Full Member
  • ***
  • Posts: 230
Re: Outerra Anteworld C++ Plugin API
« Reply #2 on: June 24, 2017, 01:33:52 pm »

Here ... finally !!!
A good subject of study!   :)

Thanks Uriah!
Logged
I do not know the English language. I use Google Translate. I hope it's all understandable.

langdon

  • Full Member
  • ***
  • Posts: 110
Re: Outerra Anteworld C++ Plugin API
« Reply #3 on: June 30, 2017, 12:51:01 am »

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
Logged

SteelRat

  • Sr. Member
  • ****
  • Posts: 380
  • newbie
Re: Outerra Anteworld C++ Plugin API
« Reply #4 on: October 28, 2017, 05:00:19 pm »

~

« Last Edit: October 29, 2017, 02:06:52 pm by SteelRat »
Logged

zzz

  • Sr. Member
  • ****
  • Posts: 266
  • newbie
Re: Outerra Anteworld C++ Plugin API
« Reply #5 on: April 22, 2018, 05:53:14 pm »

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".
Logged

cameni

  • Brano Kemen
  • Outerra Administrator
  • Hero Member
  • *****
  • Posts: 6514
  • Pegs is clever, but tae hain’t a touch sentimental
    • outerra.com
Re: Outerra Anteworld C++ Plugin API
« Reply #6 on: April 23, 2018, 05:09:11 am »

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
Logged

zzz

  • Sr. Member
  • ****
  • Posts: 266
  • newbie
Re: Outerra Anteworld C++ Plugin API
« Reply #7 on: May 03, 2018, 07:41:26 pm »

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.
Logged

cameni

  • Brano Kemen
  • Outerra Administrator
  • Hero Member
  • *****
  • Posts: 6514
  • Pegs is clever, but tae hain’t a touch sentimental
    • outerra.com
Re: Outerra Anteworld C++ Plugin API
« Reply #8 on: May 05, 2018, 12:26:00 pm »

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.
Logged

King_Richard

  • Newbie
  • Posts: 5
Re: Outerra Anteworld C++ Plugin API
« Reply #9 on: May 11, 2018, 07:09:14 pm »

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
Logged

cameni

  • Brano Kemen
  • Outerra Administrator
  • Hero Member
  • *****
  • Posts: 6514
  • Pegs is clever, but tae hain’t a touch sentimental
    • outerra.com
Re: Outerra Anteworld C++ Plugin API
« Reply #10 on: May 14, 2018, 01:40:16 am »

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.
Logged