Beyhan Oğur
23 KiB
23 KiB
Friends and Social Features
**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)Table of Contents
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
Introduction
This document explains the 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
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
- FriendsTabViewModel.cs
- FriendsTabControl.xaml.cs
- FriendsTabControl.axaml
- FriendsCommands.cs
- IncomingPacketHandlers.cs
- AcceptPartyInvitation.cs
- RejectPartyInvitation.cs
- PlayerStatus.cs
- Mobile.cs
- ChatManager.cs
- Options.cs
Section sources
- FriendEntry.cs
- FriendsTabViewModel.cs
- FriendsTabControl.xaml.cs
- FriendsTabControl.axaml
- FriendsCommands.cs
- IncomingPacketHandlers.cs
- AcceptPartyInvitation.cs
- RejectPartyInvitation.cs
- PlayerStatus.cs
- Mobile.cs
- ChatManager.cs
- 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
- FriendsTabViewModel.cs
- FriendsTabControl.xaml.cs
- FriendsTabControl.axaml
- FriendsCommands.cs
- IncomingPacketHandlers.cs
- AcceptPartyInvitation.cs
- RejectPartyInvitation.cs
- PlayerStatus.cs
- Mobile.cs
- ChatManager.cs
- 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
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
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
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
Section sources
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
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
Section sources
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
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
- AcceptPartyInvitation.cs
- RejectPartyInvitation.cs
- FriendsTabViewModel.cs
- PlayerStatus.cs
Section sources
- IncomingPacketHandlers.cs
- AcceptPartyInvitation.cs
- RejectPartyInvitation.cs
- FriendsTabViewModel.cs
- 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
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
Section sources
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
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
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
Dependency Analysis
The following diagram highlights key dependencies among components:
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
- FriendsTabViewModel.cs
- FriendsTabControl.xaml.cs
- FriendsCommands.cs
- IncomingPacketHandlers.cs
- AcceptPartyInvitation.cs
- RejectPartyInvitation.cs
- PlayerStatus.cs
- Mobile.cs
- ChatManager.cs
- Options.cs
Section sources
- FriendEntry.cs
- FriendsTabViewModel.cs
- FriendsTabControl.xaml.cs
- FriendsCommands.cs
- IncomingPacketHandlers.cs
- AcceptPartyInvitation.cs
- RejectPartyInvitation.cs
- PlayerStatus.cs
- Mobile.cs
- ChatManager.cs
- 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
- AcceptPartyInvitation.cs
- RejectPartyInvitation.cs
- FriendsTabViewModel.cs
- ChatManager.cs
- 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.