Skip to content

Commit 520abc6

Browse files
nmergetnmerget
authored
feat: update documentation for GodotJS (#7)
1 parent 80fc54e commit 520abc6

69 files changed

Lines changed: 1476 additions & 576 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/development/compiler-options.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Compiler Options
2+
3+
| Name | Description | Default Value |
4+
|---|---|---|
5+
|JSB_MIN_LOG_LEVEL|minimum log level|Verbose|
6+
|JSB_DEBUG| Debug mode. <br/> It's overwritten in SCsub with the value of `DEV_ENABLED` by default. | 1 |
7+
|JSB_LOG_WITH_SOURCE|log with [source filename, line number, function name]|0|
8+
|JSB_WITH_VARIANT_POOL| use a pool allocator for creating variant instances | 1 |
9+
|JSB_WITH_DEBUGGER| enable to debug with Chrome devtools | 1|
10+
|JSB_WITH_SOURCEMAP|translate the js source stacktrace with source map (currently, the `.map` file must locate at the same filename & directory of the js source) | 1|
11+
|JSB_WITH_STACKTRACE_ALWAYS| enable this to let all methods in `console` print with js stacktrace|0|
12+
|JSB_WITH_LWS|JSB_WITH_LWS must be enabled if JSB_WITH_DEBUGGER is used.<br/> Currently use `libwebsockets` to handle v8 debugger connection since `modules/websocket` fail to handshake with `devtools`. <br/>`devtools` do not response the upgrade request with a `sec-websocket-protocol` header which does not apply the handshake requirements of `WSLPeer` <br/> and the connection will break immediately by `devtools` if `selected_protocol` is assigned manually in `WSLPeer`|1|
13+
14+

‎docs/development/dependencies.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Dependencies
2+
3+
| Runtime | Version | |
4+
| -------------- | --------------------- | -------------------------------------------------------- |
5+
| v8 | refs/tags/12.4.254.21 | https://v8.dev/docs/build |
6+
| JavaScriptCore | _System Bundled_ | https://developer.apple.com/documentation/javascriptcore |
7+
| quickjs | 2024-01-13 | https://bellard.org/quickjs/ |
8+
| quickjs-ng | 0.8.0 | https://github.com/quickjs-ng/quickjs/ |
9+
| godot | 4.2.2-stable | https://github.com/godotengine/godot |
10+
| libwebsockets | 4.3.3-13-g6901c32a | https://libwebsockets.org/ |
11+
12+
> **NOTE:** `quickjs` is included with minor modifications for directly compiling with MSVC.

‎docs/development/godot-js-debugging.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Logging
2+
3+
All logging levels are defined in _jsb_log_severity.def.h_:
4+
5+
- `VeryVerbose`: very trivial messages (omitted by default even if `JSB_DEBUG` is on)
6+
- `Verbose`: trivial messges (will not output in the editor panel)
7+
- `Debug`: not important, also used by _console.debug_
8+
- `Info`: general level, also used by _console.info_
9+
- `Log`: used by _console.log_
10+
- `Trace`: used by _console.trace_, with _stacktrace_ anyway
11+
- `Warning`: used by _console.warn_
12+
- `Error`: used by _console.error_, unexpected but not critical errors
13+
- `Assert`: used by _console.assert_, print only if assertion failed
14+
- `Fatal`: critial errors
15+
16+
By default, `VeryVerbose` is omitted at _compile-time_. You can change it in _jsb.config.h_ by setting `JSB_MIN_LOG_LEVEL` to `VeryVerbose`.
17+
`Verbose` messages will be displayed only if the `--verbose` flag is set on the command line for the godot executable, and they will appear exclusively in the console (launch from IDE, or start godot from the command line).
18+
19+
![logging_01](images/logging_01.png)
20+
21+
All messages start with a category name that indicates where they are originated:
22+
23+
- `JS`: messages from JS scripts (all `console.*` calls)
24+
- `jsb`: all general messages in GodotJS
25+
- `JSWorker`: messages from GodotJS worker implementation
26+
- `JSDebugger`: messages from GodotJS debugger bridge
27+
- `JSProcess`: sub-process spawned in GodotJS (`tsc` for instance)
28+
- `JSExporter`: messages from the export plugin for packaging
29+
- `jsc`: JavaScriptCore bridge implementation
30+
- `quickjs`: QuickJS bridge implementation
31+
- `web`: Web bridge implementation
32+

‎docs/development/godot-unit-testing.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Godot Unit Testing
2+
3+
```sh
4+
# An example on Windows:
5+
scons tests=yes vsproj=yes dev_build=yes p=windows
6+
7+
# build godot
8+
# ...
9+
10+
# After the godot is built
11+
bin/your_godot_bin_file --test --test-case="[jsb]*"
12+
13+
```

‎docs/development/images/logging_01.png‎

55.5 KB
Loading

‎docs/documentation/api.md‎

Lines changed: 0 additions & 100 deletions
This file was deleted.

‎docs/documentation/building-from-source/images/web_build.png‎

920 KB
Loading

‎docs/documentation/building-from-source/index.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Build from Source
2+
3+
You can build different runtimes from source.
4+
The following runtimes are available:
5+
6+
- [`v8`](v8.md) is proven to be one of the most powerful and high-performance JavaScript runtimes.
7+
- [`QuickJS`](quick-js.md) is a remarkable and lightweight option.
8+
- [`JavaScriptCore`](javascript-core.md) is the built-in JavaScript engine for WebKit and bundled with macOS/iOS.
9+
- [`Web`](web.md) is only suitable when building for Web. All scripts run on the host browser JS VM rather than an additional interpreter.
10+
11+
## Supported Platforms
12+
13+
| | v8 | quickjs | quickjs-ng | Web Builtin JS | JavaScriptCore |
14+
| -------------- | ---------------- | --------------- | --------------- | ------------------- | --------------- |
15+
| Windows:x86_64 | ✅ | ✅ | ✅ | ❌ | ❌ |
16+
| Windows:arm64 | ✅ | ✅ | ✅ | ❌ | ❌ |
17+
| MacOS:x86_64 | ✅ (not tested) | ✅ (not tested) | ✅ (not tested) | ❌ | ✅ (not tested) |
18+
| MacOS:arm64 | ✅ | ✅ | ✅ | ❌ | ✅ (debugging) |
19+
| Linux:x86_64 | ✅ (not tested) | ✅ (not tested) | ✅ | ❌ | ❌ |
20+
| Linux:arm64 | ✅ | ✅ | ✅ | ❌ | ❌ |
21+
| Android:x86_64 | ✅ (not tested) | ✅ (not tested) | ✅ (not tested) | ❌ | ❌ |
22+
| Android:arm64 | ✅ | ✅ (not tested) | ✅ (not tested) | ❌ | ❌ |
23+
| iOS:x86_64 | ✅ (not tested) | ✅ (not tested) | ✅ (not tested) | ❌ | ✅ (not tested) |
24+
| iOS:arm64 | ✅ (not tested) | ✅ (not tested) | ✅ (not tested) | ❌ | ✅ (not tested) |
25+
| Web:wasm32 | ❌ | ✅ (not tested) | ✅ (not tested) | ✅ (debugging) | ❌ |
26+
| Debugger | ✅ Chrome/VSCode | ❌ | ❌ | ✅ browser devtools | ✅ Safari |
27+
28+
> Android: only tested on ndk_platform=android-24
29+
> Web: only tested on emsdk-3.1.64
30+
> JavaScriptCore: macOS 15, iOS 18 (support for lower versions may be implemented in future versions)

‎docs/documentation/building-from-source/javascript-core.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# JavaScriptCore
2+
3+
To enable `JavaScriptCore`, please run *scons* with the parameter `use_jsc=yes`.
4+
5+
> **NOTE:** `JavaScriptCore` is only available on macOS/iOS since the system bundled `JavaScriptCore.framework` is used.
6+
7+
```sh
8+
# An example on macOS:
9+
scons compiledb=yes dev_build=yes use_jsc=yes
10+
```
11+

‎docs/documentation/building-from-source/quick-js.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# QuickJS
2+
3+
To enable `QuickJS`, please run *scons* with the parameter `use_quickjs=yes`,
4+
or `use_quickjs_ng=yes` if [quickjs-ng](https://github.com/quickjs-ng/quickjs) is preferred.
5+
6+
> **NOTE:** `QuickJS` is also available for WebBuild.
7+
8+
If you choose *quickjs-ng*, please clone the source with submodules:
9+
```sh
10+
# If it's a fresh clone
11+
git clone --recurse-submodules https://github.com/godotjs/GodotJS.git
12+
13+
# If you've already cloned it prior
14+
git submodule update --init --recursive
15+
```
16+
17+
Then, build *Godot* from source:
18+
```sh
19+
# An example on Windows:
20+
scons vsproj=yes dev_build=yes p=windows use_quickjs_ng=yes
21+
```
22+

0 commit comments

Comments
 (0)