Text Extensions

To use global variables inside your scripts you just need to use the namespace and variable name.

[(Namespace).(Variable)]

Examples:

"Hello [Session.PlayerName], you still only have [Inventory.goldCount]g left."

You can easily access objects and their properties and templates. The general structure when accessing an object is:

[(ID/TechnicalName)<(instanceId)>.(Properties)...]

Depending on the text owner object, you also have access to 2 convenience identifier to access an object. $Self and $Speaker. The later only works on DialogueFragments but both are object references and can be used accordingly.

Examples:

"[Chr_Manfred.DisplayName]"

"[Chr_Manfred.Character.BackgroundStory]"

"[0x01000001000010C6.Text]"

"Sorry, but i only have [$Speaker.Inventory.Gold]g left."

"[MainCharacter.Character.Companion.Character.HP]"

"[Guard<15>.NPC.HP]"

"I don't talk to a filthy [[DialogueState.Counterpart].Basic.Class]"

"My first item in my Inventory is [Chr_Main.Inventory.ReferenceStrip<0>.DisplayName]"

You can access meta information about your articy:draft types, utilizing the type system. This can be useful if you want for example to create your UI texts with information from your templates.

To access a type where you know the type or template name, like DialogueLine, FlowFragment or Character.

[$Type.(ClassName).(Properties)...]

or alternatively if you want to access the type of an object instance

[(ObjectSource).$Type.(Properties)...]

Examples:

"[$Type.Character.Attributes.Strength.DisplayName]: [[Session.PlayerCharacter].Attributes.Strength]/([$Type.Character.Attributes.Strength.MaxValue])"

For even more complex use cases you can use methods as a source. A method can take any number of parameters and always returns a string. Methods are mostly for your special use cases and custom sources as you see later, but there are some built-in methods that you can use out of the box:

if and not methods

Sometimes you need to add or change text in a text depending on another token. To do that, you can use the if and not methods. For example:

"Hello, how are you[if([Player.IsWearingPoliceUniform], ", Officer", "")]?"

Notice how the first token calls a method called if, passing in 3 parameters: The first parameter is another token, in this case a global variable, checking if the player is wearing the Police Uniform. The second parameter is the string to insert into the text, when the first parameter resolves to true, so if the player is wearing the police uniform, the text ", Officer" is added to the string. The third parameter is therefore what would be added, when the first parameter is false.

The [not()] method works the same, but switches the second and third parameters.

When accessing a script property found on a template, you have 2 ways to use it inside your text. You could either execute the script or using the actual script content inside your scripts

"The script text is: [Something.Feature.ScriptProperty]"

Without brackets, the script property is treated the same as RawScript and returns the script as text.

If you want to execute the script you just add brackets at the end of the script property

"The script value is: [Something.Feature.ScriptProperty()]"

Now the script is executed and, in the case of a condition, a boolean is returned. If the script is an instruction, nothing is returned and nothing is added in its place.

You can use any of the available Resolve methods to access the text resolver.

string output = ArticyTextExtension.Resolve("Hi, [Chr_Manfred]");
Debug.Log(output); // output: "Hi, Manfred"

An additional feature available when using the ArticyTextExtension class is, to have the option in adding additional parameters. This works almost exactly like String.Format

if(playerGold < Shop.SelectedItem.ShopInfo.Cost) 
{
    string output = ArticyTextExtension.Resolve("Sorry but you still need {0}g to buy this [Shop.SelectedItem].", Shop.SelectedItem.ShopInfo.Cost - playerGold);
    // output: "Sorry but you still need 24g to buy this Sword."
}

Here is a more advanced way when you use parameters inside tokens.

int playerCount = 4;

// Global variables
Session.Player1 = "Bob";
Session.Player2 = "Anna";
Session.Player3 = "Jack";
Session.Player4 = "Sue";

// iterating over all players
for(int i = 0; i < playerCount; i++)
{
    string output = ArticyTextExtension.Resolve("Hello, [Session.Player{0}]", i + 1);
    // ...
}

// Output:
// "Hello, Bob"
// "Hello, Anna"
// "Hello, Jack"
// "Hello, Sue"

Similar to how you can use parameters to insert into tokens, you can of course also nest tokens to create a similar effect

Session.CurrentPlayerIndex = 2;

string output = ArticyTextExtension.Resolve("[Session.Player[Session.CurrentPlayerIndex]], its your turn!");

// Output:
// "Anna, its your turn!"

Note
While difficult to show in examples the text extension always make sure to check if any value needs to be localized before using it in any part of the resolving. If you pass a loca key into the Resolve method it will also first be localized before the actually resolving begins.

Unless otherwise set in the plugin settings, the plugin will automatically resolve the string for all articy:draft object properties like DisplayName, SpokenText etc.. But sometimes it is necessary to get the unresolved string for manual resolving especially when you want to insert parameters. To do that, you can access the UnresolvedValue of an ArticyString.

var obj = ArticyDatabase.GetObject<Character>("Chr_MainCharacter");
ArticyTextExtension.Resolve(obj, obj.DisplayName.UnresolvedValue);

If the available sources aren't enough, you can register custom methods to use inside your texts. To do that, you first register your custom method

// define the custom method anywhere in your code (doesn't have to be static, but be wary of memory leaks)
static string GetCurrentTime(ArticyTextToken token, string[] args)
{
    return DateTime.Now.ToString();
}

// Register once to the text extension
ArticyTextExtension.AddUserMethod(GetCurrentTime);

The current time is [GetCurrentTime()].

You can also add method arguments. These can be literal texts, other tokens and even other method calls.

The current time is [GetCurrentTime(\"now\", [GetCurrentLocale()])].

When you look at the example above, the parameters passed into the GetCurrentTime method can be accessed via the string array.

If you need even greater flexibility in how the text extension resolves your string, you can use the ResolveAdvance(FuncArticyTextToken, String, String, Object) method. Note this is an advanced use cases and therefore rather complex in its setup.

Generally speaking, you supply a callback that is called when the plugin resolves your string for each token, gives you information said token and expects a string as a result. This is useful if you want the maximum flexibility when it comes to parsing and creating your strings.