# How to Use the ArmorPaint Debug Console and Scripting API for Live Coding

> Unlock ArmorPaint's power with live coding. Use the debug console and scripting API to manipulate projects, textures, and brushes programmatically. Explore the ArmorScript API now.

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

---

**ArmorPaint features a built-in debug console that leverages the Haxe hscript interpreter to evaluate code at runtime, allowing artists to manipulate projects, textures, and brushes programmatically through the ArmorScript API.**

ArmorPaint, developed in the [armory3d/armorpaint](https://github.com/armory3d/armorpaint) repository, is built on the **Kha** cross-platform engine with its core logic written in **Haxe**. The application exposes a powerful **scripting API** through an embedded debug console, enabling live coding and rapid prototyping without recompiling the application.

## Opening the Debug Console

The debug console provides an interactive REPL (Read-Eval-Print Loop) directly within the ArmorPaint viewport. To access it:

- Press `Shift + ~` (tilde) to toggle the console overlay.
- Type Haxe expressions into the input field and press Enter to execute.
- View output and errors in the scrolling log panel above the input.

This interface is implemented in `base/sources/ui/DebugConsole.hx`, which handles the UI overlay, text input capture, and result display.

## Architecture Overview

The scripting system integrates tightly with ArmorPaint's core engine through four main components:

- **DebugConsole.hx** (`base/sources/ui/DebugConsole.hx`): Manages the UI layer and forwards user input to the scripting engine.
- **ArmorScript.hx** (`base/sources/api/ArmorScript.hx`): Initializes the `hscript` interpreter and registers global API functions.
- **Bindings.hx** (`base/sources/api/Bindings.hx`): Wraps core ArmorPaint objects (Project, Texture, Brush) for script accessibility.
- **Project.hx** (`base/sources/logic/Project.hx`): Represents the active painting session data model that scripts query and modify.

When you submit a line of code, the execution flow follows this path: `DebugConsole.onSubmit(line)` → `ArmorScript.evaluate(line)` → `hscript.Interp.execute(line)` → Bindings → Core Objects. Results return to the console immediately.

## Key API Methods and File Locations

### DebugConsole.hx - The UI Layer

Located at `base/sources/ui/DebugConsole.hx`, this module creates the text input field and maintains the command history. It captures keyboard events and routes valid Haxe syntax to the singleton scripting engine instance.

### ArmorScript.hx - The Scripting Engine

The central entry point in `base/sources/api/ArmorScript.hx` creates the `hscript.Interp` instance and exposes these key methods:

- `ArmorScript.getProject()`: Returns the current `Project` object.
- `ArmorScript.createTexture(width, height)`: Generates a new texture buffer.
- `ArmorScript.getActiveTexture()`: Retrieves the currently selected layer.
- `ArmorScript.setActiveTexture(tex)`: Switches the active painting target.
- `ArmorScript.saveTexture(tex, path)`: Exports texture data to disk.

### Core Data Bindings

The `base/sources/api/Bindings.hx` file maps internal C++ or Haxe objects to script-friendly globals. For rendering operations, `base/sources/render/RenderPass.hx` provides hooks for custom shader execution via `ArmorScript.runShader()`.

## Practical Scripting Examples

### Basic Project and Texture Operations

Query project metadata and manage texture assets interactively:

```haxe
// Print the current project name
trace(ArmorScript.getProject().name);

// Create a 1024x1024 texture and set it as active
var tex = ArmorScript.createTexture(1024, 1024);
ArmorScript.setActiveTexture(tex);

// Export the active texture to PNG
ArmorScript.saveTexture(ArmorScript.getActiveTexture(), "exports/myTexture.png");

```

### Brush Manipulation

Adjust painting parameters in real-time without navigating menus:

```haxe
// Set brush size to 12 pixels
ArmorScript.setBrushSize(12.0);

// Change brush color to opaque green (ARGB format)
ArmorScript.setBrushColor(0xff00ff00);

```

### Custom Shaders and Rendering

Execute shader passes programmatically using the render pipeline defined in `base/sources/render/RenderPass.hx`:

```haxe
// Apply a custom blur shader to the active layer
ArmorScript.runShader("scripts/shaders/blur.hlsl", ArmorScript.getActiveTexture());

// Check current render target dimensions
var size = ArmorScript.getRenderTargetSize();
trace('Render size: ${size.x} × ${size.y}');

```

### Defining Functions in the Console

Define reusable functions directly in the REPL for batch operations:

```haxe
function fillLayer(colour:Int) {
    var tex = ArmorScript.getActiveTexture();
    ArmorScript.clearTexture(tex, colour);
}

// Fill the current layer with white
fillLayer(0xffffffff);

```

## Execution Flow and Performance Considerations

Because the `hscript` interpreter runs in the same thread as the main Kha render loop, scripts execute synchronously and block the UI until completion. This design provides immediate visual feedback—any texture or brush changes appear instantly in the viewport—but requires careful coding practices:

- Keep scripts short and non-blocking; avoid heavy file I/O in the main thread.
- Use Kha's `Task` system for asynchronous operations like batch exporting.
- Errors thrown by `hscript.Interp` are caught and printed to the console log without crashing the application.

## Summary

- **ArmorPaint** exposes a live coding environment via the debug console (`base/sources/ui/DebugConsole.hx`), accessible with `Shift + ~`.
- The **ArmorScript API** (`base/sources/api/ArmorScript.hx`) wraps core functionality using the `hscript` interpreter.
- Scripts can manipulate **Project** data, create and export **Textures**, adjust **Brush** parameters, and execute custom **RenderPass** shaders.
- All scripting operations run synchronously in the main thread, providing immediate visual feedback.

## Frequently Asked Questions

### How do I open the ArmorPaint debug console?

Press `Shift + ~` (tilde) to toggle the console overlay. This shortcut is handled by the UI module in `base/sources/ui/DebugConsole.hx`.

### What programming language does the ArmorPaint scripting API use?

The API uses **Haxe** syntax interpreted at runtime via the `hscript` library. You write Haxe code directly into the console, which `ArmorScript.evaluate()` passes to `hscript.Interp`.

### Can I automate repetitive tasks with the ArmorPaint scripting API?

Yes. You can define functions in the console to batch-process textures, automate brush settings, or export multiple layers. For heavy operations, delegate to Kha's asynchronous `Task` system to avoid blocking the render loop.

### Where are the scripting API bindings defined in the source code?

The bindings that expose internal objects to the scripting environment are located in `base/sources/api/Bindings.hx`, while the main API entry points reside in `base/sources/api/ArmorScript.hx`. Core data models like `Project` are defined in `base/sources/logic/Project.hx`.