How to Create Custom Shader Materials in ArmorPaint: A Complete Kong Shading Guide

ArmorPaint uses the Kong shading language (*.kong files) to define custom shader programs; placing these files in paint/shaders/ automatically registers them in the Material editor, where you can assign them to materials and edit exposed uniforms in real time.

The open-source 3D texturing application ArmorPaint (armory3d/armorpaint) extends its rendering capabilities through a custom shading language called Kong. By authoring .kong files and leveraging the project's automatic build pipeline, you can integrate procedural textures, custom lighting models, and post-processing effects directly into the material system. This guide details the exact file structure, compilation workflow, and UI integration based on the current source tree.

Understanding the Kong Shading Language Structure

ArmorPaint materials rely on Kong shader programs that define vertex and fragment processing stages. Unlike standard GLSL, Kong requires a specific export structure to expose entry points to the engine.

The Required pipe Struct

Every Kong shader must declare a pipe struct annotated with #[pipe] that maps the vertex and fragment functions. This struct tells the compiler which functions serve as the shader entry points. The built-in paint/shaders/world_pass.kong demonstrates this pattern, defining how environment map rendering interfaces with the engine.

Additionally, shaders use attribute markers like #[set(everything)] to configure resource bindings, and declare input/output structures (e.g., VertIn and VertOut) to pass data between the vertex and fragment stages.

Step-by-Step Guide to Creating Custom Shader Materials

Step 1: Write Your Kong Shader Code

Create a .kong file that implements a vertex function, a fragment function, and the mandatory pipe struct. If you do not require custom vertex processing, you may implement only the fragment stage, though the struct must still map both entry points.

Here is a minimal implementation that visualizes vertex normals:

#[set(everything)]
const sampler_linear: sampler;

struct VertIn { pos: float3; nor: float3; }
struct VertOut { pos: float4; nor: float3; }

fun my_vert(v: VertIn): VertOut {
    var out: VertOut;
    out.pos = float4(v.pos, 1.0);
    out.nor = v.nor;
    return out;
}

fun my_frag(v: VertOut): float4 {
    var col: float3 = v.nor * 0.5 + 0.5;   // visualize normal
    return float4(col, 1.0);
}

#[pipe]
struct pipe {
    vertex   = my_vert;
    fragment = my_frag;
}

Save this file with a .kong extension, such as my_shader.kong.

Step 2: Place the Shader in the Project Directory

Move your .kong file to the paint/shaders/ directory. According to base/project.js at line 16, the default project configuration automatically discovers shaders using the glob pattern shaders/*.kong:

project.add_shaders("shaders/*.kong");

Any file matching this pattern in the project tree is recognized by the build system as a shader asset.

Step 3: Automatic Compilation via make.js

When you launch the ArmorPaint editor, the build system (make.js) scans the shader glob, invokes the Kong compiler, and generates paired vertex and fragment binaries. This compilation happens automatically; no manual build step is required. The process outputs compiled files (typically with .vert.* and .frag.* extensions) that the runtime loads when you select the material.

Assigning Custom Shaders to Materials

Selecting Your Shader in the Material Editor

Once compiled, your shader appears in the Material editor UI. Open the Materials panel (implemented in paint/sources/ui/materials.js), click + New Material, and select your custom shader from the Shader dropdown. The material now references your compiled Kong program.

Exposing Uniform Parameters for Real-Time Editing

To make shader variables editable in the interface, declare them as uniforms in your Kong source. For example, to add an intensity slider:

uniform float intensity = 1.0;

fun my_frag(v: VertOut): float4 {
    var col: float3 = v.nor * intensity;
    return float4(col, 1.0);
}

After compilation, this intensity uniform automatically appears in the material’s Properties panel, allowing you to adjust values in real time while painting. You can save these configurations as presets or export them with your project for portability across scenes.

Reference Implementation: world_pass.kong

For a production-ready example of environment mapping and uniform handling, examine paint/shaders/world_pass.kong. This file demonstrates the full pipe struct declaration, proper resource binding syntax, and the integration of samplers and uniforms required for full-screen passes.

Summary

• Kong language: ArmorPaint uses .kong files with a mandatory #[pipe] struct to define vertex and fragment entry points.
• File placement: Store custom shaders in paint/shaders/ to match the glob configuration in base/project.js (line 16).
• Automatic compilation: The make.js build system compiles shaders on editor startup without manual intervention.
• Uniform exposure: Declaring uniform variables in Kong code automatically generates editable parameters in the Material Properties panel.
• Integration: Select compiled shaders from the Material editor dropdown to apply them to assets.

Frequently Asked Questions

What file extension do custom ArmorPaint shaders use?

ArmorPaint recognizes the .kong extension for shader source files. These files contain the Kong shading language syntax, which compiles to the engine's native shader binaries.

Where should I place custom shader files in the ArmorPaint repository?

Place your .kong files in the paint/shaders/ directory. This location is covered by the default glob pattern shaders/*.kong defined in base/project.js, ensuring automatic discovery by the build system.

Do I need to manually compile Kong shaders before using them?

No. The make.js build script automatically scans the shader directories and invokes the Kong compiler when the editor initializes. Compiled vertex and fragment binaries are generated without requiring manual command-line interaction.

How do shader parameters appear in the ArmorPaint interface?

Any variable declared with the uniform keyword in your Kong source code (e.g., uniform float myParam;) is automatically exposed in the Properties panel of the Material editor after you assign the shader to a material. You can adjust these values in real time to update the viewport preview.

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