Addressables

Addressables let you change remote content — levels, art, balance data — without publishing a new base build. You upload the catalog and bundles once, publish them, and players pick them up on their next catalog check. Addressables are supported for WebGL only.

Addressables go live as soon as you publish them. There is no review step — unlike base builds, which wait for a SusaPlay reviewer. Instead, SusaPlay checks every publish against your live build and refuses content that would break it, and you can roll back to an earlier release.

Enable Addressables

Developer Portal → your game → Addressables → Enable
Copy the Remote Load Path shown there

https://games.susaplay.com/addressables/{gameId}/

Enabling is a one-time setup step and is only available in the portal.

Unity build settings

Set these before you build the base game:

Setting	Value
Build Remote Catalog	Enabled
Remote Load Path	The exact URL from the Developer Portal
Bundle Naming Mode	`Filename And Hash` or `Full Path And Hash`
Catalog format	Binary — SusaPlay accepts `catalog_{version}.bin`, not `.json`

The Remote Load Path is baked into the WebGL build. If it is wrong when you build, no bundle upload can fix it for players who already have that build — you have to publish a new base build.

A binary catalog is the default in Addressables 2.x, which runs on Unity 6: leave Enable Json Catalog off in the Addressable Asset Settings. Addressables 1.x writes a JSON catalog, which SusaPlay refuses. If you stay on Unity 2021.3 or 2022.3, use Addressables 1.21.3 or later and add ENABLE_BINARY_CATALOG to the WebGL Scripting Define Symbols in Player Settings, then rebuild both the player and the content. Bundle Naming Mode matters because uploaded bundle filenames must carry Unity’s 32-character lowercase hash, such as remote_mainmenu_scenes_all_8a60300e1ab74f60538aa6bf690bc976.bundle. That hash is also how SusaPlay knows a bundle has not changed.

File requirements

File	Required name	Max size
Catalog hash	`catalog_{version}.hash` — for example `catalog_1.1.1.hash`	10 MB
Catalog bin	`catalog_{version}.bin` — same version as the hash	10 MB
Bundle	`*.bundle` containing the 32-character hash segment	200 MB

A publishable set is exactly one catalog hash, exactly one catalog bin with the same version suffix, and at least one bundle. Mixing catalog files from two different builds is rejected — that pair is what tells Unity which bundles to load.

Upload from the Developer Portal

Developer Portal → your game → Addressables, then drop your whole Addressables output folder onto the upload area. The portal picks out the catalog pair and every .bundle, ignores everything else, uploads them in parallel with per-file progress, and skips any bundle SusaPlay already has. Click Review and publish to see what the publish would change — files added and removed, the catalog version, and each compatibility check. Click Publish to make it live. If a check fails, the portal shows why and offers no publish button.

Upload from CI

The same three shapes work with your developer API key. Sign the whole set in one call, upload the files, then register them.

1. Sign the batch

API=https://api.susaplay.com/catalog/game/$GAME_ID/addressables

curl -sS -X POST "$API/upload-batch" \
  -H "Authorization: ApiKey $DEVELOPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"files":[
        {"filename":"catalog_1.1.1.hash","sizeBytes":120},
        {"filename":"catalog_1.1.1.bin","sizeBytes":8400},
        {"filename":"remote_scene_0123456789abcdef0123456789abcdef.bundle","sizeBytes":52428800}
      ]}'

fileType is optional — SusaPlay infers it from the filename. The response holds an uploads array with one signed uploadUrl per file, and a reused array listing bundles you should not send because SusaPlay already has them.

2. Upload each file

PUT each uploadUrl with the Content-Type given alongside it. URLs are valid for 20 minutes. Skip everything under reused.

3. Register and publish

curl -sS -X POST "$API/register-batch" \
  -H "Authorization: ApiKey $DEVELOPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"files":[
        {"filename":"catalog_1.1.1.hash"},
        {"filename":"catalog_1.1.1.bin"},
        {"filename":"remote_scene_0123456789abcdef0123456789abcdef.bundle"}
      ]}'

curl -sS -X POST "$API/publish" \
  -H "Authorization: ApiKey $DEVELOPER_API_KEY"

register-batch reports what it recorded, what it reused, and anything missing because its upload never arrived. publish promotes the whole staged set to live and returns the new releaseNumber, publishedFiles, changedFiles, unchangedFiles, removedFiles, the catalogVersion now serving, and deletedReleases — older releases that can no longer be restored (see Releases). To review before you publish, see Plan a publish first.

