Skip to content

Commit 589a775

Browse files
CalinouCalinou
committed
Improve documentation related to SharedArrayBuffer in Exporting for the Web
1 parent 9536651 commit 589a775

File tree

6 files changed

+60
-53
lines changed

6 files changed

+60
-53
lines changed

‎tutorials/export/exporting_for_android.rst‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -191,16 +191,16 @@ the export menu.
191191
* - Export option
192192
- Environment variable
193193
* - Encryption / Encryption Key
194-
- GODOT_SCRIPT_ENCRYPTION_KEY
194+
- ``GODOT_SCRIPT_ENCRYPTION_KEY``
195195
* - Options / Keystore / Debug
196-
- GODOT_ANDROID_KEYSTORE_DEBUG_PATH
196+
- ``GODOT_ANDROID_KEYSTORE_DEBUG_PATH``
197197
* - Options / Keystore / Debug User
198-
- GODOT_ANDROID_KEYSTORE_DEBUG_USER
198+
- ``GODOT_ANDROID_KEYSTORE_DEBUG_USER``
199199
* - Options / Keystore / Debug Password
200-
- GODOT_ANDROID_KEYSTORE_DEBUG_PASSWORD
200+
- ``GODOT_ANDROID_KEYSTORE_DEBUG_PASSWORD``
201201
* - Options / Keystore / Release
202-
- GODOT_ANDROID_KEYSTORE_RELEASE_PATH
202+
- ``GODOT_ANDROID_KEYSTORE_RELEASE_PATH``
203203
* - Options / Keystore / Release User
204-
- GODOT_ANDROID_KEYSTORE_RELEASE_USER
204+
- ``GODOT_ANDROID_KEYSTORE_RELEASE_USER``
205205
* - Options / Keystore / Release Password
206-
- GODOT_ANDROID_KEYSTORE_RELEASE_PASSWORD
206+
- ``GODOT_ANDROID_KEYSTORE_RELEASE_PASSWORD``

‎tutorials/export/exporting_for_ios.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -123,8 +123,8 @@ the export menu.
123123
* - Export option
124124
- Environment variable
125125
* - Encryption / Encryption Key
126-
- GODOT_SCRIPT_ENCRYPTION_KEY
126+
- ``GODOT_SCRIPT_ENCRYPTION_KEY``
127127
* - Options / Application / Provisioning Profile UUID Debug
128-
- GODOT_IOS_PROVISIONING_PROFILE_UUID_DEBUG
128+
- ``GODOT_IOS_PROVISIONING_PROFILE_UUID_DEBUG``
129129
* - Options / Application / Provisioning Profile UUID Release
130-
- GODOT_IOS_PROVISIONING_PROFILE_UUID_RELEASE
130+
- ``GODOT_IOS_PROVISIONING_PROFILE_UUID_RELEASE``

‎tutorials/export/exporting_for_linux.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,4 +31,4 @@ the export menu.
3131
* - Export option
3232
- Environment variable
3333
* - Encryption / Encryption Key
34-
- GODOT_SCRIPT_ENCRYPTION_KEY
34+
- ``GODOT_SCRIPT_ENCRYPTION_KEY``

‎tutorials/export/exporting_for_macos.rst‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -227,20 +227,20 @@ the export menu.
227227
* - Export option
228228
- Environment variable
229229
* - Encryption / Encryption Key
230-
- GODOT_SCRIPT_ENCRYPTION_KEY
230+
- ``GODOT_SCRIPT_ENCRYPTION_KEY``
231231
* - Options / Codesign / Certificate File
232-
- GODOT_MACOS_CODESIGN_CERTIFICATE_FILE
232+
- ``GODOT_MACOS_CODESIGN_CERTIFICATE_FILE``
233233
* - Options / Codesign / Certificate Password
234-
- GODOT_MACOS_CODESIGN_CERTIFICATE_PASSWORD
234+
- ``GODOT_MACOS_CODESIGN_CERTIFICATE_PASSWORD``
235235
* - Options / Codesign / Provisioning Profile
236-
- GODOT_MACOS_CODESIGN_PROVISIONING_PROFILE
236+
- ``GODOT_MACOS_CODESIGN_PROVISIONING_PROFILE``
237237
* - Options / Notarization / API UUID
238-
- GODOT_MACOS_NOTARIZATION_API_UUID
238+
- ``GODOT_MACOS_NOTARIZATION_API_UUID``
239239
* - Options / Notarization / API Key
240-
- GODOT_MACOS_NOTARIZATION_API_KEY
240+
- ``GODOT_MACOS_NOTARIZATION_API_KEY``
241241
* - Options / Notarization / API Key ID
242-
- GODOT_MACOS_NOTARIZATION_API_KEY_ID
242+
- ``GODOT_MACOS_NOTARIZATION_API_KEY_ID``
243243
* - Options / Notarization / Apple ID Name
244-
- GODOT_MACOS_NOTARIZATION_APPLE_ID_NAME
244+
- ``GODOT_MACOS_NOTARIZATION_APPLE_ID_NAME``
245245
* - Options / Notarization / Apple ID Password
246-
- GODOT_MACOS_NOTARIZATION_APPLE_ID_PASSWORD
246+
- ``GODOT_MACOS_NOTARIZATION_APPLE_ID_PASSWORD``

‎tutorials/export/exporting_for_web.rst‎

Lines changed: 36 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,11 @@ in the user's browser.
2020
Projects written in C# using Godot 4 currently cannot be exported to the
2121
web. To use C# on web platforms, use Godot 3 instead.
2222

