Build size
What is in the Balaur web module, which cargo features and dependencies decide its size, and how to build a smaller runtime template.
On this page
The engine module is most of a web game's download. Two modules are built
from one crate: the game template balaur export --target web ships, and the
editor's module behind the examples and a project's editor.
balaur_bg.wasm, 2026-11-02 |
Raw | Brotli |
|---|---|---|
| Game template | 19.7 MB | 5.0 MB |
Game template, physics2d only |
17.3 MB | 4.6 MB |
Game template, physics3d only |
17.6 MB | 4.7 MB |
| The editor's module | 25.1 MB | 6.6 MB |
- The host decides which number a player downloads: brotli when it compresses
.wasm(see thecontent-encodingheader), gzip when it only does that, raw when it does neither. - The browser compiles the raw size either way.
- The export pack, the game's own bytes, is on top.
What a game template leaves out
The template is balaur_cli built without four features the editor's module
has.
editor: the exporter and its encoders (FLAC, a resampler, a palette quantiser, zip), the project store, a tab's editor entry points, and egui's Hack, Ubuntu Light and two emoji faces. The faces are 1.4 MB of data. A game draws with the faces under its ownfonts/and the Source Sans 3 face the engine carries.compile: the script compiler, the WESL shader linker and the.bsto C translator. An export ships compiled scripts, and every shader its game draws with linked and deflated into the export pack: 9 KB for a game with no materials of its own. An export pack written with--keep-sourcesruns only in a build withcompile.import: the importers and SVGs read in place.bs-wasmi: the script interpreter besidebs-web, so a debugger can park a call.
The web game template also leaves out two features every other build has, and builds its own std:
webgl: WebGL2 beside WebGPU, 1.0 MB. A browser without WebGPU shows "this browser has no WebGPU" instead of the game. Build a template withwebglfor one that should run there.env-filter:RUST_LOG's regex syntax, 0.23 MB. A page has no environment.- std is rebuilt with
-Zbuild-stdandoptimize_for_sizeon the pinned stable, 1.14 MB. Sorting a large array is slower;WEB_STD=stockbuilds with rustup's std.
Every build decodes images as PNG, JPEG, WebP, BMP, TGA, HDR and EXR, the
formats a material and a sky read. The marked-up text shaper and egui's share
one harfrust and one read-fonts.
Module contents
One module carries the whole engine; nothing loads lazily.
| section | Editor's module | Game template |
|---|---|---|
| code | 19.1 MB | 15.7 MB |
| data | 5.8 MB | 3.8 MB |
scripts/wasm_crates.py in the engine repository charges a module's code to
its crates, and every build of a template writes that table to
crates-<template>.txt beside it. scripts/native_crates.py does the same
for a desktop, Android or iOS template.
| Baked in by a dependency | Raw | Brotli |
|---|---|---|
| kiss3d's Tony McMapface table, the editor's module only | 0.8 MB | 0.2 MB |
| egui's default fonts, the editor's module only | 1.4 MB | 0.7 MB |
A game that sets tonemap = "tony_mcmapface" carries the Tony McMapface
table in its export pack instead, deflated: 350 KB more pack.
The rest of the data is tables: Unicode data for the text shapers, codec tables, and kiss3d's built-in shaders, linked when it compiles.
Export pack size
The export pack is the second download. Every export prints a report.
pack 2.0 MB
section entries bytes
manifest 1 78 B
scenes 1 3.4 KB
scripts 37 488.2 KB
assets 6 1.6 MB
extension entries bytes
ttf 4 1.5 MB
png 2 22.7 KB
largest bytes
fonts/Phosphor-Fill.ttf 477.2 KB
fonts/SourceSans3-Regular.ttf 421.1 KB
fonts/SourceSans3-Semibold.ttf 415.9 KB
assets/balaur-logo.png 20.2 KB
0 files nothing references, 0 B
- Fonts outweigh images in most projects, and the engine outweighs both.
- On the engine's own assets, subsetting takes a 421 KB face to 29 KB and the image pass takes a small sprite from 1.1 KB to 0.5 KB.
- Four
[export]keys act on the report, each off by default.

