Intercept: A library for writing Arma Addons in native C++

[noubernou 77]

Intercept is a C/C++ binding interface to the Arma 3 engine (internally referred to as the Real Virtuality or RV engine). It's goal is to provide easy to use library for addon makers to develop addons in a native language, or to develop language extensions for the Arma 3 engine.

In a nutshell, Intercept provides a full C/C++ binding system for calling the base C++ functions which are declared in RVEngine for SQF functions. All SQF functions within the RVEngine are actually native code, which is called by SQF via the function names. Intercept bypasses SQF entirely, allowing native C++ plugins to seamlessly interact with the game engine. In essence, Intercept allows for expansions of the game engine, calling internal functionality of the engine which has been exposed via SQF functions. This was the idea behind the intended Java implementation by Bohemia Interactive in Take On Helicopters and was planned for, but never implemented in Arma 3. Intercept not only completes the intended functionality of what Java was meant to provide but has gone much further, including returning data to SQF and multithreaded addons.

Intercept works on a host/client based system, in which the host, Intercept itself, hosts client DLLs that implement the Intercept library. The Intercept host handles access to the RV engine by clients through a layer that provides thread concurrency, memory handling, and event dispatching. Client DLLs are then able to be written in a way that can safely ignore most internal nuances of handling data in the RV engine and work with standard C++ STD/STL data types, and only a few specialized objects specific to the game engine.

The Intercept library also provides raw C bindings to the C++ versions of SQF functions, so it is entirely possible to use Intercept as the basis for writing in additional scripting languages to the RV engine, such as Python or Lua.

You can find more information on our GitHub project page.

Technical Details
Intercept works by making direct calls to the SQF functions in the RV engine. These functions are themselves C++ functions which are then exposed to SQF for allowing interaction with the underlying game engine; Intercept completely bypasses SQF and allows C++ plugins to interact with the engine directly. User created threads can even be created and by properly using the provided thread concurrency functionality it is possible to execute game functionality safely and concurrently.

Intercept clients are able to invoke through the host these commands by provided wrapper functions that replicate and emulate the SQF command namespace (minus some unneeded functionality, like arrays or control structures). These wrapper functions take standard inputs, such as simple primitives like float or bool, and standard std::string arguments and convert them into the proper SQF command variables, providing a seamless layer to the clients.

An example of a very simple client that invokes nular, unary, and binary SQF functions (aka functions that take no arguments, a right side argument only, and both a left and right side argument respectively) is demonstrated below and a more examples can be found here.
 

#include <Windows.h>
#include <stdio.h>
#include <cstdint>
#include <sstream>

// the Intercept library, only one include required.
#include "intercept.hpp"

// required exported function to return API version
int __cdecl intercept::api_version() {
    return 1;
}

// This function is exported and is called by the host each frame.
void __cdecl intercept::on_frame() {
    // get the player object and store it
    intercept::types::object player = intercept::sqf::player();

    // get the post of the player
    intercept::types::vector3 pos = intercept::sqf::get_pos(player);

    // build a string...
    std::stringstream side_chat_msg;
    side_chat_msg << "Hello Arma World, here is the player pos: " << pos.x << "," << pos.y << "," << pos.z;

    // send it to the binary SQF sideChat command
    intercept::sqf::side_chat(player, side_chat_msg.str());
}

// Normal Windows DLL junk...
BOOL APIENTRY DllMain(HMODULE hModule,
    DWORD  ul_reason_for_call,
    LPVOID lpReserved
    )
{
    switch (ul_reason_for_call)
    {
    case DLL_PROCESS_ATTACH:
        break;
    case DLL_THREAD_ATTACH:
    case DLL_THREAD_DETACH:
    case DLL_PROCESS_DETACH:
        break;
    }
    return TRUE;
}

Completion Status
As of now (3/13/16) Intercept is over 82% language feature complete. You can view the progress of wrapper completion here. Almost all normally used SQF functions are available to the end user, and with the added ability of writing inline SQF code, you can call any function that has not had a wrapper written for it yet (though with a small performance penalty). We will post a release thread when we start releasing builds of the host.

Contributions
Feel free to contribute as much as you want to this project in terms of time and code. The goal of this project is to be a tool for the community to provide better performing and more complex addons for the Arma 3 platform. If you would like to contribute or want more information please join our Slack channels and get involved!

License
Intercept is licensed under the MIT license. You can find the full license in the LICENSE file. Prior to commit f9fe4d5 the project was licensed under the GNU/GPL v2 license and continues to be for any commit prior to that.

[bux578 65]

Good job. Really looking forward to this.

[Kingsley1997 39]

This is Nutsâ„¢

[jonpas 294]

Wooo, great job to everyone involved!

[code34 248]

drapal, i keep on eye on it :D

[alganthe 74]

Weeee it's heeeere !

[commy2 188]

Welp, time to learn C++

[code34 248]

Noubernou, do you try do develop a demo addon with it ?

