Improve the ability for users to play fheroes2 on the web

[justinbburris]

Genesis 👇

By the way, are you aware of modern web frontend technologies? The thing is, we have the Emscripten port of fheroes2. The README claims it's experimental, but it actually works pretty well in general... except that we don't have a convenient launcher for it (HTML/JS code for its launch page). All we have is a pretty basic launcher here. It works in general, but it is absolutely inconvenient for the end user. The general requirements for the launcher are described here. For the reference, the Emscripten port has the build job in our CI for pull requests:

fheroes2/.github/workflows/make.yml

Lines 321 to 366 in 349cc49

	make-emscripten:
	strategy:
	matrix:
	include:
	- name: Emscripten
	on: [ 'pull_request' ]
	env:
	FHEROES2_STRICT_COMPILATION: ON
	package_name: fheroes2_emscripten.zip
	- name: Emscripten Multithreaded
	on: [ 'pull_request' ]
	env:
	FHEROES2_STRICT_COMPILATION: ON
	FHEROES2_WITH_THREADS: ON
	package_name: fheroes2_emscripten_mt.zip
	name: Make (${{ matrix.name }})
	runs-on: ubuntu-latest
	container: emscripten/emsdk:latest
	timeout-minutes: 30
	defaults:
	run:
	shell: bash
	steps:
	- uses: actions/checkout@v4
	if: ${{ contains( matrix.on, github.event_name ) }}
	- name: Install dependencies
	if: ${{ contains( matrix.on, github.event_name ) }}
	run: |
	sudo apt-get -y update
	sudo apt-get -y install gettext p7zip-full
	- name: Build
	if: ${{ contains( matrix.on, github.event_name ) }}
	run: |
	emmake make -f Makefile.emscripten -j "$(nproc)"
	env: ${{ matrix.env }}
	- name: Create package
	if: ${{ contains( matrix.on, github.event_name ) }}
	run: |
	# Translations and H2D files are already included in fheroes2.data
	7z a -bb1 -tzip -- ${{ matrix.package_name }} LICENSE changelog.txt fheroes2.data fheroes2.js fheroes2.wasm ./docs/README.txt ./files/emscripten/*
	- uses: actions/upload-artifact@v4
	if: ${{ contains( matrix.on, github.event_name ) }}
	with:
	name: ${{ matrix.package_name }}
	path: ${{ matrix.package_name }}
	if-no-files-found: error

which produces PR artifacts. Ideally, it would be interesting to host the WebAssembly build as part of the fheroes2 website so that users can play directly in their browser using the user's local game assets.

Are you interested in looking into this (of course, not right now, but maybe in the future)?

Originally posted by @oleg-derevenetz in #9726

[justinbburris]

@oleg-derevenetz if you would kindly assign this to me when you have a moment - I would appreciate it 🙇

[justinbburris]

@oleg-derevenetz
Just so I'm clear with the ask here - is the idea that the user would visit a page like https://ihhub.github.io/fheroes2/play-online and they'd be presented with a nice launcher (with the requirements from that link) where they'd be guided through the process of picking their files - and once complete -- they'd be able to play the game using that URL. Is that correct?

[oleg-derevenetz]

@justinbburris

Just so I'm clear with the ask here - is the idea that the user would visit a page like https://ihhub.github.io/fheroes2/play-online and they'd be presented with a nice launcher (with the requirements from that link) where they'd be guided through the process of picking their files - and once complete -- they'd be able to play the game using that URL. Is that correct?

Yes, in general, that's the idea. But if you have other ideas, then please suggest them. We will consider and discuss them.

[justinbburris]

While I'm getting setup locally with this, is it expected that the emscripten build should play the cinematics when loaded though the browser?

[oleg-derevenetz]

While I'm getting setup locally with this, is it expected that the emscripten build should play the cinematics when loaded though the browser?

Yes, of course, if that cinematics is present in the OG assets (most of cinematics are missing from demo assets, for instance).

[justinbburris]

Okay great! These work with the build when it's not wrapped, but I might have some nginx setup issues. Thanks for the note.

[oleg-derevenetz]

Okay great! These work with the build when it's not wrapped, but I might have some nginx setup issues. Thanks for the note.

What do you mean by "wrapped"/"not wrapped"?

[justinbburris]

In this context "not wrapped" means building & then running the project using make && ./fheroes2
This loads my files as expected (save files and cinematics)

However, when I build with emscripten and serve it via the web (wrapped by the nginx/html/emscriptem/wasm build tooling) the cinematics and save files don't load.

(I have noticed that I can save/load in the web version)

[oleg-derevenetz]

The existing launcher is written in such a way that no OG assets should be bundled into the wasm data file. It uses Emscripten IDBFS to store these assets in the user's browser using IndexedDB backend. We cannot offer a copyrighted material on our website, so bundling these files into the fheroes2.data is not an option (except maybe the demo version assets, which may be discussed separately). Save files, highscores, config, etc, etc are also stored in the IDBFS.

[justinbburris]

Yeah, that makes sense - That is why you have to load the files at the first launch.

With my local build, I've done that, and I've loaded the same assets that I use for the non-emscripten build.

I've traced the error to this line

diff --git a/files/emscripten/index.html b/files/emscripten/index.html
index 6b6918c2..dc55612b 100644
--- a/files/emscripten/index.html
+++ b/files/emscripten/index.html
@@ -117,7 +117,7 @@
                         const requiredResolved = files.filter(({ webkitRelativePath: path }) =>
                             requiredFiles.some(rq => path.toLocaleLowerCase().endsWith(rq.toLocaleLowerCase()))).length === 2;
                         if (!requiredResolved) return Module.clearInput('wrong directory');
-                        const whitListed = ['data', 'heroes2', 'maps', 'music'];
+                        const whitListed = ['data', 'heroes2', 'maps', 'music', 'anim'];
                         files.filter(file => {
                             const [fileName, ...path] = file.webkitRelativePath.split('/').reverse();
                             if (fileName.startsWith('.')) return false;

It's my understanding that this is loading up the folders to sync from the local file system and load into the browser. In this case, it would appear that the anim folder was missed in the initial implementation. When I add it, not as part of the build, but rather as part of the website wrapper, it loads my cinematic files, as I would expect.

My understanding here is that this is not bundling the files with the wasm data file, rather into the IDBFS. Am I misunderstanding this in some way?

If not, I can submit a patch which would allow these files to be loaded by the browser at game initialization time - which would fix the cinematic issue.

[justinbburris]

However, if that is the case - If you don't have this patch, I don't understand why your cinematics would work, when mine do not 😅