Enabling Addressables and deleting staged files stay in the portal. Your API key covers uploading, registering, publishing, and rolling back. Uploading and registering need the addressables:write permission, as does planning (dryRun); publishing and rolling back need addressables:publish.

Only changed bundles move

A bundle filename contains its content hash, so a bundle whose name already exists in your live set holds the same bytes. SusaPlay skips the upload and keeps the file it has. On a typical incremental Addressables build only the catalog pair and the few bundles you touched are transferred and re-cached, which is why publishing is fast even for a large set. A file that is live but absent from your new set stops reaching players when you publish. Publish the complete set every time, not just the changed files.

Releases

Every publish creates a release, numbered 1, 2, 3 and so on for each game. A release is the catalog pair and the bundles it names. SusaPlay keeps the three newest releases plus the live one; publishing deletes older releases, and their files once no kept release uses them. The portal lists the kept releases under Addressables → Releases, newest first, with the date, the catalog version, the file count and size, and the build that was live when each was published. GET /catalog/game/{gameId}/addressables returns the same list as releases, with liveReleaseId and operationInProgress. If you published Addressables before releases existed, your current live set becomes release 1 on your next publish, so you can roll back to it.

Compatibility check

Before a publish or a rollback changes anything, SusaPlay reads the catalog and checks it against your game’s live build:

Check	Fails when
C1 — The live build finds this catalog	The remote catalog the live build requests is not in the set, or the live build requests it from a path other than your Remote Load Path
C2 — Every bundle exists	A bundle the catalog names is neither in the set nor shipped inside the live build
C3 — Bundles load from this game	A remote bundle loads from anywhere other than your Remote Load Path, or from a path with an unresolved `{...}` placeholder
C4 — The catalog can be read	The catalog is missing or is not a binary catalog

If your game has no live build yet, C1 and the check for bundles inside the build are skipped. A failed check refuses the request with 409 INCOMPATIBLE_CATALOG. Nothing changes, and your live content keeps serving. error.compatibility holds the result:

{
  "success": false,
  "error": {
    "code": "INCOMPATIBLE_CATALOG",
    "message": "Publishing would break the live game: …",
    "compatibility": {
      "compatible": false,
      "liveBuild": "1.0.9",
      "requestedCatalog": "catalog_1.hash",
      "checks": [
        { "id": "C1", "status": "failed", "message": "…" },
        { "id": "C2", "status": "passed", "message": "…" },
        { "id": "C3", "status": "passed", "message": "…" },
        { "id": "C4", "status": "passed", "message": "…" }
      ]
    }
  }
}

Each check’s status is passed, failed, skipped, or info. Only failed refuses.

Most failures come from building the content with different settings than the live build — a different Remote Load Path, or a group switched between local and remote. Build the content from the same project and profile as the live build, or publish a new build first.

If you believe a check is wrong, contact SusaPlay support.

Plan a publish first

Send "dryRun": true to see what a publish would do without changing anything:

curl -sS -X POST "$API/publish" \
  -H "Authorization: ApiKey $DEVELOPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dryRun": true}'

The response holds the plan:

Field	Meaning
`releaseNumber`	The release this publish would create
`filesAdded`, `filesRemoved`	Files the publish would add or take away
`filesChanged`	Files on both sides whose content is replaced — the catalogs
`filesUnchanged`	Bundles already live and kept as they are
`catalogVersion`	`from` the live catalog version `to` the staged one
`compatibility`	The compatibility check’s result
`releasesDropped`	Releases the publish would delete
`expectedLiveReleaseId`, `expectedStagingHash`	Send these back with the real publish

A dry run answers 200 even when a check fails — read compatibility.compatible. Send the expected values back exactly as the plan returned them: expectedLiveReleaseId is a string, such as "4", or null if your game has no release yet. To publish exactly what you reviewed, send the two expected values back:

curl -sS -X POST "$API/publish" \
  -H "Authorization: ApiKey $DEVELOPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expectedLiveReleaseId": "4", "expectedStagingHash": "9f2c…"}'

If the live release or the staged files changed since the plan — someone else published, or uploaded another file — the publish is refused with 409 CONFLICT. Plan again. Only one publish or rollback runs per game at a time. A second one gets 409 OPERATION_IN_PROGRESS; wait a few minutes and try again.

Roll back

