GodotJS

This project adds TypeScript/JavaScript Support for Godot 4.x by leveraging the high-performance capabilities of V8 to bring the delightful development experience of TypeScript into Godot. Meanwhile, it also supports switching to QuickJS, or even directly run scripts on the host browser JS VM if porting to web.

Note

The core functionality is implemented and essentially usable but still under testing.

Features

• Godot ScriptLanguage integration
• Debug with Chrome devtools when using V8
• REPL in Editor
• Hot-reloading
• Support for multiple javascript engines (v8, quickjs, quickjs-ng, the host Browser JS)
• Worker threads (limited support) (experimental)
• Asynchronously loaded modules (limited support)

Get Started

Before initiating, make sure to select the JavaScript runtime you prefer between v8, QuickJS and Web (See Supported Platforms):

• v8 is proven to be one of the most powerful and high-performance JavaScript runtimes.
• QuickJS is a remarkable and lightweight option.
• Web is only suitable when building for Web. All scripts run on the host browser JS VM.

Option 1: v8

v8 is used as the default JavaScript runtime. Follow the instructions below to set it up:

STEP 1: Download or clone the repo into the modules directory of your Godot engine source:

cd YourGodotEngineSource/modules
git clone https://github.com/ialex32x/GodotJS.git

STEP 2: Put v8 headers and libraries into GodotJS, or directly download the prebuilt v8 from GodotJS-Dependencies:

# download the archive of prebuilt v8 
curl https://github.com/ialex32x/GodotJS-Dependencies/releases/download/v8_r11/v8_r11.zip --output your/download/path/v8.zip

# extract the zip file into your `GodotJS` directory, 
# NOTE: no white space after the switch `-o`
7z x -o"YourGodotEngineSource/modules/GodotJS" your/download/path/v8.zip 

Note

Don't forget to put the headers/libraries of v8 into the same directory structure used in prebuilt v8 if you decide to compile it by yourself.

The module directroy structure looks like this:

┗━ godot
    ┗━ modules
        ┣━ ...
        ┣━ gltf
        ┣━ GodotJS
        ┃    ┣━ bridge-quickjs
        ┃    ┣━ bridge-v8
        ┃    ┣━ ...
        ┃    ┣━ lws
        ┃    ┗━ v8
        ┃        ┣━ include
        ┃        ┣━ linux.x86_64.release
        ┃        ┣━ macos.arm64.release
        ┃        ┣━ windows_x86_64_release
        ┃        ┗━ ...
        ┣━ gridmap
        ┣━ ...

The currently used version of v8 is 12.4.254.20.

STEP 3: Compile and launch Godot Editor. Then, install TypeScript/JavaScript presets into a Godot project.

Note

Since the prebuilt v8 library is built with the windows-latest github runner which uses VS2022, encountering Unresolved external symbol errors during linkage with v8_monolith.lib or libucrt.lib may be addressed by updating to the latest version of the MSVC v143 toolchain, Windows Universal CRT SDK and Visual Studio 2022 itself. See GodotJS-Dependencies README for the version of MSVC C++ Compiler used in different prebuilt library packages.

A prebuilt version of Godot Editor can be downloaded from GodotJS-Build.
Because the GodotJS-Build workflow is currently run manually, it may not be built from the latest commit of GodotJS.

Option 2: QuickJS

To enable QuickJS, please run scons with the parameter use_quickjs=yes, or use_quickjs_ng=yes if quickjs-ng is preferred.

Note

QuickJS is also available for WebBuild.

# An example on Windows:
scons vsproj=yes dev_build=yes p=windows use_quickjs_ng=yes 

Option 3: Web

It's enabled by default for WebBuild.

Note

Be cautious about the JS compatibility issues between different web browsers.

Examples

For more information on how to use GodotJS in a project, check out GodotJSExample for examples written in typescript.
And, don't forget to run npm install and npx tsc before opening the example project.

More Details

Scripting

• GodotJS Scripts
• Godot Bindings
• Running code in the editor
• Signals

Utilities

• REPL
• SourceMap
• Debugger

Advanced

• V8
• Web
• QuickJS
• Worker
• Dependencies
• Compiler Options
• Unit Testing
• Misc

Auxiliary Repositories

• GodotJSExample: An example godot project for demonstrating how to use GodotJS
• GodotJS-Build: Github workflows for building Godot Editor with GodotJS support
• GodotJS-Dependencies: Github workflows for building dependencies of GodotJS (v8, lws)

Supported Platforms

	v8.impl	quickjs.impl	quickjs.impl (quickjs-ng)	web.impl
Windows:x86_64	✅	✅	✅	❌
Windows:arm64	🟡	🟡	🟡	❌
MacOS:x86_64	✅ (not tested)	✅ (not tested)	✅ (not tested)	❌
MacOS:arm64	✅	✅	✅	❌
Linux:x86_64	✅ (not tested)	✅ (not tested)	✅	❌
Linux:arm64	🟡	✅	✅	❌
Android:x86_64	✅ (not tested)	✅ (not tested)	✅ (not tested)	❌
Android:arm64	✅	✅ (not tested)	✅ (not tested)	❌
iOS:x86_64	✅ (not tested)	✅ (not tested)	✅ (not tested)	❌
iOS:arm64	✅ (not tested)	✅ (not tested)	✅ (not tested)	❌
Web:wasm32	❌	✅ (not tested)	✅ (not tested)	✅ (debugging)
Debugger	✅ chrome devtools	❌	❌	✅ browser devtools

Android: only tested on ndk_platform=android-24
Web: only tested on emsdk-3.1.64