Godot 4.7: install, versions and renderers

One line from a Godot 3 tutorial, export var speed = 200, stops a Godot 4.7.2 script before it runs, and the volumetric fog of a Forward+ game is simply missing from its web build, which Godot draws with another renderer. Many first-day problems with Godot come from the download, the version or the renderer, not from the game.

Here you install Godot 4.7.2, the release every example in this track ran on, and confirm it from a terminal. Then you read what Godot’s version numbers and support table promise, choose a renderer for the devices your game targets, and learn to spot Godot 3 code by the errors Godot 4 prints for it.

Godot is one program, and its MIT licence asks for one thing

Godot is a game engine and its editor in one program. The same download opens the Project Manager, edits your scenes and scripts, runs your game and, with the export templates (a separate download of 1.28 GB), exports it for every platform Godot supports. Games are made of scenes, which are trees of nodes, and scripted in GDScript, the language this track teaches; a separate build of Godot adds C#. Started with the --headless option, the program runs with no window at all. That is headless modeheadless mode: Running Godot with no window and no sound output, started with the --headless option. Servers, build machines and scripts started from a terminal run Godot this way., and every program on this page ran that way on Godot 4.7.2, so you can read exactly what it printed.

Godot is released under the MIT licenceMIT licence: A short permissive licence: anyone may use, change, share and sell the software, as long as its copyright notice and licence text are included in copies. Godot is released under it.. Its documentation sums it up as no strings attached and no royalties: your game is yours, under any licence you choose, including a commercial one. The engine can tell you itself what it asks in return. This script reads the licence text and the list of credited components from the running engine:

extends SceneTree

# What the engine itself says about its licence and the code it includes.
func _initialize() -> void:
	var text := Engine.get_license_text()
	print("Godot's licence: %d lines of text" % text.split("\n").size())
	for paragraph in text.split("\n\n"):
		if paragraph.begins_with("The above copyright notice"):
			print("Its one condition: ", paragraph.replace("\n", " "))
	var parts := Engine.get_copyright_info()
	print("Components credited: %d, the first is %s" % [parts.size(), parts[0].name])
	print("Licences among them: %d" % Engine.get_license_info().size())
	quit()

from session import files, run

files("licence_report.gd")
run("""
godot --headless --no-header --script licence_report.gd
""")

$ godot --headless --no-header --script licence_report.gd
Godot's licence: 21 lines of text
Its one condition: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
Components credited: 102, the first is Godot Engine
Licences among them: 19

That one condition is the whole obligation: Godot’s copyright notice and licence text must travel with every copy of the engine, and your game contains one. The licence guide lists ways that count, and one is enough: a credits screen, a licences screen in the menus, a text file shipped beside a desktop build, or an output log players can read.

The 102 components are the engine itself plus the libraries it includes, such as Jolt Physics, FreeType and Mbed TLS, under 19 licences between them. The guide asks you to credit those too. Engine.get_copyright_info() and Engine.get_license_info() give a licences screen the exact list from the running engine, so the screen stays right after every upgrade.

Install the standard build, then let the terminal confirm it

Every desktop system has two builds of Godot 4.7.2. The standard build runs GDScript, and this track uses it. The .NET build adds C# and needs Microsoft’s .NET SDK beside it. Neither has an installer: the download page says to extract the zip and run what is inside. Copies from Steam, itch.io and the Epic Games Store are standard builds too, without C#.

The macOS build is universal: one app for Apple Silicon and Intel Macs. The command-line tutorial also names package managers that put godot on your PATH for you: brew install godot on macOS, and on Windows scoop install godot after scoop bucket add extras. Step through the whole route, from choosing a build to the line that confirms it:

The terminal step is worth doing even when the editor already opens, because it tells you exactly which build you have. This script asks the engine the same question in more detail:

extends SceneTree

