Variables

Variable nodes, also just called variables most of the time, are a key part of uScript graphs. One way to think of variables are as containers that you can use to store a piece of information. You can either get a piece of information out from one of these containers, or put a piece of information into one of these containers. However, with the exception of List Variables (which we will discuss a bit later in this topic), you can only ever store a single piece of information at a time inside a variable.

 

All programming languages use variables in some way to store and retrieve data. Because uScript is a visual scripting system, it must also use variables to store the information you wish to use in your uScript graphs. uScript follows some key rules regarding variables, shown here:

 

Key Rules

 

Color Codes

uScript uses color coding on the border of it's variable nodes for the most commonly used variable types in uScript. Any variable type not currently assigned a specific color will have a white border.

 

Standard variable types that currently support color coding are:

 

 

 

 

uScript's Event and Action nodes also use this same color coding for it's bottom variable sockets. Here is an example of a couple of nodes using a String variable. You can see how the green color for the String variable is also matched on the a node's socket that require a String variable for both input and output. Even the connection lines between the variable and the node's socket is the same color (green in this case):

 

 

 

Variable Node Display Options

Variables in uScript are by default displayed as circles that on selection may be expanded to fit the full value of the variable if it does not fit in it's default, collapsed state.

 

 

 

In the uScript Editor's Preferences window you can choose how you wish to have uScript display variable nodes (see "Editor Preferences" for details).

 

 

 

Variable Node Types

 

Common Variables

While uScript can use any type of variable that Unity uses through reflection, there is a common set of variable types you will find yourself using repeatedly in uScript. Those variables are described here.

 

Bool

Bool stands for boolean and it can either store the value true of false. They work great as a way to decide if you wish to do something or not and many other comparison type situations.

Example - here we check to see if a Bool variable is set to true or false. If it is true, the logic carries on to do something else:

 

 

 

Color

The Color variable stores a color as Red, Green, Blue, and Alpha float components. Legal ranges for the color components are between 0.0 and 1.0.

Example - this logic get's the Blue float value from the named "Car Paint" Color variable and then checks to see if it is greater than "0.5":

 

 

 

Float

A float is a number that contains decimal places. Even a "whole" number such as 4 would be considered as 4.0 when it is a float. Most times Unity will want a number as a float as the need ofr decimal places is very important in math. Unity will also commonly use the range of 0.0 - 1.0 to represent percentages and other ranges internally. For example, if you wished to set the Intensity (brightness) on a light to 42%, you would represent that the float value 0.42.

Example - this logic will add two floats together and then print the result to Unity's console window. You might notice that the Float variable hooked up to the "result" socket shows "0". This is because 0 is the default value for a float variable. Once this logic is run in the game, the real value will be inserted into it (5.25 in this case) before the Log node prints out to the console window.

 

 

 

GameObject

Everything you place in your scene in Unity is a GameObject. This variable type allows you to store a specific object from your Unity scene so you can access it inside uScript in order to work with it.

Example - in this example we are rotating a GameObject from the Unity scene called "Cube".

 

 

