Skip to content

Search

Documentation

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 the content-encoding header), 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 own fonts/ and the Source Sans 3 face the engine carries.
  • compile: the script compiler, the WESL shader linker and the .bs to 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-sources runs only in a build with compile.
  • import: the importers and SVGs read in place.
  • bs-wasmi: the script interpreter beside bs-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 with webgl for 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-std and optimize_for_size on the pinned stable, 1.14 MB. Sorting a large array is slower; WEB_STD=stock builds 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.

Where an export pack's bytes are, and what lossless re-encoding takes off

[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 quantized and vorbis is 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-run prints 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
  • physics2d and physics3d each register one world. Without physics3d a template is 2.4 MB smaller raw and 0.4 MB brotli; without physics2d, 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, vorbis and wav each 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 a vorbis build.
  • The script needs the wasm32-unknown-unknown target, the wasm-bindgen CLI at the version in Cargo.lock (checked), wasm-opt from binaryen, and brotli for the size line it prints.
  • It refuses a module under 5 MB: a build whose entry point was optimised away.
  • http, websocket, webtransport, gamend and multiplayer gate 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.

Are you sure?