Introduction

= Chapter 1 =

JavaScript for Unity (aka UnityScript) is a customized version of the popular JavaScript language, built for the Unity platform. However, it resembles JScript.NET more than actual JavaScript/ECMAScript.

This chapter will provide a broad overview of the language, which later chapters will go into more detail to cover. Overall, this language specification is meant primarily for a user and will not be comprehensive enough for a language implementer.

Getting Started
It wouldn't be a language specification without having a "Hello, world" example. In Unity, you will need to create a new JavaScript asset in your project view and name it 'HelloWorld' (extension is hidden). Here it is:

When you attach this to a GameObject in Unity and hit Play it will print "Hello, world" once to the console.

To attach the script to a GameObject, select the following in the Unity menu:

GameObject > Create Empty

This will create a new empty GameObject. You can then see the new GameObject in the Heirarchy view with the name: "GameObject".

Drag the script from the Assets view onto the newly created GameObject in the Heirarchy view. If you select the GameObject (in the Heirarchy view) you will then see that, in the Inspector view, the GameObject includes the script in its list of properties.

Click on the play arrow above the Game view. In the text field below the Game view you should then see "Hello, World".

The JavaScript source code you write for your Unity project is usually stored in one or more text files and must have a file extension of .js, as in HelloWorld.js. Unity does this for you if you create your scripts from within the editor. There is no command-line compiler for JavaScript, however, your scripts get compiled by the Unity editor as soon as you save them.

Examining our script further shows:


 * The Start method as a member of the implicit class HelloWorld. It has no static modifier, so it is an instance method instead of a class method.
 * The "Hello, world" output is produced using an inherited print method from MonoBehaviour.

Types
JavaScript for Unity has reference and value types. Value types are simple types such as char, int, float, enum, etc. Reference types include class types, arrays, and delegates.

Value and reference types are different in the way the data is associated with a variable. For value types, the variable has a one-to-one relationship with the data, which means that only one variable is associated with the data. For reference types, it is possible to have a many-to-one relationship with the data. Two reference type variables can point to the same instance of a class and affect that instance independently. Here is an example:

Output:

Value types 1 2 999 1 Reference types 0 0 111 111

You will notice from the output that assigning intValue to anotherIntValue copies the data, whereas assigning classVar to anotherClassVar points the two variables to the same data.

Predefined Types
JavaScript for Unity has the following predefined types:

Additional built-in types (without explicit importing) are listed in the Unity Script Reference

A predefined type is shorthand for a system-provided type (e.g. boolean is really System.Boolean). You should use the shorthand predefined types instead of the system-provided type when you have the option.

Conversions
Predefined types can be converted between implicitly (e.g. sbyte to short). Explicit conversions are supported for reference types, but not for predefined value types. Be careful when converting between predefined types that have different min and max ranges. For example:

will throw an "OverflowException: Number overflow" at run-time because an integer type cannot hold the max value that a long integer can hold.

Array types
There are two array types in JavaScript for Unity: built-in arrays and the Array class. Array documentation from Unity Script Reference