C++.CodeCompared.To/GDScript

GDScript has no main because the engine owns the entry point: a script attaches to a node and the engine calls into it. print writes to the output panel and the console, appending a newline and converting any value. The point of the language is that this file can be edited while the game is running and reloaded without a rebuild — which for a codebase whose C++ side takes minutes to compile is the whole argument.

GDExtension is why this page is worth a C++ programmer's time at all. Before Godot 4 the only way to add C++ was a module compiled into the engine, which meant maintaining an engine build; now a .gdextension file plus a shared library built against godot-cpp registers new node types the editor treats as native. So the practical arrangement mirrors the Lua one: C++ owns the things that must be fast or must touch the platform, GDScript owns the behavior that changes daily — and unlike Lua, both halves see the same object model, which is the subject of the next section.

Choosing a base class chooses a memory strategy. RefCounted is shared_ptr — the common case, and what Resource derives from. Object is a raw new with a matching free() you must call, and forgetting it leaks. Node is an Object that additionally belongs to a tree, so its parent frees it — which is why you almost never free a node yourself. There is no stack allocation and no value semantics for engine objects: every variable holding one is a reference, exactly as in the Kotlin page.

is_instance_valid() asks whether an object reference still points at a live object, which is weak_ptr::expired() without needing to have set up a weak_ptr in advance. It is the standard defense when holding a reference to a node that might have been freed — a target that died, a UI element that closed. queue_free() is the other half: it defers destruction to the end of the frame so nothing currently executing loses its object mid-call. The rule is queue_free() for anything in the tree, free() only for a bare Object you created and own.

The count lives inside the object rather than in a separate control block, which is the one structural difference from shared_ptr: there is no make_shared versus shared_ptr(new T) distinction to worry about, and a raw pointer to a RefCounted can always be turned back into a counted handle. In C++ the type is Ref<T> and it does exactly what you expect on copy, assignment and destruction. weakref() is weak_ptr: it observes without owning, and get_ref() answers null once the last real handle is gone. The trap is the same trap: two objects holding counted handles to each other never reach zero, and Godot has no cycle collector.

GDScript has no destructor you can rely on for cleanup ordering. A RefCounted is collected when the last handle drops, but you cannot say when and you get no callback to hang work off; _notification(NOTIFICATION_PREDELETE) exists and runs, but it runs during teardown and is not the place for anything elaborate. So cleanup is explicit: disconnect what you connected, and free what you allocated with Object.new(). free() deletes immediately and invalidates every other handle to that object, which is why queue_free() is the default for nodes — it waits until the end of the frame, by which time nothing is mid-way through using it. Signals are the exception worth knowing: a connection is dropped automatically when either end is freed.

A node is owned by its parent, a resource by its reference count, and a bare Object by you. Those three sentences cover almost every lifetime question on this engine. add_child() is a unique_ptr move in everything but spelling: after it, the child is the parent's business, and remove_child() hands ownership back — a node removed and not re-parented is a leak until someone frees it. The owner property is a separate idea and a common confusion: it marks which nodes get written out when a scene is saved, and has nothing to do with memory.

A bare var holds a Variant and can be reassigned to anything. := infers the type and fixes it, and : Type states it — both give compile-time checking, editor autocomplete, and a real speed improvement, because the compiler can skip the Variant dispatch. The style advice in every Godot codebase of any size is to annotate everything, and the project setting untyped_declaration can be promoted to a warning or an error to enforce it. For a C++ programmer the useful framing is that := is auto and a bare var is std::any.

Every untyped GDScript value, every signal argument, every exported property and every engine API that crosses the script boundary is a Variant — a tagged union of about forty types, roughly 24 bytes, dispatched at runtime. It is what makes the dynamic half of the engine possible and it is where the performance goes: an untyped a + b must check both tags and pick an implementation, where a typed int + int compiles to an integer add. In C++ you meet it as the godot::Variant class, and the same rule applies — convert at the boundary, then work in real types.

String is a single type for all text and it counts characters, so "café".length() is 4 where std::string would say 5 bytes. There is no std::wstring / u16string / u32string decision to make and no encoding conversion at the boundary; when you genuinely need bytes, to_utf8_buffer() gives you a PackedByteArray and says so in its name. Strings are also immutable-by-value with copy-on-write underneath, so passing one around costs a pointer copy and mutating a shared one silently makes the copy for you.

