Head First into Unity with UnityScript

From Unify Community Wiki
(Difference between revisions)
Jump to: navigation, search
(Unity's "JavaScript" vs. the JavaScript you probably know)
(Debugging)
Line 123: Line 123:
 
Scripting errors will show in Unity as a "red x icon" in the window status bar. Click on the icon to bring up the console, showing a list of errors, which should be both informative and lead you to the line in the script that caused the problem.
 
Scripting errors will show in Unity as a "red x icon" in the window status bar. Click on the icon to bring up the console, showing a list of errors, which should be both informative and lead you to the line in the script that caused the problem.
  
The print() function will produce messages in the status bar and console.
+
Unity also generates useful warnings (with a "blue ! icon") e.g. telling you a variable you've declared isn't used anywhere. Striving to write code that never generates warnings is a very useful habit.
 +
 
 +
The print() function will produce messages in the status bar and console. You can also use Log("insert message here"); and Debug.Log("insert message here");
  
 
Although Unity does not have a conventional "stop, watch, and step" debugger, the editing GUI is completely live when running projects in the development environment (e.g. instances created at runtime appear in the browsers and you can click on them and look at their internal state).
 
Although Unity does not have a conventional "stop, watch, and step" debugger, the editing GUI is completely live when running projects in the development environment (e.g. instances created at runtime appear in the browsers and you can click on them and look at their internal state).

Revision as of 15:00, 4 December 2007

Written by Tonio Loewald (a.k.a. podperson)

Note: this tutorial assumes you know the basics of JavaScript and programming. We're not going to go over all that stuff from scratch. If you don't know anything at all about programming, well ... you should probably get a book oriented at learning to program, or take a class. The fundamentals of programming are a major topic in and of themselves.

Unity's "JavaScript" vs. the JavaScript you probably know

1) Unity JavaScript is compiled (and fast, which is excellent) but not so dynamic as JavaScript in browsers (which is interpreted).

2) In Unity, Strings are denoted with double quote '"' characters. Single quotes are not allowed. (This is a very nasty adjustment for long-time JavaScript hackers, where single quotes are more efficient than double -- but it makes sense in Unity because the code is compiled, eliminating the need for strings that don't get preprocessed.)

<javascript>var a = 'fred'; // works in JavaScript, error in Unity</javascript>

<javascript>var a = "fred"; // good in both Unity and JavaScript, no performance hit in Unity</javascript>

3) You must declare variables before using them. You can, and generally should, explicitly declare variables as having types (helps code to run faster, detects some errors at compile-time -- which is excellent, and others at run time -- which is less excellent).

<javascript>a = "fred"; // works in JavaScript, error in Unity</javascript>

<javascript>var a = "fred"; // a is now a string variable containing 'fred' var b: String; // b is now a string variable, with no assigned value b = "wilma"; var c; // c is now a dynamically typed variable with no assigned value c = "barney"; c = 17;</javascript>

3a) You can (and often should) explicitly scope variables as private, static, etc.

3b) Unity will implicitly type a variable if you assign it a value when you declare it. So:

<javascript>var a = "fred"; // a is now of type String a = 5; // ERROR! -- a is a String var b : String = "fred"; // redundant</javascript>

But: <javascript>var a; // a is dynamically typed; a = "fred"; // works a = 5; // works</javascript>

4) Method (and class) names are generally capitalized, except when they aren't. (It's confusing.) Basically, Unity's JavaScript is living in a .NET naming convention world (where methods are CamelCase and properties are camelCase), but is also trying to be like JavaScript (which, like C, is strongly biased towards lowercase and camelCase for everything).

e.g. in JavaScript typeof("fred") == 'string', but in Unity the type you write var a: String;

5) JavaScript has, in essence, three types: number, string, and Object (with functions and arrays in essence being Objects). Unity's JavaScript has many more types, including:

