Bundle Distribution

This page targets server owners. If you want to create bundles, see Authoring instead.

How bundles work

Bundles get streamed to clients automatically. This ensures that all clients connected to your server are running on the same code, producing the expected data nad adhering to the same rules.

In most cases there is not much to be aware about, but a few things deserve mention.

As described in Bundle Config, bundles come with a config.toml manifest. This manifest controls what parts of the bundle get sent to the client.

In most cases this will only be the manifest itself, the cl.wasm blob and potentially some UI files.

Warning

Files mentioned in [ReUI] -> files are packaged into the client side bundle!

Do NOT! include files that are suppsed to stay on your server side here

Managing bundles

Bundle presence can be controlled at server runtime. You can start and stop bundles at any time. When changing the bundle state, the server will inform clients about that and they will follow that command.

This is fine in most cases, but be aware that in some edge-cases bundles with a high number of hooks dont like to be hot-reloaded. This is not a rule and mostly fine, but if you are testing and restarting bundles over and over, expect to restart your client once in a while.

Testing bundles

During development or testing, the ConVar sv_ugc_automatic_restarts might be interesting to you. It uses a file system monitor to detect changes to a bundle and will restart it automatically. This is not recommended for production use, as automatic restarts tend to "over fire" if your deployment replaces files too slow. This causes multiple bundle restarts in quick succession, which is not recommended.

CDN hosting

If your server is popular or your player base is distributed around the globe, hosting bundles from a CDN might be of interest to you. The server offers the ConVar sv_ugc_bundle_url. You can point clients at a CDN or download server of your choosing. The CDN has to handle HTTP requests in a specific way:

sv_ugc_bundle_url "http://cdn-url.com/"

The client will try to download it from: cdn-url.com/<bundle-name>.zip?<bundle-crc-hash>

Please note the trailing slash on the CDN URL and the bundle crc hash parameter. This is used to ensure no stale cache entries are referenced, so make sure that your CDN publish logic handles that.

Info

A good setup would be to forward the requests from your CDN to your game server and let it handle the caching automatically. Ensure .zip files are tagged as cachable and that the URL parameter does not disable caching