Skip to content

README.md

Latest commit

 

History

History
131 lines (97 loc) · 5.51 KB

README.md

File metadata and controls

131 lines (97 loc) · 5.51 KB
Raw

UESpec

UESpec is a UE5 plugin for spec-driven UMG/CommonUI generation and UI test automation. It reads declarative UISpec JSON, validates the schema and support surface, compiles widgets through Unreal commandlets, and exposes structured failure reports for agent-driven repair loops.

The companion MCP server lives at https://github.com/Mithril0rd/uespec-mcp-public.

What

  • Compiles UISpec JSON into Widget Blueprint assets.
  • Dumps the current support surface: UMG/CommonUI widgets, registered ARPG/MMO components, converters, style tokens, signals, and action primitives.
  • Validates spec shape and known symbols before generation.
  • Runs JSON test specs against generated widgets and emits JUnit plus structured failure reports.
  • Provides AngelScript ViewModel integration through manual binding fallback.
  • Ships a Round 6 ARPG/MMO component library slice with 12 built-in components and example HUD/test specs.

Quickstart

Prerequisites:

  • Unreal Engine 5.4.
  • A UE project with CommonUI, ModelViewViewModel, and Angelscript available.
  • This plugin placed under the project or engine Plugins/UESpec directory.

Enable the plugin in the target .uproject:

{
  "Plugins": [
    { "Name": "UESpec", "Enabled": true },
    { "Name": "CommonUI", "Enabled": true },
    { "Name": "ModelViewViewModel", "Enabled": true },
    { "Name": "Angelscript", "Enabled": true }
  ]
}

Build the editor target:

<UE_ROOT>\Engine\Build\BatchFiles\Build.bat UnrealEditor Win64 Development -Project=<PROJECT>.uproject -WaitMutex -NoHotReloadFromIDE

Run the first commandlet to verify the plugin loads and the support surface can be serialized:

<UE_ROOT>\Engine\Binaries\Win64\UnrealEditor-Cmd.exe <PROJECT>.uproject -run=UESpecDumpSupportSurface -Format=json -Output=<PROJECT>\Saved\UESpec\support-surface.json -unattended -NoSplash -NoP4

Validate and compile an example HUD:

<UE_ROOT>\Engine\Binaries\Win64\UnrealEditor-Cmd.exe <PROJECT>.uproject -run=UESpecValidate -SpecFile=<PLUGIN_ROOT>\Examples\HUDs\combat-status-hud.json -Output=<PROJECT>\Saved\UESpec\validate-combat-status.json -unattended -NoSplash -NoP4
<UE_ROOT>\Engine\Binaries\Win64\UnrealEditor-Cmd.exe <PROJECT>.uproject -run=UESpecCompile -SpecFile=<PLUGIN_ROOT>\Examples\HUDs\combat-status-hud.json -OutputDir=/Game/UESpec/Generated -Output=<PROJECT>\Saved\UESpec\compile-combat-status.json -unattended -NoSplash -NoP4

Run a test spec against the generated widget:

<UE_ROOT>\Engine\Binaries\Win64\UnrealEditor-Cmd.exe <PROJECT>.uproject -run=UESpecRunTests -SpecFile=<PLUGIN_ROOT>\Examples\Tests\combat-status-hud.test.json -Report=<PROJECT>\Saved\UESpec\combat-status.junit.xml -JsonReport=<PROJECT>\Saved\UESpec\combat-status.failure-report.json -Output=<PROJECT>\Saved\UESpec\combat-status.result.json -unattended -NoSplash -NoP4 -NullRHI

Architecture

UISpec JSON
    |
    v
UESpecValidate / compiler schema checks
    |
    v
UESpecCompile -> Widget Blueprint assets under /Game/UESpec/Generated
    |
    v
UESpecRunTests -> JUnit + structured failure-report.json

Core modules:

  • UESpecRuntime: runtime widget bases, component registry, support surface data, sample widgets, test runner primitives.
  • UESpecEditor: commandlets, compiler subsystem, binding builder, Widget Blueprint generation.
  • UESpecTests: automation coverage for compiler behavior, AngelScript integration, support surface, and JSON test execution.

Component Library

Round 6 registers these built-in ARPG/MMO components:

  • SkillSlot
  • RedDot
  • HealthBar
  • ResourceBar
  • DamageNumber
  • StatusEffectIcon
  • QuestEntry
  • PlayerNamePlate
  • ItemSlot
  • ItemTooltip
  • EquipmentPanel
  • ChatLine

Example specs live under Examples/Components, Examples/HUDs, and Examples/Tests. The broadest example is Examples/HUDs/round6-showcase-hud.json, which exercises all 12 built-ins.

Companion Repo

uespec-mcp is the agent-facing orchestration layer. It talks to this plugin through the commandlets above and adds:

  • MCP tools for validate, compile, test, support-surface lookup, and autofix.
  • Python mock bridge for offline evals.
  • LLM adapters and JSON Patch proposal handling.
  • Closed-loop failure repair and eval reports.

Use the MCP repo when integrating with Claude Desktop, Codex, or other MCP-capable agents. Use this repo when changing Unreal-side generation, commandlets, runtime widgets, or tests.

Known Limitations

  • The plugin currently targets UE 5.4.
  • bindingMode: "manual" is the supported path for AngelScript ViewModels. Full MVVM FieldNotify parity for AngelScript is not claimed.
  • Complex bind paths with array indexes, such as skills[0].cooldownProgress, are skipped by the binding builder and logged as warnings instead of emitted as hard compiler errors. See docs/round4-report.md section 3.5.
  • AngelScript widget-base inheritance was explored but not promoted to the supported authoring surface.
  • The Round 6 component widgets are lightweight host classes for generation/test coverage, not final production art.
  • Real end-to-end use still requires a local Unreal project and compatible plugin dependencies.

Documentation

  • docs/round4-report.md: AngelScript integration and binding limitations.
  • docs/round5-report.md: structured failure reports and test-runner hardening.
  • docs/round6-report.md: ARPG/MMO component library and showcase.
  • docs/component-library.md: current component inventory.
  • docs/roadmap.md: development timeline and release hardening plan.