Objects, which are NOT interchangeable with arrays, or Arrays (which are somewhat like JavaScript's objects, but not dynamic): <javascript>var a = new Object(); // works a.fred = "wilma"; // runtime exception!</javascript>

native arrays (which are not associative or dynamic): <javascript>var a = [1, 2, 3]; a.Push(4); // ERROR -- won't work!</javascript>

Mono Arrays (which are associative and dynamic, but not with the same syntax sugar as Objects): <javascript>var a = new Array(); a.Push(4); // This works</javascript>

integer types (including int, uint32, etc.)

float

And Unity's many built-in classes (e.g. Vector3)

5a) Unity's String class lacks many of the nicer features of JavaScript's strings.

5b) Unity's internal arrays are far less flexible than JavaScript's arrays or objects. In general, you'll probably want to use Mono's Array object if you want flexibility, and Unity's internal arrays if you want performance.

6) It's important to understand that when you write a behavior script in JavaScript you are actually writing a class implementation, where:

a) The name of the class is the name of the script file (so if it's foo.js you can instance it elsewhere by saying var x = new foo()).

b) Certain "magic" method names will in fact implement event handlers (e.g. Start(), FixedUpdate() etc.). In any event, a function declaration is a method of the class you've written.

c) Code written outside function definitions inside your file are executing in the class's body. Variables declared in it are members of the class.

d) static functions and variables in a class are, in essence, class functions and variables.

This is all FAR more elegant than implementing classes in "real" JavaScript, but also somewhat restrictive ... mostly in a good way (you can't arbitrarily wire objects together the way you can in "real" JavaScript).

For example, if I create a new behavior and name it foo, the file will be named foo.js. Let's suppose foo.js looks like this: <javascript>public name : String; // when you drag the behavior onto a gameobject, these values will be visible and editable public age : int; // other scripts which have a reference to this object (e.g. if they're attached to the same object) can see public functions private favoriteColor : Color; // private members are NOT visible to other scripts, even if they have a reference to this object public bestFriend : foo; // you can assign a value to bestFriend by dragging a gameObject with an attached copy of the foo behavior to this property. This will give you access to bestFriend's public methods and members static faction : String; // static properties are visible globally, so another script can look at foo.faction

function Update(){

 // this function will be called every frame by Unity, so it's actually an event handler
 var t = transform; // transform is a property inherited from the gameObject the behavior is attached to

}

function Bar(){

 // this is just a function, if you don't call it yourself, it will never do anything

}

static function FooBar(){

 // this is a global function. Other scripts in the same scene can call foo.FooBar();

}</javascript>

7) Some early versions of Unity did not support JavaScript switch() statements, but both Unity 1.6 and Unity 2.0 do.

7a) Unity 1.x does not support eval, but Unity 2.x does -- possibly only in the dev environment (?). Doesn't matter -- Don't use eval.

8) Semicolons are generally optional in JavaScript (which has some ferocious logic to determine when a statement ends) but very much not optional in Unity.

<javascript>var foo = 3 // OK in JavaScript but an error in Unity foo += 17</javascript>

9) You can't define functions quite as freely in Unity.

<javascript>function foo(){} // OK in both var bar = function(){} // error in Unity</javascript>

Note that most of JavaScript's other niceness w.r.t. functions is retained, e.g.

<javascript>function foo(x){ print(x); } var bar = foo; bar("test"); // works just fine in Unity</javascript>

10) JavaScript's annoying Math library (because, really, stuff like abs() should just be in the language) becomes Unity's (also annoying) Mathf library. And remember, method names are usually capitalized (in Unity) so Math.abs() becomes Mathf.Abs().

Debugging

Scripting errors will show in Unity as a "red x icon" in the window status bar. Click on the icon to bring up the console, showing a list of errors, which should be both informative and lead you to the line in the script that caused the problem.

Unity also generates useful warnings (with a "blue ! icon") e.g. telling you a variable you've declared isn't used anywhere. Striving to write code that never generates warnings is a very useful habit.

The print() function will produce messages in the status bar and console. You can also use Log("insert message here"); and Debug.Log("insert message here");

Although Unity does not have a conventional "stop, watch, and step" debugger, the editing GUI is completely live when running projects in the development environment (e.g. instances created at runtime appear in the browsers and you can click on them and look at their internal state).

Personal tools
Namespaces

Variants
Actions
Navigation
Extras
Toolbox