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

> Learn to create custom shader materials in ArmorPaint using the Kong shading language. Easily register and edit your shaders for real-time material customization.

- Repository: [Armory 3D/armorpaint](https://github.com/armory3d/armorpaint)
- Tags: how-to-guide
- Published: 2026-09-11

---

**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:

```kong
#[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`](https://github.com/armory3d/armorpaint/blob/main/base/project.js) at line 16, the default project configuration automatically discovers shaders using the glob pattern `shaders/*.kong`:

```javascript
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`](https://github.com/armory3d/armorpaint/blob/main/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`](https://github.com/armory3d/armorpaint/blob/main/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:

```kong
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`](https://github.com/armory3d/armorpaint/blob/main/base/project.js) (line 16).
- **Automatic compilation**: The [`make.js`](https://github.com/armory3d/armorpaint/blob/main/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`](https://github.com/armory3d/armorpaint/blob/main/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`](https://github.com/armory3d/armorpaint/blob/main/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.