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

12 KiB
Raw Blame History

Getting Started

**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)

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. 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
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

Section sources

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

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.
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

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

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

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

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.

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

Diagram sources

Section sources

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

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]

Reference in New Issue View Git Blame Copy Permalink