godotjs · nmerget · May 20, 2025 · May 20, 2025
diff --git a/docs/development/compiler-options.md b/docs/development/compiler-options.md
@@ -0,0 +1,14 @@
+# Compiler Options
+
+| Name | Description | Default Value |
+|---|---|---|
+|JSB_MIN_LOG_LEVEL|minimum log level|Verbose|
+|JSB_DEBUG| Debug mode. <br/> It's overwritten in SCsub with the value of `DEV_ENABLED` by default. | 1 |
+|JSB_LOG_WITH_SOURCE|log with [source filename, line number, function name]|0|
+|JSB_WITH_VARIANT_POOL| use a pool allocator for creating variant instances | 1 |
+|JSB_WITH_DEBUGGER| enable to debug with Chrome devtools | 1|
+|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|
+|JSB_WITH_STACKTRACE_ALWAYS| enable this to let all methods in `console` print with js stacktrace|0|
+|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|
+
+
diff --git a/docs/development/dependencies.md b/docs/development/dependencies.md
@@ -0,0 +1,12 @@
+# Dependencies
+
+| Runtime        | Version               |                                                          |
+| -------------- | --------------------- | -------------------------------------------------------- |
+| v8             | refs/tags/12.4.254.21 | https://v8.dev/docs/build                                |
+| JavaScriptCore | _System Bundled_      | https://developer.apple.com/documentation/javascriptcore |
+| quickjs        | 2024-01-13            | https://bellard.org/quickjs/                             |
+| quickjs-ng     | 0.8.0                 | https://github.com/quickjs-ng/quickjs/                   |
+| godot          | 4.2.2-stable          | https://github.com/godotengine/godot                     |
+| libwebsockets  | 4.3.3-13-g6901c32a    | https://libwebsockets.org/                               |
+
+> **NOTE:** `quickjs` is included with minor modifications for directly compiling with MSVC.
diff --git a/docs/development/godot-js-debugging.md b/docs/development/godot-js-debugging.md
@@ -0,0 +1,32 @@
+# Logging
+
+All logging levels are defined in _jsb_log_severity.def.h_:
+
+- `VeryVerbose`: very trivial messages (omitted by default even if `JSB_DEBUG` is on)
+- `Verbose`: trivial messges (will not output in the editor panel)
+- `Debug`: not important, also used by _console.debug_
+- `Info`: general level, also used by _console.info_
+- `Log`: used by _console.log_
+- `Trace`: used by _console.trace_, with _stacktrace_ anyway
+- `Warning`: used by _console.warn_
+- `Error`: used by _console.error_, unexpected but not critical errors
+- `Assert`: used by _console.assert_, print only if assertion failed
+- `Fatal`: critial errors
+
+By default, `VeryVerbose` is omitted at _compile-time_. You can change it in _jsb.config.h_ by setting `JSB_MIN_LOG_LEVEL` to `VeryVerbose`.  
+`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).
+
+![logging_01](images/logging_01.png)
+
+All messages start with a category name that indicates where they are originated:
+
+- `JS`: messages from JS scripts (all `console.*` calls)
+- `jsb`: all general messages in GodotJS
+- `JSWorker`: messages from GodotJS worker implementation
+- `JSDebugger`: messages from GodotJS debugger bridge
+- `JSProcess`: sub-process spawned in GodotJS (`tsc` for instance)
+- `JSExporter`: messages from the export plugin for packaging
+- `jsc`: JavaScriptCore bridge implementation
+- `quickjs`: QuickJS bridge implementation
+- `web`: Web bridge implementation
+
diff --git a/docs/development/godot-unit-testing.md b/docs/development/godot-unit-testing.md
@@ -0,0 +1,13 @@
+# Godot Unit Testing
+
+```sh
+# An example on Windows:
+scons tests=yes vsproj=yes dev_build=yes p=windows 
+
+# build godot
+# ...
+
+# After the godot is built
+bin/your_godot_bin_file --test --test-case="[jsb]*" 
+
+```
diff --git a/docs/development/images/logging_01.png b/docs/development/images/logging_01.png
diff --git a/docs/documentation/api.md b/docs/documentation/api.md
diff --git a/docs/documentation/building-from-source/images/web_build.png b/docs/documentation/building-from-source/images/web_build.png
diff --git a/docs/documentation/building-from-source/index.md b/docs/documentation/building-from-source/index.md
@@ -0,0 +1,30 @@
+# Build from Source
+
+You can build different runtimes from source.
+The following runtimes are available:
+
+- [`v8`](v8.md) is proven to be one of the most powerful and high-performance JavaScript runtimes.
+- [`QuickJS`](quick-js.md) is a remarkable and lightweight option.
+- [`JavaScriptCore`](javascript-core.md) is the built-in JavaScript engine for WebKit and bundled with macOS/iOS.
+- [`Web`](web.md) is only suitable when building for Web. All scripts run on the host browser JS VM rather than an additional interpreter.
+
+## Supported Platforms
+
+|                | v8               | quickjs         | quickjs-ng      | Web Builtin JS      | JavaScriptCore  |
+| -------------- | ---------------- | --------------- | --------------- | ------------------- | --------------- |
+| Windows:x86_64 | ✅               | ✅              | ✅              | ❌                  | ❌              |
+| Windows:arm64  | ✅               | ✅              | ✅              | ❌                  | ❌              |
+| MacOS:x86_64   | ✅ (not tested)  | ✅ (not tested) | ✅ (not tested) | ❌                  | ✅ (not tested) |
+| MacOS:arm64    | ✅               | ✅              | ✅              | ❌                  | ✅ (debugging)  |
+| Linux:x86_64   | ✅ (not tested)  | ✅ (not tested) | ✅              | ❌                  | ❌              |
+| Linux:arm64    | ✅               | ✅              | ✅              | ❌                  | ❌              |
+| Android:x86_64 | ✅ (not tested)  | ✅ (not tested) | ✅ (not tested) | ❌                  | ❌              |
+| Android:arm64  | ✅               | ✅ (not tested) | ✅ (not tested) | ❌                  | ❌              |
+| iOS:x86_64     | ✅ (not tested)  | ✅ (not tested) | ✅ (not tested) | ❌                  | ✅ (not tested) |
+| iOS:arm64      | ✅ (not tested)  | ✅ (not tested) | ✅ (not tested) | ❌                  | ✅ (not tested) |
+| Web:wasm32     | ❌               | ✅ (not tested) | ✅ (not tested) | ✅ (debugging)      | ❌              |
+| Debugger       | ✅ Chrome/VSCode | ❌              | ❌              | ✅ browser devtools | ✅ Safari       |
+
+> Android: only tested on ndk_platform=android-24  
+> Web: only tested on emsdk-3.1.64  
+> JavaScriptCore: macOS 15, iOS 18 (support for lower versions may be implemented in future versions)
diff --git a/docs/documentation/building-from-source/javascript-core.md b/docs/documentation/building-from-source/javascript-core.md
@@ -0,0 +1,11 @@
+# JavaScriptCore
+
+To enable `JavaScriptCore`, please run *scons* with the parameter `use_jsc=yes`.
+
+> **NOTE:**  `JavaScriptCore` is only available on macOS/iOS since the system bundled `JavaScriptCore.framework` is used. 
+
+```sh
+# An example on macOS:
+scons compiledb=yes dev_build=yes use_jsc=yes 
+```
+
diff --git a/docs/documentation/building-from-source/quick-js.md b/docs/documentation/building-from-source/quick-js.md
@@ -0,0 +1,22 @@
+# QuickJS
+
+To enable `QuickJS`, please run *scons* with the parameter `use_quickjs=yes`, 
+or `use_quickjs_ng=yes` if [quickjs-ng](https://github.com/quickjs-ng/quickjs) is preferred.
+
+> **NOTE:**  `QuickJS` is also available for WebBuild. 
+
+If you choose *quickjs-ng*, please clone the source with submodules:
+```sh
+# If it's a fresh clone
+git clone --recurse-submodules https://github.com/godotjs/GodotJS.git
+
+# If you've already cloned it prior
+git submodule update --init --recursive
+```
+
+Then, build *Godot* from source:
+```sh
+# An example on Windows:
+scons vsproj=yes dev_build=yes p=windows use_quickjs_ng=yes 
+```
+