Note! - uScript relies on Unity to provide the correct GameObject by its name. It is important that you uniquely name any GameObjects in your Unity scene that you wish to directly use with uScript by name. If you do not wish to uniquely name your GameObject (or can't such as with prefabs spawning at runtime), please see the Owner GameObject variable type instead.

 

 

Int

An Int is a whole number and can not contain any decimal places. Ints are not used as frequently in game logic as float variables, but are very handy for things such as counting totals or other times where you only need to use whole numbers.

Example - this example sets an Int variable to a random number between 3 and 7, then converts the Int variable value into a string variable (see String below) before finally printing the resulting number to the screen.

 

 

 

Material

The Material variable type holds a Unity material which is made up of texture, color and other information to describe how a GameObject should "look" in the game.

Example - this example assigns a material called "BluePlayer" to a GameObject called "Player".

 

 

 

Quaternion

A Quaternion variable is made up of four float components and describes the rotation of a GameObject in mathematical terms. It is very rare that you would want to actual modify the components of this variable type directly and will instead mostly use by just passing on a Quaternion value you got from Unity into another uScript node or GameObject.

Example - this logic creates a Quaternion value from Euler degree input (90 degrees on the Y axis in this case) and passes that value to a named Quaternion variable called "TurretHeading". It then Inverts the Quaternion variable's value by updating itself in the "Invert Quaternion" uScript node.

 

 

 

Rect

The Rect variable type is used by Unity for things such as the GUI system. It contains four float components (X Position, Y Position, Width, and Height) that define the size and position of a rectangle.

Example - this logic uses a Rect variable to define the position and height of a Unity GUI Button in the scene (with a label of "Yes"). Note that it is telling Unity to draw the top left of the button at 32 on X and 128 on Y for the screen postion, and of a size of 256 wide by 64 high.

 

 

 

String

The String variable type is used to hold text. Even if you assign it a number, Unity will just treat it as text and not a number.

Example - in this logic, we combine (concatenate) the text in two different String variables into one new String variable. The results are printed on the screen ("I love uScript!").

 

 

 

Vector2

The Vector2 variable type holds two float components (X and Y). It is a useful variable type to store a pair of floats that you would normal want to have together, such as a screen resolution or other X and Y location.

Example - this logic gets the current X and Y position of the mouse cursor on the screen as a Vector2 and then compares it to see if it is at 1024 on X and 768 on Y as specified from the second Vector2 variable. If so, the logic will continue to other nodes.

 

 

 

Vector3

The Vector3 variable type is a very common type to use in Unity. It contains three float components (X, Y, and Z) and is usually used to store a position in 3D space. They are also used to store the force/magnitude of motion in a 3D direction for physics.

Example - this logic tells the GameObject called "Cube" to teleport 5 units above the position of another GameObject called "TeleportPad" by first getting TeleportPad's 3D position in the game as a Vector3 variable.

 

 

 

Vector4

The Vector4 variable type is basically the same as the Rect variable type mentioned above as it contains four float variable components (X, Y, Z, W). However, this variable type is usually used in physics calculations and other general cases where four float values are useful in defining something.

Example - this logic simply allows you to convert a Rect value into a Vector4 value.

 

 

Other Variable Types

These and other more common variables are found in the Variables section of the Toolbox. Also, if you are using the Professional or Personal Learning Edition (PLE) of uScript, you can also access every variable type available in your Unity scene through reflection under Reflection()/Variables.

 

 

List Variables

Sometimes you will want to store a bunch of the same variable type together. uScript does this through List Variables. List Variables are just that-- they store a bunch of variables of the same type together. This allows you to use special "List nodes" we have written to quickly read/write/iterate through the list for various purposes. For those with a programming or scripting background, you can think of a List as a variable array.

 

A simple example of using a List variable might be if you wanted to end your game once a specific number of GameObjects have touched a trigger (let's say 8 GameObjects and the trigger GameObject is called "GoalTrigger" for example). To do this, you could add each GameObject that touches the trigger to a GameObject List variable and then check the size of the list to see if you have reached 8 GameObjects:

 

 

 

Properties

uScript can reflect public variables being used by other things in Unity ("public", or exposed, means that the developer who created the variable set it to be accessible by other things outside of itself).

 

All reflected variables from other objects in Unity are called "Properties" and can be found under the Reflected()/Properties section of uScript. Reflected properties can be a very powerful thing and is also a great way to allow you to pass, or assign, your own uScript graph values outside of your graph to either other uScript graphs or even other Unity scripts or the Unity Inspector panel (see Named Variables below).

 

Please also see "Reflected Nodes" and "Advanced Reflection" for more information about uScript's reflection feature.

 

Note! - because properties are part of reflection, this feature is only available using the Professional or Personal Learning Edition (PLE) of uScript.

 

Using Properties

To se what properties are available to use, go to the Reflected ( ) section of the Toolbox and open the Properties section:

 

 

Once expanded, you can access any properties that are available in the currently loaded Unity scene. For example, here are the default properties available for all GameObjects:

 

 

Setting the Property's Instance

Once a property has been placed on the uScript Canvas, it is important that you specify exactly what GameObject you wish to read or write the property to. This is important because you may have many GameObjects in your Unity scene that all have the same stuff on them-- like a light component. uScript needs to be able to tell Unity which specific instance of a GameObject with the light component you wish to effect. To do this you just need to assign the property's Instance property with the proper GameObject.

 

Here are three Light component color properties. The first is how it would look when first placed on the graph before an Instance was assigned to it. The second shows the Instance property set (to a GameObject called MyLight2), and the third is also set, but through a GameObject variable hooked up to the Instance socket- which was set to visible from the property node's Properties Panel setting:

 

 

Tip - exposing the Instance socket can be very useful when you want to set the instance GameObject at runtime or use the Owner GameObject variable as the Instance.

 

 

Example - Change Light Color and Intensity

 

As mentioned above, properties are really just variables. In this example we will set the color and intensity of a specific light in a Unity scene by modifying two of its properties.

 

Let's say we had three point light GameObjects in the scene called MyLight1, MyLight2, MyLight3 and we wanted to modify the MyLight2 light properties to change the light's color to red and the intensity to 50% (0.5) when the game starts:

 

Step 1 - Set up the graph logic:

 

 

 

Step 2 - Find and place the needed property nodes for a light component:

 

 

 

Step 3 - Hook up the placed property nodes and make sure the set their Instance property to the specific light we wish to effect (MyLight2):

 

 

 

Advanced Variable Use

Special Variable Nodes

uScript has a few "Special" variables that are designed to perform specific tasks.

Owner GameObject

The Owner GameObject it a special variable that tells uScript to "use whatever GameObject this uScript graph is assigned to". This allows you to build reusable graph logic for Unity Prefabs or other such uses. For those familiar with programming, the Owner GameObject variable is the equivalent of "this" in code.

 

 

Here is example logic that will play a sound when something collides with a GameObject. Because it uses the Owner GameObject for the Collision Event's instance socket as well as the Play Sound node's target, this graph can be assigned to any GameObject and it will automatically play the sound for that GameObject collision only (and the sound will come from that same GameObject):

 

 

 

External Connection Node Variables

The External Connection is used when creating nested graph node's in uScript. They can be hooked up to any node socket-- including variable sockets. When an External Connection node is hooked up to a variable socket, it will take on the variable type of the socket is was hooked up to.

 

 

Here is an example of External Connection nodes hooked up to various sockets to create a Nested Graph called "Give Points". Notice that the there is one hooked up to a Bool socket of a node:

 

 

 

It is important to setup the External Connection's properties-- especially a friendly name:

 

 

 

 

Here is what the nested node looks like (called "Give Points") when used in another uScript graph and hooked up to a Bool variable:

 

 

 

Note! - please see the Nested Graph section of the topic for more information on creating Nested Graphs and using External Connection nodes.

 

 

Changing Values Over Time

There are many times when you might wish to change the value of a Variable or Property Node over a set time. This can be accomplished using our Linear Interpolation Nodes. These nodes allow you to define a start and end value that will change between the two over a specified time.

 

 

 

Here is an example where we use an Interpolate node (a Vector3 one in this case) to change the value of a Vector3 over time and feed that value directly into a GameObject's "position" Property Node each tick of the game to move it. Also note we are using the Owner GameObject variable so that this graph can be assigned to any GameObject to move it-- making it very reusable.

 

 

 

Named Variables

Named variables allow you to "share" a variable throughout a uScript graph without needing to draw many lines to the same variable node to access it. uScript will treat any variable of the same type with the same name as the same variable-- no matter how many instances you might have of that named variable on your graph. If you change the value of one of the named variables, all other instances of that named variable will have it's value automatically updated throughout the entire graph.

 

Naming a variable is as simple as setting it's Name property in the Properties Panel:

 

 

Once you have named a variable, it's name will show up below the variable node on the graph:

 

 

Named Variable Rules:

 

 

Here is an example of the same logic shown twice. In the first example (1), we are linking the variables directly to all the sockets that need those values. In the second setup (2), we are using named variables to pass along the values to the sockets that need them. These two graphs are functionally the same:

 

 

 

 

Tip - It can be very useful to create a section of a large graphs that contain an instance of all Named Variable in the graph. This can make editing and iterating on the graph faster. Here is an example:

 

 

 

Exposed Variables

Exposed Variables are simply standard variables that have been named (see Named Variables) that have also been set to be exposed to Unity's inspector panel. This is done by checking the "Expose to Unity" option in the Variable Node's Properties Panel. Please note however that this option will only be available for Named Variables as Unity needs a name for the variable in order to expose it.

 

 

Note! - for you programmers/scripters out there, exposing a variable is equivalent to making a variable public in a Unity script.

 

 

Exposing variables to Unity has two major benefits:

 

Inspector Editing

Once you have exposed a variable to the Unity Inspector Panel, you will be able to edit that value from Unity directly without needing to open the uScript editor to view or change the value. This also means you can take advantage of Unity's ability to view and edit the values of exposed variables while the game is running for quick iteration and debugging.

 

To access exposed variables, open up the uScript graph component on the object that contains the variables you are looking for and expand the "Exposed Variables" section:

 

 

 

Sharing Values Across Graphs as a Property

You can access any exposed variable form another uScript graph as a reflected property (see Properties in this section for details). This is a great way to pass a value from one uScript graph to another.

 

Note! - Make sure you set the Property Node's Instance to the GameObject that has the graph with the exposed variables assigned to it!

 

Variable Tips & Tricks

Hot-Keys

uScript has several hot-keys that can be used to quickly place nodes on the graph. For example, holding the "S" key while left-clicking on the canvas will place a String Variable, "B" will place a Bool Variable, etc. For a full list of hot-keys, see the Canvas section of the "Hot-Keys" topic in the References section.

 

 

Context Menu

Another way to quickly place a Variable Node and have it automatically hooked up to a socket, is to use the right-click context menu. Simply right-click on a node's variable socket and choose the "Create Linked Variable" option of the menu.