快速入门

安装

TypeScript

npm install @lsde/dialog-engine

C#

dotnet add package LsdeDialogEngine

# JSON loader — choose ONE based on your platform:
dotnet add package LsdeDialogEngine.Newtonsoft        # Unity
dotnet add package LsdeDialogEngine.SystemTextJson    # .NET 5+ / Godot .NET

C++ (CMake)

# Add as a git submodule
git submodule add https://github.com/jonlepage/LS-Dialog-Editor-Engine.git deps/lsde

# CMakeLists.txt
add_subdirectory(deps/lsde/lsde-cpp)
target_link_libraries(your_target PRIVATE lsde)

Unreal Engine

# Copy the headers and source into your project
# e.g. Source/YourModule/ThirdParty/lsde/

cp -r lsde-cpp/include/lsde  YourProject/Source/YourModule/ThirdParty/lsde/include
cp -r lsde-cpp/src/*          YourProject/Source/YourModule/ThirdParty/lsde/src

# In your module's .Build.cs, add:
# PublicIncludePaths.Add(Path.Combine(ModuleDirectory, "ThirdParty/lsde/include"));
# Add the .cpp files from ThirdParty/lsde/src/ to your module

GDScript

# Clone the repository
git clone https://github.com/jonlepage/LS-Dialog-Editor-Engine.git

# Copy the addon into the Godot project
mkdir -p addons
cp -r LS-Dialog-Editor-Engine/lsde-gdscript/addons/lsde addons/lsde
rm -rf LS-Dialog-Editor-Engine

基本用法

engine 是一个图遍历机器 — 它将 block 分发给已注册的 handler，由 handler 赋予其意义。没有 handler 的话，engine 不会产生任何输出。

格式无关

engine 接收 BlueprintExport 对象，而非文件。您可以使用平台适配的解析器从 JSON、XML 或 YAML 加载蓝图。请参阅解析与导入。

TypeScript

import { DialogueEngine } from '@lsde/dialog-engine';
import blueprintJson from './blueprint.json';

const engine = new DialogueEngine();
engine.init({ data: blueprintJson });

// Unified condition resolver — evaluates game-state conditions for both
// choice visibility and condition block pre-evaluation.
engine.onResolveCondition((cond) => game.evaluateCondition(cond));

// 3 required handlers — bridge between the engine and your game
// (onCondition is optional when onResolveCondition is installed)
engine.onDialog(({ scene, block, context, next }) => {
  game
    .createDialogAuto(block, context)
    .catch(() => scene.cancel())
    .finally(() => next());
});

engine.onChoice(({ scene, block, context, next }) => {
  game
    .createChoiceAuto(block, context)
    .catch(() => scene.cancel())
    .finally(() => next());
});

engine.onAction(({ block, context, next }) => {
  game
    .executeActions(block.actions)
    .catch((err) => context.reject(err))
    .finally(() => next());
});

// Start a scene anywhere in your game code
function myGameScript(sceneId: string) {
  const scene = engine.scene(sceneId);
  scene.start();
}

C#

using LsdeDialogEngine;
using LsdeDialogEngine.Json; // LsdeDialogEngine.SystemTextJson package
// Unity: use LsdeDialogEngine.Newtonsoft instead

var blueprint = LsdeJson.Parse(File.ReadAllText("blueprint.json"));
var engine = new DialogueEngine();
engine.Init(new InitOptions { Data = blueprint });

// Unified condition resolver — evaluates game-state conditions for both
// choice visibility and condition block pre-evaluation.
engine.OnResolveCondition(cond => Game.EvaluateCondition(cond));

// 3 required handlers — bridge between the engine and your game
engine.OnDialog(args => {
    var (scene, block, context, next) = args;
    Game.ShowDialog(block, context, onComplete: next);
});

engine.OnChoice(args => {
    var (scene, block, context, next) = args;
    Game.ShowChoices(block, context, onSelected: next);
});

engine.OnAction(args => {
    var (scene, block, context, next) = args;
    Game.ExecuteActions(block.Actions);
    context.Resolve();
    next();
});

// Start a scene anywhere in your game code
void MyGameScript(string sceneId) {
    var scene = engine.Scene(sceneId);
    scene.Start();
}

C++

#include <lsde/engine.h>

using namespace lsde;

DialogueEngine engine;
engine.init({blueprint});

// Unified condition resolver — evaluates game-state conditions for both
// choice visibility and condition block pre-evaluation.
engine.onResolveCondition([](const ExportCondition& cond) {
    return game->evaluateCondition(cond);
});

// 3 required handlers — bridge between the engine and your game
engine.onDialog([](auto* scene, auto* block, auto* ctx, auto next) -> CleanupFn {
    game->showDialog(block, ctx, [next]() { next(); });
    return {};
});

engine.onChoice([](auto* scene, auto* block, auto* ctx, auto next) -> CleanupFn {
    game->showChoices(block, ctx, [next]() { next(); });
    return {};
});

engine.onAction([](auto*, auto* block, auto* ctx, auto next) -> CleanupFn {
    game->executeActions(block->actions);
    ctx->resolve();
    next();
    return {};
});

// Start a scene anywhere in your game code
auto scene = engine.scene(sceneId);
scene->start();

GDScript

var engine = LsdeDialogueEngine.new()
engine.init({"data": blueprint})

# Unified condition resolver — evaluates game-state conditions for both
# choice visibility and condition block pre-evaluation.
engine.on_resolve_condition(func(cond):
    return game.evaluate_condition(cond)
)

# 3 required handlers — bridge between the engine and your game
engine.on_dialog(func(args):
    await game.show_dialog(args["block"], args["context"])
    args["next"].call()
)

engine.on_choice(func(args):
    await game.show_choices(args["block"], args["context"])
    args["next"].call()
)

engine.on_action(func(args):
    game.execute_actions(args["block"].actions)
    args["context"].resolve()
    args["next"].call()
)

# Start a scene anywhere in your game code
func my_game_script(scene_id: String):
    var scene = engine.scene(scene_id)
    scene.start()

Blueprint 验证

engine.init() 返回包含错误、警告和统计信息的诊断报告。check 选项可与宿主应用程序的功能进行交叉验证：

TypeScript

engine.init({
  data,
  check: {
    signatures: ['set_flag', 'play_sound'],
    dictionaries: { items: ['sword', 'shield'] },
    characters: ['Alice', 'Bob'],
  },
});

C#

engine.Init(new InitOptions {
    Data = blueprint,
    Check = new CheckOptions {
        Signatures = new() { "set_flag", "play_sound" },
        Dictionaries = new() { ["items"] = new() { "sword", "shield" } },
        Characters = new() { "Alice", "Bob" },
    },
});

C++

engine.init({
    blueprint,
    CheckOptions{
        .signatures = {"set_flag", "play_sound"},
        .dictionaries = {{"items", {"sword", "shield"}}},
        .characters = {"Alice", "Bob"},
    },
});

GDScript

engine.init({
    "data": blueprint,
    "check": {
        "signatures": ["set_flag", "play_sound"],
        "dictionaries": {"items": ["sword", "shield"]},
        "characters": ["Alice", "Bob"],
    },
})