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

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

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

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

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

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.

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