23-
.. important:: Use the browser-integrated developer console, usually opened
24-
with :kbd:`F12`, to view **debug information** like JavaScript,
25-
engine, and WebGL errors.
23+
.. tip::
24+
25+
Use the browser-integrated developer console, usually opened
26+
with :kbd:`F12` (:kbd:`Cmd + Option + I` on macOS), to view
27+
**debug information** like JavaScript, engine, and WebGL errors.
2628

2729
.. attention::
2830

@@ -35,10 +37,6 @@ in the user's browser.
3537
general, especially when using the GLES2 rendering backend (which only
3638
requires WebGL 1.0).
3739

38-
.. warning:: SharedArrayBuffer requires a :ref:`secure context <doc_javascript_secure_contexts>`.
39-
Browsers also require that the web page is served with specific
40-
`cross-origin isolation headers <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy>`__.
41-
4240
WebGL version
4341
-------------
4442

@@ -93,11 +91,6 @@ of limitations you should be aware of when porting a Godot game to the web.
9391
page is served via a secure HTTPS connection (localhost is
9492
usually exempt from such requirement).
9593

96-
.. tip:: Check the `list of open HTML5 issues on GitHub
97-
<https://github.com/godotengine/godot/issues?q=is:open+is:issue+label:platform:web>`__
98-
to see if the functionality you're interested in has an issue yet. If
99-
not, open one to communicate your interest.
100-
10194
Using cookies for data persistence
10295
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10396

@@ -203,12 +196,32 @@ Exporting for the web generates several files to be served from a web server,
203196
including a default HTML page for presentation. A custom HTML file can be
204197
used, see :ref:`doc_customizing_html5_shell`.
205198

199+
.. warning::
200+
201+
To ensure low audio latency and the ability to use :ref:`class_Thread` in web exports,
202+
Godot 4 web exports always use
203+
`SharedArrayBuffer <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer>`__.
204+
This requires a :ref:`secure context <doc_javascript_secure_contexts>`,
205+
while also requiring the following CORS headers to be set when serving the files:
206+
207+
::
208+
209+
Cross-Origin-Opener-Policy: same-origin
210+
Cross-Origin-Embedder-Policy: require-corp
211+
212+
If you don't control the web server or are unable to add response headers,
213+
use `coi-serviceworker <https://github.com/gzuidhof/coi-serviceworker>`__
214+
as a workaround.
215+
216+
If the client doesn't receive the required response headers,
217+
**the project will not run**.
218+
206219
The generated ``.html`` file can be used as ``DirectoryIndex`` in Apache
207-
servers and can be renamed to e.g. ``index.html`` at any time, its name is
220+
servers and can be renamed to e.g. ``index.html`` at any time. Its name is
208221
never depended on by default.
209222

210223
The HTML page draws the game at maximum size within the browser window.
211-
This way it can be inserted into an ``<iframe>`` with the game's size, as is
224+
This way, it can be inserted into an ``<iframe>`` with the game's size, as is
212225
common on most web game hosting sites.
213226

214227
The other exported files are served as they are, next to the ``.html`` file,
@@ -223,23 +236,17 @@ The ``.pck`` file is binary, usually delivered with the MIME-type
223236
:mimetype:`application/octet-stream`. The ``.wasm`` file is delivered as
224237
:mimetype:`application/wasm`.
225238

226-
.. caution:: Delivering the WebAssembly module (``.wasm``) with a MIME-type
227-
other than :mimetype:`application/wasm` can prevent some start-up
228-
optimizations.
229-
230-
.. tip::
231-
Godot 4 web exports use the `SharedArrayBuffer <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer>`__, and require the following CORS headers to be set when serving the files:
232-
233-
::
234-
Cross-Origin-Opener-Policy: same-origin
235-
Cross-Origin-Embedder-Policy: require-corp
236-
239+
.. warning::
237240

241+
Delivering the WebAssembly module (``.wasm``) with a MIME-type
242+
other than :mimetype:`application/wasm` can prevent some start-up
243+
optimizations.
238244

239245
Delivering the files with server-side compression is recommended especially for
240-
the ``.pck`` and ``.wasm`` files, which are usually large in size.
241-
The WebAssembly module compresses particularly well, down to around a quarter
242-
of its original size with gzip compression.
246+
the ``.pck`` and ``.wasm`` files, which are usually large in size. The
247+
WebAssembly module compresses particularly well, down to around a quarter of its
248+
original size with gzip compression. Consider using Brotli precompression if
249+
supported on your web server for further file size savings.
243250

244251
**Hosts that provide on-the-fly compression:** GitHub Pages (gzip)
245252

@@ -389,4 +396,4 @@ the export menu.
389396
* - Export option
390397
- Environment variable
391398
* - Encryption / Encryption Key
392-
- GODOT_SCRIPT_ENCRYPTION_KEY
399+
- ``GODOT_SCRIPT_ENCRYPTION_KEY``

‎tutorials/export/exporting_for_windows.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -69,10 +69,10 @@ the export menu.
6969
* - Export option
7070
- Environment variable
7171
* - Encryption / Encryption Key
72-
- GODOT_SCRIPT_ENCRYPTION_KEY
72+
- ``GODOT_SCRIPT_ENCRYPTION_KEY``
7373
* - Options / Codesign / Identity Type
74-
- GODOT_WINDOWS_CODESIGN_IDENTITY_TYPE
74+
- ``GODOT_WINDOWS_CODESIGN_IDENTITY_TYPE``
7575
* - Options / Codesign / Identity
76-
- GODOT_WINDOWS_CODESIGN_IDENTITY
76+
- ``GODOT_WINDOWS_CODESIGN_IDENTITY``
7777
* - Options / Codesign / Password
78-
- GODOT_WINDOWS_CODESIGN_PASSWORD
78+
- ``GODOT_WINDOWS_CODESIGN_PASSWORD``

0 commit comments

Comments
 (0)