Editing Windows Environment Setup and Sample Client Installation.md

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:

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

At the bottom of the New Project window

1. Name: Hello_Intercept
2. Location: default location provide by Visual Studio, should be located in ..\Documents\Visual Studio 2017\Hello_Intercept
3. Solution name: Hello_Intercept
4. 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.

1. Right click on the Hello_Intercept project, located as a child of Solution Hello_Intercept

2. Click properties

3. At the top open the Configuration drop-down, and change to "All Configurations"

4. Platform: All Platforms

5. In the left pane, expand Configuration Properties -> C/C++

6. Click General under C/C++

7. In right pane, click the value for "Additional Include Directories", this will show a drop-down arrow

8. Click the drop-down arrow

9. Click Edit

The "Additional Include Directories" window will open

1. Click the "Insert New Line" button (folder with star)
2. Click the new line in the top pane, press the '...'
3. Locate your Intercept download
4. 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
5. Press OK

Next, still under C/C++ click Language

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

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

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

Expand the Linker category

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

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

1. Click General in the Linker category
2. Click the "Additional Library Directories" value
3. Click the drop-down button
4. Click Edit

The "Additional Library Directories" window will open

1. Click the "Insert New Line" button (folder with star)
2. Click the new line in the top pane, press the '...'
3. Locate your Intercept download
4. 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
5. Press OK

At the top of the screen, change Platform to x64

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

The "Additional Library Directories" window will open

1. Click the "Insert New Line" button (folder with star)
2. Click the new line in the top pane, press the '...'
3. Locate your Intercept download
4. 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_
5. Press OK
6. Collapse the Linker category in the left pane

Ensure the Platform is still set as "x64"

1. Click General under Configuration Properties
2. Click the "Target Name" value
3. Change the "Target Name" value from $(ProjectName) to $(ProjectName)_x64
4. 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();
}

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

Next, Open a new File Explorer window:

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

After build has completed:

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

If built as x64:

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

If built as x86:

1. Navigate to \Release
2. 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.

1. Create a new folder called Hello_Intercept without quotation marks
2. Create a new folder within Hello_Intercept called addons
3. Create a new folder within addons called Hello_Intercept
4. Within @Hello_Intercept create a new file without an extension called $PBOPREFIX$
5. In the $PBOPREFIX$ file, enter Hello_Intercept
6. Save the $PBOPREFIX$ file

Now we will create the config file for our mod

1. 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";
        };
    };
};

1. Save and close config.cpp

Now we will build our mod:

1. Open Arma 3 Tools Addon Builder
2. In the "Addon Source Directory" field, press the "..." to the right
3. Navigate to the Hello_Intercept folder
4. Select the @Hello_Intercept folder
5. In the "Destination directory or filename" field select the addons folder one directory up from the second Hello_Intercept folder
6. Ensure the Binarize checkbox is checked
7. 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.

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

We have built and installed the minimal client extension mod.

Testing

1. Start Arma 3 and open the EDEN editor
2. Load into the Virtual Reality map
3. Place a playable BLUFOR unit down
4. 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!