A StringName is an interned string — created once, stored once, and compared by pointer rather than by character. That is why the engine's own signatures use it everywhere a short fixed name is passed repeatedly: node names, signal names, input actions, animation names, method names in call(). The &"..." prefix builds one at parse time so the interning cost is paid before the game runs; writing a plain "ui_accept" where a StringName is expected works, but converts on every call. The trade is the one you would expect from a hand-rolled intern table: creation is more expensive, and the entry lives until the program ends.

A NodePath is split into its segments when it is constructed, so get_node(^"Player/Sprite2D") walks a pre-parsed list instead of scanning text. The ^"..." literal builds it at parse time, so a path written in a script costs nothing at run time — passing a plain string builds one on every call. The :property subpath form is the part with no obvious analogue in C++: one value can address a node, a property on it, and even a component of that property, which is what lets an animation track or a Tween take a single argument saying what to animate. $Player/Sprite2D is shorthand for get_node(^"Player/Sprite2D").

The % operator is printf's format vocabulary with an array on the right — %s, %d, %.1f, %04d all mean what you expect, and %% is a literal percent. String.format() is the named-placeholder alternative when the argument order would be hard to follow. What is genuinely different is the surface area: split, join, strip_edges, pad_zeros, similarity, is_valid_int, humanize_size and about a hundred more are methods on the type, so the small text utilities that accumulate in every C++ codebase are already written. C++23's std::format closed the formatting half of this gap; the utility half is still yours.

A GDScript Array is a vector of Variants, so a million integers costs roughly 24 bytes each with a tag check on every access — perhaps six times the memory of a std::vector<int> and none of the cache behavior. Array[int] adds insert-time checking and better codegen but does not change the storage. Dictionary is hashed and, like Python's dict, preserves insertion order. When the cost matters the answer is the next row, which is Godot's equivalent of reaching for a real typed buffer.

The Packed*Array family stores real machine types contiguously with no Variant boxing, which is why every bulk engine API takes one — mesh vertices, image data, index buffers, network packets. They are also copy-on-write, so passing one is cheap and mutating a shared one duplicates it, exactly like the Swift page's arrays. Reaching for a packed array is often the difference between "this needs a C++ node" and "this is fine in GDScript", and it is a much cheaper move than adding a build step.

An Array[int] is one Array type carrying its element type as data, not a distinct type per element as std::vector<int> is — so there is no monomorphization, no code generated per instantiation, and the check happens when a value goes in rather than when the code is compiled. That still catches the bug near where it was written, which is most of the value. The storage is unchanged: every element is a Variant, so a typed array of a million integers costs the same memory as an untyped one. When that matters, the answer is PackedInt32Array, and the row two down explains why.

Three things a C++ programmer should notice. Dictionary keeps insertion order, so iterating one is reproducible in a way std::unordered_map explicitly is not — worth having when a save file or a network packet is built by walking it. get(key, default) replaces the find-compare-to-end dance, and there is no iterator to invalidate. And any Variant can be a key, including a Vector2 or a whole array, with no std::hash specialization to write — the cost being that hashing goes through Variant rather than through a type you chose. Typing it as Dictionary[String, int] checks keys and values on insertion, the same bargain the typed array makes.

The C++ pipeline is lazy: views::filter and views::transform compose into one type and nothing is computed until the loop pulls, so no intermediate vector is ever built. GDScript's filter and map are eager — each returns a new array, so a three-stage pipeline over ten thousand elements allocates twice on the way through, and each element crosses the interpreter boundary through a Callable. For a list of items in a menu that is irrelevant and the readability is worth having; inside _process over a large array, a plain for loop is measurably faster and is what the engine's own GDScript is written with.

Every .gd file is a class, implicitly extending RefCounted unless it says otherwise, and its resource path is its identity. class_name additionally registers a global name so the editor autocompletes it and it appears in the "create node" dialog. Nested classes exist (class Inner: inside a file) but are uncommon. There is no header, no forward declaration and no separate compilation — but there is a cyclic-dependency problem, since two files that class_name each other can fail to load, which is the Godot equivalent of an include cycle.

A script extends an engine class and thereby becomes that class with extra behavior — so your enemy.gd is a CharacterBody2D, with its physics, collision and transform already present. That is very different from a C++ hierarchy you design, and it means the interesting question is which engine class to start from rather than how to structure your own tree. With no interfaces, shared behavior is composition: a node whose only job is a health bar, added as a child. Duck typing fills the rest — has_method("take_damage") is the idiomatic check.

