Key Concepts

Before you start working with uScript, it is important that you have a good understanding of key concepts for both Unity and uScript.

While uScript's purpose is to unleash the power of programming to those without programming experience, you still need to have an understanding of Unity terminology and its various systems and features.

Also, please see the Unity prerequisites area of the "Setting Expectations" topic in the Introduction section for a list of specific Unity concepts we highly recommend you know how to use.

Playing Assets At Runtime

One of the first things many people usually wish to try with uScript is to do something with an existing asset in their game such as spawn a prefab, play a sound or animation, or use some other kind of asset such as a Texture2D, GUISkin, Font, etc. It is important to remember that uScript must follow Unity's rules when it comes to doing this!

 

Using a Resources Folder

Putting all your assets into a Resources folder is the first/easiest way to access assets to stream in at runtime when you build the game. Unity requires that any asset that is not present in the game/scene in the editor, must be put into a "Resources" folder in order to be loaded while the game is running:

 

 

We recommend you familiarize yourself with this aspect of Unity so you understand how it works and what the tradeoffs are. You can read more about the Resources folder here in Unity's documentation:

Unity Documentation: Loading Resources At Runtime

 

If using the Resources folder to stream your assets into the game at runtime, the most important thing to remember is that you will need to load the asset in uScript by using a Load <Asset Type> node before you can use access that asset with other nodes that wish to use it.

 

Here is an example of a sound loaded into uScript when the scene first runs and then other logic that plays the sound whenever the left mouse button is pressed:

 

 

Note! - You do NOT need to load animations or prefabs through a Load <Asset Type> node like other assets. This is because all animations need to be assigned to GameObjects in the editor so it is assumed if the GameObject or prefab is in the Unity scene, the animations have been loaded by Unity as well.

 

 

Using Exposed Named Variables

Another way you can access assets at runtime is to assign the asset to a named variable you have exposed in uScript (see Named Variables section within the "Variables" topic in the Working With uScript section of this guide for details regarding exposing Named Variables).

 

When an asset has been assigned to an exposed variable, Unity knows that it should package up that asset when building the game, so there is no need to manually load that asset from a Resources folder beforehand. This also means that you do not need to have your asset in a Resources folder at all when using this method.

 

Here is an example of assigning an Audio asset to an exposed Named Variable on a graph called PlayAssetExample that is assigned to the _uScript GameObject (an AudioClip variable called AlarmSound):

 

 

 

Now that the AudioClip is assigned, we can just tell Unity to play it whenever we like without the need of having to load the asset beforehand:

 

 

 

_uScript Master GameObject

uScript needs to make a GameObject for itself that contains key uScript components. The default name for this GameObject is "_uScript". For your graphs to work in your scene, they must be assigned to a GameObject. In most cases they can just be assigned to the master uScript GameObject unless you are doing something specific like Nested or Prefab uScript graphs (see the "Graphs" topic in the Working With uScript section for more information about graph types).

 

In this case the graph we saved was called "ExampleGraph". uScript will generate a component script file and append "_Component" to the end of the name. This graph component is what is assigned to the GameObject for the uScript graph to be active in the Unity scene:

 

 

 

When you first save a new graph, uScript will ask is you would like to attach it to the master GameObject. Just press Yes to have the graph's generated code component to be assigned automatically. If you choose No, then uScript will not assign your graph to any GameObject and you will need to manually assign it to your GameObject of choice.

 

 

Note! - Selecting No is useful for graphs that you wish to assign to Prefabs or not have assigned in the scene at all (like for Nested Graphs).

 

If for some reason you wish to manually assign your graphs to the _uScript master GameObject (or any other GameObject in your Unity scene), just locate the generated code component file (it will be called YourGraphName_Component.cs) and drag it onto the GameObject's inspector panel. You can also assign the graph component from Unity's Component menu. Just go to the uScript/Graphs section and choose the graph component you want to assign.

 

 

 

uScript Files

uScript currently generates three files for each uScript graph you create. These files will be located in your project's root assets folder in uScriptProjectFiles/uScripts/ by default. Let’s assume you create a new uScript graph called “MyGreatGame”—these are the files uScript would generate:

 

• MyGreatGame.uscript – This is the “master” binary file that uScript uses to save your uScript graph. You don’t want to delete this file (unless you want to actually delete the uScript permanently). This file can generate/re-generate the other two code files below at any time. Sometimes you will need to regenerate the code files from this file when uScript has been updated and you receive compile warnings or errors from Unity.

 

