Ancient Warfare 3 [WIP for Alpha 0.36.0] Scripting & Triggers

Introduction

 
If you read the scripting sections and have no programming experience, it may feel a bit overwhelming. That’s okay and totally normal 🙂 Maybe have a look at some of the first few examples (last section). They are very simple and you get a more graphical introduction to the topic. Visual scripting is very easy. 
 
(Just a reminder: You can click on small images in this guide to increase their size) 
 
 

Scripting Mode

 
The scripting mode is a separate mode in the Custom Battle Editor, which allows you to create and edit specific events. For instance, you can spawn enemies when the player enters a region or activate something when a button has been pressed. 
To open it, you simply have to press the Scripting-Button in the toolbar: 
 
Once you are in the scripting mode, everything will be rendered white. The features of this mode will be explained in the following sections. 
 
 

Triggers

 
 
Triggers are one of the features of the scripting mode. A trigger is an area which detects when a unit enters, leaves or stays in the area. Later in this guide, we will use triggers to start scripts. In AW3 there are cube and sphere triggers to define an area. 
To place a trigger, press on one of the buttons in the left toolbar (1) and place it like a regular object in the editor. The controls are visible at the bottom of the screen. Placed triggers can be selected by clicking on them. You can adjust the position by dragging the position handles (2) and resize the trigger by dragging its size handles (3). 
 
 

Lights

 
 
Custom lights are another feature of the scripting mode. You can place lights from the left toolbar (1). Similar to triggers, lights can be selected and you can use the position handles (2) to change the position of placed lights. While a light is selected, the editor renders using the regular materials to preview the light and you can adjust the range, intensity and color of the light (3). 
Lights can also be deactivated. This can be useful if you want the lights to be activated by a script later on. 
 
 

Other objects

 
Besides triggers and lights, there are other objects which can be used with the scripting system: 
Alarms, Buttons, Levers, Codelocks, Locks, Doors, Light objects and more… 
 
 

Scripts

 
Triggers without functionality are a useless addition. That’s why the scripting mode allows you to create scripts to access game functions and add functionality to your triggers, buttons and other objects. Scripts can be global or attached to an object. The difference is that attached scripts will no longer work, if the attached object has been destroyed. However, it’s recommended to attach scripts to the object that starts the interaction, because it helps to find scripts and it also helps while editing scripts, as we will see later. 
 
 
To create a new script, either press the last button in the left toolbar to create a global one or click on an object to select it (1). The selected object is rendered blue. While an object is selected, there is a panel on the right side of the screen where all scripts are listed. Button (2) adds a new script to an object. Each script has a name and a description that helps to identify its functionality. Button (3) opens the script editor to edit the script. 
 
 

Editing Scripts

 
Ancient Warfare 3 uses a visual scripting system. That means you dont have to write any code. To create logic, you can just connect different functions to create a graph of different actions. These graphs look like this: 
 
Before we dive into the details, please have a look at the editor controls: 
The script name is visible in the top left corner (1). The back button (2) saves the current script and closes the script editor. (3) In the bottom left corner you can see the zoom, save/load a script or add nodes to the current script. Other controls are: 

• Zoom = Mouse Scroll Wheel 
• Move view = LMB + mouse movement while not hovering a node 
• Add node = Space 
• Select node/connection = Clicking on a node/connection, holding Shift or Ctrl enables the selection of multiple elements 
• Box select = B enables the selection of multiple nodes and connections 
• Delete selection = Delete button 
• Copy/Paste selected = Ctrl + C, Ctrl + V 
• Move node = Drag with the mouse while holding LMB over a node

Adding nodes

 
 
Placing nodes works by pressing space. A small panel shows all available nodes sorted into categories with short descriptions. If you know what you are looking for, you can also search for a node name. When you click on an item, it will spawn a new node of that type. 
 

Connecting nodes

 
 
