This is part 12 of the tutorial series Learn TypeScript in Construct. This part continues on from part 11. So in case you missed it, see Learn TypeScript in Construct, part 11: Standard library.
In this guide we've covered some of the built-in features - also known as APIs - of the TypeScript programming language, and touched on a few browser APIs too. Now we'll cover some of the APIs that Construct provides. These parts are specific to Construct and so will either be unavailable or work differently in other platforms or tools, even if they use TypeScript. However it's still useful to know how to use Construct's own APIs since we're working in Construct, and it lets us write code that uses Construct features like sprites. Many platforms also provide their own specific APIs, so it also demonstrates how to get up and running with another set of APIs.
Moving a sprite
One of the simplest tasks we can do with TypeScript coding in Construct is just move a sprite when a button is clicked. We'll go back to using snippets of code in event sheets to get this working. Download the project below and open it in Construct. It provides a sprite and a button, and a Button clicked event.
Open the Event sheet 1 tab so you can see the Button: On clicked trigger. Here we will add a piece of TypeScript in the place of an action to move the sprite. But before that, let's explain a few details about Construct's APIs.
The runtime
With scripts in event sheets, Construct automatically provides two additional built-in variables. These are:
runtime - representing the Construct runtime, i.e. the overall game engine powering your project. This is typically the main way you will access Construct features in TypeScript.localVars - representing any local variables in the event sheet that are in scope. This lets you get and set the value of these variables from TypeScript, which is useful for passing values between event sheets and code.
We won't need localVars for now - we'll focus on runtime.
We can have a look at what runtime looks like by taking advantage of TypeScript's precise autocomplete. Add TypeScript code to the On clicked event, and then in the code editor, type runtime. - when you type that last dot, thanks to TypeScript's type system you'll see a scrollable list of all the properties and methods you can use on runtime.
The built-in runtime variable is a class named IRuntime. As we learned previously, the name of a class is also its type, so the type of the runtime variable is also IRuntime. Every property and method it has is documented in the Scripting section of the manual. You can find the IRuntime reference here, which covers everything you can see in the console. TypeScript's autocomplete will list everything available from the IRuntime class which is a good way to start exploring available APIs, but it's still a good idea to refer to this documentation to check how to use the available properties and methods.
Objects and instances
All the objects in your project - that is, everything under Object types in the Project Bar - are represented under runtime.objects. For example, runtime.objects.Sprite represents the Sprite object type in the Project Bar.
It's important to note that runtime.objects.Sprite refers to an object type. This is different to an object instance. If you have 10 instances of a Sprite, then there is still only one Sprite object type, and there are 10 instances. The object type has properties such as the name of the object, and the instances have properties like a position and size. A common mistake is to mix them up and try to access the position of an object type. But object types don't have a position - only instances do. TypeScript's type system it will mark mistaken usages of objects as an error. Remember you can use autocomplete (which appears when you type a . after an object) to see the properties and methods you are allowed to use.
If we want to get or change the position of a sprite instance, we must first get the instance of the Sprite object type that is already in the layout. If there's only one, the easiest way to do that is to call getFirstInstance() on the object type, i.e. runtime.objects.Sprite.getFirstInstance(). That then returns an instance with a position, size etc.
Change your TypeScript code in the event sheet to the following:
let inst = runtime.objects.Sprite.getFirstInstance();
inst.x += 10;
However TypeScript will mark an error on the second line. The reason for this is getFirstInstance() is allowed to return null if there are no instances of the Sprite object type. TypeScript doesn't know if there are any instances or not, it just knows the result might be null, and it's not valid to try to access a property of null.
There are a couple of ways to solve this - for example you could use an if statement to check that inst is not null. However our preferred solution in this case is to use the non-null assertion operator, which is written as a ! after an expression. This tells TypeScript to ignore the possibility the expression may be null. This is safe because while TypeScript doesn't know if the result is null, we know that there is always an instance of the Sprite object and so it will never return null. Therefore if you change the code to the following, with the addition of ! after getFirstInstance(), it will fix the error.
// Note trailing '!'
let inst = runtime.objects.Sprite.getFirstInstance()!;
inst.x += 10;
This code then gets the first instance of the Sprite object type (the one already placed in the layout) and stores a reference to it in the variable inst. Then it adds 10 to the X co-ordinate of the instance, which will move it to the right. Try previewing the project and clicking the button - the sprite instance moves to the right!
Types and documentation
Construct uses lots of its own classes to represent things like object instances, and it's useful to explain these a bit more, and how you can use the documentation as a reference for them too.
runtime.objects.Sprite is a class named IObjectType. This class also inherits IObjectClass. We didn't cover the inheritance feature of classes in this guide, but it basically means IObjectType includes all the properties and methods of IObjectClass, and then adds some more of its own. In the linked documentation you can find that the method getFirstInstance() is listed and documented (as part of IObjectClass), along with various other properties and methods. You can also find getFirstInstance() in the autocomplete list when you type runtime.objects.Sprite..
The returned instance includes the properties and methods of IWorldInstance (so named as objects appearing in the layout are part of the game "world", whereas things like a Dictionary or an Array object are not). In the linked documentation you can find the properties x and y are listed and documented, along with various other properties and methods, which you'll also see in the autocomplete list when typing inst..
The type of the instance is actually a little bit more complicated than that. Sprite instances are classes named ISpriteInstance, which also inherits from both IWorldInstance and IInstance. This means Sprite instances can use the properties and methods of all three classes. However each object type can have its own instance variables, behaviors and effects, which needs to be defined as part of the class for TypeScript to be able to validate everything correctly. Therefore Construct actually generates a class named InstanceType.Sprite to represent instances of the Sprite object type specifically that includes those details. This is the actual type of the inst variable. This class inherits ISpriteInstance, IWorldInstance and IInstance, so the properties and methods of all of them are available.
As writing code in Construct frequently involves using instances, it's important to be clear about these different classes. Another way to look at them is like a hierarchy going from most specific to least specific:
InstanceType.Sprite is specifically the type of an instance of the Sprite object type. This covers the instance variables, behaviors and effects for the object type.ISpriteInstance is the type of any sprite instance from any object type, so long as it comes from the Sprite plugin.IWorldInstance is the type of any instance that appears in the layout (or "world"), including other kinds of plugins like Tiled Background, Particles, etc.IInstance is the least specific type and is the type of any object instance of any kind in Construct, including data objects like Array, Dictionary and so on.
Which type you use depends on how specific the code you are writing is. For example if you want to make a function that changes the position of an object instance, it can use the type IWorldInstance to work with any instance that has a position. On the other hand if you wanted to do a calculation involving a specific object type's instance variables, it should use the specific instance type like InstanceType.Sprite.
We're highlighting the class hierarchy as it's important to understand the relevant types when writing TypeScript code. We're also pointing out the documentation as it's an important reference to use: while autocomplete is handy, it doesn't tell you much about how to use the listed features, and the documentation explains that.