CsvSpreadsheetInterchange

Review draft. This source page has not completed website editorial and release-specific verification.

# Dialogue Director CSV bundle interchange (V1)

CSV is a writer-facing, update-only projection over an exact canonical typed document. JSON remains the lossless interchange authority and the only format for full-fidelity structures. The CSV layer does not mutate assets or contain a second native application path.

Workflow and bundle

The editor flow selects one current supported asset, then uses the native directory picker to export or import a bundle. The backend flow is:

native asset -> typed detached document -> canonical JSON -> CSV bundle -> edited CSV -> patch a copy of the current typed document -> existing semantic validation -> existing application API

A bundle contains manifest.json, document.json, and exactly the projection files declared for its canonical document type. The current C++ API represents each file as exact UTF-8 bytes in FDialogueCsvBundle::Files. Editor import is UpdateExisting only; create and clone modes are JSON-only. Successful import leaves the asset dirty for the normal Unreal save workflow. .xlsx is not supported.

document.json is the deterministic canonical UTF-8 JSON base used to produce the CSVs. Writers edit projection CSVs, not document.json. The manifest is control metadata and does not duplicate narrative fields.

The manifest schema is DialogueDirector.CsvBundle, version 1, with these fields:

• schema, schemaVersion
• documentSchema, documentSchemaVersion
• baseDocumentSha256
• projections, an array of { projectionId, fileName, projectionVersion }

Each projection version is 1. The document schema and version are the existing canonical typed-document schema and version. Import verifies the bundled document bytes against SHA-256, canonicalizes the caller’s current typed document with the existing JSON writer, and requires the current hash to equal baseDocumentSha256. A mismatch is STALE_BASE; a malformed or tampered bundle is INVALID_BUNDLE. There is no three-way merge and the bundled old JSON is never applied over current project state.

The Win64 Editor implementation computes SHA-256 through the Windows CNG system API. bcrypt.lib and the CNG calls are Windows-only; non-Windows targets compile the Editor module but CSV export or bundle verification returns the structured HASH_FAILURE diagnostic because this version has no non-Windows SHA-256 provider. This limitation applies to CSV bundle hashing only; it does not make the Dialogue Director plugin Windows-only. The engine Core generic SHA-256 function is not a fallback: its base implementation asserts when no platform implementation exists.

Identity, rows, and patch behavior

StableIds bind CSV rows only within the exact hash-pinned document.json. GUIDs remain in JSON. Import resolves each StableId against the current typed document, verifies required read-only context columns, and preserves the matched GUID. It never generates identities or rebinds a StableId to a different GUID.

Fixed structural rows must all appear exactly once. CSV cannot create or delete participant roles, nodes, line/interjection text records, choice options, DialogueSet entries, or LineDelivery TextId rows. The only complete child-table snapshots that may add or remove rows are LineDelivery format arguments and culture timing overrides.

OptionOrder, EntryOrder, and ArgumentOrder are explicit zero-based semantic order values. Physical CSV row order has no semantic meaning. Choice and Set order values must form a complete contiguous sequence for their parent/document. Culture override order is not semantic; reconstruction and projection export use ordinal lexical culture ordering.

Every import parses and validates all declared files, patches a copy, and returns it only after existing typed and semantic validation succeeds. The caller’s input document and native assets remain unchanged on failure. Editor import applies the patched document through the existing UpdateExisting importer. No automatic save or three-way merge occurs. See DataInterchangeTooling.md for the user workflow.

Projection files

The header spelling and case below are exact. Header cells may be physically reordered on input; exported headers use the listed order. Missing, duplicate, wrong-case, or unknown headers fail. Undeclared files, missing declared files, duplicate projection identifiers, and duplicate filenames fail.

DialogueDefinition

Projection ID	File	Exact headers	Editable	Read-only/context
DialogueDefinition.Participants	participants.csv	RoleId, RoleName	RoleName	RoleId
DialogueDefinition.Nodes	nodes.csv	NodeId, NodeType, DeveloperNodeName	DeveloperNodeName	NodeId, NodeType
DialogueDefinition.DialogueText	dialogue_text.csv	RecordType, NodeId, TextId, SpeakerRoleId, SourceText	SourceText	RecordType, NodeId, TextId, SpeakerRoleId
DialogueDefinition.Choices	choices.csv	NodeId, OptionId, OptionOrder, Label, TextId, SourceText	OptionOrder, Label, SourceText	NodeId, OptionId, TextId