Two nodes can be connected by dragging from an output to an input (marked in red) 
But there are different types of out and inputs and not all of them are compatible. When they are not compatible you can’t connect them and the editor will display the connection in red color. Why that’s the case will be explained in the upcoming sections, but for the basic controls, that’s all you need to know. 
 
 

Scripting – Events

 
Events are the entry points for scripts. Every time an event happens, scripts with that event node will run. Event nodes can be found in the “Event” category when adding a node. 
 
 
Some events work without any additional work, like the start event, which runs when the battle starts. However, the trigger event requires a reference to a trigger object in order to work. To select the trigger, press on the arrow button (1). The scripting panel will be minimized and all available objects are displayed and can be selected. When the script is already attached to a trigger object, the reference will be selected automatically and you dont have to do anything. 
 
Some events output different information (2). For instance, the trigger event outputs which unit entered the trigger. That’s required because different units can enter the same trigger and you want to know which one. If you dont want to know, you can just ignore the output. 
 
 

Scripting – Input

 
 
Input nodes can be found in the “Input” category when adding nodes. These nodes can be useful, if you need constant values. For instance, when you want to add 150 damage to every unit that enters a trigger, you have to store the value 150 somewhere and connect it to another node. 
 
You will find many different input types, but the most important ones to remember are: 

 
There are also various object reference inputs, like Trigger, Unit, … Those work similar to the reference of the trigger event from the previous section. 
 
 

Scripting – Actions

 
Action nodes are responsible for actions that happen after an event caused a script to run. For instance, there are action nodes which spawn units, add damage to a unit or open a door. 
 
 
These kind of nodes have a special input (1) and a special output (2). Those connection points can be used to start the node. How that works will be explained in the following sections. 
Action nodes can have input parameters (3), which can be used to modify the function. In this case the function needs information about the unit which we want to spawn. The next action probably wants to know which unit was spawned, so there is an output parameter (4) with the reference to the spawned unit. 
 
 

Scripting – Data Connections

 
As explained in the previous section, action nodes require input parameter in order to work properly. So how do you know which input/output connection points can be connected? 
 
 
Each input/output connection point is labeled with the type in brackets. To find matching inputs, you just have to find an output with the same type as the input. The input can be from an input node or another action node. If it’s from another action node, it’s important to make sure that that node runs before the node which uses the input. How to ensure that will be explained in the next section. 
 
 

Scripting – Control Connections

 
The previous section explained data connections between nodes. But that’s not enough to actually run the nodes. The special arrow shaped input/output points from the event and action nodes have to be connected to make the script work. These connections are animated and control the execution of the individual nodes. 
 
 
When a unit enters the trigger, the event node is executed first and starts the script. After that the “Unit To Health” node runs and gets a health reference from the unit which entered the trigger. Since that node is connected to the “Add Damage” node, the “Add Damage” node will run last and applies damage to the health reference from the previous node. 
 
The previous example was straight forward. Lets have a look at a more complex graph. 
 
This time the control connections split after the first action (1). What happens in that case is that both paths will continue to be executed. However, the upper path requires the result of the lower path to add the correct amount of damage to the unit (2)! To ensure that, it’s important to connect the control connection from the last node of the lower path to the “Add Damage” node (3). That way the whole lower path will be executed before the upper part adds the damage. 
 
There are much more advanced methods to adjust the control flow, which will be explained in the examples. 
 
 

Scripting – Variables

 
Variables are not implemented yet 
 
 

Scripting – Advanced Topics

Missing data reference inputs

 
 
In this example the health reference input is not set. When the script runs, the node will not do anything, but the following nodes after the “Add Damage” node will run regardless. 
 

Missing data value inputs

 
 
In this example the damage amount float is not set. In this case, the default value of a float is used 
Default values 

Examples

 
Below are examples for various scripts to explain certain nodes and to provide something you can use or build on. 
 

How to add damage to a unit that enters a trigger?

 
 
