A Crash Course in C#

When writing scripts for Unity games, you write in a language called C#. We’re not going to explain the fundamentals of programming in this book (we don’t have the space!), but we’ll highlight some main points to keep in mind.

To give you a quick introduction, we’ll take a chunk of C# code, and highlight some important elements:

using UnityEngine; 

namespace MyGame { 

    [RequireComponent(typeof(SpriteRenderer))] 
    class Alien : MonoBehaviour { 

        public bool appearsPeaceful; 

        private int cowsAbducted;

        public void GreetHumans() {
            Debug.Log("Hello, humans!");

            if (appearsPeaceful == false) {
                cowsAbducted += 1;
            }
        }
    }
}

The using keyword indicates to the user which packages you’d like to use. The UnityEngine package contains the core Unity types.

C# lets you put your types in namespaces, which means that you can avoid naming collisions.

Attributes are placed between square brackets, and let you add additional information about a type or method.

Classes are defined using the class keyword, and you specify the superclass after a colon. When you make a class a subclass of MonoBehaviour, it can be used as a script component.

Variables attached to classes are called fields.

Mono and Unity

Unity’s scripting system is powered by the Mono framework. Mono is an open source implementation of Microsoft’s .NET Framework, which means that in addition to the libraries that come with Unity, you also have the complete set of libraries that come with .NET.

A common misconception is that Unity is built on top of Mono. Unity is not built on Mono; it merely uses Mono as its scripting engine. Unity supports scripting, through Mono, using both the C# language and the UnityScript language (what Unity calls “JavaScript;” see Languages in Unity).

The versions of C# and the .NET Framework available in Unity are older than the most current versions. At the time of writing in early 2017, the version of the C# language available is 4, while the version of the .NET Framework available is 3.5. The reason for this is that Unity uses its own fork of the Mono project, which diverged from the mainline branch several years ago. This has meant that Unity can add features that are specific to their uses, which are primarily mobile-oriented compiler features.

Unity is in the middle of updating its compiler tools to make the latest versions of the C# language and the .NET Framework available to users. Until that happens, your code will be a few versions behind.

For this reason, if you’re looking for C# code or advice around the web, you should search for Unity-specific code most of the time. Similarly, when you’re coding C# for Unity, you’re going to be using a combination of Mono’s API (for generic things that most platforms provide) and Unity’s API (for game engine-specific things).

Game Objects, Components, and Scripts

Unity scenes are composed of game objects. On their own, they’re invisible objects, and have nothing but a name. Their behavior is defined by their components.

Components are the building blocks of your game, and anything you see in the Inspector is a component. Each component has a different responsibility; for example, Mesh Renderers display 3D meshes, while Audio Sources play sound to the user. Scripts that you write are components as well.

To create a script:

1. Create the script asset. Open the Assets menu, and choose Create → Script → C# Script.

2. Name the script asset. A new script file will appear in the folder you had selected in the Project panel, ready for you to name.

3. Double-click the script asset. The script will open in the script editor, which defaults to MonoDevelop. Most of your scripts will start off looking like this:

   using UnityEngine;
   using System.Collections;
   using System.Collections.Generic;
   
   public class AlienSpaceship : MonoBehaviour { 
   
       // Use this for initialization
       void Start () { 
   
       }
   
       // Update is called once per frame
       void Update () { 
   
       }
   }

   

   The name of the class, in this case AlienSpaceship, must be the same as the asset filename.

   

   The Start function is called before the Update function is called for the first time, and is where you might put code that initializes variables, loads stored preferences, or sets up other scripts and GameObjects.

   

   The Update function is called every frame, and is an opportunity to include code that responds to input, triggers another script, or moves things around—anything that needs to happen.

Script assets in Unity do not actually do anything—none of their code is executed—until they are attached to a GameObject (seen in Figure 3-1). There are two main ways to attach a script to a GameObject:

1. Dragging the script asset onto the GameObject. This can be done with either the Inspector or the Hierarchy panel.

