beyhan/ClassicAssist.Avalonia
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b7db07060fcbf017429f64877e5b54975ec3e26a
ClassicAssist.Avalonia/.qoder/repowiki/en/content/Communication Tools/Chat System.md
T
Beyhan Oğur d5f52cc3d3 first commit
2026-09-03 04:45:36 +03:00

451 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Chat System
<cite>
**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)
</cite>
## Table of Contents
1. [Introduction](#introduction)
2. [Project Structure](#project-structure)
3. [Core Components](#core-components)
4. [Architecture Overview](#architecture-overview)
5. [Detailed Component Analysis](#detailed-component-analysis)
6. [Dependency Analysis](#dependency-analysis)
7. [Performance Considerations](#performance-considerations)
8. [Troubleshooting Guide](#troubleshooting-guide)
9. [Conclusion](#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)
```mermaid
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](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)
- [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)
- [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)
**Section sources**
- [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)
- [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)
- [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)
## 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**
- [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)
## 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
```mermaid
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](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
- [UnicodeText.cs](file://ClassicAssist.Shared/UO/Network/Packets/UnicodeText.cs)
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
- [ChatViewModel.cs](file://ClassicAssist/UI/ViewModels/ChatViewModel.cs)
- [ChatWindow.xaml](file://ClassicAssist.Avalonia/Views/ChatWindow.xaml)
- [ChatWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/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
```mermaid
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**
- [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)
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
**Section sources**
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
### 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
```mermaid
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**
- [ChatMessage.cs](file://ClassicAssist.Shared/Data/Chat/ChatMessage.cs)
- [ChatUser.cs](file://ClassicAssist.Shared/Data/Chat/ChatUser.cs)
**Section sources**
- [ChatMessage.cs](file://ClassicAssist.Shared/Data/Chat/ChatMessage.cs)
- [ChatUser.cs](file://ClassicAssist.Shared/Data/Chat/ChatUser.cs)
### 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
```mermaid
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**
- [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)
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
**Section sources**
- [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)
### 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
```mermaid
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**
- [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)
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
**Section sources**
- [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)
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
### 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
```mermaid
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**
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
- [UnicodeText.cs](file://ClassicAssist.Shared/UO/Network/Packets/UnicodeText.cs)
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
**Section sources**
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
- [UnicodeText.cs](file://ClassicAssist.Shared/UO/Network/Packets/UnicodeText.cs)
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
### 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**
- [Options.cs](file://ClassicAssist.Shared/Data/Options.cs)
- [AssistantOptions.cs](file://ClassicAssist.Shared/Data/AssistantOptions.cs)
## 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
```mermaid
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](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
- [UnicodeText.cs](file://ClassicAssist.Shared/UO/Network/Packets/UnicodeText.cs)
- [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)
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
- [RepeatedMessagesFilter.cs](file://ClassicAssist.Shared/Data/Filters/RepeatedMessagesFilter.cs)
- [ClilocFilter.cs](file://ClassicAssist.Shared/Data/Filters/ClilocFilter.cs)
- [ChatViewModel.cs](file://ClassicAssist/UI/ViewModels/ChatViewModel.cs)
- [ChatWindow.xaml](file://ClassicAssist.Avalonia/Views/ChatWindow.xaml)
**Section sources**
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
- [ChatViewModel.cs](file://ClassicAssist/UI/ViewModels/ChatViewModel.cs)
## 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**
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
- [ChatViewModel.cs](file://ClassicAssist/UI/ViewModels/ChatViewModel.cs)
## 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.
Reference in New Issue View Git Blame Copy Permalink