metaverseDubai/docs/NPC_DIALOGUE.md

NPC Dialogue System - Dubai Metaverse

Overview

This document describes the ChatGPT-powered dynamic dialogue system for NPCs in the Dubai Metaverse project (optional feature).

System Architecture

Overview

The dialogue system integrates ChatGPT API to generate dynamic, context-aware dialogue for NPCs, allowing for natural conversations with players.

Components

1. BP_DialogueSystem: Main dialogue system blueprint
2. API Integration: ChatGPT API client
3. Dialogue Handler: Handles dialogue requests and responses
4. NPC Integration: Integrates with NPC behavior system

---

ChatGPT API Integration

API Setup

1. API Key: Obtain ChatGPT API key from OpenAI
2. Secure Storage: Store API key securely (environment variable, not in repository)
3. API Client: Create API client in blueprint or C++
4. Configuration: Configure API endpoint and settings

API Configuration

• Model: GPT-3.5-turbo or GPT-4
• Temperature: 0.7-0.9 (creative but coherent)
• Max Tokens: 100-200 (concise responses)
• System Prompt: Define NPC personality and context

---

Dialogue System Blueprint

BP_DialogueSystem

Main dialogue system controller

Functions

RequestDialogue

• Purpose: Request dialogue from ChatGPT
• Input: Player message, NPC context
• Output: Generated dialogue response
• Implementation: API call to ChatGPT

ProcessResponse

• Purpose: Process API response
• Input: API response
• Output: Formatted dialogue
• Implementation: Parse and format response

GetNPCContext

• Purpose: Get NPC context for dialogue
• Input: NPC reference
• Output: NPC context (name, location, personality)
• Implementation: Gather NPC information

---

NPC Context

Context Information

NPC Identity

• Name: NPC name
• Role: NPC role (tourist, resident, business person)
• Personality: Personality traits
• Background: Background information

Location Context

• Current Location: Where NPC is located
• District: Dubai Marina
• Landmarks: Nearby landmarks
• Activities: Current activities

Conversation Context

• Previous Messages: Conversation history
• Topic: Current conversation topic
• Mood: NPC mood/emotional state

---

System Prompts

NPC Personality Prompts

Example: Tourist NPC

You are a tourist visiting Dubai Marina. You are friendly, curious, and excited about Dubai. 
You speak in a casual, enthusiastic manner. Keep responses brief (1-2 sentences). 
You know about Dubai Marina, Cayan Tower, and the luxury lifestyle in Dubai.

Example: Resident NPC

You are a resident of Dubai Marina. You are knowledgeable about the area, professional, 
and helpful. You speak in a friendly but professional manner. Keep responses brief (1-2 sentences). 
You know about local restaurants, shops, and the Marina lifestyle.

Example: Business Person NPC

You are a business person in Dubai. You are professional, busy, and focused. 
You speak in a professional, concise manner. Keep responses brief (1-2 sentences). 
You know about business in Dubai, the financial district, and professional services.

---

Dialogue Flow

Player Interaction

1. Player Approaches NPC: Player interacts with NPC
2. Dialogue UI: Dialogue UI appears
3. Player Input: Player types or selects message
4. Dialogue Request: System requests dialogue from ChatGPT
5. NPC Response: NPC speaks generated dialogue
6. Continuation: Conversation continues

Implementation

1. Interaction System: Use interaction system to trigger dialogue
2. UI Widget: Create dialogue UI widget
3. API Call: Make API call to ChatGPT
4. Response Processing: Process and display response
5. Audio: Play NPC voice (optional, text-to-speech)

---

API Integration Script

npc_dialogue_api.py

Python script for API integration (optional)

Functions

• send_dialogue_request: Send request to ChatGPT API
• process_response: Process API response
• format_dialogue: Format dialogue for display

Usage

• Standalone: Run as standalone service
• Integration: Integrate with Unreal via HTTP requests
• Caching: Cache responses for performance

---

Performance Considerations

Optimization

1. Caching: Cache common responses
2. Rate Limiting: Limit API calls per NPC
3. Response Time: Optimize for quick responses
4. Fallback: Fallback to pre-written dialogue if API fails

Cost Management

1. API Costs: Monitor API usage and costs
2. Token Limits: Limit tokens per request
3. Request Frequency: Limit request frequency
4. Caching: Cache responses to reduce API calls

---

Security

API Key Security

• Never Commit: Never commit API keys to repository
• Environment Variables: Use environment variables
• Secure Storage: Store keys securely
• Access Control: Limit access to API keys

Input Validation

• Sanitize Input: Sanitize player input
• Length Limits: Limit input length
• Content Filtering: Filter inappropriate content

---

Testing

Dialogue Testing

1. Quality: Test dialogue quality
2. Context: Test context awareness
3. Personality: Test NPC personality consistency
4. Response Time: Test response time

Integration Testing

1. NPC Integration: Test with NPC system
2. UI Integration: Test with dialogue UI
3. Performance: Test performance impact
4. Error Handling: Test error handling

---

Fallback System

Pre-Written Dialogue

Fallback if API unavailable

• Greetings: Pre-written greetings
• Common Responses: Common response templates
• Topics: Pre-written dialogue for common topics

Implementation

1. Dialogue Database: Store pre-written dialogue
2. Topic Matching: Match player input to topics
3. Response Selection: Select appropriate response
4. Fallback Trigger: Trigger fallback if API fails

---

Troubleshooting

Common Issues

Issue: API not responding

• Solution: Check API key and connection
• Solution: Implement fallback system
• Solution: Check rate limits

Issue: Dialogue quality poor

• Solution: Refine system prompts
• Solution: Adjust temperature settings
• Solution: Improve context information

Issue: Response time too slow

• Solution: Implement caching
• Solution: Optimize API calls
• Solution: Use faster API model

---

Documentation

API Documentation

Document API integration:

• API setup
• Configuration
• Usage
• Error handling

Dialogue Documentation

Document dialogue system:

• NPC personalities
• Context information
• System prompts
• Usage examples

---

Version: 1.0 Last Updated: [Current Date]

Note: This is an optional feature. The project can function without ChatGPT integration using pre-written dialogue or no dialogue system.