Content and patching¶
Patching is how your team changes a live game without shipping a new build: a balance tweak, a seasonal banner, a new set of textures. This page explains what can be changed that way and what can't, the words the admin website uses (namespace, version, pack, release, channel), and exactly what the game does when it updates.
The one rule to remember¶
Content can be patched. Code can't.
Otomo can deliver data: numbers, text, colours, on/off switches, and Godot resources such as textures, sounds and scenes. It can't deliver new C# code. A change to how something behaves still needs a new build of the game.
Why? When you build a Godot C# game, all your C# scripts are compiled into one program file that ships with the game. Godot can load extra resources while the game runs, but it can't swap that program file for a new one. So:
| Change | Patchable? |
|---|---|
| The fireball does 20 damage instead of 15 | Yes: a number in a settings document |
| A "Double XP" banner this weekend | Yes: text and a switch in a settings document |
| A new texture for the winter event | Yes: a texture in a content pack |
| The fireball now bounces off walls | No: new behaviour, which is C# code |
| A new enemy type with its own AI | No: new code |
A good habit follows from this: put tunable numbers in settings documents from the start, instead of hard-coding them. Then designers can balance the live game themselves.
The building blocks¶
The admin website organises content with five ideas. It's worth reading this section slowly, because every guide uses these words.
Namespace: a named settings document¶
A namespace is one JSON settings document with a name, such as balance.player or
ui.motd (the message of the day). For example, balance.player might contain:
Names are lowercase words joined by dots: balance.player, events.winter. The dots are
only for tidiness; they don't nest one namespace inside another.
Each namespace has an audience, chosen when it's created and never changed:
- Client: sent to players' games. Use this for anything the game reads.
- Server: read only by otomo's own services and never sent to players. For example,
session.rulessets the maximum party size. Players can't read these, so they're the place for anything players shouldn't see.
A namespace can also have a schema: a description of what its JSON must look like
("max_hp must be a whole number between 1 and 1000"). The admin website uses it to show a
form and to catch mistakes. A new namespace starts with an empty schema that accepts any
JSON.
Version: a frozen snapshot of a namespace¶
While you edit a namespace, your changes are a draft. Nobody sees a draft except the team. When the document is right, you create a version: a numbered, frozen copy (v1, v2, v3…) that can never change again. Freezing matters because a release (below) must always mean exactly the same content, even months later.
Pack: a bundle of Godot resources¶
A pack is a Godot .pck file: a bundle of resources such as textures, sounds, scenes
and text files, with their res:// paths inside. You make one with Godot (see
Publish your first content update) and upload it to the admin
website. Pack names are lowercase letters, digits and underscores, such as winter_event.
A pack can add files, not replace them
Otomo mounts packs so that they can't overwrite files that shipped with the game.
If your build contains res://ui/banner.png, a pack containing the same path is
ignored for that file. Put patchable content at paths the build doesn't have, for
example res://patch/winter/banner.png, and have your code look there first.
Release: what players get¶
A release is the complete answer to "what content should players have right now?". It lists:
- one version of each client namespace you include;
- the packs to include;
- a minimum client version: the oldest game build allowed to use this content.
Every release gets a number, its release_id. Like versions, a release never changes once
published.
Channel: which audience gets a release¶
A channel is a named stream of releases. There are three:
| Channel | Who receives it |
|---|---|
dev |
Developers testing new content |
staging |
A final check before players |
live |
Every player |
Each channel has one head: the release it's currently serving. Publishing a release to
live makes it the head of live, and every player gets it the next time their game
checks.
Rolling back makes an older release the head again. That's how you undo a mistake:
nothing is deleted, the channel just points at the earlier release. Promoting copies the
head of the previous channel in line: dev to staging, or staging to live once it's
been checked.
What the game does when it patches¶
When your game calls StartAsync (see the SDK reference), the SDK
runs these steps before anything else. The state names in capitals are what the SDK
reports as it goes:
-
CHECKING. It asks Patch for the head of its channel's manifest: a small JSON list of every file in the current release, each with its size and SHA-256 fingerprint. A fingerprint is a 64-character code computed from a file's exact bytes; change one byte and the fingerprint changes completely.
The SDK remembers a tag for the last manifest it got (the
ETag). If nothing has changed, Patch answers304 Not Modifiedwith no body, and the check costs almost nothing. -
Version check. If the game build is older than the release's minimum client version, the SDK stops with
ClientTooOld. Your game should tell the player to update. -
DOWNLOADING. For every file it doesn't already have, it downloads the file. If a download is interrupted, the next attempt continues where it stopped instead of starting over.
-
VERIFYING. It computes each downloaded file's fingerprint and compares it with the manifest. A file that doesn't match (damaged on the way, or tampered with) is thrown away and fetched again.
-
MOUNTING. It loads the settings documents into RemoteConfig (below), and adds each pack to Godot's resource system so
res://paths inside it work, just like files from the build. -
READY. It saves the manifest as the "last good" release, and deletes old files the release no longer lists.
When the server can't be reached¶
If Patch doesn't answer (no internet, or the server is down), the SDK uses the last good
release saved on the player's computer and reports OfflineReady. The game still starts,
with the content it had last time. On the very first run with no internet, there's nothing
saved, so the game runs with no settings documents and no packs, and your code's
fallback values (see below) are used.
When changes reach players¶
The game checks for updates when it starts. A player who's already playing gets the new release the next time they launch the game.
Reading settings in your game¶
After patching, every client namespace in the release is available through
Otomo.Instance.RemoteConfig. You ask for a value by namespace and key, and always give a
fallback, the value to use if the document or key is missing:
var config = Otomo.Instance.RemoteConfig;
// "balance.player" is the namespace; "max_hp" is the key inside it.
// 100 is used if the key is missing (for example, offline on first run).
int maxHp = config.GetInt("balance.player", "max_hp", 100);
// Dots in the key reach into nested objects: spells → fireball → damage.
float damage = config.GetFloat("balance.player", "spells.fireball.damage", 15f);
bool showBanner = config.GetBool("ui.motd", "show", false);
string text = config.GetString("ui.motd", "text", "");
The fallback also protects you from typos in the admin website: if a designer writes
"max_hp": "lots" (text instead of a number), GetInt returns the fallback instead of
crashing the game.
Next¶
Continue with Parties and matches, or, if you want to try patching right away, go to Publish your first content update.