---
name: ue5-unreal
description: >
  Unreal Engine 5 development assistant — log analysis, asset auditing,
  engine-docs research, and Python script generation via Spaghetti Unreal AI
  Workbench. Call these tools when the user is working in a UE5 project and
  needs expert help with log errors or crashes, asset cleanup, engine docs,
  or editor automation.
---

# UE5 Unreal AI Workbench Tools

This skill provides access to Spaghetti's Unreal AI Workbench MCP tools.
These tools run on a remote server (`mcp.spaghetti.gg`) and require
authentication via OAuth (your client handles this automatically on first
connect — a browser window opens for sign-in at spaghetti.gg).

## Prerequisites

The user must have signed in at [spaghetti.gg](https://spaghetti.gg) at least
once (accounts and welcome credits are created on first sign-in).

A `.spaghetti` file at the UE5 project root (`team_id`, `project_id`) is
optional — without it, calls bill the user's personal wallet and everything
works except the two project-scoped research tools (`search_logs_temporal`,
`investigate_incident`). If you see a "no user account exists" error, point
the user at the portal sign-in; if you see "not a member of team", the
`.spaghetti`/headers point at the wrong team.

## Available tools

### Log Analyzer (`spaghetti/analyze_logs`)

**When to call:** The user reports errors or a crash in their UE5 project and
has a log file (for example `Saved/Logs/<Project>.log`, or a crash log).

**What it does:** Full-log analysis — structured findings with severity and
evidence, crash triage naming the suspect Blueprint, and statistics. Uploads
are session-based; large logs never flow through chat.

**Input:** A local log path (`logPath`) to start a session, or pasted log
text (`logText`) as the fallback path.

**Cost:** 5 credits per session, billed only when analysis runs — empty logs
or logs with no Error/Fatal entries are free. Retries never bill twice.

**Safety:** Read-only analysis. Does not modify project files.

### Asset Janitor (`spaghetti/tidy_assets`)

**When to call:** The user asks about asset cleanup, naming conventions,
unused assets, missing LODs, or compliance reports.

**What it does:** Audits a project asset inventory — unused assets with
reclaimable sizes, redirectors, naming-convention violations, LOD problems —
and returns a prioritized report plus a downloadable CSV.

**Input:** An inventory JSONL path. With the UE connector plugin installed,
call its `export_asset_inventory` tool in the editor first (it writes
`Saved/spaghetti_inventory.jsonl`); without it, a short Python-console script
produces the same file.

**Cost:** 3 credits per session, billed only when a report is produced.

**Safety:** Audit is read-only. If the user wants to apply fixes, use
Tool-Maker to generate a dry-run script first.

### Research tools (free)

- `search_docs_code` — hybrid search over curated UE engine documentation.
- `search_patterns` — recommended engine approaches vs anti-patterns for a described intent.
- `search_logs_temporal` — time/severity/subsystem-filtered search over logs previously ingested by `analyze_logs`. Requires project context.
- `query_temporal_relations` — entity-relation traversal over ingested logs (up to 3 hops, optionally as of a point in time).
- `investigate_incident` — bounded investigation combining logs, relations, docs, and patterns. Requires project context.

### Tool-Maker (`spaghetti/make_tool`)

**When to call:** The user wants to automate a UE5 editor task (batch-rename
assets, apply settings, generate reports, etc.).

**What it does:** Generates an editor-automation Python script from a
natural-language description of the task.

**Safety — three-layer model:**
1. **API allowlist:** only approved editor APIs.
2. **Dry run:** delivered scripts are simulation transforms — destructive
   operations commented out, reversible operations wrapped in
   `unreal.ScopedTransaction` for undo support.
3. **Human approval:** the user Approves/Declines via the client's approval
   flow. Billed 10 credits only on approval; blocked, declined, and
   cancelled runs are free.

**Always show the generated script to the user before executing.**

## Safety defaults

- **Never auto-delete assets** without explicit user confirmation.
- **Prefer dry-run mode** for any script that modifies the project.
- **Use ScopedTransaction** for reversible operations (enables Ctrl+Z).
- **Read the Output Log** for errors after any automated editor operation.

## Billing

Tool calls bill the user's personal wallet, or the team wallet when team
context is set. If you see `402 Payment Required` / "Insufficient credits",
call the free `topup` tool to create a checkout link, or direct the user to
`spaghetti.gg/billing` to top up.