Hello and welcome to the articy:draft X Importer for Unity tutorial series.
The Goal of this Series
During this 5-part 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 X Importer for Unity takes care of getting the data from articy into the game engine.
Within Unity specialized components like the Articy Flow Player do a lot of heavy lifting in the background and take 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 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.
Download demo projects
In this first lesson we will take a look at the demo projects this series is based on. Then we will install the articy Importer for Unity and export the content from articy:draft X and import it into Unity, so we can use it in the upcoming lessons.
Download the articy:draft X project as well as the Unity 6 project for this series right here:
The Unity project exists in two stages. The START version is the base Unity project, without anything articy related yet. It is meant to follow this series hands on, step by step, until we arrive at the end with the finished project. The FINAL project version is how the project will look like at the end of the series.
Unity project
The first time you open the project, you need to go to the Scenes folder (1) and open the included scene (2), to see the base content we prepared.
We kept the project relatively simple to not distract from its main focus – to show how the implementation of the articy Importer works.
In Play Mode, we can walk the player character around in the scene and interact with the NPCs. Interacting opens up a dialogue UI. The buttons are not functional at this stage, we will implement functionality together with displaying narrative content during this series. You can use “Esc” to close the dialogue UI or “R” to restart the scene.
Let’s look at some objects, that will be important in the coming lessons, in more detail:
Dialogue Manager
The DialogueManager game object (3) holds the DialogueManager.cs script (4), which is responsible for handling everything around dialogue in our project.
Currently, it’s just starting and ending dialogues by displaying or hiding the UI element, but we’ll be expanding on this very soon.
DialogueManager.cs
using TMPro;
using Unity.Cinemachine;
using UnityEngine;
public class DialogueManager : MonoBehaviour
{
[Header(“UI”)]
// Reference to Dialogue UI
[SerializeField]
private GameObject dialogueWidget;
// Reference to Dialogue text
[SerializeField]
private TMP_Text dialogueText;
// Reference to speaker
[SerializeField]
private TMP_Text dialogueSpeaker;
[Header(“Cameras”)]
[SerializeField]
private CinemachineCamera movementCam;
[SerializeField]
private CinemachineCamera dialogueCam;
private InteractPrompt prompt;
// To check if we are currently showing the Dialogue UI interface
public bool DialogueActive { get; set; }
private void Awake()
{
//Default camera setting
movementCam.enabled = true;
dialogueCam.enabled = false;
}
private void Start()
{
}
public void StartDialogue(InteractPrompt aPrompt)
{
DialogueActive = true;
dialogueWidget.SetActive(DialogueActive);
movementCam.enabled = false;
dialogueCam.enabled = true;
prompt = aPrompt;
prompt.ShowInteractPrompt(false);
}
public void EndDialogue()
{
DialogueActive = false;
dialogueWidget.SetActive(DialogueActive);
movementCam.enabled = true;
dialogueCam.enabled = false;
if (prompt != null)
{
prompt.ShowInteractPrompt(true);
}
}
}
Player
The Player game object (5) holds the PlayerController.cs script (6), which takes care of player movement and animation.
In addition, it is also responsible for player interaction options, which is a part of the script we will be updating during this series.
PlayerController.cs
using UnityEngine;
using UnityEngine.SceneManagement;
public class PlayerController : MonoBehaviour
{
[SerializeField]
private int speed;
[SerializeField]
private Animator animator;
[SerializeField]
private SpriteRenderer playerSprite;
private PlayerControls playerControls;
private Rigidbody rb;
private DialogueManager dialogueManager;
private Vector3 movement;
private InteractPrompt interactPrompt;
private bool isNearNPC = false;
//Animation Control
private const string IS_WALKING_PARAM = “IsWalking”;
private const string IS_DIALOGUE_PARAM = “IsDialogue”;
//Tags
private const string IS_NPC_TAG = “NPC”;
private void Awake()
{
playerControls = new PlayerControls();
}
private void OnEnable()
{
playerControls.Player.Enable();
}
private void Start()
{
rb = GetComponent<Rigidbody>();
dialogueManager = FindFirstObjectByType<DialogueManager>();
}
void Update()
{
GetPlayerPosition();
AnimationControl();
PlayerInteractions();
}
private void FixedUpdate()
{
MovePlayer();
}
private void GetPlayerPosition()
{
float x = playerControls.Player.Move.ReadValue<Vector2>().x;
float z = playerControls.Player.Move.ReadValue<Vector2>().y;
movement = new Vector3(x, 0, z).normalized;
SpriteDirection(x);
}
private void MovePlayer()
{
// Remove movement control from player while in dialogue
if (dialogueManager.DialogueActive)
return;
rb.MovePosition(transform.position + movement * speed * Time.fixedDeltaTime);
}
private void PlayerInteractions()
{
if (playerControls.Player.Interact.WasPerformedThisFrame() && isNearNPC)
{
dialogueManager.StartDialogue(interactPrompt);
}
// Debug functionality to easy get out of a dialogue and restart the scene
if (playerControls.Player.Quit.WasPerformedThisFrame() && dialogueManager.DialogueActive)
{
dialogueManager.EndDialogue();
}
if (playerControls.Player.Restart.WasPerformedThisFrame())
{
RestartScene();
}
}
private void AnimationControl()
{
//Idle to Walking
animator.SetBool(IS_WALKING_PARAM, movement != Vector3.zero);
//Idle to still when in dialogue
animator.SetBool(IS_DIALOGUE_PARAM, dialogueManager.DialogueActive);
}
private void SpriteDirection(float x)
{
if (x != 0 && x < 0)
{
playerSprite.flipX = true;
}
if (x != 0 && x > 0)
{
playerSprite.flipX = false;
}
}
private void OnTriggerEnter(Collider aOther)
{
if (aOther.CompareTag(IS_NPC_TAG))
{
interactPrompt = aOther.GetComponent<InteractPrompt>();
if (interactPrompt != null)
{
interactPrompt.ShowInteractPrompt(true);
isNearNPC = true;
}
}
}
private void OnTriggerExit(Collider aOther)
{
if (aOther.CompareTag(IS_NPC_TAG))
{
isNearNPC = false;
if (aOther.GetComponent<InteractPrompt>() != null)
{
interactPrompt.ShowInteractPrompt(false);
}
}
}
private void RestartScene()
{
playerControls.Player.Disable();
SceneManager.LoadScene(SceneManager.GetActiveScene().name);
}
}
NPC 1 and NPC 2
The NPC game objects (7) are instantiated from the NPC prefab (8). We will touch this when it comes to assigning dialogue data.
Dialogue Widget
Our Canvas (9) holds our Dialogue Widget (10), which consists of the entire dialogue UI. We have a box with space for speaker name and the actual dialogue line, plus room for buttons, which will be used to navigate through a dialogue.
All other objects and scripts in this base project are not important for the scope of this series, as we do not need to touch any of them to integrate functionality necessary for the articy Importer for Unity.
articy:draft X project
articy:draft is used to write all narrative content we want for our project and keep it organized.
In this little demo project, we find three objects on the top Flow layer. A Flow Fragment, which has two test dialogues nested inside, and two Dialogue nodes, with the dialogue we want to display within the Unity project at the end of this series. All dialogues are set up in a way that Dialogue nodes are used as containers, and Dialogue Fragments for the entire dialogue content.
In the final dialogues we also find some organizational elements like Hubs (11), a Jump (12), or a Condition node (13).
Localization
articy:draft X has a localization feature set and the Importer for Unity can make use of that. We won’t cover localization in this beginner series, but we will set up the Unity project in a way that localization can be included at a later stage without immense effort. Even if you do not plan to have your project available in multiple languages, there is no downside of using this approach.
There is one thing we need to check in articy:draft and if applicable properly set up: The Localization settings.
Go to Settings in the Navigator (14) and select the Localization tab (15). Set a primary project language here (16), which usually will be the same as the main language of the Unity project.
The second important task to do here in the Settings is to select all properties that are supposed to be localized. Or in general, the properties that are supposed to be displayed in Unity, even if no localization is planned. For Dialogue Fragments (17), we need the Text property, as well as MenuText checked for localized text.
Don’t worry, these settings can still be changed at later stages, in case you notice that other properties are supposed to be localized / displayed, or if you would like to add voice-over in addition to the text.
articy Importer for Unity
Okay, we have a Unity project with our little demo game scene and an articy project with the narrative content. But how do we get the narrative content from articy into Unity? This is where the articy Importer for Unity comes into play.
The most convenient way to get the articy Importer is at the Unity Asset Store. In case you search the store, make sure to get the current articy:draft X Importer version, as the old articy:draft 3 version is also still available.
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 access the Package Manager via the Asset Store dropdown in the toolbar, then My Assets (18), or by selecting Window in the Unity menu bar and then selecting My Assets (19) from there.
Make sure to have My Assets selected from the Drop-down menu (20), then look for the articy:draft X Importer in the list (21). Now you can download and then import the package (22). For the import window, leave everything checked and click Import (23).
If a new version of the importer is released, you also get the option to update here.
After importing the package, we now have an ArticyImporter folder in our Assets.
Exporting articy:draft data
Now it is time to get the actual data from articy:draft over to Unity.
From articy’s main menu select Export (24), then Unity from the options list on the left (25).
We can leave all settings on their default state, for the scope of this tutorial series.
If you’d like to learn more, for example about Rulesets (26), which allow for the customization of exports, for example if you do not 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, click here.
All that is left to do is to select the export path (27). This needs to point to the Unity project’s asset folder, or a subfolder of it. I will use the Assets folder.
Imported data in Unity
The exported articy data will automatically be imported into Unity. If Unity is currently open it will happen when you switch back to the engine, if Unity is closed the process will run the next time you open the Unity project.
In case there is ever an issue with the automatic import, you can trigger a manual import via Tools -> articy:draft Importer -> Import articy:draft export file.
We can find the articy export file in the folder we selected when exporting.
For a quick check to see if all data was properly imported we again go to Tools -> articy:draft Importer and now select Show database panel.
By default, this will open in a tab next to the Inspector. Here we can see all objects that were imported, which are indeed our dialogues from articy:draft. All right, we are in business.
Next lesson
In the next lesson, we will start accessing this data. See you there!
Useful links:
Project files for this series
Get the articy:draft X Importer for Unity in the asset store
Help Center: articy:draft X export rulesets
Don’t have articy:draft X yet? Get the free version now!
Get articy:draft X FREE
*No Payment information required
Follow us on Twitter, Facebook and LinkedIn to keep yourself up to date and informed. To exchange ideas and interact with other articy:draft users, join our community on discord.