Construct for TypeScript developers quick start guide

UpvoteUpvote 4 DownvoteDownvote

Tagged

Features on these Courses

Stats

73 visits, 96 views

Tools

Share

Translations

This tutorial hasn't been translated.

Create a translation

License

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

Published on 10 Jun, 2025.

Construct supports writing TypeScript code in both script files and event sheets. If you are new to the JavaScript programming language, consider looking for a beginner tutorial. However if you already have some knowledge of TypeScript coding, this guide will help you quickly get up to speed with TypeScript in Construct.

JavaScript

If you are interested in using JavaScript in Construct, see the separate guide Construct for JavaScript developers quick start guide.

Compiling TypeScript

When writing TypeScript in Construct, it will be compiled to JavaScript using Construct's built-in TypeScript compiler. You don't need to add any .js files to your project - you only need to add a .ts file and the compilation to JavaScript happens automatically.

If you want to use an external code editor like VS Code, the workflow is different - for details on that see Using an external editor in the manual.

Modules

All TypeScript code in Construct runs in modules, based on the language-provided module system, also known as ES Modules or ESM. Construct does not currently directly support other module patterns like CommonJS or AMD.

Modules allow for using the import and export syntax, which is supported in Construct.

The main script

In Construct the main script is automatically loaded. This file appears bold in the Project Bar and has its Purpose property set to Main script. However other scripts are not automatically loaded by default - instead they must be imported in order to load and execute them.

Top-level scope

If you've not worked with modules before, note that top-level scope works differently in modules. Each module (script file) has its own top-level scope. This means top-level declarations are not globally accessible. Using imports and exports are preferable to global variables, but if you have to, use globalThis to access the global namespace, as demonstrated below. 

// In a module, this is scoped only to the same file.
let myGlobal = 0;

// In a module, this is now global.
globalThis.myGlobal = 0;

Note that TypeScript does not normally allow using undeclared global variables. To allow this, add a TypeScript definition file (with extension .d.ts) to your project, and add a line like this: 

declare var myGlobal: number;

This will then allow use of the global variable via globalThis.

Importing third-party scripts

Third-party scripts written in the modern ES Modules style should work normally in Construct. If you can, use a script based on ES Modules, or ask the third-party developer to provide one.

If you import an older third-party JavaScript file that does not use ES Modules, it may try to add something to the global namespace by using a top-level declaration. Since modules have their own scope, this means the script won't actually declare anything usable in other script files. These scripts have to be lightly modified to get them to work as modules. Some further advice and examples on modifying JavaScript files is in the Construct for JavaScript developers quick start guide.

You can import JavaScript files and import them to TypeScript files. This kind of interoperability relies on TypeScript's support for interoperability with JavaScript. You may need to provide additional type definition files (.d.ts) when doing this. You can import .d.ts files to your Construct project and it will use the definitions for type checking without outputting anything when you export your project.

Scripts in event sheets

When adding TypeScript code in an event sheet, it actually runs inside an async function. This allows use of await in such code snippets. The event system can then wait for a previous block of code to finish using the Wait for previous actions to complete system action.

Note that since these code snippets are inside functions, the use of import and export is not allowed, as these are not permitted inside functions. Further, any variable or function declarations will only be available in that snippet. Global variables can still be accessed using globalThis.

Referring to script files in event sheets

Scripts in event sheets are a concept unique to Construct. Therefore the way modules are accessed in scripts in event sheets is slightly different to the way script files work.

Scripts in event sheets are all combined in to a single script file. If a script in the project has the purpose Imports for events, its content is inserted to the top of that combined script file. This provides a way to use modules in scripts in event sheets.

For example suppose the Imports for events script uses the following import: 

import * from "./mymodule.js" as MyModule;

This then means all scripts in event sheets in the entire project can now refer to MyModule.

In fact the Imports for events script can declare variables and functions that can then be used in scripts in event sheets. However usually it is preferable to import a script, as that can also be shared with other script files.

The Imports for events script can also import the main script. This provides a convenient way to call functions exported from the main script from event sheets. 

import * from "./main.js" as Main;

Construct APIs

Construct provides a range of APIs to access Construct-specific features. These are typically accessed via runtime, which refers to the runtime script interface, and has the type IRuntime.

