Hello and welcome to this articy:draft X scripting tutorial.
Interactivity helps to make a narrative story really come to life. We can achieve interactivity by creating a branching story flow within articy:draft. We navigate through this flow by player choices, but also through an underlying system of story logic.
To facilitate this story logic, articy:draft comes with its own expression language called articy:expresso. It gives you the means to shape your story flow with conditions and instructions, which make use of global variables and template properties.
Generally speaking, instructions are used to modify variable or property values, and conditions perform checks for these values and control the game flow by that.
This tutorial will set its focus on accessing template properties. If you are entirely new to scripting in articy, I’d recommend to check out the scripting lesson in the articy:draft X Basics series. That lesson covers scripting with global variables, to handle often used scenarios like checking if a character has a certain item in their inventory or to track which location a character visited or if they already spoke to a certain NPC.
Template properties
One of articy’s core features is the template system. With the help of custom templates, you can assign project specific properties to almost any kind of object.
You can find more info about how to create and use templates overall in the Basics series and the Help Center.
For this tutorial, we use a template on Entities and we are going to access and modify its properties for the player character in the Flow.
Global variables vs template properties
A question that comes up often is when to use global variables and when to use template properties? As is often the case in articy:draft, there are no definite rules or a right/wrong answer.
Global variables are easy to set up and use. They feature auto-complete and type check. However, they don’t offer all data types that can be covered by properties, and it can get a bit hard to keep track if the amount of used variable gets very high.
Template properties provide additional data types, like enumerations, and shine when a certain value is going to be needed multiple times. However, they require more effort to set up initially and they do not come with auto-complete or a type check. And please note that not all properties can be accessed and modified via expresso. The greatest benefit comes within the game engine.
As a rule of thumb, look at the data in question and determine what data type is needed and how often this data is going to be used.
For example, if we only want to track the wealth of one player character and using whole numbers is sufficient for that, just use an integer global variable. In a case, where we also need to track how much money each NPC has, it will be more elegant to use a number property, because instead of having to create a unique global variable for each and every character in the game, we create a number property and add it to a template. That template then gets assigned to all characters we want to track.
Please note that not all properties can be accessed and modified via expresso. The greatest benefit comes within the game engine.
Accessing property values
In the articy:draft project, we have a single dialogue with multiple examples of how to access and change template property values.
(View in full resolution)
The playable character Phoenix has a template Playable Character assigned (1), which consists of two features: Attributes (2) and Wallet (3).
The Attributes feature has four number properties, for the attributes each playable character shares: Strength, Agility, Intelligence, and Morale (4). These have a minimum value of one, a max value of ten, and are populated with one as a default value (5).
The Wallet feature consists of a single number property Money (6), with a minimum of zero, a maximum of one million and a default value of one hundred (7).
These properties we are going to access in the dialogue to control the story flow with conditions and instructions.
The first time happens in a condition node, where we want to check the player’s morale. If the morale value is too high, the NPC Shady Pete doesn’t trust the player and some extra effort is necessary to remedy that.
To check for a variable value, the process for the scripting expression is to get the variable set and the variable in question, and then use a relational operator to compare it to something to evaluate if the expression returns true or false.
<Variable Set>.<Variable> <Relational Operator> <Value> GameState.HasSolvedMasterRiddle == true
The way to access a template property is similar in the broad sense that we need to access a feature and then get to one of its properties, comparable to having a variable set and access one if its variables. However, the whole process works in a different manner, as we also need to specify an object that has a template with the feature in question.
For properties, we use the built-in function getProp. It might look complex at first glance, but the structure is always the same, so you can always come back to the following examples or refer to the scripting Help Center article, until setting up these expressions becomes second nature.
To get a property via getProp, we first need to get a specific object with getObj and then pick one of its properties.
The structure looks as follows:
getProp(getObj(“TechnicalName”), “FeatureName.PropertyName”)
If you start writing the function name in a condition node or input pin, articy assists you by displaying the required structure.
The technical name (8) of our player character can be found by selecting the object in the Navigator (9) and then choosing the General tab (10).
That gives us getProp(getObj(“Char_Phoenix”), for the first part of the expression.
Now, switch to the Template tab of the Phoenix entity. Here we can see that the Playable Character template is assigned (11), with two features, Attributes and Wallet. If you are sure that your technical and display names are identical, you can grab the info from here, however to be 100% safe, let’s just click the Edit feature button for Attributes (12) to jump directly to the feature.
In the window that pops up, click the Morale property in the layout area (13). On the right side, feature and property parameters are shown. Here, we can now verify the correct technical names for feature (14) and selected property (15).
Please note that there is neither auto-complete nor type check for the arguments you enter. In case the condition behaves not as expected in a simulation or throws an exception in the game engine, please check if there might be a typo somewhere.
That means the complete getProp expression is getProp(getObj(“Char_Phoenix”), “Attributes. Morale”). What is missing is the relational operator and the value we want to compare against.
getProp(getObj(“Char_Phoenix”), “Attributes.Morale”) < 5
If the morale value of the player character is less than five, Shady Pete feels a connection to the player. If the player has a high morale value, Shady Pete is less accommodating and will have additional demands for the player later.
A bit further along the dialogue we arrive at another point where we use a check for an Attribute property in a condition. This time we check for the Strength property. Depending on the value, the conversation is supposed to follow different branches.
getProp(getObj(“Char_Phoenix”), “Attributes.Strength”) < 4
However, this time the conditions are placed in the input pins of Dialogue Fragments, that means we are able to use the speaker identifier instead of getting the object.
getProp(speaker, "Attributes.Strength") <4
The speaker identifier gets the assigned speaker of this Dialogue Fragment as the source for the property. As Dialogue Fragments are the only node type with a speaker, it goes without saying that the speaker identifier can only be used in combination with a Dialogue Fragment.
For the next branch option, we want to check if the character’s strength is between four and nine. To achieve this, we can employ another built-in method: isPropInRange.
To get the object, we again can substitute with the speaker identifier, then we specify the property, and lastly the range. The values we enter for min and max are inclusive.
isPropInRange(speaker, "Attributes.Strength", 4, 9)
The last two branches are for characters with a very high Strength value of above nine. But not only that, we combine it with a check if they carry a specific item in their inventory – here simulated by a simple Boolean variable.
This case is to demonstrate that although a condition in articy:draft needs to be a single Boolean expression that evaluates to true or false, you can of course use logical operators to concatenate comparisons.
The first of these options will be selected if the character has a Strength greater than nine, but does not have the necessary item.
getProp(speaker, "Attributes.Strength") > 9 && !Inventory.FoeBlaster
The last branch is valid, if in addition to a high Strength, the character has the item as well.
getProp(speaker, "Attributes.Strength") > 9 && Inventory.FoeBlaster
For this example, the logical And && was used, but the logical Or || is also a valid option for conditions in articy:draft X. You can find a list of all usable operators in the scripting Help Center article.
Modifying property values through scripting
Similar to global variables, it is of course also possible to modify template properties through scripting. This we do with an instruction. An instruction can be placed in the output pin of a node or into a specific instruction node.
When modifying a property value, please make sure to write object and property names exactly as they are and also make sure that the data type matches for the value you are changing, as there is neither auto-complete nor type check for the arguments you enter. If you encounter an exception when dealing with template properties, there is probably a typo somewhere or a mismatching data type.
In this example dialogue we have three occurrences where we want to modify a property value.
The first one happens if the conversation follows the branch for a high morale value. For this example, Shady Pete takes the player’s money and only leaves them a fixed amount. That means we set the money property to a value.
For this, there is another built-in function – setProp, for set property. To set a property, we first need to get the object and the property in question. This part is similar to the getProp function. In addition, we need to specify the value that is supposed to be assigned to the property.
The structure for a setProp call looks like this:
setProp(getObj(“TechnicalName”), “FeatureName.PropertyName”, value)
setProp(getObj("Char_Phoenix"), "Wallet.Money", 20)
Regardless of how much money the player initially has, after going through this instruction node, they are left with only 20.
More often than setting a property to a specific value, you probably want to add to or subtract from an existing value. This, of course, is possible as well, with dedicated increment and decrement functions.
An example for this we encounter if our character’s Strength is very low and we follow the top branch after the Qualification hub.
The structure is similar to the setProp function with the difference that the property will not be set to the provided value, but the current value gets incremented by it.
incrementProp(getObj(“TechnicalName”), “FeatureName.PropertyName”, value to be incremented)
incrementProp(getObj("Char_Phoenix"), "Attributes.Strength", GameState.Potion)
As you can see from this example, the value does not have to be a literal number, you can also provide a variable as a value here.
GameState.Potion is an integer variable with a value of three. Increasing the Strength value to six in total. The conversation then jumps back to the Qualification hub and can now continue through the “Strength average” branch, as the value is now in the range between four and nine.
To subtract from the current value of a property, we use the decrementProp function. We see this at the very end of the example dialogue. The decision to work for Shady Pete costs the player two points of morale.
The structure is identical to the previously used incrementProp, only the function name changes.
decrementProp(getObj(“TechnicalName”), “FeatureName.PropertyName”, value to be decremented)
decrementProp(getObj("Char_Phoenix"), "Attributes.Morale", 2)
Example of how the dialogue plays out integrated into a Unity project:
These were the basics of working with template properties in scripting, expanding your toolkit of creating and controlling story logic inside articy:draft X.
Check out the Help Center articles for the complete documentation about scripting in articy:draft X.
Useful links:
articy:draft X Basics – Scripting
articy:draft X Basics – Templates I
Help Center – Templates
Help Center – Scripting
Don’t have articy:draft X yet? Get the free version now!
Get articy:draft X FREE
*No Payment information required
Follow us on X, 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.