Learn JavaScript in Construct, part 11: Construct APIs

14

Index

Attached Files

The following files have been attached to this tutorial:

.c3p

move-sprite.c3p

Download now 62.55 KB
.c3p

using-script-file.c3p

Download now 62.64 KB
.c3p

keyboard-controls-template.c3p

Download now 62.62 KB
.c3p

modify-sprites-template.c3p

Download now 62.92 KB

Stats

6,758 visits, 17,475 views

Tools

Translations

This tutorial hasn't been translated.

License

This tutorial is licensed under CC BY-NC 4.0. Please refer to the license text if you wish to reuse, share or remix the content contained within this tutorial.

This is part 11 of the tutorial series Learn JavaScript in Construct. This part continues on from part 10. So in case you missed it, see Learn JavaScript in Construct, part 10: Standard library.

In this guide we've covered some of the built-in features - also known as APIs - of the JavaScript 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 JavaScript. 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 JavaScript 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.

.C3P

move-sprite.c3p

Download now 62.55 KB

Open the Event sheet 1 tab so you can see the Button: On clicked trigger. Here we will add a piece of JavaScript 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 JavaScript.
  • 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 JavaScript, which is useful for passing values between event sheets and JavaScript.

We won't need localVars for now - we'll focus on runtime.

We can have a look at what runtime looks like in the browser console. Add a script to the On clicked event with this code:

console.log(runtime);

This just logs the built-in runtime variable to the browser console. Preview the project, click the button, and check the console. You should be able to expand it and see all sorts of properties and methods.

The built-in runtime variable is a class named 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. It's a good idea to refer to this documentation to check what properties and methods are available and how to use them. However looking at things in the console is also a quick way to explore what something is and what it can do.

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.

So 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 JavaScript code in the event sheet to the following:

let inst = runtime.objects.Sprite.getFirstInstance();
inst.x += 10;

This will get the first instance of the Sprite object type (the one already placed in the layout) and store it in a 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!

Documentation

Once again it's useful to refer to the documentation and see what we've used.

runtime.objects.Sprite is a class named IObjectClass (so named as it is also used for families, i.e. "object class" means "either an object type or a family"). In the linked documentation you can find that the method getFirstInstance() is listed and documented, along with various other properties and methods.

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.

We're highlighting the documentation as it's an important reference to use when finding out what Construct features you can use from JavaScript. The editor will often try to autocomplete names as you type, but since JavaScript is a dynamic language it's not usually able to tell what properties and methods are actually available, and so it will tend to suggest everything. To know what is really available and what you can actually use, you'll need to refer to the documentation. After regular use you'll start to remember what the common properties and methods are and not need to keep looking them up.

Next Tutorial In Course

Learn JavaScript in Construct, part 12: Modules 14:40

Learn how to organise code with JavaScript Modules, including how they are used in Construct.

  • 3 Comments

  • Order by
Want to leave a comment? Login or Register an account!
  • How can I pick an instance by an instance variable?

    • Just in case this is still relevant (for anyone with the same question): check out the fairly new example titled "Generator Function" for one way; but using generator functions is not required, you can just do that too:

      for (const inst of runtime.objects.SomeObjectType.instances())

      {

      if (inst.instVars.SomeInstanceVariable === 42) {...}

      }

  • does not help