Skip to content

For Developers

Jump to bottom
PhILoXs edited this page Apr 16, 2022 · 5 revisions

Coding guidelines

As you know, we all have our own coding styles and guidelines which apparently makes the code only readable for ourselves, if at all. To prevent this issue, and make our lives easier when working on a bigger project together, we must set coding guidelines. And what role model is better than ACE3 or CBA itself? So therefore we're choosing the ACE3 coding guidelines as our standard. Please read and follow the coding guildlines when making a PR.

Installation

This page describes how you can setup your development environment for Metis Presentation, allowing you to properly build the Metis (mts) Presentation mod and utilize file patching.

Requirements

  • Arma 3
  • A proper installation of the Arma 3 Tools (available on Steam)
  • A properly setup P-drive
  • Run Arma 3 and Arma 3 Tools directly from steam once to install registry entries (and again after every update)
  • Python 3.x
  • CBA mod

Why so complicated?

Metis Presentation uses macros to simplify things and give the developer access to a better debug process, which requires a stricter build environment. The structure of this development environment also allows for file patching, which is very useful for debugging.

Not offering .exes for the Python scripts we use, allows us to make easy changes without the hassle of compiling self-extracting .exes all the time.

Getting Source Code

To actually get the Metis Presentation source code on your machine, it is recommended that you use Git. Tutorials for this are all around the web, and it allows you to track your changes and easily update your local copy.

You can clone Metis Presentation with any Git command line client using the following command:

git clone https://github.com/Metis-Team/mts_presentation.git

Setup and Building

Initial Setup

Execute setup.bat in tools folder.

File Patching Setup

Create the following links manually. First, create z folder in your Arma 3 directory. Then run the following command as admin, replacing the text in brackets with the appropriate paths:

mklink /J "[Arma 3 installation folder]\z\mts_presentation" "[location of the Metis Presentation project]"

Creating a Test Build

To create a development build to test changes or to debug something, execute build.bat in the root folder. This will populate the addons folder with PBOs. These PBOs still point to the source files in their respective folders however, which allows you to use file patching. This also means that you cannot distribute this build to others.

To start the game using this build, you can use the following modline:

-mod=@CBA_A3;z\mts_presentation

Creating a Release Build

To create a complete build that you can use without the source files, execute build_release.bat in the root folder. This will populate the release folder with binarized PBOs that you can redistribute. These handle like those of any other mod. Be sure to set the new version in addons\main\script_version.hpp first!

If you want the release build to be optimized you will need following requirements:

To create the required links for ArmaScriptCompiler execute setup.py in the tools folder.
If that fails, you can create the links manually. First, create z folder in your P-drive. Then run the following command as admin, replacing the text in brackets with the appropriate paths:

mklink /J "P:\z\mts_presentation" "[location of the Metis Presentation project]"

Copy the folder structure in the include folder to P:\. The folders in the P-Drive should look like P:\x\cba\addons\....

Execute build_release.bat in the project root folder. Your builds will now be optimized.
P-drive needs to be mounted if you want to build the release.

File Patching

File Patching allows you to change the files in an addon while the game is running, requiring only a restart of the mission. This makes it great for debugging, as it cuts down the time required between tests. Note that this only works with PBOs created using the build.bat.

To run Arma 3 with file patching add the -filePatching startup parameter.

Files must exist in the built PBOs for file patching to work. If you create a new file you must rebuild the PBO or Arma will not find it in your file paths.

Disable CBA Function Caching

By default CBA caches a compiled version of functions to reduce mission load times. This interferes with file patching. You can disable caching for a single module. To do that you need add the following line or remove the comment in the script_component.hpp file of said module:

#define DISABLE_COMPILE_CACHE

We added a CBA Keybind for a fast recompile of all Metis Presentation functions. Default keybind is the V key.

Restrictions

Configs are not patched during run time, only at load time. You do not have to rebuild a PBO to make config changes, just restart Arma.

Creating GitHub Release

Steps before release:

  1. Merge all wanted Pull-Requests into Master branch
  2. Commit/bump up version number in Master branch (don't forget version in README!)
  3. Merge Master branch into Release branch
  4. Push your local Master and Release branch (this will start the release Action!)
  5. Verify release draft and publish it (wait for Action to finish)

If the Action fails because of a validation error, this means that a release draft already exists with the same version. Just delete the draft and restart the action.

Clone this wiki locally