Initial commit: Complete project foundation with all documentation, scripts, and project structure
This commit is contained in:
Dubai Metaverse Team
285
docs/NPC_DIALOGUE.md
Normal file
285
docs/NPC_DIALOGUE.md
Normal file
@@ -0,0 +1,285 @@
|
||||
# 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.
|
||||
|
||||
Reference in New Issue
Block a user