Forge's Adventure mode, the single-player Magic: The Gathering RPG, running in a web browser. The Java game (libGDX) is compiled to JavaScript with gdx-teavm and TeaVM 0.15, with as few changes to Forge as possible.
Play it at https://cosmicscribe64.github.io/forge-adventure-web/, on a desktop computer. The first visit downloads about 30 MB.
This is an early, rough port, and a lot still breaks. Expect crashes, layout problems and slow spots.
In desktop Chrome you can play the tutorial, generate a world, walk the overworld, visit towns and shops, fight duels against Forge's AI, and save and load. That's about as far as testing has gone. Other desktop browsers haven't been tried.
Phones work now. Version 0.1.1 crashed on phones soon after the main menu appeared, because it needed about 1.3 GB of memory. Since 0.1.2 the game has been played on an iPhone in Chrome through the tutorial, the overworld and a duel. Every release is also tested before and after it deploys in Mobile Safari on the iOS Simulator and in Chrome on an Android emulator, where the game uses about 950 MB (iOS) and 470 MB (Android) at the title screen and about 1.1 GB and 630 MB in a duel. On phones the game is drawn at the screen's real resolution and fits between the browser's bars, and music and sound start switched off. Reports from more phones are welcome, especially older or smaller ones.
The title screen takes 20 seconds to a minute or more to appear, depending on your connection
and computer. wiki/status/open-issues.md lists the known
problems, and bug reports are welcome in the
issue tracker.
Forge is pinned to one upstream commit, named in FORGE_COMMIT, and every
change to it is in a single patch file, patches/forge-web.patch.
Most of those changes are meant to go upstream.
TeaVM compiles Forge and its dependencies to JavaScript in web/, a Gradle project. TeaVM is
missing parts of the JDK that Forge needs, such as blocking concurrency, XML, object streams and
text handling. This project supplies them through its own class library, a substitution policy
and a compiler plugin, all in web/src/main/java.
Forge blocks threads freely, which a browser can't do. Game code runs on TeaVM green threads that share one UI thread, and world generation runs in Web Workers.
Forge's res/ folder holds 466 MB of game data. The page fetches files from it over HTTP when
Forge first reads them, using a manifest of what exists. Card scripts and the files a new game
needs at startup come as a few gzipped downloads instead. Settings and saves are kept in
IndexedDB. Card art comes from Scryfall's API, as in the desktop game.
wiki/overview.md has the full picture. The wiki/ folder is an
Obsidian vault, and its [[links]] work best there.
You need:
- Docker, with at least 8 GB of memory for its VM, because the TeaVM compile peaks at about
6.7 GB. The JDK, Maven and Gradle run in a container (
docker/Dockerfile), so you don't install any Java tools yourself. - bash, git and Python 3.
- About 1 GB of disk for the Forge checkout and 1.5 GB for the build image, plus 3.5 GB for the Playwright image if you run the tests.
It's developed on macOS (Apple silicon) and should work on Linux. Windows is untested.
scripts/update-forge # clone Forge at FORGE_COMMIT and apply patches/forge-web.patch
scripts/build-forge-libs # build Forge's jars with Maven into web/libs
scripts/build-webdata # pack Forge's game data for the web into web/webdata
scripts/build-web # compile to JavaScript (about 5 min) into web/build/dist/js/webapp
scripts/serve-web # serve it at http://localhost:8090 (set PORT to change)Then open http://localhost:8090/ in Chrome. These page parameters are useful for testing:
| Parameter | Effect |
|---|---|
?seed=N |
Generates the same world every time |
?test=1 |
Turns on the in-game test harness (forgeweb.test.WebTest) |
?wfc=local |
Generates the world on the page instead of in Web Workers |
scripts/build-site puts the built game in web/build/site (about 245 MB) as a static site.
Any static host can serve it, from the root or from a subpath.
.github/workflows/pages.yml runs every step above on GitHub's
servers and publishes the result to GitHub Pages whenever a release is published. You can also
run it by hand from the Actions tab.
Players' browsers fetch card art straight from Scryfall's API, which asks clients to stay under about 10 requests per second.
| Script | What it does |
|---|---|
scripts/selftest |
Builds and runs a set of checks (forgeweb.selftest.SelfTest) in headless Chromium, without the game. Each check reproduces a bug once found in the game. It exits with 0 only if every check passes. |
scripts/webtest |
Drives a build in headless Chromium (Playwright, in Docker). web/tools/webtest.py lists the steps it accepts. |
scripts/play-start, play, api |
Start a headless game session and send it commands from the shell through the test harness. |
scripts/measure |
Measures download size, startup time, world-generation time and memory for a fixed seed. |
scripts/wfc-golden |
Checks that the world-generation patches produce exactly the same output as upstream Forge. |
scripts/update-forge <ref> |
Moves to a newer Forge. See wiki/howto/update-forge.md. |
To continue the work, start with
wiki/howto/pick-up-work.md: what to read first, how CI and
releases work, the test helpers, and the project's conventions.
For background, NOTES.md is the lab notebook, with every round of fixes in order
and the measurements taken along the way. PLAN.md is the architecture plan, with
phases and exit criteria. The wiki/ explains how each part works and why it
was built that way, and it catalogues the TeaVM, gdx-teavm and Forge bugs found so far.
If you contribute, fix root causes instead of working around them, and change Forge only through the patch, in a way that could go upstream. When the game hits a runtime bug, reproduce it as a SelfTest check first, fix it there, and then run the full game build.
| Path | What |
|---|---|
patches/forge-web.patch |
Every change to Forge |
web/src/main/java/forge/web |
The web launcher |
web/src/main/java/forgeweb |
The web layer: file system, threads, compatibility hooks, test harness and TeaVM plugins |
web/src/main/java/org/teavm/classlib |
JDK classes that TeaVM lacks or gets wrong |
web/src/main/java/emu, com/... |
Fixed copies of a few gdx-teavm, libGDX and TenPatch classes |
web/html/index.html |
The page: loading screen, prefetching and IndexedDB |
web/tools |
Test driver, static server and code generators |
scripts/ |
Build, serve and test scripts. The heavy work runs in Docker. |
wiki/ |
The project wiki |
Forge Adventure Web is licensed under the GPL-3.0, like Forge. The patch is a derivative of Forge, and the compiled game contains Forge's code.
A few files are modified copies of code from other projects, and they keep their original licenses and headers:
web/src/main/java/com/badlogic/gdx/graphics/g2d/NinePatch.javacomes from libGDX (Apache-2.0).web/src/main/java/com/ray3k/tenpatch/TenPatchDrawable.javacomes from TenPatch (MIT).AsyncResult.java,Gdx2DPixmapNative.javaandFreeType.javaunderweb/src/main/java/emu/com/badlogic/gdx/come from gdx-teavm (Apache-2.0).TObject.javaand thejava/util/zipclasses underweb/src/main/java/org/teavm/classlib/come from TeaVM (Apache-2.0).
Forge's game data isn't in this repository. scripts/update-forge downloads it with the rest of
Forge. No card images are included either, because the game loads them from Scryfall while
you play.
Forge Adventure Web is an unofficial fan project. It is not affiliated with or endorsed by Wizards of the Coast or the Forge team. Magic: The Gathering is a trademark of Wizards of the Coast LLC.
Thanks to the Forge team for the game, to Xpenatan for gdx-teavm, to Alexey Andreev for TeaVM, and to the libGDX project.
