DebugDraw3D puts a C++ debug renderer inside Godot, and its scoped configs are the real feature

One C++ add-on callable from three languages

DebugDraw3D is a Godot add-on for debug drawing in 3D and for a set of 2D overlays, written in C++ and usable from GDScript, C++ or C#. That last point is the differentiator. Most debug drawing helpers are GDScript only, which means a project that has a C++ core or a C# layer cannot share one drawing helper across the whole codebase.

The project has its own lineage, and it explains the design. It is based on the author's earlier add-on, which was C# only, and that earlier project was inspired by Zylann's GDScript debug draw add-on. A Godot 3 version of this add-on lives on a separate `godot_3` branch, and the current one targets Godot 4.

The repository layout shows how the work is done. There is a `src/` directory for the C++ source, a `godot-cpp` submodule for the engine bindings, a `patches/` directory, a `SConstruct` build script with `lib_utils.py` helpers for the build, and `lib_utils_gen_dd3d_api.py`, whose name says it generates the scripting API surface. There is an `addons/` directory holding the editor plugin, an `examples_dd3d/` folder with the sample scenes, a `tests_native_api/` directory, a `dd3d_web_build/` directory for the web demo, and a `Doxyfile` for documentation generation.

A generated API layer is the mark of an add-on that intends to be a real interface rather than a script with helper functions, and the same applies to the `C#` support, which is a second binding generated from the same core.

The shape catalogue, from arrows to camera frustums

The 3D drawing vocabulary covers the things you actually want to see while debugging.

The list includes arrow, billboard opaque square, box, camera frustum, capsule, cylinder, gizmo, grid, line, line path, line with arrow, plane, points, position 3D as three crossing axes, sphere and 3D text. The overlay side is smaller, with text that supports grouping and coloring.

A few of these are worth singling out because they answer questions that are otherwise hard to answer visually. The camera frustum draws the volume a camera can see, which turns a bad projection into something you can look at instead of reason about. The gizmo and the three-axis position marker are the standard way to check whether an object's transform is what you think it is. The line path takes a polyline, and the grid draws a reference plane, both of which are the kind of thing you want when tracking a moving body or a navigation path.

The billboard opaque square is an interesting entry. It draws a quad that always faces the camera, which is the standard way to render a label or icon in 3D space without a full text or sprite pipeline, and it explains how the 3D text feature is likely to look from any angle.

The 2D overlay is deliberately modest. Text with grouping and coloring, placed in a corner, is a heads-up display of numbers, not a UI framework, and the README is explicit that the entire text overlay can only be placed in one corner.

Scoped configs are the mechanism worth learning from

Most debug drawing APIs take every parameter on every call, which turns a draw function into a wall of arguments. DebugDraw3D instead uses a scoped configuration that a block of drawing code inherits.

@tool
extends Node3D

func _ready():
    # Set the base scoped_config.
    # Each frame will be reset to these scoped values.
    DebugDraw3D.scoped_config().set_thickness(0.1).set_center_brightness(0.6)

func _process(delta):
    DebugDraw3D.draw_box(Vector3.ZERO, Quaternion.IDENTITY, Vector3.ONE * 2, Color.CORNFLOWER_BLUE)
    if true:
        # Create a scoped config that will exist until exiting this if.
        var _s = DebugDraw3D.new_scoped_config().set_thickness(0).set_center_brightness(0.1)
        DebugDraw3D.draw_box(Vector3.ZERO, Quaternion.IDENTITY, Vector3.ONE, Color.RED)
        # If necessary, the values inside this scope can be changed
        # even before each call to draw_*.
        _s.set_thickness(0.05)
        DebugDraw3D.draw_box(Vector3(1,0,1), Quaternion.IDENTITY, Vector3.ONE * 1, Color.BLUE_VIOLET)

The mechanics are clear from the example. `scoped_config()` sets the base values that are reset each frame, and `new_scoped_config()` creates a config that lives only until the block exits. The setters chain, so `set_thickness(0.1).set_center_brightness(0.6)` reads as one expression, and the values inside a scope can be changed again before the next draw call.

The practical benefit is that a drawing helper can be written once with sensible defaults and then adjusted in one place. Thickness and brightness are the two settings the example shows, and there are others, including the no depth test mode, which is set per instance along with other settings.

There is one requirement that catches people out, and the README has a tip about it. If you render a 3D scene into a non standard Viewport, you have to specify that viewport in the scoped config, or the geometry will be drawn into the wrong target.

The basic draw calls, and how the 2D overlay stays in sync

The simple test in the README is the smallest complete example, and it shows both halves of the API working together.

