Construct 3 icon

Construct 3

Documentation

Script files

Ashley's avatar
Medal
Construct Team Founder
Published 28 May, 2019
592 words
~2-4 mins

For those more familiar with JavaScript coding, script files provide a code editor to write a JavaScript file which works independently of the event sheet.

Adding script files

Script files can be added in the Scripts folder of the Project Bar. Existing JavaScript files (.js) can also be imported using the Import scripts option instead.

Once you add a script a code editor appears with some default code added to help you get started.

Execution of script files

Script files are run just after the Construct engine scripts run. This is before any loading screen appears. It is a good place to write any initialization code and any global functions or properties your entire project will use. Since the Construct engine has still not yet initialised at this point, there is no runtime variable (representing the runtime script interface) available at the top level. Instead there is a special runOnStartup function that runs a callback once the runtime is ready, and provides the runtime variable as a parameter.

runOnStartup(async runtime =>
{
	// This code runs on startup with
	// the 'runtime' variable available
});

The callback can be an async function, meaning the await keyword can be used inside it. The top-level scope of a script is not allowed to use await, so this is a convenient place to run any asynchronous initialization, while also making use of the runtime script interface. All callbacks passed to runOnStartup are executed simultaneously just as the loading screen appears, and the runtime will wait for all the async functions to complete before starting the game.

Continuing execution

The only code in a script file that is automatically executed is the top-level scope and any runOnStartup callbacks. Beyond that no code in your script will run any more, unless you add event listeners to run callbacks. The main event to listen for is the runtime "tick" event. Since this fires every tick it provides a good place to keep running JavaScript code throughout your game. The code example below demonstrates a typical way to use this.

runOnStartup(async runtime =>
{
	runtime.addEventListener("tick", () => Tick(runtime));
});

function Tick(runtime)
{
	// Code to run every tick.
	// Note 'runtime' is passed.
}

Integration with scripts in events

Any declarations at the top level of a script file are in the global scope. For example the function myFunction below is available globally.

function myFunction()
{
    // do something useful...
}

This can then be called by scripts in event sheets. For example it could be called in a script action with myFunction(). This provides a useful way to write a library of functions that can be used by code anywhere else in the project, and is another good way to closely integrate event sheets with your JavaScript code.

Errors

Unlike scripts in event sheets, errors arising from the top level of script files are not automatically handled by Construct. If an unhandled exception is thrown, the browser will halt any further execution of script in that file. Typically this causes the rest of your code to stop working, and is considered a crash. See the section debugging scripts to find out how to deal with such issues.

Note one difference is exceptions or rejections in a runOnStartup callback are automatically handled by Construct. The error will be logged to the browser console and the runtime will continue to start up and run the game - but note if an error occurred it may not run as expected.