Beyhan Oğur
19 KiB
19 KiB
Chat System
**Referenced Files in This Document** - [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs) - [ChatMessage.cs](file://ClassicAssist.Shared/Data/Chat/ChatMessage.cs) - [ChatUser.cs](file://ClassicAssist.Shared/Data/Chat/ChatUser.cs) - [ChatWindow.xaml](file://ClassicAssist.Avalonia/Views/ChatWindow.xaml) - [ChatWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/ChatWindow.xaml.cs) - [ChatViewModel.cs](file://ClassicAssist/UI/ViewModels/ChatViewModel.cs) - [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs) - [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs) - [UnicodeText.cs](file://ClassicAssist.Shared/UO/Network/Packets/UnicodeText.cs) - [FilterEntry.cs](file://ClassicAssist.Shared/Data/Filters/FilterEntry.cs) - [RepeatedMessagesFilter.cs](file://ClassicAssist.Shared/Data/Filters/RepeatedMessagesFilter.cs) - [ClilocFilter.cs](file://ClassicAssist.Shared/Data/Filters/ClilocFilter.cs) - [Options.cs](file://ClassicAssist.Shared/Data/Options.cs) - [AssistantOptions.cs](file://ClassicAssist.Shared/Data/AssistantOptions.cs)Table of Contents
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
Introduction
This document explains the ClassicAssist.Avalonia chat system with a focus on:
- The ChatManager class and its role in managing channels, routing messages, and coordinating user interactions
- The ChatMessage and ChatUser data models, their properties, relationships, and lifecycle management
- The chat window interface implementation for real-time display, channel switching, and input handling
- Message filtering capabilities including built-in filters and how to develop custom filters
- Integration with Ultima Online’s native chat protocol and packet handling
- Configuration options for appearance, notifications, and logging
- Performance optimization strategies for high-volume chat processing and memory management
Project Structure
The chat system spans shared logic and UI layers:
- Shared domain and networking:
- Data models and manager: ChatManager, ChatMessage, ChatUser
- UO network integration: IncomingPacketHandlers, IncomingPacketFilters, UnicodeText packet
- Filters: FilterEntry and specific filter implementations
- Options: Options and AssistantOptions for configuration
- Avalonia UI:
- Views: ChatWindow.axaml and code-behind
- ViewModel: ChatViewModel (shared UI layer)
graph TB
subgraph "Shared"
CM["ChatManager"]
MSG["ChatMessage"]
USER["ChatUser"]
INH["IncomingPacketHandlers"]
INF["IncomingPacketFilters"]
PKT["UnicodeText Packet"]
FENTRY["FilterEntry"]
RFILT["RepeatedMessagesFilter"]
CFILT["ClilocFilter"]
OPTS["Options / AssistantOptions"]
end
subgraph "Avalonia UI"
CWXAML["ChatWindow.axaml"]
CWCSD["ChatWindow.xaml.cs"]
CVM["ChatViewModel"]
end
PKT --> INH
INH --> CM
CM --> MSG
CM --> USER
CM --> INF
INF --> FENTRY
FENTRY --> RFILT
FENTRY --> CFILT
CM --> CVM
CVM --> CWXAML
CVM --> CWCSD
OPTS --> CM
OPTS --> CVM
Diagram sources
- ChatManager.cs
- ChatMessage.cs
- ChatUser.cs
- IncomingPacketHandlers.cs
- IncomingPacketFilters.cs
- UnicodeText.cs
- FilterEntry.cs
- RepeatedMessagesFilter.cs
- ClilocFilter.cs
- Options.cs
- AssistantOptions.cs
- ChatWindow.xaml
- ChatWindow.xaml.cs
- ChatViewModel.cs
Section sources
- ChatManager.cs
- ChatMessage.cs
- ChatUser.cs
- IncomingPacketHandlers.cs
- IncomingPacketFilters.cs
- UnicodeText.cs
- FilterEntry.cs
- RepeatedMessagesFilter.cs
- ClilocFilter.cs
- Options.cs
- AssistantOptions.cs
- ChatWindow.xaml
- ChatWindow.xaml.cs
- ChatViewModel.cs
Core Components
- ChatManager
- Central coordinator for chat channels, message ingestion, filtering, and dispatch to UI
- Manages user presence and per-channel state
- Integrates with incoming packet handlers and filter pipeline
- ChatMessage
- Represents a single chat event with metadata such as timestamp, sender, channel, color, and text
- Used by both filtering and UI rendering
- ChatUser
- Represents a player or entity participating in chat
- Tracks identity and attributes relevant to chat display and filtering
These components collaborate to receive packets, parse them into messages, apply filters, and present results in the chat window.
Section sources
Architecture Overview
The chat system follows a layered architecture:
- Network layer parses UO packets into structured events
- Processing layer converts events into ChatMessage instances and applies filters
- Presentation layer binds filtered messages to the chat window via a view model
sequenceDiagram
participant Net as "UO Network"
participant InH as "IncomingPacketHandlers"
participant Pkt as "UnicodeText Packet"
participant CM as "ChatManager"
participant Fil as "Filter Pipeline"
participant VM as "ChatViewModel"
participant Win as "ChatWindow"
Net->>InH : "Receive raw packet"
InH->>Pkt : "Parse into UnicodeText"
Pkt-->>InH : "Parsed packet"
InH->>CM : "Dispatch parsed chat event"
CM->>CM : "Create ChatMessage"
CM->>Fil : "Apply filters"
Fil-->>CM : "Filtered result"
CM->>VM : "Notify new message"
VM->>Win : "Update UI binding"
Win-->>VM : "User input / channel switch"
VM->>CM : "Forward actions"
Diagram sources
- IncomingPacketHandlers.cs
- UnicodeText.cs
- ChatManager.cs
- IncomingPacketFilters.cs
- ChatViewModel.cs
- ChatWindow.xaml
- ChatWindow.xaml.cs
Detailed Component Analysis
ChatManager
Responsibilities:
- Channel management: creation, selection, and persistence of active channels
- Message routing: receiving parsed chat events, constructing ChatMessage objects, applying filters, and notifying observers
- User coordination: tracking participants and updating presence information
- Configuration integration: reading options for behavior and appearance
Key behaviors:
- On incoming chat event:
- Parse packet fields into ChatMessage
- Apply configured filters
- Persist or cache recent messages
- Raise UI updates through the view model
- On user actions:
- Handle channel switches and input submission
- Update UI state and notify subscribers
classDiagram
class ChatManager {
+SelectChannel(channel)
+AddMessage(event)
+ApplyFilters(message)
+GetActiveChannel()
+SubscribeToUpdates(observer)
}
class ChatMessage {
+Timestamp
+Sender
+Channel
+Color
+Text
}
class ChatUser {
+Id
+Name
+Attributes
}
class FilterPipeline {
+Evaluate(message) bool
}
ChatManager --> ChatMessage : "creates"
ChatManager --> ChatUser : "tracks"
ChatManager --> FilterPipeline : "uses"
Diagram sources
Section sources
ChatMessage and ChatUser Models
ChatMessage:
- Properties include timestamp, sender reference, channel identifier, color/hue, and textual content
- Lifecycle: created from incoming packets, passed through filters, then bound to UI; may be retained in a bounded buffer for performance
ChatUser:
- Properties include unique identifier, display name, and optional attributes used for coloring or filtering
- Relationship: referenced by ChatMessage to link messages to users
erDiagram
CHATMESSAGE {
datetime Timestamp
string SenderId
string Channel
int Color
string Text
}
CHATUSER {
string Id
string Name
map Attributes
}
CHATUSER ||--o{ CHATMESSAGE : "sends"
Diagram sources
Section sources
Chat Window Interface (Avalonia)
Components:
- ChatWindow.axaml defines layout and bindings for message list, channel selector, and input area
- ChatWindow.xaml.cs provides code-behind for window behavior and interaction hooks
- ChatViewModel coordinates UI state, handles user input, and subscribes to ChatManager updates
Workflow:
- Real-time display: view model listens for new messages and updates observable collections
- Channel switching: view model requests channel change from ChatManager and refreshes display
- Input handling: captures user input, validates, and forwards to ChatManager for sending
sequenceDiagram
participant VM as "ChatViewModel"
participant CM as "ChatManager"
participant Win as "ChatWindow"
Win->>VM : "User types message"
VM->>CM : "Submit message"
CM-->>VM : "Acknowledge / update state"
VM->>Win : "Refresh UI"
Win->>VM : "Switch channel"
VM->>CM : "Change active channel"
CM-->>VM : "Provide channel messages"
VM->>Win : "Render channel history"
Diagram sources
Section sources
Message Filtering Capabilities
Built-in filters:
- RepeatedMessagesFilter: suppresses duplicate or near-duplicate messages based on configurable thresholds
- ClilocFilter: matches messages against localized strings for targeted filtering
Filter framework:
- FilterEntry defines the base contract and configuration surface for filters
- IncomingPacketFilters orchestrates evaluation across registered filters
Custom filter development:
- Implement the filter interface defined by the filter entry base
- Provide configuration options via the filter options attribute mechanism
- Register the filter with the pipeline so it participates in message evaluation
flowchart TD
Start(["New ChatMessage"]) --> Eval["Evaluate Filters"]
Eval --> Repeat{"RepeatedMessagesFilter?"}
Repeat --> |Yes| Drop["Drop message"]
Repeat --> |No| Cliloc{"ClilocFilter?"}
Cliloc --> |Match| Drop
Cliloc --> |No Match| Keep["Keep message"]
Drop --> End(["End"])
Keep --> End
Diagram sources
Section sources
Integration with Ultima Online Chat Protocol
Packet handling:
- IncomingPacketHandlers listen for UO chat-related packets
- UnicodeText packet is parsed into structured data and forwarded to ChatManager
- ChatManager constructs ChatMessage instances and proceeds through the filter pipeline
sequenceDiagram
participant UO as "UO Client"
participant InH as "IncomingPacketHandlers"
participant Pkt as "UnicodeText"
participant CM as "ChatManager"
UO->>InH : "Send chat packet"
InH->>Pkt : "Deserialize packet"
Pkt-->>InH : "Structured fields"
InH->>CM : "Invoke chat handler"
CM->>CM : "Build ChatMessage"
Diagram sources
Section sources
Configuration Options
Appearance:
- Colors, fonts, and formatting can be controlled via options consumed by the view model and renderer
Notifications:
- Toggleable notification settings allow users to enable/disable alerts for specific channels or senders
Logging:
- Logging preferences control verbosity and destinations for chat logs
Configuration sources:
- Options and AssistantOptions provide strongly-typed settings that are read by ChatManager and ChatViewModel
Section sources
Dependency Analysis
The chat system exhibits clear separation between networking, processing, and presentation:
- Networking depends on UO packet definitions and handlers
- Processing depends on data models and filters
- Presentation depends on view models and UI controls
graph LR
InH["IncomingPacketHandlers"] --> Pkt["UnicodeText"]
InH --> CM["ChatManager"]
CM --> MSG["ChatMessage"]
CM --> USER["ChatUser"]
CM --> FIL["FilterPipeline"]
FIL --> RFILT["RepeatedMessagesFilter"]
FIL --> CFILT["ClilocFilter"]
CM --> VM["ChatViewModel"]
VM --> CW["ChatWindow"]
Diagram sources
- IncomingPacketHandlers.cs
- UnicodeText.cs
- ChatManager.cs
- ChatMessage.cs
- ChatUser.cs
- IncomingPacketFilters.cs
- RepeatedMessagesFilter.cs
- ClilocFilter.cs
- ChatViewModel.cs
- ChatWindow.xaml
Section sources
Performance Considerations
High-volume chat processing requires careful attention to throughput and memory usage:
- Bounded message buffers: limit retained messages to reduce memory pressure while preserving recent history
- Efficient filtering: short-circuit filters when possible and avoid heavy allocations inside hot paths
- UI batching: coalesce UI updates to minimize layout passes and redraws
- Thread affinity: ensure UI updates occur on the UI thread using the dispatcher provided by the platform
- Garbage collection: reuse objects where feasible and avoid unnecessary string allocations
[No sources needed since this section provides general guidance]
Troubleshooting Guide
Common issues and resolutions:
- Messages not appearing:
- Verify incoming packet handlers are registered and parsing UnicodeText correctly
- Check filter pipeline configuration to ensure messages are not being dropped unintentionally
- Incorrect colors or formatting:
- Confirm options for appearance are applied consistently in the view model and renderer
- High CPU usage during chat spikes:
- Review filter complexity and consider simplifying conditions
- Ensure UI updates are batched and not triggered excessively
Section sources
Conclusion
The ClassicAssist.Avalonia chat system integrates tightly with Ultima Online’s packet protocol, providing robust channel management, flexible filtering, and responsive UI. By leveraging well-defined data models and a modular filter pipeline, it supports both built-in and custom filtering scenarios. Configuration options allow tailoring appearance, notifications, and logging. For high-volume environments, adopting bounded buffers, efficient filtering, and UI batching ensures smooth performance and stable memory usage.