# Which Godot runs this script. Run it with: godot --headless --script version_report.gd
func _initialize() -> void:
	var info := Engine.get_version_info()
	print("Version: ", info.string)
	print("Major %d, minor %d, patch %d" % [info.major, info.minor, info.patch])
	print("Status: %s, build: %s, commit: %s" % [info.status, info.build, info.hash.left(9)])
	print("As one number: 0x%06x" % info.hex)
	print("Debug build: ", OS.is_debug_build())
	print("At least 4.7.2: ", info.hex >= 0x040702)
	print("As text, \"4.10.0\" < \"4.7.2\": ", "4.10.0" < "4.7.2")
	quit()

from session import files, run

files("version_report.gd")
run("""
godot --version
godot --headless --no-header --script version_report.gd
""")

$ godot --version
4.7.2.stable.official.ed1daf0bf
$ godot --headless --no-header --script version_report.gd
Version: 4.7.2-stable (official)
Major 4, minor 7, patch 2
Status: stable, build: official, commit: ed1daf0bf
As one number: 0x040702
Debug build: true
At least 4.7.2: true
As text, "4.10.0" < "4.7.2": true

4.7.2.stable.official.ed1daf0bf has four parts: the version, the status (stable, where a preview would say beta or rc1), the build name (official, a binary the Godot team built) and the first nine characters of the commit, the same nine the 4.7.2 release notes give. Engine.get_version_info() returns the same parts in a dictionary, and its hex entry packs major, minor and patch into one byte each: 4.7.2 is 0x040702. The editor binary also reports itself as a debug build; an exported game running on a release template reports false there.

The version number says what an upgrade will change

Godot numbers its releases major.minor.patch and, as its release policy puts it, loosely follows semantic versioning. Each number changes for a different reason, and that reason tells you how carefully to upgrade:

Support follows the same numbers. Several minor series are supported at once, but within a series only its latest patch releasepatch release: A release that changes only the third number of a version, such as 4.7.1 to 4.7.2. It brings bug and security fixes that stay compatible, and only the latest patch of a series is supported.: on a problem with 4.7.1, the policy’s answer is to upgrade to 4.7.2 and test again. Walk through the Godot 4 releases that this track’s lessons depend on; each tag is the support that series has while 4.7 is the newest:

Read the tags from the newest release back. 4.7 and 4.6 get every bug and security fix; 4.5 gets security and platform fixes only; 4.4 and older get nothing. A game that will be worked on for months belongs on 4.7, and a game still on 4.5 should plan its move.

The upgrade itself is a routine. Commit your project first; the 4.7.2 release notes give that advice for every upgrade. Open the project in the new version and run it. A project that moves from 4.5 or older to a newer series has one extra step: Project > Tools > Upgrade Project Files re-saves all its scenes in one go, so the unique node ids of 4.6 come in a single commit, not scattered through later ones. From 4.7 the Project Manager also marks projects that the editor can only open after an upgrade, with an icon next to their version.

Three renderers trade drawing features for the devices they reach

Godot 4 draws every frame with one of three renderersrenderer: The part of Godot that draws each frame. Godot 4 has three, Forward+, Mobile and Compatibility, and a project chooses one in the rendering/renderer/rendering_method setting., chosen when you create a project and changeable later from the renderer name in the editor’s upper-right corner:

• Forward+ has the most features, among them SDFGI, VoxelGI and volumetric fog, and is the default on desktop.
• Mobile has fewer features, renders simple scenes faster, and is the default on phones and tablets.
• Compatibility has the fewest features, runs on the widest range of hardware, and draws every web build.

Forward+ and Mobile draw through Vulkan, Direct3D 12 or Metal, so they need a recent GPU. Compatibility uses OpenGL, which the download pages put at OpenGL 3.3 or OpenGL ES 3.0 hardware, and in a browser WebGL 2.0: Godot 4 can target the web only that way. The choice is stored in project.godot, and it is not one value but three. Here are three projects that differ only in the lines the Project Manager writes for each choice, asked what they use where:

extends SceneTree

# The renderer a project asks for on each kind of device.
func _initialize() -> void:
	var setting := "rendering/renderer/rendering_method"
	print("  desktop: ", ProjectSettings.get_setting(setting))
	print("  phones and tablets: ", ProjectSettings.get_setting(setting + ".mobile"))
	print("  web: ", ProjectSettings.get_setting(setting + ".web"))
	quit()

