API Quick Start

<aside> 💡 This article is written for developers of all experience levels. However, it may be helpful to understand the basics of the ConvoGen editor.

</aside>

Table of Contents

Introduction

<aside> 💡 Prerequisites: a sample project ready to use with the API. For a quick tutorial on how to create one, go here and follow the Project Setup and Exporting a Project sections.

</aside>

ConvoGen is a powerful dialogue editor tool that allows users to create dynamic dialogue trees for their games (and other media, too!). Its easy-to-use API can be easily integrated into projects and consumed with only a few lines of code.

While the API does not depend on any particular engine, the implementation may vary. This article details the minimum necessary steps to outputting .cvg projects in various engines.

Engines

Unity

Unity integration has two options: use the provided Unity Asset Store package (easiest and recommended), or integrate from scratch.

Option 1: Unity Asset Store Package (recommended)

Follow the instructions on the API Quick Start page to get started immediately.

Option 2: New Integration

<aside> 💡 Prerequisites: Unity and Visual Studio or VS Code installed.

</aside>

Integrating into Unity only takes a few steps.

  1. Create a new blank project.
  2. Create or use a blank scene.
  3. In the Project panel, create a new folder in Assets called ConvoGen.
  4. From the ConvoGen application folder (typically at C:\Program Files\Bungus Interactive\ConvoGen), click and drag the ConvoGen.API.dll file into the newly created ConvoGen folder in the Unity window.
  5. Right click inside the ConvoGen folder in Unity and click Create → C# Script. Call it LoadConvoGen. Double click it to open it in your text editor.

Untitled

  1. Copy the following code into the script and save:
using ConvoGen.API;
using System;
using System.Linq;
using UnityEngine;

public class LoadConvoGen : MonoBehaviour
{
    // Start is called before the first frame update
    void Start()
    {
        Debug.Log("Loading ConvoGen project...");
        
        //Load ConvoGen export data.
        var path = @"C:\\Path\\To\\My\\APIExampleExport.cvg";
        if (!System.IO.File.Exists(path)) Debug.Log("Path doesn't exist.");

        //Tell the API to initialize the project.
        var projectLoadResult = ConvoGenAPI.LoadProject(path);

        if (projectLoadResult.Success)
        {
            Debug.Log("ConvoGen project loaded successfully");
        }
        else
        {
            Debug.Log(projectLoadResult.Message);
        }

        var project = projectLoadResult.Result;

        //Output any errors or messages that occurred during load.
        foreach (var log in project.Logs.GetLogs())
        {
            Debug.Log(log.LogText);
        }

        //Enter a sequence by Id (found in the right sidebar in ConvoGen when a sequence is selected).
        Debug.Log("Entering sequence...");
        var enterSequenceResult = project.EnterSequence(Guid.Parse("af55ad69-8370-4d9e-8c1d-e07796e5266e"));

        //Since we entered the sequence, the current node is the starting node of the sequence.
        //Execute the current node.
        //This will return every dialogue until execution encounters a branch/choice that requires user input.
        //Note: this means more than one node can be executed with this call.
        Debug.Log("Executing node...");
        var nodeExecutionResult = project.ExecuteCurrentNode();

        //Output the result of the execution
        outputResult(nodeExecutionResult);
        
        //Here is where the options would be presented to the user in the application.
        //Let's assume the user wanted to pick the first option.
        var choiceToSelect = nodeExecutionResult.Choices.First();

        //Execute the current choice.
        //This sets the current node to the choice's linked node.
        project.ExecuteChoice(choiceToSelect);

        //Continue the execution.
        nodeExecutionResult = project.ExecuteCurrentNode();

        //Output again.
        outputResult(nodeExecutionResult);
    }

    private void outputResult(ConvoGen.API.Classes.NodeExecutionResult nodeExecutionResult)
    {
        //Output every dialogue from the previous execution.
        Debug.Log("Dialogue:");
        foreach (var dialogueComponent in nodeExecutionResult.Dialogues)
        {
            Debug.Log(dialogueComponent.DialogueText);
        }

        //Output the choices for the user to select.
        Debug.Log("Choices:");
        foreach (var choiceComponent in nodeExecutionResult.Choices)
        {
            Debug.Log("" + choiceComponent.ChoiceText);
        }
    }
}
  1. In the Hierarchy panel, right click → Empty. This will create an empty GameObject.
  2. Select the empty GameObject. Drag the LoadConvoGen script from the Project panel into the Inspector panel to add the script to the empty GameObject.
  3. Play the project. Check the Console panel for your project output.

Custom Engine

<aside> 💡 Prerequisites: a game or media engine in C#.

</aside>

ConvoGen works with any C# game or media engine, and does not depend on any one design philosophy. This section is for general purposes outside of the established engines.

See the full tutorial here. It is recommended that you start there to learn about basic API flow and node execution.

static void Main(string[] args)
{
    //Load ConvoGen export data.
    var path = @"C:\\Path\\To\\My\\APIExampleExport.cvg";
    if (!System.IO.File.Exists(path)) Console.WriteLine("Path doesn't exist.");

    //Tell the API to initialize the project.
    var projectLoadResult = ConvoGenAPI.LoadProject(path);

    if (projectLoadResult.Success)
    {
        Console.WriteLine("ConvoGen project loaded successfully");
    }
    else
    {
        Console.WriteLine(projectLoadResult.Message);
    }

    var project = projectLoadResult.Result;

    //Output any errors or messages that occurred during load.
    foreach (var log in project.Logs.GetLogs())
    {
        Console.WriteLine(log.LogText);
    }

    //Enter a sequence by Id (found in the right sidebar in ConvoGen when a sequence is selected).
    Console.WriteLine("Entering sequence...");
    var enterSequenceResult = project.EnterSequence(Guid.Parse("af55ad69-8370-4d9e-8c1d-e07796e5266e"));

    //Since we entered the sequence, the current node is the starting node of the sequence.
    //Execute the current node.
    //This will return every dialogue until execution encounters a branch/choice that requires user input.
    //Note: this means more than one node can be executed with this call.
    Console.WriteLine("Executing node...");
    var nodeExecutionResult = project.ExecuteCurrentNode();

    //Output the result of the execution
    outputResult(nodeExecutionResult);

    //Here is where the options would be presented to the user in the application.
    //Let's assume the user wanted to pick the first option.
    var choiceToSelect = nodeExecutionResult.Choices.First();

    //Execute the current choice.
    //This sets the current node to the choice's linked node.
    project.ExecuteChoice(choiceToSelect);

    //Continue the execution.
    nodeExecutionResult = project.ExecuteCurrentNode();

    //Output again.
    outputResult(nodeExecutionResult);

    if (nodeExecutionResult.SequenceEnded) Console.WriteLine("Sequence ended");
}

private static void outputResult(ConvoGen.API.Classes.NodeExecutionResult nodeExecutionResult)
{
    //Output every dialogue from the previous execution.
    Console.WriteLine("Dialogue:");
    foreach (var dialogueComponent in nodeExecutionResult.Dialogues)
    {
        if (dialogueComponent.Person != null)
        {
            Console.WriteLine(dialogueComponent.Person.PersonName);
        }
        Console.WriteLine(dialogueComponent.DialogueText);
    }

    //Output the choices for the user to select.
    Console.WriteLine("Choices:");
    foreach (var choiceComponent in nodeExecutionResult.Choices)
    {
        Console.WriteLine("" + choiceComponent.ChoiceText);
    }
}