# 🎮 MMORPG with MCP Integration - User Documentation ## 📋 Table of Contents 1. [Overview](#overview) 2. [Quick Start Guide](#quick-start-guide) 3. [Core Features](#core-features) 4. [User Interface Guide](#user-interface-guide) 5. [Gameplay Mechanics](#gameplay-mechanics) 6. [MCP Integration](#mcp-integration) 7. [Developer & AI Agent Usage](#developer--ai-agent-usage) 8. [NPC Addon System](#npc-addon-system) 9. [Advanced Features](#advanced-features) 10. [Troubleshooting](#troubleshooting) 11. [API Reference](#api-reference) --- ## 📖 Overview The **MMORPG with MCP Integration** is a real-time multiplayer online role-playing game that serves as both an entertaining game and a powerful platform for testing and developing Model Context Protocol (MCP) integrations. It combines traditional MMORPG elements with cutting-edge AI agent capabilities. ### 🎯 What Makes This Special - **🌍 Real-time Multiplayer**: Multiple human players can join simultaneously - **🤖 AI Agent Support**: AI agents can connect and play alongside humans - **🔌 MCP Integration**: Full Model Context Protocol support for extensibility - **🧩 Addon System**: Extensible NPC addon architecture - **⌨️ Keyboard Controls**: WASD and arrow key support for fluid gameplay - **🔥 Secure Messaging**: Read2Burn self-destructing message system - **🌤️ Live Services**: Real weather integration via MCP - **🔧 Developer Platform**: Complete API for building custom integrations ### 🚀 Use Cases **For Gamers:** - Experience a unique MMORPG with AI-powered NPCs - Interact with real-time weather and other live services - Send secure self-destructing messages to other players **For Developers:** - Test MCP server integrations in a real-world environment - Develop custom NPC addons with rich functionality - Build AI agents that can play and interact in the game - Prototype multiplayer game mechanics **For AI Researchers:** - Study human-AI interaction in gaming environments - Test AI agent behaviors in social multiplayer settings - Develop and evaluate conversational AI systems **For MCP Server Developers:** - Test server implementations with real users - Demonstrate MCP capabilities in an engaging context - Debug and optimize server performance --- ## 🚀 Quick Start Guide ### 1. Starting the Game ```bash # Navigate to the project directory cd c:\Users\Chris4K\Projekte\projecthub\projects\MMOP_second_try # Install dependencies (first time only) pip install gradio mcp aiohttp asyncio # Start the game server python app.py ``` The game will start and display: ``` 🎮 Starting COMPLETE MMORPG with ALL FEATURES... 🌐 Human players: Access via web interface 🤖 AI agents: Connect via MCP API endpoints ⌨️ Keyboard: Use WASD or Arrow Keys for movement 🔌 MCP Tools available for AI integration 🔥 Read2Burn mailbox for secure messaging 🎯 All features working with deadlock fix! * Running on local URL: http://127.0.0.1:7868 🔨 MCP server (using SSE) running at: http://127.0.0.1:7868/gradio_api/mcp/sse ``` ### 2. Joining as a Human Player 1. Open your web browser and go to `http://127.0.0.1:7868` 2. Navigate to the **🌍 Game World** tab 3. Enter your desired player name in the "Player Name" field 4. Click **"🎮 Join Game"** 5. You'll see your character (🧝‍♂️) appear on the game map ### 3. Basic Movement **Web Interface:** - Use the directional buttons: ↑ ↓ ← → **Keyboard Controls:** - **WASD Keys**: W (up), A (left), S (down), D (right) - **Arrow Keys**: ↑ ↓ ← → - **Space**: Action key (context-sensitive) ### 4. First Interactions **Chat with Others:** 1. Go to the **💬 Chat** tab 2. Type a message and press Enter 3. All players will see your message **Talk to NPCs:** 1. Move close to an NPC on the map 2. Go to the **🎯 Private Messages** tab 3. Select the NPC from the dropdown 4. Send them a message --- ## 🎮 Core Features ### 🌍 Real-time Game World **Map System:** - **Size**: 500x400 pixel game world - **Visual Style**: Fantasy forest theme with grid overlay - **Real-time Updates**: All player movements update immediately - **Collision Detection**: Prevents players from occupying same space **Player Characters:** - **Humans**: Represented by 🧝‍♂️ (elf character) - **AI Agents**: Represented by 🤖 (robot character) - **Name Tags**: Player names displayed above characters - **Level Display**: Shows current player level ### 👥 Multiplayer System **Player Management:** - **Concurrent Players**: Supports multiple simultaneous players - **Unique Sessions**: Each player gets a unique session ID - **Real-time Sync**: All actions sync across all connected clients - **Player Stats**: Level, HP, gold, experience tracking **Player Actions:** - **Join/Leave**: Seamless game entry/exit - **Movement**: 4-directional movement with smooth transitions - **Chat**: Public chat visible to all players - **Private Messaging**: Direct communication with NPCs ### 🎯 NPC System **Built-in NPCs:** - **🧙‍♂️ Village Elder**: Wise questgiver and general information - **⚔️ Warrior Trainer**: Combat training and warrior wisdom - **🏪 Merchant**: Trade goods and equipment - **🌟 Mystic Oracle**: Magical insights and prophecies - **🚶‍♂️ Roaming Rick**: Wandering NPC with location updates - **📮 Read2Burn Mailbox**: Secure message handling - **🌤️ Weather Oracle**: Real-time weather information **NPC Features:** - **Personality System**: Each NPC has unique response patterns - **Proximity Detection**: NPCs respond when players approach - **Smart Responses**: Context-aware conversation handling - **Addon Support**: Extensible with custom functionality ### 💬 Communication Systems **Public Chat:** - **Real-time Messaging**: Instant message delivery - **Player Identification**: Messages show sender name and type - **Message History**: Scrollable chat history - **Command Support**: Special commands like `/help` **Private Messaging:** - **NPC Communication**: Direct messages to any NPC - **Secure Channels**: Private conversation channels - **Response Handling**: NPCs can provide detailed responses - **Message Logging**: Optional message history tracking --- ## 🖥️ User Interface Guide ### 🌍 Game World Tab **Main Game View:** - **Game Map**: Central 500x400 pixel game world - **Player Controls**: Movement buttons (↑ ↓ ← →) - **Join/Leave**: Game participation controls - **Auto-refresh**: Real-time world updates **Player Information Panel:** ``` 🟢 Connected | Player: YourName | Level: 1 HP: 100/100 | Gold: 50 | XP: 0/100 Position: (150, 200) | Session: abc12345... Last Update: 14:30:15 ``` **Control Layout:** ``` Player Name: [_____________] [🎮 Join Game] [👋 Leave Game] [↑] [←] [⚔️] [→] [↓] ``` ### 💬 Chat Tab **Interface Elements:** - **Message Input**: Text field for typing messages - **Send Button**: Submit messages to all players - **Chat History**: Scrollable message display - **Auto-scroll**: Automatically shows latest messages **Message Format:** ``` [14:30] 👤 PlayerName: Hello everyone! [14:31] 🤖 AIAgent: Greetings, fellow adventurers! [14:32] 🌍 System: New player joined the world ``` ### 🎯 Private Messages Tab **NPC Selection:** - **Dropdown Menu**: List of all available NPCs - **NPC Status**: Shows which NPCs are online/available - **Message Input**: Text field for private messages - **Response Display**: Shows NPC replies **Example Interaction:** ``` To: 🌤️ Weather Oracle Message: What's the weather in Berlin? 🌤️ Weather Oracle: 🌍 The spirits speak of Berlin, Germany: ☀️ Clear skies with 18°C 💨 Light winds from the northwest 🌡️ Feels like 19°C Perfect weather for outdoor adventures! ``` ### 📊 Player Stats Tab **Detailed Statistics:** - **Basic Info**: Name, level, type (human/AI) - **Combat Stats**: HP, maximum HP, combat level - **Resources**: Gold pieces, experience points - **Location**: Current X,Y coordinates - **Session Info**: Connection time, session ID ### 🔥 Read2Burn Mailbox Tab **Secure Messaging Interface:** - **Create Message**: Compose self-destructing messages - **Message Management**: View your active messages - **Read Messages**: Access messages sent to you - **Security Settings**: Configure burn timers and read limits **Usage Example:** ``` Create Message: Content: [Secret meeting at coordinates 200,150] [📮 Create Secure Message] Result: ✅ Message Created Successfully! 📝 Message ID: AbC123Xyz789 🔗 Share this ID with the recipient ⏰ Expires in 24 hours 🔥 Burns after 1 read ``` ### 🌤️ Weather Oracle Tab **Weather Service Interface:** - **Location Input**: City, Country format - **Get Weather Button**: Fetch current conditions - **Weather Display**: Formatted weather information - **Examples**: Pre-filled location examples **Weather Response Format:** ``` 🌍 Weather for Berlin, Germany: 🌡️ Temperature: 18°C (feels like 19°C) ☀️ Conditions: Clear skies 💨 Wind: 12 km/h northwest 💧 Humidity: 65% 👁️ Visibility: 10 km ``` --- ## 🎮 Gameplay Mechanics ### 🚶‍♂️ Movement System **Movement Controls:** - **Web Buttons**: Click directional arrows - **Keyboard**: WASD or arrow keys - **Movement Speed**: Fixed speed with smooth transitions - **Boundary Checking**: Prevents movement outside game world **Movement Feedback:** - **Visual**: Character position updates immediately - **Audio**: Optional movement sound effects - **Chat**: Movement can trigger proximity events - **Stats**: Position coordinates update in real-time ### 📈 Character Progression **Experience System:** - **Starting Level**: All players begin at level 1 - **Experience Gain**: Earn XP through various activities - **Level Up**: Automatic progression when XP threshold reached - **Benefits**: Higher levels unlock new features **Resource Management:** - **Health Points (HP)**: Combat and survival metric - **Gold**: In-game currency for transactions - **Experience (XP)**: Progression tracking - **Inventory**: Items and equipment (future feature) ### 🎯 Interaction System **NPC Interaction:** - **Proximity-based**: NPCs respond when players are nearby - **Message-based**: Send direct messages to any NPC - **Context-aware**: NPCs provide relevant responses - **Addon-powered**: Enhanced NPCs with special abilities **Player Interaction:** - **Public Chat**: Communicate with all players - **Private Messages**: Future feature for player-to-player - **Collaborative**: Work together on quests and challenges - **Social**: Build friendships and alliances ### 🌍 World Events **Dynamic Events:** - **Player Join/Leave**: Announced to all players - **NPC Activities**: Roaming NPCs change positions - **Weather Updates**: Real-time weather changes - **System Messages**: Important game announcements **Event Examples:** ``` 🌍 PlayerName has joined the adventure! 🚶‍♂️ Roaming Rick moved to the village square 🌤️ Weather updated for current location ⚔️ A new quest has become available ``` --- ## 🔌 MCP Integration ### 🤖 AI Agent Connection **MCP Endpoint:** - **URL**: `http://127.0.0.1:7868/gradio_api/mcp/sse` - **Protocol**: Server-Sent Events (SSE) - **Format**: JSON messages following MCP specification **Available MCP Tools:** 1. **join_game**: Register as a player 2. **leave_game**: Leave the game world 3. **move_up_handler/move_down_handler/move_left_handler/move_right_handler**: Movement controls 4. **handle_chat**: Send public chat messages 5. **handle_private_message**: Send private messages to NPCs 6. **register_test_ai_agent**: Register AI agent 7. **execute_ai_action**: Execute AI agent actions 8. **handle_mailbox_command**: Interact with Read2Burn system 9. **handle_weather_request**: Get weather information 10. **install_addon**: Add new NPC addons ### 📡 MCP Tool Usage Examples **Joining the Game:** ```json { "tool": "join_game", "parameters": { "name": "MyAIAgent" } } ``` **Moving Around:** ```json { "tool": "move_up_handler", "parameters": {} } ``` **Sending Chat:** ```json { "tool": "handle_chat", "parameters": { "message": "Hello from AI agent!" } } ``` **Talking to NPCs:** ```json { "tool": "handle_private_message", "parameters": { "message": "What quests are available?" } } ``` ### 🌐 MCP Server Development **Creating Custom MCP Servers:** 1. Implement MCP protocol specification 2. Expose game-relevant tools 3. Handle authentication (if required) 4. Provide tool descriptions and schemas 5. Test with the game platform **Integration Process:** 1. Start your MCP server 2. Use the **install_addon** tool 3. Provide server endpoint URL 4. Configure addon settings 5. Test functionality in-game --- ## 👨‍💻 Developer & AI Agent Usage ### 🔧 Platform Capabilities **MCP Testing Platform:** - **Real-world Environment**: Test MCP servers with actual users - **Interactive Feedback**: See how humans interact with your tools - **Performance Monitoring**: Track server response times and errors - **Integration Validation**: Verify MCP protocol compliance **Development Benefits:** - **Rapid Prototyping**: Quickly test new MCP server features - **User Experience Testing**: Observe how users interact with your tools - **Community Feedback**: Get input from real users - **Documentation**: Generate examples from actual usage ### 🤖 AI Agent Development **Agent Capabilities:** ```python # Example AI agent implementation class GameAIAgent: def __init__(self, name): self.name = name self.mcp_client = MCPClient("http://127.0.0.1:7868/gradio_api/mcp/sse") async def join_and_explore(self): # Join the game await self.mcp_client.call_tool("join_game", {"name": self.name}) # Explore the world directions = ["move_up_handler", "move_right_handler", "move_down_handler", "move_left_handler"] for direction in directions: await self.mcp_client.call_tool(direction, {}) await asyncio.sleep(1) # Interact with NPCs await self.mcp_client.call_tool("handle_private_message", { "message": "Hello, I'm an AI explorer!" }) ``` **Agent Use Cases:** - **Game Testing**: Automated gameplay testing - **NPC Interaction**: Test conversational AI systems - **Multiplayer Simulation**: Simulate player populations - **Data Collection**: Gather interaction data for research ### 🧩 Custom NPC Development **Addon Architecture:** ```python class CustomNPCAddon(NPCAddon): @property def addon_id(self) -> str: return "my_custom_npc" @property def addon_name(self) -> str: return "My Custom NPC" def get_interface(self) -> gr.Component: # Create Gradio interface pass def handle_command(self, player_id: str, command: str) -> str: # Process player commands return "Custom NPC response" ``` **Development Steps:** 1. Inherit from `NPCAddon` base class 2. Implement required methods 3. Create Gradio interface components 4. Handle player commands and interactions 5. Register addon with game world ### 📊 Research Applications **Human-AI Interaction Studies:** - **Mixed Populations**: Study humans and AI agents together - **Conversation Analysis**: Analyze chat patterns and interactions - **Behavior Modeling**: Model player behavior patterns - **Social Dynamics**: Understand multiplayer social structures **MCP Protocol Research:** - **Performance Analysis**: Measure protocol efficiency - **Compatibility Testing**: Test different MCP implementations - **Feature Evaluation**: Evaluate new MCP features - **Integration Patterns**: Develop best practices --- ## 🧩 NPC Addon System ### 📮 Read2Burn Mailbox **Features:** - **Self-destructing Messages**: Messages burn after reading - **Expiration Timer**: 24-hour automatic expiration - **Read Limits**: Configurable read count before burning - **Access Logging**: Track message creation and access - **Secure IDs**: Unique, hard-to-guess message identifiers **Commands:** - **create [message]**: Create new secure message - **read [message_id]**: Read and burn message - **list**: Show your active messages **Usage Example:** ``` Player: create Secret meeting location Mailbox: ✅ Message Created! ID: AbC123Xyz789 Player: read AbC123Xyz789 Mailbox: 📖 Message Content: Secret meeting location 🔥 This message has been BURNED and deleted forever! ``` ### 🌤️ Weather Oracle **Features:** - **Real-time Weather**: Live weather data via MCP - **Global Coverage**: Weather for any city worldwide - **Detailed Information**: Temperature, conditions, wind, humidity - **Format Flexibility**: Supports "City, Country" format - **Error Handling**: Graceful handling of invalid locations **Usage Examples:** ``` Player: Berlin, Germany Oracle: 🌍 Weather for Berlin, Germany: 🌡️ 18°C, clear skies 💨 Light winds, 65% humidity Player: Tokyo Oracle: 🌍 Weather for Tokyo, Japan: 🌡️ 22°C, partly cloudy 💨 Moderate winds, 70% humidity ``` ### 🏪 Generic NPCs **Built-in NPCs:** - **Village Elder**: Quests and lore - **Warrior Trainer**: Combat training - **Merchant**: Trading and equipment - **Mystic Oracle**: Magical services - **Roaming Rick**: Dynamic location updates **Response System:** - **Personality-based**: Each NPC has unique personality - **Context-aware**: Responses based on player context - **Randomized**: Multiple response options for variety - **Extensible**: Easy to add new NPCs and responses --- ## 🔬 Advanced Features ### 🎯 Auto-refresh System **Real-time Updates:** - **World State**: Continuous map updates - **Player Positions**: Live position tracking - **Chat Messages**: Instant message delivery - **NPC Status**: Dynamic NPC state updates **Performance Optimization:** - **Selective Updates**: Only update changed elements - **Throttling**: Prevent excessive update frequency - **Error Recovery**: Graceful handling of update failures - **Resource Management**: Efficient memory usage ### 🔐 Session Management **Player Sessions:** - **Unique IDs**: Each player gets unique session identifier - **State Persistence**: Maintain player state across interactions - **Cleanup**: Automatic cleanup of disconnected players - **Security**: Prevent session hijacking and spoofing **Multi-client Support:** - **Concurrent Players**: Multiple players simultaneously - **Session Isolation**: Each player's state remains separate - **Resource Sharing**: Efficient sharing of game world state - **Conflict Resolution**: Handle simultaneous action conflicts ### 📡 MCP Server Integration **Server Discovery:** - **Endpoint Management**: Track multiple MCP server endpoints - **Health Checking**: Monitor server availability - **Load Balancing**: Distribute requests across servers - **Failover**: Handle server outages gracefully **Protocol Support:** - **SSE Integration**: Server-Sent Events for real-time communication - **Tool Discovery**: Automatic detection of available tools - **Schema Validation**: Ensure tool parameters match schemas - **Error Handling**: Robust error recovery and reporting ### 🎨 UI Customization **Theme System:** - **Color Schemes**: Multiple visual themes - **Layout Options**: Customizable interface layouts - **Accessibility**: Support for screen readers and keyboard navigation - **Responsive Design**: Works on different screen sizes **Interface Components:** - **Gradio Integration**: Rich web interface components - **Custom Styling**: CSS customization options - **Interactive Elements**: Buttons, inputs, displays - **Real-time Updates**: Live data binding and updates --- ## 🔧 Troubleshooting ### 🚨 Common Issues **Connection Problems:** ``` Issue: "Cannot connect to game server" Solution: 1. Check if server is running (python app.py) 2. Verify port 7868 is available 3. Check firewall settings 4. Try restarting the server ``` **Keyboard Controls Not Working:** ``` Issue: "WASD keys don't move character" Solution: 1. Ensure JavaScript is enabled 2. Click on the game interface to focus 3. Check browser console for errors 4. Try refreshing the page ``` **NPC Not Responding:** ``` Issue: "NPC doesn't reply to messages" Solution: 1. Check NPC addon is loaded 2. Verify message format 3. Look for error messages in console 4. Try different NPC ``` **MCP Connection Failures:** ``` Issue: "AI agent cannot connect via MCP" Solution: 1. Verify MCP endpoint URL 2. Check MCP server is running 3. Validate tool parameters 4. Review MCP protocol compliance ``` ### 🐛 Debug Information **Enable Debug Mode:** ```python # Add to app.py for detailed logging import logging logging.basicConfig(level=logging.DEBUG) ``` **Check Logs:** - **Console Output**: Server startup and error messages - **Browser Console**: JavaScript errors and warnings - **MCP Logs**: Tool call results and errors - **Game Events**: Player actions and world updates **Performance Monitoring:** - **Player Count**: Monitor concurrent player limits - **Memory Usage**: Track RAM consumption - **Response Times**: Measure tool execution times - **Error Rates**: Monitor failure frequencies --- ## 📚 API Reference ### 🎮 Core Game APIs **Player Management:** ```python # Join game game_world.add_player(player: Player) -> bool # Leave game game_world.remove_player(player_id: str) -> bool # Move player game_world.move_player(player_id: str, direction: str) -> bool ``` **Chat System:** ```python # Public chat game_world.add_chat_message(sender: str, message: str, message_type: str = "public") # Private message game_world.send_private_message(sender_id: str, target_id: str, message: str) -> tuple[bool, str] ``` **World State:** ```python # Get world HTML create_game_world_html() -> str # Player stats get_player_stats_display(player_id: str) -> Dict # Player session get_player_id_from_session(session_hash: str) -> Optional[str] ``` ### 🔌 MCP Tool Reference **Game Control Tools:** - `join_game(name: str)`: Join as player - `leave_game()`: Leave the game - `move_up_handler()`: Move up - `move_down_handler()`: Move down - `move_left_handler()`: Move left - `move_right_handler()`: Move right **Communication Tools:** - `handle_chat(message: str)`: Send public chat - `handle_private_message(message: str)`: Send private message **AI Agent Tools:** - `register_test_ai_agent(ai_name: str)`: Register AI agent - `execute_ai_action(action: str, message: str)`: Execute AI action **Addon Tools:** - `handle_mailbox_command(command: str)`: Read2Burn mailbox - `handle_weather_request(location: str)`: Weather information - `install_addon(addon_type: str, addon_url: str, addon_name: str)`: Install addon ### 🧩 Addon Development APIs **Base Classes:** ```python class NPCAddon(ABC): @property @abstractmethod def addon_id(self) -> str: ... @property @abstractmethod def addon_name(self) -> str: ... @abstractmethod def get_interface(self) -> gr.Component: ... @abstractmethod def handle_command(self, player_id: str, command: str) -> str: ... ``` **Registration:** ```python # Register addon game_world.addon_npcs[addon_id] = addon_instance # Access addon addon = game_world.addon_npcs.get(addon_id) ``` --- ## 🎯 Best Practices ### 👥 For Players **Effective Communication:** - Use clear, descriptive messages - Be patient with AI agents learning - Report bugs and issues promptly - Share interesting discoveries with community **Game Etiquette:** - Respect other players - Don't spam chat or commands - Help new players learn the game - Provide feedback to developers ### 🤖 For AI Agents **Efficient Integration:** - Cache frequently used data - Handle errors gracefully - Respect rate limits - Log interactions for debugging **Social Behavior:** - Introduce yourself when joining - Respond appropriately to other players - Follow game rules and conventions - Contribute positively to the community ### 👨‍💻 For Developers **MCP Server Development:** - Follow MCP protocol specifications exactly - Provide detailed tool descriptions - Handle edge cases and errors - Test thoroughly before deployment **Addon Development:** - Keep interfaces simple and intuitive - Provide helpful error messages - Document your addon's capabilities - Share code examples with community --- ## 📞 Support & Community ### 🆘 Getting Help **Documentation:** - This user guide for comprehensive information - NPC Addon Development Guide for addon creation - Simple Game Client Guide for client development - Sample MCP Server for server examples **Community Resources:** - GitHub Issues for bug reports and feature requests - Discussion forums for general questions - Developer Discord for real-time chat - Wiki for community-contributed content **Contact Information:** - **Technical Issues**: Create GitHub issue with detailed description - **Feature Requests**: Use GitHub discussions - **Security Issues**: Contact maintainers directly - **General Questions**: Use community forums ### 🤝 Contributing **Ways to Contribute:** - **Bug Reports**: Help identify and fix issues - **Feature Development**: Implement new capabilities - **Documentation**: Improve guides and tutorials - **Testing**: Quality assurance and validation - **Community Support**: Help other users and developers **Development Process:** 1. Fork the repository 2. Create feature branch 3. Implement changes with tests 4. Submit pull request 5. Participate in code review --- *This documentation is continuously updated. Last updated: June 6, 2025* *For the latest version, visit: https://github.com/your-repo/MMOP* **🎮 Happy Gaming and Developing! 🚀**