ClassicAssist.Avalonia/.qoder/repowiki/en/content/Getting Started.md

# Getting Started

<cite>
**Referenced Files in This Document**
- [README.md](file://README.md)
- [ClassicAssist.sln](file://ClassicAssist.sln)
- [ClassicAssist.Avalonia/Program.cs](file://ClassicAssist.Avalonia/Program.cs)
- [ClassicAssist.Avalonia/App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
- [ClassicAssist.Avalonia/Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
- [ClassicAssist.Avalonia/ClassicAssist.Avalonia.csproj](file://ClassicAssist.Avalonia/ClassicAssist.Avalonia.csproj)
- [ClassicAssist.Shared/ClassicAssist.Shared.csproj](file://ClassicAssist.Shared/ClassicAssist.Shared.csproj)
- [ClassicAssist.Launcher/MainViewModel.cs](file://ClassicAssist.Launcher/MainViewModel.cs)
- [ClassicAssist.Launcher/ShardManager.cs](file://ClassicAssist.Launcher/ShardManager.cs)
- [ClassicAssist.Shared/Data/Options.cs](file://ClassicAssist.Shared/Data/Options.cs)
- [ClassicAssist.Shared/Data/AssistantOptions.cs](file://ClassicAssist.Shared/Data/AssistantOptions.cs)
- [ClassicAssist.Shared/UO/Data/ShardEntry.cs](file://ClassicAssist.Shared/UO/Data/ShardEntry.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
ClassicAssist.Avalonia is a cross-platform rewrite of the original WPF-based ClassicAssist Ultima Online client. It brings modern UI and platform support to Windows, macOS, and Linux using Avalonia UI on top of .NET 6+. The project provides a familiar UO assistant experience with enhanced portability and extensibility.

Key goals:
- Modern, cross-platform UI via Avalonia
- Shared game logic and data models across platforms
- Python.NET integration for scripting and macros
- Familiar features from the original WPF client

## Project Structure
The repository is organized into multiple projects:
- ClassicAssist.Avalonia: Avalonia-based UI entry point and platform-specific bootstrapping
- ClassicAssist.Shared: Core game logic, networking, data models, and shared resources
- ClassicAssist.Launcher: WPF-based launcher used to manage shards and profiles (legacy but still present)
- ClassicAssist: Legacy WPF UI components (kept for compatibility)
- ClassicAssist.Tests: Unit tests covering agents, filters, macros, and core functionality
- ClassicAssist.Updater: Update utility
- Tools: Utility tools such as command export

```mermaid
graph TB
subgraph "UI Layer"
A["ClassicAssist.Avalonia<br/>Avalonia UI"]
L["ClassicAssist.Launcher<br/>WPF Launcher"]
C["ClassicAssist<br/>Legacy WPF UI"]
end
subgraph "Shared Core"
S["ClassicAssist.Shared<br/>Game Logic, Data, Networking"]
end
subgraph "Tests & Tools"
T["ClassicAssist.Tests"]
U["ClassicAssist.Updater"]
X["Tools/ExportCommands"]
end
A --> S
L --> S
C --> S
T --> S
U --> S
X --> S
```

**Diagram sources**
- [ClassicAssist.Avalonia/Program.cs](file://ClassicAssist.Avalonia/Program.cs)
- [ClassicAssist.Avalonia/App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
- [ClassicAssist.Launcher/MainViewModel.cs](file://ClassicAssist.Launcher/MainViewModel.cs)
- [ClassicAssist.Shared/ClassicAssist.Shared.csproj](file://ClassicAssist.Shared/ClassicAssist.Shared.csproj)

**Section sources**
- [README.md](file://README.md)
- [ClassicAssist.sln](file://ClassicAssist.sln)

## Core Components
- Application Entry Point: The Avalonia app initializes the runtime, sets up the dispatcher, and starts the main window.
- Engine Initialization: The Avalonia Engine bridges UI initialization with shared engine startup.
- Shared Game Engine: ClassicAssist.Shared contains networking, packet handling, objects, commands, macros, and configuration.
- Launcher Integration: The WPF launcher manages shard selection and profile management; it can be used alongside or prior to launching the Avalonia client.

What you need to know:
- The Avalonia app depends on ClassicAssist.Shared for all game logic.
- Python.NET integration is part of the macro/scripting subsystem within the shared layer.
- Configuration and options are persisted through shared settings classes.

**Section sources**
- [ClassicAssist.Avalonia/Program.cs](file://ClassicAssist.Avalonia/Program.cs)
- [ClassicAssist.Avalonia/App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
- [ClassicAssist.Avalonia/Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
- [ClassicAssist.Shared/ClassicAssist.Shared.csproj](file://ClassicAssist.Shared/ClassicAssist.Shared.csproj)

## Architecture Overview
High-level flow when starting the Avalonia client:
- Program.cs bootstraps the Avalonia application and invokes App.axaml.cs.
- App.axaml.cs initializes the UI and delegates to Engine.cs to start the shared engine.
- ClassicAssist.Shared loads configuration, sets up networking, and prepares the game state.

```mermaid
sequenceDiagram
participant OS as "Operating System"
participant Prog as "Program.cs"
participant App as "App.axaml.cs"
participant Eng as "Engine.cs"
participant Shared as "ClassicAssist.Shared"
OS->>Prog : Launch executable
Prog->>App : Initialize Avalonia app
App->>Eng : Start engine
Eng->>Shared : Load options and config
Shared-->>Eng : Ready
Eng-->>App : UI ready
App-->>OS : Show main window
```

**Diagram sources**
- [ClassicAssist.Avalonia/Program.cs](file://ClassicAssist.Avalonia/Program.cs)
- [ClassicAssist.Avalonia/App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
- [ClassicAssist.Avalonia/Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
- [ClassicAssist.Shared/ClassicAssist.Shared.csproj](file://ClassicAssist.Shared/ClassicAssist.Shared.csproj)

## Detailed Component Analysis

### Installation and Build
Prerequisites:
- .NET 6+ SDK installed and available on PATH
- Git (optional, for cloning)
- Platform-specific dependencies:
  - Windows: Visual Studio build tools or dotnet CLI
  - macOS: Xcode command line tools
  - Linux: GTK3 development libraries and other system packages required by Avalonia

Steps:
1. Clone the repository or download source.
2. Restore NuGet packages:
   - dotnet restore
3. Build the solution:
   - dotnet build ClassicAssist.sln
4. Publish or run the Avalonia app:
   - dotnet run --project ClassicAssist.Avalonia/ClassicAssist.Avalonia.csproj
   - Or publish for your target runtime identifier (e.g., win-x64, osx-x64, linux-x64)

Notes:
- Ensure your environment matches the target framework specified in the project files.
- On Linux, install Avalonia’s required system dependencies (GTK3, etc.).

**Section sources**
- [ClassicAssist.Avalonia/ClassicAssist.Avalonia.csproj](file://ClassicAssist.Avalonia/ClassicAssist.Avalonia.csproj)
- [ClassicAssist.Shared/ClassicAssist.Shared.csproj](file://ClassicAssist.Shared/ClassicAssist.Shared.csproj)
- [ClassicAssist.sln](file://ClassicAssist.sln)

### First-Time Setup
After building and running the client:
- Profile creation:
  - Use the NewProfileWindow to create a new profile if prompted or via the UI controls.
- Shard configuration:
  - Configure shard entries using the shared ShardEntry model and options.
  - If using the launcher, select a shard before launching the client.
- Initial connection:
  - Enter server address, port, and credentials in the connection dialog or options.
  - Connect to the selected shard and verify login.

Where to look:
- Options and AssistantOptions define persistent settings.
- ShardEntry defines shard parameters like host, port, and protocol details.

**Section sources**
- [ClassicAssist.Avalonia/Views/NewProfileWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/NewProfileWindow.axaml.cs)
- [ClassicAssist.Shared/Data/Options.cs](file://ClassicAssist.Shared/Data/Options.cs)
- [ClassicAssist.Shared/Data/AssistantOptions.cs](file://ClassicAssist.Shared/Data/AssistantOptions.cs)
- [ClassicAssist.Shared/UO/Data/ShardEntry.cs](file://ClassicAssist.Shared/UO/Data/ShardEntry.cs)
- [ClassicAssist.Launcher/ShardManager.cs](file://ClassicAssist.Launcher/ShardManager.cs)

### Basic Usage Patterns
- Launch the application:
  - Run the published binary or use dotnet run against the Avalonia project.
- Connect to UO servers:
  - Select a configured shard and enter credentials.
  - Click Connect; the shared networking layer handles authentication and session setup.
- Navigate the main interface:
  - Use tabs and windows for Agents, Macros, Skills, Chat, Debug, and more.
  - Access hotkeys and options from the main menu or control panels.

**Section sources**
- [ClassicAssist.Avalonia/Program.cs](file://ClassicAssist.Avalonia/Program.cs)
- [ClassicAssist.Avalonia/App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
- [ClassicAssist.Avalonia/Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)

## Dependency Analysis
The Avalonia project depends on ClassicAssist.Shared for core functionality. The Launcher and legacy UI also depend on Shared. Tests validate behavior across agents, filters, and macros.

```mermaid
graph LR
Avalonia["ClassicAssist.Avalonia"] --> Shared["ClassicAssist.Shared"]
Launcher["ClassicAssist.Launcher"] --> Shared
Legacy["ClassicAssist (WPF)"] --> Shared
Tests["ClassicAssist.Tests"] --> Shared
```

**Diagram sources**
- [ClassicAssist.Avalonia/ClassicAssist.Avalonia.csproj](file://ClassicAssist.Avalonia/ClassicAssist.Avalonia.csproj)
- [ClassicAssist.Shared/ClassicAssist.Shared.csproj](file://ClassicAssist.Shared/ClassicAssist.Shared.csproj)
- [ClassicAssist.Launcher/ClassicAssist.Launcher.csproj](file://ClassicAssist.Launcher/ClassicAssist.Launcher.csproj)
- [ClassicAssist/ClassicAssist.csproj](file://ClassicAssist/ClassicAssist.csproj)
- [ClassicAssist.Tests/ClassicAssist.Tests.csproj](file://ClassicAssist.Tests/ClassicAssist.Tests.csproj)

**Section sources**
- [ClassicAssist.Avalonia/ClassicAssist.Avalonia.csproj](file://ClassicAssist.Avalonia/ClassicAssist.Avalonia.csproj)
- [ClassicAssist.Shared/ClassicAssist.Shared.csproj](file://ClassicAssist.Shared/ClassicAssist.Shared.csproj)

## Performance Considerations
- Prefer publishing as self-contained for distribution to avoid missing runtime issues.
- Keep macro scripts efficient; heavy computations should be offloaded appropriately.
- Use profiling tools to identify bottlenecks in packet processing or UI rendering.
- Avoid excessive logging in production builds.

[No sources needed since this section provides general guidance]

## Troubleshooting Guide
Common issues and resolutions:
- Missing .NET 6+ runtime:
  - Install the correct .NET 6+ runtime for your platform.
- Avalonia system dependencies not found (Linux):
  - Install GTK3 and related development packages required by Avalonia.
- NuGet package restore failures:
  - Verify network access and ensure dotnet CLI is updated.
  - Clear local NuGet cache if necessary.
- Python.NET integration errors:
  - Ensure Python is installed and accessible on PATH.
  - Confirm compatible Python version and architecture match the target runtime.
- Connection problems:
  - Validate shard host/port and credentials.
  - Check firewall rules and proxy settings.
- Launcher vs. Client confusion:
  - Use the Launcher to manage shards and profiles; then launch the Avalonia client.

Where to look:
- Options and AssistantOptions for configuration persistence.
- ShardEntry for shard parameters.
- Launcher ShardManager for shard management workflows.

**Section sources**
- [ClassicAssist.Shared/Data/Options.cs](file://ClassicAssist.Shared/Data/Options.cs)
- [ClassicAssist.Shared/Data/AssistantOptions.cs](file://ClassicAssist.Shared/Data/AssistantOptions.cs)
- [ClassicAssist.Shared/UO/Data/ShardEntry.cs](file://ClassicAssist.Shared/UO/Data/ShardEntry.cs)
- [ClassicAssist.Launcher/ShardManager.cs](file://ClassicAssist.Launcher/ShardManager.cs)

## Conclusion
ClassicAssist.Avalonia delivers a modern, cross-platform Ultima Online client built on Avalonia and .NET 6+. By following the installation steps, configuring your first profile and shard, and connecting to a server, you can quickly get started. For advanced usage, explore the shared engine capabilities, macros, and agent tools provided by ClassicAssist.Shared.

[No sources needed since this section summarizes without analyzing specific files]