Giới thiệu về Estragonia

Estragonia là một thư viện cho phép nhúng giao diện Avalonia vào trong công cụ Godot. Dự án hiện tại còn ở giai đoạn thử nghiệm và tồn tại một số lỗi như control không được vẽ ngay lập tức hoặc vấn đề với tài nguyên từ thư viện Avalonia.

Chuẩn bị môi trường

• Avalonia 11.0.0
• Godot 4.2 (.NET edition)
• NuGet package: JLeb.Estragonia

Quy trình thiết lập

1. Cấu hình Godot

Trước tiên, cần tạo hoặc mở một dự án Godot 4 với renderer Forward+ hoặc Mobile. Thêm một node Control vào Scene, đặt tên là UserInterface. Trong Inspector, thiết lập thuộc tính Focus > Mode thành All để đảm bảo nhận được sự kiện bàn phím.

// UserInterface.cs (Godot C# Script)
public partial class UserInterface : JLeb.Estragonia.AvaloniaControl
{
    public override void _Ready()
    {
        base._Ready();
        // Khởi tạo Avalonia view ở đây
        Control = new MyAvaloniaView();
    }
}

2. Cài đặt NuGet packages

Mở dự án Godot và cài các gói sau qua NuGet:

• JLeb.Estragonia
• Avalonia.Themes.Fluent (bắt buộc để có theme cho control)

3. Tạo Avalonia Application

Tạo class App kế thừa từ Avalonia.Application và cấu hình:

// App.axaml.cs
using Avalonia;
using Avalonia.Markup.Xaml;

namespace MyProject
{
    public partial class App : Application
    {
        public override void Initialize()
        {
            AvaloniaXamlLoader.Load(this);
        }
    }
}

Trong file App.axaml, cần khai báo theme Fluent:

<Application xmlns="https://github.com/avaloniaui"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             x:Class="MyProject.App">
    <Application.Styles>
        <FluentTheme />
    </Application.Styles>
</Application>

4. Thiết lập Avalonia trong Godot

Trong file UserInterface.cs (Godot), thêm dòng khởi tạo Avalonia trước khi gán Control:

public partial class UserInterface : JLeb.Estragonia.AvaloniaControl
{
    public override void _Ready()
    {
        // Khởi tạo Avalonia engine
        AppBuilder.Configure<App>()
                 .UseGodot()
                 .SetupWithoutStarting();

        // Gán view Avalonia
        Control = new MyAvaloniaView();
        
        base._Ready();
    }
}

5. Tạo Avalonia View

Tạo một UserControl trong Avalonia:

<UserControl xmlns="https://github.com/avaloniaui"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             x:Class="MyProject.MyAvaloniaView">
    <StackPanel>
        <TextBlock Text="Welcome to Avalonia in Godot!" />
        <Button Content="Click me" />
    </StackPanel>
</UserControl>

6. Xử lý vấn đề tương thích .NET

Nếu Godot dùng .NET 6.0 và Avalonia yêu cầu .NET 7.0, cần sửa file .csproj của Godot:

<TargetFramework>net7.0</TargetFramework>

Đồng thời thêm tham chiếu trực tiếp đến dự án Avalonia:

<ItemGroup>
    <ProjectReference Include="..\AvaloniaProject\AvaloniaProject.csproj" />
</ItemGroup>

7. AutoLoad AvaloniaLoader (Quan trọng)

Estragonia yêu cầu một class đặc biệt tên là AvaloniaLoader để quản lý vòng đời Avalonia. Thêm file AvaloniaLoader.cs vào dự án Godot:

using Godot;
using JLeb.Estragonia;

public partial class AvaloniaLoader : Node
{
    public override void _Ready()
    {
        // Đảm bảo Avalonia được khởi tạo trước các control
    }
}

Trong Godot Editor, vào Project > Project Settings > Autoload, thêm AvaloniaLoader.cs với tên AvaloniaLoader.

Giải quyết vấn đề thường gặp

Màn hình trắng khi chạy

Nếu giao diện Avalonia không hiển thị ngay, cần click vào vùng control để kích hoạt vẽ lại. Đây là lỗi đã biết của Estragonia. Có thể thử force refresh code:

public override void _Ready()
{
    base._Ready();
    // Force refresh
    CallDeferred("UpdateAvaloniaControls");
}

private void UpdateAvaloniaControls()
{
    // Kích hoạt vẽ lại
    QueueRedraw();
}

View từ thư viện ngoài không hiển thị

Các control Avalonia được định nghĩa trong thư viện riêng có thể không hoạt động. Nên tạo trực tiếp view UserControl trong dự án Godot để đảm bảo tương thích.

Kết luận tạm thời

Estragonia vẫn đang trong giai đoạn phát triển sớm. Các vấn đề như vẽ lại không đồng bộ, tương thích .NET và thiếu tối ưu khiến việc áp dụng vào sản phẩm thực tế còn nhiều rủi ro. Cần chờ các bản cập nhật tiếp theo để cải thiện độ ổn định.