Package and publish client resources
Why package resources?
Section titled “Why package resources?”Players need the client scripts, interfaces, audio and custom assets used by the server. Packaging prepares those files for download and creates a manifest with their paths, sizes and hashes. The client uses that manifest to verify downloads and reuse files already in its cache. Compression reduces download size, and optional encryption controls how files are stored on the player’s PC.
| Environment | Recommended workflow |
|---|---|
| Development | Let the server package files at startup and serve them through its built-in HTTP server. |
| Production | Build and publish resources separately to S3 or compatible storage, with a CDN serving downloads. |
For production, this keeps packaging work and resource downloads off the game server. A release can be uploaded while servers remain online, then selected when each server restarts.
resource-tool is the standalone command-line utility for this workflow. Its
publish command packages the client files and uploads them through AWS CLI
v2. It can run on your development PC or in a deployment pipeline.
Development: package on startup
Section titled “Development: package on startup”Point resources.pack.path at your built client files. For the
development server, use:
[resources]mode = "local"path = ".resources"url = "http://127.0.0.1:27018/"
[resources.pack]path = "resources/client"compression = trueencryption = false
[resources.http]enabled = truehost = "127.0.0.1"port = 27018Each startup prepares .resources and serves it at the configured URL. After
changing scripts or assets, build them and restart the server. Clients check
for updated resources when reconnecting. See
Development workflow.
Keep source and output folders separate, with neither inside the other. The
packer scans the source recursively and does not use .gitignore. Keep server
scripts, credentials and development dependencies outside the client folder.
Production: publish to S3 and serve through a CDN
Section titled “Production: publish to S3 and serve through a CDN”1. Prepare storage and the CDN
Section titled “1. Prepare storage and the CDN”Create a bucket and a CDN distribution before publishing. For AWS, use S3 with CloudFront. CloudFront can access a private bucket through Origin Access Control. The CDN download URLs must be accessible to clients without a browser login.
The examples use these locations. Replace them with your own:
| Setting | Example | Purpose |
|---|---|---|
publish.target |
s3://revo-assets-example/resources |
Bucket and prefix used by AWS CLI for uploads. |
resources.url |
https://cdn.example.com/resources/ |
Base URL used by servers and clients for downloads. |
With the bucket root as the CDN origin and no additional origin path,
resources/release.json in S3 must be available at
https://cdn.example.com/resources/release.json. Keep that mapping consistent
for every file under the prefix.
Configure delivery as follows:
- Use HTTPS and allow
GET,HEADand HTTP range requests. - Serve the packaged bytes unchanged. Disable automatic compression and file
transformations for resource downloads. Packed blobs use
application/octet-stream, including files ending in.gz. - Respect the cache headers written by the publisher. Hash-named files are
immutable and can be cached for a long time.
release.jsonusesno-cache,max-age=0,must-revalidateso server startups can find the current release.
For CloudFront, set the minimum TTL to 0 for release.json. A positive minimum
TTL can override its cache headers. See
CloudFront cache duration.
2. Install the publishing tools
Section titled “2. Install the publishing tools”Download the resource-tool package through developer access. On Windows, use
resource-tool-<version>-release-win64.zip. Extract it into a folder of your
choice. This guide uses C:\Revo\resource-tool. Keep its lib/ directory beside
the executable.
Install AWS CLI v2 on the machine that will publish resources. Configure a named profile for your storage account. For access-key credentials:
aws --versionaws configure --profile revo-resourcesFor an account using IAM Identity Center, follow the AWS CLI SSO setup and use the resulting profile name instead.
The publishing identity needs permission to list the bucket and read, write and delete objects under the upload prefix, including the publishing lock. Ensure multipart uploads are allowed for large files. Keep these permissions limited to the storage used for resources.
resource-tool uses the selected AWS CLI profile. If publish.profile is omitted,
AWS CLI uses its usual credential configuration, including environment or role
credentials. If aws cannot be found, set AWS_CLI to the full executable path.
3. Configure the publication
Section titled “3. Configure the publication”Create a working folder of your choice. This guide uses C:\Revo\resource-build
with built client files in its client/ subfolder.
Create a private resource key once:
Set-Location C:\Revo\resource-build& "C:\Revo\resource-tool\resource-tool.exe" keygen --output resources.keyThe key lets the server verify the published release. It is required for remote
resources even when encryption is disabled. Use the same key for all subsequent
uploads and releases. Keep it outside client/ and the public output, and deploy
a copy securely to the game server. See Resource encryption and keys
for encryption settings and key rotation.
Save publish.toml beside the key:
[resources]mode = "local"path = "dist/resources"url = "https://cdn.example.com/resources/"key_path = "resources.key"
[resources.pack]path = "client"compression = trueencryption = true
[publish]target = "s3://revo-assets-example/resources"profile = "revo-resources"
[api]project_secret = "YOUR_PROJECT_SECRET"On the publishing machine, mode = "local" prepares the package from local files.
Paths are relative to publish.toml. Use the private API credential supplied
through developer access for project_secret. Release tracking uses it to keep
files required by registered servers and manage cleanup.
For S3-compatible storage, add endpoint = "https://s3.example.com" and, if
required by the provider, region = "us-east-1" under [publish]. The endpoint
is the storage API address. Keep resources.url pointed at the CDN download URL.
4. Publish
Section titled “4. Publish”After building the client files, run:
& "C:\Revo\resource-tool\resource-tool.exe" publish --config .\publish.tomlThe command packages the files, uploads new payloads through AWS CLI, reuses existing payloads and verifies the uploaded inventory and metadata. It selects the release only after the required files are available. Upload order and cache headers are handled by the tool.
A successful command prints a JSON summary containing manifestSha256. Keep
that hash with your deployment record. Preserve dist/resources, including its
private cache/, so later publications can reuse the packing cache. Only the
public release files are uploaded.
Running servers continue using their selected release during publication. Before restarting them, check the CDN URL:
$release = Invoke-RestMethod https://cdn.example.com/resources/release.json($release.payload | ConvertFrom-Json).manifestSha256The hash should match manifestSha256 from the publish result. A different hash
can indicate stale CDN metadata. Resolve any 403, 404 or unexpected HTML
response before restarting the server.
5. Configure the game server
Section titled “5. Configure the game server”Copy the same resources.key to secrets/resources.key on the server and merge
these settings into its config.toml:
[api]enabled = trueproject_secret = "YOUR_PROJECT_SECRET"public_host = "play.example.com"
[resources]mode = "remote"url = "https://cdn.example.com/resources/"key_path = "secrets/resources.key"
[resources.http]enabled = falseUse the same API credential as the publisher and your server’s public address.
Remove [resources.pack] and [resources.pack.scripts] from the server
configuration. Keep sources and the private packing cache on the publishing
machine. The CDN serves the published files.
On startup, the server downloads and authenticates release.json, verifies its
manifest and registers the selected release with the API. Clients download the
files from the CDN. When encryption is enabled, the game server supplies the
matching decryption key during connection.
Updates and rollback
Section titled “Updates and rollback”Build the changed client files and run publish again. Once CDN delivery has
been checked, restart the server to select the new release. Existing clients
check the new manifest when reconnecting and reuse matching cached files.
To keep a server on a specific release, set release = "SHA256" under
[resources], using the manifest hash printed by the publisher. An omitted or
empty value selects the latest published release at startup.
To select the previous retained release for subsequent server starts, run:
& "C:\Revo\resource-tool\resource-tool.exe" rollback --config .\publish.tomlRestart the affected servers afterward. If a server has a release pinned, update or remove that setting before restarting.
Cleanup preserves tracked releases still used by servers and retained rollback releases. If cleanup is skipped or fails, read the command’s message before removing old files manually.
See Development workflow for changes that also require a GTA restart.