Adastrea Director - AI Game Director

February 24, 2026 · View on GitHub

An intelligent assistant system designed to understand natural language commands and assist with the game development lifecycle in Unreal Engine.

✅ Phase 3 Complete: Legacy IPC components removed. Plugin now uses VibeUE architecture exclusively.

📚 Documentation: See Adastrea Director Wiki for complete documentation.

🏗️ Architecture: See ARCHITECTURE.md for system architecture and VibeUE components.

Overview

Adastrea Director is an AI-powered tool that aims to revolutionize game development by providing context-aware assistance, automated planning, and eventually autonomous development capabilities. The project is being developed in four distinct phases, with each phase building upon the previous one.

Value Proposition

Current Value (P1-P3): ⭐⭐⭐⭐⭐⭐⭐⭐⭐ 9/10

Context-aware documentation search across all project guides
Intelligent planning and task decomposition for development goals
Code generation assistance with multiple implementation approaches
✨ Autonomous agents for performance profiling, bug detection, and code quality
Real-time monitoring and proactive issue detection
230+ comprehensive tests across Phases P1–P3 (including 120+ Phase 3 autonomous-agent tests, all 100% passing) for production-ready stability
ROI: 300%+ return in 6 months with automated profiling and bug detection

Future Potential (P4 + Plugin): ⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐ 10/10

Integrated UE Editor experience with all P1-P3 capabilities
AI-assisted content generation (quests, dialogue, assets)
Real-time in-editor performance profiling and optimization
Automated playtesting with reproduction steps
ROI: 400%+ return with full autonomous development assistance

For detailed analysis, see the Wiki

Architecture: One System, Two Deployment Options

Adastrea Director is one AI system with two deployment modes:

🖥️ Standalone Mode (Python GUI/CLI)

Purpose: Development, testing, and standalone use
Technology: Python + tkinter/CLI
Best for: Rapid prototyping, testing, non-UE users
Status: ✅ Fully functional (P1-P3)

🎮 Plugin Mode (Unreal Engine - VibeUE Architecture)

Purpose: Native C++ integration in Unreal Editor
Technology: Modern C++ with direct LLM integration (no external processes)
Architecture: VibeUE pattern - IPythonScriptPlugin, direct HTTP, runtime queries
Best for: Production UE development with integrated AI assistance
Status: ✅ VibeUE architecture complete - Phase 3 migration finished (Jan 2026)
Components: AdastreaScriptService, LLMClient, AssetService, ToolSystem, MCPServer

Key Point: The plugin uses the VibeUE architecture with native C++ components. Legacy IPC components have been REMOVED (Phase 3 complete). All functionality is now provided through direct C++ integration.

📖 See: ARCHITECTURE.md for detailed system architecture and Wiki for complete documentation.

Current Phase: Phase 3.5 Complete - Plugin Integration 70%

Latest Achievement: Phase 3.5 (VibeUE Architecture) completed January 2026! 🎉

Completed Phases

✅ Phase 1: Foundation (RAG-based Q&A)
✅ Phase 2: The Planner (Goal decomposition and task planning)
✅ Phase 3: Autonomous Agents (Performance, Bug Detection, Code Quality)
✅ Phase 3.5: VibeUE Architecture Migration (Native C++ integration)

Phase 3.5 Highlights (January 2026)

The C++ plugin has completed the full migration to VibeUE architecture:

✅ Direct LLM integration (AdastreaLLMClient) - no external Python process needed
✅ Built-in Python execution (AdastreaScriptService) via IPythonScriptPlugin
✅ Runtime asset discovery (AdastreaAssetService) - no document ingestion required
✅ Tool system (AdastreaToolSystem) for extensible AI capabilities
✅ MCP server (AdastreaMCPServer) for external AI clients (VS Code, Claude Desktop)
✅ Legacy IPC components fully removed (~5,000 lines) - zero IPC overhead
✅ Sockets/Networking modules removed from build dependencies

Impact: Better reliability, simplified architecture, native C++ performance, and modern integration patterns.

See Q1_2026_PROGRESS_SUMMARY.md for complete details, VIBEUE_COMPLETION_SUMMARY.md for technical implementation, and MIGRATION_GUIDE.md for historical migration reference.

Current Focus: Plugin Integration (70% Complete)

Completed:

✅ Basic plugin infrastructure and UI framework
✅ RAG integration for documentation queries
✅ Phase 3 agent integration with IPC server
✅ UE Python API integration (25+ tests)
✅ Content generation and validation utilities
✅ Backend logging and monitoring infrastructure

