# 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.