# Debug Console **Referenced Files in This Document** - [DebugWindow.axaml](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml) - [DebugWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml.cs) - [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs) - [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs) - [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs) - [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs) - [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs) - [PacketFilter.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilter.cs) - [PacketFilterInfo.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilterInfo.cs) - [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs) - [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs) - [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs) - [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs) ## 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 Debug Console in ClassicAssist.Avalonia, focusing on how it receives, displays, and manages diagnostic information from various subsystems. It covers: - Console output system and log viewing capabilities - Diagnostic information display for packets, chat, and macros - Configuring logging levels, filtering messages, and exporting debug data - Real-time streaming and search functionality - Message formatting options and interpreting outputs - Performance implications across logging levels - Best practices for development vs production - Extending the console with custom sources and formats ## Project Structure The Debug Console is implemented as an Avalonia view with a corresponding ViewModel that binds to shared services and network filters. The key files are: - View layer (Avalonia): DebugWindow.axaml and DebugWindow.axaml.cs - View model: DebugViewModel.cs - Shared services and filters: ChatManager, Packet Filters, Packet Handlers - Application bootstrap: App.axaml.cs and Engine.cs ```mermaid graph TB subgraph "UI Layer" DW["DebugWindow.axaml"] DWC["DebugWindow.axaml.cs"] DVM["DebugViewModel.cs"] end subgraph "Shared Services" CM["ChatManager.cs"] SMTW["SystemMessageTextWriter.cs"] end subgraph "Networking" IPF["IncomingPacketFilters.cs"] OPF["OutgoingPacketFilters.cs"] PF["PacketFilter.cs"] PFI["PacketFilterInfo.cs"] IPH["IncomingPacketHandlers.cs"] OPH["OutgoingPacketHandlers.cs"] end subgraph "Bootstrap" APP["App.axaml.cs"] ENG["Engine.cs"] end DW --> DWC DWC --> DVM DVM --> CM DVM --> IPF DVM --> OPF DVM --> PF DVM --> PFI DVM --> IPH DVM --> OPH APP --> ENG ENG --> DVM ``` **Diagram sources** - [DebugWindow.axaml](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml) - [DebugWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml.cs) - [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs) - [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs) - [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs) - [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs) - [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs) - [PacketFilter.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilter.cs) - [PacketFilterInfo.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilterInfo.cs) - [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs) - [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs) - [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs) - [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs) **Section sources** - [DebugWindow.axaml](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml) - [DebugWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml.cs) - [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs) - [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs) - [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs) ## Core Components - Debug Window (View): Provides UI elements for displaying logs, searching, filtering, and exporting. - Debug View Model: Binds UI to shared services and network filters; exposes commands for filtering, clearing, and exporting. - Chat Manager: Centralizes chat message handling and can be integrated into the console for unified diagnostics. - System Message Text Writer: Bridges macro/system messages into the console pipeline. - Packet Filters and Handlers: Provide real-time packet inspection and routing, enabling detailed network diagnostics. Key responsibilities: - Receive and aggregate logs from multiple sources - Render logs in real time with optional auto-scrolling - Support filtering by level, source, or keyword - Allow export of filtered logs to external files - Maintain performance by throttling high-volume streams **Section sources** - [DebugWindow.axaml](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml) - [DebugWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml.cs) - [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs) - [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs) - [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs) ## Architecture Overview The Debug Console integrates with shared services and networking layers to provide centralized diagnostics. The flow typically involves: - Subsystems emitting logs/messages via shared services - Debug View Model subscribing to events and updating bound collections - UI rendering entries in real time with filtering and search - Export functionality writing selected entries to disk ```mermaid sequenceDiagram participant Subsystem as "Subsystem" participant Service as "Shared Service" participant VM as "DebugViewModel" participant UI as "DebugWindow" participant Exporter as "Exporter" Subsystem->>Service : Emit log/message Service-->>VM : Event/Notification VM->>VM : Apply filter/format VM-->>UI : Update collection UI->>UI : Render entry (real-time) UI->>Exporter : Export filtered logs Exporter-->>UI : Save file path/status ``` **Diagram sources** - [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs) - [DebugWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml.cs) - [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs) - [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs) - [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs) ## Detailed Component Analysis ### Debug Window (View) - Purpose: Hosts the console UI, including log list, search box, filter controls, and export actions. - Behavior: Binds to properties exposed by DebugViewModel; supports keyboard shortcuts and context menu operations. - Integration: Uses Avalonia data binding to reflect changes from the ViewModel efficiently. ```mermaid classDiagram class DebugWindow { +InitializeComponent() +OnLoaded() +BindDataContext() +ExportLogs() +ClearConsole() +SearchText +SelectedLogLevel +AutoScrollEnabled } ``` **Diagram sources** - [DebugWindow.axaml](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml) - [DebugWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml.cs) **Section sources** - [DebugWindow.axaml](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml) - [DebugWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml.cs) ### Debug View Model - Purpose: Aggregates logs, applies filters, formats messages, and exposes commands for UI interaction. - Responsibilities: - Subscribe to shared services (e.g., ChatManager) and packet filters - Maintain a bounded collection of log entries to prevent memory growth - Implement filtering by level, source, and text search - Provide export functionality to write logs to files - Manage auto-scroll behavior and thread-safe updates ```mermaid classDiagram class DebugViewModel { +ObservableCollection~LogEntry~ Logs +string SearchText +LogLevel SelectedLogLevel +bool AutoScroll +void AddLog(source, level, message) +void ClearLogs() +IEnumerable~LogEntry~ GetFilteredLogs() +void ExportLogs(path) +void ToggleAutoScroll() } class LogEntry { +DateTime Timestamp +string Source +LogLevel Level +string Message } DebugViewModel --> LogEntry : "creates/manages" ``` **Diagram sources** - [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs) **Section sources** - [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs) ### Chat Integration - Purpose: Route chat messages into the console for unified diagnostics. - Mechanism: Subscribe to ChatManager events and append formatted entries to the log collection. ```mermaid sequenceDiagram participant Client as "Game Client" participant CM as "ChatManager" participant VM as "DebugViewModel" participant UI as "DebugWindow" Client->>CM : Chat event CM-->>VM : OnChatMessage(args) VM->>VM : Format message VM-->>UI : Append to Logs UI->>UI : Render new entry ``` **Diagram sources** - [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs) - [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs) - [DebugWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml.cs) **Section sources** - [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs) - [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs) ### Macro System Messages - Purpose: Capture macro/system messages and route them to the console. - Mechanism: Use SystemMessageTextWriter to bridge macro outputs into the logging pipeline. ```mermaid flowchart TD Start(["Macro Execution"]) --> Write["SystemMessageTextWriter.Write(message)"] Write --> Filter{"Filter by Level/Source?"} Filter --> |Yes| Append["Append to DebugViewModel.Logs"] Filter --> |No| Drop["Discard Entry"] Append --> Render["UI Renders Entry"] Drop --> End(["End"]) Render --> End ``` **Diagram sources** - [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs) - [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs) **Section sources** - [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs) - [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs) ### Packet Diagnostics - Purpose: Inspect incoming and outgoing packets for network troubleshooting. - Mechanism: Use IncomingPacketFilters and OutgoingPacketFilters to capture and format packet data; integrate with DebugViewModel for display. ```mermaid sequenceDiagram participant Net as "Network Stack" participant IPF as "IncomingPacketFilters" participant OPF as "OutgoingPacketFilters" participant VM as "DebugViewModel" participant UI as "DebugWindow" Net->>IPF : Incoming packet IPF-->>VM : OnIncoming(packet) VM->>VM : Format packet info VM-->>UI : Append to Logs Net->>OPF : Outgoing packet OPF-->>VM : OnOutgoing(packet) VM->>VM : Format packet info VM-->>UI : Append to Logs ``` **Diagram sources** - [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs) - [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs) - [PacketFilter.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilter.cs) - [PacketFilterInfo.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilterInfo.cs) - [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs) - [DebugWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml.cs) **Section sources** - [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs) - [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs) - [PacketFilter.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilter.cs) - [PacketFilterInfo.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilterInfo.cs) - [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs) ### Bootstrap and Initialization - Purpose: Initialize the application and ensure the Debug Console is wired to shared services. - Mechanism: App.axaml.cs and Engine.cs set up DI, register services, and start the main window. ```mermaid flowchart TD Boot["App Startup"] --> Register["Register Services"] Register --> InitVM["Initialize DebugViewModel"] InitVM --> BindUI["Bind DebugWindow DataContext"] BindUI --> Ready["Console Ready"] ``` **Diagram sources** - [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs) - [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs) - [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs) - [DebugWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml.cs) **Section sources** - [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs) - [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs) ## Dependency Analysis The Debug Console depends on shared services and network filters to aggregate and display diagnostics. Key dependencies include: - ChatManager for chat integration - Packet filters for network diagnostics - SystemMessageTextWriter for macro outputs - UI components for rendering and user interaction ```mermaid graph TB DVM["DebugViewModel.cs"] --> CM["ChatManager.cs"] DVM --> IPF["IncomingPacketFilters.cs"] DVM --> OPF["OutgoingPacketFilters.cs"] DVM --> PF["PacketFilter.cs"] DVM --> PFI["PacketFilterInfo.cs"] DVM --> SMTW["SystemMessageTextWriter.cs"] DW["DebugWindow.axaml.cs"] --> DVM ``` **Diagram sources** - [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs) - [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs) - [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs) - [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs) - [PacketFilter.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilter.cs) - [PacketFilterInfo.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilterInfo.cs) - [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs) - [DebugWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml.cs) **Section sources** - [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs) - [DebugWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml.cs) ## Performance Considerations - Logging Levels: - High verbosity (Trace/Debug) can significantly impact performance due to increased I/O and UI updates. - Recommended levels: - Development: Debug or Trace for comprehensive diagnostics - Production: Warning or Error to minimize overhead - Filtering: - Enable server-side filtering where possible to reduce payload size before reaching the console. - Use keyword and level filters to limit displayed entries. - Throttling: - Implement rate limiting for high-frequency logs (e.g., packet dumps). - Batch UI updates to avoid excessive re-renders. - Memory Management: - Use bounded collections to cap log history size. - Periodically purge old entries to prevent memory growth. - Export Strategy: - Stream exports instead of loading entire logs into memory. - Compress exported files if large volumes are expected. [No sources needed since this section provides general guidance] ## Troubleshooting Guide Common issues and resolutions: - Console not receiving logs: - Verify service registration during app startup. - Ensure subscriptions to ChatManager and packet filters are active. - Slow UI when many logs: - Reduce logging level or enable filtering. - Disable auto-scroll if not needed. - Missing packet diagnostics: - Confirm packet filters are enabled and correctly configured. - Check handler registrations for incoming/outgoing packets. - Export failures: - Validate file path permissions and available disk space. - Ensure asynchronous export to avoid blocking UI. **Section sources** - [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs) - [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs) - [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs) ## Conclusion The Debug Console in ClassicAssist.Avalonia provides a centralized, extensible platform for diagnosing game interactions, network traffic, and macro execution. By leveraging shared services and packet filters, it offers real-time insights with configurable filtering and export capabilities. Proper configuration of logging levels and performance optimizations ensures effective debugging in development while maintaining stability in production. [No sources needed since this section summarizes without analyzing specific files] ## Appendices ### Configuration Options - Logging Levels: - Trace: Most verbose, includes detailed internal states - Debug: Useful for feature-level diagnostics - Info: General operational messages - Warning: Potential issues requiring attention - Error: Critical failures - Filters: - Level-based filtering - Source-based filtering (e.g., chat, packets, macros) - Keyword search across message content - Export Formats: - Plain text with timestamps and levels - JSON for structured analysis - CSV for spreadsheet processing [No sources needed since this section provides general guidance] ### Extending the Console - Custom Log Sources: - Implement a publisher that emits log events to DebugViewModel. - Register the publisher during application initialization. - Custom Output Formats: - Extend the exporter to support additional formats. - Integrate with external tools via API endpoints or file watchers. [No sources needed since this section provides general guidance]