KerbalDialogueKit

A utility library that extends ChatterBox with programmatically-triggered dialogue scenes, branching, mid-scene choice capture, and lifecycle callbacks. Built for KSP 1.12.x mods that want character-driven interactive dialogue.

Status

Early release. v0.1.0.

Currently requires a locally-built ChatterBox from the public-api branch. Upstream PR at DymndLab/ChatterBox#1. Once merged and a new ChatterBox version ships, stock CKAN-installed ChatterBox will work. See docs/UPSTREAM.md.

Features

• Trigger dialogue scenes from code, not just from ContractConfigurator state
• Branch dialogue by flag — line variants based on visibleIf expressions
• Pause mid-scene and present 2-4 option cards; capture the player's choice
• Receive lifecycle callbacks (scene start/end, line activated, choice made)
• Queue multiple scenes; manage them via a simple static API
• Load scenes from .cfg files OR build them fluently in C#
• Per-save flag persistence so choices stick across saves/loads

Requirements

• KSP 1.12.x
• ChatterBox v1.0.0 or later with the scene rendering API public (see docs/UPSTREAM.md for PR status)

Installation

Extract so the folder structure is:

GameData/
  KerbalDialogueKit/
    KerbalDialogueKit.version
    Plugins/
      KerbalDialogueKit.dll

CKAN support is planned.

Usage — Code

using KerbalDialogueKit.Core;

var wernher = new DialogueCharacter
{
    Name = "Wernher",
    PortraitModel = "Instructor_Wernher",
    Color = "#FF82B4E8"
};
var gus = new DialogueCharacter
{
    Name = "Gus",
    PortraitModel = "Strategy_MechanicGuy",
    Color = "#FFFFC078"
};

var scene = new DialogueScene("my_directive")
    .WithTitle("The Approach Debate")
    .WithCharacter("A", wernher)
    .WithCharacter("B", gus)
    .AddLine("A", "The data is extraordinary.")
    .AddLine("B", "Heavy means expensive.")
    .AddChoice("approach",
        new DialogueChoiceOption { Value = "science", Text = "Back Wernher: Go big" },
        new DialogueChoiceOption { Value = "engineering", Text = "Back Gus: Start lean" })
    .AddLine("A", "This is most excellent!",
        visibleIf: "approach == science")
    .AddLine("B", "Smart call.",
        visibleIf: "approach == engineering")
    .OnChoiceMade((id, value) => Debug.Log($"{id}={value}"))
    .OnSceneEnd(s => Debug.Log("Done"));

DialogueKit.Enqueue(scene);

Usage — Config

Define a scene in any .cfg file inside GameData:

DIALOGUE_SCENE
{
    id = my_directive
    title = The Approach Debate

    CHARACTER
    {
        id = A
        name = Wernher
        model = Instructor_Wernher
        color = #FF82B4E8
    }
    CHARACTER
    {
        id = B
        name = Gus
        model = Strategy_MechanicGuy
        color = #FFFFC078
    }

    LINE
    {
        speaker = A
        text = The data is extraordinary.
    }
    LINE
    {
        speaker = B
        text = Heavy means expensive.
    }

    CHOICE
    {
        id = approach
        OPTION { value = science; text = Back Wernher: Go big }
        OPTION { value = engineering; text = Back Gus: Start lean }
    }

    LINE
    {
        speaker = A
        visibleIf = approach == science
        text = This is most excellent!
    }
    LINE
    {
        speaker = B
        visibleIf = approach == engineering
        text = Smart call.
    }
}

Then enqueue by id:

DialogueKit.EnqueueById("my_directive",
    new SceneCallbacks { OnChoiceMade = (id, value) => Debug.Log($"{id}={value}") });

See Examples/demo-scene.cfg for a complete example.

visibleIf Expressions

Supported operators:

• ==, !=, >, <, >=, <=
• in (value1, value2)
• &&, || with && binding tighter

Examples:

• mood == Enthusiastic
• score > 5 && completedMun == true
• mood in (Enthusiastic, Supportive)

Missing flags are treated as empty string. Numeric comparisons against non-numeric values return false silently (no crash).

Flags

Flags persist per-save via FlagScenario. Set them from code or via choice selection (a CHOICE's selected Value is automatically set as the flag named by the CHOICE's Id):

DialogueKit.Flags.Set("wernherDisposition", "Enthusiastic");
var mood = DialogueKit.Flags.Get("wernherDisposition");

Callbacks

SceneCallbacks exposes optional lifecycle hooks:

• OnSceneStart(scene) — fires when the scene opens
• OnLineActivated(lineIndex, line) — fires when each line is activated
• OnChoiceMade(choiceId, value) — fires when the player selects a choice option
• OnSceneEnd(scene) — fires when the scene closes normally
• OnSceneCancelled(scene) — fires if the scene is cancelled early

Set them via the fluent API (scene.OnChoiceMade(cb)) or pass a SceneCallbacks instance to EnqueueById.

License

MIT — see LICENSE.

Credits

Built on top of ChatterBox by DymndLab. Portrait rendering, dialogue sequencing, and audio handling remain ChatterBox's work — we extend it with the interactive layer.