The normal spelling is signal damaged(amount: int) at file scope, then emitter.damaged.connect(handler) and damaged.emit(30) — the example above builds one at runtime only so it can execute inside the runner. What makes signals more than a hand-rolled observer is the integration: connections are visible and editable in the editor, they are saved with the scene, and they are severed automatically when either object is freed, so the dangling-callback bug that plagues C++ observer implementations does not arise. The design rule Godot teaches is "call down, signal up" — a parent calls its children's methods, a child signals its parent.

A Callable holds an object and a method name, or a lambda, and can be passed, stored and compared. .bind() pre-binds trailing arguments, which is how pressed.connect(on_pressed.bind(button_index)) passes context a signal does not carry — the pattern you will use constantly in UI code. Note it also knows whether its object is still alive: calling a Callable whose object was freed produces an error rather than undefined behavior, which is the same safety story as is_instance_valid.

The callbacks to know: _ready once when the node and its children are in the tree, _process every rendered frame with a variable delta, _physics_process on a fixed timestep where anything physics- or determinism-sensitive belongs, and _input/_unhandled_input for events. The trap for a C++ programmer is _init versus _ready: _init runs at construction when the node has no parent, no children resolved and no tree, so anything touching get_node() or a sibling belongs in _ready. A GDExtension class overrides exactly the same virtuals from C++.

The tree is the object graph, the scene file format, the editor hierarchy and the lookup namespace all at once — $Player/Sprite2D is sugar for get_node("Player/Sprite2D"). Freeing a node frees its whole subtree, which is why node ownership is rarely something you think about. The cost is that lookup is by path and therefore runtime-checked: renaming a node in the editor silently breaks every $Path that referenced it, with no compile error. The mitigations are unique names (%Name), @exported NodePaths set in the inspector, and signals instead of reaching across the tree.

@export makes a script variable editable in the Godot editor's Inspector — the panel a designer sees when they select the node, not anything that appears in the shipped game. The property is typed, and the annotation constrains what can be entered — @export_range bounds it to a numeric range, @export_enum to a fixed set of names, NodePath to a node in the scene, PackedScene to a scene file. The value is saved per instance in the scene file, so ten enemies can each have different speeds without ten scripts. For a C++ programmer the significance is organizational rather than technical: it moves tuning out of the code and out of the programmer's queue. A GDExtension class gets the same thing by calling ClassDB::bind_method and ADD_PROPERTY.

A GDScript lambda copies the values it references at the moment it is created, so it is a snapshot rather than a live view — threshold = 100 after the fact changes nothing. That makes it safe (nothing dangles, nothing surprises you later) and means it cannot be used as an accumulator the way a C++ [&] lambda can; mutate an object's property instead. Note also that a lambda is invoked with .call() rather than (), because it is a Callable value rather than a function name.

has_method() is the idiom, and it is structural typing evaluated at the moment of the call: anything with a take_damage can be hit, regardless of its class. That is flexible in exactly the way a template is, and it fails in exactly the way a template does not — a renamed method is a silent no-op rather than a compile error. Static typing helps where it can (var target: Enemy gives real checking), and the practical compromise most projects reach is typed variables for things you own and has_method at the boundaries where you do not.

await suspends the function until the given signal emits, then resumes it exactly where it stopped with its local state preserved — the same mechanism as Lua's coroutines and Python's await, and the reason cutscenes, dialogue and multi-step abilities are written as ordinary code in Godot rather than as state machines. The trap is that a function containing await becomes a coroutine, so its caller gets a signal-like object rather than the return value unless the caller also awaits. And an awaiting function whose node is freed mid-wait simply never resumes, which is a leak of intent if not of memory.

GDScript has no exceptions at all — no throw, no try, no unwinding, and therefore nothing to make exception-safe. A function that can fail returns a value saying so, which is why so much of the engine's API returns an Error code or a nullable object. push_error() writes to the error stream and shows in the debugger without stopping anything, so it reports rather than aborts. The practical consequence for someone arriving from C++: there is no RAII to protect and no noexcept to reason about, but there is also no compiler telling you that a failure was ignored, so the discipline of checking the returned value has to come from you.

The Error enum is Godot's errno: about fifty named values, OK is zero, and error_string() turns one into something readable. The convention is consistent enough to rely on — if a method can fail and has nothing else to return, it returns Error — which makes if resource.save(path) != OK: the shape most engine-facing code takes. Where a method must return a value and can fail, it returns null or an empty result instead, and that is the case worth being careful about: nothing warns you when a returned null is used as if it were an object. user:// is the writable per-project directory, resolved by the engine rather than by a path you assemble.

