Skip to content

Bundle Config

Every bundle has a config.toml manifest at the bundle folder root. The UGC server reads it whenever it loads the bundle. The manifest decides what runs where, what is streamed to clients, and whether the folder is a valid bundle at all.

A complete manifest looks like this:

config.toml
[General]
description = "Example game mode bundle"
author = "replay.re"
version = "1.0.0"

[Scripting]
client_blob = "cl.wasm"
server_blob = "sv.wasm"
enable_vfs = true

[ReUi]
initial_page = "index.html"
content_root = "ui/"
files = [
    "ui/index.html",
    "ui/_app/**",
    "ui/fonts/**",
    "ui/sw.js",
]

[Meta]
config_version = "alpha_playtest"

[General]

Informational metadata attached to the bundle:

  • description - A short summary of what the bundle does
  • author - The author or studio / group name
  • version - A version string of your choosing

[Scripting]

The compiled components:

  • client_blob - File name of the client component, relative to the bundle root
  • server_blob - File name of the server component, relative to the bundle root
  • enable_vfs - Mount the bundle's vfs/ folder into the server component's sandbox (server realm only). See Bundle IO for what the VFS is and how to use it

Each blob is optional. A bundle may ship only one side, or neither if it is UI-only. Any blob that is declared must exist inside the bundle folder, a manifest naming a missing file is rejected. The blob file must be a compiled WASI component of the matching side.

[ReUi]

The optional in-game web UI. A bundle with a UI gets a sandboxed iframe on each client that loads initial_page. The page and its assets are streamed to the client as part of the bundle.

  • initial_page - The page to load in the frame. Use a bundle-relative path (see content_root below), or an absolute https:// URL to host the UI elsewhere. Required whenever files is present
  • files - Every file the UI needs, relative to the bundle root. Only the listed files are delivered to clients, so every asset the page references at runtime must be listed.
    • Globbing is supported: * matches within a directory, ** matches recursively
    • Entries that are not globs must name existing files, or the bundle is rejected
  • content_root - Optional. When a framework (for example a Svelte or Vite build) emits absolute URLs and expects to be served from the origin root, set content_root to the folder inside the bundle where that content lives. Requests to the origin root are then served from that folder. The example above packages a ui/ folder that is served as if it were the origin root: index.html resolves to ui/index.html, /_app/... to ui/_app/...

When no UI is shipped, omit the whole section (the manifest still needs the other three sections)

[Meta]

  • config_version - The manifest format version. "alpha_playtest" is the only accepted value for now

Bundle parsing

When the server realm loads a bundle it verifies that:

  • config.toml sits directly in the bundle folder root
  • All provided sections parse and config_version is accepted
  • Every declared blob exists inside the folder
  • Every non-glob [ReUi] file entry exists, and initial_page is set whenever files is set

A folder that fails validation is reported in the server log and ignored as a bundle. The folder name becomes the bundles name, so pick a short, stable and unique name.

See Project Layout for how the files a manifest points at are produced and staged.