Updates and Versioning

Updating a game server is not the same as updating a game client. When you push a client update, each player downloads it on their own time. When you push a server update, thousands of active servers need to update, each with players connected, worlds loaded, and mods installed. A bad update strategy causes half your servers to go offline after a patch.

Semantic Versioning

Use semantic versioning (semver) for your server builds: MAJOR.MINOR.PATCH

MAJOR: Breaking changes. Save format changes, removed features, protocol incompatibilities.
MINOR: New features, added content. Backward-compatible with existing saves and mods.
PATCH: Bug fixes. No new features, no breaking changes.

This gives hosting platforms and server admins a clear signal about what an update contains and whether it’s safe to apply immediately.

Client/Server Version Compatibility

Your game client and server versions must agree on a network protocol. When they disagree, players either cannot connect or experience desyncs and crashes.

Strict version matching: Client and server must be the exact same version. Simple to implement, but forces every player to update before they can join any server.

Version range compatibility: Client version 1.2.x can connect to server version 1.2.x. Minor/patch differences are allowed. More flexible, but you need to maintain protocol backward compatibility within the range.

Version handshake: When a client connects, the server and client exchange version information. If incompatible, the server rejects the connection with a message explaining which version is required.

Implement the handshake regardless of your compatibility strategy. A clear “Your client version 1.3.0 is not compatible with server version 1.2.5. Please update your game.” is far better than a silent disconnect or mysterious crash.

Forced Updates

When a critical update ships (security fix, game-breaking bug), you need a way to force servers to update before accepting players.

Options:

Client-side gate: The game client refuses to connect to servers running an outdated version (uses the version handshake)
Master server gate: Your matchmaking or server list API marks outdated servers as incompatible
Server-side check: The server checks for updates at startup and refuses to launch if it’s out of date (requires an update API endpoint)

At minimum, implement the client-side gate. Players should never connect to a server that will give them a broken experience.

Rolling Updates

Not all servers update at the same time. When you push an update:

Some servers update immediately (auto-update enabled, no players online)
Some servers wait for a restart (players are online, admin wants to finish the current session)
Some servers don’t update at all (admin is away, hosting platform is offline)

Your game must tolerate a mixed-version ecosystem for hours or days after an update. The client version handshake handles this: players running the new client can only connect to servers running the new version.

Save File Migration

When an update changes the save format, servers must migrate their existing world data to the new format. This is covered in detail in Configuration, but the key points for versioning:

Include a version field in every save file
Your server auto-migrates old saves on first load after an update
Never silently discard data during migration
Test migration against real community saves, not just internal test data

Rollback Strategy

If an update introduces a critical bug, you need a way to roll back.

Server rollback: Hosting platforms revert to the previous server version. This only works if:

The previous version’s save format is still compatible (the new version didn’t migrate saves irreversibly)
The previous version’s binaries are still available for download

Save rollback: Admins restore a backup from before the update. This requires your server to cooperate with backup workflows (see Configuration).

Plan for this before you need it:

Keep previous server versions available for download (don’t delete old builds)
Make save format migrations reversible when possible
Test “downgrade then upgrade” scenarios in your QA process

Communicating Updates

Hosting Providers need to know about your updates to manage their fleet:

Before the update:

Is this a breaking change? (major version bump)
Does it require a config migration?
Does it change the save format?
Are there new or changed startup arguments?
Are there new port requirements?

With the update:

Changelog with hosting-relevant details (not just player-facing patch notes)
Minimum required client version
Whether a server restart is required or if hot-reload is supported

How to communicate:

A dedicated changelog or mailing list for Hosting Providers
An API endpoint that returns the latest version and changelog
Direct communication with your hosting partner (for managed providers like Nodecraft)

Do not assume Hosting Providers read your Steam announcements or Discord posts. They need structured, technical information about what changed.