articy:draft Importer for Unity – Tutorial Lesson 1

Hello and welcome to the articy:draft Importer for Unity tutorial series.

This series contains 7 lessons that you can either view as videos or read as blog posts with texts and helpful screenshots. Simply click play on the video or scroll down to dive in:

The Goal of this Series

During this series we will take a look at how to access imported articy data within Unity with the goal of displaying branching dialogue.

The articy:draft Importer for Unity takes care of getting all the data you want from articy into the game engine. Within Unity the ArticyFlowPlayer component does a lot of heavy lifting in the background and takes care of the flow traversal, among other things. However, which data to access and how to display that data in our project is totally on us, that means that some C# coding will be required!

This is where this tutorial series comes in. We will start out with a small Unity project and step by step update it to a point where we can trigger and display the branching dialogue we imported from articy. Depending on your personal project you then can go with the same approach or at least use it as a basis you can modify to fit your needs. The articy to Unity workflow we are going to set up will make life easier for writers and designers, as they can work in articy, but within moments can see and test changes in the Unity project.

This lesson

In this first lesson we will take a look at our Unity project and get the articy Importer for Unity from the asset store and install it. Then we will switch to articy:draft to have a quick look at the project on that end, followed by exporting the articy data to Unity. Back in Unity we will make sure that our data is ready to use by doing a quick check with the included Debug Flow Player.

Overview of Unity demo scene

Okay, let’s get right to it. There is one scene in this Unity project. At the time of the recording I am working with a Unity 2020.3 LTS Version. We keep the project as simple as possible to not distract from its main focus – to show how the implementation of the articy Importer works.

In a small game area we have a controllable player character and two NPCs. The player can move around and talk to the NPCs by pressing Space when in their proximity. You can download this small demo project plus the articy project if you want to follow along, or play around in it. You will find two zipped Unity projects in the download, one is the base version, which can be used to follow the course and the other one is the final version, which is the completely finished project as it will look like at the end of this series.

using UnityEngine;
using UnityEngine.SceneManagement;

public class PlayerController : MonoBehaviour
{
    private string dialogue;
    private string speaker;

    private float speed = 15f;
    private bool isNearNPC = false;

    private Rigidbody playerRB;
    private DialogueManager dialogueManager;
 
    void Start()
    {
        playerRB = gameObject.GetComponent<Rigidbody>();
        dialogueManager = FindObjectOfType<DialogueManager>();
    }

    void Update()
    {
        PlayerInteraction();
    }

    private void FixedUpdate()
    {
        PlayerMovement();
    }

    // Simple player movement
    void PlayerMovement()
    {
        // Remove movement control while in dialogue
        if (dialogueManager.DialogueActive)
            return;

        playerRB.velocity = new Vector3(Input.GetAxis("Horizontal") * speed, 0, Input.GetAxis("Vertical") * speed);
    }

    // All interactions and key inputs player can use
    void PlayerInteraction()
    {
        // Key option to start dialogue when near NPC
        if (Input.GetKeyDown(KeyCode.Space) && isNearNPC)
        {
            dialogueManager.StartDialogue(dialogue, speaker);
        }

        // Key option to abort dialogue
        if (dialogueManager.DialogueActive && Input.GetKeyDown(KeyCode.Escape))
        {
            dialogueManager.CloseDialogueBox();
        }

        // Key option to reset entire scene
        if (Input.GetKeyDown(KeyCode.R))
        {
            RestartScene();
        }
    }

    // Simple scene restart for testing purposes
    void RestartScene()
    {
        SceneManager.LoadScene(SceneManager.GetActiveScene().name);
    }

    // Trigger Enter/Exit used to determine if interaction with NPC is possible
    void OnTriggerEnter(Collider aOther)
    {
        isNearNPC = true;

        // get dialogue line and speaker name from triggered object
        dialogue = aOther.GetComponent<DialogueHolder>().dialogueLine;
        speaker = aOther.GetComponent<DialogueHolder>().speakerName;
    }

    void OnTriggerExit(Collider aOther)
    {
        isNearNPC = false;
    }
}

On the player character there is a PlayerController script, which takes care of movement and interactions.

using UnityEngine;

public class DialogueHolder : MonoBehaviour
{
    //Just for dialogue testing purposes
    public string dialogueLine;
    public string speakerName;
}

The NPCs have a DialogueHolder script on them, which is just for simulating dialogue at this stage.

On the Canvas we have the Dialogue Widget with a box for text and two buttons. We can display text, but the buttons are without function at the moment, as the entire widget is supposed to be connected to and combined with articy functionality later anyways.

