The Complete Guide to the Unity Scripting API

Unity is by far the most popular game development engine out there. Its user-friendly world view lets you add objects to the game scene and immediately see the results. It’s true that Unity isn’t limited to making games. However, it usually lacks the feature set for other kinds of software development. That said, it is a powerhouse for feature-rich interactive graphic applications.

The reason for this is that at its core Unity has a game engine – a piece of code that updates every game object periodically. These updates can be driven by the built-in physics engine, or by the developers code.

Like many technologies, programming languages and component libraries, Unity may seem simple enough. But the deeper you dive, the more complex it gets. This deep-dive will, sooner or later, lead you to Unity API scripting. 

Maybe you’ve already played around Getting Started with Unity. Perhaps you’re just gathering information about Unity before picking it up. In either case you may have come across the term ‘Unity Scripting API’ and decided to Google it, This probably landed you on the unhelpful front page of the Unity Scripting API. 

Fortunately, you decided to go back to the search results page and so find yourself here, where yours truly will do her best to explain what Unity Scripting API is and what you can do with it.

What is the Unity scripting API?

API stands for Application Programming Interface. What it essentially means is “a way to interact with a piece of software through code”. Any software that is meant to be interacted with has an API. If you are lucky, it is a well documented one, so you don’t have to guess what the different access points are.

Unity Scripting API is a way to programmatically interact with Unity’s game engine and editor. Every object you can add onto a scene has a Class, and that class has an API you can manipulate through code. 

It is possible to make a game (or other form of software) with Unity without using the API thanks to Unity’s rich editor and physics engine. However, the vast majority of Unity developers will realize very early on in their journey that they need to write at least a few scripts to accomplish their goals.

Unity supports two API languages. One is called UnityScript, which looks a lot like Javascript but is in fact very different. The other is C#. Note that Unity is looking to discontinue UnityScript. Considering this, if you’re just starting out with Unity API, I recommend that you start with C#. That said, from the perspective of the API they are identical. If an access point exists for Unityscript it also exists for C# and vice versa. At least the time of writing.

What you can do with the Unity scripting API

You can do almost anything with the Unity scripting API. But that isn’t a very useful answer. Most objects you add onto a scene have properties, and those properties can be changed in the editor, via the inspector, or through code. 

The properties define many things about an object such as its color, its interaction with the game engine, and even its position in the world.

There are also many classes, and therefore API methods, for invisible behind-the-scenes functionality. The SceneManager is one such class. It allows you to load a new scene using code. You can also use the API to log messages in the console, or check how much time has passed since the game started.

Here is an example of something you can’t do without the API. 

First, let’s start up Unity and create a new project.

Call it ButtonExample, and create. When your project has loaded up, add a Button by right licking under the Hierarchy -> UI -> Button

With the Button selected, make sure the xpos and ypos of the button are 0. Often Unity will create new objects outside the camera area, which makes them quite hard to see!

Now if you run the scene, you will find a Button that you can click but doesn’t actually do anything. There are some things you might be able to do with a button that do not involve code, but those are very rare.

With the Button still selected, right at the bottom of the Inspector you can click Add Component, and click the new script at the bottom of the list. Name it Example. Right click the new added script and click Edit. This will load up the script in an editor, Visual Studio if you had that installed during setup.

The code you will see will look like this:

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class Example : MonoBehaviour
{
    // Start is called before the first frame update
    void Start()
    {
        
    }

    // Update is called once per frame
    void Update()
    {
        
    }
}

Let’s say you want something to happen when the Button is clicked. But how? This is where the Scripting API comes in handy. You could Google “unity button clicked script”, and you would likely be pointed at the scripting API by someone answering someone else’s question. 

Since we’re here to learn how the Scripting API documentation can be helpful, let’s explore the documentation here.

If you browse to UnityEngine -> UnityEngine.UI -> Classes -> Button, you will be greeted with a page that has all the methods in a Button. This is the API documentation for the Button class. 

There are many ways to activate code when a button is pressed. For this example, we’ll create a simple one. 

We can see there is a public method OnPointerClick, but how do we use it? If we click on it, we are taken to a page with a nice code example. If we simply copy the code over and replace our Example script, we will see a log entry saying the button was clicked!

Unity scripting API hierarchy

The hierarchy of the API is split into several top level namespaces, and those then have other namespaces under them. Namespaces are simply a way to hierarchically sort code. The most interesting top level namespaces are UnityEngine and UnityEditor. 

While most developers will spend the majority of their time using the UnityEngine API, it is important to know of the existence of the UnityEditor API. Here you will be able to find ways to modify the editor itself, which can be a fantastic tool if you find yourself taking inefficient actions when editing scenes.

When clicking open on those namespaces you will find more namespaces inside. But under most you will also find Classes, which are the juicy parts where all the important information is stored. Classes are the building blocks of the engine, and those are the things you want to interact with.

Lastly, when you open a class, like we did with the Button, you can see a full list of methods, members and properties you can manipulate. Many of these have code examples detailing how to use them. 

Unity Scripting API reference documents may not seem friendly at first. But once you understand how to find what you’re looking for, you’ll discover it is very well explained.

Navigating the Unity API documentation

You could start reading through the API documentation, opening namespaces in search of what you’re looking for, but Google will do a much better job of getting you where you need to go. By simply searching for “Unity Button Clicked” you will find yourself in a relevant section of the API documentation. You may need to adjust your searches a few times before you land on the exact page you want, but you will always get relevant information.

If you have a particularly unique issue, you might find yourself on answer.unity.com, which is similar to stack exchange for Unity developers. There, other users will point you to the right page on the Scripting API.

To summarize, the scripting API is the phone book for your way into interacting with code in Unity. Like phone books, you don’t often browse through them nowadays. Instead, you Google (or DuckDuckGo) it, and the miracle of search engines will point you to where you need to read.