Skip to content

Latest commit

 

History

History
287 lines (227 loc) · 10.6 KB

README.md

File metadata and controls

287 lines (227 loc) · 10.6 KB
Raw

JavaScript language binding for Godot game engine

This module implements JavaScript/TypeScript language support for the Godot game engine using QuickJS as the JavaScript engine.

Features

  • Almost complete ES2020 support
  • All Godot API available
  • Operator overriding for built-in types (Vector3, Color, etc)
  • TypeScript support
  • Using third-party libraries from npm
  • Multi-thread support with Worker API
  • Full code completion support for all Godot APIs including signals and enumerations
  • Debug in Visual Studio Code with the plugin - currently not available for 4.x

Installation

No installation or setup necessary. The binaries for download are the complete, usable Godot editor and engine with JavaScript/TypeScript language support.

Download

You can try the pre-compiled binaries from the release page or get the binaries with the latest commits from the GitHub build action result.

Compilation

  1. Clone the source code of godot
  2. Clone this module and put it into godot/modules/ and make sure the folder name of this module is javascript
  3. Recompile the godot engine - Use scons with those additional options warnings=extra werror=yes module_text_server_fb_enabled=yes to show all potential errors

Build Godot with ECMAScript

Usage

How to export script class to Godot

  1. Define your JavaScript class and inherit from a Godot class, then export it as the default entry:
// The default export entry is treated as an exported class to Godot
export default class MySprite extends godot.Sprite {
	// this is _init() in GDScript
	constructor() {
		super();
	}

	_ready() {}

	_process(delta) {}
}
  1. Save the script with extension .mjs
  2. Attach the script file to the node or resource object like you do with GDScript

How to export signals

export default class MySprite extends godot.Sprite {}
// register game_over signal to MySprite class
godot.register_signal(MySprite, "game_over");

How to export properties

export default class MySprite extends godot.Sprite {
	_process(delta) {
		// Yes! We can use operators in JavaScript like GDScript
		this.position += this.direction * delta;
	}
}
// export 'direction' properties to MySprite Godot inspector
godot.register_property(MySprite, "direction", new godot.Vector2(1, 0));

There are 2 ways of using the godot.register_property. The third parameter can either be a default value for the property you're trying to export or an object giving a more detailed description of how the editor should show it.

function register_property(target: GodotClass | godot.Object, name: string, value: any);
function register_property(target: GodotClass | godot.Object, name: string, info: PropertyInfo);

So calling the register_property like this:

godot.register_property(MyClass, "number_value", 3.14);

Is the simplified version of:

godot.register_property(MyClass, "number_value", {
	type: godot.TYPE_REAL,
	hint: godot.PropertyHint.PROPERTY_HINT_NONE,
	hint_string: "",
	default: 3.14,
});

For more detail on how to use it, click here.

About the API

All of Godot's APIs are defined within the godot namespace.

No API names have been renamed or changed, so you shouldn't need to change your habits.

GDScript JavaScript
null null
int number
float number
String string
Array Array
Dictionary Object
NodePath string
Object godot.Object
Resource godot.Resource
Vector2 godot.Vector2
Color godot.Color
sin(v) godot.sin(v)
print(v) godot.print(v)
PI godot.PI
Color.black godot.Color.black
Control.CursorShape godot.Control.CursorShape
Label.Align.ALIGN_LEFT godot.Label.Align.ALIGN_LEFT

API specification:

  • Keys of Dictionary are converted to String in JavaScript

  • Signals are defined as constants to their classes

    godot.Control.resized === 'resized' // true

  • Additional functions

    • godot.register_signal(cls, signal_name) to register signals
    • godot.register_property(cls, name, default_value) to define and export properties
    • godot.register_class(cls, name) to register named class manually
    • godot.set_script_tooled(cls, tooled) to set tooled of the class
    • godot.set_script_icon(cls, path) to set icon of the class
    • godot.get_type(val) Returns the internal type of the given Variant object, using the godot.TYPE_*
    • godot.yield(target, signal) Returns a Promise which will be resolved when the signal emitted
    • requestAnimationFrame(callback) registers a callback function to be called every frame, returns a request ID.
    • cancelAnimationFrame(request_id) to cancel a previously scheduled frame request
    • require(module_id) to load a CommonJS module or load a resource file
    • $ is the alias of Node.get_node

  • Using signals in the ECMAScript way

    • Allow passing functions for godot.Object.connect, godot.Object.disconnect, and godot.Object.is_connected
    this.panel.connect(godot.Control.resized, (size) => {
	console.log("The size of the panel changed to:", size);
});
    • Using await to wait for signals
    await godot.yield(
	this.get_tree().create_timer(1),
	godot.SceneTreeTimer.timeout
);
console.log("After one second to show");

  • Preload resources with ECMAScript import statement

    import ICON from "res://icon.png";

  • Multi-threading with minimal Worker API (This is an experimental feature)

    • Start a new thread with Worker

      const worker = new Worker("worker.js"); // Run worker.js in a new thread context