from session import files, run

# Three projects that differ only in the renderer the Project Manager wrote into project.godot.
files("forward_plus", "mobile", "compatibility")
files("renderer_report.gd=forward_plus/renderer_report.gd", "renderer_report.gd=mobile/renderer_report.gd")
files("renderer_report.gd=compatibility/renderer_report.gd")
run("""
grep rendering_method compatibility/project.godot
cd forward_plus && godot --headless --no-header --script renderer_report.gd && cd ..
cd mobile && godot --headless --no-header --script renderer_report.gd && cd ..
cd compatibility && godot --headless --no-header --script renderer_report.gd && cd ..
""")

$ grep rendering_method compatibility/project.godot
renderer/rendering_method="gl_compatibility"
renderer/rendering_method.mobile="gl_compatibility"
$ cd forward_plus && godot --headless --no-header --script renderer_report.gd && cd ..
  desktop: forward_plus
  phones and tablets: mobile
  web: gl_compatibility
$ cd mobile && godot --headless --no-header --script renderer_report.gd && cd ..
  desktop: mobile
  phones and tablets: mobile
  web: gl_compatibility
$ cd compatibility && godot --headless --no-header --script renderer_report.gd && cd ..
  desktop: gl_compatibility
  phones and tablets: gl_compatibility
  web: gl_compatibility

The Forward+ project asks for Mobile on phones and for Compatibility on the web. rendering_method.mobile and rendering_method.web are feature-tagfeature tag: A name such as mobile, web, windows or debug that describes the platform and build a game runs on. A project setting written with a tag after a dot, such as rendering_method.mobile, applies only there. overrides with those defaults, and the engine applies the one for the device it starts on. That is why choosing Compatibility in the Project Manager writes the .mobile line as well: without it, phones would use Mobile. The web needs no line of its own, because its default is already gl_compatibility.

Three questions about your game decide most of the choice. Answer them in the table, and it rules out the renderers that cannot work, with the reason:

In short: Compatibility for anything that must look the same in a browser or run on older hardware, Forward+ for desktop 3D that needs its lighting, and Mobile for newer phones and tablets. For 2D, the renderers page calls Compatibility usually good enough. Switching later is possible, but moving to or from Compatibility means more scene and lighting fixes than moving between Forward+ and Mobile.

Godot 3 code fails on Godot 4, and the error names the fix

Godot 4 changed enough of GDScript and the node names that a script from a Godot 3 tutorial rarely parses. Tutorials do not always say which version they target, but the code does: export and onready written as plain words, yield, and node types such as KinematicBody2D or Spatial. Here is a small script as a Godot 3 tutorial writes it, and the same script for Godot 4:

extends SceneTree

# A script written for Godot 3: it does not parse in Godot 4.
export var speed = 200

func _initialize():
	print("Speed: ", speed)
	yield(create_timer(0.5), "timeout")
	print("Half a second later")
	quit()

extends SceneTree

# The same script for Godot 4: an annotation instead of the export keyword, await instead of yield.
@export var speed := 200

func _initialize() -> void:
	print("Speed: ", speed)
	await create_timer(0.5).timeout
	print("Half a second later")
	quit()

The session runs the old script, three more Godot 3 lines that tutorials still show, and finally the new script:

from session import files, run, write

files("old_tutorial.gd", "new_tutorial.gd")
# Three more lines that Godot 3 tutorials still show, each in a script of its own.
write("old_onready.gd", "extends Node\n\nonready var label = $Label\n")
write("old_yield.gd", 'extends Node\n\nfunc _ready():\n\tyield(get_tree().create_timer(1.0), "timeout")\n')
write("old_body.gd", "extends KinematicBody2D\n")
run("""
!godot --headless --no-header --script old_tutorial.gd
!godot --headless --no-header --check-only --script old_onready.gd
!godot --headless --no-header --check-only --script old_yield.gd
!godot --headless --no-header --check-only --script old_body.gd
godot --headless --no-header --script new_tutorial.gd
""")

