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

[Networking]
allowed = [
    "https://api.example.com",
    "http://127.0.0.1:8080",
]

[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
  • backtrace - Show stack traces of the client component (client realm only, default false). When off, a client's log shows the exception type and message but no stack frames, for unhandled exceptions, script errors and the ExportExceptions your exports pass to other bundles. Turn it on while developing. The server always logs full stack traces

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.

[Networking]

The optional outbound network allow list for the server component. Server code has no network access of its own, the only way it can connect is re.net.Http (see HTTP Requests). That API is limited to the destinations listed here.

  • allowed - Endpoints the server component may contact. Each entry is host, host:port, scheme://host, or scheme://host:port

Entries without a scheme cover both http and https. Entries without a port use the scheme's default port, or both 80 and 443 when no scheme is given. Host names are matched case insensitively and must match exactly, no wildcards.

[Networking]
allowed = [
    "api.example.com",             # https://api.example.com and http://api.example.com
    "https://secure.example.com",  # https://secure.example.com:443 only
    "http://127.0.0.1:8080",       # http://127.0.0.1:8080 only
]

The list is enforced on every request, including the destinations a redirect points at, so a redirect can never take a request outside the list.

A malformed entry is reported in the server log and ignored. A request to a destination that is not listed fails in the bundle with a curl error code and is logged.

[Database]

Optional. Defines aliases a server bundle may open with re.sql. This group is server side only. It is stripped from the config.toml that ships to clients, to prevent credentials from leaking to clients.

Bundle code opens connections by referencing an alias:

[Database.players]
type = "postgres"
conninfo = "host=${DB_HOST} port=5432 dbname=players user=ugc password=${DB_PASSWORD}"

[Database.stats]
type = "sqlite"
name = "stats.db"
await using var db = new re.sql.SqlConnection(re.sql.SqlConnection.For("players"));
await db.OpenAsync();

Each alias takes:

  • type - "postgres" or"sqlite"
  • conninfo - Only used by the postgres baackend. It expects a a libpq connection string, in which ${VAR} placeholders are replaced with the evironment variables. It must specifiy exactly one host. hostaddr, service, unix sockets and other variants are not allowed
  • name - Only used by the sqlite backend. Databases will be created as in the dir data/persistent/<bundle>/. The file size limit on sqlite databases is 1 GB

sqlite databases are only accessible by the bundle that declared them. If another bundle uses the same name, it will get its own file in its own directory.

Note

Environment expansion is only applied to this group

No other config region expands variables currently. This might change in the future

[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
  • Every [Networking] allowed entry is a valid endpoint

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.