Ouse.Estragonia 1.0.1

Estragonia

在 Godot 4 中嵌入 Avalonia UI 的桥接库（Vulkan / Skia 共享纹理）。

代码命名空间仍为 JLeb.Estragonia；NuGet 包名为 Ouse.Estragonia（与上游 JLeb.Estragonia 区分）。

重要声明

• 本仓库大量代码由 AI 辅助编写与改写（含 Avalonia 12 / Godot 4.7 / .NET 10 适配）。
• 不保证稳定性，请勿在未验证的情况下直接用于生产。
• 维护者会审查关键改动；欢迎 Issue / PR，但请自行充分测试。

署名与许可

基于 Julien Lebosquain 的开源项目 Estragonia（MIT）。
原作者版权与许可声明见 license.txt；修改与再分发须保留 MIT 要求的版权与许可文本。

环境

使用教程（推荐：模板）

1. 安装模板

dotnet new install Ouse.Estragonia.Templates

更新到新版本时先卸再装：

dotnet new uninstall Ouse.Estragonia.Templates
dotnet new install Ouse.Estragonia.Templates

2. 创建项目

# -n = 解决方案名；--GodotProjectName = Godot / C# 项目名（须为合法 C# 标识符）
dotnet new estragonia -n MySolution --GodotProjectName MyGame -o MySolution
cd MySolution
dotnet restore

或在 Visual Studio：新建项目 → 搜索 Estragonia Godot App（装模板后若看不到请重启 VS）。

3. 用 Godot 打开

用 Godot 4.7+（.NET） 打开项目根目录的 project.godot
（不要打开 .godot/ 缓存目录）。

模板已配置好：

• Autoload：AvaloniaLoader（UseGodot() 只初始化一次）
• 宿主脚本在 Godot 工程内：AvaloniaControl.cs、UiHost.cs（不要指望 NuGet 自带）
• 默认宿主：UserInterface（UiHost + Views / ViewModels）
• Designer.cs：供 Avalonia 预览器用（Main + BuildAvaloniaApp）

4. 改 UI

• 界面：Views/MainView.axaml
• 逻辑：ViewModels/MainViewModel.cs
• 主题：App.axaml（默认 Semi.Avalonia）

更多说明见 templates/README.md 与 文档 · 快速开始。

使用教程（手动加包）

已有 Godot C# 工程时：

dotnet add package Ouse.Estragonia
dotnet add package Semi.Avalonia
# 可选 MVVM
dotnet add package CommunityToolkit.Mvvm

只加 NuGet 不够。 Godot 节点宿主必须是工程内的脚本文件：

1. 从 templates/estragonia-godot/（或 samples/HelloWorld/）复制到你的 Godot 工程根目录：
   • AvaloniaControl.cs
   • UiHost.cs
2. 增加 Avalonia Application（含主题）。
3. Autoload 里调用一次：

AppBuilder.Configure<App>()
    .UseGodot()
    .SetupWithoutStarting();

GodotAvalonia.EnsureAssetLoader(typeof(App).Assembly);
GetWindow()?.SetImeActive(true);

4. 场景里挂一个 Control，脚本继承工程内的 UiHost，实现 CreateRoot()。

详见 docs/v1.0.0/zh-CN/hosting.md（含「宿主必须在 Godot 工程内」说明）。

仓库内示例

1. 用 Godot 打开 samples/HelloWorld。
2. 编译并运行（该示例用 ProjectReference 指向源码，便于改库）。

仓库结构

src/JLeb.Estragonia/   # 桥接库（NuGet: Ouse.Estragonia）——不含 AvaloniaControl/UiHost
templates/             # dotnet new 模板（含宿主脚本；NuGet: Ouse.Estragonia.Templates）
samples/HelloWorld/    # 示例（含 AvaloniaControl.cs / UiHost.cs）
docs/v1.0.0/           # 手写文档（英 / 中）

热重载提示

AvaloniaControl / UiHost 放在 Godot 工程内，可避免「外部程序集 Godot 类型」导致的 ScriptTypeBiMap 重复 key。
Avalonia 仍可能触发「无法卸载程序集」；编辑器卡死时 完全重启 Godot，必要时删 .godot。

文档 / GitHub Pages

• 在线文档：https://0use-te.github.io/Estragonia/
• 工作流：.github/workflows/docs.yml

本地预览：

docfx docfx.json
docfx serve _site --port 8080

api/ 与 _site/ 为生成物，已 gitignore。维护规则见 DOCFX-AI-PROMPT.md。