Skip to content

Export for the Web

Web is experimental

You can export your own project to the Web. Kanama checks exports in desktop Chrome and Firefox; Safari and phones are checked by hand. What does not work on the Web is listed in Limitations.

Kanama compiles your Kotlin scripts to WebAssembly, the code format browsers run natively, and Godot's Web export runs them in the page next to your game. Web Internals explains how the two talk.

Requirements

  • A Kanama project that runs in the editor, made from a release kit or set up with the store addon. The addon carries the Kanama Web runtime, so you need nothing else from Kanama. A project built from a checkout of the Kanama repository exports from there; see From a Source Checkout.
  • The Godot version of your Kanama and its export templates, installed from Editor > Manage Export Templates (Godot Version). The Web export uses web_nothreads_release.zip from the templates folder, whose last part is 4.7.2.stable for release 0.4.0 and 4.8.beta2 for a checkout of main:

    OS Export templates folder
    macOS ~/Library/Application Support/Godot/export_templates/<version>/
    Linux ~/.local/share/godot/export_templates/<version>/
    Windows %APPDATA%\Godot\export_templates\<version>\
  • A network connection for the first export. It downloads the tools the Web build runs, about 90 MB in all: Node.js, Yarn and Binaryen into Gradle's folder in your home folder (~/.gradle), and webpack with the npm packages it uses into ~/.kotlin/kotlin-npm-tooling. Unpacked, they take about 400 MB.

  • 8 GB of memory or more. Compiling your scripts with the Kanama Web runtime can use up to 3 GB.
  • Chrome 130 or Firefox 141, or newer, to run the export.

Exporting Your Project

Run this in your project:

cd /path/to/your-project
./gradlew exportWeb

It compiles the scripts in kotlin-src/ to WebAssembly with the Kanama Web runtime from addons/kanama/maven; it does not need your desktop build, so a script that only fails to compile for desktop does not stop it. It exports a copy of the project with Godot, with each Kotlin script replaced by a small GDScript file that calls into WebAssembly, and puts the two together. The export lands in build/web-export/. Your project folder is not changed: the copy Godot exports is under build/kanama/web/.

The first export takes a minute or two, most of it the downloads. Later ones take about 30 seconds for the starter project.

The game's name, icon, window size and main scene come from your Project Settings, as in any export. The settings of your own Web export preset do not apply; Limitations says what to do instead.

The export finds Godot and its Web template where Godot installs them: the templates folder above, and /Applications/Godot.app on macOS. If yours are somewhere else, name them:

cd /path/to/your-project
./gradlew exportWeb \
  -PkanamaGodotExecutable=/path/to/godot \
  -PkanamaWebTemplateRelease=/path/to/web_nothreads_release.zip

When the build stops on one of your scripts, the error names the script and the function. See Web-Compatible Scripts.

Running the Export

Serve the export over HTTP. Opening index.html from disk does not load the game. Any static server works; the one in the addon sends the right type for .wasm files and listens on this machine only:

cd /path/to/your-project
python3 addons/kanama/web/serve_export.py build/web-export

It prints PORT=<n>. Open http://127.0.0.1:<n>/ in your browser. The server runs until you press Ctrl+C.

Testing on a Phone or Tablet

To open the export from another device on your network, serve it over HTTPS. Godot's Web export only starts from a secure address, and 127.0.0.1 is the only plain-HTTP address that counts as one:

cd /path/to/your-project
python3 addons/kanama/web/serve_export.py --lan --https build/web-export

It prints LAN=https://<this-machine>:<n>/. --https makes a self-signed certificate with the openssl command the first time and reuses it for 30 days. Open the address on the device and accept the certificate warning once. On iPhone and iPad Safari, tap Show Details, then visit this website.

Publishing

Zip the contents of build/web-export/, so that index.html is at the root of the zip:

cd /path/to/your-project/build/web-export
zip -r ../my-game-web.zip .

To publish on itch.io, install butler, log in once with butler login, and upload the zip:

butler push /path/to/your-project/build/my-game-web.zip <user>/<game>:html5

On the game's edit page, set the upload to This file will be played in the browser. Leave SharedArrayBuffer support off: the export uses a single thread and needs no special headers. itch.io takes at most 500 MB and 1000 files; build/web-export/kanama-web/export-report.json lists every file and the total size.

To publish on any other static host, such as GitHub Pages, copy the contents of build/web-export/ into a folder the host serves over HTTPS. The host must send .wasm files with the application/wasm content type; GitHub Pages does.

Web-Compatible Scripts

The Web build compiles the same kotlin-src/ folder as desktop, and most scripts need no change: by node<Timer>("Timer"), requireAs<T>(), castOrNull<T>(), preload and instantiateAs<T>() work the same way. When the build stops on a script, the error names the script and the function. Limitations lists what the Web build cannot compile, with what to do instead.

For a script that must differ on the Web, a file with the same name in web/kotlin-src/ replaces the shared file in the Web build only. A desktop-only script is left out by listing its path, relative to kotlin-src/, in web/kotlin-src-excludes.txt, one per line. The demos use both.

From a Source Checkout

A project you build from a checkout of the Kanama repository, as Install from a Source Checkout sets up, exports from the checkout instead. Pass the folder that holds your project's project.godot:

cd /path/to/kanama
./gradlew :web-runtime:exportWeb -PkanamaWebProjectDir=/path/to/your-project

It runs the same steps as exportWeb above and lands in web-runtime/build/web-export/project/ inside the checkout. It takes -PkanamaGodotExecutable and -PkanamaWebTemplateRelease as above. Serve it with python3 scripts/web/serve_export.py web-runtime/build/web-export/project.

packageWebExport zips an export you have already built and tried, and checks it first:

cd /path/to/kanama
./gradlew :web-runtime:packageWebExport -PkanamaWebProjectDir=/path/to/your-project

The zip lands in web-runtime/build/distributions/. It is named after your project folder and the version of your Kanama checkout, such as kanama-web-my-game-v0.5.0.zip, with index.html at its root. The task builds nothing. It fails when the export is missing, older than the current build or made from another project, when the export contains a path from your machine, or when it exceeds itch.io's limits of 500 MB and 1000 files.

Trying the Web Build with a Demo

The Kanama demos export the same way. -PkanamaWebDemo picks the demo, and the matching -PkanamaWeb<Demo>ProjectDir points at its folder in the demos checkout:

cd /path/to/kanama
./gradlew :web-runtime:exportWeb -PkanamaWebDemo=match3 \
  -PkanamaWebMatch3ProjectDir=/path/to/kanama-demos/Starter-Kit-Match3
-PkanamaWebDemo Demo folder -PkanamaWebDemo Demo folder
match3 Starter-Kit-Match3 thirdperson godot-4-3d-third-person-controller
bunnymark Bunnymark charactercontroller godot-4-3d-character-controller-tutorial
dodge godot-demo-2d-dodge-the-creeps racing Starter-Kit-Racing
platformer Starter-Kit-3D-Platformer citybuilder Starter-Kit-City-Builder
squash godot-demo-3d-squash-the-creeps tpsdemo tps-demo-kanama
fps Starter-Kit-FPS web3d none; it is built into Kanama

The property name capitalizes the key: dodge takes -PkanamaWebDodgeProjectDir. Bunnymark also takes -PkanamaWebBunnymarkVariant=BunnymarkSprites, the variant that runs on the Web. A demo's export lands in web-runtime/build/web-export/<demo>/. tpsdemo is larger than itch.io's 500 MB limit, so packageWebExport refuses it; serve it from your own host.

Troubleshooting

Problem Fix
exportWeb stops with The Kanama addon has no Web runtime. The addon is incomplete, or older than the Web export. Unzip the kit or the store addon of the same Kanama version into the project again. A project built from a source checkout uses the command in From a Source Checkout instead.
exportWeb says the bridge speaks Kanama Web protocol one number but the processor generated another. addons/kanama mixes two Kanama versions. Unzip the kit or the store addon into the project again.
exportWeb says No kotlin-src/ folder. The Web export compiles your Kotlin scripts from kotlin-src/. Put them there.
exportWeb says the project has no main scene, or that the main scene does not exist or matches no scene file. Set Project > Project Settings > Application > Run > Main Scene to a scene of the project, and save it.
The build stops on one of your scripts. See Web-Compatible Scripts.
exportWeb says Godot was not found or Godot not found at. Add -PkanamaGodotExecutable=/path/to/godot.
exportWeb says the Web export template is not installed or not found. Install the export templates of your Godot version from Editor > Manage Export Templates, or add -PkanamaWebTemplateRelease=/path/to/web_nothreads_release.zip.
The first exportWeb fails while it downloads Node.js, Yarn or an npm package. It needs a network connection, also through a proxy Gradle can use. Run it again once the network is back.
exportWeb fails with Java heap space or OutOfMemoryError. The project needs more than 3 GB heap the Web build gives the compiler. Run ./gradlew exportWeb -PkanamaWebHeap=6g.
The page says Kanama Web protocol mismatch. The page's files come from two exports. Run exportWeb again and serve the new build/web-export/, and clear the browser's cache.
The page says Kanama Web runtime not started. The WebAssembly module was not built by exportWeb. Run exportWeb again.
The page loads but the game never starts, on a phone or another computer. See Testing on a Phone or Tablet.
The page is blank when opened from disk. Serve the folder over HTTP as in Running the Export.

From a source checkout:

Problem Fix
exportWeb says Pass -PkanamaWebProjectDir=.... Add -PkanamaWebProjectDir with your project folder. Check its spelling: Gradle ignores a property it does not know.
exportWeb says Web project not found or has no project.godot. Pass the folder that holds your project.godot, as an absolute path.
exportWeb says the project has no kotlin-src/. The Web export compiles your Kotlin scripts from kotlin-src/. Point it at a Kanama project.
packageWebExport says the export is stale. Run exportWeb again for the same project, then package.
exportWeb fails with Unsupported -PkanamaWebDemo=.... Use one of the demo keys in the table, or -PkanamaWebProjectDir for your own project.

On Other Platforms

On Windows, run .\gradlew.bat wherever this page says ./gradlew, and python wherever it says python3. Put a command on one line, or end each line with a backtick (`) instead of a backslash, which is the PowerShell line continuation. On Linux and Windows, the export finds Godot when it is on your PATH as godot; otherwise pass -PkanamaGodotExecutable. To zip an export on Windows, select everything inside build\web-export in Explorer and choose Send to > Compressed (zipped) folder.