The DialogueDefinition text projection includes existing Line and Interjection records. Choice order is reconstructed from OptionOrder, never physical row order. Participant asset references remain in JSON. Format arguments on Definition Line, Interjection, and Choice text remain in JSON and are preserved when source text is edited; incompatible text is rejected by existing semantic validation.

Connections and routing; Conditions and clauses; provider payloads; skill/check structures; retries; Actions (including Skill XP payloads); Events; RandomBranch; SubDialogue; presentation; authoring state; asset bindings; and structural creation/deletion remain JSON-only. This includes Skill Gate, Definition SkillComparison, all D20 policy-intent fields, D100 Roll-Over checks, Numeric Skill/World State Bias fields, and both Skill XP operations. The participant CSV’s RoleId/RoleName columns are general participant context; participant GUIDs and Skill consumers’ role references remain in canonical JSON. No Skill payload or Action field is projected to CSV.

The bundle’s document.json is the authoritative immutable base for those values. Import requires both a valid document digest and that the canonicalized current document still has the manifest’s SHA-256 base hash. Supported CSV edits patch a copy of that current document, preserving non-projected Skill semantics byte-for-byte at the canonical base. A stale bundle is rejected (STALE_BASE); failed or unsupported edits do not return partial state. D20 ProjectDefault is never converted to Normal. CSV adds no Action or Skill columns in V1.

DialogueSet

Projection ID	File	Exact headers	Editable	Read-only/context
DialogueSet.Entries	entries.csv	EntryId, EntryOrder, TargetType, TargetAssetPath, Priority, Weight, HasCondition	EntryOrder, Priority, Weight	EntryId, TargetType, TargetAssetPath, HasCondition

EntryOrder reconstructs the complete Set entry order. Set root identity and SelectionPolicy, targets, and embedded Conditions remain canonical JSON context; target asset paths and condition presence are verified as read-only columns.

LineDelivery

Projection ID	File	Exact headers	Editable	Read-only/context
LineDelivery.Rows	delivery.csv	TextId, DeliveryMode, WrittenText, CaptionText, VoiceAssetPath, CaptionStartOffsetSeconds, CaptionDisplayDurationSeconds, CaptionEndHoldSeconds	DeliveryMode, WrittenText, CaptionText, VoiceAssetPath, and all three timing fields	TextId
LineDelivery.FormatArguments	delivery_format_arguments.csv	TextId, Surface, ArgumentOrder, Name, Type, SourceKey	All columns; this is a complete child snapshot	None
LineDelivery.CultureTiming	delivery_culture_timing.csv	TextId, Culture, StartOffsetSeconds, DisplayDurationSeconds, EndHoldSeconds	All columns; this is a complete child snapshot	None

Surface tokens are exactly Written or Caption; Type tokens are exactly Text, Integer, or Float. TextId + Surface + exact-case Name identifies a format argument, so Name and name may coexist when valid. TextId + Culture identifies a culture override. Culture identifiers are accepted and validated by the existing Unreal culture contract without importer normalization.

An empty VoiceAssetPath clears the optional soft reference; a nonempty value is a soft asset path and native application preflight checks its type. Voice-only or combined delivery mode and timing constraints continue to be checked by existing validators/application preflight.

CSV dialect and cells

Export is UTF-8 without BOM, comma-delimited, and uses CRLF record endings. Fields are quoted when required; quotes inside quoted fields are doubled. Commas, quotes, embedded CR/LF, Unicode, and leading/trailing authored spaces are preserved. Import accepts UTF-8 with or without one leading BOM, LF or CRLF records, and properly quoted multiline cells. Malformed quoting fails with structured diagnostics.

There is no unchanged, null, delete, or inherit sentinel. Every projection is a complete snapshot of its projected fixed records. An empty editable text cell is exactly the empty string. An empty optional voice path means unset. Required identities, enums, numeric cells, and context cells cannot be empty. Omitting a fixed row is an error, not deletion. Non-projected fields are preserved from the hash-bound current typed document.

Diagnostics contain projection ID, filename, 1-based logical row where available, header/column, resolved StableId where available, code, message, and severity. Import reports structured errors such as STALE_BASE, INVALID_BUNDLE, UNKNOWN_HEADER, MISSING_IDENTITY, CONTEXT_MISMATCH, and semantic validation codes.

CSV does not implement translation output or PO workflows and is not a translation authority. Unreal Localization owns PO operations; DialogueDefinition readiness guidance is in Localization.md. .xlsx and NAS integration are not implemented.