Ink

Table of Contents

The Dialogue System can tie into Inkle's Ink Integration for Unity.

Ink copyright © Inkle Studios.

About Ink Integration

Ink is a narrative scripting language created by Inkle Studios. You can read about Ink here:

https://www.inklestudios.com/ink/

Unlike the other third party file formats that use the Dialogue System's in-editor converter tools to create dialogue databases, when working with Ink the Dialogue System uses Ink as the engine that parses Ink files and runs them. Your Ink files can use the Dialogue System's ShowAlert and quest control functions, and the Dialogue System can get and set Ink global variable values.

Example Scene

The example scene lets you play two conversations.

  • "story" is a version of the Ink-Unity integration's example story with these additions:
    • External Functions to interface with the Dialogue System.
    • Actor Tags to disambiguate some lines.
    • A variable "wagerAmount" that gets set during the story. You can set a watch on this variable in the Dialogue Editor if you want to see it change.
  • "TheIntercept" is a copy of Inkle's sample story for Ink.

Ink Setup

  1. Import Inkle's Ink Integration for Unity. You can get it here: https://www.assetstore.unity3d.com/en/#!/content/60055
  2. Add a Dialogue System Ink Integration component to the Dialogue Manager.
  3. Assign your Ink stories (JSON files) to the component's Ink JSON Assets list. These stories will be added to the Dialogue System's runtime environment when the component starts. To add additional stories at runtime (e.g., user content, or downloaded from a server), use the DialogueSystemInkIntegration.AddStory(title, json) method.
  4. If you want to start each Ink story from the beginning each time you play it, tick Reset State On Conversation Start.
  5. To include the states of the Ink stories in the Dialogue System's save data, tick Include In Save Data.
  6. Create a dialogue database, which can be empty, and assign it to the Dialogue Manager. This will silence the Dialogue System's warning about no database being assigned. The Dialogue System Ink Integration component will create another database at runtime and add it to the Dialogue System's runtime environment.

You may want to add the following to the database:

  • Actor 1: "Player" - the player actor used in response menus.
  • Actor 2: "Story" - the default actor used in subtitles.
  • Actor 3: "Player Speaker" - the player actor when used in subtitles.
  • Quests, if your game has any.

How to Start Conversations

You can use all of the Dialogue System's regular triggers, scripting API calls, and visual scripting actions to start Ink stories as conversations.

Since the stories are added at runtime, you'll need to enter their names manually in Conversation Triggers' Conversation title field. Or, if you prefer, you can create a dummy database containing empty conversations with the same titles as your stories, assign this database to your Conversation Trigger, and select the conversation from the dropdown menu. (Don't add this dummy database to the Dialogue Manager.)

Special Content in Ink Files

Actor Tags

For any given line, to specify the actor (speaker) or conversant (listener), use Actor=actorName and/or Conversant=actorName tags. For example, to make the actor Boromir speak a line to the conversant Elrond:

- One does not simply walk into Mordor. # Actor=Boromir # Conversant=Elrond

External Functions

To make Dialogue System functions available to your Ink story, the Dialogue System integration will automatically add these external function definitions to the top of your Ink file at runtime:

EXTERNAL ShowAlert(x)                 // ShowAlert("message")
EXTERNAL CurrentQuestState(x)         // CurrentQuestState("quest")
EXTERNAL CurrentQuestEntryState(x,y)  // CurrentQuestEntryState("quest", entry#)
EXTERNAL SetQuestState(x,y)           // SetQuestState("quest", "inactive|active|success|failure")
EXTERNAL SetQuestEntryState(x,y,z)    // SetQuestEntryState("quest", entry#, "inactive|active|success|failure")

You may also want to add these fallback functions at the bottom of your file so you can test your story outside of the Dialogue System:

<pre>// Fallback functions

== function ShowAlert(x) == ~ return 1

== function CurrentQuestState(x) == ~ return "inactive"

== function CurrentQuestEntryState(x,y) == ~ return "inactive"

== function SetQuestState(x,y) == ~ return 1

== function SetQuestEntryState(x,y,z) == ~ return 1

Lua Functions

These functions are available in the Dialogue System's Lua environment:

Function Description Example
SetInkBool("variable", value) Sets a Boolean value in your Ink stories. SetInkBool("teacup", true)
SetInkNumber("variable", value) Sets a number value in your Ink stories. SetInkNumber("wagerAmount", 16000)
SetInkString("variable", "value") Sets a string value in your Ink stories. SetInkString("surname", "Shortshanks")

<< Dialogue Database Converters >>