In scripts in event sheets, runtime is automatically defined and so can be used directly.

In script files, runtime is passed to a callback in the special Construct-provided runOnStartup global function. The default code snippet in a newly added script file demonstrates using that. From there on, it is up to your own code to pass runtime to code that needs to use it.

Construct objects are typically accessed via runtime.objects, e.g. runtime.objects.Sprite is an IObjectClass representing the Sprite object.

For example if there is only one instance of Sprite, then it can be retrieved using getFirstInstance() like so: 

const inst = runtime.objects.Sprite.getFirstInstance()!;
// now can use inst.x, inst.y etc.

Note the use of the ! operator (non-null assertion). This is because getFirstInstance() may return null when there are no instances of the object. Therefore its return type allows returning null. TypeScript will mark unconditional access of something that might be null as an error; using the ! operator tells TypeScript that you know it definitely isn't null, and so suppresses any such errors.

If there are multiple instances they can be iterated with methods such as instances() like so: 

for (const inst of runtime.objects.Sprite.instances())
{
	// now can use inst.x, inst.y etc.
}

The specific APIs for instances depends on the plugin type. These interfaces are all documented in the scripting reference section of the manual, such as ISpriteInstance for Sprite instances, which provides APIs for things like animations. Note that these interfaces also inherit from IWorldInstance and IInstance (depending on the kind of plugin). For example common properties like x and y are part of IWorldInstance.

Construct further generates a type definition for every object type in the project, such as InstanceType.Player for a Sprite object named Player. This will derive from ISpriteInstance but add type definitions for the instance variables, behaviors and effects specific to that object type, ensuring they are autocompleted and type checked correctly. When writing TypeScript code you may wish to use a specific type like InstanceType.Player if you want to refer to a specific object type, or a more general type like ISpriteInstance or IWorldInstance depending on whether that code is more generally applicable.

Integrating scripts and events

Strings and numbers can be exchanged between event sheets and TypeScript code using global and local variables in event sheets. Local variables are accessible via localVars inside scripts in event sheets, and global variables are accessible via runtime.globalVars. There is more information in the manual section on Scripts in event sheets.

Strings and numbers can also be exchanged via instance variables via the instVars property of IInstance. (As noted previously Construct generates type definitions for each kind of object type which will include all the available instance variables.)

See also the example project Integrating events with script for an example of some useful techniques.

Using an external editor

Construct has special features to let you use an external code editor like VS Code to write your project's code if you prefer. Note that the workflow is different to working within the Construct editor itself, and involves exporting your project's type definitions. See the guide Using an external editor.

Learn more

Here are some more resources to learn more about using TypeScript in Construct.

Examples

There are lots of example projects using TypeScript coding in Construct which you can find in the Scripting category in the Example Browser.

Debugging

You can still use the browser developer tools to debug code that you write in Construct. Note that the debugger will show the compiled JavaScript output of your TypeScript code, but that generally looks the same but just without the type annotations. For a quick-start guide on debugging, see the manual section on Debugging script.

Minifying

Minifying on export also applies to your TypeScript code written in Construct. When minifying, your TypeScript code is first compiled to JavaScript, and then the minification performed on the resulting JavaScript. Code minification is done with the industry-standard library terser. Simple minify mode should never affect how your code runs. However if you enable Advanced minify mode on export, you may need to adjust how you write your code. See the manual guide on Exporting with Advanced minification for more details.

Worker mode

Construct is capable of running its entire engine in a Web Worker, rendering via OffscreenCanvas. However by default projects using TypeScript code run in the main page ("DOM mode") to ensure compatibility with code that expects to be able to use DOM features like document. If your TypeScript code is compatible with running in a Web Worker, you can re-enable worker mode for improved performance by changing the project property Use worker to Yes (in the Advanced section). When you do this, Construct will also adjust the provided type definitions to match a worker context, so accessing DOM-specific APIs like document will be marked as an error. There is more information about this in the manual section JavaScript in Construct.

Reference

See the Scripting section of the manual for full documentation on using TypeScript in Construct.

  • 0 Comments

Want to leave a comment? Login or Register an account!