Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/armory3d/armorpaint/llms.txt

Use this file to discover all available pages before exploring further.

ArmorPaint accepts a wide variety of asset types — 3D meshes, texture images, fonts, environment maps, color lookup tables, and plugin scripts — through a unified import system. Press Ctrl+I to open the file browser and pick any supported asset; ArmorPaint automatically detects the file type and routes it to the correct importer. You can also drag and drop files directly onto the viewport or the nodes editor.

​
Importing Meshes

A mesh defines the 3D surface you paint on. When you import a mesh, ArmorPaint replaces the active scene geometry and resets the paint layers by default.

​
Supported Formats

OBJ (.obj)

Wavefront OBJ — built-in importer. The most universally compatible option. Supports multi-object files split by object, material group, or UDIM tile.

glTF / GLB (.glb)

Binary glTF 2.0 — provided by the io_gltf plugin (cgltf 1.4). Supports skinning and multi-mesh scenes.

ARM (.arm)

ArmorPaint native binary format. Fastest load time; used for round-tripping meshes between ArmorPaint projects.

FBX (.fbx)

Autodesk FBX — provided by the io_fbx plugin (ufbx). Supports skinning with optional per-frame evaluation.

Blender (.blend)

Blender project files — imported via the import_blend_mesh bridge, which calls Blender’s Python API (bpy.ops.wm.obj_export) to convert the mesh to OBJ and load it automatically.
These format constants are defined in enums.h:
ConstantValueFormat
MESH_FORMAT_OBJ0Wavefront OBJ
MESH_FORMAT_ARM1ArmorPaint native
MESH_FORMAT_GLB2Binary glTF 2.0

​
Import Options

When importing an OBJ or FBX file, ArmorPaint shows an Import Mesh dialog with the following options:
Controls how multi-object files are divided into separate paint objects:
  • Object — split on object boundaries (default)
  • Material — split on material group boundaries
  • UDIM Tile — split into one object per UDIM tile
Evaluates the mesh skeleton at a specific animation frame before importing. Enable the checkbox and set the Frame slider (1–99) to bake a pose into the mesh geometry at import time.
Set the path to your Blender executable so ArmorPaint can call it to export the .blend mesh. This path is stored in your ArmorPaint configuration and persists across sessions.

​
Reimporting a Mesh

To reload the source mesh from disk (for example, after editing it in a modelling application) without losing your painted layers:
  • Ctrl+R — reimport the mesh from the last-used path, preserving existing paint layers
  • Ctrl+Shift+R — reimport all project textures from disk
Use Ctrl+R after updating a mesh in your DCC tool. ArmorPaint reloads the geometry and keeps all painted layer data intact, as long as the UV layout has not changed.

​
Importing Textures

Textures are imported into the project’s texture browser and can be applied to materials or used as stencils, brushes, and image nodes.

​
Supported Formats

The built-in texture formats (registered in path_texture_formats()) are:
FormatExtension(s)
JPEG.jpg, .jpeg
PNG.png
TGA.tga
BMP.bmp
HDR (Radiance).hdr
PSD (via plugin).psd — requires io_psd plugin
TIFF (via plugin).tiff — requires io_tiff plugin
EXR (via plugin).exr — requires io_exr plugin
SVG (via plugin).svg — requires io_svg plugin (NanoSVG)

​
Bit Depth

Texture bit depth is controlled by the texture_bits_t enum in enums.h:
ConstantValueDescription
TEXTURE_BITS_BITS808-bit per channel (standard LDR)
TEXTURE_BITS_BITS16116-bit per channel (half-float precision)
TEXTURE_BITS_BITS32232-bit per channel (full float, EXR output)

​
How Textures Are Added

When a texture file is imported, ArmorPaint:
  1. Decodes the image and uploads it to GPU memory.
  2. Registers it as an asset_t in the project’s asset list.
  3. Makes it available throughout the texture browser, node editor, and brush stencil selector.
If the same file path is imported a second time, ArmorPaint skips the re-import and logs “Asset already imported” to the console. HDR files dragged onto the viewport are automatically loaded as environment maps (see Environment Maps below).

​
Importing Environment Maps

Environment maps set the scene lighting and background visible in the 3D viewport.
1

Open the file browser

Press Ctrl+I or drag an .hdr or .exr file directly onto the viewport.
2

Select an HDR or EXR file

ArmorPaint detects .hdr files and automatically routes them through import_envmap_run(), which down-scales the image to 1024×512, pre-filters radiance mip levels, and computes spherical harmonics coefficients for irradiance.
3

Adjust lighting

After loading, use the Envmap Angle (envmap_angle) and Light Angle (light_angle) controls in the scene panel to rotate the environment and the dominant light direction independently.
The environment map drives both image-based lighting (IBL) and the real-time irradiance approximation used in the lit viewport mode.

​
Importing Fonts

Fonts are used with the Text tool (TOOL_TYPE_TEXT) to paint text directly onto the mesh surface.
1

Import a font file

Press Ctrl+I and select a .ttf, .ttc, or .otf font file. ArmorPaint calls import_font_run(), which reads all font faces from the file and registers each as a slot_font_t in the project’s font list.
2

Select the font in the Text tool

Open the Text tool options and choose your imported font from the font selector. A preview is rendered automatically after import.
If the same font path is imported a second time, ArmorPaint skips it and logs “Asset already imported”.

​
Importing LUTs

Color Lookup Tables (LUTs) apply color-grading transforms to the viewport display. ArmorPaint uses the standard .cube 3D LUT format.
1

Import a .cube file

Press Ctrl+I and select a .cube file. ArmorPaint calls import_lut_run(), which parses the LUT_3D_SIZE header and RGB triplets, then packs the 3D data into a 2D GPU texture strip (width = N×N, height = N).
2

Activate in Preferences

Navigate to Preferences → Viewport and select your imported LUT. The color grading is applied in real-time to the viewport output.

​
Blender Integration

ArmorPaint includes two dedicated Blender import bridges that both require a valid Blender executable path set in Preferences → Plugins.

Import Blend Mesh

Imports the mesh from a .blend file. Internally calls Blender with bpy.ops.wm.obj_export to export a triangulated OBJ, then loads that OBJ into the current ArmorPaint project. The Blender executable path is configured in the Import Mesh dialog when a .blend file is selected.

Import Blend Material

Bakes Cycles materials from a .blend file into texture maps (base color, roughness, normal) using Blender’s bake system, then imports the resulting JPG textures into the ArmorPaint texture browser.

​
Plugin-Based Importers

Several formats are handled by the plugin system rather than built-in code. These plugins register custom importer functions into import_mesh_importers or import_texture_importers at startup.
PluginFormatType
io_gltf.glb / .gltfMesh
io_fbx.fbxMesh
io_exr.exrTexture
io_tiff.tiffTexture
io_psd.psdTexture
io_svg.svgTexture
If ArmorPaint encounters an unrecognised file extension, it attempts to enable a matching import plugin automatically via context_enable_import_plugin(). Plugin source files (.c) can be installed by dragging them onto the viewport or through Preferences → Plugins.
Plugin importers ship as .c source files and are compiled at runtime. If a required plugin is missing, ArmorPaint logs “Unknown asset format” to the console. See the Plugin API documentation for details on writing custom importers.

Build docs developers (and LLMs) love

Get started for freeTalk to us