How dmitriysalnikov/godot_debug_draw_3d works
1. Project shape
This repository is a Godot 4 add-on implemented as a native C++ GDExtension. The shipped plugin lives under addons/debug_draw_3d, while the source code, docs, examples, and CI/build tooling are kept in the repository root. The same codebase supports use from GDScript, C++, and C#.
2. Primary runtime boundary
The main architectural boundary is between Godot scripts/scenes and the native extension. User code calls the public DebugDraw3D and DebugDraw2D APIs; those calls cross into C++ through the extension registration layer and are then converted into internal draw commands and renderable instances.
3. 3D debug drawing subsystem
Most of the repo is the 3D drawing pipeline in src/3d. It is split into configuration objects, geometry generation, render-instance management, node/viewport tracking, and statistics. The design suggests a command-to-geometry flow: high-level draw requests become reusable geometry data, which is then attached to the correct world/viewport and rendered each frame.
4. 2D overlay subsystem
src/2d handles screen-space overlays such as grouped text and stats display. This subsystem is separate from the 3D path because it has different placement rules, drawing semantics, and update cadence. The README’s DebugDraw2D.set_text(...) examples map to this overlay layer rather than the 3D geometry pipeline.
5. Scoped configuration model
A key architectural concept is scoped state. The config_3d, config_2d, and config_scope_3d classes indicate that draw settings are not just global; they can be reset per frame and temporarily overridden within nested scopes. This is how the addon supports per-instance settings like thickness, depth-test behavior, viewport selection, and brightness without forcing callers to pass full parameter sets every time.
6. Viewport and world awareness
Support for multiple World3D objects and non-standard Viewports is a first-class boundary in the design. The presence of nodes_container, debug_geometry_container, and the README’s notes about scoped viewport selection indicate that the addon tracks where each draw request should appear and binds rendered output to the correct scene view rather than assuming a single default camera/world.
7. Internal rendering assets
The addon relies on bundled shader resources in src/resources, including unshaded variants for billboards, planes, meshes, and wireframes. These resources are part of the rendering backend, not user-facing content, and they define the visual style of the debug primitives independently of the application’s own materials.
8. Native API surface for non-GDScript users
src/native_api provides a C API plus generated C++ and C# bindings templates. This is the bridge that makes the addon usable outside of GDScript. The separate tests_native_api tree reinforces that this API is a stable architectural surface, not just an internal helper.
9. Editor integration and telemetry
src/editor contains editor-facing extensions such as menu hooks and an asset-library update checker. The README’s telemetry note maps to this layer: usage statistics are collected only in editor-capable builds, not in runtime-only libraries. So editor integration is a distinct subsystem with its own behavior and settings boundary.
10. Examples, demo app, and web packaging
examples_dd3d contains runnable scene-based demos that exercise the API from GDScript and C#. dd3d_web_build is a separate Godot project used for web testing/demo export. This indicates the repo maintains at least three practical integration targets: embedded addon usage, sample scenes for validation, and a standalone web demo.
11. Build and distribution pipeline
The repository uses SConstruct, vendored godot-cpp, and helper scripts under lib_utils*.py and patches/ to build and package binaries across platforms. GitHub Actions workflows cover extension compilation, release uploads, cache cleanup, virus scanning, and web deployment. The architecture therefore includes a significant build/distribution layer, not just runtime code.
12. Documentation and generated artifacts
docs/, Doxyfile, and the image/doc generation utilities show that the API and behavior are documented as part of the project’s delivery model. The documentation is not incidental: it mirrors the extension’s public API, build options, and platform-specific behavior, which is important because the addon is intended to be consumed directly by other Godot projects.
13. Testing and validation
There are dedicated native API tests and a web headless test setup. That implies the repo validates both the C++ extension behavior and the exported/web-facing integration points. In architecture terms, the tests sit at the boundary between the plugin and Godot runtime, ensuring the public API remains usable across supported languages and platforms.
14. Overall data flow
The high-level flow is: game/editor code calls debug draw APIs → the GDExtension layer routes the request into native managers → configuration and scope state determine viewport/world/render settings → geometry and text are generated or updated → rendering containers emit the final debug visuals into the correct 2D/3D context. The addon is therefore a stateful rendering service embedded in Godot, with explicit support for editor features, multiple runtimes, and multiple target platforms.
Main entry points: debug_draw_3d.cpp DebugDraw3D · debug_draw_2d.cpp DebugDraw2D · c_api.h Native API · debug_draw_manager.cpp Manager
Components 24
Runtime
Native addon runtime and public APIs
- Addon · Shipped plugin entry under addons/debug_draw_3d
addons/debug_draw_3d/debug_draw_3d.gdextension - Register · Binds native classes and extension types
src/register_types.cpp - Manager · Coordinates draw requests and runtime routing
src/debug_draw_manager.cpp - DebugDraw3D · Main 3D drawing surface used by scripts and native callers
src/3d/debug_draw_3d.cpp - DebugDraw2D · Screen-space overlay API for text and stats
src/2d/debug_draw_2d.cpp - 3D config · Scoped and per-frame configuration for 3D draws
src/3d/config_3d.cpp - Scope 3D · Nested override/reset handling for 3D settings
src/3d/config_scope_3d.cpp - Geometry · Converts draw commands into reusable geometry data
src/3d/geometry_generators.cpp - Debug geometry · Holds generated 3D debug content before rendering
src/3d/debug_geometry_container.cpp - Containers · Tracks worlds, viewports, and attached debug nodes
src/3d/nodes_container.cpp - Render instances · Manages instance objects and per-frame rendering output
src/3d/render_instances.cpp - 3D stats · Tracks 3D drawing statistics and counters
src/3d/stats_3d.cpp - 2D config · Configuration for overlay text and 2D debug output
src/2d/config_2d.cpp - Grouped text · Grouped screen-space text rendering
src/2d/grouped_text.cpp - 2D stats · Screen overlay statistics and text status
src/2d/stats_2d.cpp - Native API · Stable C API with generated C++ and C# bindings templates
src/native_api/c_api.h - Editor · Editor integration and asset-library update checks
src/editor/editor_menu_extensions.cpp - Shaders · Bundled unshaded shaders for billboards, planes, meshes, and wireframes
src/resources/wireframe_unshaded.gdshader - Common · Shared utility code used across runtime subsystems
src/common/colors.cpp
Tooling
Build, docs, tests, and distribution
- Docs · API, build, export, and examples documentation
docs/Introduction.md - Build · SCons build scripts, vendored Godot C++, patches, and helper utilities
SConstruct - Native tests · Native API test harness and web headless validation
tests_native_api/cpp/test_api_node.cpp
Connections 28
- Addon → Register: loads · The packaged extension enters through registration
- Register → Manager: creates · Registers the central manager and API classes
- Manager → DebugDraw3D: routes 3D · Dispatches 3D draw calls into the main API
- Manager → DebugDraw2D: routes 2D · Dispatches overlay and text calls
- DebugDraw3D → 3D config: uses · Applies scoped 3D settings to draw requests
- DebugDraw3D → Scope 3D: scopes · Supports nested temporary overrides
- DebugDraw3D → Geometry: builds · Turns draw requests into geometry data
- Geometry → Debug geometry: stores · Places generated geometry into debug containers
- Debug geometry → Containers: attaches · Binds debug content to the right world and viewport
- Containers → Render instances: feeds · Supplies renderable instances for each frame
- Render instances → Shaders: styles with · Uses bundled shaders for visual presentation
- DebugDraw3D → 3D stats: records · Collects 3D usage and draw statistics
- DebugDraw2D → 2D config: uses · Applies 2D overlay configuration
- DebugDraw2D → Grouped text: renders · Produces grouped text overlays
- DebugDraw2D → 2D stats: reports · Updates 2D status and stats overlays
- Native API → DebugDraw3D: bridges · Exposes the 3D API to non-GDScript users
- Native API → DebugDraw2D: bridges · Exposes the 2D API to non-GDScript users
- Editor → Addon: integrates · Editor-only features augment the addon experience
- Build → Addon: packages · Build tooling produces the distributable extension
- Build → Native API: generates · Creates binding templates and API artifacts
- Native tests → Native API: verifies · Checks the stable native API surface
- Examples → DebugDraw3D: demonstrates · Shows 3D usage from GDScript and C#
- Examples → DebugDraw2D: demonstrates · Shows overlay/text usage from demos
- Web build → DebugDraw3D: exports · Exercises the addon in a standalone web project
- Docs → DebugDraw3D: documents · Covers public drawing behavior and usage
- Docs → Native API: documents · Explains the non-GDScript integration surface
- Common → DebugDraw3D: supports · Provides shared helpers used by 3D internals
- Common → DebugDraw2D: supports · Provides shared helpers used by 2D internals