Skip to content

Web Configuration ​

Set properties in MyGame.web.csproj, which references 2dog.engine and 2dog.browser-wasm. The generated host uses RuntimeIdentifier=browser-wasm and defaults to Release; pass -c Debug for a Debug build. See global settings for the game directory and import controls.

Properties ​

PropertyDefaultPurpose
TwoDogWebVariantFollows the configurationNative engine variant: debug or release
TwoDogExportPacktrueExport game content; false uses an existing wwwroot/godot.pck
TwoDogWebExportPresetWebPreset in export_presets.cfg
TwoDogWebPackNamegodot.pckDeployed pack name
TwoDogWebSizeManifesttrueWrite twodog.sizes.json for loading progress
TwoDogWebStripMapstrue with the release engineRemove JavaScript source maps
TwoDogWebPrecompresstrue with the dotnet CLIWrite Brotli (.br) and gzip (.gz) copies of large bundle files
TwoDogWebPrecompressLevelOptimalOptimal (balance speed and size), Fastest, SmallestSize (slower), or NoCompression; case-insensitive
TwoDogWebPrecompressFormatsbr;gzCompressed copies to write: br, gz, or br;gz
TwoDogWebPrecompressKeepOriginalstruefalse removes the uncompressed engine, pack and .NET binaries; needs gz (upload limits)
TwoDogWebSideModuleExportstrueExport native symbols used by GDExtensions
WasmEnableThreadsfalseLink the multithreaded runtime and engine (experimental)
TwoDogWebSideModuleTableSlots16384With threads: function table slots reserved for GDExtension side modules
WasmEmitSymbolMapfalse in Release, true otherwiseInclude native symbols for stack traces; explicit settings override the default
WasmInitialHeapSize256MBInitial memory allocation; memory can grow
TwoDogWebGpuCachePathSystem temporary directoryWritable Emscripten port cache for WebGPU

2dog.browser-wasm restores both debug and release natives. If the payload for the selected variant is missing, the build fails.

If you change TwoDogWebPackName, change the pack URL in your boot page to match.

Experimental WebGPU ​

See New Tricks: WebGPU for browser requirements, boot settings, and Compatibility fallback. See Forward+ and Mobile on the web to select the web renderer and enable shader baking before export.

Precompression ​

The dotnet CLI writes Brotli (.br) and gzip (.gz) copies next to the large bundle files. Visual Studio's MSBuild skips this step. Choose the settings that match your web server:

Your serverSettings
Serves precompressed filesDefaults, or TwoDogWebPrecompressFormats set to the one format it serves (br or gz)
Compresses responses itselfTwoDogWebPrecompress=false
Compresses nothingDefaults, plus compression in the page
Compresses nothing and limits the upload sizegzip only

Servers that serve precompressed files include Caddy with precompressed, and nginx with gzip_static or brotli_static. They send a copy in place of the original when the browser accepts its format, so keep the originals for browsers that do not. dotnet-serve with -b -z compresses responses itself and ignores the copies.

A publish removes copies of formats you no longer select, and with TwoDogWebPrecompress=false it removes all of them, so a server never sends an outdated copy.

Compression in the page ​

On a server that compresses nothing, the page can download the .gz copies and inflate them with the browser's built-in gzip decoder, DecompressionStream. Chrome does not support Brotli there, so the page uses gzip. Set this in wwwroot/index.html:

javascript
const TWODOG_PCK_GZ = true;

The page then requests godot.wasm.gz, godot.pck.gz and the .gz copies of the .NET binaries in _framework/. Scripts and the page itself still load uncompressed. If a .gz copy is missing, the page falls back to the original. Do not use this on a server that compresses responses, because the files would be compressed twice.

Web hosting with upload limits ​

The uncompressed bundle, engine and all, of an empty project is about 70 MiB, plus 10-15 MiB per compressed variant of the Godot engine.

If your web hosting service limits how much you can upload, ship only the gzip copies of the engine, the pack and the .NET binaries.

That's about 18-20 MiB for an empty game.

xml
<PropertyGroup>
  <TwoDogWebPrecompressFormats>gz</TwoDogWebPrecompressFormats>
  <TwoDogWebPrecompressKeepOriginals>false</TwoDogWebPrecompressKeepOriginals>
</PropertyGroup>

A minimum-size deploy is not a smaller game download

This deploy fits web hosting services that limit how much you can upload. It does not make your game smaller for players. Instead, it trades their download experience for upload size. Compared with a full deploy, players:

  • download gzip, which is larger than Brotli
  • cannot load the game in browsers without DecompressionStream, because there are no originals to fall back to

Players get the best experience from a full deploy with all variants (Brotli, gzip and the uncompressed originals), where the server sends each browser the best format it accepts.

The page has nothing to fall back to, so the publish turns on compression in the page in the bundle's copy of index.html. Your wwwroot/index.html stays unchanged. The build fails if gz is not among the formats.

Trimming and AOT ​

See Trimming for assemblies accessed only through reflection.

Browser hosts run on Mono. Enable Mono's AOT compiler in the host's csproj instead of PublishAot. This setting applies to dotnet publish:

xml
<PropertyGroup>
  <RunAOTCompilation>true</RunAOTCompilation>
</PropertyGroup>

-p:RunAOTCompilation=true sets it for a single publish.

See the Web host guide for serving and deploying AppBundle/.

2dog is Free and Libre Open Source under the MIT License.
2dog is not affiliated with or endorsed by the Godot Foundation.
Godot is licensed under the MIT License; the Godot logo is by Andrea Calabró under CC BY 4.0. @icons made by Voxy under the MIT License.
Continuous Integration compute graciously supported by Blacksmith.