func _process(delta: float) -> void:
    var _time = Time.get_ticks_msec() / 1000.0
    var box_pos = Vector3(0, sin(_time * 4), 0)
    var line_begin = Vector3(-1, sin(_time * 4), 0)
    var line_end = Vector3(1, cos(_time * 4), 0)

    DebugDraw3D.draw_box(box_pos, Quaternion.IDENTITY, Vector3(1, 2, 1), Color(0, 1, 0))
    DebugDraw3D.draw_line(line_begin, line_end, Color(1, 1, 0))
    DebugDraw2D.set_text("Time", _time)
    DebugDraw2D.set_text("Frames drawn", Engine.get_frames_drawn())
    DebugDraw2D.set_text("FPS", Engine.get_frames_per_second())
    DebugDraw2D.set_text("delta", delta)

The 3D calls are stateless per frame: each `draw_box` takes a position, an orientation, a size and a colour. The 2D side is different in kind. `set_text` writes a keyed value, so the overlay is a set of named fields that are updated rather than appended, and the same key is overwritten each frame.

That distinction matters for anyone writing a debug HUD. The 3D geometry is a stream of things to draw this frame. The 2D text is a persistent panel of values you keep updating. The README notes that the keys and values in a text group cannot contain multi-line strings, which is a limitation of the text format rather than of the draw call.

The API is documented both on the project site and inside the editor, where the `DebugDraw3D` and `DebugDraw2D` nodes carry the list of all available functions in their built in help, which is the faster reference when you are already in the editor.

Every platform is precompiled, and the version is tied to the engine

The add-on ships precompiled for Windows, Linux built on Ubuntu 22.04, macOS 10.15 and newer, Android 5.0 and newer, iOS and the web, where Firefox support comes from Godot 4.3 and newer. That is a wide target list for a debug tool, and it is what makes the add-on usable in a project that ships to more than one platform rather than only to a desktop editor session.

There is an interactive web demo hosted on the project site, and the `dd3d_web_build/` directory in the repository is what it is built from. A web build of a debug drawing library is a slightly odd idea until you realise it lets someone see the add-on working without installing Godot.

The version scheme ties the add-on to the engine. The release tags are labelled with the supported engine version, and the three most recent are 1.7.1, 1.7.2 and 1.7.3, all marked for 4.4.1 and newer. The last push to the repository was on 2026-04-04, and the repository is not archived.

Installation is manual and deliberately simple. Close the editor, copy the `addons/debug_draw_3d` folder into your project's `addons` folder, creating it if needed, and launch the editor. Downloads come from the Godot Asset Library or from the GitHub Releases page, and for versions from 1.4.5 onwards the file is `debug-draw-3d_[version].zip`.

There is also a note about double precision builds. The add-on supports them, and the documentation has a page on the subject, which matters because a debug overlay drawing at a slightly different position than expected is exactly the symptom of a mismatch between single and double precision expectations.

Telemetry in the editor, and the limitations the project admits

The add-on collects anonymous statistics on editor usage time. The data includes the library version, engine version, operating system, system architecture and locale, and the README states that no personally identifiable information is gathered. Libraries without editor support collect nothing, and previews running in the editor collect nothing either.

The opt-out is a single editor setting, `debug_draw_3d/settings/telemetry_state`. It is worth knowing the path, because a team with a policy on usage analytics needs to either disable it or record the decision, and the setting is documented rather than hidden.

The known issues section is short and honest. Text keys and values cannot contain multi-line strings. The entire text overlay can only be placed in one corner, which rules out a HUD with panels in more than one place. And the camera frustum does not take into account the window size from ProjectSettings, a limitation that is tracked as an upstream Godot issue.

That last one is a good example of the right kind of limitation to report. A frustum that ignores the window aspect ratio is misleading in exactly the situation you would draw it in, and linking the upstream issue tells you the project is not going to work around it.

The add-on also supports several World3D environments and different Viewports, and that support is what the scoped config viewport hint ties into.

Editorial conclusion

Adopt DebugDraw3D if you work in Godot 4 with physics, navigation or animation code that needs visible geometry, and you want one drawing API callable from GDScript, C++ and C# alike. Do not adopt it if you are still on Godot 3, since a separate branch exists for that version and the add-on targets the 4.x line, and do not expect the 2D overlay to be a general UI layer, because the whole text overlay can only sit in one corner. Verify first that the precompiled binary matches your Godot version, that the engine build you use is a standard single precision build unless you specifically need the double precision variant, and that you have read the telemetry setting in the editor settings if your environment forbids usage statistics.

Frequently asked questions

Official sources

1. DmitriySalnikov/godot_debug_draw_3d on GitHub
2. Issues
3. Project website
4. README
5. Releases