The macro family is the engine's answer to having neither exceptions nor a way to abort cleanly: ERR_FAIL_COND_V(condition, value) returns value and logs file, line and function; ERR_FAIL_INDEX and ERR_FAIL_NULL are the common specializations; _MSG variants add a sentence; CRASH_COND is for the genuinely impossible and stays in release builds; and WARN_PRINT_ONCE reports without returning. Writing GDExtension code means adopting it, because the engine calls into your code from places that cannot handle a longjmp or a thrown object. On the script side, assert() is the closest thing — and its one crucial property is that a release export strips it entirely, so anything the shipped game must still check has to be an ordinary if.

Thread is a real operating-system thread and wait_to_finish() is join(), with one improvement: it returns the callable's return value, so the result does not have to be smuggled out through a captured variable. bind() is partial application — it produces a Callable with the arguments already attached, which is what Thread.start() takes. The hard limit is what a background thread may touch: the scene tree is not thread-safe, so a worker computes and hands its answer back, and anything that changes a node goes through call_deferred() to run on the main thread. Loading and parsing, pathfinding, procedural generation and save-file writing are what threads are actually used for here.

This is where the absence of RAII actually costs something. There is no lock_guard, no scoped_lock and no way to write one, because nothing runs when a variable goes out of scope — so the unlock() is an ordinary statement that an early return will happily skip. The practical discipline is to keep the locked region to a few lines with no branches in it. Semaphore is there for signalling between threads, and the deadlock rules are the ones you already know. Worth saying plainly: reaching for a mutex in GDScript usually means the design has drifted — the normal shape is a worker that computes a result and hands it back, sharing nothing.

WorkerThreadPool is the engine's own pool, sized from the processor count and shared with the engine's internals, so work handed to it competes with resource loading rather than adding threads on top of it. add_task() queues one callable and hands back an id; add_group_task() runs one callable a fixed number of times with the index as its argument, which is the parallel for loop; both are collected with a matching wait_for_*_completion. The rule from the previous row still applies — the callables must not touch the scene tree — and the elements each one writes must not overlap, which is why indexing into a pre-sized array is the shape to copy.

The GDCLASS macro plus _bind_methods registers the type with ClassDB — the same registry every built-in node uses — so the editor, the inspector, the scene serializer and GDScript all treat it as native. Overriding _process, _ready and the rest works because they are the same virtuals GDScript overrides. What you get over a module is that the engine is stock: no fork, no engine rebuild, and the extension is a shared library you ship alongside the game. What you give up is hot reload (improving, still fiddly) and crash isolation — a segfault in your extension takes the editor with it.

Every argument and return value crossing the script boundary is converted to and from a Variant, so the cost of a call is dominated by marshalling rather than by your code. That makes the shape of the interface the thing to design: one call that processes a PackedVector2Array of a thousand points is fast, a thousand calls each processing one point is not. Godot's own APIs are shaped this way for exactly this reason, which is why Packed*Array exists at all — and it is worth trying the packed-array version in pure GDScript before concluding you need C++.

Taking const Ref<T>& avoids an atomic increment and decrement on every call, which matters because these signatures are crossed thousands of times a frame; the const then says the callee will not reseat the caller's handle. The same reasoning applies to const String& and const Variant&, both copy-on-write. Match the style in your own bindings — _bind_methods reflects the signature you declared, and a by-value Ref<T> parameter is a small cost paid forever. On the script side there is nothing to decide: arguments are handles passed by value, so the caller's variable can never be reseated, but the object is shared and a function that mutates what it was given will be seen doing it. make_read_only() is the nearest thing to a const promise, and it is a run-time flag rather than a compile-time one.

Godot builds with SCons — a Python-based build system — and godot-cpp ships an SConstruct that already encodes every platform, architecture, compiler and debug/release combination the engine supports. Loading it and appending your own sources is the whole build file, which is the argument for not fighting it even if CMake is what you know; community CMake ports exist and are a maintenance commitment. What you build is one shared library per platform you ship, listed in a small .gdextension text file that the editor reads to pick the right one. The script side has no equivalent step at all: the source file is what ships, and compiling it is something the engine does on load — or, as here, whenever you ask.

The engine can dump its entire public API as JSON, and godot-cpp's build turns that file into a class per header before any of your code compiles — so the bindings always match the engine version they were generated against. That is the source of the rule that surprises people, and it runs in one direction only: an extension built against an older 4.x keeps loading in a newer engine, because the compatibility system holds the older call paths open — but one built against a newer API will not load in an older engine at all, since the entry points it was generated against do not exist there yet. ClassDB is the same registry seen from the other side, alive and queryable while the game runs, which is what lets the editor build an inspector for a class it has never heard of — and what makes your registered extension types indistinguishable from built-in ones.

