UnrealTools

Evidence-driven automation for Unreal Engine and UEFN asset workflows.

What it does | Quickstart | Proof boundaries | Docs

---

UnrealTools is a public automation toolkit for Unreal Engine and UEFN asset work. It gives AI coding agents a small, measurable command surface for importing, editing, validating, observing, exporting, and testing assets with evidence instead of guesswork.

The repository contains a .NET CLI and an Unreal Editor plugin. Together they turn broad asset requests into narrow workflows with deterministic paths, engine calls, quarantine checks, validation gates, hashes, approval packets, rollback records, and structured reports an agent can read and act on.

UnrealTools is an independent project. It is not affiliated with or endorsed by Epic Games, Unreal Engine, UEFN, Fortnite, or OpenAI.

What It Does

• Import, edit, and repair assets: run narrow CLI flows and UE-side automation instead of manual editor steps.
• Quarantine external files: hold downloaded content behind provenance, license, file-type, and safety checks before it enters real project paths.
• Validate with Unreal: use commandlet flows and live-editor paths where the engine is the meaningful source of truth.
• Observe and report: produce JSON reports, logs, hashes, and rendered observations that are useful to both maintainers and agents.
• Approve before writes: generate approval packets before changing a target project.
• Export with evidence: move .uasset package sets with rollback manifests and SHA-256 hashes, including UEFN content-directory staging.
• Separate the claims: keep file staging, engine visibility, and publishing as distinct gates.
• Gate the software in CI: run deterministic .NET CLI and report-contract checks without pretending GitHub Actions proves real Unreal runtime behavior.

Proof Boundaries

UnrealTools is intentionally conservative about what each report proves.

• Engine proof means the configured Unreal Editor or commandlet workflow produced the reported validation, observation, build, or audit evidence.
• File-staging proof means exported package files match recorded size and SHA-256 evidence at the configured destination.
• CI proof means the no-engine .NET harness, command dispatch, safety checks, and report contracts behaved deterministically on GitHub Actions or a local machine. It is not a substitute for engine proof.
• Visibility and publishing are separate gates. Do not treat a clean process exit or a staged file copy as proof of platform ingestion or publishability.
• Moderation, memory calculation, review, and platform-owned outcomes are manual or platform-owned gates unless a current report proves that exact gate.

The project favors precise, narrow reports over broad success claims.

Prerequisites

• Windows with PowerShell.
• .NET SDK 9.0.
• Git and Git LFS.
• Unreal Engine 5 for real-engine workflows.

Runtime state, reports, packets, logs, rollback manifests, and observations are written under .codexuefn/. That directory is local-only and ignored by Git.

Quickstart

git clone https://github.com/ThatNerdChris/UnrealTools.git
cd UnrealTools
git lfs install
git lfs pull

dotnet build .\src\CodexUefnTools.Cli\CodexUefnTools.Cli.csproj -c Release
dotnet run --project .\tests\CodexUefnTools.Tests\CodexUefnTools.Tests.csproj -c Release

Configure your local project paths. Use paths from your own machine; these examples show the expected shape:

$SandboxProject = "C:\UnrealProjects\UnrealToolsSandbox\UnrealToolsSandbox.uproject"
$UefnProject = "$env:USERPROFILE\Documents\Fortnite Projects\MyIsland"

dotnet run --project .\src\CodexUefnTools.Cli\CodexUefnTools.Cli.csproj -c Release -- init --sandbox $SandboxProject --uefn $UefnProject

Install and build the Unreal plugin for the configured project:

dotnet run --project .\src\CodexUefnTools.Cli\CodexUefnTools.Cli.csproj -c Release -- install-plugin --json
dotnet run --project .\src\CodexUefnTools.Cli\CodexUefnTools.Cli.csproj -c Release -- build-plugin --json

Run common evidence commands:

dotnet run --project .\src\CodexUefnTools.Cli\CodexUefnTools.Cli.csproj -c Release -- capability --json
dotnet run --project .\src\CodexUefnTools.Cli\CodexUefnTools.Cli.csproj -c Release -- crash-status --json
dotnet run --project .\src\CodexUefnTools.Cli\CodexUefnTools.Cli.csproj -c Release -- builddoc-audit --json

Asset-specific commands depend on the domain and runtime. Prefer the narrowest command that proves the behavior you changed, and keep .codexuefn/ outputs out of commits.

Repository Layout

Path	What's there
src/CodexUefnTools.Cli/	.NET CLI and asset-workflow orchestration.
tests/CodexUefnTools.Tests/	Deterministic CLI and report-contract tests.
unreal/CodexAssetAutomation/	Unreal Editor plugin and commandlets.
scripts/	Validation and smoke-test helpers.
skills/	Repo-local agent workflow guidance.
test-assets/	Small fixtures with documented provenance.
docs/	Current limits, evidence notes, and supporting documentation.

Documentation

• Historical evidence index points to older evidence files. Treat those as historical proof notes, not setup instructions.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md, keep changes scoped, and include the narrowest deterministic proof command for the behavior you changed.

Security

Please report security issues privately. See SECURITY.md.

Support

Use GitHub Issues for reproducible UnrealTools bugs, docs gaps, and focused feature requests. See SUPPORT.md for scope and Epic/Unreal support boundaries.

License

UnrealTools is licensed under the MIT License.