はじめに

インストール

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 がなければ、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"],
    },
})