Message-Passing Specification for MUD Game Using SignalR and Akka.NET

Overview

This document outlines the structure and flow of messages within the MUD game environment, focusing on communication between players (UserSpace) and actors (AkkaSpace), inter-process communications, and special messages from admins or owners. The goal is to provide a clear and consistent message format that supports various types of interactions while maintaining flexibility and scalability.

Message Envelope Structure

All messages, whether originating from players, actors, or administrators, will use a standardized envelope structure. This envelope encapsulates the payload and metadata necessary for routing, security, and processing.

Envelope Components

1. MessageId: A unique identifier for the message.
2. Timestamp: The UTC time when the message was created.
3. Source: The origin of the message (e.g., Player, NPCActor, System, Admin).
4. Destination: The intended recipient(s) of the message (e.g., specific PlayerId, NPCActorId, Broadcast).
5. MessageType: The type of message (e.g., Command, Response, Notification, AdminCommand).
6. PayloadType: The format of the payload contained in the message (e.g., Text, JSON, Binary).
7. Payload: The actual content of the message, serialized according to the PayloadType.
8. Metadata: Optional metadata for additional context or instructions (e.g., priority, retries, tags).

{
  "MessageId": "string",         // A unique identifier for the message
  "Timestamp": "string",         // The UTC time when the message was created, formatted as ISO 8601
  "Source": "string",            // The origin of the message (e.g., "Player", "NPCActor", "System", "Admin")
  "Destination": "string",       // The intended recipient(s) of the message (e.g., "PlayerId", "NPCActorId", "Broadcast")
  "MessageType": "string",       // The type of message (e.g., "Command", "Response", "Notification", "AdminCommand")
  "PayloadType": "string",       // The format of the payload contained in the message (e.g., "Text", "JSON", "Binary")
  "Payload": "string",           // The actual content of the message, serialized according to the PayloadType
  "Metadata": {                  // Optional metadata for additional context or instructions
    "priority": "string",        // Example: "High", "Medium", "Low"
    "retries": "number",         // Number of retries allowed for this message if delivery fails
    "tags": ["string"]           // Additional tags or labels for the message (e.g., ["urgent", "combat"])
  }
}

Message Types

1. Player-to-Actor Messages

• Description: Messages initiated by players directed towards NPC actors or other game processes. These represent commands or interactions.
• MessageType: Command, Chat, Action
• PayloadType: Usually JSON to represent structured commands or actions.
• Examples:
  • Command to move in a direction.
  • Chat message to another character.
  • Action to attack an NPC.

2. Actor-to-Player Messages

• Description: Responses or notifications from NPC actors or game systems back to the player. These provide feedback on actions or convey game state information.
• MessageType: Response, Notification
• PayloadType: JSON or Text depending on the complexity of the response.
• Examples:
  • Response confirming a successful action.
  • Notification about an event in the game world.

3. Inter-Actor Messages

• Description: Messages exchanged between actors (NPCs, system processes, etc.) within Akka.NET. These coordinate actions, share state, or execute distributed algorithms.
• MessageType: StateUpdate, Coordination, Event
• PayloadType: Binary or JSON for efficiency and structured data interchange.
• Examples:
  • State update of an NPC.
  • Coordination for a joint task.
  • Event signaling the start of combat.

4. Admin-to-Actor Messages

• Description: Special commands or instructions issued by game administrators or owners. These messages include commands to ban players, restart servers, or manually alter game states.
• MessageType: AdminCommand
• PayloadType: JSON or Text depending on the nature of the command.
• Examples:
  • Command to ban a player.
  • Instruction to restart the server.

Routing and Handling

1. Routing Logic

Messages are routed based on the Destination field:

• Player-to-Actor: Routed from SignalR to Akka.NET actors based on player input.
• Actor-to-Player: Routed from Akka.NET actors to SignalR, addressed to the correct player connection.
• Inter-Actor: Routed within Akka.NET based on actor IDs and locations.
• Admin-to-Actor: Routed from an admin interface directly to the intended actor or process.

2. Payload Processing

Upon receipt, each message's Payload is deserialized according to the PayloadType:

• Text: Directly passed to display or log.
• JSON: Parsed into structured objects or command models.
• Binary: Decoded into application-specific data formats (e.g., state updates).

3. Error Handling and Retries

• Messages that fail to deliver are logged with the MessageId and retried according to the Metadata retry policy.
• Errors in deserialization or processing trigger error messages back to the sender (player or actor) with appropriate details.

Special Considerations

1. Security and Validation: All messages must be validated and sanitized to prevent injection attacks or unauthorized actions. Admin commands require additional authentication.
2. Performance Optimization: Messages between actors should use the most efficient PayloadType (e.g., Binary for frequent state updates) to minimize processing overhead.
3. Extensibility: The message system should support easy extension for new message types or payload formats as the game evolves.

Conclusion

By standardizing the message envelope and defining clear routing and handling strategies, we ensure robust, flexible, and scalable communication across the MUD game environment. This system facilitates dynamic interactions between players and NPCs, supports complex NPC behaviors, and provides administrative control, all while maintaining performance and security.