using System.Collections.Generic;
using UnityEngine;
using UnityEngine.UI;

public class DialogueManager : MonoBehaviour
{
    [Header("UI")]
    // Reference to Dialog UI
    [SerializeField]
    GameObject dialogueWidget;
    // Reference to dialogue text
    [SerializeField]
    Text dialogueText;
    // Reference to speaker
    [SerializeField]
    Text dialogueSpeaker;

    // To check if we are currently showing the dialog ui interface
    public bool DialogueActive { get; set; }

    void Start()
    {
        
    }
    
    public void StartDialogue(string aDialogueLine, string aSpeaker)
    {
        DialogueActive = true;
        dialogueWidget.SetActive(DialogueActive);       
        
        dialogueText.text = aDialogueLine;
        dialogueSpeaker.text = aSpeaker;
    }

    public void CloseDialogueBox()
    {
        DialogueActive = false;
        dialogueWidget.SetActive(DialogueActive);        
    }
}

Last but not least we have a Dialogue Manager game object with a DialogueManager script on it. In here we will spend a lot of time in the coming tutorial parts.

Download and installation of Importer for Unity

First order of business is to install the articy:draft Importer for Unity, which we can get from the Asset Store. For free, of course! Search for articy:draft or use this link to jump to the Importer right away. Click the Add to my Assets button. If you then click Open in Unity we will directly go to the Package Manager.

Alternatively you can open it from selecting Window in the Unity menu bar and then selecting Package Manager. Make sure to have My Assets selected from the Drop-down menu, then look for the articy:draft Importer in the list. Now you can download and then import the package. I already have the package on my computer, this is why it goes straight to import for me. In case a patch comes out for the importer and there is a new version, you also get the option to update here. For the import window, leave everything checked and click Import.

We now have an Articy Importer folder in our Assets, but before we continue with that we will switch over to articy:draft for a moment.

The articy:draft project

This is the articy project with the dialogues we want to bring over to Unity. Two final dialogues and two small test dialogues we will use for the step by step implementation of our dialogue system in the game.

All dialogues are set up in a way that we use Dialogue nodes as containers, and Dialogue Fragments for the entire dialogue content. Plus some organizational elements like hubs, jumps, or condition nodes.

How do we get all this over and into Unity? That’s really easy: Select Export from the Main Menu and choose Unity. We will use the default export ruleset, which will export the entire project. Totally fine for our little demo scene. With the help of rulesets you can customize your export, for example if you don’t want to export all data types, or in a bigger project want to divide up the export to multiple packages to make it easier to load them during runtime. If you are interested to learn more about rulesets, you can learn more about them in the Help Center. All we need to do for our export is to specify the export folder, which needs to be the asset folder of the Unity project or a subfolder of it.

articy data in Unity

The data is automatically imported to Unity. You can also trigger the import manually by selecting Tools from the menu bar, articy:draft Importer and then Import articy:draft export file. As the import needs to compile code, errors somewhere else in the project might lead to a failure of the automatic import. In that case you can trigger a manual import after fixing any errors.

As a side note: At some point a Gizmos folder will appear in your Assets. It belongs to the Articy Importer. We don’t need to do anything with it, I just wanted to mention it in case you are like me and wonder if things suddenly appear.
Now, let’s do a quick check to verify if everything went okay with the import: Tools, articy:draft Importer and Show database panel. All the data is here!

In the Articy Importer folder under Helper then Prefabs, we find an ArticyDebugFlowPlayer. It’s like the name suggests mainly for debugging purposes, but we can use it to get a first glimpse of our dialogue data here in Unity. It works only with a Canvas, so we drag the ArticyDebugFlowPlayer over in the hierarchy and add it to our Canvas object.

Now all that’s left to do is to select the Debug Flow Player game object in the hierarchy and scroll to the ArticyFlowPlayer component in the Inspector. Here we need to select an object to start on, then we can hit Play.
We are able to traverse through the dialogue we have seen earlier in articy. Isn’t that something?

Next lesson

In the next lesson we will start laying the foundation to be able to display a dialogue from articy in our own custom dialogue UI.

See you there!

GO TO LESSON 2

Useful links:

articy:draft project + Unity demo project
Get the articy:draft importer for Unity in the asset store
articy:draft 3 export rulesets

Don’t have articy:draft 3 yet? Get the free version now!
Get articy:draft 3 FREE
*No payment information required

Follow us on Twitter, Facebook and LinkedIn, or visit our articy Reddit to keep yourself up to date and informed.