[export]
strip = true # drop an asset no scene, script or include glob names
include = ["sfx/**"] # ...except paths a script builds at run time
image_recode = "webp" # write lossless WebP
font_recode = "subset" # cut a face to the characters the project shows
font_original = ["fonts/SourceSans3-*"] # ...but ship these whole
audio_recode = "flac" # write uncompressed WAV as lossless FLAC
Anything under fonts/ survives a strip: the UI finds faces by listing that
directory, and no scene names one.
Two more keys are lossy, and named separately from the lossless ones.
[export]
image_recode = "quantized" # a 256-colour palette with alpha, then the PNG pass
image_quality = 80 # the palette's quality target, 0 to 100
audio_recode = "vorbis" # an Ogg Vorbis stream instead of the original PCM
audio_quality = 0.5 # libvorbis quality, -0.1 to 1.0
One picture overrides the mode in its own import settings.
# art/logo.png.import.toml
recode = "original" # this one ships exactly as drawn
- Every mode except
quantizedandvorbisis lossless. None changes a pixel count. - A sprite is sized from its image header; a re-encoded texture is the same sprite.
balaur export --dry-runprints the table and writes nothing.- An atlas is not a size lever: it saves each file's header and little else. The renderer draws one call per node either way.
- GPU-compressed textures (BC, ETC2, ASTC) cut video memory and upload time, not the download. A block-compressed image on disk is larger than the PNG it came from.
Building a smaller runtime
Every release carries a template per physics world for every target, and one with neither, which the project picks (see Shipping).
[export]
runtime = "2d" # web-2d: no rapier3d; "3d" leaves out rapier2d, "bare" both
A template built with fewer features still is passed to the exporter.
WEB_FEATURES=audio,vorbis,browser,window,physics2d,bs-web scripts/package_runtime.sh web
balaur export my-game --target web --runtime dist/balaur-runtime-web
physics2dandphysics3deach register one world. Withoutphysics3da template is 2.4 MB smaller raw and 0.4 MB brotli; withoutphysics2d, 2.1 MB and 0.3 MB.- A world left off still compiles; its systems, components and verbs are never registered, so its solver never links.
flac,mp3,mp4,vorbisandwaveach decode one audio format. MP4 and AAC is the largest at 0.14 MB; all five are 0.32 MB.[export] audio_recode = "vorbis"rewrites WAV as Ogg Vorbis, so a project of WAV and Ogg files plays on avorbisbuild.- The script needs the
wasm32-unknown-unknowntarget, thewasm-bindgenCLI at the version inCargo.lock(checked),wasm-optfrom binaryen, andbrotlifor the size line it prints. - It refuses a module under 5 MB: a build whose entry point was optimised away.
http,websocket,webtransport,gamendandmultiplayergate their native stacks off the wasm target and cost the plugin's own code.
Features
The cargo features of balaur_cli, the binary every runtime is built
from, and what each adds to a wasm32-unknown-unknown build. A feature's native
dependencies are gated off that target, so http or websocket costs a browser
build only the plugin's own code; the two that matter there are audio and
window.
The web runtime (scripts/package_runtime.sh web) is built with
--no-default-features --features audio,flac,mp3,mp4,vorbis,wav,http,websocket,webtransport,multiplayer,browser,physics2d,physics3d,bs-web,bs-jit,window and links 288 crates.
Override the set with WEB_FEATURES=... scripts/package_runtime.sh web.
WEB_THREADS=1 builds the second runtime, which adds parallel to that
set: rapier's solver threads on rayon, which needs the shared memory and
atomics only that build has.
| Feature | Default | Web runtime | What it is | Adds to a web build |
|---|---|---|---|---|
apple |
off | off | apple.* for scripts, and Game Center and iCloud under platform.*. Off, a build drops GameKit and the objc2 bindings to it. platform.* is always there; with no store behind it every call answers unsupported. |
balaur_apple |
audio |
off | on | Sound. Off, a build drops rodio, cpal and the platform audio stack. | nothing |
browser |
off | on | browser.* for scripts: the page a browser build runs in. Always compiles; off the web every call answers nil. |
nothing |
bs |
off | off | Balaur Script (.bs), the language scripts are written in: bs on wasmi or an iOS export's native build, bs-jit on wasmtime (5 to 7 times wasmi, about 11 MB; not on the web or iOS), bs-web on the page's own engine. |
nothing |
bs-jit |
off | on | nothing | |
bs-wasmi |
off | off | The interpreter alone: what the web editor's module adds beside bs-web so a debugger can park a call. |
nothing |
bs-web |
off | on | nothing | |
compile |
off | off | The WESL shader linker, the .bs compiler and its C translator: a dev run, the editor and an export. A template leaves it off and draws with the shaders an export linked, and runs the script units it compiled, into the export pack. |
nothing |
editor |
off | off | The editor: edit and export, the export.*, project.*, debugger.* and script.* modules its scripts call, a browser tab's editor entry points, and egui's bundled faces. A game template leaves it off. |
nothing |
env-filter |
off | off | RUST_LOG with tracing's full filter syntax, regex included. Off, plain target=level rows, and 0.23 MB less of a web module. |
nothing |
extensions |
off | off | Load extensions from a project's extensions/ directory at run time. | libloading |
flac |
off | on | One feature per container audio decodes; a build without one plays none of that format. |
nothing |
headless |
on | off | Every default but the window: a tool that opens none, on a machine that may have no display. Its runs are headless. | nothing |
http |
off | on | http.* for scripts. Off, a build drops ureq and its TLS stack. |
nothing |
import |
off | off | balaur import, import.* for the editor and SVGs read in place. The web game runtime leaves it off: a game reads what an import and export wrote. |
nothing |
mp3 |
off | on | nothing | |
mp4 |
off | on | nothing | |
multiplayer |
off | on | multiplayer.* for scripts: host, join and play a rollback match over whichever of websocket and webtransport the build has. |
nothing |
parallel |
off | off | rapier's solver on rayon. Native builds want it; a browser can only take it with shared memory and atomics, which is the threaded web runtime alone. | nothing |
physics2d |
off | on | The 2D physics world: physics2d.* and its components. |
nothing |
physics3d |
off | on | The 3D physics world: physics3d.* and its components. |
nothing |
vorbis |
off | on | nothing | |
wav |
off | on | nothing | |
webgl |
on | off | WebGL2 beside WebGPU in a browser, for a page without WebGPU. 1.0 MB of a web module, and nothing on any other target. | glow, wgpu-core, wgpu-core-deps-wasm, wgpu-hal, wgpu-naga-bridge |
websocket |
off | on | websocket.* for scripts, and the websocket Transport. Off, a build drops tungstenite, rustls and the frame codec; the Gamend addon's realtime socket runs on them. |
nothing |
webtransport |
off | on | The WebTransport Transport, over QUIC: the transport rollback and replication are meant to run on. Off, a build drops quinn, its runtime and the certificate machinery, which is most of what a networked build costs. |
nothing |
window |
on | on | Windowed rendering (kiss3d/wgpu). | egui-wgpu, glow, kiss3d, naga, wgpu, winit, … (27 crates) |
What the web runtime resolves
The features on in the dependencies that weigh most. A feature named here is
enabled; whether it links code on the web is up to that crate's own target
gates (winit's X11 is on and compiles nothing in a browser).
| Crate | Version | Features on |
|---|---|---|
egui |
0.37.0 | none |
wgpu |
30.0.1 | dx12, fragile-send-sync-non-atomic-wasm, gles, metal, parking_lot, std, vulkan, web, web-sys, webgpu, wgsl |
image |
0.25.10 | bmp, exr, hdr, jpeg, png, tga, webp |
rodio |
0.23.0 | cpal, dither, experimental, flac, mp3, mp4, noise, playback, rand, rand_distr, symphonia, symphonia-aac, symphonia-flac, symphonia-isomp4, symphonia-mp3, symphonia-ogg, symphonia-pcm, symphonia-vorbis, symphonia-wav, vorbis, wasm-bindgen, wav |
rapier3d |
0.36.1 | alloc, debug-render, dim3, enhanced-determinism, f32, fem, serde-serialize, std |
parry3d |
0.31.1 | alloc, dim3, downcast-rs, ena, enhanced-determinism, f32, hashbrown, indexmap, required-features, rstar, serde, serde-serialize, serde_arrays, slab, smallvec, spade, std |
cosmic-text |
0.19.0 | monospace_fallback, shape-run-cache, std, swash, sys-locale |
wesl |
— | not in the runtime |
The web profile
The web profile in the engine's Cargo.toml sets opt-level = "z", fat
LTO, one codegen unit, panic = "abort" and stripped symbols, and the script
runs wasm-opt -Oz after bindgen. panic_immediate_abort would cut more, and
a panic in a browser would then log nothing.