worker.postMessage({ type: "load_dlc", value: "dlc01.pck" });
worker.onmessage = function (msg) {
	console.log("[MainThread] received message from worker thread:", msg);
};

    • Transfer value in different thread context with godot.abandon_value and godot.adopt_value

      // In worker thread
let id = godot.abandon_value(object);
postMessage({ type: "return_value", id: id });

// In the host thread
worker.onmessage = function (msg) {
	if (typeof msg === "object" && msg.type === "return_value") {
		let value_from_worker = godot.adopt_value(msg.id);
	}
};

TypeScript support

  • Run the menu command Project > Tools > JavaScript > Generate TypeScript Project from the Godot editor to generate a TypeScript project
  • Run tsc -w -p . under your project folder in the terminal to compile scripts

Code completion

  • Code completion in TS will automatically work once the TypeScript project is generated by the above steps.
  • Code completion in VSCode is achieved by the property "types": "./godot.d.ts" in the generated package.json file of the TypeScript project. The godot.d.ts file can be generated alone via the Project > Tools > ECMAScript > Generate TypeScript Declaration File editor menu option and added to a package.json file manually to achieve this without a full TypeScript project.

Example TypeScript Usage

Compile your ts script to a .mjs file then we can attach it to a node in godot editor.

Most of the register functions are available as various decorators as seen below.

import { signal, property, tool, onready, node } from "./decorators";

@tool // make the script runnable in godot editor
export default class InputLine extends godot.HBoxContainer {
	// define a signal
	@signal
	static readonly OnTextChanged: string;

	// expose a node property
	@node
	icon: godot.Sprite;

	// register offset property with the godot inspector with default value of Vector2(0, 0)
	@property({ default: godot.Vector2.ZERO })
	offset: godot.Vector2;

	// register properties for godot editor inspector
	@property({ type: godot.VariantType.TYPE_STRING })
	get title() {
		return this._title;
	}
	set title(v: string) {
		this._title = v;
		if (this._label) {
			this._label.text = v;
		}
	}
	private _title: string;

	@property({ default: "Input text here" })
	get hint() {
		return this._hint;
	}
	set hint(v: string) {
		this._hint = v;
		if (this.edit) {
			this.edit.hint_tooltip = v;
			this.edit.placeholder_text = v;
		}
	}
	private _hint: string;

	get label(): godot.Label {
		return this._label;
	}
	protected _label: godot.Label;

	// call get_node('LineEdit') and assign the returned value to 'this.edit' automatically when the node is ready
	@onready("LineEdit")
	edit: godot.LineEdit;

	get text(): string {
		return this.edit?.text;
	}

	_ready() {
		// get first child with the type of godot.Label
		this._label = this.get_node(godot.Label);

		// Apply the inspector filled values with property setters
		this.title = this.title;
		this.hint = this.hint;

		this.edit.connect(godot.LineEdit.text_changed, (text: string) => {
			this.emit_signal(InputLine.OnTextChanged, text);
		});
	}
}

Demo

You can try demos in the ECMAScriptDemos

Developer notes

  • This package is not compatible with MSVC, you will get build errors in quickjs.
  • The script also build the on_tag.yml script which automates the github release publishing. ** The on_tag.yml functionality tries to sleep until all jobs with the same sha are completed. It should be fine to run whenever, but depending on how github actions culls long running jobs you might want to make sure that all/(most of) the builds look good before tagging.
  • They should definitely be fixed & enabled at some point, so please submit a PR if you have any ideas of how to do that!