LsdeDialogEngine 0.3.0

LSDE Dialog Engine — C#

C# runtime for Unity (2021+) and .NET Standard 2.1. Zero external dependencies.

Port of the TypeScript reference implementation. Validated against the same 42 cross-language JSON test specifications. The engine is a pure .NET Standard 2.1 library with no NuGet dependencies — drop it into Unity or any .NET project.

Installation

# Core engine
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

Unity (alternative)

Copy the src/LsdeDialogEngine/ folder into your Unity project's Assets/Plugins/ directory. Install com.unity.nuget.newtonsoft-json via Unity Package Manager for JSON parsing.

Quick Start

using LsdeDialogEngine;
using LsdeDialogEngine.Json; // or LsdeDialogEngine.Newtonsoft for Unity

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

engine.SetLocale("en");

// Character resolver (optional — default: first character in list)
engine.OnResolveCharacter(chars => chars.Count > 0 ? chars[0] : null);

// Unified condition resolver — handles choice visibility + condition block pre-evaluation.
// choice: conditions are handled internally by the engine via choice history.
engine.OnResolveCondition(cond => GameState.Evaluate(cond));

// ─── 4 Required Handlers ────────────────────────────────────────

engine.OnDialog(args => {
    var text = LsdeUtils.GetLocalizedText(args.Block.DialogueText);
    var ch = args.Context.Character;
    Debug.Log($"{ch?.Name ?? "???"}: {text ?? "—"}");
    args.Next();
    return null; // or return a cleanup Action
});

engine.OnChoice(args => {
    var visible = args.Context.Choices
        .Where(c => c.Visible != false)
        .ToList();
    args.Context.SelectChoice(visible[0].Uuid);
    args.Next();
    return null;
});

// onCondition is OPTIONAL when OnResolveCondition is installed.
// The engine pre-evaluates condition groups and auto-routes.
// Add it only for logging, UI, or custom override logic.
engine.OnCondition(args => {
    var groups = args.Context.ConditionGroups!;
    var matched = groups.Where(g => g.Result == true).Select(g => g.PortIndex).ToList();
    var isDispatcher = args.Block.NativeProperties?.EnableDispatcher == true;
    object result = isDispatcher ? (object)matched : (object)(matched.Count > 0 ? matched[0] : -1);
    args.Context.Resolve(result);
    args.Next();
    return null;
});

engine.OnAction(args => {
    foreach (var a in args.Block.Actions)
        Debug.Log($"Action: {a.ActionId}");
    args.Context.Resolve();
    args.Next();
    return null;
});

// ─── Run ─────────────────────────────────────────────────────────

var handle = engine.Scene("scene-uuid");
handle.Start();

Unity Integration

In Unity, store the next callback and trigger it from your UI events:

engine.OnDialog(args => {
    dialogueUI.SetText(args.Context.Character?.Name,
                       LsdeUtils.GetLocalizedText(args.Block.DialogueText));
    dialogueUI.Show();

    // Store next — triggered by UI button click
    _pendingNext = args.Next;

    return () => dialogueUI.Hide(); // cleanup
});

// Called from your UI button
public void OnContinueClicked() {
    _pendingNext?.Invoke();
    _pendingNext = null;
}

Scripts

Project Structure

src/LsdeDialogEngine/       # Engine library (netstandard2.1, zero dependencies)
├── Types.cs                 # All types, interfaces, delegates
├── DialogueEngine.cs        # Public facade
├── SceneHandle.cs           # Traversal loop + AsyncTrack
├── HandlerRegistry.cs       # Two-tier handler resolution
├── PortResolver.cs          # Output port routing
├── BlockContext.cs           # Context factories
├── ConditionEvaluator.cs    # AND/OR chain evaluation
├── Graph.cs                 # Scene + Blueprint indexing
├── Validator.cs             # Blueprint validation
└── Utils.cs                 # Type checks, helpers

tests/LsdeDialogEngine.Tests/  # xUnit test runner
samples/MiniRuntime/            # Console playground

API Overview

Engine Lifecycle

Handler Registration (Tier 1 — Global)

All 4 type handlers are required — the engine will throw if a scene starts without them.

Optional Handlers

Scene Handle (Tier 2 — Per-Scene)

Handler Pattern

Every handler receives a typed args object and may return a cleanup Action:

engine.OnDialog(args => {
    // Display dialogue...
    args.Next(); // Advance to next block

    return () => {
        // Called when leaving this block (cleanup)
    };
});

Utilities (LsdeUtils)

Cross-Language Conformance

42 shared JSON tests across all runtimes: 42/42 passing.

License

Proprietary — distributed under the LSDE license.