Rolling back makes a kept release live again. Use it when a publish passed the checks but the content is wrong — a bad level, broken balance data. In the portal: Addressables → Releases, then Roll back to this release on the release you want. The portal shows the same review as a publish, then rolls back. From CI, plan first, then roll back:

curl -sS -X POST "$API/rollback" \
  -H "Authorization: ApiKey $DEVELOPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"releaseId": "3", "dryRun": true}'

curl -sS -X POST "$API/rollback" \
  -H "Authorization: ApiKey $DEVELOPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"releaseId": "3", "expectedLiveReleaseId": "4"}'

With dryRun, the response is the plan: filesAdded, filesRemoved, filesChanged, filesUnchanged, catalogVersion, compatibility and expectedLiveReleaseId. The real rollback answers with releaseNumber, fromReleaseNumber, catalogVersion, fileCount, and compatibility. A rollback:

is checked against your current live build, like a publish. A release built for an older build may fail C1–C3 if you have since published a new build;
creates no new release, so undoing it is another rollback, to the newer release. The release you roll away from stays only if it is among the three newest;
leaves your staged files untouched.

It is refused when:

Response	Cause
`404 NOT_FOUND`	The release is not kept. Only the three newest releases and the live one can be restored
`409 FAILED_PRECONDITION`	The release is already live
`409 RELEASE_INCOMPLETE`	Files the release needs are gone. The message names them
`409 INCOMPATIBLE_CATALOG`	The release would break the live build
`409 CONFLICT`	The live release changed since you sent `expectedLiveReleaseId`
`409 OPERATION_IN_PROGRESS`	A publish or rollback is already running

Limits

Limit	Value
Files in one published set	1,500
Total size of one published set	5 GB
Files per `upload-batch` call	250

Split a larger set across several upload-batch and register-batch calls, then publish once at the end.

Caching

Catalog files are served with no-cache, so a published catalog reaches players immediately. Bundles are immutable and cached for a year at the edge — safe, because a changed bundle gets a new filename.

If your content is suspended

SusaPlay can suspend a game’s Addressables — a kill switch for broken or unsafe remote content. While suspended, player requests that are not already cached at the edge fail, and the base build keeps running. The portal shows the reason. Uploading and publishing are blocked until an admin reinstates it.

Troubleshooting

Message	Cause
`Bundle filename must include Unity's 32-character lowercase hash segment`	Bundle Naming Mode is not `Filename And Hash` or `Full Path And Hash`
`Catalog hash file must be named catalog_{version}.hash`	You uploaded a renamed or non-catalog file
`Catalog version mismatch`	The hash and bin come from different Addressables builds
`Could not determine the addressables file type of catalog_….json`	The catalog is JSON. Build a binary catalog — see Unity build settings
`Addressables are not enabled for this game`	Enable them in the portal first
`Staging addressables are not ready to publish`	The set is missing the catalog pair or has no bundle
`Addressables set would hold … over the 1500 file limit`	Split the content or remove unused bundles
`Publishing would break the live game: …`	A compatibility check failed. The rest of the message says which
`The live release changed since the plan` or `Staging changed since the plan`	Someone published or uploaded after your dry run. Plan again
`Another Addressables publish or rollback is running for this game`	Wait a few minutes and try again
`Release … is not retained`	Only the three newest releases and the live one can be restored
`Release … cannot be restored: Storage no longer has …`	Files the release needs were deleted. Publish the content again instead

Getting Started

Integration

SDK

API

Enable Addressables

Unity build settings

File requirements

Upload from the Developer Portal

Upload from CI

1. Sign the batch

2. Upload each file

3. Register and publish

Only changed bundles move

Releases

Compatibility check

Plan a publish first

Roll back

Limits

Caching

If your content is suspended

Troubleshooting

​Enable Addressables

​Unity build settings

​File requirements

​Upload from the Developer Portal

​Upload from CI

​1. Sign the batch

​2. Upload each file

​3. Register and publish

​Only changed bundles move

​Releases

​Compatibility check

​Plan a publish first

​Roll back

​Limits

​Caching

​If your content is suspended

​Troubleshooting

Enable Addressables

Unity build settings

File requirements

Upload from the Developer Portal

Upload from CI

1. Sign the batch

2. Upload each file

3. Register and publish

Only changed bundles move

Releases

Compatibility check

Plan a publish first

Roll back

Limits

Caching

If your content is suspended

Troubleshooting