The HEMTT Book

What is HEMTT?

HEMTT is an open source tool used to build your Arma 3 mod into PBOs for development and release. It is a replacement for tools like Addon Builder and pboProject.

HEMTT supports the majority of the features found in Bohemia's tools, but prioritizes support for the workflows of best practices and modern modding.

HEMTT is slightly opinionated, most configurations are supported, but some niche features are not and will not be supported. This is to keep the codebase small and maintainable, as well as promote best practices.

Recommended Workflow

HEMTT works best when used in a Git based project, but the HEMTT executable should not be added to your version control.

It is also recommended to use VSCode for your Arma 3 modding, as it has great extensions that will support you in your modding journey.

Additionally the HEMTT VSCode extension is available.

Warning

The VSCode Plugin is in development, and available as an alpha

Using HEMTT in VSCode's integrated terminal is the recommended way to use HEMTT, the output can have helpful information that may be missed otherwise.

Installation

Windows

HEMTT can be installed using Winget.

winget install hemtt

To update HEMTT with winget use:

winget upgrade hemtt

Linux & MacOS

HEMTT can be installed using an installer script.

curl -sSf https://hemtt.dev/install.sh | sh

The script can be ran again to update HEMTT.

Manual Download

The latest HEMTT release can be downloaded from the GitHub releases page.

Builds are available for Windows, Linux, and MacOS.

Compile from Source

HEMTT can be compiled from source using Rust.

HEMTT usually requires the latest stable version of Rust, older versions may work but are not supported.

You can use the cargo install --path bin command to install HEMTT while in the root of the repository.

Arma 3 Tools

HEMTT will use your installation of Arm 3 Tools to binarize supported files (p3d, rtm, wrp).

Installation

Windows

Arma 3 Tools can be installed using Steam. After installation, run the tools at least once to ensure the registry keys are set.

Linux

HEMTT can use either Proton or Wine to run the tools. wine64 is highly recommended, as using Proton will be much slower and may cause windows to pop up while running the tools. HEMTT will always use wine64 if it is available.

Steam

Arma 3 Tools can be installed using Steam with Proton. You can also use SteamCMD to install the tools on servers.

~/.local/share/arma3tools

The tools can be installed manually into ~/.local/share/arma3tools by copying the files from a Windows installation. If the tools are installed with Steam and inside this directory, HEMTT will prefer to use ~/.local/share/armatools.

HEMTT_BI_TOOLS Environment Variable

If you have the tools installed in a different location, you can set the HEMTT_BI_TOOLS environment variable to the path of the tools. HEMTT will always use this path if it is set.

Configuration

Every HEMTT project requires a .hemtt/project.toml file. This file contains all the information HEMTT needs to build your mod.

Previous versions of HEMTT supported a hemtt.json or hemtt.toml file, but these are no longer supported.

Minimum Configuration

The minimum configuration only requires a name and prefix to be set.

.hemtt/project.toml

name = "Advanced Banana Environment"
prefix = "abe"

You can read more about these options on the Minimum Configuration page.

Version

HEMTT uses a custom version format based on standards in the Arma 3 community. You can read more about it on the Version page.

Project

You can additionally configure optional settings for your project.

Main Prefix

The mainprefix option allows you to set the root prefix for your project, used before the prefix option. This is currently only used by hemtt launch.

.hemtt/project.toml

mainprefix = "z"

It should match the $PBOPREFIX$ file in each addon folder.

addons/main/$PBOPREFIX$

z\abe\addons\main

Files

You can add a list of files to be copied to the build directory. This is useful for including files that are not part of addons, such as a README.md, LICENSE, logos, or extensions. To include a folder, you must use a glob pattern that matches all files in that folder.

.hemtt/project.toml

[files]
include = [
    "mod.cpp",        # These files are copied to the build directory by default
    "meta.cpp",       # They do not need to be added to your list
    "LICENSE",
    "logo_ca.paa",
    "logo_co.paa",
    "python_code/**", # Copy the folder "python_code" including all its files
]
exclude = [
    "*.psd",          # By default this list is empty
    "addons/main/README.md",
]