2. Using the Component menu. You will find all the scripts that are in the project under Component → Scripts.

Figure 3-1. The Inspector for a GameObject, showing a script called “PlayerMovement” added as a component

Since scripts are primarily exposed in the Unity editor through being attached, as components, to GameObjects, Unity allows you to expose properties in your script as editable values in the Inspector. To do this, you create a public variable in your script. Everything specified as public will be visible in the editor; you can also set variables to private, though.

public class AlienSpaceship : MonoBehaviour {
    public string shipName;

    // "Ship Name" will appear in the Inspector
    // as an editable field
}

// gets the Animator component on this object, if it exists
var animator = GetComponent<Animator>();

Important Methods

Your MonoBehaviours have several methods that are particularly important to Unity. These methods are called at different times during the component’s life cycle, and are opportunities to run the right behavior at the right moment. This section lists the methods in the order that they’re run.

// In a file called ObjectA.cs
class ObjectA : MonoBehaviour {

    // A variable for other scripts to access
    public Animator animator;

    void Awake() {
        animator = GetComponent<Animator>();
    }
}

// In a file called ObjectB.cs
class ObjectB : MonoBehaviour {

    // Connected to the ObjectA script
    public ObjectA someObject;

    void Awake() {
        // Check to see if someObject has set its 'animator'
        // variable
        bool hasAnimator = someObject.animator == null;

        // May print 'true' OR 'false', depending on which
        // one happens to run first
        Debug.Log("Awake: " + hasAnimator.ToString());
    }

    void Start() {
        // Check to see if someObject has set its 'animator'
        // variable
        bool hasAnimator = someObject.animator == null;

        // Will *always* print 'true'
        Debug.Log("Start: " + hasAnimator.ToString());
    }
}

Coroutines

Most functions do their work and return immediately. However, sometimes you need something to take place over time. For example, if you want an object to slide from one point to another, you need that movement to happen over multiple frames.

A coroutine is a function that runs over multiple frames. In order to create a coroutine, first create a method that has a return type of IEnumerator:

IEnumerator MoveObject() {

}

Next, use the yield return statement to make the coroutine temporarily stop, allowing the rest of the game to carry on. For example, to make an object move forward by a certain amount every frame,¹ you’d do this:

IEnumerator MoveObject() {
    // Loop forever
    while (true) {

        transform.Translate(0,1,0); // move 1 unit on the Y
                                    // axis every frame

        yield return null; // wait until the next frame

    }
}

When you yield return from a coroutine, you temporarily pause the execution of the function. Unity will resume execution later; the specifics of when it resumes depends on what value you yield return with.

For example:

yield return null

waits until the next frame

yield return new WaitForSeconds(3)

waits three seconds

yield return new WaitUntil(() => this.someVariable == true)

waits until someVariable equals true; you can also use any expression that evaluates to a true or false variable

// stop this coroutine immediately
yield break;

Once you have a coroutine function, you can start it. To start a coroutine, you don’t call it on its own; instead, you use it in conjunction with the StartCoroutine function:

StartCoroutine(MoveObject());

When you do this, the coroutine will start executing until it either reaches a yield break statement, or it reaches the end.

It’s also possible to stop a coroutine from outside of it. To do this, keep a reference to the return value of the StartCoroutine method, and pass it to the StopCoroutine method:

Coroutine myCoroutine = StartCoroutine(MyCoroutine());

// ... later ...

StopCoroutine(myCoroutine);

Creating and Destroying Objects

There are two ways to create an object during gameplay. The first is by creating an empty GameObject, and attaching components to it by using code; the second involves duplicating another object (called instantiation). The second method is more popular because you can do everything in a single line of code, so we’ll discuss it first.

public GameObject myPrefab;

void Start() {
    // Create a new copy of myPrefab,
    // and position it at the same point as this object
    var newObject = (GameObject)Instantiate(myPrefab);

    newObject.transform.position = this.transform.position;
}

