View source for Arma 3: Creating an Addon

{{TOC|side}}{{Wiki|WIP}}
This page explains the steps required to create an addon ([[PBO File Format|PBO]] file).


== Prerequisites ==

* An addon making tool, such as the official [[Arma_3:_Tools|Arma 3 Tools]], or Mikero's Tools.
* A text editor, such as Notepad++ or Visual Studio Code.


== Preparing the Addon ==

Place all required files (scripts, textures, fonts, models, etc.) in an empty folder, which hereafter will be referred to as the '''Addon folder'''.<br>
It is recommended to organize the files into subfolders to avoid clutter.

In order to make this addon fully functional, at least two additional steps are required, which are explained in further detail in the subsequent sections:

* A file named [[Arma_3:_Creating_an_Addon#Config.cpp|'''config.cpp''']] should be created in the root of the Addon Folder for the game to be able to recognize the addon contents.

* Paths to all files in the addon, such as script paths, model paths, etc. should be adjusted with respect to the [[#Addon_Prefix|'''Addon Prefix''']].

== Addon Prefix ==

In simple terms, Addon Prefix is a virtual (in-game) path to the root of an addon. This virtual path should be unique to prevent collision with other addons.
The addon prefix is added to the [[PBO_File_Format#Arma_PBO|PBO properties]] by the packing tool.

The addon prefix is typically a single word:
 {{Color|purple|Addon_Name}}


It is also possible to use a directory-like structure, which is typically used by mods that contain several addons:
 {{Color|purple|Mod_Name}}\{{Color|darkorange|Addon_Name}}\{{Color|teal|Category}}\...
For example:
 {{Color|purple|My_Faction_Mod}}\{{Color|darkorange|Faction_Name}}\{{Color|teal|Vehicles}}


Once the addon prefix is set, the path to addon files will be as follows:
 {{Color|purple|Addon_Prefix}}\{{Color|darkorange|Folder}}\{{Color|teal|File.format}}


{{Feature | Important | The addon prefix can only contain '''English letters''', '''numbers''', '''underscore ({{ic|_}})''' and backslash ({{ic|\}}). Note that '''spaces are not allowed'''!}}

=== Setting the Addon prefix ===

There are several ways to set the addon prefix, depending on the packing tool used. The instructions for two commonly used tools, namely [[Addon_Builder|Addon Builder]] and Mikero's Tools are explained.

==== Using Addon Builder ====
To set the addon prefix using [[Addon_Builder|Addon Builder]], simply navigate to "Options" and modify the "Addon prefix" edit box.

==== Using Mikero's pboProject ====
To set the addon prefix using Mikero's pboProject, create a text file called {{ic|$PBOPREFIX$}} (no file format is required, but .txt is also possible) in the root of the addon folder, and put the addon prefix in the file.


== Config.cpp ==

When the game loads an addon, it looks for a file called '''config.cpp''' to determine how to process the addon contents. Without such file, almost nothing will happen. In other words, '''config.cpp''' is the hub through which '''all of the addon contents''' will be applied to the game.

This file should be created in the root of the Addon Folder. It is also possible to place additional '''config.cpp''' files in the subfolders of the addon, in which case the subfolders will be treated as separate addons by the game.

At the bare minimum, the '''config.cpp''' file requires a [[CfgPatches|CfgPatches]] class. This will allow the game to determine what external addons are required by this addon, what objects/weapons are being added, as well as other information about the addon such as the author, version, etc.

All added/patched classes should be added to this file in order to be recognized by the game.

=== Config modifications ===

All added/modified config classes, such as [[CfgVehicles]], [[CfgWeapons]], [[CfgAmmo]], [[CfgFunctions]], [[CfgCloudlets]], etc. need to be added to this file.<br>
If the class contents are too long, it is recommended to put them in external files (e.g. {{ic|CfgFunctions.hpp}}) and [[PreProcessor_Commands#.23include|#include]] them in the '''config.cpp''' file:
<syntaxhighlight lang="cpp">
class CfgPatches
{
   // ...
};
#include "cfgFunctions.hpp"
#include "some_other_file.hpp"
#include "ui\gui_defines.hpp"
// etc.
</syntaxhighlight>

=== Scripts ===
{{Feature | Informative | It is recommended to register your scripts as functions in the [[Arma_3:_Functions_Library|CfgFunctions]] class, especially if they are expected to be executed many times during the mission. }}

Scripts can be executed through appropriate classes in '''config.cpp'''. There are several ways to execute scripts, depending on the time and place where it is supposed to happen.<br>

For example, scripts that are to be executed at mission init can be added to the [[Arma_3:_Functions_Library|CfgFunctions]] class with an init flag, such as {{ic|preInit [[=]] 1}}.

Scripts that need to execute when a certain event takes place can be executed using appropriate [[Arma_3:_Event_Handlers|Event Handlers]], if applicable. This method is typically used by vehicle/weapon event handlers.

Some community modifications, such as '''Community Base Addons 3 (CBA)''', add more ways to execute scripts, such as executing a script every time a unit is created (object init event handlers)


== Signing the Addon (optional) ==
Signing an addon allows it to be used in multiplayer servers that check for addon signatures. To sign an addon, a private key is required.

=== Keys and Signatures ===
There are two types of keys used in the context of addons.
==== Private Key ====
A private key is a file in  {{ic|.biprivatekey}} format. It is used to sign addons.
{{Feature | Important | The private keys, as the name suggests, should never be given to the public!}}

==== Public Key ====
A public key is a file in {{ic|.bikey}} format. It is used by the server to check the addon signatures. <br>
These files are safe to give to the public (typically published with the mod itself; see [[#Mod_Folder_Structure|Mod Folder Structure]]).

==== Signature ====
A signature is a file placed next to the PBO file, to verify its contents.<br>
They are named as {{ic|addon_name.pbo.key_name.bisign}}

=== Creating the Keys ===

To create a key, use the [[DSUtils]] program in Arma 3 Tools.

{{Feature | Informative | There is no need to create a new key with every version of an addon! That would require all servers using the addon to update the key after every update, which is inconvenient. }}

{{Wiki|stub}}


== Building the Addon ==
=== Addon Builder ===
'''Main interface'''
[[File:Addon Builder Folder Setup.png|frameless|right|Folder Setup in Addon Builder]]
* '''Addon source directory:''' Should be the path to the Addon folder
* '''Destination directory or filename:''' The output folder which will contain the PBO file, as well as the signature (if "Sign output PBO" is checked)
* '''Sign Output PBO:''' See [[#Signing_the_Addon_(optional)|Signing the Addon]]
* '''Binarize:''' Binarized configs are loaded faster by the game. They will also be checked for syntax errors during the packing process.
'''Options'''
* '''List of files to copy directly:''' By default, only '''.cpp''' files are included in the addon. If other files need to be copied to the addon (e.g. scripts, models, etc.), add them to the list, separated by {{ic|;}} or {{ic|,}}. It is also possible to use the wildcard character {{ic|*}} instead of the file names/formats. For example:
 *.p3d;*.paa;*.sqf;*.fxy;*.xml;*.bisurf;*.rvmat;*.h
All files will be copied in their original folder structure with respect to the Addon Folder.
{{Feature | Informative | When the "Binarize" option is checked, all [[PreProcessor_Commands#.23include|#include]]d '''.hpp''' files in '''config.cpp''' will be added to '''config.bin''' file. Therefore there is no need to add '''*.hpp''' to the list of files to add (unless they're used elsewhere in the mod, such as scripts)}}
* '''Addon Prefix:''' See [[Arma_3:_Creating_an_Addon#Addon_Prefix|Addon Prefix]]
* '''Path to private key file:''' Set this path to the private key file (if "Sign output PBO" is checked)

Other options can be left at their default values. 

Finally, click on "Pack" to start the packing process!

=== Mikero's pboProject ===
{{Wiki|stub}}


== Mod Folder Structure ==
 {{Color|purple|@My_Mod}}                               {{cc|Mod folder}}
 |__{{Color|darkorange|Addons}}                               {{cc|Addons folder, containing all addons and their signatures (if signed)}}
 |  |__{{Color|teal|addon_name.pbo}}
 |  |__{{Color|teal|addon_name.pbo.key_name.bisign}}
 |  |__{{Color|teal|other_addon.pbo}}
 |  |__{{Color|teal|other_addon.pbo.key_name.bisign}}
 |__{{Color|darkorange|Keys}}                                 {{cc|Keys folder (if the mod is signed)}}
 |  |__{{Color|teal|key_name.bikey}}
 |__{{Color|teal|mod.cpp}}                              {{cc|(Optional) file containing the mod description, icon, hover icon, etc.}}
 |__{{Color|teal|mod.paa}}                              {{cc|(Optional) mod icon}}
 |__{{Color|teal|my_extension.dll}}                     {{cc|(Optional) [[Extensions|extension]] that was created as part of the mod}}