Global Chat Session Implementation

Overview

PadawanForge implements global chat functionality using a single, unique ChatLobby Durable Object session that all users connect to for platform-wide communication. This approach provides a simple, scalable solution without requiring a separate Durable Object class.

Architecture

Single ChatLobby with Global Session

ChatLobby Durable Object
├── Regular Room Sessions (UUID-based)
│   ├── Room-specific chat
│   ├── NPC interactions
│   └── Game session features
└── Global Chat Session (ID: 'global-chat')
    ├── Platform-wide communication
    ├── Global statistics
    └── Community features

Key Implementation Details

  1. Unique Session ID: Global chat uses a fixed ID 'global-chat' for the ChatLobby Durable Object
  2. Message Type Detection: The ChatLobby detects global sessions and handles messages differently
  3. Database Storage: Global messages are stored with game_session_id = 'global-chat'
  4. API Routing: /api/global-chat routes to the specific global chat session

Implementation

ChatLobby Modifications

Location: src/durable-objects/ChatLobby.ts

Key Changes:

  • Added isGlobalChat flag to detect global sessions
  • Added global-specific message handlers:
    • handlePlayerJoinGlobal(): Handles global chat joins
    • handleGlobalMessage(): Processes global chat messages
    • handleTypingStart() / handleTypingStop(): Typing indicators
    • sendGlobalStats(): Sends platform statistics

Global Session Detection:

constructor(state: DurableObjectState, env: any) {
  // ...
  this.isGlobalChat = this.state.id.toString() === 'global-chat';
}

Message Type Handling:

switch (data.type) {
  case 'player_join_global':
    await this.handlePlayerJoinGlobal(sessionId, data.player);
    break;
  case 'global_message':
    await this.handleGlobalMessage(sessionId, data.message, data.attachments);
    break;
  // ... other cases
}

API Endpoint

Location: src/pages/api/global-chat.ts

Functionality:

  • Routes WebSocket connections to the global chat session
  • Uses env.CHAT_LOBBY.idFromName('global-chat') to get the specific session
  • Handles both GET and POST requests

WebSocket URL: wss://your-domain.com/api/global-chat

Frontend Integration

Location: src/components/game/multi-room-chat-lobby.tsx

Global Chat Features:

  • Connects to global chat via /api/global-chat
  • Sends player_join_global message on connection
  • Handles global-specific message types:
    • global_message: Regular chat messages
    • welcome_global: Welcome messages
    • global_stats: Platform statistics
    • global_player_list: Online players list
    • typing_start_global / typing_stop_global: Typing indicators

Message Flow

Global Chat Connection

  1. Client connects to /api/global-chat
  2. API routes to ChatLobby with ID 'global-chat'
  3. ChatLobby detects global session via isGlobalChat flag
  4. Client sends player_join_global message
  5. ChatLobby broadcasts join notification to all global participants

Global Message Sending

  1. Client sends global_message type
  2. ChatLobby processes via handleGlobalMessage()
  3. Message stored with game_session_id = 'global-chat'
  4. Message broadcast to all global chat participants
  5. Experience awarded for global participation

Database Schema

Global Chat Messages

Global chat messages use the existing chat_messages table with special identifiers:

-- Global chat messages
INSERT INTO chat_messages (
  game_session_id, 
  player_uuid, 
  message, 
  message_type, 
  has_attachments
) VALUES (
  'global-chat',  -- Special identifier for global chat
  ?, 
  ?, 
  'global',       -- Special message type
  ?
);

Message Types

  • Room Messages: game_session_id = room UUID, message_type = ‘text’
  • Global Messages: game_session_id = ‘global-chat’, message_type = ‘global’
  • NPC Messages: game_session_id = room UUID or ‘global-chat’, message_type = ‘npc’

Benefits of This Approach

1. Simplicity

  • No new Durable Object class required
  • Reuses existing ChatLobby infrastructure
  • Minimal code changes needed

2. Scalability

  • Single global session handles all platform-wide communication
  • Efficient resource usage
  • Easy to monitor and manage

3. Consistency

  • Same message handling patterns as room chat
  • Consistent database schema
  • Unified error handling

4. Maintainability

  • Single codebase for chat functionality
  • Easier to debug and test
  • Reduced complexity

Usage Examples

Connecting to Global Chat

const ws = new WebSocket('wss://your-domain.com/api/global-chat');

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'player_join_global',
    player: {
      uuid: player.uuid,
      username: player.username,
      avatar: player.avatar,
      level: player.level,
      experience: player.experience
    }
  }));
};

Sending Global Messages

ws.send(JSON.stringify({
  type: 'global_message',
  message: 'Hello, everyone!',
  player: playerData
}));

Receiving Global Messages

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  
  switch (data.type) {
    case 'global_message':
      // Handle global chat message
      break;
    case 'welcome_global':
      // Handle welcome message
      break;
    case 'global_stats':
      // Update global statistics
      break;
  }
};

Monitoring and Analytics

Global Chat Metrics

Key Metrics to Monitor:

  • Connection Count: Number of active global chat connections
  • Message Volume: Messages per minute in global chat
  • Player Engagement: Unique players participating in global chat
  • Performance: Response times and error rates

Monitoring Queries:

-- Global chat message volume
SELECT 
  DATE(timestamp) as date,
  COUNT(*) as message_count
FROM chat_messages 
WHERE game_session_id = 'global-chat'
GROUP BY DATE(timestamp)
ORDER BY date DESC;

-- Global chat participants
SELECT 
  COUNT(DISTINCT player_uuid) as unique_participants
FROM chat_messages 
WHERE game_session_id = 'global-chat'
AND timestamp >= datetime('now', '-1 day');

Future Enhancements

Planned Features

  1. Global NPCs: Platform-wide AI assistants
  2. Moderation Tools: Global chat moderation and filtering
  3. Channel System: Multiple global chat channels
  4. Integration Features: Cross-room notifications
  5. Analytics Dashboard: Real-time global chat analytics

Scalability Considerations

  1. Message Archiving: Automatic archiving of old global messages
  2. Rate Limiting: Per-user rate limiting for global chat
  3. Content Filtering: AI-powered content moderation
  4. Performance Optimization: Message batching and compression

Conclusion

The global chat session implementation provides a simple, efficient solution for platform-wide communication using the existing ChatLobby infrastructure. This approach maintains consistency with room-based chat while providing specialized features for global communication.

The single session design ensures optimal resource usage and easy management, while the unified codebase simplifies maintenance and development.

← Global Chat Layout Integration Infrastructure Features →
PadawanForge v1.4.1