CLAUDIUS v3.1.0 is live — the curation update for AI-driven Unreal Engine work
If you’re new here: CLAUDIUS is an Unreal Engine plugin that exposes ~230 editor operations as JSON commands so any AI assistant (Claude Code, Cursor, Codex, plain Python scripts) can drive the editor — spawn actors, edit Blueprints, render cinematics, ingest CAD, run editor Python, the lot. Local-only, no third-party servers, BYO model.
This is the biggest release the project has ever had and it changes how the plugin feels day-to-day. v2.x was “200 commands, hope your AI’s context window holds up.” v3 is “the AI sees only what your project actually needs.” Below is everything that’s different, what got fixed, and how to migrate.
TL;DR
-
Per-project command curation — AI sees ~100 commands tuned to your project, not 230.
-
In-editor Setup & Commands window — Slate UI for browsing, toggling, applying presets, managing skill packs.
-
Workflow presets — fps / platformer / level_design / animation / animation_studio / open_world / minimal / everything. One click swaps the surface.
-
Skill packs — folder format for shareable command bundles. Bundled fps_starter and animation_studio.
-
User-extensible Python — drop a .py with @claudius headers into a folder, it joins the registry.
-
Safe CLAUDE.md handling — plugin owns Claudius/CLAUDIUS.md, never overwrites your CLAUDE.md, auto-creates a minimal one if you don’t have one.
-
Control Rig + Live Link Python wrappers for shot-based studios.
-
Skills YAML parser fixed — every parameter and action used to silently drop. Not anymore.
-
spawn_actor mesh fix — mesh_path was silently ignored on StaticMeshActor. Now honored.
-
UE 5.4 – 5.7, Win/Mac/Linux.
The big idea: curation
The reason v3 exists. The plugin shipped with 130 commands in v2.0, 165 in v2.1, 230 in v2.2/v3.x. Every command’s full documentation went into a CLAUDE.md that landed in your project root, and your AI loaded the whole thing on every session. By v2.2 that was burning ~12,000 tokens of context before you’d typed a word, and you were paying for the AI to read the docs of commands it would never call.
v3 fixes this with a registry. Every command — built-in, your custom Python, skill-pack — is tracked with category, description, workflow tags, and an enabled flag. Your CLAUDIUS.md is regenerated to include the full index of every command (one line each, ~100 chars) plus detailed docs only for the commands enabled in your project. Disabled commands stay listed so the AI can suggest enabling one when relevant (“I see viewport.set_post_process in the index but it’s disabled — want me to turn it on?”), but they don’t bloat context.
A typical FPS preset enables ~95 commands. A minimal preset is ~50. everything is the old behavior. Pick what fits.
In-editor Setup & Commands window (Slate)
Tools → Claudius → Open CLAUDIUS Setup & Commands. Auto-opens once on a fresh project.
-
Header: live count of enabled / total commands and an estimated CLAUDE.md token cost.
-
CLAUDE.md integration section: shows whether your project’s CLAUDE.md references our file, with one-click “Add @Claudius/CLAUDIUS.md to CLAUDE.md” that safely appends one line (or creates a minimal stub if the file doesn’t exist). Never modifies your existing notes.
-
Policy for disabled commands: three radio cards.
-
Ask first (default) — disabled command requests return a command_disabled payload with the enable-line spelled out so the AI can ask permission.
-
Auto-enable silently — flips on any disabled command on first use, logs in recent_auto_enables.
-
Strict — disabled commands hard-fail. For demos and reviews.
-
Ask Claude to build a command — type a goal, get a generated prompt that instructs Claude to: (1) help.find to check what already exists, (2) describe the closest UE Python API and ask permission, (3) call config.create_command with name/body/category/description/tags. “Send to Claude” button writes the prompt to Claudius/inbox/task.md and flags it in CLAUDE.md so your live Claude session picks it up on its next turn.
-
Workflow Presets — 8 one-click buttons.
-
Commands — filter box at top, then 26 collapsible categories. Inside each: virtualized command rows (we use SListView so scrolling 230 entries stays smooth) with per-command checkboxes. Names + ellipsis-truncated descriptions, full text in tooltip. Toggle a checkbox → config saves + CLAUDE.md regenerates + only the affected row repaints. Persistent expansion state: toggling a command no longer collapses the category.
-
Skill Packs — list of installed packs with enable-all / disable-all per pack.
-
Create — new Command / Skill / Pack — three forms. Author a custom Python command without leaving the editor, scaffold a YAML skill, or stamp out a fresh skill pack with manifest + starter .py. Discovery + CLAUDE.md regen happen automatically.
-
Footer: regenerate CLAUDIUS.md, open CLAUDIUS.md, open config.json.
If you’re not running an editor (CI, headless), every action above also has a JSON command counterpart. The Slate window is a convenience over the meta-command API — not a wrapper that hides power.
Workflow presets
Apply with a click in the Setup window or {"category":"config","command":"load_preset","parameters":{"preset":"fps"}}.
| Preset |
Optimized for |
fps |
First-person shooter / shooter scaffolding |
platformer |
3D platformers, mascot-style projects |
level_design |
Whitebox + procedural level work |
animation |
Anim asset authoring (montages, blend spaces, anim BPs) |
animation_studio |
Shot-based commercial animation: explainers, forensic recreations, historical recreations. Sequencer + MRQ + asset ingest + level layout. |
open_world |
Streaming, landscape, vegetation, World Partition |
minimal |
Just core actor/level/blueprint primitives. ~50 commands. |
everything |
All 230. v2.x compatibility mode. |
Presets only adjust the enabled set. Your custom user commands and skill packs stay where you put them.
Skill packs
Folders under {Project}/Claudius/SkillPacks/{pack_name}/ with a manifest.json plus one or more Python command files. The plugin discovers and registers them at startup. Two reference packs ship in v3.1:
fps_starter (in Resources/SkillPacks/fps_starter/)
animation_studio (new in v3.1)
-
batch_ingest_fbx — bulk FBX import with material slotting.
-
setup_camera_rig — multi-camera cinematic rig setup.
-
exploded_view — radial separation of mesh components for technical-explainer shots.
-
render_shot — Sequencer + Movie Render Queue render orchestration.
-
material_swap_reveal — material-swap reveal animation helper.
Status note: animation_studio pack is v0.1 — usable as scaffolding, expects studio-specific variants once you’ve used it on a real shot. The preset itself (curation + categories) is stable.
Bundled packs are auto-copied to your project on first launch. You can edit them freely (your edits aren’t overwritten on subsequent updates).
Manifest format:
{
"name": "my_pack",
"version": "1.0.0",
"author": "you",
"description": "one-line summary",
"workflow_tags": ["fps", "combat"]
}
pack.install, pack.uninstall, pack.enable, pack.disable, pack.list are always-on meta-commands.
User-extensible Python commands
Drop any .py with an execute(params) function into {Project}/Claudius/UserCommands/. Add @claudius metadata headers and it joins the registry as a first-class member of the index:
# @claudius category: combat
# @claudius description: Spawn a weapon pickup at a location.
# @claudius workflow: fps, weapons
import unreal
def execute(params):
return {"success": True, "message": "...", "output": {...}}
@claudius category defaults to custom if omitted. Any category you specify gets its own JSON route automatically — {"category": "combat", "command": "<filename>"} works without touching C++.
config.create_command is also a thing — your AI can author a new custom command end-to-end without you opening a Python editor.
Safe CLAUDE.md handling
The biggest fix for buyers who got burned by v2 silently overwriting their CLAUDE.md. The complaint was legit. v3 hard-promises:
-
The plugin owns {Project}/Claudius/CLAUDIUS.md — auto-generated index plus full docs for enabled commands. Regenerated on any toggle. Yours to read, never to edit (changes get overwritten).
-
The plugin never modifies an existing {Project}/CLAUDE.md. Period.
-
If your project has no CLAUDE.md at all (typical for brand-new UE projects), the plugin auto-creates a minimal stub with # Project Notes and an @Claudius/CLAUDIUS.md reference line. Brand-new users get the integration without clicking anything; the safety guarantee for existing files isn’t affected because there’s nothing to preserve.
-
If your CLAUDE.md exists but doesn’t reference us, the Setup window’s “Add @Claudius/CLAUDIUS.md to CLAUDE.md” button safely appends one line. Optional, idempotent, and prefixed with an HTML comment explaining where the include came from so future-you isn’t confused.
If you’re a v2 user with an existing CLAUDE.md, your file isn’t touched on upgrade. Click the button or paste @Claudius/CLAUDIUS.md into your CLAUDE.md once and you’re done.
Curation meta-commands (always enabled)
Live in the registry as config.*, help.*, pack.*, user.*. Always available regardless of preset.
| Category |
Commands |
config |
status, set_auto_enable_policy, enable_command / disable_command, enable_category / disable_category, load_preset, list_presets, export_profile / import_profile, regenerate_claude_md, create_command, delete_command, clear_inbox |
help |
ping, find, list_categories, list_disabled, list_packs |
pack |
install, uninstall, enable, disable, list |
user |
list_commands, reload_commands, plus your scripts |
config.status and regenerate_claude_md now return unambiguous fields (claudius_md_path, user_claude_md_path, user_claude_md_state ∈ linked / not_linked / missing). Legacy claude_md_path is retained as an alias for backwards compat.
Control Rig and Live Link
Animation studios — this one’s for you. Both categories shipped as Python-backed wrappers in v3.1, all commands real:
control_rig.* (7 commands)
-
list_rigs, get_rig_info — inspect Control Rig assets.
-
set_control_value — scalar or {x,y,z[,pitch,yaw,roll]} value object → rig.set_control_value(name, value).
-
get_control_value — reads via rig.get_control_value(name).
-
set_pose — bulk-apply via controls{name: value} dict; reports applied=N failed=M and lists each failure.
-
bake_to_animation — given rig_path + skeletal_mesh_path + output_path, creates a target AnimSequence of the requested length on the matching skeleton. Honest scope: writes the asset, leaves curve population to a Sequencer Control Rig track.
-
retarget_animation — two paths: target_skeleton_path for simple skeleton swap, or ik_retargeter_path for proper IK Retargeter via IKRetargetBatchOperation.duplicate_and_retarget.
live_link.* (5 commands)
-
list_sources, list_subjects.
-
get_subject_data — LiveLinkBlueprintLibrary.evaluate_live_link_subject with role detection (default LiveLinkAnimationRole, override via role param).
-
start_recording / stop_recording — drives the Take Recorder panel programmatically. Optional slate, take_number, and source_subject (auto-adds a Live Link source).
Take Recorder must be enabled (UE-shipped, not third-party). Both categories are in the animation_studio preset by default.
Skills system fixes (huge for v2 users)
The YAML parser had a long-standing bug: parameters: and actions: list items used - key: value form, and the parser checked for : before the - list marker, miscategorizing every list row as key="- name" and silently dropping every parameter and action. create_skill produced YAML that was technically valid and entirely non-functional. execute_skill returned success: true with (0 actions).
Fixed by swapping the priority of those two checks. Skills now parse correctly. Both YAML forms (- key: value and the bare-dash-on-its-own-line form) work. Existing broken skills will start working on first load — no migration needed.
Reported by Pete Batchelor — thanks for the clean repro steps.
Mesh-swap commands
Reported by Oliver during Lyra FPS work: level.spawn_actor accepted a mesh_path parameter on StaticMeshActor and silently dropped it. Fixed and three new setters added:
-
level.spawn_actor now honors mesh_path for StaticMeshActor / SkeletalMeshActor classes (with a warning surface if the param can’t be applied).
-
level.set_static_mesh (actor_name, mesh_path) — swap mesh on an existing StaticMeshActor.
-
level.set_skeletal_mesh (actor_name, mesh_path) — same for SkeletalMeshActor.
-
blueprint.set_component_mesh (blueprint_path, component_name, mesh_path) — set the mesh on an SCS mesh component in a Blueprint CDO. Auto-detects static vs skeletal.
Performance: the Setup window
Initial v3 builds had visible scroll lag in the Commands section because every category inflated all its rows upfront — ~1000 live Slate widgets. v3.1 fixes:
-
Lazy category bodies — collapsed categories have zero child widgets. Bodies build on expansion.
-
SListView virtualization inside each category — only on-screen rows get widgetized.
-
Ellipsis descriptions — replaced AutoWrapText with single-line ellipsis + tooltip. Killed hundreds of layout calls per arrange pass.
-
Surgical state updates — toggling a checkbox no longer rebuilds the tree. IsChecked is a lambda on Config, header counts use TAttribute<FText>.
-
AI prompt preview collapsed by default — used to be a 220px live multi-line editor visible at all times.
Net: scrolling through all 26 categories is smooth even on lower-end hardware.
Behind-the-scenes housekeeping
-
ULevelSequenceEditorBlueprintLibrary::SetCurrentTime / GetCurrentTime deprecation warnings on UE 5.7 wrapped in PRAGMA_DISABLE_DEPRECATION_WARNINGS — builds warning-clean across 5.4–5.7. Will port to FMovieSceneSequencePlaybackParams properly in v3.2 once we can test the new API on every supported engine.
-
Missing Animation/SkeletalMeshActor.h and Components/SkeletalMeshComponent.h includes added — without these, the mesh-swap commands wouldn’t compile on any engine.
-
Per-engine ZIPs ship with EngineVersion injected (5.4.0 / 5.5.0 / 5.6.0 / 5.7.0) so FAB packages cleanly per slot.
Migration notes
From v2.x:
-
No breaking changes to existing command shapes. Every JSON call you have today still works.
-
On first launch in a v2 project, v3 writes a default config, discovers existing user commands, and generates Claudius/CLAUDIUS.md. Your CLAUDE.md is untouched.
-
Click the Add @Claudius/CLAUDIUS.md to CLAUDE.md button (or paste that line manually) to wire up the new include flow.
-
If you never click it, everything still works via JSON; Claude Code just won’t auto-discover the curated index.
From v1.x:
- See migration above. v1 → v2 → v3 in one hop is supported. Older
claudius_request.json formats are still valid.
Custom Python commands written for v2:
- They keep working. Add
@claudius headers when you have a moment to make them first-class registry citizens (better names in CLAUDE.md, workflow tags, etc.).
Custom YAML skills written before v3.1:
- The Skills parser fix is retroactive — your existing YAML starts parsing correctly without any change to the file.
Engine and platform support
-
UE 5.4, 5.5, 5.6, 5.7 — all builds clean Win64. FAB compiles Mac and Linux server-side.
-
Required UE plugins: EditorScriptingUtilities, MovieRenderPipeline, PCG. Optional: PythonScriptPlugin (without it: built-ins all work, user-extensible Python doesn’t).
Known gaps and roadmap
Honest list of what v3.1 doesn’t solve:
-
DCC bridges (Maya / Blender / C4D round-trip) — separate companion plugin work, not part of CLAUDIUS core. Open to scoping per-studio if there’s interest.
-
Forensic audit trail for criminal-reconstruction work — bespoke per engagement.
-
MCP server shim — wrapping the existing HTTP endpoint so Claude Desktop / Cursor / anything-MCP can talk to CLAUDIUS natively. Coming, lower priority than the curation work was.
-
bake_to_animation curve population — creates the destination AnimSequence with the right skeleton + length, but leaves curve population to a Sequencer Control Rig track. Will harden with real production hours.
-
MovieScene API migration — the deprecation suppressions land in v3.2 with a proper port to FMovieSceneSequencePlaybackParams.