In Progress (Q1 2026):

🔄 Plugin C++ testing framework (Target: 90% coverage)
🔄 UI/UX redesign matching UE5 editor style
🔄 Blueprint widgets for agent visualization
🔄 Real-time event streaming to editor

Next Milestones:

📅 Feb 2026: Complete testing framework
📅 Mar 2026: UI/UX redesign complete
📅 Apr 2026: Plugin feature complete (v1.0)
📅 May 2026: Marketplace submission

For detailed roadmap and future plans, see ROADMAP.md.

Features

✅ P1: Foundation - RAG-based document understanding and Q&A
✨ P2: The Planner (Complete):
- Goal Analysis: Parse natural language development goals and classify them
- Task Decomposition: Automatically break down goals into prioritized tasks
- Dependency Management: Identify task dependencies and optimal execution order
- Code Generation: Generate implementation approaches with code examples
- Feasibility Analysis: Assess complexity and provide recommendations
- Plan Export: Export plans in Markdown, JSON, or Text formats
- Interactive Planning CLI: New dedicated planning interface
- Effort Estimation: Estimate time and complexity for tasks
- Priority Assignment: Intelligent task prioritization

📋 Project Status

Current Focus: Plugin Integration & Testing (70% Complete - Target: May 2026 v1.0)

Completed Phases:

✅ Phase 1: Foundation (RAG-based Q&A) - Q3 2024
✅ Phase 2: The Planner (Goal decomposition and task planning) - Q4 2024
✅ Phase 3: Autonomous Agents (Performance, Bug Detection, Code Quality) - Q4 2025
✅ Phase 3.5: VibeUE Architecture Migration (Native C++ integration) - January 2026
✅ Backend Infrastructure Hardening (Comprehensive logging) - January 2026
✅ Standalone Python application (CLI + GUI) - Production Ready

In Progress:

🔄 UE Plugin Testing Framework (Feb 2026)
🔄 UI/UX Redesign for UE5 Style (Mar 2026)
🔄 Blueprint Widgets & Real-time Features (Feb-Mar 2026)

Upcoming:

📅 Plugin v1.0 Feature Complete (April 2026)
📅 Marketplace Submission (May 2026)
📅 Phase 4: Creative Partner (Q3 2026)

Latest Updates:

January 30, 2026: Updated roadmap with detailed future plans through 2027
January 24, 2026: Completed backend logging infrastructure
January 19, 2026: VibeUE migration complete, removed ~5,000 lines of legacy code

For detailed progress tracking and future plans, see Q1_2026_PROGRESS_SUMMARY.md, ROADMAP.md, and the Wiki.

Project Phases

P1: Foundation (Context-Aware Assistant) - ✅ Complete
- RAG-based document understanding
- Natural language query interface
- Document ingestion and vector database
P2: The Planner (Goal-Oriented Tasking) - ✅ Complete
- Goal analysis and classification
- Task decomposition with dependencies
- Action plan generation
- Effort estimation and prioritization
Phase 3: The Proactive Agent System - ✅ Complete
- ✅ Autonomous performance profiling and optimization
- ✅ Automated bug detection and crash analysis
- ✅ Code quality monitoring and refactoring suggestions
- ✅ Agent Orchestrator CLI for managing agents
- ✅ Real-time Dashboard UI for monitoring
- ✅ 120+ comprehensive tests (100% passing)
- ✅ Remote Control API client module (67 tests, integrated and functional)
- ✅ Event bus implementation (16 tests)
- ✅ Shared state management (20 tests)
- ✅ MCP Server integration for AI agent access (84 tests)
P4: Creative Partner - 🌟 Vision
- AI-assisted content generation
- Creative design suggestions

Getting Started

🚀 Quick Start (5 Minutes)

New to Adastrea Director? Start with our updated quick start guide:

👉 QUICK_START_GUIDE.md - Get started in 5 minutes with either:

Standalone Python tools (no Unreal Engine required)
Unreal Engine integration (full MCP server control)

Recent Updates (2026-02-24):

Added connection diagnostic tool: test_unreal_connection.py
Created comprehensive work session summary: WORK_SESSION_SUMMARY_2026-02-24.md
Simplified setup instructions for new users

Prerequisites

Python 3.9 or higher (Python 3.12+ recommended for best compatibility)
pip package manager
(Optional) GitHub Personal Access Token for game repository ingestion

Quick Start: Populate the Database

⚡ Want to start using Adastrea Director immediately with full game context?

🎉 NEW: HuggingFace access is now enabled! Game repository ingestion is ready to use.

