Game Registry

Builds — bring your own game

What a game installs. Upload a zip, install from Steam, or fetch a vendor archive.

accounts/{account}/builds/{build}

Builds belong to the account, not a project: a studio building one server binary uses it across every project, and a copy per project would mean re-uploading gigabytes to change nothing.

Every build has a kind

kind is required and cannot be changed afterwards. A dedicated server — anything a Playpute server runs — is KIND_SERVER (--kind server in the CLI, kind = "server" in Terraform). A game refuses a build of the wrong kind when you save it, rather than leaving you with a server that installs and has nothing to start.

Three sources

Most game servers are already published somewhere, so a build declares a source, and only an upload stores files with Plany.

For the large family of Source and Steamworks games, an app id is the whole configuration.

text

1source:
2  steam_cmd:
3    app_id:  4020        # the DEDICATED SERVER's app id
4    branch:  ""          # empty takes the public branch
5    validate: true

Use the dedicated server's app id, which is usually not the game's. Garry's Mod is 4000 to play and 4020 to host.

username and password are for a dedicated server that refuses anonymous downloads; most do not. branch_password opens a private branch.

For a vendor that publishes a server directly — Mojang's server jar, a Forge installer, a modpack zip.

text

1source:
2  archive:
3    url:             "https://example.com/server-1.20.4.zip"
4    checksum_sha256: "9f86d0…"
5    extract:         true
6  install_commands:
7    - "java -jar forge-installer.jar --installServer"

Nothing is mirrored: the URL is fetched when a server installs the build, so the vendor's terms stay between you and them.

checksum_sha256 is the difference between "this is the build I tested" and "this is whatever is at that URL today". extract: false leaves the download as it is, which is what a bare server.jar wants.

A zip of your own server, sent straight to storage — the bytes do not pass through Plany's API, so a large upload is as fast as your connection. One archive may be up to 5 GiB.

The CLI and Terraform do all of this for you; through the API it is four steps:

CreateBuild with an upload source
The build waits in STATE_PENDING_UPLOAD.
GetBuildUploadUrl
Hash your archive first and pass checksum_sha256: storage then refuses an archive that does not match, so a corrupted or truncated upload is rejected outright rather than found at first boot. The URL is short-lived; if one expires, ask for a fresh one.
PUT the archive
Straight to the returned URL.
FinalizeBuild
Checks what arrived and moves the build to STATE_READY.

If an upload from the CLI fails partway, plany builds upload <build> <archive> tries again against the same build.

Builds → New build → Upload from this machine → choose the archive → Create build

In Terraform, changing the uploaded file plans a new build: a build's files never change under the servers already running from it. Point the game or group at the new build and they move over.

install_commands

Commands run in order after the files are in place, for every source. Forge ships an installer rather than a server: fetch the installer with an archive source, then run it here.

The shape of an uploaded archive

The root of the archive is the root of the game server

No wrapper directory. What the archive unpacks to is what the launch command runs in.

A plany-install.sh at that root is run once, after unpacking, inside the build directory. It can unpack, fetch and set up whatever it needs.

It cannot install system packages — everything outside your build's own directory is read-only. Bring what your server needs inside the archive, or fetch it into the build directory from the script.

States

State	Meaning
`PENDING_UPLOAD`	Created, waiting for its archive. Only upload builds wait here.
`PROCESSING`	Being fetched, unpacked or checked.
`READY`	Usable by a game.
`FAILED`	Something went wrong; `error` says what.
`DELETED`	Deleted, and kept so a server still referring to it can say what it ran.

Attaching a build to a game

A build alone runs nothing. It becomes runnable by being attached to a game, along with a launch command and ports — all at once, because a game with a build and no launch command cannot be run. See Making your own game.

Operating system

Game servers run on Linux. A server build is a Linux build, and a Windows-only dedicated server cannot be run.

Storage

Uploaded builds count against game.plany.cloud/build_storage_bytes — 20 GiB on Hobby and 500 GiB on Pro, across the whole account. Steam and archive builds store nothing with Plany and count against nothing. See Quotas.