Documentation

Overview

CLAUDIUS is an Unreal Engine 5 plugin that exposes editor functionality through a JSON-based command interface. It enables external tools, scripts, and AI assistants to control the Unreal Editor programmatically.

Key capabilities include:

• 130+ commands across 19 categories covering most editor operations
• Two communication methods: file-based polling and HTTP REST API
• AI-ready: Built-in support for Claude Code and other AI assistants
• Real-time control: Modify levels, spawn actors, control playback during runtime

Getting Started

Requirements

• Unreal Engine 5.4, 5.5, 5.6, or 5.7
• Windows (macOS support coming soon)
• Epic Games Launcher for installation

Installation

1. Purchase CLAUDIUS from the Epic Marketplace
2. Open Epic Games Launcher → Library → Vault
3. Find CLAUDIUS and click "Add to Project"
4. Select your project and confirm
5. Open your project and enable the plugin in Edit → Plugins
6. Restart the editor when prompted

After enabling, you'll see "CLAUDIUS initialized" in the Output Log, and the following files appear in your project root:

• claudius_request.json — Write commands here
• claudius_response.json — Responses appear here
• CLAUDE.md — Auto-generated documentation for AI assistants

Communication Methods

File-Based Communication

The simplest integration method. Write a JSON command to claudius_request.json, and CLAUDIUS will process it and write the response to claudius_response.json.

• Polling interval: ~500ms
• Best for: Claude Code, simple scripts, manual testing
• No dependencies: Works with any tool that can read/write files

HTTP REST API

For lower latency and real-time control, use the HTTP endpoint. Commands are sent as POST requests and responses are returned synchronously.

• Default endpoint: http://127.0.0.1:8080/api/v1/commands
• Latency: ~10-50ms
• Best for: Python scripts, automation pipelines, real-time tools

Command Format

All commands follow the same JSON structure:

{
  "command_id": "unique_identifier",
  "category": "level",
  "command": "spawn_actor",
  "params": {
    "class_path": "/Script/Engine.PointLight",
    "location": { "x": 0, "y": 0, "z": 300 },
    "actor_label": "MyLight"
  }
}

Fields

• command_id (string) — Unique identifier for tracking. Can be any string; useful for correlating requests and responses.
• category (string) — The command category (see list below).
• command (string) — The specific command name within the category.
• params (object) — Command-specific parameters. Some commands require no parameters (empty object {}).

Command Categories

Commands are organized into 17 categories. The CLAUDE.md file in your project contains full documentation for every command.

Additional categories include audio, physics, landscape, foliage, and streaming.

Response Handling

Every command returns a standardized response:

{
  "command_id": "unique_identifier",
  "success": true,
  "message": "Spawned actor successfully",
  "timestamp": "2024-12-28T10:30:45.123Z",
  "execution_time_ms": 12.5,
  "output": {
    "actor_name": "MyLight",
    "actor_path": "/Game/Maps/TestMap.TestMap:PersistentLevel.MyLight"
  }
}

Response Fields

• command_id — Echoes back the ID from the request
• success — Boolean indicating if the command succeeded
• message — Human-readable status or error message
• timestamp — ISO 8601 timestamp when the command was processed
• execution_time_ms — How long the command took to execute
• output — Command-specific return data (varies by command)

Error Handling

When a command fails, success will be false and message will contain error details:

{
  "command_id": "spawn_invalid",
  "success": false,
  "message": "Actor class not found: /Script/Engine.InvalidClass",
  "timestamp": "2024-12-28T10:31:00.456Z",
  "execution_time_ms": 2.1,
  "output": null
}

Claude Code Integration

CLAUDIUS is designed to work seamlessly with Claude Code (Anthropic's AI coding assistant).

How It Works

1. When CLAUDIUS loads, it generates a CLAUDE.md file in your project root
2. This file contains complete documentation for all available commands
3. When you open your project in Claude Code, it automatically reads this file
4. You can then ask Claude to perform tasks in natural language

Example Conversation

You: "Spawn 5 point lights in a circle around the origin"

Claude: Creates the appropriate JSON commands and writes them to claudius_request.json, then reports the results.

Best Practices

Use Unique Command IDs

Always use unique command_id values. This helps with debugging and ensures you can correlate requests with responses, especially in async workflows.

Check Success Before Using Output

Always verify success is true before accessing the output field. Failed commands may have null output.

Handle Long Operations

Some commands like build_lighting or render_sequence can take minutes. Use appropriate timeouts or polling strategies for these operations.

Use Actor Labels

When spawning actors, provide meaningful actor_label values. This makes it easier to reference actors in subsequent commands.

Runtime vs Editor Commands

Some commands (like AI/Blackboard control) only work during Play-In-Editor (PIE). Start PIE first with console/start_pie, then execute runtime commands.