godotjs/GodotJS

GodotJS - Add TypeScript/JavaScript Support for Godot 4.x with v8/QuickJS

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 as an alternative runtime.

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
• QuickJS as an alternative runtime (experimental, testing)
• Asynchronous module loading (import function)
• Sandboxed scripting (not multi-threading)
• Worker threads

Get Started

Before initiating, make sure to select the JavaScript runtime you prefer between v8 and QuickJS:

• v8 is proven to be one of the most powerful and high-performance JavaScript runtimes
• QuickJS is a remarkable and lightweight option

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

Note

QuickJS support may not be stable enough to use.

To enable QuickJS, please run scons with the parameter use_quickjs=yes.

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

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

• Build V8
• QuickJS
• 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	✅	✅	🟡 (incomplete)	❌
Windows:arm64	🟡 (incomplete)	🟡 (incomplete)	🟡 (incomplete)	❌
MacOS:x86_64	✅ (not tested)	✅ (not tested)	🟡 (incomplete)	❌
MacOS:arm64	✅	✅	🟡 (incomplete)	❌
Linux:x86_64	✅ (not tested)	✅ (not tested)	🟡 (incomplete)	❌
Linux:arm64	🟡 (incomplete)	🟡 (incomplete)	🟡 (incomplete)	❌
Android:x86_64	✅ (not tested)	✅ (not tested)	🟡 (incomplete)	❌
Android:arm64	✅	✅ (not tested)	🟡 (incomplete)	❌
iOS:x86_64	✅ (not tested)	✅ (not tested)	🟡 (incomplete)	❌
iOS:arm64	✅ (not tested)	✅ (not tested)	🟡 (incomplete)	❌
Web	❌	🟡 (incomplete)	🟡 (incomplete)	🟡 (incomplete)

Android: tested on ndk_platform=android-24
Currently, except for the web, 32-bit platforms are not considered to support.