Version Checker

A tiny Godot 4 plugin that checks the running project's version against a minimum version you host remotely as JSON. Useful for softly forcing players onto an up-to-date client (e.g. after a server-breaking update) without shipping a whole update framework.

When the checker node enters the tree it fetches a JSON document, reads its min_version field, and compares it to your project's application/config/version. The result is exposed through a signal and two global static flags, so any part of your game can react to an outdated client.

Requirements

• Godot 4.1+ (uses static var and class_name)

Installation

1. Copy the addons/VersionChecker/ folder into your project.
2. (Optional) Open Project → Project Settings → Plugins and enable Version Checker.

The result flags are static, so you read them globally through the class name (VersionChecker.version_valid) — no node reference needed.

Usage

The checker runs its check in _ready(), so it needs to be a node in the tree. Pick whichever setup fits your project.

Option A — node in a scene

Add the checker to a scene that loads early (e.g. your main scene):

1. Add a Node to the scene.
2. Attach res://addons/VersionChecker/version_checker.gd to it.

_ready() runs when that scene enters the tree, so the check starts as soon as the scene loads.

Option B — autoload (runs before everything else)

Register the script as an autoload so it enters the tree before your main scene and the check runs first thing at launch:

Project → Project Settings → Globals (Autoload), add res://addons/VersionChecker/version_checker.gd.

Because the script declares class_name VersionChecker, the autoload node name must be different (Godot forbids reusing the class name), e.g. VersionCheckerAutoload. The static flags are still read as VersionChecker.version_valid; the checked signal is reached via the autoload node (VersionCheckerAutoload.checked).

Option C — create and check manually

Skip _ready() entirely and drive it from code — useful for re-checking on demand (e.g. from a "Retry" button):

var vc := VersionChecker.new()
vc.version_url = "https://example.com/version.json"
add_child(vc)          # _ready() runs here and calls check()
vc.checked.connect(_on_checked)

Or trigger another check on an existing instance at any time with vc.check().

In every case the static flags VersionChecker.version_valid / VersionChecker.version_checked are readable from anywhere via the class_name.

Configuration

Open addons/VersionChecker/version_checker.gd and set the two fields at the top of the file:

var version_url: String = "https://example.com/version.json" # PUT YOUR VERSION URL HERE
var timeout: float = 5.0                                     # request timeout in seconds

Leave version_url empty to skip the check entirely.

Make sure your project version is set under Application → Config → Version (application/config/version), e.g. v1.2.0.

Expected server response

The URL must return a JSON object with a min_version field:

{
  "min_version": "v1.2.0"
}

Versions are expected to follow SemVer (MAJOR.MINOR.PATCH, e.g. 1.2.0). The leading v is optional on both the project version and min_version. They are compared numerically, component by component (1.2.0 > 1.1.9); missing components are treated as 0.

Note: comparison covers the numeric MAJOR.MINOR.PATCH core only — pre-release and build-metadata suffixes (e.g. -rc.1, +build.5) are not interpreted.

Reacting to the result

Read the static flags anywhere through the VersionChecker class name:

func _ready() -> void:
    if VersionChecker.version_checked and not VersionChecker.version_valid:
        $UpdateRequiredPopup.show()

To react the moment the check finishes, connect to the checked signal on the checker node itself (the signal is an instance member, not static):

@onready var _checker: VersionChecker = $VersionChecker

func _ready() -> void:
    _checker.checked.connect(_on_checked)

func _on_checked(valid: bool) -> void:
    if not valid:
        $UpdateRequiredPopup.show()

API

Member	Kind	Description
checked(valid: bool)	signal	Emitted once when the check finishes (success or failure).
version_valid	static bool	true when the current version >= the required minimum.
version_checked	static bool	true once a check has completed.
version_url	String	Override the URL from code before calling check().
timeout	float	Request timeout in seconds.
check()	method	Manually trigger another check.

Notes

• version_valid starts as true, so a network error or unreachable server never locks players out — an outdated client is only flagged on a successful check that reports a higher min_version.
• If version_url is empty the check is skipped and checked is emitted with the current (valid) state.

License

MIT © icecube092