uScript uses the above master graph file to automatically generate the following code files whenever the graph is saved (with the exception of Quick Save) or "Rebuild All Scripts" is used from the file menu in uScript. These files are what Unity actually uses when your game is run:

 

• MyGreatGame_Component.cs – This is a “wrapper” output C# script file. This is the component code that would be assigned to a GameObject in your Unity scene, such as the uScript master GameObject (see above), in order to have your uScript graph active in the scene. This file is automatically built/rebuilt by uScript from the .uscript binary file above.
• MyGreatGame.cs – This file is where all the “magic” is. This is the file that contains your entire uScript graph as pure C# code. This file is automatically built/rebuilt by uScript from the .uscript binary file above.

 

Note! - you may notice a slight pause after saving a uScript graph because, when the C# script files are generated, Unity will recompile the script files to update them with your changes. This is why "Quick Save" in uScript can be handy-- it allows you to save changes you have made to the master .uscript file without causing uScript to regenerate the C# script files. Just make sure you do a full save before trying to run your game so that the latest code files are generated!

 

 

Uniquely Named GameObjects

Currently uScript needs to be able to tell which specific GameObject you want it to use by its name. This means that you should have a unique name for any GameObject you wish to use or reference in uScript, as that is the only way uScript can identify a specific GameObject between Unity sessions (a session means quitting and then running Unity again). While Unity does support unique IDs internally for all GameObjects in your scenes, unfortunately these unique IDs are not persistent. This means that we cannot rely on the GameObjects to have the same ID numbers in between closing and reopening Unity, leaving the only choice for the user to make sure they uniquely name their GameObjects they wish to use in uScript.

 

As an example, if you place three point lights in your scene, Unity will name them all "Point light" by default. If you wish to reference one of those lights in uScript, you should give it a unique name so that uScript can find the correct light you wish to use.

 

 

Reflection

uScript will use .Net Reflection in order to visualize many aspects of your existing GameObjects, Components and Scripts (C#, javascript, and Boo) in Unity. In the case of scripts created in either javascript or Boo, you may need to place the scripts inside a "Standard Assets" folder in your Unity project because of the order in which Unity compiles scripts. C# scripts do not have this restriction.

 

It is important to note that uScript can only reflect things that are part of active GameObjects in your Unity scene. uScript will reflect any public Actions (methods/functions), Properties (Properties/Public Variables exposed to the Unity inspector – both Get and Set), and Variables (all variable types). You must assign an instance GameObject (see above) to them so uScript knows what specific GameObject you want to use.

 

All reflected nodes can be found in the Nodes Palette under the "Reflected()" section. If you have a Unity scene with a name, the scene name will be shown between the parentheses - Reflected(YourSceneName).

 

This image shows an example of auto-created nodes made through reflection for some aspects of a light GameObject in the scene. To reiterate-- if you do not have a light in your Unity scene, these light nodes generated through reflection would not show up for you. You must have a light in your scene for them to appear:

 

 

Note! - the bottom two "square shaped" colored nodes are properties of the GameObject and can be used just like variables. These two would let you change the light's intensity and color. Again, you need to assign the Instance of the light GameObject you wish to effect in the node's properties or uScript won't know which light in your scene you wish to affect!

 

 

Instances

uScript’s Event Nodes and many Reflected Nodes require you to assign a specific GameObject to it so that uScript knows what object you want to fire that event or read/write a reflected property. In many cases, for the more global event nodes, using the master _uScript GameObject if fine (and uScript will auto-assign the -uScript master GameObject by default when placing many Event Nodes). For other nodes however, you want to tell uScript exactly what GameObject is firing an event.

 

It is also important to note that for many event types, Unity requires that you have a certain component on your GameObject to work correctly. As an example, if you want to have a trigger, you need to make sure that a Collider component assigned to that GameObject in Unity and that it has the "Is Trigger" checkbox checked.

 

Using the Trigger Events node as an example, you need to tell uScript what trigger GameObject in your scene you want to make fire that event (you could have hundreds in your scene!). This is done by assigning an instance (a specific GameObject) to the property of the event. In the below image, we are assigning a GameObject trigger called "AlarmTrigger" to the Trigger Events node. This means that when the player enters the specified trigger (AlarmTrigger), the event will fire and cause text to print to Unity's console. No other trigger you may have in your the game will cause this event to fire.

 

 

Note! - in many cases, uScript will not allow you to assign a GameObject as an instance for an event node if it does not have the correct component assigned to it. Keep an eye on the Unity console output for uScript warnings if you try to assign the wrong thing.