[jonpas 294]

@code34 You can see some examples in the examples repository.

[sttosin 67]

This is kind of a big deal

[noubernou 77]

This is kind of a big deal

Not to toot my own horn (or the horns of the gracious people who have contributed to this project along with me), but it really is. This breaks the engine wide open for modding. One of the pet projects I want to work on using this is integrating JSBSim or some other fixed wing FDM to replace the normal Arma flight model for airplanes. That is totally doable now in a very easy, performant way.

[Flax 397]

Amazing work nou, cannot wait to see some of the amazing things to come out of this as i'm sure there will be some! Hopefully someone jumps on the fixed wing flight model, or is that a hint towards your next project?  :D

[alanford 27]

I've been following this since you've first posted it on reddit. Hasn't really been much news though since. Infact, I just 2 days ago checked github again for any progress. I was beginning to worry because you went so quiet. This thread more than makes up for it. HYYYYPE! :)

 

 

Edit: I know it's waaay too early for such questions, but this one has been burning in my mind for months now. Do you think modders will widely adapt this? And do you plan to move ACE3 to intercept at any point down the line?

 

Cheers

[noubernou 77]

How ACE3 integrates it is still up for debate. There are definitly some systems in ACE that would instantly benefit from this, like wind deflection and the lasers system (I wrote an example of the ACE laser system in Intercept). I also plan to look at how ACRE can benefit from this as well, mostly in making it easier to move more and more of ACRE into C++ and making the entire ACRE system more generic and decoupled from Arma.

 

For other modders I do hope it gets picked up, and I hope it can bring in new talent. A lot of serious game modders are reluctant to take up Arma modding because of SQF and some of the performance issues that come along with it. By providing a native way to code game modifications I hope that people who disregarded the platform before will take a second look and maybe put their ideas into motion on this game platform.

[aenigma 13]

I'm not a coder at all, and I will be honest...most of the description leaves me scratching my head. I understand the concept clearly, and the implications it could have if widely adopted. Hopefully, word gets out in the modding circles of other games and with big things round the corner for Arma, an increase in interest may well see your work used to its full potential. I really hope it does. 

 

I remember the hype surrounding the Java implementation in ToH so I can only imagine what this means to the mod makers these days. 

[Cyteless 10]

This is amazing, Nou! A very exciting addition to modding tools available, I'll have to get stuck into this. Great work.

[zooloo75 834]

Am I too late to the party? Good job! Gonna play around with this unbelievable beast!

[morthon 152]

Oh man, this is really insane! I really hope the modding community will be able to realise the potential of this and we'll see some amazing things happen! I wonder what implications this could have for modifying the ai. Could someone finally fix the driving ai with this?

I'm only beginning to learn C++, but the way I understand it, people could really make almost any kind of game out of arma npw, right? Or am I being silly?

[zooloo75 834]

Oh man, this is really insane! I really hope the modding community will be able to realise the potential of this and we'll see some amazing things happen! I wonder what implications this could have for modifying the ai. Could someone finally fix the driving ai with this?

 

Indeed. Regarding the driving AI, I'd recommend trying out VCOM AI.

[zooloo75 834]

Any plans on a C# wrapper? ;)

[jonpas 294]

Oh man, this is really insane! I really hope the modding community will be able to realise the potential of this and we'll see some amazing things happen! I wonder what implications this could have for modifying the ai. Could someone finally fix the driving ai with this?

I'm only beginning to learn C++, but the way I understand it, people could really make almost any kind of game out of arma npw, right? Or am I being silly?

About AI the most viable solution would be to just disable vanilla AI and control everything yourself, from animations to high command. Otherwise you are always getting in conflict with the engine.

Not anything, you are still bound by the engine itself.

[jonpas 294]

Any plans on a C# wrapper? ;)

No plans for anything yet, anyone is welcome to contribute though. :)

[marceldev89 89]

Is it currently feasible to start making addons with this project and dropping the SQF environment? What are the (known) limitations of this? I understand that there are a couple of unimplemented wrappers and what not but this is pretty damn interesting.  ^_^

 

Also, the last (commit) activity on the GitHub repo has been 2 months ago. Is the project still active or did it die down a little?

[jonpas 294]

Is it currently feasible to start making addons with this project and dropping the SQF environment? What are the (known) limitations of this? I understand that there are a couple of unimplemented wrappers and what not but this is pretty damn interesting.  ^_^

Depends on what you want to do, there are still some cases where the game is likely to crash (a couple of wrappers like that). It's not the intention of this project to completely replace SQF, with that I mean that SQF is still much more accessible to the majority, C++ is not exactly easy and straightforward to pick up and get through it without crashing everything. As of limitations, as you said wrappers, and then a couple of crashes.

 

Also, the last (commit) activity on the GitHub repo has been 2 months ago. Is the project still active or did it die down a little?

A bit, other projects and real life exist as well. :)

[Neviothr 102]

How would one go about converting an existing addon into a dll using this?