From 5298a00b5f962f900c69bcc44f88e8b87b4a6a08 Mon Sep 17 00:00:00 2001 From: Oleg Derevenetz Date: Fri, 10 Jan 2025 12:13:46 +0300 Subject: [PATCH 1/2] Add the basic developer's documentation for the Wasm port --- docs/DEVELOPMENT.md | 4 +++ docs/README_emscripten.md | 68 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 72 insertions(+) create mode 100644 docs/README_emscripten.md diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 0ab9d7e04d..df21229db0 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -43,6 +43,10 @@ If you would like to build and run this project on PlayStation Vita please follo If you would like to build and run this project on Nintendo Switch please follow the instructions on [**this page**](README_switch.md). +### Emscripten (Wasm) + +If you would like to run this project in a web browser please follow the instructions on [**this page**](README_emscripten.md). + ### Build with CMake If you would like to build the project using CMake please follow the instructions on [**this page**](README_cmake.md). diff --git a/docs/README_emscripten.md b/docs/README_emscripten.md new file mode 100644 index 0000000000..5eb384cf41 --- /dev/null +++ b/docs/README_emscripten.md @@ -0,0 +1,68 @@ +# Emscripten (Wasm) port of [**fheroes2**](README.md) project + +## Current status of this port + +Please note that this port is currently just an **experiment**. It may experience various problems, crash, or even not work at all in a particular browser. + +## Building + +### Prerequisites + +* emsdk 4.0 or later +* GNU gettext + +### Building using Docker + +To save time, you can use a ready-made Docker image: + +```sh +docker run --rm -v "$(pwd):/src" emscripten/emsdk:latest sh -c "apt-get -y update; apt-get -y install gettext; emmake make -f Makefile.emscripten" +``` + +### Building without Docker + +If you do not want to use Docker, then you will need to install all the prerequisites manually using your platform's package manager, and then run the following command: + +```sh +emmake make -f Makefile.emscripten +``` + +### Building with additional parameters + +If you want to specify some additional ad hoc build parameters, you can use the appropriate environment variables for this, for example: + +```sh +FHEROES2_WITH_DEBUG=ON LDFLAGS="-sMODULARIZE -sEXPORTED_RUNTIME_METHODS=run -sEXPORT_NAME=fheroes2" emmake make -f Makefile.emscripten +``` + +will build fheroes2 in debug mode with additional parameters to create a module. + +## Running the Wasm port on a web server + +### Configuring the web server + +Emscripten uses web workers along with `SharedArrayBuffer` to support multithreading. `SharedArrayBuffer` usage is usually protected by Cross Origin Opener Policy (COOP) +and Cross Origin Embedder Policy (COEP) HTTP headers, and the web server should send these headers as part of its response to a request for resources related to the Wasm +build: + +```text +Cross-Origin-Opener-Policy: same-origin +Cross-Origin-Embedder-Policy: require-corp +``` + +Please see the following link for details: + + + +### Copying necessary files + +After the build is completed, copy the following files to the appropriate directory on your website: + +```text +fheroes2.data +fheroes2.js +fheroes2.wasm +fheroes2.wasm.map (if fheroes2 has been built in debug mode) +``` + +If you want to use the stock launcher (pretty basic at the moment), then also copy all the files from `files/emscripten` to the same directory. From c7f9b733c48dd0a758db4afcc4cf799b6f361c44 Mon Sep 17 00:00:00 2001 From: Oleg Derevenetz Date: Fri, 10 Jan 2025 15:09:54 +0300 Subject: [PATCH 2/2] Apply suggestions Co-authored-by: Zenseii --- docs/README_emscripten.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/README_emscripten.md b/docs/README_emscripten.md index 5eb384cf41..2048629881 100644 --- a/docs/README_emscripten.md +++ b/docs/README_emscripten.md @@ -2,7 +2,7 @@ ## Current status of this port -Please note that this port is currently just an **experiment**. It may experience various problems, crash, or even not work at all in a particular browser. +Please note that this port is currently still **experimental**. You may experience various problems, crashes, or it not even working at all in particular browsers. ## Building @@ -65,4 +65,4 @@ fheroes2.wasm fheroes2.wasm.map (if fheroes2 has been built in debug mode) ``` -If you want to use the stock launcher (pretty basic at the moment), then also copy all the files from `files/emscripten` to the same directory. +If you want to use the stock launcher (pretty basic at the moment), then you will also need to copy all the files from `files/emscripten` to the same directory.