Creating custom tokens

Tokens are bits of text that get replaced with something useful when written inside Label menu elements and speech text. For example, the [var:2] token will be replaced with the value of the Global Variable with an ID number of 2. As of Adventure Creator v1.48, it's possible to create our own tokens using some very simple functions. This tutorial assumes basic programming knowledge.

In this tutorial, we'll use tokens to display the current page number, and the total number of pages, of a Journal. A tutorial covering the creation of a Journal can be found here.

Let's imagine our Journal element is simply named Journal, and it's placed within a Menu name Diary. We want to create a label underneath that reads something like Page 2 of 5. We'll set the two numbers using tokens - so our "tokenised" string take the form:

Page [token:0] of [token:1]

Where [token:0] will represent the current page number, and [token:1] will represent the total number of pages, in our Journal.

First, let's create the Label element that will display this string. In the Menu Manager, select the Diary Menu (or equivalent), and create a new Label element. Name this element PageNumbers, and set the Label text as follows:

We now need to create these tokens in a script, so that they can be replaced during gameplay. Create a new C# script, and insert using AC; at the top so that we can make use of Adventure Creator's functions:

using UnityEngine;
using System.Collections;
using AC;

public class JournalPageNumbers : MonoBehaviour
{
	
}

Remove the Start () function, since we only need the Update () function, which we'll use to update the tokens every frame. We'll begin this function by creating a variable reference to our Journal element, which is a MenuJournal class. Of course, we could store this as a private variable outside the function, but we'll just keep it in Update() for simplicity.

MenuJournal menuJournal = (MenuJournal) PlayerMenus.GetElementWithName ("Diary", "Journal");

Here, we've used the PlayerMenus script's GetElementWithName function to get the MenuElement of the name Journal, within the Menu named Diary. We've then cast it to the MenuJournal subclass. This function can be found here within the scripting guide.

The MenuJournal class, as documented here in the scripting guide, has some functions that we'll use to get the current page number, and total page numbers, respectively:

GetCurrentPageNumber ()
GetTotalNumberOfPages ()

We'll use these functions to assign the values of our two custom tokens, 0 and 1. We assign tokens using the RuntimeVariables script's SetCustomToken function:

KickStarter.runtimeVariables.SetCustomToken (0, menuJournal.GetCurrentPageNumber ().ToString ());
KickStarter.runtimeVariables.SetCustomToken (1, menuJournal.GetTotalNumberOfPages ().ToString ());

And that's it! Our Label element will now be amended as we intended when the game runs:

Custom tokens will be stored automatically in saved games. This feature is especially useful, because the text in the Label element is independent of the game's language, so this will work for any translation we may create.

The finished script is as follows:

using UnityEngine;
using System.Collections;
using AC;

public class JournalPageNumbers : MonoBehaviour
{

	void Update ()
	{
		MenuJournal menuJournal = (MenuJournal) PlayerMenus.GetElementWithName ("Diary", "Journal");
		KickStarter.runtimeVariables.SetCustomToken (0, menuJournal.GetCurrentPageNumber ().ToString ());
		KickStarter.runtimeVariables.SetCustomToken (1, menuJournal.GetTotalNumberOfPages ().ToString ());
	}
}