This is the real argument for keeping gameplay in GDScript and reserving C++ for the parts that need it. A script is recompiled on load, so changing one and pressing play costs nothing; the editor reloads a changed script while it is running. A GDExtension is a shared library the editor has already mapped, so reloading it means tearing down every instance it registered and rebuilding them — which Godot 4 can do, and which still has sharp edges: renamed properties lose their values, cached editor state is invalidated, and on Windows the loaded library is locked so the build fails before the reload is even attempted. Plan for a close-rebuild-reopen cycle on the C++ side and you will not be disappointed by it.

Typing alone is commonly a two-to-four times improvement and costs nothing but annotations, because it lets the compiler skip Variant dispatch. Packed arrays remove per-element boxing. And a great deal of what looks like it needs C++ is already C++ inside the engine — MultiMeshInstance for thousands of identical objects, the navigation server for pathfinding, AnimationTree for state machines. GDExtension is the right answer for genuinely novel heavy computation, and it is worth remembering that it costs a build step, an ABI to keep in step with the engine version, and the loss of crash isolation.

Indentation delimits blocks, so the layout and the structure cannot disagree; elif is else if; and range() replaces the three-clause for. match is worth knowing because it is closer to Rust's pattern matching than to C++'s switch: it matches literals, arrays, dictionaries and bound variables with when guards, and it does not fall through. What it does not do is check exhaustiveness. Note that GDScript is Python-like, not Python — no list comprehensions, no decorators, no multiple inheritance, and range() returns a real array.

Like Lua, GDScript is a component of a C++ program rather than an alternative to one, so the question is where the line goes rather than which language wins. The difference is that Godot's two halves share an object model: a GDExtension class and a GDScript class both extend engine types, both override the same virtuals, both register properties with the same ClassDB, and both are nodes in the same tree. That makes the boundary substantially cheaper to cross conceptually than an embedded scripting language's — you are not bridging two type systems, only converting through Variant at the seam.

const is resolved when the script is parsed, so it is closer to constexpr than to a runtime constant — it costs nothing at run time and cannot be reassigned. An enum is a plain set of integers like an unscoped C++ enum, with one convenience C++ lacks: keys() returns the names, because they survive into the running program. The one to be careful about is the third: const on an array or dictionary freezes the handle, not the contents, so the object it names can still be modified — make_read_only() is what actually freezes the contents, and it is checked at run time rather than by the compiler.

memnew(VBoxContainer) and VBoxContainer.new() call the same allocator and produce the same engine object; column->add_child(entry) and column.add_child(entry) are the same method. The differences are all C++'s own: GDCLASS registers the type with the engine's reflection so the editor can list and instantiate it, _bind_methods() is where anything the engine or GDScript needs to call by name gets declared, and the Button * is a raw pointer whose lifetime belongs to its parent — add_child is what makes that true, and forgetting it leaks. A Node subclass is the one place in Godot where a raw new is normal C++.

The two columns are the same calls in the same order, which is the point of putting them side by side — but this one is also the clearest case for NOT reaching for C++. The per-frame work here is twelve points and one draw_polyline_colors, so almost no Variant conversion happens at all and the C++ version buys nothing but a build step. The rule that follows: reach for C++ where the work is per element, per frame — a particle solver, a mesh build, a pathfinder over thousands of cells — not where it is a fixed handful of engine calls. Note also what the C++ column has to spell out that GDScript does not: callable_mp_lambda to hand a lambda to a signal, and PackedVector2Array by name where := infers it.

No physics engine, no collision shapes, no scene file, no assets — Rect2.has_point for the bricks and two sign flips for the walls, which at forty bricks beats a physics server on both speed and readability. Every speed is in pixels per second, so delta keeps the ball crossing the pane at the same rate on a 60Hz laptop and a 144Hz monitor.

Two control schemes, for a reason: a browser reports the pointer only while it is over the canvas, so get_local_mouse_position() freezes where it last saw it. Input.get_axis("ui_left", "ui_right") has no such edge, and both actions ship in Godot's default input map.

Every engine call is identical across the columns; only C++'s own machinery differs — std::vector<Rect2> against a typed Array[Rect2], Ref<InputEventMouseButton> and a validity check against event is InputEventMouseButton. Which answers the obvious question: no, this did not need C++. Ask again at forty thousand bricks.