Building on Emscripten - TheXTech/TheXTech GitHub Wiki

Emscripten build process is most similar to building on Linux, with one note: you should prepare a separate folder with game assets, including one or more episodes.

Before beginning work, installation of the Emscripten toolchain is required (this manual suggested: https://emscripten.org/docs/getting_started/downloads.html).

Preparing to build

Before to start the build, you should obtain the source code for TheXTech. You can use the stable version as well as the latest in-development to test out any new experimental features and receive any further bugfixes earlier.

Stable version

If you want to build the stable version, you can simply download the source code archive from the official site or from GitHub releases:

Download the source code archive from the TheXTech's official page.
Or download the source code archive from one of GitHub releases pages.

And then, unpack the archive and open the terminal at the just-now unpacked directory that contains the source code for TheXTech.

Important note: Please never use the "Source code" links at Github releases: they are broken. Instead, download the thextech-full-src-v*.*.*.tar.gz or thextech-full-src-v*.*.*.tar.bz2 or thextech-full-src-v*.*.*.zip archive.

This project uses submodules and GitHub is unable to create source code packages that includes submodules too.

Development version

If you want to build the latest in-development version, then, instead of downloading the archive, you can clone the repository itself by running this in a terminal (please open the terminal at the directory where you want to put the clonned repository, so, you will know where it is):

git clone https://github.com/TheXTech/TheXTech.git

Then, Make sure all submodules have been pulled, otherwise, it won't build:

cd TheXTech
git submodule init
git submodule update

Prepare assets folder which will be packed

To make your game work, you need to prepare an assets folder that will be embedded in your final build.

First off, create a directory in any convenient place.
Download one of two archives with compatible assets:
- SMBX 1.3 assets
- Adventures of Demo assets
After unpacking an archive, make "worlds" and "battle" folders and put your episode(s) and battle levels you want to include with your build of a game. Modify the content of stuff you would customize, etc.
Be sure no junk and old game saves are left in your episodes (save*.sav files). Examples of junk files were Thumbs.db and siblings, desktop.ini, .DS_Store on macOS, etc.

Building

The build of this on Linux or macOS is suggested. Windows didn't test but should be possible.

Open a terminal in the root of the Emscripten toolchain, and execute the next command:
```
source ./emsdk_env.sh
```
If you work on Windows, the next command should work:
```
emsdk_env.bat
```
Make a new build directory (where build-cache will be generated) in any convenient place.
- Run CMake configure through emcmake wrapper:
```
emcmake cmake \
    -G Ninja \
    -S "/path/to/sources/thextech/" \
    -B "/path/to/build-thextech-emscripten" \
    -DCMAKE_BUILD_TYPE=MinSizeRel \
    -DENABLE_ANTICHEAT_TRAP=ON \
    -DENABLE_LOGGING=OFF \
    -DTHEXTECH_GAME_NAME_TITLE="Super Mario Bros. X - Web Edition" \
    -DTHEXTECH_CREDITS_URL="www.SuperMarioBrosX.org" \
    -DTHEXTECH_CREDITS_TITLE="Super Mario Bros. X" \
    -DTHEXTECH_MANIFEST_NAME="SMBX on TheXTech" \
    -DTHEXTECH_MANIFEST_DESC="Play Super Mario Bros. X on TheXTech v1.3.x" \
    -DTHEXTECH_MANIFEST_ID="smbx-thextech" \
    -DTHEXTECH_DEPLOY_URL="https://yourdomain.net/smbx-on-web/" \
    -DPGE_PRELOAD_ENVIRONMENT="/path/to/your/assets/directory"
```
- Where -DPGE_PRELOAD_ENVIRONMENT= - the full path to the directory that contains all game assets (In simple words, the directory of SMBX game content: graphics, music, sounds, episodes, battle levels, intro/outro levels, and no executables and DLLs).
- Where -DENABLE_ANTICHEAT_TRAP= - enables the mechanism that will punish the player for an attempt to use the well-known "redigitiscool" cheat code in a form of a complete game save removal. It's the reference to the Heretic game where if you will use cheats from the Doom game, you'll get the opposite effect: iddqd kills the player, and idkfa removes all weapons and ammo.
- Where -DENABLE_LOGGING=OFF - disables any sort of logging completely, suggested for the Emscripten builds with no debug consoles added to the page with the game.
- Where -DTHEXTECH_GAME_NAME_TITLE= - the title of the game.
- Where -DTHEXTECH_CREDITS_URL= - the homepage URL that will be shown at the credits screen.
- Where -DTHEXTECH_CREDITS_TITLE= - the game title that appears at the credits screen.
- Where -DTHEXTECH_MANIFEST_NAME= - the short name that will be used if your game is installed as a web app.
- Where -DTHEXTECH_MANIFEST_DESC= - a longer description that will be used if your game is installed as a web app.
- Where -DTHEXTECH_MANIFEST_ID= - a unique identifier for the game; no more than one installation on your server should use this
- Where -DTHEXTECH_DEPLOY_URL= - the URL prefix where your game will be deployed. This must be an https URL except for local debug testing, where http://localhost:8000/ or http://localhost:8080/ are acceptable with the correct browser config.

Run building

emmake cmake --build "/path/to/build-thextech-emscripten" --target all

Once the build will complete, in your build directory you will find the built project in the output/bin folder:
- thextech.html - a working template of a page with a playable game.
- thextech.data - a pack of assets.
- thextech.js - a built game.
- thextech.wasm - WebAssembly data.
Don't try to open the HTML file directly in a browser: the browser may blocking of local file system requests and prevent a game run. Instead, run some tiny web server with a document root in the output/bin folder, for example, via python:
```
python3 -m http.server
```
And then, you can open in your browser the http://127.0.0.1:8000/thextech.html and try a game in action.