$ godot --headless --no-header --script old_tutorial.gd
SCRIPT ERROR: Parse Error: The "export" keyword was removed in Godot 4. Use an export annotation ("@export", "@export_range", etc.) instead.
          at: GDScript::reload (res://old_tutorial.gd:4)
ERROR: Failed to load script "res://old_tutorial.gd" with error "Parse error".
   at: load (modules/gdscript/gdscript_resource_format.cpp:46)
$ godot --headless --no-header --check-only --script old_onready.gd
SCRIPT ERROR: Parse Error: The "onready" keyword was removed in Godot 4. Use the "@onready" annotation instead.
          at: GDScript::reload (res://old_onready.gd:3)
ERROR: Failed to load script "res://old_onready.gd" with error "Parse error".
   at: load (modules/gdscript/gdscript_resource_format.cpp:46)
$ godot --headless --no-header --check-only --script old_yield.gd
SCRIPT ERROR: Parse Error: "yield" was removed in Godot 4. Use "await" instead.
          at: GDScript::reload (res://old_yield.gd:4)
ERROR: Failed to load script "res://old_yield.gd" with error "Parse error".
   at: load (modules/gdscript/gdscript_resource_format.cpp:46)
$ godot --headless --no-header --check-only --script old_body.gd
SCRIPT ERROR: Parse Error: Could not find base class "KinematicBody2D".
          at: GDScript::reload (res://old_body.gd:1)
ERROR: Failed to load script "res://old_body.gd" with error "Parse error".
   at: load (modules/gdscript/gdscript_resource_format.cpp:46)
$ godot --headless --no-header --script new_tutorial.gd
Speed: 200
Half a second later

Godot 4.7.2 recognises the old keywords and names their replacements. Renamed nodes get only “Could not find base class”, so for those the upgrade guide’s table of renames is the place to look:

Practise: check your own installation

Do these four things on the computer you will make games on, in this order:

1. Download the standard build for your system from godotengine.org, extract it and start it once.
2. In a terminal, run the program with --version and compare the output with 4.7.2.stable.official.ed1daf0bf.
3. Save version_report.gd in an empty folder and run it with --headless --script version_report.gd. Add a line that prints OS.has_feature("web"), run it again and check that it prints false.
4. Save old_tutorial.gd, run it, and fix it line by line using the errors until it prints the same two lines as new_tutorial.gd.

Then check yourself on licences, installs, versions, renderers and Godot 3 code. The self-check below opens with the topic where your answers have been weakest, and after each answer it tells you why that choice is right or wrong:

Interview questions

Warm-up: what does Godot’s MIT licence require from a game you sell?

One thing: include Godot’s copyright notice and licence text in the game, where players can reach it. A credits screen, a licences screen in the menus, a file shipped beside a desktop build or a readable output log all count, and one is enough. There are no fees or royalties, and the game itself can use any licence, closed and commercial included. Godot also bundles libraries with licences of their own, 102 credited components under 19 licences in 4.7.2, and the documentation asks you to credit them too; Engine.get_license_text(), Engine.get_copyright_info() and Engine.get_license_info() return all of it from the running engine, so a licences screen built from them stays current after every upgrade.

Key takeaways

• Godot is one program, editor and engine together, under the MIT licence: no fees or royalties, and one condition, that every game includes Godot’s copyright and licence notice.
• The standard build of Godot 4.7.2 is a zip to extract and run on each system, and godot --version must print 4.7.2.stable.official.ed1daf0bf before you start, with versions compared as numbers, never as text.
• A patch release is a safe fix to take soon, a minor release is a small project on a branch and a major release is a port; while 4.7 is the newest series, 4.7 and 4.6 have full support, 4.5 partial support and 4.4 and older none.
• Forward+, Mobile and Compatibility trade features for reach: only Compatibility runs on older hardware and draws web builds, and one project setting holds a renderer for desktop, for phones and for the web.
• Godot 3 tutorials show export, onready, yield or old node names, and Godot 4 rejects them with errors that name most replacements while still ending with status 0.