Populate the database with your game repository so all agents have access to your codebase:

Method 1: Quick Ingestion Script (Easiest)

./quick_ingest_game.sh

Method 2: Manual Ingestion

# Set your GitHub token (for private repository access, if needed)
export GITHUB_TOKEN="ghp_your_token_here"

# Populate the database (uses HuggingFace embeddings - no API key required!)
python3 ingest_game_repo.py

Method 3: Use GitHub Actions (Automated) ⭐

Add GAME_REPO_TOKEN secret in repository settings
Go to Actions → "Populate Database with Adastrea Game Repository"
Click "Run workflow"

📖 Documentation:

Quick Status: INGESTION_STATUS.md - Current status and quick reference
Complete Guide: GAME_REPO_INGESTION_GUIDE.md - Detailed instructions and troubleshooting
Quick Start: START_HERE_INGESTION.md - 60-second setup guide

Once populated, all agents will have full context about your Adastrea game when providing assistance!

Installation

Quick Setup (All Platforms)

git clone https://github.com/Mittenzx/Adastrea-Director.git
cd Adastrea-Director
./setup.sh  # Linux/Mac

The setup script will:

Check your system compatibility
Create a virtual environment (reusable for fast subsequent runs)
Install all dependencies with platform-specific handling
Verify the installation

💡 Tip: The virtual environment can be reused - just activate it with source venv/bin/activate for instant access without reinstalling dependencies.

Manual Installation

Clone the repository:

git clone https://github.com/Mittenzx/Adastrea-Director.git
cd Adastrea-Director

Install dependencies:

Option A: Smart Installer (Recommended)

python install_dependencies.py

This script will detect your platform and guide you through any platform-specific setup needed.

Option B: Direct Installation

pip install -r requirements.txt

📝 Note: If you encounter issues (especially on Apple Silicon Macs or ARM systems), use the smart installer or see the Installation Guide in the Wiki for platform-specific instructions and troubleshooting.

Verify your installation and test API keys:

⚠️ Run from system terminal, NOT UE Python console!

# Test that all dependencies are installed and API keys work
python test_api_keys.py

# Test specific provider
python test_api_keys.py --provider gemini

# Check configuration without making API calls
python test_api_keys.py --skip-api-test

This script will help you diagnose any issues with dependencies or API key configuration.

Note: If run from Unreal Engine's Python console, you'll see "Dependencies NOT INSTALLED" messages. This is expected - the script should be run from your system terminal. See TROUBLESHOOTING.md for details.

Set up your LLM API key:

For document embeddings: The system uses HuggingFace embeddings by default (no API key required, works offline).

See the Wiki for OpenAI embeddings setup if needed

For LLM queries: Set up your preferred LLM provider. You have four options:

Option A: Save to local config (Recommended - persists across repository clones)

# Via CLI
python main.py --set-api-key gemini  # or openai, or openrouter

# Via GUI
# When prompted, check "Save API key for future sessions"

Keys are securely stored in ~/.adastrea/config.json and encrypted with a machine-specific key.

Option B: Use environment variable

export GEMINI_KEY="your-api-key-here"
# or for OpenAI
export OPENAI_API_KEY="your-api-key-here"
# or for OpenRouter
export OPENROUTER_API_KEY="your-api-key-here"

Option C: Use .env file

cp .env.example .env
# Edit .env and add your GEMINI_KEY, OPENAI_API_KEY, or OPENROUTER_API_KEY

Option D: Select provider in GUI Settings Open the Settings dialog (⚙️) and configure your preferred provider and API key.

Priority: Local config → Environment variables (including .env file)

🔍 Test your configuration: After setting up your API key, verify it works:

python test_api_keys.py

(Optional) Set up GitHub token for game repository ingestion:

export GITHUB_TOKEN="your-github-token-here"

This is only needed if you want to ingest documents from the private Mittenzx/Adastrea game repository.

📖 For detailed setup guides, see the Wiki

Usage

💡 Which mode should I use?

Use Case	Recommended Mode	Why
Working in Unreal Engine	🎮 Plugin	Integrated workflow, no context switching
Testing/prototyping new features	🖥️ Standalone	Faster iteration, easier debugging
Non-UE game development	🖥️ Standalone	Works with any project type
Plugin is not yet feature-complete	🖥️ Standalone	All features available immediately

Both modes share the same AI backend, so you get the same quality of results!

Planning System (P2 - Complete!)

Create implementation plans for your development goals:

# Interactive planning mode
python planner.py --interactive

# Plan a specific goal
python planner.py "Add a new inventory system"

