AI Game Companion Prototype 🤖🎮

A production-ready prototype for an AI Companion System in Unreal Engine. This project uses a local LLM (Ollama) to convert natural language commands (e.g., "attack that enemy") into structured JSON commands that Unreal Engine can execute.

🚀 Quick Start (Daily Workflow)

👉 READ THIS FIRST: QUICKSTART_GUIDE.md (Contains the Start, Stop, and Restart instructions you need every day).

---

📚 Documentation

Everything you need to set up Unreal Engine and test the API is in the docs/ folder:

• 📘 Blueprint Integration Tutorial – Step-by-step guide to connecting UE5 Blueprints.
• 🗺️ UE Integration Map – Mapping API actions ("attack") to UE Enums.
• 🏗️ Architecture Guide – How the system works under the hood.

---

🛠️ Setup & Installation

1. Prerequisites

• Python 3.11+
• Ollama (Download)
• Ngrok (For remote access/firewall bypass)

2. Install Dependencies

pip install -r requirements.txt

3. Run the System

See QUICKSTART_GUIDE.md for the 3-terminal setup.

---

🧪 Testing

We have included a Postman Collection to make testing easy.

1. Go to postman/ folder.
2. Import companion_api_collection.json into Postman.
3. Use Send Command to test the API.

---

⚠️ Common Issues & Fixes

1. Connection Failed (-1 or 403 Forbidden)

Cause: Firewall or Ngrok Browser Warning. Fix: You MUST add this header to your Unreal Engine Request:

• User-Agent: MyCustomApp/1.0

2. URL Not Working

Cause: Ngrok URL changes every time you restart it. Fix: Copy the new URL from the ngrok terminal and paste it into your Blueprint.

---

🎮 Supported Commands

Command Category	Examples
Movement	"follow me", "move to the door", "hold position", "take cover", "retreat", "regroup"
Combat	"attack that enemy", "suppress the window", "clear this room", "defend here", "overwatch this area"
Interaction	"pick up the ammo", "use the switch", "throw a grenade", "use medkit on me"
General	"stop", "cancel", "wait here"

---

📁 Project Structure

UE_testing/
├── app/                       # Core Application Logic
│   ├── intent_compiler.py     # AI Logic (Text -> JSON)
│   ├── mock_unreal.py         # Fake UE for testing
│   └── ...
├── docs/                      # Documentation & Tutorials
├── postman/                   # API Collections
├── tests/                     # Test Suite
├── tools/                     # Utilities (ngrok)
├── server.py                  # Flask API Server (Entry Point)
├── run.py                     # CLI Runner (Entry Point)
├── QUICKSTART_GUIDE.md        # Daily Instructions
└── README.md                  # This file