This section covers some details about how JavaScript code is run in Construct.
Expressions aren't exposed to script
Construct's event sheets fundamentally work differently to code. Consequently object expressions that you may enter in to conditions and actions are not directly accessible from script. Refer to the scripting reference for the methods and properties that are directly accessible from scripts. You can also still indirectly access things that are not directly exposed to scripts by passing values between scripts and event sheets - for an example of that see integrating events with script.
Case sensitivity
Many features in Construct are case insensitive, such as "Player" being considered equilvant to "player". However the JavaScript programming language is case sensitive. Therefore when referring to objects, variables and other items in your project from JavaScript code, you must use the same case as it was written with in Construct.
Modules
All scripts in Construct are JavaScript Modules. This allows use of the import and export syntax. It also has a few differences to the legacy "classic" mode scripts, notably:
- Each module (script file) has its own top-level scope. This means top-level declarations are not globally accessible. Instead prefer to use imports and exports, or if you have to, explicitly use properties of
globalThis to make them global.
- Modules run code in strict mode. This eliminates common problems such as silent errors, typos accidentally creating 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.
See the Imports & exports example for a demonstration of using modules in Construct.
Worker mode
When the Use worker project property is Yes, 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.
The default mode for Use worker is Auto. This means Construct automatically decides whether to run your project in a Web Worker or the DOM. Currently this means it will run in a worker unless your project uses any JavaScript code, in which case it will run on the DOM on the assumption your code will need to make use of DOM APIs. Note however that this loses the performance benefits of worker mode. If your JavaScript code can run in a Web Worker, you can change the setting back to Yes and gain the performance benefits.
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.
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.