Parsing & import

Vue d'ensemble

Le engine est agnostique du format — engine.init({ data }) reçoit un objet BlueprintExport désérialisé, pas un fichier ni une string brute. Le engine ne lit jamais de fichiers et n'a aucune dépendance sur une librairie de sérialisation.

L'éditeur LSDE exporte les blueprints en plusieurs formats :

Format	Graphe complet?	Usage
JSON	Oui	Par défaut — support le plus large sur toutes les plateformes
XML	Oui	Pipelines XML, outils de localisation (XLIFF), systèmes legacy
YAML	Oui	Édition humaine, diffs git lisibles, workflows config-driven
CSV	Non (plat)	Localisation / traduction — export vers Excel ou Google Sheets

Le CSV exporte un tableau plat de textes par locale. Il ne contient pas de connections, conditions ni actions — il ne peut pas être utilisé avec le runtime engine.

Parseurs recommandés

Platform	JSON	XML	YAML
Unity	Newtonsoft.Json (com.unity.nuget.newtonsoft-json)	System.Xml (native)	not recommended
Unreal Engine	FJsonSerializer (native module Json)	XmlParser (native)	UnrealYAML (marketplace)
Godot	JSON.parse_string() (native)	XMLParser (native)	godot-yaml (GDExtension)
TypeScript	JSON.parse() (native)	fast-xml-parser	yaml
CSharp	System.Text.Json (.NET 5+) / Newtonsoft.Json	System.Xml (native)	YamlDotNet
CPP	nlohmann/json (header-only)	tinyxml2 / pugixml	yaml-cpp

Unity

JSON — LsdeDialogEngine.Newtonsoft

// Install: dotnet add package LsdeDialogEngine.Newtonsoft
// Unity Package Manager: com.unity.nuget.newtonsoft-json (auto-pulled)
using LsdeDialogEngine;
using LsdeDialogEngine.Newtonsoft;

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

JSON — manual Newtonsoft

// Without companion package — manual converter setup
using Newtonsoft.Json;
using LsdeDialogEngine;

var json = File.ReadAllText("blueprint.json");
var settings = new JsonSerializerSettings();
settings.Converters.Add(new BlueprintBlockNewtonsoftConverter()); // see Polymorphic Dispatch
var blueprint = JsonConvert.DeserializeObject<BlueprintExport>(json, settings);
engine.Init(new InitOptions { Data = blueprint });

XML — System.Xml

// System.Xml is native — nothing to install
using System.Xml.Linq;
using LsdeDialogEngine;

var doc = XDocument.Load("blueprint.xml");
// Manual mapping from XElement → BlueprintExport required.
// See polymorphic dispatch section below for BlueprintBlock handling.

Unreal Engine

JSON — FJsonSerializer (native)

#include "Json.h"
#include <lsde/engine.h>

FString JsonStr;
FFileHelper::LoadFileToString(JsonStr, TEXT("blueprint.json"));

TSharedPtr<FJsonObject> JsonObject;
auto Reader = TJsonReaderFactory<>::Create(JsonStr);
FJsonSerializer::Deserialize(Reader, JsonObject);

// Map FJsonObject → BlueprintExport manually.
// Dispatch on block "type" field for polymorphism.

XML — XmlParser (native)

#include "XmlParser.h"

FXmlFile XmlFile(TEXT("blueprint.xml"));
auto* Root = XmlFile.GetRootNode();
// Walk XML nodes → map to BlueprintExport.

Godot

JSON (native)

var file = FileAccess.open("res://blueprint.json", FileAccess.READ)
var data = JSON.parse_string(file.get_as_text())
file.close()

engine.init({"data": data})
# No polymorphism issues — GDScript uses dynamic Dictionaries.

XML — XMLParser (native)

var parser = XMLParser.new()
parser.open("res://blueprint.xml")
# Walk parser events → build Dictionary matching BlueprintExport structure.
# See Godot docs: XMLParser class reference.

TypeScript (TS/JS)

JSON — import (bundler)

// Bundlers (Vite, Webpack, esbuild) auto-parse .json imports.
import blueprintJson from './blueprint.json';
engine.init({ data: blueprintJson });

