Initial commit

Author: nmerget

.github/workflows/gh_pages.yml

@@ -0,0 +1,26 @@
+name: 📑 GitHub Pages
+on:
+  push:
+    branches:
+      - "main"
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force

.gitignore

@@ -0,0 +1 @@
+.idea

README.md

@@ -0,0 +1,24 @@
+# Documentation for GodotJS
+
+This project uses [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) to serve all docs. 
+
+
+## Install
+
+````pycon
+pip install mkdocs-material
+````
+
+## Start
+
+````shell
+mkdocs serve
+````
+
+Goto: ``http://localhost:8000``
+
+## Contribute
+You can change the documentation inside the `docs` folder.
+To add new pages you need to update `mkdocs.yml`.
+
+

docs/assets/images/favicon.ico

@@ -0,0 +1,100 @@
+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
+
+Allow passing functions for `godot.Object.connect`, `godot.Object.disconnect`, and `godot.Object.is_connected`:
+
+```js
+this.panel.connect(godot.Control.resized, (size) => {
+  console.log("The size of the panel changed to:", size);
+});
+```
+
+Using `await` to wait for signals
+
+```js
+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
+
+```js
+import ICON from "res://icon.png";
+```
+
+### Multi-threading
+
+Multi-threading with minimal [Worker API](https://developer.mozilla.org/en-US/docs/Web/API/Worker) (**This is an experimental feature**)
+
+Start a new thread with Worker:
+
+```js
+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`:
+
+```js
+// 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);
+  }
+};
+```

docs/documentation/api.md

@@ -0,0 +1,67 @@
+### 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:
+
+```javascript title="my-sprite.mjs"
+// 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) {}
+}
+```
+
+2. Save the script with extension `.mjs`
+3. Attach the script file to the node or resource object like you do with GDScript
+
+### How to export signals
+
+```javascript title="my-sprite.mjs"
+export default class MySprite extends godot.Sprite {}
+// register game_over signal to MySprite class
+godot.register_signal(MySprite, "game_over");
+```
+
+### How to export properties
+
+```javascript title="my-sprite.mjs"
+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.
+
+```js
+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:
+
+```js
+godot.register_property(MyClass, "number_value", 3.14);
+```
+
+Is the simplified version of:
+
+```js
+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](https://github.com/Geequlim/ECMAScript/issues/24#issuecomment-655584829).

docs/documentation/getting-started.md

@@ -0,0 +1,60 @@
+# Gotchas and limitations
+
+Some common mistakes and limitations.
+
+## Import dependency from `node_modules`
+
+If you use `TypeScript` you may encounter the problem where dependencies from `node_modules` are not bundled correctly.
+
+As a workaround you can create a new file `npm-modules.bundle.ts`:
+
+```ts title="npm-modules.bundle.ts"
+import { default as dayjs } from "dayjs";
+export default { dayjs };
+```
+
+In your class you can use the dependency like this:
+
+```ts title="main.ts"
+import npm from "./npm-modules.bundle";
+
+export default class Main extends godot.Node {
+  _ready(): void {
+    console.log(npm.dayjs().toString());
+  }
+}
+```
+
+With a bundler like `esbuild` you should build the `npm-modules.bundle.ts` with the `--bundle` option, but all the other classes like `main.ts` without it.
+
+## Position.x is immutable
+
+You cannot change `this.position.x` try to change `this.position`:
+
+```javascript title="player.mjs"
+export default class Player extends godot.KinematicBody2D {
+  constructor() {
+    super();
+    this.direction = new godot.Vector2(1, 0);
+  }
+  _ready() {}
+  _process(delta) {
+    this.position.x += this.direction.x; // <- breaks
+    this.position += this.direction; // <- works
+  }
+}
+godot.register_property(Player, "direction", new godot.Vector2(1, 0));
+```
+
+## ``register_property`` has to be a target
+
+You cannot change `this.position.x` try to change `this.position`:
+
+```javascript title="player.mjs"
+export default class Player extends godot.KinematicBody2D {
+}
+// This works
+godot.register_property(Player, "directionWorks", new godot.Vector2(1, 0));
+// This breaks because `player` isn't a correct target
+godot.register_property(player, "directionBreaks", new godot.Vector2(1, 0));
+```

docs/documentation/gotchas.md

@@ -0,0 +1,84 @@
+- 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
+
+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.
+
+```ts
+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);
+		});
+	}
+}
+```

docs/documentation/typescript.md

@@ -0,0 +1,117 @@
+# Load json in singleton
+
+This example shows how to load a file like a `config` inside a singleton to access it everywhere.
+
+For the `TypeScript` examples, all `.ts` files will be compiled as `.mjs` to the folder `scripts/generated/**`.
+
+> **Note:** If you use `TypeScript` you need to set `"resolveJsonModule": true` inside your `tsconfig.json`.
+
+## 1. Create file
+
+We create a new folder named `config` and a new file `test.json`.
+
+Next we write this to the `test.json`:
+
+```json title="test.json"
+{
+  "test": true
+}
+```
+
+## 2. Create the singleton
+
+We create a new file inside our `src` folder like `read-config.(mjs|ts)` and add this code to it:
+
+=== "JavaScript"
+
+    ```javascript title="read-config.mjs"
+    import TestJson from "res://config/test.json";
+
+    export default class ReadConfig extends godot.Node {
+      static _singleton;
+
+      static get singleton() {
+    	return ReadConfig._singleton;
+      }
+
+      constructor() {
+    	super();
+    	if (!ReadConfig._singleton) {
+    	  ReadConfig._singleton = this;
+    	}
+      }
+
+      // This property is available for other classes
+      config = TestJson;
+    }
+    ```
+
+=== "TypeScript"
+
+    ```ts title="read-config.ts"
+    // @ts-ignore
+    import TestJson from "res://config/test.json";
+
+    type TestType = {
+      test: boolean;
+    };
+
+    export default class ReadConfig extends godot.Node {
+      static _singleton: ReadConfig;
+
+      static get singleton() {
+    	return ReadConfig._singleton;
+      }
+
+      constructor() {
+    	super();
+    	if (!ReadConfig._singleton) {
+    	  ReadConfig._singleton = this;
+    	}
+      }
+
+      // This property is available for other classes
+      config: TestType = TestJson as TestType;
+    }
+    ```
+
+## 3. Autoload singleton in project
+
+We need to update the `[autoload]` inside `project.godot`:
+
+```text title="project.godot"
+...
+[autoload]
+
+; Use the generated `.mjs` file instead of `.ts`
+ReadConfig="*res://scripts/generated/read-config.mjs"
+...
+```
+
+## 4. Use the singleton in other class
+
+In another class e.g. `main.(mjs|ts)` you need to import the `ReadConfig` then you can access every public property and method from `ReadConfig` via `ReadConfig.singleton`:
+
+=== "JavaScript"
+
+    ```ts title="main.mjs"
+    import ReadConfig from "./read-config";
+
+    export default class Main extends godot.Node {
+      _ready() {
+    	console.log(ReadConfig.singleton.config.test); // prints "true"
+      }
+    }
+    ```
+
+=== "TypeScript"
+
+    ```ts title="main.ts"
+    import ReadConfig from "./read-config";
+
+    export default class Main extends godot.Node {
+      _ready(): void {
+    	console.log(ReadConfig.singleton.config.test); // prints "true"
+      }
+    }
+    ```

docs/examples/load-json-in-singleton.md

@@ -0,0 +1,54 @@
+# Read file local
+
+This example shows how to load any file as string from a local folder.
+
+For the `TypeScript` examples, all `.ts` files will be compiled as `.mjs` to the folder `scripts/generated/**`.
+
+## 1. Create the file you want to read
+
+In this example we try to read a ``.csv`` file, but it should work with any other file as well.
+
+We create a folder ``resources`` and add a new file `test.csv`:
+
+````csv title="test.csv"
+keys,en,de
+HELLO,hello,hallo
+````
+
+## 2. Read the file in class
+
+We use [FileAccess](https://docs.godotengine.org/en/stable/classes/class_fileaccess.html) to read the file.
+
+We create a new file ``read-local-file.(mjs|ts)``:
+
+=== "JavaScript"
+
+    ````ts title="read-local-file.mjs"
+    export default class ReadLocalFile extends godot.Node {
+        _ready() {
+            const file = new godot.FileAccess();
+            file.open("res://resources/test.csv", godot.FileAccess.ModeFlags.READ);
+            let fileContent = "";
+            while (!file.eof_reached()) {
+                fileContent += `${file.get_line()}\n`;
+            }
+            console.log(fileContent);
+        }
+    }
+    ````
+=== "TypeScript"
+
+    ````ts title="read-local-file.ts"
+    export default class ReadLocalFile extends godot.Node {
+        _ready(): void {
+            const file = new godot.FileAccess();
+            file.open("res://resources/test.csv", godot.FileAccess.ModeFlags.READ);
+            let fileContent: string = "";
+            while (!file.eof_reached()) {
+                fileContent += `${file.get_line()}\n`;
+            }
+            console.log(fileContent);
+        }
+    }
+    ````
+

docs/examples/read-file-local.md

@@ -0,0 +1,68 @@
+# Use GDScript in TypeScript
+
+This example shows how to use a class written in GDScript in another TS class.
+
+For the `TypeScript` examples, all `.ts` files will be compiled as `.mjs` to the folder `scripts/generated/**`.
+
+## 1. Create the GDScript file
+
+First we create a simple class with GDScript inside a new file `scripts/gd/GDTest.gd`:
+
+````gdscript title="GDTest.gd"
+extends Node
+
+func _ready():
+	pass
+
+func print_in_gd_test():
+	print("gd_test")
+
+````
+
+## 2. Create a declaration (*.d.ts) for GDScript (only TypeScript)
+
+For proper TypeScript support we need to add a ``gdtest.d.ts`` file:
+
+````ts title="gdtest.d.ts"
+declare module "res://scripts/gd/GDTest.gd" {
+  class GDTest {
+    call(func: "print_in_gd_test"): void;
+
+    static new() {
+      return this;
+    }
+  }
+  export = GDTest;
+}
+````
+
+## 3. Use the class inside your TS file
+
+In the end we need to call the ``GDTest.gd`` from another `(.mjs|.ts)` file, like `main.(mjs|ts)`:
+
+=== "JavaScript"
+    ````ts title="main.mjs"
+    import GDTest from "res://scripts/gd/GDTest.gd";
+    
+    export default class Main extends godot.Node {
+        _ready() {
+            const gdTest = GDTest.new();
+            gdTest.call("print_in_gd_test");
+        }
+    }
+    
+    ````
+=== "TypeScript"
+    ````ts title="main.ts"
+    import GDTest from "res://scripts/gd/GDTest.gd";
+    
+    export default class Main extends godot.Node {
+        _ready(): void {
+            const gdTest: GDTest = GDTest.new();
+            gdTest.call("print_in_gd_test");
+        }
+    }
+    
+    ````
+
+> **Note:** The important thing here is that you use `new()` to instantiate and `call` to execute the function

docs/examples/use-gdscript-in-js-or-ts.md

@@ -0,0 +1,57 @@
+---
+hide:
+  - navigation
+  - toc
+---
+
+# GodotJS - JavaScript language binding for Godot game engine
+
+This module implements JavaScript/TypeScript language support for the Godot game engine using [QuickJS](https://bellard.org/quickjs/) as the JavaScript engine.
+
+
+### Getting started
+
+Read the [getting-started](https://godotjs.github.io/documentation/getting-started/).
+
+## 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](https://github.com/GodotExplorer/ECMAScriptDemos/tree/master/npm_module)
+- 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](https://marketplace.visualstudio.com/items?itemName=geequlim.godot-javascript-debug) - currently not available for 4.x
+
+## Getting the engine
+
+No installation or setup necessary. The binaries for download are the complete, usable Godot editor and engine with JavaScript/TypeScript language support.
+
+### Binary downloads
+
+Download the binaries from the [release page](https://github.com/GodotExplorer/ECMAScript/releases).
+
+### Compiling from source
+
+- Clone the source code of [godot](https://github.com/godotengine/godot):
+  - `git clone git@github.com:godotengine/godot.git` or
+  - `git clone https://github.com/godotengine/godot.git`
+- This branch uses version `4.1` so checkout the version with: `git checkout 4.1`
+- Clone this module and put it into `godot/modules/javascript`:
+  - `git clone git@github.com:Geequlim/ECMAScript.git godot/modules/javascript` or
+  - `git clone https://github.com/Geequlim/ECMAScript.git godot/modules/javascript`
+- [Recompile the godot engine](https://docs.godotengine.org/en/4.1/development/compiling/index.html)
+  - Use `scons` with those additional options `warnings=extra werror=yes module_text_server_fb_enabled=yes` to show all potential errors:
+    - Windows: `scons platform=windows warnings=extra werror=yes module_text_server_fb_enabled=yes`
+    - MacOS: `scons platform=macos arch=arm64 warnings=extra werror=yes module_text_server_fb_enabled=yes`
+
+## Documentation, Tutorials & Demos
+
+
+Read this [documentation](https://godotjs.github.io/documentation/getting-started/) or look at the tutorials or demos:
+
+- [ECMAScriptDemos](https://github.com/Geequlim/ECMAScriptDemos) - Demos
+- [godot-ECMAScript-cookbook](https://github.com/why-try313/godot-ECMAScript-cookbook/wiki) - Tutorial
+- [godot-typescript-starter](https://github.com/citizenll/godot-typescript-starter) - Template
+- [godot-js-template](https://github.com/fukaraadam-workspace/godot-js-template) - Template

docs/index.md

@@ -0,0 +1,45 @@
+# yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json
+site_name: GodotJS
+site_url: https://godotjs.github.io
+repo_url: https://github.com/Geequlim/ECMAScript
+site_description: JS/TS language binding for Godot
+
+nav:
+  - Home: index.md
+  - Docs:
+    - Getting Started: documentation/getting-started.md
+    - API: documentation/api.md
+    - TypeScript: documentation/typescript.md
+    - Gotchas: documentation/gotchas.md
+  - Examples:
+      - Load JSON in Singleton: examples/load-json-in-singleton.md
+      - Read file local: examples/read-file-local.md
+      - Use GDScript in JS or TS: examples/use-gdscript-in-js-or-ts.md
+
+theme:
+  name: material
+  favicon: assets/images/favicon.ico
+ # logo: ./assets/logo.svg
+  icon:
+    repo: fontawesome/brands/github
+  features:
+    - navigation.tabs
+    - navigation.instant
+    - navigation.instant.prefetch
+    - navigation.path
+    - navigation.top
+    - search.suggest
+    - search.highlight
+    - content.code.copy
+    - content.tabs.link
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true