include

By default, those 5 files are included in the build directory if they exist in the root of your project. You do not need to add them to your list. Additional files or glob paths can be added to the list.

.hemtt/project.toml

[files]
include = [
    "mod.cpp",      # These files are copied to the build directory by default
    "meta.cpp",     # They do not need to be added to your list
    "LICENSE",
    "logo_ca.paa",
    "logo_co.paa",
]

exclude

By default, no files are excluded from PBOs. You can add files or glob paths to the list.

.hemtt/project.toml

[files]
exclude = [
    "*.psd",        # By default this list is empty
    "addons/main/README.md",
]

properties

You can add a list of properties to be added to every PBO.

.hemtt/project.toml

[properties]
author = "ABE Team"
url = "https://github.com/ABE-Mod/ABE"

Minimum Configuration

The minimum configuration only requires a name and prefix to be set.

.hemtt/project.toml

name = "Advanced Banana Environment"
prefix = "abe"

name

The name of your mod, currently unused.

prefix

The prefix of your mod.

It should be used in the $PBOPREFIX$ file in each addon folder in the following format.

z\{prefix}\addons\main

addons/main/$PBOPREFIX$

z\abe\addons\main

Version Configuration

HEMTT uses the project version as part of the signing authority. It is also included as an property in built PBOs.

No [version] configuration is required if you use macros in your script_version.hpp file.

.hemtt/project.toml

[version]
path = "addons/main/script_version.hpp" # Default

major = 1 # Overrides path when set
minor = 0
patch = 4
build = 3 # Optional

git_hash = 0 # Default: 8

Macros

By default, HEMTT will look for addons/main/script_version.hpp and use the version components defined there. No [version] configuration is required. A major, minor, and patch version are required, and a build version is optional.

/addons/main/script_version.hpp

#define MAJOR 1
#define MINOR 0
#define PATCH 4 // `#define PATCHLVL` can also be used
#define BUILD 3 // Optional

If your macros are in another file, you can set the path with the version.path key.

.hemtt/project.toml

[version]
path = "addons/common/script_version.hpp"

Defined in Configuration

If you do not want to use a version file, you can set the version components directly in the configuration. If a version is defined in the configuration, the macros will not be used, even if a path is set.

.hemtt/project.toml

[version]
major = 1
minor = 0
patch = 4
build = 3 # Optional

Git Hash

By default, HEMTT will include the first 8 characters of the current git hash in the version. Since the git hash is enabled by default, without configuration HEMTT will require a git repository with at least one commit to be present. The git hash can be disabled by setting version.git_hash = 0, or configured to a different length.

.hemtt/project.toml

[version]
git_hash = 0 # Disabled
git_hash = 4 # 4 characters

Lint Configuration

HEMTT runs lints against your config and SQF files to check for errors, common mistakes, and improvements. Some lints can be disabled, configured, or changed in severity.

Lints can be kept in the project.toml file under the lints section, or in a separate .hemtt/lints.toml file. When kept in lints.toml, the lints. prefix is not required.

See the Analysis section for Config and SQF lints.

Configuration

Note

Some lints are not able to be disabled or reduced in severity. These are usually critical lints that are required for your project to work correctly.

There are 3 ways to configure a lint:

Disabling

A lint can be completely disabled by setting it to false. Only lints that are not critical can be disabled.

[lints.sqf]
command_case = false

Severity

A lint can have its severity changed. The severity can be Error, Warning, or Help. Only lints that are not critical errors can have their severity changed.

[lints.sqf]
command_case = "Warning"

Options

Some lints provide configuration options. Check the documentation for the lint to see what options are available.

[lints.sqf.command_case]
severity = "Error"
options.ignore = [
    "AGLtoASL",
    "ASLtoAGL",
]

Addon Configuration

In addition to .hemtt/project.toml, HEMTT also supports an optional addon.toml in each addon folder.