How to Build ArmorPaint from Source on Linux: A Complete Guide

To build ArmorPaint from source on Linux, install the Vulkan and GTK development libraries, clone the armory3d/armorpaint repository, execute ../base/make --run from the paint directory to invoke the custom amake build system, and launch the resulting binary at build/ArmorPaint.

ArmorPaint is a native 3D PBR texture-painting application developed by armory3d. Compiling it from source on Linux requires Clang, the Vulkan SDK, and GTK3 libraries, orchestrated through a custom JavaScript-driven build tool called amake. This guide explains the exact steps to configure your environment and generate a working binary using the official source tree.

Prerequisites: Install Linux Dependencies

Before compiling, install the system libraries listed in base/docs/linux_deps.md. The build requires Vulkan graphics drivers, GTK-3 for the interface, and Clang as the compiler.

On Debian or Ubuntu systems, run:

sudo apt update && sudo apt install -y make clang libvulkan-dev libgtk-3-dev \
    libssl-dev libxi-dev libxrandr-dev libxcursor-dev libasound2-dev

Arch Linux users should install the equivalent packages from their repositories. These dependencies link against the engine's WebGPU Vulkan backend and the UI layer's native windowing system.

Clone the Repository

Clone the source tree and navigate to the UI layer directory:

git clone https://github.com/armory3d/armorpaint
cd armorpaint/paint

The repository splits into two main sections: base/ contains the core engine and build system, while paint/ houses the application UI, material logic, and plugin system. The build commands are always executed from within the paint directory.

Understanding the Build System

ArmorPaint uses a custom build system called amake located in base/tools/amake/. This lightweight JavaScript-driven tool abstracts platform differences and generates native project files.

The entry point is the base/make wrapper script. When invoked, it forwards arguments to the platform-specific amake binary at tools/bin/linux/amake. This generates a build/ directory containing Ninja-generated Makefiles configured to link against the Vulkan SDK and GTK libraries.

Key architectural components include:

• Engine (base/sources/): Written in C/C++ with a WebGPU wrapper (webgpu_gpu.c) for Vulkan rendering
• UI Layer (paint/sources/): Implements viewport.c, util_ui.c, and util_brush.c, interacting with the engine via iron_draw.c
• Plugin System: Shared libraries loaded at runtime from paint/plugins/

Compile ArmorPaint

Run the Build Wrapper

From the paint directory, execute the build command:

../base/make --run

This invokes amake to generate build files and compiles the project. The process links the engine core against Vulkan and GTK, producing the final executable. On successful completion, you will find ArmorPaint inside the newly created build/ directory.

Optional Build Targets

The amake system supports specific build targets for development:

Engine only: To compile only the core engine library without the full UI:

../base/make --target engine

Embed mode: To enable resource embedding using Clang 19+ #embed directives:

../base/make --embed

For advanced configuration, invoke amake directly with custom targets as documented in base/tools/amake/readme.md.

Launch the Application

Run the compiled binary:

./build/ArmorPaint

If the build succeeded, the application initializes using base/sources/engine.c for the main loop and paint/sources/viewport.c for UI rendering. Ensure your system has a Vulkan-compatible GPU and drivers loaded.

Summary

• Install dependencies from base/docs/linux_deps.md including libvulkan-dev, libgtk-3-dev, and clang
• Clone the armory3d/armorpaint repository and enter the paint/ directory
• Build using ../base/make --run, which calls the custom amake tool to generate Ninja Makefiles
• Locate the output binary at build/ArmorPaint and execute it directly
• Customize the build with --target engine for core-only compilation or --embed for modern Clang features

Frequently Asked Questions

What Linux dependencies are required to build ArmorPaint?

You need development headers for Vulkan, GTK-3, OpenSSL, X11, and ALSA. The specific packages for Debian/Ubuntu are make clang libvulkan-dev libgtk-3-dev libssl-dev libxi-dev libxrandr-dev libxcursor-dev libasound2-dev, as listed in base/docs/linux_deps.md.

How does the amake build system differ from CMake or Make?

amake is a custom JavaScript-driven tool in base/tools/amake/ that generates native project files for multiple platforms. The base/make wrapper script calls the Linux-specific tools/bin/linux/amake binary, which creates a build/ directory with Ninja-generated Makefiles tailored for the Vulkan and GTK toolchain.

Can I compile only the ArmorPaint engine without the UI?

Yes. Pass the --target engine flag to the build wrapper: ../base/make --target engine. This compiles only the core engine library from base/sources/ without linking the UI layer modules like viewport.c or util_ui.c.

Where is the compiled binary located after building?

The executable is placed at build/ArmorPaint relative to the paint/ directory where you ran the build command. This binary links dynamically against the Vulkan SDK and GTK-3 libraries installed on your system.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}