Windows Environment Setup and Sample Client Installation

This guide will get a user from zero to having Intercept up and working within their Arma 3 development environment

Requirements:

Arma 3 is installed
Latest version of CBA is installed and enabled as a mod CBA releases can be found here
A working knowledge of C++
Knowledge of how to install and activate non-workshop mods in Arma 3

Outcome:

Intercept Host mod installed
Visual Studio 2017 project environment configured to build an Intercept client
Minimal mod created for Intercept host to find and load sample client
Sample client built
Sample client installed

Install Visual Studio 2017

You can find the downloads for the free community edition here.
Note: Ensure C++ Visual Studio modules are installed.

Install Arma 3 Tools

Note: You may use some other PBO packer.

To install this via Steam, go to the Library drop-down, click tools. In the list, select and download Arma 3 Tools. This is necessary to build the mod to allow the Intercept host to find our client.

Download and Install the Latest Release of Intercept

Building from source

If you would prefer to install from source, please see Building and installing Intercept from source and follow the build guide there. How to do this will not be covered here.

Download the latest release

You may prefer to download a pre-compiled version of the library, which can be found here.

Installation

The Intercept library comes with two components:

The client libary: we use this to build our client extension
The host mod: This allows our code to be injected into the Arma 3. This should be installed as an Arma 3 mod

Creating the Visual Studio 2017 Project

In Visual Studio 2017:

Click File -> New -> Project
The New Project window will open
Click Installed -> Other Languages -> Visual C++ -> Windows Desktop
Click Dynamic-Link Library (DLL) in the center pane

At the bottom of the New Project window

Name: Hello_Intercept
Location: default location provide by Visual Studio, should be located in ..\Documents\Visual Studio 2017\Hello_Intercept
Solution name: Hello_Intercept
Press OK

Configuring the Visual Studio 2017 Project

Note: This section assumes no prior working knowledge of Visual Studio.

Locate the Solution Explorer, by default found on the right side of the screen. If the Solution Explorer is not open, select View -> Solution Explorer to open it.

Right click on the Hello_Intercept project, located as a child of Solution Hello_Intercept
Click properties
At the top open the Configuration drop-down, and change to "All Configurations"
Platform: All Platforms
In the left pane, expand Configuration Properties -> C/C++
Click General under C/C++
In right pane, click the value for "Additional Include Directories", this will show a drop-down arrow
Click the drop-down arrow
Click Edit

The "Additional Include Directories" window will open

Click the "Insert New Line" button (folder with star)
Click the new line in the top pane, press the '...'
Locate your Intercept download
Select the intercept\client\include folder as the line item value
- Note: The fully qualified path to your intercept client include folder should be visible in the top pane
Press OK

Next, still under C/C++ click Language

Click the "C++ Language Standard" value
Press the drop-down button
Change to "ISO C++ Latest Draft Standard (/std:c++latest)"

Next, still under C/C++ click Code Generation

Click the "Runtime Library" value
Press the drop-down button
Change to "Multi Threaded (/MT)"
Collapse the C/C++ category in the left pane

Expand the Linker category

Click Input
Click the Additional Dependencies value
Click the drop-down button
In the top pane, enter intercept_client.lib as a string value
Press OK

At the top of the screen, change Platform to "Win32"

Click General in the Linker category
Click the "Additional Library Directories" value
Click the drop-down button
Click Edit

The "Additional Library Directories" window will open

Click the "Insert New Line" button (folder with star)
Click the new line in the top pane, press the '...'
Locate your Intercept download
Select the \intercept\client\lib folder as the line item value
- Note: The fully qualified path to your intercept client lib folder should be visible in the top pane
Press OK

At the top of the screen, change Platform to x64

Ensure the General tab of the Linker category is still selected
Click the "Additional Library Directories" value
Click the drop-down button
Click Edit

The "Additional Library Directories" window will open

Click the "Insert New Line" button (folder with star)
Click the new line in the top pane, press the '...'
Locate your Intercept download
Select the \intercept\client\lib64 folder as the line item value
- Note: The fully qualified path to your intercept client lib64 folder should be visible in the top pane_
Press OK
Collapse the Linker category in the left pane

Ensure the Platform is still set as "x64"

Click General under Configuration Properties
Click the "Target Name" value
Change the "Target Name" value from $(ProjectName) to $(ProjectName)_x64
Press OK at the bottom right to accept the previous changes and close the Property Pages window

The Intercept client environment in Visual Studio has been configured.

Developing and Installing a Sample Client

Note: This section assumes a basic knowledge of C++ syntax.

We will make a client which spawns a new OPFOR unit, disables the AI, and has it follow the player around. This will demonstrate various operations, and the threading model.

`stdafx.h`

#include "targetver.h"
#include "intercept.hpp"

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

`Hello_Intercept.cpp`

#include "stdafx.h"

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

