# dmitriysalnikov/godot_debug_draw_3d architecture

> Architecture diagram of the GitHub repository dmitriysalnikov/godot_debug_draw_3d, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dmitriysalnikov/godot_debug_draw_3d
- Repository: https://github.com/dmitriysalnikov/godot_debug_draw_3d

## Overview

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: [`src/3d/debug_draw_3d.cpp`](https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/3d/debug_draw_3d.cpp) (DebugDraw3D), [`src/2d/debug_draw_2d.cpp`](https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/2d/debug_draw_2d.cpp) (DebugDraw2D), [`src/native_api/c_api.h`](https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/native_api/c_api.h) (Native API), [`src/debug_draw_manager.cpp`](https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/debug_draw_manager.cpp) (Manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_runtime["Runtime"]
  node_n_public_addon["Addon"]
  node_n_register["Register<br/>entrypoint<br/>[register_types.cpp]"]
  node_n_manager["Manager<br/>orchestrator"]
  node_n_api3d["DebugDraw3D<br/>public API<br/>[debug_draw_3d.cpp]"]
  node_n_api2d["DebugDraw2D<br/>public API<br/>[debug_draw_2d.cpp]"]
  node_n_cfg3d["3D config<br/>state model<br/>[config_3d.cpp]"]
  node_n_scope3d["Scope 3D<br/>scope state"]
  node_n_geom["Geometry<br/>mesh builder"]
  node_n_dbggeom["Debug geometry<br/>3D backend"]
  node_n_containers["Containers<br/>scene binding"]
  node_n_render["Render instances<br/>renderer glue"]
  node_n_stats3d["3D stats<br/>telemetry<br/>[stats_3d.cpp]"]
  node_n_cfg2d["2D config<br/>state model<br/>[config_2d.cpp]"]
  node_n_text2d["Grouped text<br/>overlay layer<br/>[grouped_text.cpp]"]
  node_n_stats2d["2D stats<br/>overlay stats<br/>[stats_2d.cpp]"]
  node_n_native_api["Native API<br/>c api bridge<br/>[c_api.h]"]
  node_n_editor["Editor"]
  node_n_resources["Shaders<br/>render assets"]
  node_n_common["Common<br/>shared utils<br/>[colors.cpp]"]
end

subgraph group_grp_tooling["Tooling"]
  node_n_docs["Docs<br/>documentation<br/>[Introduction.md]"]
  node_n_build["Build<br/>toolchain"]
  node_n_tests["Native tests<br/>validation<br/>[test_api_node.cpp]"]
end

subgraph group_grp_samples["Samples"]
  node_n_examples["Examples<br/>demo scenes<br/>[DD3DDemo.tscn]"]
  node_n_webbuild["Web build<br/>demo project<br/>[project.godot]"]
end

node_n_public_addon -->|"loads"| node_n_register
node_n_register -->|"creates"| node_n_manager
node_n_manager -->|"routes 3D"| node_n_api3d
node_n_manager -->|"routes 2D"| node_n_api2d
node_n_api3d -->|"uses"| node_n_cfg3d
node_n_api3d -->|"scopes"| node_n_scope3d
node_n_api3d -->|"builds"| node_n_geom
node_n_geom -->|"stores"| node_n_dbggeom
node_n_dbggeom -->|"attaches"| node_n_containers
node_n_containers -->|"feeds"| node_n_render
node_n_render -->|"styles with"| node_n_resources
node_n_api3d -->|"records"| node_n_stats3d
node_n_api2d -->|"uses"| node_n_cfg2d
node_n_api2d -->|"renders"| node_n_text2d
node_n_api2d -->|"reports"| node_n_stats2d
node_n_native_api -->|"bridges"| node_n_api3d
node_n_native_api -->|"bridges"| node_n_api2d
node_n_editor -->|"integrates"| node_n_public_addon
node_n_build -->|"packages"| node_n_public_addon
node_n_build -->|"generates"| node_n_native_api
node_n_tests -->|"verifies"| node_n_native_api
node_n_examples -->|"demonstrates"| node_n_api3d
node_n_examples -->|"demonstrates"| node_n_api2d
node_n_webbuild -->|"exports"| node_n_api3d
node_n_docs -->|"documents"| node_n_api3d
node_n_docs -->|"documents"| node_n_native_api
node_n_common -->|"supports"| node_n_api3d
node_n_common -->|"supports"| node_n_api2d

click node_n_public_addon "https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/addons/debug_draw_3d/debug_draw_3d.gdextension"
click node_n_register "https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/register_types.cpp"
click node_n_manager "https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/debug_draw_manager.cpp"
click node_n_api3d "https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/3d/debug_draw_3d.cpp"
click node_n_api2d "https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/2d/debug_draw_2d.cpp"
click node_n_cfg3d "https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/3d/config_3d.cpp"
click node_n_scope3d "https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/3d/config_scope_3d.cpp"
click node_n_geom "https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/3d/geometry_generators.cpp"
click node_n_dbggeom "https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/3d/debug_geometry_container.cpp"
click node_n_containers "https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/3d/nodes_container.cpp"
click node_n_render "https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/3d/render_instances.cpp"
click node_n_stats3d "https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/3d/stats_3d.cpp"
click node_n_cfg2d "https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/2d/config_2d.cpp"
click node_n_text2d "https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/2d/grouped_text.cpp"
click node_n_stats2d "https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/2d/stats_2d.cpp"
click node_n_native_api "https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/native_api/c_api.h"
click node_n_editor "https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/editor/editor_menu_extensions.cpp"
click node_n_resources "https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/resources/wireframe_unshaded.gdshader"
click node_n_common "https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/common/colors.cpp"
click node_n_examples "https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/examples_dd3d/DD3DDemo.tscn"
click node_n_webbuild "https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/dd3d_web_build/project.godot"
click node_n_docs "https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/docs/Introduction.md"
click node_n_build "https://github.com/dmitriysalnikov/godot_debug_draw_3d/tree/master/SConstruct"
click node_n_tests "https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/tests_native_api/cpp/test_api_node.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_public_addon,node_n_register,node_n_manager,node_n_api3d,node_n_api2d,node_n_cfg3d,node_n_scope3d,node_n_geom,node_n_dbggeom,node_n_containers,node_n_render,node_n_stats3d,node_n_cfg2d,node_n_text2d,node_n_stats2d,node_n_native_api,node_n_editor,node_n_resources,node_n_common toneBlue
class node_n_docs,node_n_build,node_n_tests toneAmber
class node_n_examples,node_n_webbuild toneMint
```

## Components

### Runtime

Native addon runtime and public APIs

- [Addon](https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/addons/debug_draw_3d/debug_draw_3d.gdextension): godot addon · Shipped plugin entry under addons/debug_draw_3d · `addons/debug_draw_3d/debug_draw_3d.gdextension`
- [Register](https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/register_types.cpp): entrypoint · Binds native classes and extension types · `src/register_types.cpp`
- [Manager](https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/debug_draw_manager.cpp): orchestrator · Coordinates draw requests and runtime routing · `src/debug_draw_manager.cpp`
- [DebugDraw3D](https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/3d/debug_draw_3d.cpp): public API · Main 3D drawing surface used by scripts and native callers · `src/3d/debug_draw_3d.cpp`
- [DebugDraw2D](https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/2d/debug_draw_2d.cpp): public API · Screen-space overlay API for text and stats · `src/2d/debug_draw_2d.cpp`
- [3D config](https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/3d/config_3d.cpp): state model · Scoped and per-frame configuration for 3D draws · `src/3d/config_3d.cpp`
- [Scope 3D](https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/3d/config_scope_3d.cpp): scope state · Nested override/reset handling for 3D settings · `src/3d/config_scope_3d.cpp`
- [Geometry](https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/3d/geometry_generators.cpp): mesh builder · Converts draw commands into reusable geometry data · `src/3d/geometry_generators.cpp`
- [Debug geometry](https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/3d/debug_geometry_container.cpp): 3D backend · Holds generated 3D debug content before rendering · `src/3d/debug_geometry_container.cpp`
- [Containers](https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/3d/nodes_container.cpp): scene binding · Tracks worlds, viewports, and attached debug nodes · `src/3d/nodes_container.cpp`
- [Render instances](https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/3d/render_instances.cpp): renderer glue · Manages instance objects and per-frame rendering output · `src/3d/render_instances.cpp`
- [3D stats](https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/3d/stats_3d.cpp): telemetry · Tracks 3D drawing statistics and counters · `src/3d/stats_3d.cpp`
- [2D config](https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/2d/config_2d.cpp): state model · Configuration for overlay text and 2D debug output · `src/2d/config_2d.cpp`
- [Grouped text](https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/2d/grouped_text.cpp): overlay layer · Grouped screen-space text rendering · `src/2d/grouped_text.cpp`
- [2D stats](https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/2d/stats_2d.cpp): overlay stats · Screen overlay statistics and text status · `src/2d/stats_2d.cpp`
- [Native API](https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/native_api/c_api.h): c api bridge · Stable C API with generated C++ and C# bindings templates · `src/native_api/c_api.h`
- [Editor](https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/editor/editor_menu_extensions.cpp): editor ext · Editor integration and asset-library update checks · `src/editor/editor_menu_extensions.cpp`
- [Shaders](https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/resources/wireframe_unshaded.gdshader): render assets · Bundled unshaded shaders for billboards, planes, meshes, and wireframes · `src/resources/wireframe_unshaded.gdshader`
- [Common](https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/src/common/colors.cpp): shared utils · Shared utility code used across runtime subsystems · `src/common/colors.cpp`

### Tooling

Build, docs, tests, and distribution

- [Docs](https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/docs/Introduction.md): documentation · API, build, export, and examples documentation · `docs/Introduction.md`
- [Build](https://github.com/dmitriysalnikov/godot_debug_draw_3d/tree/master/SConstruct): toolchain · SCons build scripts, vendored Godot C++, patches, and helper utilities · `SConstruct`
- [Native tests](https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/tests_native_api/cpp/test_api_node.cpp): validation · Native API test harness and web headless validation · `tests_native_api/cpp/test_api_node.cpp`

### Samples

Example and demo projects

- [Examples](https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/examples_dd3d/DD3DDemo.tscn): demo scenes · GDScript and C# demo scenes exercising the addon · `examples_dd3d/DD3DDemo.tscn`
- [Web build](https://github.com/dmitriysalnikov/godot_debug_draw_3d/blob/master/dd3d_web_build/project.godot): demo project · Standalone Godot project for web testing and export · `dd3d_web_build/project.godot`

## Connections

- 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
