diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a52df983..4f10f618 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Local Development +# Contributing ## Project Structure @@ -7,6 +7,8 @@ TODO ## Documentation This project uses [MKDocs](https://www.mkdocs.org/) to serve all docs. You can change the documentation inside the `docs` folder. +Install mkdocs via ``pip install mkdocs``. +Serve the docs via ``mkdocs serve``. To add new pages you need to update `mkdocs.yml`. ## Preparing your PR @@ -14,3 +16,15 @@ To add new pages you need to update `mkdocs.yml`. The project is using [`clang-format`](https://clang.llvm.org/docs/ClangFormat.html) to format most files. You need to run `bash ./clang_format.sh` before your PR for a successful pipeline. Furthermore, there is an `utf-8` and `LF` checker to fix file formats. Additionally, some spellchecks run inside the [pipeline](.github/workflows/static_checks.yml). + +## Release library + +As a maintainer you are able to create a new release. +1. Go to [create new release](https://github.com/Geequlim/ECMAScript/releases/new) +2. Next you should ``Choose a tag`` and create a new one in the format `v0.0.0` +3. Select target ``master`` +4. Click ``Generate release notes`` +5. (Optional) You can edit the generated release notes +6. Add a release title in the format ``[Godot_Version]-[Tag]-alpha-[Year][Month][Day]`` as an example ``4.1-v0.0.17-alpha-20231003`` +7. Press ``Publish release`` + diff --git a/docs/examples/load-json-in-singleton.md b/docs/examples/load-json-in-singleton.md index ae05b9db..d2fffca9 100644 --- a/docs/examples/load-json-in-singleton.md +++ b/docs/examples/load-json-in-singleton.md @@ -1,77 +1,117 @@ # Load json in singleton -This example shows how to load a file like a ``config`` inside a singleton to access it everywhere. -We use ``TypeScript`` for this example all `.ts` files will be compiled as `.mjs` to the folder `scripts/generated/**`. If you use `TypeScript` you need to set `"resolveJsonModule": true` inside your `tsconfig.json`. +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`. +We create a new folder named `config` and a new file `test.json`. -Next we write this to the ``test.json``: +Next we write this to the `test.json`: -````json title="test.json" +```json title="test.json" { "test": true } -```` +``` ## 2. Create the singleton -We create a new file inside our `src` folder like ``read-config.ts`` and add this code to it: +We create a new file inside our `src` folder like `read-config.(mjs|ts)` and add this code to it: -````ts title="read-config.ts" -// @ts-ignore -import TestJson from "res://config/test.json"; +=== "JavaScript" -type TestType = { - test: boolean; -}; + ```javascript title="read-config.mjs" + import TestJson from "res://config/test.json"; -export default class ReadConfig extends godot.Node { - static _singleton: ReadConfig; + export default class ReadConfig extends godot.Node { + static _singleton; - static get singleton() { - return ReadConfig._singleton; - } + static get singleton() { + return ReadConfig._singleton; + } - constructor() { - super(); - if (!ReadConfig._singleton) { - ReadConfig._singleton = this; + constructor() { + super(); + if (!ReadConfig._singleton) { + ReadConfig._singleton = this; + } + } + + // This property is available for other classes + config = TestJson; } - } - - // This property is available for other classes - config: TestType = TestJson as TestType; -} -```` + ``` + +=== "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`: +We need to update the `[autoload]` inside `project.godot`: -````text title="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.ts`` you need to import the `ReadConfig` then you can access every public property and method from `ReadConfig` via `ReadConfig.singleton`: +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`: -````ts title="main.ts" -import ReadConfig from "./read-config"; +=== "JavaScript" -export default class Main extends godot.Node { - _ready(): void { - console.log(ReadConfig.singleton.config.test); // prints "true" - } -} + ```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" + } + } + ``` diff --git a/docs/examples/read-file-local.md b/docs/examples/read-file-local.md index 6191bea3..8dbdf0a6 100644 --- a/docs/examples/read-file-local.md +++ b/docs/examples/read-file-local.md @@ -2,7 +2,7 @@ This example shows how to load any file as string from a local folder. -We use ``TypeScript`` for this example all `.ts` files will be compiled as `.mjs`. +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 @@ -19,19 +19,36 @@ HELLO,hello,hallo 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.ts``: - -````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); - } -} -```` +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); + } + } + ```` diff --git a/docs/examples/use-gdscript-in-js-or-ts.md b/docs/examples/use-gdscript-in-js-or-ts.md new file mode 100644 index 00000000..b5ca70d2 --- /dev/null +++ b/docs/examples/use-gdscript-in-js-or-ts.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 diff --git a/docs/examples/use-gdscript-in-ts.md b/docs/examples/use-gdscript-in-ts.md deleted file mode 100644 index c3d69d18..00000000 --- a/docs/examples/use-gdscript-in-ts.md +++ /dev/null @@ -1,55 +0,0 @@ -# Use GDScript in TypeScript - -This example shows how to use a class written in GDScript in another TS class. - -We use ``TypeScript`` for this example 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("bla") - -```` - -## 2. Create a declaration (*.d.ts) for GDScript - -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 `.ts` file, like `main.ts`: - -````ts title="main.ts" -import GDTest from "res://scripts/gd/GDTest.gd"; - -export default class Main extends godot.Node { - _ready(): void { - const bla: Bla = Bla.new(); - bla.call("run_in_bla"); - } -} - -```` - -> **Note:** The important thing here is that you use `new()` to instantiate and `call` to execute the function diff --git a/docs/getting-started.md b/docs/getting-started.md index 4b9dbcec..d8033d70 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -2,7 +2,7 @@ 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 @@ -10,7 +10,7 @@ export default class MySprite extends godot.Sprite { super(); } - _reajavascript title="my-sprite.mjs"dy() {} + _ready() {} _process(delta) {} } diff --git a/mkdocs.yml b/mkdocs.yml index d3964c07..c8c78347 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -10,7 +10,7 @@ nav: - Examples: - Load JSON in Singleton: examples/load-json-in-singleton.md - Read file local: examples/read-file-local.md - - Use GDScript in TS: examples/use-gdscript-in-ts.md + - Use GDScript in JS or TS: examples/use-gdscript-in-js-or-ts.md - Gotchas: gotchas.md theme: name: material @@ -24,6 +24,7 @@ theme: - search.suggest - search.highlight - content.code.copy + - content.tabs.link markdown_extensions: - pymdownx.highlight: anchor_linenums: true @@ -32,3 +33,5 @@ markdown_extensions: - pymdownx.inlinehilite - pymdownx.snippets - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true