JSON — manual

const json = fs.readFileSync('./blueprint.json', 'utf-8');
engine.init({ data: JSON.parse(json) });
// No polymorphism issues — JS objects are dynamically typed.

XML — fast-xml-parser

// npm install fast-xml-parser
import { XMLParser } from 'fast-xml-parser';
const xml = fs.readFileSync('./blueprint.xml', 'utf-8');
const parser = new XMLParser({ ignoreAttributes: false });
const data = parser.parse(xml);
engine.init({ data });

YAML — yaml

// npm install yaml
import { parse } from 'yaml';
const yml = fs.readFileSync('./blueprint.yaml', 'utf-8');
engine.init({ data: parse(yml) });

CSharp (C#)

JSON — LsdeDialogEngine.SystemTextJson

// Install: dotnet add package LsdeDialogEngine.SystemTextJson
using LsdeDialogEngine;
using LsdeDialogEngine.Json;

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

JSON — manual System.Text.Json

// Without companion package — manual converter setup
using System.Text.Json;
using System.Text.Json.Serialization;
using LsdeDialogEngine;

var json = File.ReadAllText("blueprint.json");
var options = new JsonSerializerOptions {
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    Converters = {
        new JsonStringEnumConverter(),
        new BlueprintBlockConverter(),       // see Polymorphic Dispatch
        new BlockPropertyValueConverter(),
    },
};
var blueprint = JsonSerializer.Deserialize<BlueprintExport>(json, options);
engine.Init(new InitOptions { Data = blueprint });

XML — System.Xml (native)

// System.Xml is included in .NET — nothing to install.
using System.Xml.Linq;
using LsdeDialogEngine;

var doc = XDocument.Load("blueprint.xml");
// Manual mapping from XElement → BlueprintExport required.

YAML — YamlDotNet

// dotnet add package YamlDotNet
using YamlDotNet.Serialization;
using LsdeDialogEngine;

var yaml = File.ReadAllText("blueprint.yaml");
var deserializer = new DeserializerBuilder().Build();
// YamlDotNet requires custom type converters for polymorphic blocks.

CPP (C++)

JSON — lsde/json_loader.h

// Include the optional JSON loader (requires nlohmann/json)
#include <lsde/json_loader.h>

auto blueprint = lsde::LsdeJson::parseFile("blueprint.json");
// or from string:
// auto blueprint = lsde::LsdeJson::parse(jsonString);
engine.init({blueprint});

JSON — manual nlohmann/json

// Without json_loader.h — manual polymorphic dispatch
#include <nlohmann/json.hpp>
#include <lsde/engine.h>

std::ifstream f("blueprint.json");
auto j = nlohmann::json::parse(f);
auto blueprint = j.get<lsde::BlueprintExport>();
// Requires custom from_json — see polymorphic dispatch below.

XML — tinyxml2

#include <tinyxml2.h>
tinyxml2::XMLDocument doc;
doc.LoadFile("blueprint.xml");
// Walk XML elements → map to BlueprintExport.

YAML — yaml-cpp

// Install: apt install libyaml-cpp-dev (or include source)
#include <yaml-cpp/yaml.h>
auto node = YAML::LoadFile("blueprint.yaml");
// Requires custom YAML::convert specializations.

Dispatch polymorphe

BlueprintScene.blocks est un tableau de BlueprintBlock — une union discriminée avec 5 sous-types identifiés par le champ type :

type	Sous-type	Champs spécifiques
DIALOG	DialogBlock	dialogueText, content, structureKey
CHOICE	ChoiceBlock	choices
CONDITION	ConditionBlock	conditions
ACTION	ActionBlock	actions
NOTE	NoteBlock	(aucun)

Les langages dynamiques (TypeScript, GDScript) gèrent ça automatiquement — les objets parsés contiennent déjà tous les champs.

Les langages typés (C#, C++) ont besoin d'un converter custom qui lit le champ type et construit le bon sous-type. Sans ça, les champs spécifiques comme dialogueText ou choices sont silencieusement perdus.

Packages compagnons

Si vous utilisez LsdeDialogEngine.Newtonsoft ou LsdeDialogEngine.SystemTextJson, ces converters sont déjà inclus — appelez simplement LsdeJson.Parse(json). Le code ci-dessous est pour l'intégration manuelle uniquement.

CSharp — Newtonsoft.Json (Unity)

using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using LsdeDialogEngine;

class BlueprintBlockNewtonsoftConverter : JsonConverter<BlueprintBlock>
{
    public override BlueprintBlock ReadJson(JsonReader reader, Type objectType,
        BlueprintBlock existingValue, bool hasExistingValue, JsonSerializer serializer)
    {
        var obj = JObject.Load(reader);
        var type = obj["type"]?.ToString();
        BlueprintBlock block = type switch
        {
            "DIALOG"    => new DialogBlock(),
            "CHOICE"    => new ChoiceBlock(),
            "CONDITION" => new ConditionBlock(),
            "ACTION"    => new ActionBlock(),
            "NOTE"      => new NoteBlock(),
            _           => throw new JsonException($"Unknown block type: {type}")
        };
        serializer.Populate(obj.CreateReader(), block);
        return block;
    }

    public override void WriteJson(JsonWriter writer, BlueprintBlock value, JsonSerializer serializer)
        => serializer.Serialize(writer, value, value.GetType());
}

CSharp — System.Text.Json (.NET 5+)

using System.Text.Json;
using System.Text.Json.Serialization;
using LsdeDialogEngine;

class BlueprintBlockConverter : JsonConverter<BlueprintBlock>
{
    public override BlueprintBlock Read(ref Utf8JsonReader reader, Type typeToConvert,
        JsonSerializerOptions options)
    {
        using var doc = JsonDocument.ParseValue(ref reader);
        var root = doc.RootElement;
        var type = root.GetProperty("type").GetString();
        var json = root.GetRawText();
        return type switch
        {
            "DIALOG"    => JsonSerializer.Deserialize<DialogBlock>(json, options)!,
            "CHOICE"    => JsonSerializer.Deserialize<ChoiceBlock>(json, options)!,
            "CONDITION" => JsonSerializer.Deserialize<ConditionBlock>(json, options)!,
            "ACTION"    => JsonSerializer.Deserialize<ActionBlock>(json, options)!,
            "NOTE"      => JsonSerializer.Deserialize<NoteBlock>(json, options)!,
            _           => throw new JsonException($"Unknown block type: {type}")
        };
    }

    public override void Write(Utf8JsonWriter writer, BlueprintBlock value,
        JsonSerializerOptions options)
        => JsonSerializer.Serialize(writer, value, value.GetType(), options);
}

class BlockPropertyValueConverter : JsonConverter<object>
{
    public override object Read(ref Utf8JsonReader reader, Type typeToConvert,
        JsonSerializerOptions options)
    {
        return reader.TokenType switch
        {
            JsonTokenType.String => reader.GetString(),
            JsonTokenType.Number => reader.TryGetInt64(out var l) ? (object)(double)l : reader.GetDouble(),
            JsonTokenType.True   => true,
            JsonTokenType.False  => false,
            JsonTokenType.Null   => null,
            _                    => throw new JsonException($"Unexpected token {reader.TokenType}")
        };
    }

    public override void Write(Utf8JsonWriter writer, object value, JsonSerializerOptions options)
        => JsonSerializer.Serialize(writer, value, options);
}

CPP — nlohmann/json

#include <nlohmann/json.hpp>
#include <lsde/types.h>

void from_json(const nlohmann::json& j, std::unique_ptr<lsde::BlueprintBlock>& block) {
    auto type = j.at("type").get<std::string>();
    if      (type == "DIALOG")    block = std::make_unique<lsde::DialogBlock>();
    else if (type == "CHOICE")    block = std::make_unique<lsde::ChoiceBlock>();
    else if (type == "CONDITION") block = std::make_unique<lsde::ConditionBlock>();
    else if (type == "ACTION")    block = std::make_unique<lsde::ActionBlock>();
    else if (type == "NOTE")      block = std::make_unique<lsde::NoteBlock>();
    else throw std::runtime_error("Unknown block type: " + type);
    j.get_to(*block);
}