Skip to main content

Setup Guide

Complete installation and configuration guide for ElysGenAIPlugin.

Prerequisites​

Software Requirements​

  • Unreal Engine 5.6+ (compatible with 5.0+)
  • Visual Studio 2022 (Windows) or Xcode (Mac)
  • Git (for cloning/downloading)

Hardware Requirements​

  • CPU: Modern multi-core processor (Intel i5/AMD Ryzen 5 or better)
  • RAM: 8GB minimum, 16GB recommended
  • Storage: 5GB for plugin and bundled models
  • Microphone: Required for STT features

Installation​

  1. Download the latest release from GitHub Releases
  2. Extract to your project's Plugins folder: 
    YourProject/
    └── Plugins/
        └── ElysGenAIPlugin/
  3. Continue to Enable Plugin

Method 2: Clone from GitHub​

cd YourProject/Plugins
git clone https://github.com/RogueParadigm/ElysGenAIPlugin.git

Enable Plugin​

  1. Open YourProject.uproject in a text editor
  2. Add ElysGenAIPlugin to the Plugins array:
{
  "FileVersion": 3,
  "EngineAssociation": "5.6",
  "Plugins": [
    {
      "Name": "ElysGenAIPlugin",
      "Enabled": true
    }
  ]
}

Option B: Enable in Editor​

  1. Open your project in Unreal Editor
  2. Go to Edit → Plugins
  3. Search for "ElysGenAI"
  4. Check the Enabled checkbox
  5. Restart the editor when prompted

Regenerate Project Files​

After enabling the plugin:

  1. Close Unreal Editor if it's open
  2. Right-click your .uproject file
  3. Select Generate Visual Studio Project Files (Windows) or Generate Xcode Project (Mac)
  4. Wait for generation to complete

Compile Plugin​

In Editor (Automatic)​

  1. Open your project in Unreal Editor
  2. Editor will automatically compile the plugin
  3. Wait for "Compiling ElysGenAIPlugin..." to finish

From IDE (Manual)​

Visual Studio (Windows)​

  1. Open YourProject.sln
  2. Set build configuration to Development Editor
  3. Build solution (Ctrl+Shift+B)

Xcode (Mac)​

  1. Open YourProject.xcworkspace
  2. Set scheme to YourProjectEditor
  3. Build (Cmd+B)

Verify Installation​

Check Logs​

Open Output Log in Unreal Editor and look for:

LogElysGenAI: ElysGenAIPlugin loaded successfully
LogElysGenAI: Found 4 modules: Core, Audio, STT, LLM

Test Component​

  1. Open any Blueprint (e.g., PlayerController)
  2. Click Add Component
  3. Search for "Elys"
  4. You should see:
    • ERP_STTComponent
    • ERP_LLMComponent

If components appear, installation was successful!

Model Downloader​

ElysGenAIPlugin includes a flexible model downloader for both editor and packaged games.

Editor Downloads (Development)​

Use UERP_ModelDownloaderEditorSubsystem during development.

Method 1: Menu (Easiest)​

  1. Open Unreal Editor
  2. Go to Tools → Elys GenAI → Download AI Models
  3. Follow the prompts

Method 2: Output Log Command​

Open Window → Developer Tools → Output Log and paste:

auto* Subsystem = GEditor->GetEditorSubsystem<UERP_ModelDownloaderEditorSubsystem>();
Subsystem->DownloadWhisperModel(TEXT("base"));

Method 3: C++​

#include "ERP_ModelDownloaderEditorSubsystem.h"

auto* Downloader = GEditor->GetEditorSubsystem<UERP_ModelDownloaderEditorSubsystem>();
if (Downloader)
{
    Downloader->DownloadWhisperModel(TEXT("base"));
}

Runtime Downloads (Packaged Games)​

Use UERP_ModelDownloaderSubsystem for player-facing downloads.

Blueprint Setup​

  1. Get Game Instance → Get Subsystem (UERP_ModelDownloaderSubsystem)
  2. Call Download Whisper Model (ModelId: "base")
  3. Bind to OnDownloadProgress and OnDownloadComplete events

