Getting Started With TypeScript in Unreal Engine

Chances are, you’ve heard of games like Fortnite and Player Unknown’s Battlegrounds. Both games were built in Unreal Engine 4. Unreal Engine has been a favorite among triple-A game developers and indie studios alike. Ever since Epic Games released the engine as free-to-use back in 2015, many eager developers and enthusiasts have tried their hand at creating games in the robust 3D engine. A majority of hobbyists and small teams opt for the engine’s built in blueprint editor rather than script in C++. While Unreal’s blueprint editor is very simple to use, connecting many nodes in a GUI interface can seem cumbersome to some developers. Luckily, the JavaScript community always finds a way to pair their favorite language with anything, thus giving us Unreal.JS. Unreal.js is a V8 runtime for Unreal Engine that can be an alternative to, or run alongside existing C++ and Blueprint scripts. The only thing that could make developing a large 3D game with JS easier is the infinitely-scalable TypeScript. Here, I will show you how to get started with Unreal.js and TypeScript.

First, if you haven’t already, install Unreal Engine through the Epic Games Launcher. Next, in the launcher go to the marketplace and find Unreal.js, then run “Install to Engine”.

Open Unreal Engine and create a new project. In this example, I created a third-person blueprint project.

Once you have the editor open, go to “Edit>Plugins” and make sure that “Unreal JS” is enabled. If it isn’t, enable it and you will see a prompt to restart the editor.

Now in your project’s content folder you should see a folder called “Scripts”. If you don’t have typescript installed, install it by running

npm install -g typescript

Next, open up your terminal and navigate to the Scripts folder and run

tsc --init

This should generate a tsconfig.json file. Open the file and change the settings to your preferences. At the bottom we will exclude the “aliases.js” file from Unreal.js.

tsconfig.json
...
...// "emitDecoratorMetadata": true,         /* Enables experimental          support for emitting type metadata for decorators. */}, "exclude": [   "aliases.js"  ]}

Now open the Scripts folder in your favorite editor and create a file called “helloUnreal.ts”.

For now let’s just add a console message. In the file add

console.log(’HELLO UNREAL!’)

Now in our terminal let’s run the TypeScript Compiler.

tsc helloUnreal.ts

This should create a “helloUnreal.js” file.

Open up the unreal editor and in the ThirdPersonExampleMap, go to ‘Blueprints’ and open the event graph. In the event graph we will add an event that triggers when the game is started called “EventBeginPlay”. The easiest way to add the event is to right click on the blueprint and search for it.

Next we will find the function for adding a JavaScript Component using the same method and connect the two nodes together by clicking and dragging. Select the JavaScript Component, and then on the “Details” tab in the right side of the editor add our “helloUnreal.js” file to the “Script Source File” input box.

Now make sure to click “Compile” and “Save” and that should be it. Now we can open our JavaScript Console and test our code. Go to “Window>Developer Tools>Javascript Console” and open the console.

Now click the “Play” button and run the game. In the console, you should see the “HELLO UNREAL!” message that we added earlier.

Ok, now let’s try and actually do something to our game using Unreal.js. First, to initiate a live reloading dev environment, let’s create a bootstrap file called “bootstrap.ts” that will follow the Unreal.js Example.

/// <reference path="typings/ue.d.ts">/>export default function (filename:string) {    Context.RunFile('aliases.js')    Context.RunFile('polyfill/unrealengine.js')    Context.RunFile('polyfill/timers.js')  require('devrequire')(filename)}

Now let’s run TypeScript to watch for changes as we edit our helloUnreal.ts file with

tsc -w

Let’s print our “HELLO UNREAL!” message to the HUD by creating an actor. Following the helloCanvas example. Open up helloUnreal.ts and add the following code:

/// <reference path="typings/ue.d.ts">/>// find a local player controllerfunction GetPC() {// out-ref function returns an object which contains out-ref params and return param.// eg) bool USomeClass::Func(int a, int* b, int* c); -> {$:{bool}, b:{int}, c:{int}}return PlayerController.C(GWorld.GetAllActorsOfClass(PlayerController).OutActors[0])}function main(){ class MyHUD extends HUD {    ctor() {    }// override ReceiveDrawHUD   ReceiveDrawHUD() {   var text:string = 'HELLO UNREAL!';   this.Canvas.DrawText(      GEngine.SmallFont,      text,      {X:this.Canvas.SizeX/2,Y:this.Canvas.SizeY/2},      {R:1,G:1,B:1,A:1},      0,      {R:0,G:0,B:0,A:1},      {X:1,Y:1},      true,true,true,      {R:0,G:0,B:0,A:1}    )  }}// register new HUD classlet MyHUD_C = require('uclass')()(global,MyHUD);// and instantiate it  GetPC().ClientSetHUD(MyHUD_C)// no mess to clean  return function () {  }}import bootstrap from "./bootstrap"// bootstrap to initiate live-reloading dev env.try {  module.exports = () => {   let cleanup:Function|null = null// wait for map to be loaded.process.nextTick(() => cleanup = main());// live-reloadable function should return its cleanup function  return () => (<Function>cleanup)()  }}catch (e) {  bootstrap('helloUnreal')}

Now when we hit “Play” in our game we should see the “HELLO UNREAL!” message in the center of the screen.

Notice that this example includes a cleanup function that isn’t used. This function is very important if you are creating Actors in your script, however and you can see a basic example of it here.

Now we have an Unreal Engine project with Unreal.JS that can be scripted using TypeScript. Happy coding!