// Our custom function, instructing our follower unit to move to a location near the player every second
void follow_player(intercept::types::object& follower) {
    while (true) {
        //New scope to allow the thread_lock to lock and release each cycle
        {
            // Blocks the renderer to allow the SQF engine to execute
            intercept::client::invoker_lock thread_lock; 

            // Get the player object and store it
            intercept::types::object player = intercept::sqf::player();

            // Get the position of the player, returned as a Vector3 in PositionAGLS format
            intercept::types::vector3 player_pos = intercept::sqf::get_pos(player);

            // Calculate a new position near the player for our follower to move to
            auto target_pos = intercept::types::vector3(player_pos.x + 5, player_pos.y + 3, player_pos.z);

            // Move our follower
            intercept::sqf::move_to(follower, target_pos);

        } // thread_lock leaves scope and releases its lock

        // Wait one second
        Sleep(1000);
    }
}

// This function is exported and is called by the host at the end of mission initialization.
void intercept::post_init() {
    // Get the player object and store it
    intercept::types::object player = intercept::sqf::player();
    // Get the position of the player, returned as a Vector3 in PositionAGLS format
    intercept::types::vector3 player_pos = intercept::sqf::get_pos(player);

    // Calculate a new position near the player for our follower to spawn at
    auto follower_start_pos = intercept::types::vector3(player_pos.x + 5, player_pos.y + 3, player_pos.z);

    // Make a new group so that we can make a new unit
    intercept::types::group follower_group = intercept::sqf::create_group(intercept::sqf::east());

    // Make our new unit
    intercept::types::object follower_unit = intercept::sqf::create_unit(follower_group, "O_G_Soldier_F", follower_start_pos);
    
    // Stop our new friend from shooting at us or cowering in fear
    intercept::sqf::disable_ai(follower_unit, intercept::sqf::ai_behaviour_types::TARGET);
    intercept::sqf::disable_ai(follower_unit, intercept::sqf::ai_behaviour_types::AUTOTARGET);
    intercept::sqf::disable_ai(follower_unit, intercept::sqf::ai_behaviour_types::AUTOCOMBAT);
    intercept::sqf::disable_ai(follower_unit, intercept::sqf::ai_behaviour_types::CHECKVISIBLE);

    // The doStop SQF function allows him to move independently from his group
    intercept::sqf::do_stop(follower_unit);

    // Make a new thread
    std::thread follower_thread(follow_player, follower_unit);
    
    // Allow that thread to execute independent of the Arma 3 thread
    follower_thread.detach();
}

Next to the Debug Play Button, change the first drop-down to "Release":
Change the other drop-down to x64 if you are running Arma in 64-bit, otherwise change it to x86 for 32-bit
Click on Build
Click Build Solution

Next, Open a new File Explorer window:

Navigate to your Arma 3 installation folder
In the root of your Arma 3 installation folder (where the arma3.exe exists), create a new folder
Name the new folder "intercept" without the quotation marks

After build has completed:

Right click on the Hello_Intercept project
Click on Open Folder in File Explorer

If built as x64:

Navigate to \x64\Release
Copy Hello_Intercept.dll to the intercept folder that was created in the Arma 3 installation folder

If built as x86:

Navigate to \Release
Copy Hello_Intercept.dll to the intercept folder that was created in the Arma 3 installation folder

The sample client has been built and installed.

Create the Intercept Client Addon

In order for the Intercept host to find our sample client, we must create a mod which will point to the DLL we've just installed.

Create a new folder called Hello_Intercept without quotation marks
Create a new folder within Hello_Intercept called addons
Create a new folder within addons called Hello_Intercept
Within @Hello_Intercept create a new file without an extension called $PBOPREFIX$
In the $PBOPREFIX$ file, enter Hello_Intercept
Save the $PBOPREFIX$ file

Now we will create the config file for our mod

Create a new file called config.cpp and enter the following

class CfgPatches {
    class testpbo {
        units[] = { "" };
        weapons[] = {};
        requiredVersion = 0.1;
        requiredAddons[] = {"Intercept_Core"};
        version = 0.1;
    };
};

class Intercept {
    class hello_intercept_project {
        class hello_intercept_plugin {
            pluginName = "hello_intercept";
        };
    };
};

Save and close config.cpp

Now we will build our mod:

Open Arma 3 Tools Addon Builder
In the "Addon Source Directory" field, press the "..." to the right
Navigate to the Hello_Intercept folder
Select the @Hello_Intercept folder
In the "Destination directory or filename" field select the addons folder one directory up from the second Hello_Intercept folder
Ensure the Binarize checkbox is checked
Click the Pack button at the bottom right

Open the addons folder, and we should see Hello_Intercept.pbo along side our Hello_Intercept folder.

Copy the root Hello_Intercept folder to the Arma 3 installation folder.
Rename the root Hello_Intercept folder to @Hello_Intercept
Include the @Hello_Intercept mod to your mod list

We have built and installed the minimal client extension mod.

Testing

Start Arma 3 and open the EDEN editor
Load into the Virtual Reality map
Place a playable BLUFOR unit down
Start the map in single player mode

You should notice the new unit that has spawned, and it should move along with with you as if it were in formation with you

Happy Intercepting!

dedmen/Editing Windows Environment Setup and Sample Client Installation.md