// Create a new game object; it will appear as
// "My New GameObject" in the hierarchy
var newObject = new GameObject("My New GameObject");

// Add a new SpriteRenderer to it
var renderer = newObject.AddComponent<SpriteRenderer>();

// Tell the new SpriteRenderer to display a sprite
renderer.sprite = myAwesomeSprite;

// Destroy the game object that this script is attached to
Destroy(this.gameObject);

Attributes

An attribute is a piece of information that you can attach to a class, variable, or method. Unity defines several useful attributes that you can use, which change the behavior of the class or how it’s presented in the Editor.

[RequireComponent(typeof(Animator))]
class ClassThatRequiresAnAnimator : MonoBehaviour {
    // this class requires that an Animator also
    // be attached to the GameObject
}

Header and Space

The Header attribute, when added to a field, causes Unity to draw a label above the field in the Inspector. Space works similarly, but adds empty space. Both are useful for visually organizing the contents of the Inspector.

For example, Figure 3-2 shows the Inspector’s rendering of the following code:

  public class Spaceship : MonoBehaviour {

      [Header("Spaceship Info")]

      public string name;

      public Color color;

      [Space]

      public int missileCount;
  }

Figure 3-2. The Inspector, showing header labels and spaces

class Monster : MonoBehaviour {

    // Appears in Inspector, because it's public
    // Accessible from other scripts
    public int hitPoints;

    // Doesn't appear in Inspector, because it's private
    // Not accessible from other scripts
    private bool isAlive;

    // Appears in Inspector, because of SerializeField
    // Not accessible from other scripts
    [SerializeField]
    private int magicPoints;

    // Doesn't appear in Inspector, because of HideInInspector
    // Accessible from other scripts
    [HideInInspector]
    public bool isHostileToPlayer;
}

[ExecuteInEditMode]
class LookAtTarget : MonoBehaviour {

    public Transform target;

    void Update() {
        // Don't continue if we don't have a target
        if (target != null) {
            return;
        }

        // Rotate to look at target
        transform.LookAt(target);
    }

}

Time in Scripts

The Time class is used to get information about the current time in your game. There are several variables available in the Time class (and we strongly recommend you look at the documentation for it!), but the most important and commonly used variable is deltaTime.

Time.deltaTime measures the amount of time since the last frame was rendered. It’s important to realize that this time can vary a lot. Doing this allows you to perform an action that’s updated every frame, but needs to take a certain amount of time.

In “Coroutines”, the example we used was one that moves the object one unit every frame. This is a bad idea, because the number of frames in a second can vary quite a lot. For example, if the camera is looking at a very simple part of your scene, the frames per second could be very high, whereas looking at more visually complex scenes could result in very low framerates.

Because you can’t be sure of the number of frames per second you’re running at, the best thing to do is to take into account Time.deltaTime. The easiest way to explain this is with an example:

IEnumerator MoveSmoothly() {
    while (true) {

        // move 1 unit per second
        var movement = 1.0f * Time.deltaTime;

        transform.Translate(0, movement, 0);

        yield return null;

    }
}

Logging to the Console

As we saw in “Awake and OnEnable”, it’s sometimes convenient to log some information to the Console, either for diagnostic purposes, or to warn you about some problem.

The Debug.Log function can be used to do this. There are three different levels of logging: info, warning, and error. There’s no functional difference between the three types, except warnings and errors are each more visible and prominent than the last.

In addition to Debug.Log, you can also use Debug.LogFormat, which allows you to embed values in the string that’s sent to the Console:

Debug.Log("This is an info message!");
Debug.LogWarning("This is a warning message!");
Debug.LogError("This is a warning message!");

Debug.LogFormat("This is an info message! 1 + 1 = {0}", 1+1);

Wrapping Up

Scripting in Unity is a critical skill, and becoming comfortable with both the C# language and the tools used for writing it will make building your game easier and more fun to do.