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);
+		});
+	}
+}
+```