灵泛引擎

主题

C# API 参考 ​

灵泛引擎的 C# API 用于编写游戏扩展逻辑、自定义场景和 UI 面板。

命名空间速查 ​

命名空间说明
LingFanEngine.Abstractions.Interfaces.Core核心接口
LingFanEngine.Abstractions.Interfaces.Scripting脚本相关
LingFanEngine.Abstractions.Interfaces.Media音频/视频
LingFanEngine.Abstractions.Interfaces.Saves存档
LingFanEngine.Abstractions.Interfaces.Entry入口层
LingFanEngine.Abstractions.Interfaces.Events事件调度
LingFanEngine.Abstractions.EngineOptions配置选项
LingFanEngine.AbstractionsStateKeys、模型
LingFanEngine.GamesStoryScript 基类
LingFanEngine.Views视图层（SceneView、DialogBox）

IGameController ​

游戏控制器，C# 端的主 API。

对话 ​

csharp
Task SayAsync(string text, string? speaker = null, string? template = null, CancellationToken ct = default);
Task ExtendDialogAsync(string append, CancellationToken ct = default);
Task WaitForClickAsync(CancellationToken ct = default);

过渡与等待 ​

csharp
Task TransitionAsync(string effect, double duration = 0.5, CancellationToken ct = default);
Task SkipableWaitAsync(double seconds, CancellationToken ct = default);
Task WaitAsync(double seconds, CancellationToken ct = default);

菜单与输入 ​

csharp
Task<int> ShowMenuAsync(string prompt, string[] options, CancellationToken ct = default);
Task<string?> InputAsync(string prompt, string[]? options = null, CancellationToken ct = default);
Task<string?> CallScreenAsync(string sceneName, CancellationToken ct = default);

导航 ​

csharp
Task NavigateAsync(string target);
Task BackAsync();
Task ForwardAsync();

NVL ​

csharp
void EnterNvl();
Task EnterNvlAsync();
void ClearNvl();
Task ClearNvlAsync();
void ExitNvl();       // 退出并清空
Task ExitNvlAsync();
bool IsNvlActive { get; }
string GetNvlText();

视频 ​

csharp
Task<bool> PlayCutsceneAsync(string path, bool skipable = true, float volume = 1.0f, CancellationToken ct = default);

时间事件 ​

csharp
void SetTimeEventAsync(
    string id,
    int hour,
    Func<Task>? callback = null,
    bool once = false,
    string[]? weekdays = null,
    int? minute = null,
    int? day = null);

void UnregisterEvent(string id);

存档 ​

csharp
void Save(string slot);
Task SaveAsync(string slot);
void Load(string slot);
Task LoadAsync(string slot);
void ClearStack();         // 清空场景堆栈
Task ClearStackAsync();

IStateContainer ​

状态容器，所有运行时状态的存储。

csharp
T? Get<T>(string key);
void Set<T>(string key, T value);
bool ContainsKey(string key);
bool Remove(string key);
IEnumerable<string> Keys { get; }
event Action<string>? ValueChanged;

点分路径 ​

csharp
_state.Set("player.gold", 100);
_state.Set("player.inventory.weapon", "剑");
var gold = _state.Get<int>("player.gold");

StoryScript ​

C# 场景基类。

csharp
public abstract class StoryScript
{
    public abstract string SceneName { get; }
    public virtual string SceneType => "game";

    protected IStateContainer? _state;
    protected ICommandPipeline? _pipeline;
    protected ISceneRegistry? _sceneRegistry;

    public abstract Task RunAsync();

    // C# API 通过 Ctrl（IGameController）调用，例如：
    //   await Ctrl.SayAsync(text, speaker);
    //   await Ctrl.NavigateAsync(target);
    //   await Ctrl.ShowMenuAsync(prompt, options);

    protected void CreateSceneCheckpoint();  // 创建回溯检查点
}

示例 ​

csharp
public class MyScene : StoryScript
{
    public override string SceneName => "cs_my_scene";

    public override async Task RunAsync()
    {
        await Ctrl.SayAsync("欢迎！", speaker: "系统");
        var choice = await Ctrl.ShowMenuAsync("选择", new[] { "A", "B" });
        if (choice == 0)
            _state.Set("story.choice", "A");
        await Ctrl.NavigateAsync("next_scene");
    }
}

ICommand / ICommandHandler ​

自定义命令系统。

定义命令 ​

csharp
public readonly record struct MyCommand(int Value) : ICommand;

处理器 ​

csharp
public class MyCommandHandler : ICommandHandler<MyCommand>, IDefaultCommandHandler
{
    public void Handle(MyCommand cmd, ICommandContext ctx)
    {
        // 处理逻辑
        ctx.State.Set("result", cmd.Value * 2);
    }
}

IDefaultCommandHandler

实现 IDefaultCommandHandler 标记接口的处理器会被引擎自动注册。如果不实现此接口，需手动注册到 ICommandDispatcher。

注册 ​

csharp
services.AddSingleton<IDefaultCommandHandler, MyCommandHandler>();

ICommandContext ​

命令处理上下文。