The get the unit reference from a trigger and get the health reference from it. After that 100 damage is applied to the health reference. 
 

How to set a unit on fire?

 
 
Similar to the example above. 
 

How to kill a unit when pressing a button

 
 
There is a health reference input which references an already placed unit. When the button is pressed we run the kill node. 
 

How to toggle an alarm when pressing a button

 
 
The alarm is a reference input to a placed alarm object, which is off by default. When the button is pressed we test if the alarm is current on and switch the value (true becomes false and false becomes true). The result is applied to enable/disable the alarm. 
 

How to open a door with switch

 
 
The script is attached to a switch object and the door is referenced with an input node. Whenever the switch changes, we just use the value to open/close the door. 
 

How to lock a door with switch and enable a lamp if it’s locked

 
 
Similar to the example above, but the reference is a lock and there is another reference to activate/deactivate a light, which is off by default. 
 

How to open a door with a button if the power switch is on

 
 
There is a switch reference to the lever object which controls the power. When the button is pressed, we get the current state of the switch. The “If” node tests whether the input is true and continues with the “true” control connections if that’s the case, otherwise with the “false” control connections. 
 

How to open a door with a code lock

 
 
When the enter key of the codelock is pressed, we test if the code is 1234. By using an “If” node like in the example before we open the door, if code is correct. 
 

How to spawn a unit when pressing a button

 
 
Spawning units is very easy, you just have to fill the input parameters with values and connect an event. 
 

How to end the battle if a player enters a trigger

 
 
When a unit enters the trigger, we test if it’s a player and end the battle if that’s the case. 
 

How to show custom goals on the HUD

 
 
When the player enters the trigger a loop runs. The nodes after the “N Loop” will run 5 times, because the input of the “N Loop” is 5. In this case the scripting creates 5 HUD progress marker. The lower part of the script handles the completion of the first progress marker, when a button was pressed. 
 

How to show messages on the HUD

 
 
By using something like this, we can show HUD messages to tell the player what to do. 
 

How to do a low gravity area

 
 
Gravity is global value. That means that the gravity of the whole battle is changed when a unit enters the trigger. When the unit leaves, the gravity will be reset. 
 

How to create a light switch

 
 
Light switches usually affect multiple lights. For that reason, there is an array input node. The type of an array mode can be choosen as well as the amount of elements in it. The advantage of using arrays is that you can easily do the same action for multiple elements of the same type. In this case it would be annoying to activate each individual light. However, the array allows us to use the “ForEach”. The nodes after that node will be executed for each element in the array. 
 

How to create a light switch with delay

 
 
This example is similar to the example above, but this time we use a delay node to delay the activation of each individual light. After the foreach loop we multiply the index by 0.2. Therefore the first light activation will be delayed by 0 seconds, the second by 0.2, the third by 0.4 and so on. 
 

How to slow down time while the player is not moving

 
 
This example uses the player input to control the time. The update event should be used with caution, because it’s executed every frame. Doing expensive calculations in the update event can reduce the performance. In this case the vertical and horizontal inputs (WASD) are added and clamped between 0 and 1. When the player is standing still, the value will be 0.0 and otherwise 1.0. 
This value can be used to adjust the timescale. Be aware that a time scale of 0.0 means that the game is paused. That would be a problem, because the update event would no longer be called. To solve that problem, the time scale is clamped between 0.1 and 1.0, so that the game is not stopped. 
 

How to create an ammo vending machine

 
 
When the button is pressed, we get the player of the battle and get the current amount of money the player has. If there is not enough money, the hud will show “Not enought money :(“. Otherwise we add 10 9mm bullets to the player inventory and reduce the money by 200$. 
 

Hope you enjoy the post for Ancient Warfare 3 [WIP for Alpha 0.36.0] Scripting & Triggers, If you think we should update the post or something is wrong please let us know via comment and we will fix it how fast as possible! Thank you and have a great day!