TypeScript in Construct

There are a few details specific to using TypeScript in Construct. This section outlines what you need to know.

TypeScript in the Construct editor

If you are writing TypeScript code in Construct itself, you should only have TypeScript files (.ts) in your project. Construct will automatically compile these to JavaScript (.js) files for you behind the scenes, so you don't need to worry about having .js files in your project. The only times you'll see the JavaScript output of your TypeScript code is when debugging or after exporting your project.

If you do have both a .ts and a .js file with the same name in your project, Construct gives priority to the .js file. In other words it will ignore your .ts file and just use the contents of the .js file.

Using an external editor

If you use an external editor to write TypeScript code, you most likely want to keep the .ts files external, and only import the .js output files to your Construct project. This is because your external code editor will use its own version of TypeScript. Using two different versions of TypeScript is likely to cause awkward compatibility problems, so the best workflow is to let your external editor compile TypeScript to JavaScript, and then just use the .js files in Construct so it uses them as-is. You can set your code editor to automatically compile TypeScript to JavaScript when saving a file, and set Construct to auto-reload the script files on preview, so then you can have an easy workflow where saving a TypeScript file will automatically reflect the changes in the next Construct preview.

Using an external editor also allows you to use a newer or different version of TypeScript to the one built in to Construct. Construct's built-in TypeScript version is logged to the browser console the first time a code editor is opened.

Suggested workflows

In short the two suggested workflows for TypeScript coding are:

1. Code TypeScript in the Construct editor: only have .ts files in your Construct project, and no .js files.
2. Code TypeScript using an external editor: don't have .ts files in your Construct project, only .js files.

TypeScript definition files

You can import .d.ts files - aka TypeScript definition files - to your Construct project. This will allow TypeScript to use the type definitions in those files. As per the design of TypeScript, definition files are not compiled to JavaScript and have no effect on how code is run - they only define types to be used by TypeScript's code validator.

Converting a project to TypeScript

You can switch an existing project using JavaScript code to TypeScript by right-clicking the Scripts folder in the Project Bar and choosing TypeScript►Switch project to TypeScript. This will automatically switch all JavaScript code in event sheets to use the TypeScript language instead, and rename all .js project files to .ts. Note however it does not change any code, as it is not possible to automatically add type annotations. Therefore you will still need to go through your code and add type annotations until there are no more TypeScript errors (see the next section for advice on that). However this option should still save you some time if you want to switch your project's language.

Similarly a project using TypeScript can be switched back to JavaScript. Again you'll need to then remove type annotations for it to be valid JavaScript code.

Converting a folder project to TypeScript

Construct has special handling for switching a folder-based project to TypeScript. This applies when there are both .js and .ts files in the project folder, but only .js files in the Construct project (i.e. our recommended workflow for using an external editor). In this case choosing the Switch project to TypeScript option will instead replace .js files in the Construct project with the corresponding .ts files from the project folder. This provides a handy way to switch a project from using an external editor back to using Construct's built-in TypeScript support.

Adding types to existing JavaScript code

If you convert a JavaScript project to TypeScript, you'll probably see a lot of TypeScript errors. That's because in some places TypeScript requires type annotations, and leaving them out is marked as an error. You'll need to go through all the code adding type annotations until there are no more TypeScript errors reported. This section has some advice on how to do that. Note this is not an exhaustive list of all changes you'll need to make, but the common changes that you're likely to need to make are covered, as well as some advice specific to Construct.

As a starting example, the default main.js code file includes this function:

async function OnBeforeProjectStart(runtime)
{
	// ...
}

async function OnBeforeProjectStart(runtime: IRuntime)
{
	// ...
}

const playerInst = runtime.objects.Player.getFirstInstance();
playerInst.x += 10; // Error: 'playerInst' is possibly 'null'

// Note '!' added to line below
const playerInst = runtime.objects.Player.getFirstInstance()!;
playerInst.x += 10; // OK

const inst = runtime.objects.Goblin.getFirstInstance()!;
// 'inst' is of type InstanceType.Goblin - so it won't have any of
// the properties or methods of the custom GoblinInstance class

const inst = runtime.objects.Goblin.getFirstInstance<GoblinInstance>()!;
// 'inst' is now of type GoblinInstance and so can use the properties
// and methods of the custom class

const Globals = {
	score: 0,
	playerInstance: null
};

const Globals = {
	score: 0,
	playerInstance: <InstanceType.Player | null> null
};

class MyClass {
	constructor()
	{
		this.prop1 = "hello";
		this.prop2 = 123;
	}
}

class MyClass {

	prop1: string;
	prop2: number;

	constructor()
	{
		this.prop1 = "hello";
		this.prop2 = 123;
	}
}

import Globals from "./globals.js";