Recipes

# Remote config for Godot

Change a Godot game's settings, events and kill switches after release, with HTTPRequest and a JSON file.

Tune drop rates, schedule an event or turn off a broken mode in a released game, without a patch. This recipe is a Godot 4 autoload that fetches a JSON file from hotcfg, keeps the last good copy in `user://`, and never holds up the game.

## The config

game-config.json

```
{
  "motd": "Double XP this weekend!",
  "double_xp": true,
  "modes": { "ranked": true },
  "spawn_rate": 1.0
}
```

A schema keeps a typo from reaching every player:

schema.json

```
{
  "type": "object",
  "required": ["double_xp", "modes", "spawn_rate"],
  "properties": {
    "motd": { "type": "string", "maxLength": 200 },
    "double_xp": { "type": "boolean" },
    "modes": { "type": "object", "additionalProperties": { "type": "boolean" } },
    "spawn_rate": { "type": "number", "minimum": 0.1, "maximum": 5 }
  }
}
```

terminal

```
hotcfg bins create game-config --public
hotcfg push game-config.json --bin game-config --env production
```

## The autoload

Save as `remote_config.gd` and add it under **Project → Project Settings → Globals → Autoload** as `RemoteConfig`.

remote_config.gd

```
extends Node

signal updated

const URL := "https://api.hotcfg.run/v1/acme/game-config"
const CACHE_PATH := "user://hotcfg.json"
const DEFAULTS := {"motd": "", "double_xp": false, "modes": {"ranked": true}, "spawn_rate": 1.0}

var config: Dictionary = DEFAULTS.duplicate(true)
var _etag := ""
var _http := HTTPRequest.new()


func _ready() -> void:
	_load_cache()
	_http.timeout = 2.0  # seconds; then the cached or default config stays
	add_child(_http)
	_http.request_completed.connect(_on_request_completed)
	refresh()


func refresh() -> void:
	var headers := PackedStringArray()
	if _etag != "":
		headers.append("If-None-Match: " + _etag)
	_http.request(URL, headers)


func get_value(key: String, fallback = null):
	return config.get(key, DEFAULTS.get(key, fallback))


func _on_request_completed(result: int, code: int, headers: PackedStringArray, body: PackedByteArray) -> void:
	if result != HTTPRequest.RESULT_SUCCESS or code != 200:
		return  # offline, timed out, 304 or an error: keep what we have
	var parsed = JSON.parse_string(body.get_string_from_utf8())
	if not parsed is Dictionary:
		return
	config = parsed
	_etag = _header(headers, "etag")
	var file := FileAccess.open(CACHE_PATH, FileAccess.WRITE)
	if file:
		file.store_string(JSON.stringify({"etag": _etag, "config": config}))
	updated.emit()


func _load_cache() -> void:
	if not FileAccess.file_exists(CACHE_PATH):
		return
	var saved = JSON.parse_string(FileAccess.get_file_as_string(CACHE_PATH))
	if saved is Dictionary and saved.get("config") is Dictionary:
		config = saved["config"]
		_etag = saved.get("etag", "")


func _header(headers: PackedStringArray, name: String) -> String:
	for h in headers:
		var i: int = h.find(":")
		if i > 0 and h.substr(0, i).strip_edges().to_lower() == name:
			return h.substr(i + 1).strip_edges()
	return ""
```

Read values anywhere, and react when new ones arrive:

main_menu.gd

```
func _ready() -> void:
	RemoteConfig.updated.connect(_apply)
	_apply()


func _apply() -> void:
	$Motd.text = RemoteConfig.get_value("motd", "")
	$RankedButton.disabled = not RemoteConfig.get_value("modes", {}).get("ranked", true)
```

Call `RemoteConfig.refresh()` again when the player returns to the menu to pick up changes during a long session.

## Notes

- **Numbers:** Godot parses every JSON number as a `float`. Cast with `int()` where you need an integer.
- **Web exports:** public bins send CORS headers, so `HTTPRequest` works from an HTML5 build too.
- **Per-version settings:** to change a value only for old builds of the game, see [version targeting](https://hotcfg.run/docs/recipes/version-targeting).
- **Events on a schedule:** hotcfg doesn't schedule publishes yet. Ship an `event_start` and `event_end` timestamp in the config and compare with `Time.get_unix_time_from_system()`.

Last updated 10 November 2026
