Construct 3 icon

Construct 3

Documentation

JavaScript in Construct

Ashley's avatar
Medal
Construct Team Founder
Published 28 May, 2019
800 words
~3-5 mins

This section covers some details about how JavaScript code is run in Construct.

Strict mode

All JavaScript code in Construct is run in strict mode. This eliminates common problems such as silent errors, typos accidentally creating global variables, and fixes some aspects of the language considered mistakes. In particular it helps avoid confusing problems that beginners often run in to. Since all code is already run in strict mode, there is no need to add the "use strict" directive to any of your code.

Worker mode

When the Use worker project property is checked, the Construct runtime is hosted in a Web Worker instead of in the DOM, and renders using an OffscreenCanvas. This is generally good for performance since the runtime can run independently of the browser main thread, which can be blocked by browser tasks like layout. However Web Workers have a reduced set of APIs available. Notably there are no window or document objects available, and so the DOM cannot be directly accessed. However there are many other APIs still available, such as fetch (and the older XMLHttpRequest), IndexedDB, WebSocket and others - see Functions and classes available to workers for more details.

If your JavaScript code heavily depends on accessing the DOM or using APIs not yet available in workers, the simplest solution may be to leave Use worker unchecked so the runtime continues running in the DOM. Note however that this loses the performance benefits of worker mode.

Accessing global scope

Sometimes the window object is used to refer to global scope, such as with window.myGlobal = 1;. Note however that the window object is not available in worker mode, so this won't work there.

The standard way of accessing the global scope is with globalThis, such as with globalThis.myGlobal = 1;. Since this is available in both the DOM and Web Workers, this code will work everywhere. Construct also polyfills this if it is missing, so there is no need to worry about browser support.

In a browser context you can also use self to refer to the global scope in both the DOM and workers. However this is not available in other JavaScript environments like node.js, so if you want to write code that can run anywhere, it is better to use globalThis.

Browser/platform support

When using the very latest JavaScript features, you may need to check which browsers support it. If you use a JavaScript feature that not all browsers or platforms support, you may get an error trying to run your game on that platform. We recommend the MDN web docs as a good place to check compatibility.

You can also rely on modern support for JavaScript being available, because Construct only supports scripting in the C3 runtime, and the C3 runtime itself only supports relatively modern browsers. For example the C3 runtime does not support Internet Explorer so you do not need to worry about supporting it at all. You can use many modern JavaScript features like classes, arrow functions, default parameters, rest parameters, async functions, generator functions and iterators, Maps and Sets with the confidence they will work everywhere your game is supported.

Note many older code examples across the web use an older style designed to support defunct browsers. For example many old code examples use var to declare variables, whereas in modern JavaScript let and const are preferred. Bear this in mind when looking at other code examples, and note there may be modern features that can considerably simplify the code. It can be a good idea to update any code snippets you use in your projects to a modern style.

Modules

Construct does not yet make use of JavaScript Modules. All scripts are run as "classic" scripts, as when added by a <script> tag. This means the import and export keywords cannot be used. However dynamic imports, using the await import(...) syntax, can still be used.

Undocumented features

If you explore the functions and variables available in a debugger, you may find undocumented APIs specific to the Construct engine. The only reason these can be found is because the way JavaScript works makes it difficult to hide them. Do not use any such undocumented features in your JavaScript code. These are internal details of the Construct engine and can change at any time, and such changes can easily break your code. No support will be provided for undocumented APIs, even if engine changes break your code. Responsible developers know to only use documented and officially supported APIs. These can be found in the scripting reference. If new engine functionality is essential to you, please file a feature request.

Note this only applies to the Construct engine - all other browser APIs are of course available for use.