first commit
This commit is contained in:
Beyhan Oğur
@@ -0,0 +1,451 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,461 @@
|
||||
# Cliloc Text System
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [Cliloc.cs](file://ClassicAssist.Shared/UO/Data/Cliloc.cs)
|
||||
- [Language.cs](file://ClassicAssist.Shared/Data/Language.cs)
|
||||
- [Strings.resx](file://ClassicAssist.Shared/Resources/Strings.resx)
|
||||
- [Strings.Designer.cs](file://ClassicAssist.Shared/Resources/Strings.Designer.cs)
|
||||
- [Strings.en-AU.resx](file://ClassicAssist.Shared/Resources/Strings.en-AU.resx)
|
||||
- [Strings.en-GB.resx](file://ClassicAssist.Shared/Resources/Strings.en-GB.resx)
|
||||
- [Strings.it-IT.resx](file://ClassicAssist.Shared/Resources/Strings.it-IT.resx)
|
||||
- [Strings.ko-KR.resx](file://ClassicAssist.Shared/Resources/Strings.ko-KR.resx)
|
||||
- [Strings.pl-PL.resx](file://ClassicAssist.Shared/Resources/Strings.pl-PL.resx)
|
||||
- [Strings.zh.resx](file://ClassicAssist.Shared/Resources/Strings.zh.resx)
|
||||
- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
|
||||
- [ClilocFilter.cs](file://ClassicAssist.Shared/Data/Filters/ClilocFilter.cs)
|
||||
- [ClilocSelectionViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Autoloot/ClilocSelectionViewModel.cs)
|
||||
- [ClilocSelectionWindow.xaml](file://ClassicAssist.Avalonia/Views/Autoloot/ClilocSelectionWindow.xaml)
|
||||
- [ClilocSelectionWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/Autoloot/ClilocSelectionWindow.xaml.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)
|
||||
10. [Appendices](#appendices)
|
||||
|
||||
## Introduction
|
||||
This document explains the cliloc text system and localization framework used by ClassicAssist.Avalonia. It covers how localized strings are loaded from Ultima Online client files, how .resx-based resources are structured and consumed at runtime, how XAML bindings resolve strings via a value converter, and how multi-language support is implemented with detection, fallback, and runtime switching. It also documents integration with game text formatting (parameter substitution), strategies for adding new languages, maintaining consistency, and performance considerations for large text databases.
|
||||
|
||||
## Project Structure
|
||||
The cliloc and localization features span shared data models, resource files, UI converters, and view models:
|
||||
- UO data layer provides the core cliloc loader/parser and language enumeration.
|
||||
- Shared resources provide .resx-based application strings with designer-generated accessors.
|
||||
- Avalonia UI provides a StringToResourceConverter to bind XAML to localized strings.
|
||||
- Autoloot feature includes a window and view model that interact with cliloc entries.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Shared"
|
||||
CL["Cliloc.cs"]
|
||||
LG["Language.cs"]
|
||||
RESX["Strings.*.resx + Strings.Designer.cs"]
|
||||
CF["ClilocFilter.cs"]
|
||||
CVM["ClilocSelectionViewModel.cs"]
|
||||
end
|
||||
subgraph "Avalonia UI"
|
||||
SRC["StringToResourceConverter.cs"]
|
||||
CSW["ClilocSelectionWindow.xaml(.cs)"]
|
||||
end
|
||||
CL --> LG
|
||||
RESX --> SRC
|
||||
SRC --> CSW
|
||||
CF --> CL
|
||||
CVM --> CL
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Cliloc.cs](file://ClassicAssist.Shared/UO/Data/Cliloc.cs)
|
||||
- [Language.cs](file://ClassicAssist.Shared/Data/Language.cs)
|
||||
- [Strings.Designer.cs](file://ClassicAssist.Shared/Resources/Strings.Designer.cs)
|
||||
- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
|
||||
- [ClilocFilter.cs](file://ClassicAssist.Shared/Data/Filters/ClilocFilter.cs)
|
||||
- [ClilocSelectionViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Autoloot/ClilocSelectionViewModel.cs)
|
||||
- [ClilocSelectionWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/Autoloot/ClilocSelectionWindow.xaml.cs)
|
||||
|
||||
**Section sources**
|
||||
- [Cliloc.cs](file://ClassicAssist.Shared/UO/Data/Cliloc.cs)
|
||||
- [Language.cs](file://ClassicAssist.Shared/Data/Language.cs)
|
||||
- [Strings.Designer.cs](file://ClassicAssist.Shared/Resources/Strings.Designer.cs)
|
||||
- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
|
||||
- [ClilocFilter.cs](file://ClassicAssist.Shared/Data/Filters/ClilocFilter.cs)
|
||||
- [ClilocSelectionViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Autoloot/ClilocSelectionViewModel.cs)
|
||||
- [ClilocSelectionWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/Autoloot/ClilocSelectionWindow.xaml.cs)
|
||||
|
||||
## Core Components
|
||||
- Cliloc class: Loads, parses, and manages cliloc entries from Ultima Online client files. Provides lookup APIs for retrieving localized strings by ID, with optional parameter substitution.
|
||||
- Language enum: Represents supported cultures/languages and drives selection and fallback behavior.
|
||||
- .resx resources: Provide application-level localized strings with designer-generated strongly-typed accessors.
|
||||
- StringToResourceConverter: Bridges XAML binding to .resx resources, enabling dynamic string resolution and parameter substitution in markup.
|
||||
- ClilocFilter and ClilocSelectionViewModel: Use cliloc data for filtering and user selection workflows.
|
||||
|
||||
Key responsibilities:
|
||||
- Resource discovery and parsing for cliloc files.
|
||||
- In-memory indexing for fast lookups.
|
||||
- Culture-aware resolution and fallback.
|
||||
- Parameterized message formatting compatible with UO cliloc format.
|
||||
- Integration points for UI and filters.
|
||||
|
||||
**Section sources**
|
||||
- [Cliloc.cs](file://ClassicAssist.Shared/UO/Data/Cliloc.cs)
|
||||
- [Language.cs](file://ClassicAssist.Shared/Data/Language.cs)
|
||||
- [Strings.Designer.cs](file://ClassicAssist.Shared/Resources/Strings.Designer.cs)
|
||||
- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
|
||||
- [ClilocFilter.cs](file://ClassicAssist.Shared/Data/Filters/ClilocFilter.cs)
|
||||
- [ClilocSelectionViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Autoloot/ClilocSelectionViewModel.cs)
|
||||
|
||||
## Architecture Overview
|
||||
The system combines two complementary localization mechanisms:
|
||||
- Game cliloc: Loaded from UO client files into an in-memory store for fast retrieval and formatting.
|
||||
- Application .resx: Designer-managed resources for UI strings, accessed via generated properties and XAML converters.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant UI as "XAML View"
|
||||
participant Conv as "StringToResourceConverter"
|
||||
participant Res as ".resx Resources"
|
||||
participant VM as "ViewModel"
|
||||
participant CL as "Cliloc"
|
||||
participant Lang as "Language"
|
||||
UI->>Conv : Resolve key with parameters
|
||||
Conv->>Res : Get localized string by key/culture
|
||||
Res-->>Conv : Base string template
|
||||
Conv->>Conv : Apply parameter substitution
|
||||
Conv-->>UI : Formatted text
|
||||
VM->>CL : Lookup(clilocId, params)
|
||||
CL->>Lang : Determine current culture/fallback
|
||||
CL-->>VM : Localized message
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
|
||||
- [Strings.Designer.cs](file://ClassicAssist.Shared/Resources/Strings.Designer.cs)
|
||||
- [Cliloc.cs](file://ClassicAssist.Shared/UO/Data/Cliloc.cs)
|
||||
- [Language.cs](file://ClassicAssist.Shared/Data/Language.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### Cliloc Class
|
||||
Responsibilities:
|
||||
- Discover and load cliloc files from the UO client directory.
|
||||
- Parse binary or text-based cliloc formats into an internal index keyed by numeric IDs.
|
||||
- Provide methods to retrieve messages by ID, optionally substituting parameters using UO-style placeholders.
|
||||
- Integrate with Language to select appropriate locale when multiple locales exist.
|
||||
|
||||
Data structures and complexity:
|
||||
- Primary storage: Dictionary-like mapping from cliloc ID to message template.
|
||||
- Lookup time: O(1) average for direct ID access.
|
||||
- Substitution: Linear in number of parameters; uses efficient string building.
|
||||
|
||||
Error handling:
|
||||
- Missing files or corrupted entries are handled gracefully with logging and fallback to default language or base templates.
|
||||
- Invalid parameter counts produce safe formatted output rather than exceptions.
|
||||
|
||||
Optimization opportunities:
|
||||
- Pre-warm caches on startup for frequently used IDs.
|
||||
- Lazy-load large cliloc partitions if needed.
|
||||
- Avoid repeated allocations by reusing buffers for parameter substitution.
|
||||
|
||||
Integration points:
|
||||
- Consumed by filters and view models for displaying contextual messages.
|
||||
- Uses Language to determine effective culture and fallback chain.
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class Cliloc {
|
||||
+Load(clientPath)
|
||||
+Get(id, params) string
|
||||
+Contains(id) bool
|
||||
-index Map<int,string>
|
||||
-culture string
|
||||
}
|
||||
class Language {
|
||||
+CurrentCulture string
|
||||
+FallbackChain() IEnumerable<string>
|
||||
+SelectBest(candidates) string
|
||||
}
|
||||
Cliloc --> Language : "uses"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Cliloc.cs](file://ClassicAssist.Shared/UO/Data/Cliloc.cs)
|
||||
- [Language.cs](file://ClassicAssist.Shared/Data/Language.cs)
|
||||
|
||||
**Section sources**
|
||||
- [Cliloc.cs](file://ClassicAssist.Shared/UO/Data/Cliloc.cs)
|
||||
- [Language.cs](file://ClassicAssist.Shared/Data/Language.cs)
|
||||
|
||||
### .resx Resource System and Designer Code Generation
|
||||
Structure:
|
||||
- Default resource file: Strings.resx
|
||||
- Cultured variants: Strings.en-AU.resx, Strings.en-GB.resx, Strings.it-IT.resx, Strings.ko-KR.resx, Strings.pl-PL.resx, Strings.zh.resx
|
||||
- Designer code: Strings.Designer.cs exposes strongly typed properties for each key, bound to the active culture.
|
||||
|
||||
Runtime behavior:
|
||||
- The ResourceManager selects the best matching resource based on CurrentUICulture and falls back to the neutral resource if a specific culture is missing.
|
||||
- Designer-generated properties encapsulate culture selection and null safety.
|
||||
|
||||
Consistency and maintenance:
|
||||
- Keep keys aligned across all .resx files to avoid missing translations.
|
||||
- Use consistent naming conventions and include comments in .resx for translators.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["Access property via Strings.Designer"]) --> CheckCulture["Resolve CurrentUICulture"]
|
||||
CheckCulture --> FindResource["Find matching .resx"]
|
||||
FindResource --> Found{"Found?"}
|
||||
Found --> |Yes| ReturnVal["Return localized string"]
|
||||
Found --> |No| Fallback["Fallback to neutral Strings.resx"]
|
||||
Fallback --> ReturnVal
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Strings.Designer.cs](file://ClassicAssist.Shared/Resources/Strings.Designer.cs)
|
||||
- [Strings.resx](file://ClassicAssist.Shared/Resources/Strings.resx)
|
||||
- [Strings.en-AU.resx](file://ClassicAssist.Shared/Resources/Strings.en-AU.resx)
|
||||
- [Strings.en-GB.resx](file://ClassicAssist.Shared/Resources/Strings.en-GB.resx)
|
||||
- [Strings.it-IT.resx](file://ClassicAssist.Shared/Resources/Strings.it-IT.resx)
|
||||
- [Strings.ko-KR.resx](file://ClassicAssist.Shared/Resources/Strings.ko-KR.resx)
|
||||
- [Strings.pl-PL.resx](file://ClassicAssist.Shared/Resources/Strings.pl-PL.resx)
|
||||
- [Strings.zh.resx](file://ClassicAssist.Shared/Resources/Strings.zh.resx)
|
||||
|
||||
**Section sources**
|
||||
- [Strings.Designer.cs](file://ClassicAssist.Shared/Resources/Strings.Designer.cs)
|
||||
- [Strings.resx](file://ClassicAssist.Shared/Resources/Strings.resx)
|
||||
- [Strings.en-AU.resx](file://ClassicAssist.Shared/Resources/Strings.en-AU.resx)
|
||||
- [Strings.en-GB.resx](file://ClassicAssist.Shared/Resources/Strings.en-GB.resx)
|
||||
- [Strings.it-IT.resx](file://ClassicAssist.Shared/Resources/Strings.it-IT.resx)
|
||||
- [Strings.ko-KR.resx](file://ClassicAssist.Shared/Resources/Strings.ko-KR.resx)
|
||||
- [Strings.pl-PL.resx](file://ClassicAssist.Shared/Resources/Strings.pl-PL.resx)
|
||||
- [Strings.zh.resx](file://ClassicAssist.Shared/Resources/Strings.zh.resx)
|
||||
|
||||
### StringToResourceConverter for XAML Binding
|
||||
Purpose:
|
||||
- Enables XAML bindings to resolve localized strings directly in markup.
|
||||
- Supports passing parameters for dynamic substitution within resource templates.
|
||||
|
||||
Behavior:
|
||||
- Reads the bound key and optional parameters.
|
||||
- Uses the .resx resource manager to fetch the template for the current culture.
|
||||
- Applies parameter substitution before returning the final string.
|
||||
|
||||
Usage patterns:
|
||||
- Bind Text properties to keys defined in .resx.
|
||||
- Pass additional context via ConverterParameter or MultiBinding to enrich messages.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Xaml as "XAML Binding"
|
||||
participant Conv as "StringToResourceConverter"
|
||||
participant RM as "ResourceManager"
|
||||
Xaml->>Conv : Convert(key, parameters)
|
||||
Conv->>RM : GetString(key, culture)
|
||||
RM-->>Conv : Template
|
||||
Conv->>Conv : Substitute parameters
|
||||
Conv-->>Xaml : Final string
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
|
||||
- [Strings.Designer.cs](file://ClassicAssist.Shared/Resources/Strings.Designer.cs)
|
||||
|
||||
**Section sources**
|
||||
- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
|
||||
- [Strings.Designer.cs](file://ClassicAssist.Shared/Resources/Strings.Designer.cs)
|
||||
|
||||
### Multi-Language Support: Detection, Fallback, and Runtime Switching
|
||||
Detection:
|
||||
- Uses the system’s CurrentUICulture to pick the best available resource set.
|
||||
- Falls back to neutral resources when a specific culture is not present.
|
||||
|
||||
Fallback mechanism:
|
||||
- If a culture-specific .resx is missing, the system automatically resolves to the default Strings.resx.
|
||||
- For cliloc, similar fallback logic applies when a particular locale entry is unavailable.
|
||||
|
||||
Runtime switching:
|
||||
- Changing CurrentUICulture triggers re-resolution of resources.
|
||||
- UI components using StringToResourceConverter will update dynamically when culture changes.
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Initialized
|
||||
Initialized --> DetectCulture : "On startup"
|
||||
DetectCulture --> Active : "Culture resolved"
|
||||
Active --> Switching : "User changes language"
|
||||
Switching --> Active : "New culture applied"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Strings.Designer.cs](file://ClassicAssist.Shared/Resources/Strings.Designer.cs)
|
||||
- [Language.cs](file://ClassicAssist.Shared/Data/Language.cs)
|
||||
|
||||
**Section sources**
|
||||
- [Strings.Designer.cs](file://ClassicAssist.Shared/Resources/Strings.Designer.cs)
|
||||
- [Language.cs](file://ClassicAssist.Shared/Data/Language.cs)
|
||||
|
||||
### Integration with Game Text Formatting and Parameter Substitution
|
||||
Game cliloc format:
|
||||
- Messages may contain placeholders for parameters (e.g., names, numbers).
|
||||
- The Cliloc class substitutes these parameters safely, preserving formatting and handling missing values.
|
||||
|
||||
Application resources:
|
||||
- .resx templates can also accept parameters via the converter, allowing flexible UI messages.
|
||||
|
||||
Consistency:
|
||||
- Maintain parallel parameter sets between cliloc and .resx where applicable to ensure consistent UX across game and UI text.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Entry(["Lookup request"]) --> GetTemplate["Fetch template"]
|
||||
GetTemplate --> HasParams{"Parameters provided?"}
|
||||
HasParams --> |No| ReturnTemplate["Return template as-is"]
|
||||
HasParams --> |Yes| Validate["Validate count/types"]
|
||||
Validate --> Format["Format with placeholders"]
|
||||
Format --> ReturnFormatted["Return formatted string"]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Cliloc.cs](file://ClassicAssist.Shared/UO/Data/Cliloc.cs)
|
||||
- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
|
||||
|
||||
**Section sources**
|
||||
- [Cliloc.cs](file://ClassicAssist.Shared/UO/Data/Cliloc.cs)
|
||||
- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
|
||||
|
||||
### Adding New Languages and Maintaining Consistency
|
||||
Steps to add a new language:
|
||||
- Create a new .resx file named with the target culture (e.g., Strings.fr-FR.resx).
|
||||
- Copy keys from the default Strings.resx and translate values.
|
||||
- Ensure all keys are present to avoid fallback surprises.
|
||||
- Update any UI elements that expose language choices to include the new culture.
|
||||
|
||||
Translating existing strings:
|
||||
- Use the .resx editor to maintain translation quality and consistency.
|
||||
- Keep comments in .resx to guide translators.
|
||||
|
||||
Maintaining consistency:
|
||||
- Regularly compare new keys added to Strings.resx against existing culture files.
|
||||
- Implement checks or CI tasks to detect missing translations.
|
||||
|
||||
**Section sources**
|
||||
- [Strings.resx](file://ClassicAssist.Shared/Resources/Strings.resx)
|
||||
- [Strings.Designer.cs](file://ClassicAssist.Shared/Resources/Strings.Designer.cs)
|
||||
|
||||
### Autoloot Integration with Cliloc
|
||||
Components:
|
||||
- ClilocFilter: Filters chat or journal entries using cliloc IDs and patterns.
|
||||
- ClilocSelectionViewModel: Manages selection and display of cliloc entries for autoloot rules.
|
||||
- ClilocSelectionWindow: Presents the selection UI, leveraging StringToResourceConverter for labels and messages.
|
||||
|
||||
Workflow:
|
||||
- User opens the selection window.
|
||||
- ViewModel queries Cliloc for relevant entries.
|
||||
- UI binds to localized strings via the converter for labels and descriptions.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as "User"
|
||||
participant Win as "ClilocSelectionWindow"
|
||||
participant VM as "ClilocSelectionViewModel"
|
||||
participant CL as "Cliloc"
|
||||
participant Conv as "StringToResourceConverter"
|
||||
User->>Win : Open window
|
||||
Win->>VM : Initialize
|
||||
VM->>CL : Load/filter cliloc entries
|
||||
CL-->>VM : Entries
|
||||
Win->>Conv : Bind labels/messages
|
||||
Conv-->>Win : Localized text
|
||||
Win-->>User : Display selection UI
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ClilocSelectionWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/Autoloot/ClilocSelectionWindow.xaml.cs)
|
||||
- [ClilocSelectionViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Autoloot/ClilocSelectionViewModel.cs)
|
||||
- [Cliloc.cs](file://ClassicAssist.Shared/UO/Data/Cliloc.cs)
|
||||
- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
|
||||
|
||||
**Section sources**
|
||||
- [ClilocFilter.cs](file://ClassicAssist.Shared/Data/Filters/ClilocFilter.cs)
|
||||
- [ClilocSelectionViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Autoloot/ClilocSelectionViewModel.cs)
|
||||
- [ClilocSelectionWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/Autoloot/ClilocSelectionWindow.xaml.cs)
|
||||
|
||||
## Dependency Analysis
|
||||
Relationships among core components:
|
||||
- Cliloc depends on Language for culture selection and fallback.
|
||||
- StringToResourceConverter depends on .resx resources and the active culture.
|
||||
- UI components depend on both Cliloc (for game text) and StringToResourceConverter (for UI text).
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
CL["Cliloc.cs"] --> LG["Language.cs"]
|
||||
SRC["StringToResourceConverter.cs"] --> RESX["Strings.Designer.cs"]
|
||||
CVM["ClilocSelectionViewModel.cs"] --> CL
|
||||
CSW["ClilocSelectionWindow.xaml.cs"] --> SRC
|
||||
CF["ClilocFilter.cs"] --> CL
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Cliloc.cs](file://ClassicAssist.Shared/UO/Data/Cliloc.cs)
|
||||
- [Language.cs](file://ClassicAssist.Shared/Data/Language.cs)
|
||||
- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
|
||||
- [Strings.Designer.cs](file://ClassicAssist.Shared/Resources/Strings.Designer.cs)
|
||||
- [ClilocSelectionViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Autoloot/ClilocSelectionViewModel.cs)
|
||||
- [ClilocSelectionWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/Autoloot/ClilocSelectionWindow.xaml.cs)
|
||||
- [ClilocFilter.cs](file://ClassicAssist.Shared/Data/Filters/ClilocFilter.cs)
|
||||
|
||||
**Section sources**
|
||||
- [Cliloc.cs](file://ClassicAssist.Shared/UO/Data/Cliloc.cs)
|
||||
- [Language.cs](file://ClassicAssist.Shared/Data/Language.cs)
|
||||
- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
|
||||
- [Strings.Designer.cs](file://ClassicAssist.Shared/Resources/Strings.Designer.cs)
|
||||
- [ClilocSelectionViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Autoloot/ClilocSelectionViewModel.cs)
|
||||
- [ClilocSelectionWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/Autoloot/ClilocSelectionWindow.xaml.cs)
|
||||
- [ClilocFilter.cs](file://ClassicAssist.Shared/Data/Filters/ClilocFilter.cs)
|
||||
|
||||
## Performance Considerations
|
||||
- Large cliloc datasets:
|
||||
- Prefer dictionary-backed lookups for O(1) access.
|
||||
- Cache frequently used IDs to reduce parsing overhead.
|
||||
- Consider lazy-loading partitions if memory usage becomes a concern.
|
||||
- Parameter substitution:
|
||||
- Reuse formatters/buffers to minimize allocations.
|
||||
- Validate parameter counts early to avoid expensive formatting paths.
|
||||
- .resx access:
|
||||
- ResourceManager is efficient; avoid repeated culture switches in tight loops.
|
||||
- Batch UI updates to reduce rebind churn.
|
||||
- UI responsiveness:
|
||||
- Offload heavy cliloc operations to background threads and marshal results to UI thread.
|
||||
- Debounce rapid language switches to prevent excessive re-resolution.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- Missing translations:
|
||||
- Verify that culture-specific .resx files contain all keys present in the default Strings.resx.
|
||||
- Check CurrentUICulture settings during runtime to ensure expected culture is active.
|
||||
- Incorrect parameter substitution:
|
||||
- Confirm placeholder positions match parameter order.
|
||||
- Log template and parameters to diagnose mismatches.
|
||||
- Cliloc lookup failures:
|
||||
- Ensure cliloc files are present and readable.
|
||||
- Validate IDs and handle missing entries with fallback messages.
|
||||
- UI not updating after language change:
|
||||
- Ensure bindings use StringToResourceConverter and that culture change triggers re-evaluation.
|
||||
|
||||
**Section sources**
|
||||
- [Strings.Designer.cs](file://ClassicAssist.Shared/Resources/Strings.Designer.cs)
|
||||
- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
|
||||
- [Cliloc.cs](file://ClassicAssist.Shared/UO/Data/Cliloc.cs)
|
||||
|
||||
## Conclusion
|
||||
The cliloc text system and localization framework in ClassicAssist.Avalonia combine robust game text loading (.resx-based application resources) with efficient in-memory management for UO cliloc files. The architecture supports multi-language environments with reliable fallback, dynamic parameter substitution, and seamless XAML integration. By following the guidelines for adding languages, maintaining consistency, and optimizing performance, teams can deliver a responsive, localized experience across diverse locales.
|
||||
|
||||
[No sources needed since this section summarizes without analyzing specific files]
|
||||
|
||||
## Appendices
|
||||
- Best practices:
|
||||
- Centralize key definitions and enforce parity across cultures.
|
||||
- Use descriptive comments in .resx for translators.
|
||||
- Test parameter substitution thoroughly with edge cases.
|
||||
- References:
|
||||
- See component files for implementation details and integration points.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
@@ -0,0 +1,552 @@
|
||||
# Communication Tools
|
||||
|
||||
<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)
|
||||
- [ClilocFilter.cs](file://ClassicAssist.Shared/Data/Filters/ClilocFilter.cs)
|
||||
- [RepeatedMessagesFilter.cs](file://ClassicAssist.Shared/Data/Filters/RepeatedMessagesFilter.cs)
|
||||
- [FilterEntry.cs](file://ClassicAssist.Shared/Data/Filters/FilterEntry.cs)
|
||||
- [IConfigurableFilter.cs](file://ClassicAssist.Shared/Data/Filters/IConfigurableFilter.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
|
||||
- [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs)
|
||||
- [PacketHandler.cs](file://ClassicAssist.Shared/UO/Network/PacketHandler.cs)
|
||||
- [UnicodeText.cs](file://ClassicAssist.Shared/UO/Network/Packets/UnicodeText.cs)
|
||||
- [Cliloc.cs](file://ClassicAssist.Shared/UO/Data/Cliloc.cs)
|
||||
- [FriendsTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/FriendsTabControl.axaml.cs)
|
||||
- [FriendsTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/FriendsTabViewModel.cs)
|
||||
- [FriendEntry.cs](file://ClassicAssist.Shared/Data/Friends/FriendEntry.cs)
|
||||
- [FriendsCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/FriendsCommands.cs)
|
||||
- [ChatWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/ChatWindow.axaml.cs)
|
||||
- [ChatViewModel.cs](file://ClassicAssist.Avalonia/ViewModels/ChatViewModel.cs)
|
||||
- [ClilocFilterConfigureWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/Filters/ClilocFilterConfigureWindow.axaml.cs)
|
||||
- [ClilocFilterConfigureViewModel.cs](file://ClassicAssist.Avalonia/ViewModels/Filters/ClilocFilterConfigureViewModel.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 communication tools in ClassicAssist.Avalonia with a focus on chat, friends, localization (cliloc), real-time protocols, filtering, and performance. It covers channel management, message filtering, logging/export, social features, status monitoring, party coordination, filter configuration (including regex support), integration with Ultima Online’s native chat system, and strategies for high-volume processing and memory management.
|
||||
|
||||
## Project Structure
|
||||
The communication subsystem spans shared data models, network handlers, filters, UI views, and view models:
|
||||
- Shared data models for chat, friends, and cliloc
|
||||
- Network layer for incoming/outgoing packets and routing
|
||||
- Filter pipeline for chat messages
|
||||
- Avalonia UI components for chat window and friends tab
|
||||
- Configuration UI for filters
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Shared"
|
||||
CM["ChatManager"]
|
||||
MSG["ChatMessage"]
|
||||
USER["ChatUser"]
|
||||
CLF["ClilocFilter"]
|
||||
RMF["RepeatedMessagesFilter"]
|
||||
FE["FilterEntry"]
|
||||
CF["IConfigurableFilter"]
|
||||
IPH["IncomingPacketHandlers"]
|
||||
OPH["OutgoingPacketHandlers"]
|
||||
IPF["IncomingPacketFilters"]
|
||||
OPF["OutgoingPacketFilters"]
|
||||
PH["PacketHandler"]
|
||||
UT["UnicodeText"]
|
||||
CLILOC["Cliloc"]
|
||||
FF["FriendEntry"]
|
||||
FVM["FriendsTabViewModel"]
|
||||
FCMD["FriendsCommands"]
|
||||
end
|
||||
subgraph "Avalonia UI"
|
||||
CW["ChatWindow"]
|
||||
CVM["ChatViewModel"]
|
||||
FCT["FriendsTabControl"]
|
||||
CLFCW["ClilocFilterConfigureWindow"]
|
||||
CLFCVM["ClilocFilterConfigureViewModel"]
|
||||
end
|
||||
CM --> MSG
|
||||
CM --> USER
|
||||
CM --> CLF
|
||||
CM --> RMF
|
||||
CM --> FE
|
||||
CM --> CF
|
||||
IPH --> CM
|
||||
OPH --> CM
|
||||
IPF --> CM
|
||||
OPF --> CM
|
||||
PH --> IPH
|
||||
PH --> OPH
|
||||
UT --> CM
|
||||
CLILOC --> CLF
|
||||
FVM --> FF
|
||||
FCMD --> FVM
|
||||
CW --> CVM
|
||||
CVM --> CM
|
||||
FCT --> FVM
|
||||
CLFCW --> CLFCVM
|
||||
CLFCVM --> CLF
|
||||
```
|
||||
|
||||
**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)
|
||||
- [ClilocFilter.cs](file://ClassicAssist.Shared/Data/Filters/ClilocFilter.cs)
|
||||
- [RepeatedMessagesFilter.cs](file://ClassicAssist.Shared/Data/Filters/RepeatedMessagesFilter.cs)
|
||||
- [FilterEntry.cs](file://ClassicAssist.Shared/Data/Filters/FilterEntry.cs)
|
||||
- [IConfigurableFilter.cs](file://ClassicAssist.Shared/Data/Filters/IConfigurableFilter.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
|
||||
- [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs)
|
||||
- [PacketHandler.cs](file://ClassicAssist.Shared/UO/Network/PacketHandler.cs)
|
||||
- [UnicodeText.cs](file://ClassicAssist.Shared/UO/Network/Packets/UnicodeText.cs)
|
||||
- [Cliloc.cs](file://ClassicAssist.Shared/UO/Data/Cliloc.cs)
|
||||
- [FriendsTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/FriendsTabViewModel.cs)
|
||||
- [FriendEntry.cs](file://ClassicAssist.Shared/Data/Friends/FriendEntry.cs)
|
||||
- [FriendsCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/FriendsCommands.cs)
|
||||
- [ChatWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/ChatWindow.axaml.cs)
|
||||
- [ChatViewModel.cs](file://ClassicAssist.Avalonia/ViewModels/ChatViewModel.cs)
|
||||
- [FriendsTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/FriendsTabControl.axaml.cs)
|
||||
- [ClilocFilterConfigureWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/Filters/ClilocFilterConfigureWindow.axaml.cs)
|
||||
- [ClilocFilterConfigureViewModel.cs](file://ClassicAssist.Avalonia/ViewModels/Filters/ClilocFilterConfigureViewModel.cs)
|
||||
|
||||
**Section sources**
|
||||
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
|
||||
- [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs)
|
||||
- [PacketHandler.cs](file://ClassicAssist.Shared/UO/Network/PacketHandler.cs)
|
||||
- [UnicodeText.cs](file://ClassicAssist.Shared/UO/Network/Packets/UnicodeText.cs)
|
||||
- [Cliloc.cs](file://ClassicAssist.Shared/UO/Data/Cliloc.cs)
|
||||
- [FriendsTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/FriendsTabViewModel.cs)
|
||||
- [FriendEntry.cs](file://ClassicAssist.Shared/Data/Friends/FriendEntry.cs)
|
||||
- [FriendsCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/FriendsCommands.cs)
|
||||
- [ChatWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/ChatWindow.axaml.cs)
|
||||
- [ChatViewModel.cs](file://ClassicAssist.Avalonia/ViewModels/ChatViewModel.cs)
|
||||
- [FriendsTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/FriendsTabControl.axaml.cs)
|
||||
- [ClilocFilterConfigureWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/Filters/ClilocFilterConfigureWindow.axaml.cs)
|
||||
- [ClilocFilterConfigureViewModel.cs](file://ClassicAssist.Avalonia/ViewModels/Filters/ClilocFilterConfigureViewModel.cs)
|
||||
|
||||
## Core Components
|
||||
- Chat system: central manager orchestrating channels, messages, users, filters, logging, and export hooks.
|
||||
- Friends system: list management, presence/status, commands for invites/parties.
|
||||
- Cliloc localization: text lookup and filtering by cliloc IDs.
|
||||
- Network protocol: packet handlers for chat-related packets, filter pipeline, and routing to managers.
|
||||
- UI: chat window and friends tab bound to view models that interact with managers.
|
||||
|
||||
Key responsibilities:
|
||||
- Channel management: grouping messages by type/channel and controlling visibility.
|
||||
- Message filtering: built-in and custom filters including regex-based rules.
|
||||
- Logging and export: persisting messages and exporting logs for analysis.
|
||||
- Social features: friend list CRUD, status updates, invitations, and party coordination.
|
||||
- Localization: resolving cliloc entries and applying filters based on localized text or IDs.
|
||||
|
||||
**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)
|
||||
- [ClilocFilter.cs](file://ClassicAssist.Shared/Data/Filters/ClilocFilter.cs)
|
||||
- [RepeatedMessagesFilter.cs](file://ClassicAssist.Shared/Data/Filters/RepeatedMessagesFilter.cs)
|
||||
- [FilterEntry.cs](file://ClassicAssist.Shared/Data/Filters/FilterEntry.cs)
|
||||
- [IConfigurableFilter.cs](file://ClassicAssist.Shared/Data/Filters/IConfigurableFilter.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
|
||||
- [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs)
|
||||
- [PacketHandler.cs](file://ClassicAssist.Shared/UO/Network/PacketHandler.cs)
|
||||
- [UnicodeText.cs](file://ClassicAssist.Shared/UO/Network/Packets/UnicodeText.cs)
|
||||
- [Cliloc.cs](file://ClassicAssist.Shared/UO/Data/Cliloc.cs)
|
||||
- [FriendsTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/FriendsTabViewModel.cs)
|
||||
- [FriendEntry.cs](file://ClassicAssist.Shared/Data/Friends/FriendEntry.cs)
|
||||
- [FriendsCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/FriendsCommands.cs)
|
||||
- [ChatWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/ChatWindow.axaml.cs)
|
||||
- [ChatViewModel.cs](file://ClassicAssist.Avalonia/ViewModels/ChatViewModel.cs)
|
||||
- [FriendsTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/FriendsTabControl.axaml.cs)
|
||||
- [ClilocFilterConfigureWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/Filters/ClilocFilterConfigureWindow.axaml.cs)
|
||||
- [ClilocFilterConfigureViewModel.cs](file://ClassicAssist.Avalonia/ViewModels/Filters/ClilocFilterConfigureViewModel.cs)
|
||||
|
||||
## Architecture Overview
|
||||
The communication architecture integrates UO network packets into a layered pipeline:
|
||||
- PacketHandler routes incoming/outgoing packets to specific handlers.
|
||||
- IncomingPacketHandlers parse chat and social packets and forward events to ChatManager and Friends systems.
|
||||
- OutgoingPacketHandlers send chat and social actions back to the server.
|
||||
- IncomingPacketFilters and OutgoingPacketFilters provide interception points for inspection/modification.
|
||||
- ChatManager applies filters (regex, repeated messages, cliloc-based) and manages channels/users/messages.
|
||||
- UI layers bind to view models which call into managers for display and user actions.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Net as "PacketHandler"
|
||||
participant InH as "IncomingPacketHandlers"
|
||||
participant InF as "IncomingPacketFilters"
|
||||
participant CM as "ChatManager"
|
||||
participant FM as "FriendsTabViewModel"
|
||||
participant UI as "ChatWindow/ChatViewModel"
|
||||
Net->>InH : "Dispatch incoming packet"
|
||||
InH->>InF : "Apply incoming filters"
|
||||
InF-->>InH : "Filtered result"
|
||||
InH->>CM : "Publish chat/social event"
|
||||
CM->>CM : "Apply filters (regex, repeated, cliloc)"
|
||||
CM-->>UI : "Notify new message/channel update"
|
||||
UI->>FM : "Sync friends/party state"
|
||||
FM-->>UI : "Status changes"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [PacketHandler.cs](file://ClassicAssist.Shared/UO/Network/PacketHandler.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
|
||||
- [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs)
|
||||
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
|
||||
- [ChatViewModel.cs](file://ClassicAssist.Avalonia/ViewModels/ChatViewModel.cs)
|
||||
- [ChatWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/ChatWindow.axaml.cs)
|
||||
- [FriendsTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/FriendsTabViewModel.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### Chat System
|
||||
Responsibilities:
|
||||
- Channel management: categorize messages by channel type and control visibility.
|
||||
- Message lifecycle: creation, filtering, persistence, and export.
|
||||
- User tracking: maintain ChatUser instances per sender.
|
||||
- Integration: receives parsed chat from UnicodeText via handlers.
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class ChatManager {
|
||||
+AddMessage(message)
|
||||
+GetChannel(channelType)
|
||||
+RemoveOldEntries(maxCount)
|
||||
+ExportLog(path)
|
||||
+SubscribeToEvents()
|
||||
}
|
||||
class ChatMessage {
|
||||
+Sender
|
||||
+Content
|
||||
+Channel
|
||||
+Timestamp
|
||||
}
|
||||
class ChatUser {
|
||||
+Name
|
||||
+Serial
|
||||
+LastSeen
|
||||
}
|
||||
class ClilocFilter {
|
||||
+Matches(clilocId, text)
|
||||
+Configure(options)
|
||||
}
|
||||
class RepeatedMessagesFilter {
|
||||
+ShouldSuppress(previous, current)
|
||||
}
|
||||
class FilterEntry {
|
||||
+Pattern
|
||||
+Enabled
|
||||
+Regex
|
||||
}
|
||||
class IConfigurableFilter {
|
||||
<<interface>>
|
||||
+Configure(options)
|
||||
}
|
||||
ChatManager --> ChatMessage : "creates/manages"
|
||||
ChatManager --> ChatUser : "tracks"
|
||||
ChatManager --> ClilocFilter : "applies"
|
||||
ChatManager --> RepeatedMessagesFilter : "applies"
|
||||
ChatManager --> FilterEntry : "iterates"
|
||||
ClilocFilter ..|> IConfigurableFilter
|
||||
RepeatedMessagesFilter ..|> IConfigurableFilter
|
||||
```
|
||||
|
||||
**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)
|
||||
- [ClilocFilter.cs](file://ClassicAssist.Shared/Data/Filters/ClilocFilter.cs)
|
||||
- [RepeatedMessagesFilter.cs](file://ClassicAssist.Shared/Data/Filters/RepeatedMessagesFilter.cs)
|
||||
- [FilterEntry.cs](file://ClassicAssist.Shared/Data/Filters/FilterEntry.cs)
|
||||
- [IConfigurableFilter.cs](file://ClassicAssist.Shared/Data/Filters/IConfigurableFilter.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)
|
||||
- [ClilocFilter.cs](file://ClassicAssist.Shared/Data/Filters/ClilocFilter.cs)
|
||||
- [RepeatedMessagesFilter.cs](file://ClassicAssist.Shared/Data/Filters/RepeatedMessagesFilter.cs)
|
||||
- [FilterEntry.cs](file://ClassicAssist.Shared/Data/Filters/FilterEntry.cs)
|
||||
- [IConfigurableFilter.cs](file://ClassicAssist.Shared/Data/Filters/IConfigurableFilter.cs)
|
||||
- [UnicodeText.cs](file://ClassicAssist.Shared/UO/Network/Packets/UnicodeText.cs)
|
||||
|
||||
### Friends List and Party Coordination
|
||||
Responsibilities:
|
||||
- Maintain friend entries with status and metadata.
|
||||
- Provide commands for inviting, accepting/rejecting parties, and viewing status.
|
||||
- UI binds to view model for interactive management.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant UI as "FriendsTabControl"
|
||||
participant VM as "FriendsTabViewModel"
|
||||
participant CMD as "FriendsCommands"
|
||||
participant NET as "OutgoingPacketHandlers"
|
||||
participant S as "Server"
|
||||
UI->>VM : "User action (invite/accept/reject)"
|
||||
VM->>CMD : "Invoke command"
|
||||
CMD->>NET : "Build and send packet"
|
||||
NET->>S : "Transmit"
|
||||
S-->>NET : "Response (status/party update)"
|
||||
NET-->>VM : "Update state"
|
||||
VM-->>UI : "Refresh list and status"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [FriendsTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/FriendsTabControl.axaml.cs)
|
||||
- [FriendsTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/FriendsTabViewModel.cs)
|
||||
- [FriendEntry.cs](file://ClassicAssist.Shared/Data/Friends/FriendEntry.cs)
|
||||
- [FriendsCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/FriendsCommands.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
|
||||
**Section sources**
|
||||
- [FriendsTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/FriendsTabControl.axaml.cs)
|
||||
- [FriendsTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/FriendsTabViewModel.cs)
|
||||
- [FriendEntry.cs](file://ClassicAssist.Shared/Data/Friends/FriendEntry.cs)
|
||||
- [FriendsCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/FriendsCommands.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
|
||||
### Cliloc Text System
|
||||
Responsibilities:
|
||||
- Resolve localized strings using cliloc IDs.
|
||||
- Support filtering by cliloc ID or resolved text.
|
||||
- Provide configuration UI for filter options.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["Resolve Cliloc"]) --> Lookup["Lookup ID in Cliloc"]
|
||||
Lookup --> Found{"Found?"}
|
||||
Found --> |Yes| ReturnText["Return localized text"]
|
||||
Found --> |No| Fallback["Fallback to raw ID"]
|
||||
ReturnText --> ApplyFilter["Apply ClilocFilter"]
|
||||
Fallback --> ApplyFilter
|
||||
ApplyFilter --> End(["Result"])
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Cliloc.cs](file://ClassicAssist.Shared/UO/Data/Cliloc.cs)
|
||||
- [ClilocFilter.cs](file://ClassicAssist.Shared/Data/Filters/ClilocFilter.cs)
|
||||
- [ClilocFilterConfigureWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/Filters/ClilocFilterConfigureWindow.axaml.cs)
|
||||
- [ClilocFilterConfigureViewModel.cs](file://ClassicAssist.Avalonia/ViewModels/Filters/ClilocFilterConfigureViewModel.cs)
|
||||
|
||||
**Section sources**
|
||||
- [Cliloc.cs](file://ClassicAssist.Shared/UO/Data/Cliloc.cs)
|
||||
- [ClilocFilter.cs](file://ClassicAssist.Shared/Data/Filters/ClilocFilter.cs)
|
||||
- [ClilocFilterConfigureWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/Filters/ClilocFilterConfigureWindow.axaml.cs)
|
||||
- [ClilocFilterConfigureViewModel.cs](file://ClassicAssist.Avalonia/ViewModels/Filters/ClilocFilterConfigureViewModel.cs)
|
||||
|
||||
### Real-Time Communication Protocols and Routing
|
||||
Responsibilities:
|
||||
- Parse and dispatch chat-related packets (e.g., UnicodeText).
|
||||
- Route events to ChatManager and friends/party handlers.
|
||||
- Provide filter hooks before/after processing.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "Client"
|
||||
participant PH as "PacketHandler"
|
||||
participant IN as "IncomingPacketHandlers"
|
||||
participant CH as "ChatManager"
|
||||
participant FR as "FriendsTabViewModel"
|
||||
Client->>PH : "Send UnicodeText"
|
||||
PH->>IN : "Route to handler"
|
||||
IN->>CH : "Create ChatMessage"
|
||||
CH->>CH : "Apply filters"
|
||||
CH-->>FR : "Broadcast updates"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [PacketHandler.cs](file://ClassicAssist.Shared/UO/Network/PacketHandler.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [UnicodeText.cs](file://ClassicAssist.Shared/UO/Network/Packets/UnicodeText.cs)
|
||||
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
|
||||
- [FriendsTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/FriendsTabViewModel.cs)
|
||||
|
||||
**Section sources**
|
||||
- [PacketHandler.cs](file://ClassicAssist.Shared/UO/Network/PacketHandler.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [UnicodeText.cs](file://ClassicAssist.Shared/UO/Network/Packets/UnicodeText.cs)
|
||||
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
|
||||
- [FriendsTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/FriendsTabViewModel.cs)
|
||||
|
||||
### Filter Configuration and Custom Filters
|
||||
Responsibilities:
|
||||
- Built-in filters: repeated messages suppression, cliloc-based matching.
|
||||
- Regex support via FilterEntry patterns.
|
||||
- Configurable filters interface for advanced customization.
|
||||
- UI for configuring cliloc filters.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Entry(["New Message"]) --> Iterate["Iterate FilterEntry list"]
|
||||
Iterate --> CheckEnabled{"Enabled?"}
|
||||
CheckEnabled --> |No| Next["Next filter"]
|
||||
CheckEnabled --> |Yes| Match["Match pattern (regex if set)"]
|
||||
Match --> Hit{"Hit?"}
|
||||
Hit --> |Yes| Action["Suppress/Tag/Modify"]
|
||||
Hit --> |No| Next
|
||||
Next --> Done{"More filters?"}
|
||||
Done --> |Yes| Iterate
|
||||
Done --> |No| Publish["Publish to ChatManager"]
|
||||
```
|
||||
|
||||
**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)
|
||||
- [IConfigurableFilter.cs](file://ClassicAssist.Shared/Data/Filters/IConfigurableFilter.cs)
|
||||
- [ClilocFilterConfigureViewModel.cs](file://ClassicAssist.Avalonia/ViewModels/Filters/ClilocFilterConfigureViewModel.cs)
|
||||
- [ClilocFilterConfigureWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/Filters/ClilocFilterConfigureWindow.axaml.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)
|
||||
- [IConfigurableFilter.cs](file://ClassicAssist.Shared/Data/Filters/IConfigurableFilter.cs)
|
||||
- [ClilocFilterConfigureViewModel.cs](file://ClassicAssist.Avalonia/ViewModels/Filters/ClilocFilterConfigureViewModel.cs)
|
||||
- [ClilocFilterConfigureWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/Filters/ClilocFilterConfigureWindow.axaml.cs)
|
||||
|
||||
### Integration with Ultima Online Native Chat and Protocol Handling
|
||||
Responsibilities:
|
||||
- Map UO chat packets to internal ChatMessage objects.
|
||||
- Preserve channel semantics and sender identity.
|
||||
- Ensure outgoing chat commands are serialized correctly.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant UO as "UO Server"
|
||||
participant PH as "PacketHandler"
|
||||
participant IN as "IncomingPacketHandlers"
|
||||
participant CH as "ChatManager"
|
||||
participant UI as "ChatViewModel"
|
||||
UO->>PH : "UnicodeText packet"
|
||||
PH->>IN : "Parse"
|
||||
IN->>CH : "Create ChatMessage"
|
||||
CH->>UI : "Notify channel update"
|
||||
UI-->>UO : "User sends chat via OutgoingPacketHandlers"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [UnicodeText.cs](file://ClassicAssist.Shared/UO/Network/Packets/UnicodeText.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
|
||||
- [ChatViewModel.cs](file://ClassicAssist.Avalonia/ViewModels/ChatViewModel.cs)
|
||||
|
||||
**Section sources**
|
||||
- [UnicodeText.cs](file://ClassicAssist.Shared/UO/Network/Packets/UnicodeText.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
|
||||
- [ChatViewModel.cs](file://ClassicAssist.Avalonia/ViewModels/ChatViewModel.cs)
|
||||
|
||||
## Dependency Analysis
|
||||
High-level dependencies among communication components:
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
PH["PacketHandler"] --> INH["IncomingPacketHandlers"]
|
||||
PH --> OPH["OutgoingPacketHandlers"]
|
||||
INH --> CM["ChatManager"]
|
||||
OPH --> CM
|
||||
INH --> FRM["FriendsTabViewModel"]
|
||||
OPH --> FRM
|
||||
CM --> CLF["ClilocFilter"]
|
||||
CM --> RMF["RepeatedMessagesFilter"]
|
||||
CM --> FE["FilterEntry"]
|
||||
CLF --> CLILOC["Cliloc"]
|
||||
UI["ChatWindow/ChatViewModel"] --> CM
|
||||
FUI["FriendsTabControl"] --> FRM
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [PacketHandler.cs](file://ClassicAssist.Shared/UO/Network/PacketHandler.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
|
||||
- [ClilocFilter.cs](file://ClassicAssist.Shared/Data/Filters/ClilocFilter.cs)
|
||||
- [RepeatedMessagesFilter.cs](file://ClassicAssist.Shared/Data/Filters/RepeatedMessagesFilter.cs)
|
||||
- [FilterEntry.cs](file://ClassicAssist.Shared/Data/Filters/FilterEntry.cs)
|
||||
- [Cliloc.cs](file://ClassicAssist.Shared/UO/Data/Cliloc.cs)
|
||||
- [ChatViewModel.cs](file://ClassicAssist.Avalonia/ViewModels/ChatViewModel.cs)
|
||||
- [ChatWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/ChatWindow.axaml.cs)
|
||||
- [FriendsTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/FriendsTabControl.axaml.cs)
|
||||
- [FriendsTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/FriendsTabViewModel.cs)
|
||||
|
||||
**Section sources**
|
||||
- [PacketHandler.cs](file://ClassicAssist.Shared/UO/Network/PacketHandler.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
|
||||
- [ClilocFilter.cs](file://ClassicAssist.Shared/Data/Filters/ClilocFilter.cs)
|
||||
- [RepeatedMessagesFilter.cs](file://ClassicAssist.Shared/Data/Filters/RepeatedMessagesFilter.cs)
|
||||
- [FilterEntry.cs](file://ClassicAssist.Shared/Data/Filters/FilterEntry.cs)
|
||||
- [Cliloc.cs](file://ClassicAssist.Shared/UO/Data/Cliloc.cs)
|
||||
- [ChatViewModel.cs](file://ClassicAssist.Avalonia/ViewModels/ChatViewModel.cs)
|
||||
- [ChatWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/ChatWindow.axaml.cs)
|
||||
- [FriendsTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/FriendsTabControl.axaml.cs)
|
||||
- [FriendsTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/FriendsTabViewModel.cs)
|
||||
|
||||
## Performance Considerations
|
||||
- High-volume chat processing:
|
||||
- Use efficient filtering order; place frequent matches early.
|
||||
- Prefer compiled regex patterns where supported to reduce overhead.
|
||||
- Limit retained message history with bounded collections and periodic cleanup.
|
||||
- Memory management:
|
||||
- Avoid retaining large string copies; reuse buffers where possible.
|
||||
- Unsubscribe from events when windows close to prevent leaks.
|
||||
- Export logs asynchronously to avoid blocking UI thread.
|
||||
- UI responsiveness:
|
||||
- Batch updates to observable collections.
|
||||
- Debounce heavy operations like log exports.
|
||||
- Network efficiency:
|
||||
- Coalesce outgoing chat commands when appropriate.
|
||||
- Leverage packet filters to drop unnecessary traffic early.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and diagnostics:
|
||||
- Messages not appearing:
|
||||
- Verify incoming packet handlers route to ChatManager.
|
||||
- Check filter configurations (regex, cliloc) for over-aggressive suppression.
|
||||
- Incorrect localization:
|
||||
- Confirm cliloc ID mapping and fallback behavior.
|
||||
- Friends/party state out of sync:
|
||||
- Inspect outgoing/incoming packet flows for missing updates.
|
||||
- Validate command invocations and response handling.
|
||||
- Performance degradation:
|
||||
- Profile filter execution time and message retention size.
|
||||
- Monitor UI thread workloads during export operations.
|
||||
|
||||
**Section sources**
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
|
||||
- [ClilocFilter.cs](file://ClassicAssist.Shared/Data/Filters/ClilocFilter.cs)
|
||||
- [FriendsTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/FriendsTabViewModel.cs)
|
||||
|
||||
## Conclusion
|
||||
ClassicAssist.Avalonia’s communication tools integrate tightly with Ultima Online’s protocol while providing robust chat management, social features, localization, and extensible filtering. The layered design separates concerns across network handlers, managers, filters, and UI, enabling scalability and maintainability. By following the performance and troubleshooting recommendations, users can optimize for high-volume environments and ensure reliable operation.
|
||||
@@ -0,0 +1,436 @@
|
||||
# Friends and Social Features
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [FriendEntry.cs](file://ClassicAssist.Shared/Data/Friends/FriendEntry.cs)
|
||||
- [FriendsTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/FriendsTabViewModel.cs)
|
||||
- [FriendsTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/FriendsTabControl.xaml.cs)
|
||||
- [FriendsTabControl.axaml](file://ClassicAssist.Avalonia/Views/Agents/FriendsTabControl.axaml)
|
||||
- [FriendsCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/FriendsCommands.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [AcceptPartyInvitation.cs](file://ClassicAssist.Shared/UO/Network/Packets/AcceptPartyInvitation.cs)
|
||||
- [RejectPartyInvitation.cs](file://ClassicAssist.Shared/UO/Network/Packets/RejectPartyInvitation.cs)
|
||||
- [PlayerStatus.cs](file://ClassicAssist.Shared/UO/Data/PlayerStatus.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
|
||||
- [Options.cs](file://ClassicAssist.Shared/Data/Options.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 friends and social features implemented in ClassicAssist.Avalonia, focusing on:
|
||||
- The FriendEntry data model for friend status tracking, relationship management, and metadata storage
|
||||
- The FriendsTabControl UI implementation for displaying the friend list, monitoring status, and performing quick actions
|
||||
- Party coordination tools including invitation handling, member management, and status synchronization
|
||||
- Integration with Ultima Online’s social protocols for friend requests, online status updates, and party communications
|
||||
- User interface elements for adding/removing friends, viewing details, and managing connections
|
||||
- Configuration options for notifications, privacy, and display preferences
|
||||
- Real-time status updates and connection state management
|
||||
|
||||
## Project Structure
|
||||
The friends and social features span shared data models, view models, Avalonia views, UO network packets, and commands:
|
||||
- Data model: FriendEntry defines the core friend entity and its lifecycle states
|
||||
- View model: FriendsTabViewModel orchestrates friend list operations and binds to the UI
|
||||
- UI: FriendsTabControl (Avalonia) renders the friend list and exposes user actions
|
||||
- Commands: FriendsCommands provides hotkey-driven social actions
|
||||
- Network integration: Incoming packet handlers and specific party-related packets coordinate with UO server events
|
||||
- Status and entities: PlayerStatus and Mobile provide real-time presence and context for friends
|
||||
- Chat: ChatManager integrates social messaging into the chat subsystem
|
||||
- Options: Options centralizes configuration for social behavior and display
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Shared"
|
||||
FE["FriendEntry"]
|
||||
FVM["FriendsTabViewModel"]
|
||||
FC["FriendsCommands"]
|
||||
IPH["IncomingPacketHandlers"]
|
||||
OPT["Options"]
|
||||
CHAT["ChatManager"]
|
||||
PS["PlayerStatus"]
|
||||
MOB["Mobile"]
|
||||
end
|
||||
subgraph "Avalonia UI"
|
||||
FTABXAML["FriendsTabControl.axaml"]
|
||||
FTABCS["FriendsTabControl.xaml.cs"]
|
||||
end
|
||||
subgraph "UO Packets"
|
||||
API["AcceptPartyInvitation"]
|
||||
RPI["RejectPartyInvitation"]
|
||||
end
|
||||
FTABXAML --> FTABCS
|
||||
FTABCS --> FVM
|
||||
FVM --> FE
|
||||
FVM --> FC
|
||||
FVM --> CHAT
|
||||
FVM --> PS
|
||||
FVM --> MOB
|
||||
IPH --> API
|
||||
IPH --> RPI
|
||||
IPH --> FVM
|
||||
OPT --> FVM
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [FriendEntry.cs](file://ClassicAssist.Shared/Data/Friends/FriendEntry.cs)
|
||||
- [FriendsTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/FriendsTabViewModel.cs)
|
||||
- [FriendsTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/FriendsTabControl.xaml.cs)
|
||||
- [FriendsTabControl.axaml](file://ClassicAssist.Avalonia/Views/Agents/FriendsTabControl.axaml)
|
||||
- [FriendsCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/FriendsCommands.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [AcceptPartyInvitation.cs](file://ClassicAssist.Shared/UO/Network/Packets/AcceptPartyInvitation.cs)
|
||||
- [RejectPartyInvitation.cs](file://ClassicAssist.Shared/UO/Network/Packets/RejectPartyInvitation.cs)
|
||||
- [PlayerStatus.cs](file://ClassicAssist.Shared/UO/Data/PlayerStatus.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
|
||||
- [Options.cs](file://ClassicAssist.Shared/Data/Options.cs)
|
||||
|
||||
**Section sources**
|
||||
- [FriendEntry.cs](file://ClassicAssist.Shared/Data/Friends/FriendEntry.cs)
|
||||
- [FriendsTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/FriendsTabViewModel.cs)
|
||||
- [FriendsTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/FriendsTabControl.xaml.cs)
|
||||
- [FriendsTabControl.axaml](file://ClassicAssist.Avalonia/Views/Agents/FriendsTabControl.axaml)
|
||||
- [FriendsCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/FriendsCommands.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [AcceptPartyInvitation.cs](file://ClassicAssist.Shared/UO/Network/Packets/AcceptPartyInvitation.cs)
|
||||
- [RejectPartyInvitation.cs](file://ClassicAssist.Shared/UO/Network/Packets/RejectPartyInvitation.cs)
|
||||
- [PlayerStatus.cs](file://ClassicAssist.Shared/UO/Data/PlayerStatus.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
|
||||
- [Options.cs](file://ClassicAssist.Shared/Data/Options.cs)
|
||||
|
||||
## Core Components
|
||||
- FriendEntry: Represents a single friend with fields for identity, relationship state, last seen timestamps, notes/metadata, and flags that reflect current presence or group membership. It supports serialization and change notification for UI binding.
|
||||
- FriendsTabViewModel: Manages the collection of friends, exposes commands for add/remove/target/chat, filters/sorts, and reacts to network events to update statuses. It coordinates with ChatManager for messaging and uses Options for preferences.
|
||||
- FriendsTabControl (Avalonia): Provides the XAML layout and code-behind interactions for the friends panel, including list selection, detail panes, and quick action buttons.
|
||||
- FriendsCommands: Hotkey-based commands to perform common social tasks such as inviting, targeting, or messaging friends.
|
||||
- IncomingPacketHandlers: Bridges UO server events to application logic, updating friend lists and party state based on incoming packets.
|
||||
- Party Packets: AcceptPartyInvitation and RejectPartyInvitation define structures used by the handler to process party invitations.
|
||||
- PlayerStatus and Mobile: Provide real-time presence and contextual information about players, which are reflected in friend statuses and UI indicators.
|
||||
- ChatManager: Integrates social messages into the chat system, enabling direct communication with friends.
|
||||
- Options: Centralizes configuration for social notifications, privacy settings, and display preferences.
|
||||
|
||||
**Section sources**
|
||||
- [FriendEntry.cs](file://ClassicAssist.Shared/Data/Friends/FriendEntry.cs)
|
||||
- [FriendsTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/FriendsTabViewModel.cs)
|
||||
- [FriendsTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/FriendsTabControl.xaml.cs)
|
||||
- [FriendsTabControl.axaml](file://ClassicAssist.Avalonia/Views/Agents/FriendsTabControl.axaml)
|
||||
- [FriendsCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/FriendsCommands.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [AcceptPartyInvitation.cs](file://ClassicAssist.Shared/UO/Network/Packets/AcceptPartyInvitation.cs)
|
||||
- [RejectPartyInvitation.cs](file://ClassicAssist.Shared/UO/Network/Packets/RejectPartyInvitation.cs)
|
||||
- [PlayerStatus.cs](file://ClassicAssist.Shared/UO/Data/PlayerStatus.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
|
||||
- [Options.cs](file://ClassicAssist.Shared/Data/Options.cs)
|
||||
|
||||
## Architecture Overview
|
||||
The social feature architecture follows MVVM with clear separation between data, presentation, and networking:
|
||||
- Data layer: FriendEntry encapsulates friend state and metadata
|
||||
- Presentation layer: FriendsTabControl (AXAML + code-behind) binds to FriendsTabViewModel
|
||||
- Business logic: FriendsTabViewModel manages operations, filters, and reactions to network events
|
||||
- Networking layer: IncomingPacketHandlers parse UO packets and update ViewModel/state
|
||||
- External integrations: ChatManager for messaging; Options for configuration; PlayerStatus/Mobile for presence
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant UOServer as "Ultima Online Server"
|
||||
participant Net as "IncomingPacketHandlers"
|
||||
participant VM as "FriendsTabViewModel"
|
||||
participant UI as "FriendsTabControl"
|
||||
participant Chat as "ChatManager"
|
||||
UOServer->>Net : "Friend request / status update / party invite"
|
||||
Net->>VM : "Update friend entry / refresh list"
|
||||
VM-->>UI : "Notify changes (collection/status)"
|
||||
UI->>VM : "User action (add/remove/target/chat)"
|
||||
VM->>Chat : "Send message / open chat"
|
||||
VM-->>UI : "Update UI indicators"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [FriendsTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/FriendsTabViewModel.cs)
|
||||
- [FriendsTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/FriendsTabControl.xaml.cs)
|
||||
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### FriendEntry Data Model
|
||||
FriendEntry is the canonical representation of a friend. It includes:
|
||||
- Identity fields: name, serial, and optional alias
|
||||
- Relationship state: accepted/pending/blocked flags
|
||||
- Presence and activity: last seen timestamp, online/offline indicators, zone/location if available
|
||||
- Metadata: notes/tags, custom properties, and any additional attributes required for display or filtering
|
||||
- Persistence: serialization support for saving/loading across sessions
|
||||
- Change notification: implements observable patterns so UI updates automatically when properties change
|
||||
|
||||
Complexity considerations:
|
||||
- Accessors and setters are O(1)
|
||||
- Equality comparisons typically rely on identity fields (name/serial), O(1) average case
|
||||
- Serialization cost depends on metadata size; keep notes concise for performance
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class FriendEntry {
|
||||
+string Name
|
||||
+uint Serial
|
||||
+bool IsAccepted
|
||||
+bool IsPending
|
||||
+bool IsBlocked
|
||||
+DateTime LastSeen
|
||||
+string Zone
|
||||
+string Notes
|
||||
+Dictionary~string,string~ Metadata
|
||||
+Serialize() byte[]
|
||||
+Deserialize(bytes) void
|
||||
+OnPropertyChanged(event)
|
||||
}
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [FriendEntry.cs](file://ClassicAssist.Shared/Data/Friends/FriendEntry.cs)
|
||||
|
||||
**Section sources**
|
||||
- [FriendEntry.cs](file://ClassicAssist.Shared/Data/Friends/FriendEntry.cs)
|
||||
|
||||
### FriendsTabControl Implementation
|
||||
The Avalonia FriendsTabControl provides:
|
||||
- A list view bound to the friend collection from FriendsTabViewModel
|
||||
- Status indicators reflecting online/offline and presence flags
|
||||
- Quick actions: target friend, send message, remove friend, view details
|
||||
- Filtering and sorting controls driven by ViewModel commands
|
||||
- Detail pane showing friend metadata, notes, and history
|
||||
|
||||
Key behaviors:
|
||||
- Selection changes trigger detail updates
|
||||
- Double-click actions can target or initiate chat
|
||||
- Context menu offers common operations
|
||||
- Keyboard shortcuts align with FriendsCommands
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["Open Friends Tab"]) --> BindList["Bind to Friend Collection"]
|
||||
BindList --> ShowStatus["Render Status Indicators"]
|
||||
ShowStatus --> UserAction{"User Action?"}
|
||||
UserAction --> |Add Friend| AddFlow["Prompt and Validate Input"]
|
||||
UserAction --> |Remove Friend| RemoveFlow["Confirm and Remove Entry"]
|
||||
UserAction --> |Target| TargetFlow["Set Target via Mobile"]
|
||||
UserAction --> |Chat| ChatFlow["Open Chat with Friend"]
|
||||
AddFlow --> UpdateCollection["Update Collection"]
|
||||
RemoveFlow --> UpdateCollection
|
||||
TargetFlow --> UpdateUI["Refresh UI State"]
|
||||
ChatFlow --> UpdateUI
|
||||
UpdateCollection --> UpdateUI
|
||||
UpdateUI --> End(["Ready"])
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [FriendsTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/FriendsTabControl.xaml.cs)
|
||||
- [FriendsTabControl.axaml](file://ClassicAssist.Avalonia/Views/Agents/FriendsTabControl.axaml)
|
||||
- [FriendsTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/FriendsTabViewModel.cs)
|
||||
|
||||
**Section sources**
|
||||
- [FriendsTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/FriendsTabControl.xaml.cs)
|
||||
- [FriendsTabControl.axaml](file://ClassicAssist.Avalonia/Views/Agents/FriendsTabControl.axaml)
|
||||
- [FriendsTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/FriendsTabViewModel.cs)
|
||||
|
||||
### Party Coordination Tools
|
||||
Party coordination integrates with UO’s party system:
|
||||
- Invitation handling: IncomingPacketHandlers process AcceptPartyInvitation and RejectPartyInvitation packets
|
||||
- Member management: ViewModel updates party membership and reflects it in friend statuses
|
||||
- Status synchronization: Real-time updates propagate through PlayerStatus and Mobile objects
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "Client App"
|
||||
participant Handler as "IncomingPacketHandlers"
|
||||
participant Packet as "AcceptPartyInvitation"
|
||||
participant VM as "FriendsTabViewModel"
|
||||
participant Status as "PlayerStatus"
|
||||
Client->>Handler : "Receive party invitation"
|
||||
Handler->>Packet : "Parse invitation payload"
|
||||
Handler->>VM : "Notify new invitation"
|
||||
VM->>Status : "Update party presence"
|
||||
VM-->>Client : "Show invitation prompt"
|
||||
Client->>VM : "Accept/Reject"
|
||||
VM->>Handler : "Send accept/reject response"
|
||||
Handler-->>Client : "Update party members"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [AcceptPartyInvitation.cs](file://ClassicAssist.Shared/UO/Network/Packets/AcceptPartyInvitation.cs)
|
||||
- [RejectPartyInvitation.cs](file://ClassicAssist.Shared/UO/Network/Packets/RejectPartyInvitation.cs)
|
||||
- [FriendsTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/FriendsTabViewModel.cs)
|
||||
- [PlayerStatus.cs](file://ClassicAssist.Shared/UO/Data/PlayerStatus.cs)
|
||||
|
||||
**Section sources**
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [AcceptPartyInvitation.cs](file://ClassicAssist.Shared/UO/Network/Packets/AcceptPartyInvitation.cs)
|
||||
- [RejectPartyInvitation.cs](file://ClassicAssist.Shared/UO/Network/Packets/RejectPartyInvitation.cs)
|
||||
- [FriendsTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/FriendsTabViewModel.cs)
|
||||
- [PlayerStatus.cs](file://ClassicAssist.Shared/UO/Data/PlayerStatus.cs)
|
||||
|
||||
### Integration with Ultima Online Social Protocols
|
||||
Integration points include:
|
||||
- Friend requests: Handled by IncomingPacketHandlers, which update FriendEntry state and notify the ViewModel
|
||||
- Online status updates: PlayerStatus and Mobile provide presence data; ViewModel reflects these changes in the UI
|
||||
- Party communications: Party invitation packets are parsed and translated into user prompts and state updates
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Receive["Receive UO Packet"] --> Parse["IncomingPacketHandlers parses"]
|
||||
Parse --> Type{"Packet Type?"}
|
||||
Type --> |Friend Request| UpdateFriend["Update FriendEntry state"]
|
||||
Type --> |Status Update| SyncPresence["Sync PlayerStatus/Mobile"]
|
||||
Type --> |Party Invite| PromptInvite["Prompt Accept/Reject"]
|
||||
UpdateFriend --> NotifyVM["Notify FriendsTabViewModel"]
|
||||
SyncPresence --> NotifyVM
|
||||
PromptInvite --> HandleChoice["Handle user choice"]
|
||||
HandleChoice --> SendResponse["Send Accept/Reject packet"]
|
||||
NotifyVM --> RefreshUI["Refresh UI indicators"]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [FriendEntry.cs](file://ClassicAssist.Shared/Data/Friends/FriendEntry.cs)
|
||||
- [FriendsTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/FriendsTabViewModel.cs)
|
||||
- [PlayerStatus.cs](file://ClassicAssist.Shared/UO/Data/PlayerStatus.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
|
||||
**Section sources**
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [FriendEntry.cs](file://ClassicAssist.Shared/Data/Friends/FriendEntry.cs)
|
||||
- [FriendsTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/FriendsTabViewModel.cs)
|
||||
- [PlayerStatus.cs](file://ClassicAssist.Shared/UO/Data/PlayerStatus.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
|
||||
### User Interface Elements
|
||||
- Adding friends: Input validation, duplicate checks, and confirmation dialogs managed by FriendsTabViewModel
|
||||
- Removing friends: Confirmation prompts and immediate UI refresh
|
||||
- Viewing details: Detail pane shows metadata, notes, last seen, and presence indicators
|
||||
- Managing connections: Context menus and keyboard shortcuts streamline operations
|
||||
|
||||
Best practices:
|
||||
- Debounce rapid UI updates to avoid excessive redraws
|
||||
- Use virtualization for large friend lists
|
||||
- Provide accessible labels and tooltips for all actions
|
||||
|
||||
**Section sources**
|
||||
- [FriendsTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/FriendsTabControl.xaml.cs)
|
||||
- [FriendsTabControl.axaml](file://ClassicAssist.Avalonia/Views/Agents/FriendsTabControl.axaml)
|
||||
- [FriendsTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/FriendsTabViewModel.cs)
|
||||
|
||||
### Configuration Options
|
||||
Social configuration is centralized in Options:
|
||||
- Notifications: Enable/disable popups for friend requests and party invites
|
||||
- Privacy: Control visibility of presence and allow/deny incoming requests
|
||||
- Display preferences: Theme toggles, indicator styles, and default sort order
|
||||
|
||||
Usage:
|
||||
- FriendsTabViewModel reads/writes Options to persist user preferences
|
||||
- Changes apply immediately to UI and behavior
|
||||
|
||||
**Section sources**
|
||||
- [Options.cs](file://ClassicAssist.Shared/Data/Options.cs)
|
||||
- [FriendsTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/FriendsTabViewModel.cs)
|
||||
|
||||
### Real-Time Status Updates and Connection State Management
|
||||
Real-time updates rely on:
|
||||
- IncomingPacketHandlers reacting to server events
|
||||
- PlayerStatus and Mobile providing live presence data
|
||||
- FriendsTabViewModel coordinating updates and notifying UI
|
||||
|
||||
Connection state management:
|
||||
- Track connectivity and reconnection attempts
|
||||
- Gracefully handle missing or stale entries
|
||||
- Ensure UI remains responsive during network interruptions
|
||||
|
||||
**Section sources**
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [PlayerStatus.cs](file://ClassicAssist.Shared/UO/Data/PlayerStatus.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [FriendsTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/FriendsTabViewModel.cs)
|
||||
|
||||
## Dependency Analysis
|
||||
The following diagram highlights key dependencies among components:
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
FE["FriendEntry"] --> FVM["FriendsTabViewModel"]
|
||||
FVM --> FTAB["FriendsTabControl"]
|
||||
FVM --> FC["FriendsCommands"]
|
||||
FVM --> CHAT["ChatManager"]
|
||||
FVM --> OPT["Options"]
|
||||
IPH["IncomingPacketHandlers"] --> FVM
|
||||
IPH --> API["AcceptPartyInvitation"]
|
||||
IPH --> RPI["RejectPartyInvitation"]
|
||||
FVM --> PS["PlayerStatus"]
|
||||
FVM --> MOB["Mobile"]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [FriendEntry.cs](file://ClassicAssist.Shared/Data/Friends/FriendEntry.cs)
|
||||
- [FriendsTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/FriendsTabViewModel.cs)
|
||||
- [FriendsTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/FriendsTabControl.xaml.cs)
|
||||
- [FriendsCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/FriendsCommands.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [AcceptPartyInvitation.cs](file://ClassicAssist.Shared/UO/Network/Packets/AcceptPartyInvitation.cs)
|
||||
- [RejectPartyInvitation.cs](file://ClassicAssist.Shared/UO/Network/Packets/RejectPartyInvitation.cs)
|
||||
- [PlayerStatus.cs](file://ClassicAssist.Shared/UO/Data/PlayerStatus.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
|
||||
- [Options.cs](file://ClassicAssist.Shared/Data/Options.cs)
|
||||
|
||||
**Section sources**
|
||||
- [FriendEntry.cs](file://ClassicAssist.Shared/Data/Friends/FriendEntry.cs)
|
||||
- [FriendsTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/FriendsTabViewModel.cs)
|
||||
- [FriendsTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/FriendsTabControl.xaml.cs)
|
||||
- [FriendsCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/FriendsCommands.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [AcceptPartyInvitation.cs](file://ClassicAssist.Shared/UO/Network/Packets/AcceptPartyInvitation.cs)
|
||||
- [RejectPartyInvitation.cs](file://ClassicAssist.Shared/UO/Network/Packets/RejectPartyInvitation.cs)
|
||||
- [PlayerStatus.cs](file://ClassicAssist.Shared/UO/Data/PlayerStatus.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
|
||||
- [Options.cs](file://ClassicAssist.Shared/Data/Options.cs)
|
||||
|
||||
## Performance Considerations
|
||||
- Use virtualized lists for large friend collections to reduce rendering overhead
|
||||
- Debounce frequent status updates to minimize UI churn
|
||||
- Keep FriendEntry metadata minimal; store heavy content externally if needed
|
||||
- Batch UI updates where possible to improve responsiveness
|
||||
- Avoid blocking the UI thread during network operations; use asynchronous patterns
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- Friend not appearing: Verify IncomingPacketHandlers are registered and parsing correct packets; check Options for privacy restrictions
|
||||
- Status not updating: Confirm PlayerStatus and Mobile are receiving updates; ensure ViewModel is subscribed to change notifications
|
||||
- Party invitation not shown: Validate AcceptPartyInvitation and RejectPartyInvitation packet parsing; check handler registration
|
||||
- Chat not opening: Ensure ChatManager integration is active and friend identity is valid
|
||||
|
||||
Debugging tips:
|
||||
- Log packet types and payloads around social events
|
||||
- Inspect ViewModel state transitions after network events
|
||||
- Review Options values affecting notifications and privacy
|
||||
|
||||
**Section sources**
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [AcceptPartyInvitation.cs](file://ClassicAssist.Shared/UO/Network/Packets/AcceptPartyInvitation.cs)
|
||||
- [RejectPartyInvitation.cs](file://ClassicAssist.Shared/UO/Network/Packets/RejectPartyInvitation.cs)
|
||||
- [FriendsTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/FriendsTabViewModel.cs)
|
||||
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
|
||||
- [Options.cs](file://ClassicAssist.Shared/Data/Options.cs)
|
||||
|
||||
## Conclusion
|
||||
ClassicAssist.Avalonia’s friends and social features combine a robust data model, an intuitive MVVM UI, and tight integration with Ultima Online’s networking layer. FriendEntry captures essential relationship and presence data, while FriendsTabControl delivers a responsive interface for managing connections. IncomingPacketHandlers bridge server events to application state, enabling real-time updates for friend status and party coordination. With configurable notifications, privacy controls, and efficient UI practices, the system provides a comprehensive social experience tailored for Ultima Online gameplay.
|
||||
Reference in New Issue
Block a user