csharp
public interface ICommandContext
{
    IStateContainer State { get; }
    ICommandPipeline Pipeline { get; }
    ISceneRegistry? SceneRegistry { get; }
    IGameTimeService? TimeService { get; }
    // ... 其他服务
}

IDialogBox ​

自定义对话框模板接口。

csharp
public interface IDialogBox
{
    bool IsComplete { get; }
    bool IsPausedByTag { get; }
    void SetText(string text, string? speaker = null);
    void Advance(double deltaSeconds);
    void SkipToEnd();
    void Hide();
    void ResetNvlState();
    Control AsControl();
}

IDialogBoxFactory ​

csharp
public interface IDialogBoxFactory
{
    IDialogBox Create(IStateContainer state);
}

IDialogTemplateRegistry ​

csharp
public interface IDialogTemplateRegistry
{
    void Register(string name, IDialogBoxFactory factory);
    void SetDefault(string name);
    IDialogBoxFactory? Resolve(string? name);
}

LingFanEngineOptions ​

引擎配置。

csharp
public class LingFanEngineOptions
{
    public string SaveDirectory { get; set; } = "Saves";
    public string MediaDirectory { get; set; } = "Media";
    public string StoriesDirectory { get; set; } = "Stories";
    public int DesktopTargetFps { get; set; } = 120;
    public int MobileTargetFps { get; set; } = 60;
    public int WindowWidth { get; set; } = 1920;
    public int WindowHeight { get; set; } = 1080;
    public int DesignWidth { get; set; } = 1920;
    public int DesignHeight { get; set; } = 1080;
    public bool EnableTimeSystem { get; set; } = false;
    public double DefaultTextSpeed { get; set; } = 30;
    public int MaxRollbackCheckpoints { get; set; } = 100;
    public string TitleSceneName { get; set; } = "title_main";
    public bool DefaultAutoStopBgm { get; set; } = true;
    public bool DefaultAutoStopVoice { get; set; } = true;
    public bool EnableHotReload { get; set; } = true;
    public bool ShowPerformanceHud { get; set; } = true;
    public string GameVersion { get; set; } = "1.0.0";
    // 时间系统
    public double SecondsPerGameMinute { get; set; } = 1.0;
    public int TimeStartDay { get; set; } = 1;
    public int TimeStartHour { get; set; } = 0;
    public int TimeStartMinute { get; set; } = 0;
}

DI 注册 ​

csharp
public static IServiceCollection AddLingFanEngine(this IServiceCollection services)
{
    services.AddSingleton<IUIThreadDispatcher, AvaloniaUIThreadDispatcher>();
    services.AddSingleton<IAssetAccessor, AvaloniaAssetAccessor>();
    services.AddSingleton<IAsyncWaitService, AsyncWaitService>();
    services.AddSingleton<IEncryptionKeyProvider, NullEncryptionKeyProvider>();
    services.AddSingleton<IEncryptedFileReader, EncryptedFileReader>();
    // ...
    return services;
}

IGameTimeService ​

游戏时间服务，管理游戏内时间推进。

csharp
public interface IGameTimeService
{
    long TotalMinutes { get; }       // 当前游戏总分钟数
    int CurrentDay { get; }          // 当前天数（从 TimeStartDay 开始）
    int CurrentHour { get; }         // 当前小时（0~23）
    int CurrentMinute { get; }       // 当前分钟（0~59）
    DayOfWeek DayOfWeek { get; }     // 星期几（7 天循环）
    bool IsPaused { get; }           // 是否暂停
    float TimeScale { get; set; }    // 时间缩放系数

    void Pause();                    // 暂停时间推进
    void Resume();                   // 恢复时间推进
    void SkipTime(int minutes);      // 跳过指定分钟数
    void Reset();                    // 重置到起始时间

    event Action<GameTimeEventArgs>? OnTimeAdvanced;  // 每 Tick 触发
}

配置

时间系统通过 LingFanEngineOptions.EnableTimeSystem = true 启用。 SecondsPerGameMinute 控制 1 现实秒 = N 游戏分钟（默认 1.0）。

StateKeys ​

常用状态键常量。

键说明
Dialog.Text当前对话框文本
Dialog.Speaker当前说话者
Dialog.Clickable对话框可点击
Dialog.Complete对话完成标记
Dialog.Template当前模板名
Nvl.ActiveNVL 模式激活
Scene.Name当前场景名
Scene.Type当前场景类型
Performance.Fps当前 FPS
Skip.ActiveSkip 模式
Auto.ActiveAuto 模式

IEncryptionKeyProvider ​

csharp
public interface IEncryptionKeyProvider
{
    byte[]? GetKey();  // null = 开发期无加密
}

IEncryptedFileReader ​

csharp
public interface IEncryptedFileReader
{
    Task<byte[]> ReadAllBytesAsync(string path);
    Task<string> ReadAllTextAsync(string path);
    Stream OpenRead(string path);
    bool IsEncrypted(string path);
    Task<bool> TryDecryptToFile(string path, string tempPath);
    void ReleaseTempFile(string tempPath);
}

基于 .NET 10 + Avalonia 12 · Apache-2.0 License

Copyright © 2026 灵泛引擎