C++ Example​

#include "ERP_ModelDownloaderSubsystem.h"

auto* Downloader = GetGameInstance()->GetSubsystem<UERP_ModelDownloaderSubsystem>();
if (Downloader)
{
    auto* ModelDownloader = Downloader->GetModelDownloader();
    ModelDownloader->OnDownloadProgress.AddDynamic(this, &UMyWidget::OnProgress);
    ModelDownloader->OnDownloadComplete.AddDynamic(this, &UMyWidget::OnComplete);
    
    Downloader->DownloadWhisperModel(TEXT("base"));
}

Available Models​

Model IDSizeUse Case
tiny~75 MBTesting, prototyping
base~142 MBRecommended: Best balance
base.en~142 MBEnglish-only, recommended
small~466 MBBetter accuracy
medium~1.5 GBHigh accuracy
large~3 GBBest accuracy, requires powerful hardware

Recommendation: Use base or base.en for most cases.

Model Storage​

Editor: <ProjectDirectory>/Content/ElysGenAI/Models/Whisper/ Packaged: <GameInstallDirectory>/Content/ElysGenAI/Models/Whisper/

Automatic Configuration​

When a model download completes in the editor, settings are automatically configured:

  • STTBackend → "Whisper"
  • STTModelPath → Path to downloaded model
  • bEnableSTT → true

Check Project Settings → Plugins → Elys GenAI Framework to verify.

Download LLM Models (Optional)​

ElysGenAIPlugin includes a model manager for downloading language models (LLM) for local inference.

Available Models​

Four pre-configured models are available for download:

ModelSizeLicenseBest For
Phi-3-mini 4K2.3 GBMIT✅ Production games
Llama 3.2 1B800 MBLlama CommunityIndie games, prototypes
Gemma 2 2B1.6 GBGemma CommunityIndie games, research
TinyLlama 1.1B700 MBApache 2.0✅ Testing, prototyping

Recommendation: For commercial games, use Phi-3-mini (MIT license, unrestricted) or TinyLlama (Apache 2.0, unrestricted).

Method 1: Download via Model Manager UI (Easiest)​

  1. Open Unreal Editor
  2. Go to Tools → Elys GenAI → Download AI Models
  3. Click on the "LLM Models" tab
  4. Select a model and click "Download"
    • Download progress displays in the UI
    • Takes 5-15 minutes depending on model size and internet speed
  5. When complete, click "Use This Model" to auto-configure settings
  6. The model is now ready for use in UERP_LLMComponent

Method 2: Download via C++ (Programmatic)​

#include "ERP_LLMModelDownloader.h"

// Create downloader instance
auto* LLMDownloader = NewObject<UERP_LLMModelDownloader>();

// Bind to completion event
LLMDownloader->OnDownloadComplete.AddDynamic(
    this, &AMyClass::OnModelDownloadComplete);

// Start download (valid ModelIds: "phi-3-mini-4k", "llama-3.2-1b", "gemma-2-2b", "tinyllama-1.1b")
LLMDownloader->DownloadModel(TEXT("phi-3-mini-4k"));

// Handle completion
void AMyClass::OnModelDownloadComplete(
    const FString& ModelId,
    bool bSuccess,
    const FString& FilePath,
    const FString& ErrorMessage)
{
    if (bSuccess)
    {
        UE_LOG(LogTemp, Log, TEXT("Model ready: %s"), *FilePath);
    }
    else
    {
        UE_LOG(LogTemp, Error, TEXT("Download failed: %s"), *ErrorMessage);
    }
}

Model Storage Location​

Editor: <ProjectDirectory>/Content/ElysGenAI/Models/LLM/ Packaged: <GameInstallDirectory>/Content/ElysGenAI/Models/LLM/

Automatic Configuration​

When an LLM model download completes, settings are automatically configured:

  • LLMBackend → "LlamaCpp"
  • LLMModelPath → Path to downloaded model
  • bEnableLLM → true

Verify in Project Settings → Plugins → Elys GenAI Framework → LLM Settings.