# Export plan to file
python planner.py "Optimize rendering pipeline" --export markdown --output plan.md

# Enable debug logging for troubleshooting
python planner.py --debug "Optimize rendering pipeline"

The planning system will:

Analyze your goal and identify requirements
Break it down into prioritized tasks with dependencies
Estimate effort and assess feasibility
Suggest implementation approaches with code examples
Export a complete plan for review

Debugging & Logging: All commands support --debug flag for detailed logging output. Logs are saved to logs/adastrea_YYYYMMDD.log and can be viewed in the GUI's Debug Logs tab

Context-Aware Assistant (P1)

Ingest your project documents:

python ingest.py --docs-dir /path/to/your/docs

📚 For detailed ingestion guides, see the Wiki

🎮 Working on the Mittenzx/Adastrea game? Use the dedicated game repository ingestion:

python ingest_game_repo.py

Start the interactive assistant:

python main.py

Ask questions about your project:

> What is the main gameplay loop?
> Describe the player character abilities
> What are the performance requirements?

P2: Goal Decomposition

Interactive goal planning:

python planning_cli.py --interactive

Single goal with markdown export:

python planning_cli.py --goal "Implement user authentication system" --output action_plan.md

Run the planning example:

python examples/planning_example.py

📋 Want to learn more? See the Planning Guide in the Wiki for comprehensive documentation with examples.

P3: Autonomous Agents (Complete! ✅)

The autonomous agent system is fully implemented and operational. Manage and monitor agents for performance profiling, bug detection, and code quality:

Agent Orchestrator CLI - Control agents from command line:

# Start all agents
python agent_orchestrator_cli.py start --all

# Check agent status
python agent_orchestrator_cli.py status

# View recent events
python agent_orchestrator_cli.py events --limit 20

# Stop specific agent
python agent_orchestrator_cli.py stop --agent performance

Agent Dashboard - Real-time monitoring:

# Start dashboard with auto-start
python agent_dashboard.py --auto-start

# Custom update interval
python agent_dashboard.py --interval 2.0

Run the P3 demo:

python examples/phase3_orchestrator_demo.py

📋 Documentation: See the Phase 3 Guide in the Wiki for complete documentation

Unreal Engine Plugin

For game developers working in Unreal Engine, the plugin provides an integrated in-editor experience:

Current Status: Weeks 1-6 Complete (Basic UI + RAG Integration) + NEW: UE Python API Integration ✨

🚀 Quick Start:

👉 Plugin Setup Guide - Get started in 5 minutes!

Installation (Quick):

Copy Plugins/AdastreaDirector to your UE project's Plugins folder
Regenerate project files (right-click .uproject → Generate Visual Studio project files)
Build your project
Launch Unreal Engine Editor

Usage:

Open Window → Developer Tools → Adastrea Director
The AI assistant panel opens as a dockable tab
Use the Ingestion tab to add your documentation
Use the Query tab to ask questions
Python backend starts automatically!

NEW: UE Python API Features ✨

✅ Direct access to Unreal Engine's Python API (import unreal)
✅ Asset operations (query, load, save)
✅ Actor operations (spawn, query, delete)
✅ Console command execution
✅ Editor automation (notifications, logging)
✅ Hybrid architecture (External Python + UE Python)
✅ Content generation utilities - Procedural layouts, material libraries, Blueprint creation
✅ Content validation framework - Automated asset validation and standards compliance
✅ Batch processing - Mass operations on assets and actors
✅ 25+ comprehensive tests (100% passing)

📖 Complete Plugin Documentation:

Setup Guide - 🌟 Start here! Quick setup and testing
Plugin README - Full plugin guide
UE Python API Guide - NEW! UE Python integration
Python Research Document - 📚 NEW! Complete UE Python API capabilities (UE 4.27-5.7)
Installation Guide - Detailed setup
RAG Integration - Using the RAG system
Testing Quick Reference - Verify installation

Coming Soon (Weeks 7-16):

Planning agent integration (task breakdown in UE)
Performance profiling UI
Bug detection integration
Code quality monitoring

Unreal Engine MCP Integration (NEW!)

Control Unreal Engine directly from the command line using the MCP server integration:

# Interactive mode - no external client needed
python unreal_mcp_cli.py

# Direct commands
python unreal_mcp_cli.py project-info      # Get project info
python unreal_mcp_cli.py list-assets       # List all assets
python unreal_mcp_cli.py search-assets "player"
python unreal_mcp_cli.py run-python "import unreal; print(unreal.SystemLibrary.get_engine_version())"

Features:

✅ Execute Python directly in Unreal Editor
✅ List, search, and inspect assets
✅ Create, update, and delete actors
✅ Run console commands
✅ Get project and level information
✅ Works with any MCP-compatible client (5ire, Cline, Zed, etc.)
✅ 84 comprehensive tests

📖 Documentation: MCP Server Guide

🔗 Related Project: Adastrea-MCP - Complementary MCP server providing static analysis, code generation, and UE5.6+ knowledge (37 tools). Can integrate with Adastrea-Director for comprehensive UE development assistance. See MCP Integration Architecture for details.

Project Structure

Adastrea-Director/
├── README.md                      # This file - Quick start guide
├── CONTRIBUTING.md                # Contribution guidelines
├── Documentation/                 # Organized documentation (UE standards)
│   ├── guides/                    # User guides and tutorials
│   ├── implementation/            # Implementation summaries
│   ├── architecture/              # Architecture and design docs
│   ├── research/                  # Research and exploration
│   └── development/               # Development status docs
├── requirements.txt               # Python dependencies
├── ingest.py                      # Document ingestion script
├── ingest_game_repo.py            # Game repository ingestion
├── main.py                        # P1 CLI entry point
├── planner.py                     # P2 planning CLI

├── ue_log_capture.py              # UE log capture module
├── agent_orchestrator_cli.py      # P3 agent CLI
├── agent_dashboard.py             # P3 dashboard
├── agents/                        # Agent system
│   ├── phase3/                    # P3 autonomous agents
│   └── ...                        # P2 planning agents
├── logs/                          # UE output logs (dated files)
├── tests/                         # Comprehensive test suite (230+ tests)
├── examples/                      # Example scripts
├── remote_control/                # Remote control API
└── Plugins/                       # Unreal Engine plugin
    └── AdastreaDirector/          # Plugin implementation

📚 All documentation is now in the Wiki: https://github.com/Mittenzx/Adastrea-Director/wiki

Documentation

📚 Complete documentation is available in the Adastrea Director Wiki

The wiki includes:

Installation & Setup - Platform-specific instructions and troubleshooting
Usage Guides - How to use all features (P1-P3)
Architecture - System design and agent architecture
Phase Documentation - Detailed guides for each project phase
Development - Contributing, testing, and code reference
Design System - UI/UX guidelines
API Reference - Remote control API and integrations
Remote Connection Types & Actions - Comprehensive directory of all connection types (HTTP, WebSocket, Python IPC, UE Python API, Director Plugin)

🤖 For GitHub Copilot and AI Agents

If you're a GitHub Copilot agent or AI assistant working with Adastrea Director:

COPILOT_INSTRUCTIONS.md - 📖 Complete guide for Copilot agents with connection methods, capabilities, and verification procedures
.github/COPILOT_QUICK_REFERENCE.md - 🚀 Quick reference card for common operations

🤖 GitHub Copilot Integration

NEW: MCP Server Integration ✨

GitHub Copilot in VS Code can now directly use Adastrea Director's MCP (Model Context Protocol) server to interact with Unreal Engine! The repository includes pre-configured VS Code settings in .vscode/settings.json that enable Copilot to:

Execute Python code directly in Unreal Engine Editor
Query project information and list assets
Create and manipulate actors in the level
Access Director's RAG knowledge base
Get context-aware assistance for UE development

Quick Setup:

Open this repository in VS Code
Ensure GitHub Copilot extension is installed
Start Unreal Engine with Python Editor Script Plugin enabled
Ask Copilot: Use the adastrea-unreal server to get project information

See .vscode/README.md for complete setup instructions and troubleshooting.

Debugging UE Logs: Want GitHub Copilot to help debug UE crashes and errors? See COPILOT_UE_LOGS_GUIDE.md for details on how Copilot can access Unreal Engine output logs for better assistance.

Testing

Adastrea Director includes a comprehensive test suite to ensure reliability and quality:

Test Coverage

230+ Total Tests: Covering all major components
27 GUI Tests: Complete UI testing suite (20 functional, 7 integration tests marked for future)
88% GUI Coverage: Thorough testing of UI components
100% Pass Rate: Production-ready stability

Running Tests

# Run all tests
pytest

# Run with coverage report
pytest --cov=. --cov-report=html

# Run specific test categories
pytest -m unit          # Unit tests only
pytest -m integration   # Integration tests only

Test Categories

Unit Tests: Individual component testing
Integration Tests: Component interaction testing
UI Tests: User interface behavior testing
Error Handling Tests: Error condition validation
Workflow Tests: Complete user workflow testing