Hello and welcome to this articy:draft scripting tutorial.
This tutorial was created with articy:draft 3, but all shown information is also valid for articy:draft X
This video covers scripting in articy, with a focus on accessing object properties, for example a character’s skills. In case you have never used the software you might want to take a look at the first steps tutorial series, before continuing with this tutorial. In the first steps series you will learn about global variables, update existing features or create entirely new ones, and see examples of basic scripting with Boolean variables. You can start the First Steps series here.
articy:draft has its own easy to use expression language called articy:expresso. It gives you the means to shape your story flow with global variables, conditions, and instructions. 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.
Conditions and instructions can be used in three different places:
In dedicated condition or instruction nodes.
Inside node pins, where conditions always go into the input-pin and instructions to the output-pin.
Within script fields of object templates.
Conditions need to be a single statement that can be evaluated to a Boolean. You can write the entire statement or use a shortened form as it is common in many programming languages. GameState.talkedToNPC can be used instead of GameState.talkedToNPC == true and !GameState.talkedToNPC is the same as GameState.talkedToNPC == false. A whole number of relational operators can be used to compare values. With the help of logical operators we can concatenate multiple comparisons into a condition statement.
GameState.talkedToNPC == true
GameState.talkedToNPC
GameState.talkedToNPC == false
!GameState.talkedToNPC
GameState.skillPoints == 10
GameState.skillPoints != 1
GameState.skillPoints < 5
GameState.talkedToNPC == false && GameState.skillPoints >=5
Instructions are one or more statements changing values. Please note that you have to end each statement with a semicolon if you use more than one statement.
To change values we are employing assignment operators. For example setting a Boolean variable, after talking to a certain NPC, or adding a reward sum to the player’s credit balance. You can find the complete list of usable operators in the articy Help Center.
GameState.talkedToNPC = true
GameState.credits += 1000
GameState.skillPoints --; GameState.credits -= 500;
Shaping and controlling the story or game flow with the help of global variables is already a powerful tool, but in addition to that you can also access and modify object properties through scripting in articy. Let’s take a closer look at that in the context of this small demo scene.
We have two variables under the variable set GameState – credits and skill points. Both of type integer.
On our player character a template with two Features is assigned, one of which is called Skills.
The Flow consists of two dialogues. We will look at the condition dialogue first.
The player character Lily is approached by the NPC Mr Starvaz. We want to have different dialogue options available to the player depending on which skills they possess. As we have seen earlier the skills exist as properties in a template, therefore the way to check for them in a condition is a bit different from checking for a variable. As we can see in the comment of this condition node, we want to check if Lily has the conversation skill at least skilled to 1.
To handle object properties there are a built in methods we can use. To access a property we have to call getProp() as in Get Property. Then we have to specify the object to which the property belongs to. This we do by getObj() as in Get Object. The object can be accessed by technical name or by ID.
Technical name and ID of any object can be found in its General tab.
The technical name of the player character is PC_Lily. Next comes the Property Name as a string. As we want to access template data, we need to write the technical name of the feature plus the property’s technical name divided by a dot. Resulting in Skills.Conversation. Within strings you do not have auto-complete, so make sure to write the names exactly as they are called in the Feature.
To finish the condition all that’s left to do is put in an operator and a value to check against.
getProp(getObj("PC_Lily"), "Skills.Conversation") >=1
That might look daunting at first, but is basically always the same structure if you want to check against an object property. Also as soon as you start typing in a condition node or inside a pin auto complete will kick in, so you can select the needed method from the drop-down and just complete it by adding object and property names.
If working with dialogue fragments, we can shorten the expression with a substitute for the getObj() part. Let’s try it out in the next branching point of the conversation. If Lily does not have the conversation skill, she here gets another chance to increase her fee by showing knowledge from other skills. For this node, we want to check for the Pilot skill.
We start as before with getProp(). Instead of having to query for the object by calling getObj() we can use the convenient identifier speaker which is an automatic reference to the current speaker object. Now we again add the property we want, in this case Skills.Pilot and operator and value to check against.
getProp(speaker, "Skills.Pilot") >= 1
Of course we can also use logical operators to expand these statements. Like in this last condition where both the right skill and some spare skill points are necessary to display this option to the player.
getProp(speaker, "Skills.Pilot") >= 1 && GameState.skillPoints >2
Now let’s go to the Instruction side of things. In this small dialogue our player character Lily is able to assign a skill point.
When Lily interacts with the computer, she can choose from a number of skills. First is the Pilot skill. We already have a statement in the out-put pin which removes a skill point, by setting the skillPoints variable value to its current value minus x, in this case minus 1.
GameState.skillPoints -= 1;
In the conditions earlier we used getProp() to access the value of a property. Now we want to change the value, so we have to call the setProp() method as in Set Property. Like before, we need to query the object to which the property belongs with getObj(). This again we do with the technical name of the object PC_Lily. Followed by the property we want to modify, written as the technical names for Feature plus property, divided by a dot. If we want to set the property value to an absolute number, we can do that pretty easily. Probably not the best way to set up a skill system, but for the sake of the example, let’s just set the Pilot skill value to one, by typing the number.
setProp(getObj("PC_Lily"), "Skills.Pilot", 1)
For the Conversation skill, let’s modify the value instead of setting it to an absolute number. We start out with our statement as before, setProp(), get the object and the desired property.
As we want to change the value of the property we need to know its current value first, and this we do by querying it via getProp(). Again we need to say which object we do want to access and the name of the property in question.
Then we specify how we want to change the property value, in our case we want to add one to the current value.
setProp(getObj("PC_Lily"), "Skills.Conversation", getProp(getObj("PC_Lily"), "Skills.Conversation")+1)
If it is the first time you are facing this kind of statement it probably looks quite confusing, so let’s take another look at both statements for conditions and instructions again.
First we call a method depending on what our goal is. In a condition we want to see the current value of a property to be able to compare it with something, which we accomplish with getProp(). In an instruction we want to change the current value of a property. This we do with setProp().
Next we specify our target. Who or what do we want to see or change? This part is similar for conditions and instructions. Here we want to access skill information of our player character Lily, or more precise to access the Pilot property of the Skill feature of the Lily object.
For a condition the getProp() expression is complete at this point, what we still need to do is add the comparison part to have a statement that will either give a true or false result. If at the current time Lily has one point assigned to the Pilot skill, this condition will return true.
getProp(getObj("PC_Lily"), "Skills.Pilot") >=1
The setProp() expression needs a third part, the actual instruction of how the property we specified earlier is supposed to be modified. If we want to set the property to some specific value, we don’t need to know what its current value is, as it will be overwritten anyways. This statement used in an instruction will set Lily’s pilot skill to one, regardless of how high it was before.
setProp(getObj("PC_Lily"), "Skills.Pilot", 1)
If we want to modify the property value based on its current state, we need to access this value to see it first. Do you recognize the underlined part of the statement? It is the exact same syntax for the getProp() expression as we used for the condition.
Now all that is left is to state how this value we just queried with getProp() needs to be modified. Here we want to add one to the current value of the selected property. If Lily has one point assigned to the skill right now, the new value of the pilot skill would be two.
setProp(getObj("PC_Lily"), "Skills.Pilot", getProp(getObj("PC_Lily"), "Skills.Pilot")+1)
Patch 3.2 brought some scripting improvements, including an easier way to increment or decrement property values. You can find a tutorial explaining the new methods here.
Of course, if you are working with Dialogue Fragments and want to access properties of the speaker entity, you can use the speaker identifier in instructions as well.
setProp(speaker, "Skills.Survival", getProp(speaker, "Skills.Survival")+1)
Last but not least I want to go through this sample scene in the simulation view, so we can see how our instructions and conditions change the story flow.
I start the simulation at the first dialogue node and drag out a second view pane with a property inspector view, so we can see live changes of variables and properties.
This condition returns true, as we are checking for one or greater, and currently the variable value equals one.
Next we can decide which course to take. I always wanted to know how to survive on far away planets. If we confirm the selection two things happen: First we lose a skill point, the variable value is reduced by one. And second the survival property of the skills’ feature is increased by one.
We have arrived at the second dialogue. The first condition we encounter returns false, as we have not skilled Conversation, so we cannot demand a higher fee right away.
At this point we have two options. We can settle for the base fee, an option that is always accessible, or try to negotiate a little bit extra thanks to our survival skill.
Because the condition checking for the Survival property returned true, the story follows the branch leading to more money. Now the credits variable gets updated. 4000 credits, payed up front. Very nice.
We have arrived at the end of this tutorial. You can now access and modify object properties via scripting, giving you another layer of depths for your story flow.
Useful links:
Scripting in articy:draft
Scripting and how to use it
First Steps Tutorial series
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 communities on reddit and discord.