Using Downloaded Models in Blueprint​

  1. Add LLM Component to your actor
  2. Component auto-configures after model download
  3. Send Messages via SendMessage() node
  4. Handle Completion via OnGenerationComplete event

Example Blueprint flow:

[Button Click]
   ↓
[LLM Component → Send Message("Hello")]
   ↓
[Wait for OnGenerationComplete]
   ↓
[Display Response]

Using Downloaded Models in C++​

#include "ERP_LLMComponent.h"

UERP_LLMComponent* LLMComponent = ...;

// Configure system prompt (optional)
LLMComponent->SetSystemPrompt(TEXT("You are a helpful game NPC."));
LLMComponent->SetTemperature(0.7f);
LLMComponent->SetMaxTokens(256);

// Bind to completion event
LLMComponent->OnGenerationComplete.AddDynamic(
    this, &AMyClass::OnLLMResponse);

// Send message
LLMComponent->SendMessage(TEXT("What is your name?"));

// Handle response
void AMyClass::OnLLMResponse(const FERP_LLMResult& Result)
{
    UE_LOG(LogTemp, Log, TEXT("Response: %s"), *Result.GeneratedText);
}

Troubleshooting Model Downloads​

Download is Slow​

Cause: Network speed or HuggingFace CDN throttling

Solutions:

  1. Check internet connection (Whisper/LLM models are 700MB-2.3GB)
  2. Models download from HuggingFace CDN
  3. Try again during off-peak hours
  4. If persistent, check firewall/antivirus blocking

Download Fails with Network Error​

Cause: Firewall, proxy, or network connectivity

Solutions:

  1. Check internet connection
  2. Verify firewall allows HTTPS (port 443)
  3. Try disabling proxy if configured
  4. Manually download from HuggingFace and place in Content/ElysGenAI/Models/LLM/

Model Not Working After Download​

Cause: Settings not configured or model path incorrect

Solutions:

  1. Click "Use This Model" button to auto-configure
  2. Verify settings in Project Settings → Elys GenAI Framework
  3. Delete partial download in Content/ElysGenAI/Models/LLM/ and re-download
  4. Check Output Log for specific errors

Project Settings​

Configure the plugin in Project Settings → Elys GenAI Framework.

Audio Settings​

SettingDefaultDescription
Sample Rate16000 HzAudio capture sample rate
Channels1 (Mono)Audio channels
Bit Depth16Audio bit depth
Buffer Duration100msAudio buffer size

STT Settings​

SettingDefaultDescription
STT BackendWhisperSpeech-to-text backend
Model Path(bundled)Path to Whisper model
LanguageenTarget language code
Enable VADtrueVoice activity detection

LLM Settings​

SettingDefaultDescription
LLM BackendLlamaCppLanguage model backend
Model Path(bundled)Path to Phi-3 model
Context Length4096Maximum context tokens
Temperature0.7Sampling temperature
Max Tokens512Maximum generation length

Troubleshooting Installation​

Plugin Not Appearing in Editor​

Cause: Plugin not properly enabled or compiled

Solutions:

  1. Verify .uplugin file exists in Plugins/ElysGenAIPlugin/
  2. Regenerate project files
  3. Delete Intermediate and Binaries folders, regenerate

Compilation Errors​

Cause: Missing dependencies or Unreal Engine version mismatch

Solutions:

  1. Verify UE version compatibility (5.6+ required)
  2. Check Visual Studio 2022 is installed
  3. Clean build: Delete Intermediate, Binaries, Saved/Cooked
  4. Rebuild from IDE

Audio Capture Not Working​

Cause: Microphone permissions not granted

Solutions:

  1. Windows: Privacy Settings → Microphone → Allow desktop apps
  2. Mac: System Preferences → Security & Privacy → Microphone → Grant access
  3. Verify microphone works in other applications

Model Download Fails​

Cause: Internet connection or firewall

Solutions:

  1. Check internet connection
  2. Models are downloaded from Hugging Face CDN
  3. Check firewall settings
  4. Try manual download and place in models folder

Next Steps​

Plugin installed and configured successfully!

Continue to:

Getting Help​