Skip to content

Package and publish client 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.

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 = true
encryption = false
[resources.http]
enabled = true
host = "127.0.0.1"
port = 27018

Each 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”

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, HEAD and 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.json uses no-cache,max-age=0,must-revalidate so 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.

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:

Terminal window
aws --version
aws configure --profile revo-resources

For 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.

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:

Terminal window
Set-Location C:\Revo\resource-build
& "C:\Revo\resource-tool\resource-tool.exe" keygen --output resources.key

The 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 = true
encryption = 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.

After building the client files, run:

Terminal window
& "C:\Revo\resource-tool\resource-tool.exe" publish --config .\publish.toml

The 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:

Terminal window
$release = Invoke-RestMethod https://cdn.example.com/resources/release.json
($release.payload | ConvertFrom-Json).manifestSha256

The 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.

Copy the same resources.key to secrets/resources.key on the server and merge these settings into its config.toml:

[api]
enabled = true
project_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 = false

Use 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.

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:

Terminal window
& "C:\Revo\resource-tool\resource-tool.exe" rollback --config .\publish.toml

Restart 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.