Sparkle.Live2DView 0.1.1

Sparkle.Live2DView

面向 Avalonia 的交互式 Live2D Cubism 控件，使用 OpenGL 渲染。

支持视线跟随、拖动、滚轮缩放、动作播放、Parameter API 和 Hit Area 检测。各项功能可以单独控制，也支持 Avalonia 属性绑定。

安装

dotnet add package Sparkle.Live2DView --version 0.1.1

当前面向 Windows x64 和 .NET 8。应用需要自行从 Live2D Cubism SDK for Native 获取 Live2DCubismCore.dll，本包不包含 Core 或模型文件。

准备应用项目

推荐目录：

Assets/Models/Hiyori/Hiyori.model3.json
runtimes/win-x64/native/Live2DCubismCore.dll

在应用项目的 .csproj 中加入：

<PropertyGroup>
  <PlatformTarget>x64</PlatformTarget>
</PropertyGroup>

<ItemGroup>
  <Content Include="Assets/Models/**"
           CopyToOutputDirectory="PreserveNewest"
           CopyToPublishDirectory="PreserveNewest" />

  <Content Include="runtimes/win-x64/native/Live2DCubismCore.dll"
           Link="Live2DCubismCore.dll"
           CopyToOutputDirectory="PreserveNewest"
           CopyToPublishDirectory="PreserveNewest" />
</ItemGroup>

放置控件

<Window
    xmlns="https://github.com/avaloniaui"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:live2d="using:Sparkle.Live2DView">

  <Border CornerRadius="16" ClipToBounds="True">
    <live2d:Live2DView
        x:Name="ModelView"
        ModelDirectory="Assets/Models/Hiyori"
        ModelName="Hiyori"
        ModelFit="Uniform"
        ModelPadding="24"
        AutoPauseWhenHidden="True"
        IsPointerFollowEnabled="True"
        CanDrag="True"
        CanZoom="True" />
  </Border>
</Window>

拖动、缩放和视线跟随默认开启。CanDrag、CanZoom 等属性可以直接绑定。

调用功能

依赖模型内容的操作放在 ModelLoaded 之后：

ModelView.ModelLoaded += (_, _) =>
{
    ModelView.PlayRandomMotion("Idle");
    Console.WriteLine($"参数数：{ModelView.GetParameters().Count}");
};

动态切换模型和处理加载失败：

ModelView.ModelLoadFailed += (_, e) =>
    Console.WriteLine(e.Exception.Message);

await ModelView.LoadModelAsync("Assets/Models/Mao", "Mao");
await ModelView.ReloadModelAsync();

切换失败不会移除当前正在显示的模型。

完整的加载生命周期和取消：

ModelView.ModelLoading += (_, e) => Console.WriteLine($"正在加载 {e.ModelName}");
ModelView.ModelUnloaded += (_, e) => Console.WriteLine($"已卸载 {e.ModelName}");

using var cancellation = new CancellationTokenSource();
await ModelView.LoadModelAsync("Assets/Models/Mao", "Mao", cancellation.Token);
await ModelView.UnloadModelAsync();

IsLoading 可以绑定加载提示。ModelFit 支持 None、Uniform 和 UniformToFill；Zoom 会叠加在自动适配结果上。控件默认隐藏时暂停渲染，设置 ReleaseModelWhenHidden="True" 后还会释放模型资源，并在重新显示时自动加载。

常用控制：

ModelView.PlayMotion("Idle_0");
ModelView.PlayMotion("TapBody_0", Live2DMotionPriority.Normal);
ModelView.StopMotion();
ModelView.MotionFinished += (_, name) => Console.WriteLine($"{name} 播放完成");

ModelView.SetExpression("F01");
ModelView.ClearExpression();

ModelView.SetPosition(0.2f, -0.1f);
ModelView.SetZoom(1.5f);
ModelView.SetOpacity(0.8f);
ModelView.SetFramesPerSecond(30);
ModelView.ResetTransform();

位置、缩放、模型透明度和帧率也可以直接绑定：

<live2d:Live2DView
    PositionX="{Binding ModelX}"
    PositionY="{Binding ModelY}"
    Zoom="{Binding ModelZoom}"
    ModelOpacity="{Binding ModelOpacity}"
    FramesPerSecond="{Binding ModelFps}" />

Parameter API

foreach (Live2DParameterInfo parameter in ModelView.GetParameters())
    Console.WriteLine($"{parameter.Id}: {parameter.Value}");

ModelView.SetParameterValue("ParamAngleX", 15f);
ModelView.AddParameterValue("ParamAngleX", 5f);
ModelView.MultiplyParameterValue("ParamAngleX", 1.1f);

单次写入之后仍可能被动作修改。需要每帧固定参数时使用持续覆盖：

ModelView.SetParameterOverrides(new Dictionary<string, float>
{
    ["ParamEyeLOpen"] = 0f,
    ["ParamEyeROpen"] = 0f
});

ModelView.RemoveParameterOverride("ParamEyeLOpen");
ModelView.ClearParameterOverrides();

恢复模型默认值：

ModelView.ResetParameter("ParamAngleX");
ModelView.ResetAllParameters();

Hit Area

foreach (Live2DHitArea area in ModelView.HitAreas)
    Console.WriteLine($"{area.Name}: {area.DrawableId}");

bool hitBody = ModelView.HitTest("Body", x, y);
IReadOnlyList<Live2DHitArea> hits = ModelView.HitTestAll(x, y);

ModelView.HitAreaPressed += (_, e) =>
    Console.WriteLine(e.PrimaryHitArea.Name);

命中区域来自模型的 .model3.json。控件会处理 DPI、平移和缩放；判定范围是对应 Drawable 的顶点外接矩形，不是逐像素检测。

许可

项目代码采用 MIT License。Live2D Cubism Core 和模型文件适用 Live2D 的相关许可协议，请在发布应用前自行确认。