From 7563201d54986ee99fca4bea4714a66645fc684b Mon Sep 17 00:00:00 2001 From: StillHammer Date: Tue, 20 Jan 2026 11:41:44 +0700 Subject: [PATCH] Add complete specification and update README --- README.md | 2 +- docs/SPEC.md | 395 +++++++++++++++++++++++++++++++++++++++++++++ tmpclaude-4a3e-cwd | 1 + 3 files changed, 397 insertions(+), 1 deletion(-) create mode 100644 docs/SPEC.md create mode 100644 tmpclaude-4a3e-cwd diff --git a/README.md b/README.md index c713480..fcad8f6 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ AI-powered Unreal Engine development - Generate C++ code, Blueprint conversions, ## Status: Setup phase -See ../UNREAL_MCP_SPEC.md for complete specifications. +See [docs/SPEC.md](docs/SPEC.md) for complete specifications. ## Features diff --git a/docs/SPEC.md b/docs/SPEC.md new file mode 100644 index 0000000..c81d4fd --- /dev/null +++ b/docs/SPEC.md @@ -0,0 +1,395 @@ +# Unreal Engine MCP Server - Technical Specification + +**Project** : AI-powered Unreal Engine development via MCP +**Target** : Unreal developers, AAA studios, technical designers +**Stack** : TypeScript + FastMCP + Claude API +**Timeline** : 2-3 weeks MVP + +--- + +## šŸŽÆ What is it? + +MCP server enabling Claude Desktop to generate Unreal C++ code, Blueprint logic descriptions, debug issues, and optimize performance using AI. + +**Key Features** : +āœ… Generate Unreal C++ classes (.h + .cpp) from natural language +āœ… Blueprint ā†’ C++ conversion for performance +āœ… Create complete gameplay systems (weapons, abilities, inventory) +āœ… Debug Unreal code with AI assistance +āœ… Performance analysis (profiling, optimization) +āœ… Network replication code generation +āœ… Animation Blueprint logic + +--- + +## šŸ”§ MCP Tools + +### C++ Generation + +**create_unreal_class** - Generate UE C++ class +```typescript +Input: "Create ACharacter subclass with sprint and crouch" +Output: +- MyCharacter.h (with UCLASS, UPROPERTY, UFUNCTION macros) +- MyCharacter.cpp (implementation) +``` + +**generate_gameplay_system** - Complete systems +```typescript +Input: "Create weapon system with ammo, reload, and firing modes" +Output: +- AWeapon.h/.cpp (weapon actor) +- UWeaponComponent.h/.cpp (component for characters) +- FWeaponData.h (data struct) +- Network replication setup +``` + +**generate_actor_component** - UActorComponent classes +```typescript +Input: "Health component with damage, healing, and death" +Output: UHealthComponent with proper UE architecture +``` + +--- + +### Blueprint Tools + +**blueprint_to_cpp** - Convert BP logic to C++ +```typescript +Input: Description of Blueprint logic or visual graph +Output: Optimized C++ equivalent with notes on performance gains +``` + +**generate_blueprint_library** - Blueprint Function Library +```typescript +Input: "Math utilities for gameplay (lerp, easing, etc.)" +Output: UBlueprintFunctionLibrary with static functions callable from BP +``` + +--- + +### AI-Powered Tools + +**debug_unreal_code** - AI debugging +```typescript +Input: C++ code + crash logs + callstack +Output: Root cause + fixed code + prevention tips +``` + +**optimize_unreal_performance** - Performance analysis +```typescript +Input: Unreal C++ code + optional profiler data +Analysis: +- Tick() function overhead +- Blueprint vs C++ performance comparison +- Rendering optimization suggestions +- Memory leak detection +- Thread safety issues +- Network replication bandwidth +Output: Optimized code + profiling recommendations +``` + +**analyze_crash_dump** - Crash analysis +```typescript +Input: Crash log + callstack +Output: Probable causes + fix suggestions +``` + +--- + +### Network & Multiplayer + +**generate_replicated_actor** - Network replication +```typescript +Input: "Replicated projectile with client prediction" +Output: +- C++ class with UPROPERTY(Replicated) +- GetLifetimeReplicatedProps implementation +- Client-side prediction code +- Server RPC functions +``` + +**optimize_network_bandwidth** - Replication analysis +```typescript +Input: Replicated class code +Output: Bandwidth optimization suggestions (relevancy, replication conditions) +``` + +--- + +### Advanced Tools + +**generate_animation_system** - Animation logic +```typescript +Input: "Animation system with blending and state machines" +Output: Animation Blueprint logic description + C++ notify classes +``` + +**generate_subsystem** - UE Subsystem +```typescript +Input: "Game instance subsystem for save/load" +Output: UGameInstanceSubsystem class with proper lifecycle +``` + +**generate_slate_ui** - Slate UI code +```typescript +Input: "Custom editor widget for level design" +Output: Slate C++ code for editor customization +``` + +--- + +## šŸ—ļø Architecture + +``` +Unreal MCP Server + ā†“ Claude API +Generate C++ files locally + ā†“ +User adds to Unreal project + ā†“ +Compile in Unreal Editor +``` + +**Note** : No direct Unreal Editor integration - generates files only + +--- + +## šŸ’¼ Use Cases + +### Gameplay Programming +- Weapon systems +- Ability systems +- AI controllers +- Inventory systems + +### Performance Optimization +- Blueprint ā†’ C++ migration +- Reduce tick overhead +- Network optimization +- Memory profiling + +### Multiplayer Development +- Replicated actors +- Server RPCs +- Client prediction +- Authority validation + +### Technical Design +- Custom editor tools +- Asset pipeline automation +- Blueprint libraries + +--- + +## šŸ“Š Target Market + +- **5M+ Unreal developers** worldwide +- AAA game studios +- Indie teams using Unreal +- Technical designers +- Multiplayer game developers +- VR/AR experiences (Unreal is strong here) + +**Revenue Potential** : ā‚¬10k-50k/project (higher than Unity, more enterprise) + +--- + +## šŸš€ Implementation Timeline + +**Week 1** : Core C++ generation (classes, components, basic systems) +**Week 2** : Blueprint tools (BPā†’C++, libraries) +**Week 3** : Advanced (networking, optimization, debugging) + +**MVP** : 2-3 weeks + +--- + +## šŸ“ Example Output Quality + +### Input +``` +"Create a replicated weapon with firing, ammo, and reload for multiplayer FPS" +``` + +### Output +```cpp +// Weapon.h +#pragma once + +#include "CoreMinimal.h" +#include "GameFramework/Actor.h" +#include "Weapon.generated.h" + +UCLASS() +class MYGAME_API AWeapon : public AActor +{ + GENERATED_BODY() + +public: + AWeapon(); + + virtual void GetLifetimeReplicatedProps(TArray& OutLifetimeProps) const override; + + UFUNCTION(BlueprintCallable, Category = "Weapon") + void Fire(); + + UFUNCTION(BlueprintCallable, Category = "Weapon") + void Reload(); + +protected: + virtual void BeginPlay() override; + + UFUNCTION(Server, Reliable, WithValidation) + void ServerFire(); + + UFUNCTION(NetMulticast, Unreliable) + void MulticastPlayFireEffects(); + + UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category = "Weapon") + int32 MaxAmmo = 30; + + UPROPERTY(ReplicatedUsing = OnRep_CurrentAmmo, BlueprintReadOnly, Category = "Weapon") + int32 CurrentAmmo; + + UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category = "Weapon") + float FireRate = 0.1f; + + UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category = "Weapon") + float ReloadTime = 2.0f; + +private: + UFUNCTION() + void OnRep_CurrentAmmo(); + + float LastFireTime = 0.0f; + bool bIsReloading = false; + + void ConsumeAmmo(); + bool CanFire() const; +}; + +// Weapon.cpp +#include "Weapon.h" +#include "Net/UnrealNetwork.h" +#include "TimerManager.h" + +AWeapon::AWeapon() +{ + PrimaryActorTick.bCanEverTick = false; + bReplicates = true; + CurrentAmmo = MaxAmmo; +} + +void AWeapon::GetLifetimeReplicatedProps(TArray& OutLifetimeProps) const +{ + Super::GetLifetimeReplicatedProps(OutLifetimeProps); + + DOREPLIFETIME_CONDITION(AWeapon, CurrentAmmo, COND_OwnerOnly); +} + +void AWeapon::Fire() +{ + if (!CanFire()) return; + + if (HasAuthority()) + { + ServerFire(); + } + else + { + ServerFire(); + // Client prediction: play effects immediately + MulticastPlayFireEffects(); + } +} + +bool AWeapon::ServerFire_Validate() +{ + return CanFire(); +} + +void AWeapon::ServerFire_Implementation() +{ + if (!CanFire()) return; + + ConsumeAmmo(); + LastFireTime = GetWorld()->GetTimeSeconds(); + + // Perform hit detection + // ... + + MulticastPlayFireEffects(); +} + +void AWeapon::MulticastPlayFireEffects_Implementation() +{ + // Play muzzle flash, sound, etc. + // ... +} + +void AWeapon::Reload() +{ + if (bIsReloading || CurrentAmmo == MaxAmmo) return; + + bIsReloading = true; + + FTimerHandle ReloadTimer; + GetWorld()->GetTimerManager().SetTimer(ReloadTimer, [this]() + { + CurrentAmmo = MaxAmmo; + bIsReloading = false; + }, ReloadTime, false); +} + +void AWeapon::ConsumeAmmo() +{ + CurrentAmmo = FMath::Max(0, CurrentAmmo - 1); +} + +bool AWeapon::CanFire() const +{ + const float CurrentTime = GetWorld()->GetTimeSeconds(); + return !bIsReloading + && CurrentAmmo > 0 + && (CurrentTime - LastFireTime) >= FireRate; +} + +void AWeapon::OnRep_CurrentAmmo() +{ + // Update UI + // ... +} +``` + +**Quality** : Production-ready multiplayer code with proper replication, validation, client prediction + +--- + +## šŸŽÆ Unique Value + +- āœ… Proper Unreal macros (UCLASS, UPROPERTY, UFUNCTION) +- āœ… Network replication out of the box +- āœ… Client prediction patterns +- āœ… Authority validation +- āœ… Follows Epic coding standards +- āœ… Optimized for performance +- āœ… Both .h and .cpp generated + +--- + +## šŸ’” Why Separate from Unity? + +**Completely different ecosystems** : +- Unity = C#, .NET, MonoBehaviour, ScriptableObject +- Unreal = C++, Blueprints, UCLASS/UPROPERTY macros, replication + +**Different markets** : +- Unity = Indie, mobile, smaller teams +- Unreal = AAA, high-end graphics, larger budgets + +**Separate projects = Better focus** + +--- + +**Last Updated** : 2026-01-19 diff --git a/tmpclaude-4a3e-cwd b/tmpclaude-4a3e-cwd new file mode 100644 index 0000000..00ecaf4 --- /dev/null +++ b/tmpclaude-4a3e-cwd @@ -0,0 +1 @@ +/c/Users/alexi/Documents/projects/freelance_planning/unreal-mcp