Clavem

Check for updates and download builds from a Godot game

Send GET /v1/releases/:productId/latest with the license key in the X-License-Key header, compare with application/config/version, and download with HTTPRequest.download_file when the player clicks Update. Clavem does not sign files, so a downloaded .pck needs your own signature check.

What the check returns

With a valid license, the newest published release comes back with release notes and a signed download url per file, good for one hour. Without a valid key you get only version and published_at, enough to say an update exists. If nothing is published the answer is 404. Add platform to get that platform’s files plus any unlabeled ones.

OS.get_name().to_lower() returns windows, macos or linux, so name your platform labels that way when you upload and the game needs no mapping table.

Check, compare, download

class_name Updater
extends Node

signal download_progress(fraction: float)
signal download_finished(path: String)  # "" on failure

const BASE := "https://clavem.io"
const PRODUCT_ID := 75  # from your product page

var _check := HTTPRequest.new()
var _download := HTTPRequest.new()
var _downloading := false

func _ready() -> void:
	process_mode = Node.PROCESS_MODE_ALWAYS
	_check.timeout = 8.0
	_download.timeout = 0.0  # Godot's advice for large files: no timeout
	add_child(_check)
	add_child(_download)

## The release Dictionary when a newer build exists, otherwise {}.
func check_for_update(license_key: String) -> Dictionary:
	var url := "%s/v1/releases/%d/latest?platform=%s" % [BASE, PRODUCT_ID, OS.get_name().to_lower()]
	if _check.request(url, ["X-License-Key: " + license_key]) != OK:
		return {}
	var r: Array = await _check.request_completed  # [result, response_code, headers, body]
	if r[0] != HTTPRequest.RESULT_SUCCESS or r[1] != 200:
		return {}  # 404 nothing published, 429 Retry-After 60, or no answer: try next launch
	var release = JSON.parse_string((r[3] as PackedByteArray).get_string_from_utf8())
	var current := str(ProjectSettings.get_setting("application/config/version", ""))
	if release is Dictionary and is_newer(str(release.get("version", "")), current):
		return release
	return {}

static func is_newer(latest: String, current: String) -> bool:
	var a := _numbers(latest)
	var b := _numbers(current)
	if a.is_empty() or b.is_empty():
		return false
	if latest.contains("-") and not current.contains("-"):
		return false  # a beta never replaces a stable install
	for i in 3:
		if a[i] != b[i]:
			return a[i] > b[i]
	return current.contains("-") and not latest.contains("-")  # same numbers: the release beats its prerelease

static func _numbers(v: String) -> Array:
	var out := []
	for part in v.split("-")[0].split("+")[0].split("."):
		if not part.is_valid_int():
			return []
		out.append(part.to_int())
	while out.size() < 3:
		out.append(0)
	return out

## Call on click, with a file from a fresh check_for_update(): links last one hour.
func download(file: Dictionary) -> void:
	var target := "user://" + str(file.get("filename", "update.bin")).get_file()
	_download.download_file = target  # streamed to disk, never held in memory
	if _download.request(str(file.get("url", ""))) != OK:
		download_finished.emit("")
		return
	_downloading = true
	var r: Array = await _download.request_completed
	_downloading = false
	var ok: bool = r[0] == HTTPRequest.RESULT_SUCCESS and r[1] == 200
	download_finished.emit(ProjectSettings.globalize_path(target) if ok else "")

func _process(_delta: float) -> void:
	if _downloading and _download.get_body_size() > 0:  # -1 when the server sent no length
		download_progress.emit(float(_download.get_downloaded_bytes()) / _download.get_body_size())

Set application/config/version in Project Settings to the same string you publish. A version such as 2026.11 parses here as 2026.11.0, so Godot is more forgiving than strict semver. Keep release strings in major.minor.patch anyway.

Latest means last published

If you publish a 1.4.2 backport after 1.5.0, the endpoint returns 1.4.2. is_newer offers only builds newer than the one running, so a 1.5.0 player never sees a downgrade. Unpublish a bad build and the previous release becomes the latest again.

HTTPRequest.download_file always writes from the start. The endpoint supports byte ranges, but resuming needs HTTPClient and your own file handling. For a multi-gigabyte game, OS.shell_open(url) gives the player their browser’s resume instead.

Applying the update

There is no updater and no delta patching in Clavem, and the release response has no checksum field. After the download:

  • Installer. OS.shell_open(path) opens it with the system’s default program, then get_tree().quit(). A running Windows executable cannot be overwritten, so an installer or a launcher has to do the replacing.
  • A patch .pck. ProjectSettings.load_resource_pack(path) loads it. Godot’s docs warn that this is a security hole when the pack can be swapped for a malicious one, and recommend signing patches with a private key and keeping the public key in the main pack. Clavem serves your file as you uploaded it, so the signature is yours to add. Upload patch.pck and patch.pck.sig as two files of the release.
const UPDATE_PUBLIC_KEY := "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n"

func pck_is_signed(pck_path: String, sig_path: String) -> bool:
	var key := CryptoKey.new()
	if key.load_from_string(UPDATE_PUBLIC_KEY, true) != OK:  # a string, so no export filter for .pem files
		return false
	var f := FileAccess.open(pck_path, FileAccess.READ)
	if f == null:
		return false
	var ctx := HashingContext.new()
	ctx.start(HashingContext.HASH_SHA256)
	while f.get_position() < f.get_length():
		ctx.update(f.get_buffer(mini(1 << 20, f.get_length() - f.get_position())))
	return Crypto.new().verify(HashingContext.HASH_SHA256, ctx.finish(), FileAccess.get_file_as_bytes(sig_path), key)

This uses an RSA key pair that you make for your updates, unrelated to the Ed25519 license keys.

Platforms where this does not apply

  • Web. You deploy the new export to your server. There is nothing to fetch.
  • Android and iOS. The stores deliver updates.
  • The editor. OS.get_name() returns the host OS there, so guard the check with OS.has_feature("editor") if you do not want development runs to ask.

Rate limits

The releases endpoint allows 120 requests a minute per IP address, counted apart from validation. A 429 carries Retry-After: 60. Check once per launch and skip silently on failure. A player who pressed Update gets “try again in a minute”.

Doing this with Clavem

Upload each build on the product page with a platform label and publish. The same files appear on the buyer’s order page. The endpoint, its limits and imported-license behavior are in Releases and downloads. The key check that gates download links is in validation for Godot.

Questions

Should the check and the download share one HTTPRequest node?

No. A node handles one request at a time and returns ERR_BUSY otherwise. Use one node for the version check and another for the download, which also lets you set timeout to 0 on the download only.

Can I load a downloaded .pck straight away?

Only after you verify it. Godot's own docs call patch packs a security risk and suggest signing them with a private key and checking the signature against a public key stored in the main pack.

Sources

  1. Godot docs, exporting packs, patches and mods, security concerns (checked November 2026)
  2. Godot docs, HTTPRequest class: download_file, timeout, get_body_size (checked November 2026)
  3. Godot docs, OS.get_name() return values (checked November 2026)
  4. Godot docs, CryptoKey.load_from_string (checked November 2026)