first commit
This commit is contained in:
Beyhan Oğur
@@ -0,0 +1,256 @@
|
||||
# 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]
|
||||
Reference in New Issue
Block a user