How to Use UDIM Tiles for Texture Painting in ArmorPaint

ArmorPaint supports industry-standard UDIM workflows by detecting UV tile layouts during import and exporting individual texture files per tile, enabling seamless painting across multiple UV spaces.

ArmorPaint, the open-source 3D texture painting application from the armory3d/armorpaint repository, provides full support for UDIM (U-Dimension) tiling workflows. This feature allows artists to paint high-resolution textures across multiple UV tiles—commonly numbered 1001, 1002, 1003, and beyond—and export them as separate images organized by tile ID. Understanding how to configure the import and export settings is essential for integrating ArmorPaint into professional pipelines that rely on this industry-standard texture layout.

Preparing Your Mesh for UDIM Workflow

Before importing into ArmorPaint, your mesh must contain UV islands correctly assigned to UDIM tile coordinates. Most 3D applications—including Blender, Maya, and 3ds Max—automatically generate these UV layouts when you create UVs beyond the 0-1 UV space. When you export your model as OBJ, FBX, or GLTF formats, the UDIM tile assignments are preserved in the UV coordinate data. Ensure your UV islands sit within the appropriate tile boundaries so ArmorPaint can correctly identify and separate them during import.

Importing Meshes with UDIM Tile Splitting

The critical step in utilizing UDIM tiles for texture painting in ArmorPaint occurs during the import process. When you open the Import Mesh dialog, ArmorPaint detects the file extension and presents a "Split By" combo box that determines how the geometry and materials are organized.

Configuring the Import Dialog

In [box_import_mesh.c](https://github.com/armory3d/armorpaint/blob/main/paint/sources/ui/box_import_mesh.c), the UI creates a selection dropdown that stores your preference in the global context. To enable UDIM workflow:

1. Navigate to File → Import Mesh
2. Locate the Split By combo box
3. Select UDIM Tile from the dropdown options

This selection sets g_context->split_by to SPLIT_TYPE_UDIM (defined as 2 in the source code), as implemented in lines 38-44 of the UI source. The importer then treats each UDIM tile as a distinct material layer, creating separate texture slots for every detected tile.

// UI writes the chosen split mode into the global context
g_context->split_by = SPLIT_TYPE_UDIM;   // <- selected by the user
plugins_split_by = g_context->split_by;  // used by the importer

Once imported, ArmorPaint automatically switches to the active tile when your brush moves over different UV islands, enabling seamless painting across the entire UDIM set without manual layer switching.

Exporting Textures Per UDIM Tile

After painting, you must configure the export settings to generate individual files for each UDIM tile rather than a single combined texture.

Setting the Export Mode

In the Export dialog, change the Export Mode to Per UDIM Tile. This updates g_context->layers_export to EXPORT_MODE_PER_UDIM_TILE (value 3 according to [enums.h](https://github.com/armory3d/armorpaint/blob/main/paint/sources/enums.h)).

According to [export_texture.c](https://github.com/armory3d/armorpaint/blob/main/paint/sources/io/export_texture.c), lines 172 and 512 check this specific export mode and trigger the per-tile iteration logic:

// Export dialog updates the export mode
g_context->layers_export = EXPORT_MODE_PER_UDIM_TILE;

File Naming Convention

When exporting, ArmorPaint iterates over every detected tile and writes individual image files following the standard UDIM naming convention. The exporter constructs filenames by appending the four-digit tile ID to your base texture name:

if (g_context->layers_export == EXPORT_MODE_PER_UDIM_TILE) {
    // Iterate over each UDIM tile and write a separate file
    // Example output: "myTexture_1001.png", "myTexture_1002.png", …
    for (int i = 0; i < tile_count; ++i) {
        char filename[256];
        sprintf(filename, "%s_%04d.png", base_name, tile_ids[i]);
        write_png(filename, tile_data[i]);
    }
}

The generated files (e.g., diffuse_1001.png, diffuse_1002.png) maintain industry-standard naming that allows immediate re-import into Blender, Maya, or other DCC applications without renaming.

Core Implementation Details

Understanding the underlying architecture helps troubleshoot UDIM workflows and verify compatibility with your pipeline.

Enum Definitions

The constants governing UDIM behavior are defined in [paint/sources/enums.h](https://github.com/armory3d/armorpaint/blob/main/paint/sources/enums.h):

• SPLIT_TYPE_UDIM = 2 — Controls mesh import splitting behavior
• EXPORT_MODE_PER_UDIM_TILE = 3 — Controls texture export behavior

FBX Plugin Support

The FBX importer plugin explicitly supports UDIM workflows through [paint/plugins/io_fbx/io_fbx.c](https://github.com/armory3d/armorpaint/blob/main/paint/plugins/io_fbx/io_fbx.c). This implementation respects the SPLIT_TYPE_UDIM flag and utilizes MAX_UDIM_TILES to allocate sufficient memory for high-tile-count assets. When importing FBX files, the plugin reads the UV coordinate data and assigns faces to the appropriate tile layers based on which 1001-range UV space they occupy.

Summary

• Prepare meshes with UV islands correctly positioned in 1001, 1002, etc. tile spaces before importing
• Select "UDIM Tile" in the Import Mesh dialog's "Split By" combo to enable automatic tile detection and layer creation
• Paint seamlessly across tiles as ArmorPaint automatically switches active layers based on brush position
• Export per tile by setting Export Mode to "Per UDIM Tile" to generate individually named files compatible with standard pipelines
• Reference constants SPLIT_TYPE_UDIM (2) and EXPORT_MODE_PER_UDIM_TILE (3) in enums.h when scripting or debugging workflows

Frequently Asked Questions

What is the maximum number of UDIM tiles supported in ArmorPaint?

ArmorPaint defines a maximum tile limit through the MAX_UDIM_TILES constant in the FBX importer plugin (io_fbx.c). While the specific numeric value depends on your build configuration, the architecture supports standard production workflows with dozens of tiles. For extremely high tile counts, verify your system has sufficient VRAM to accommodate the additional texture layers.

Can I use UDIM tiles with formats other than FBX?

Yes, ArmorPaint's UDIM splitting system works with any supported import format including OBJ and GLTF. The SPLIT_TYPE_UDIM flag in the global context is format-agnostic, and the core import logic in box_import_mesh.c processes UV data identically regardless of whether you import via FBX, OBJ, or other plugins. The FBX plugin simply provides additional metadata handling for complex scenes.

How does ArmorPaint handle UDIM tile switching while painting?

ArmorPaint implements automatic tile detection based on UV coordinates under your brush cursor. When you paint across UV seams into a different tile (e.g., moving from 1001 to 1002), the application automatically switches the active texture layer to match the tile being painted. This occurs in real-time during the stroke, allowing seamless painting across multiple UDIM tiles without manually selecting layers or interrupting your workflow.

Are exported UDIM textures compatible with other 3D applications?

Yes, the export process in export_texture.c generates files following the standard UDIM naming convention (baseName_1001.png, baseName_1002.png, etc.). This four-digit tile index format is recognized by Blender, Maya, 3ds Max, Houdini, and other major DCC applications. You can re-import these textures directly into your rendering or look-development environment without renaming or additional processing.

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