# spimort/terrabrush architecture

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

- Interactive diagram: https://gitdiagram.com/spimort/terrabrush
- Repository: https://github.com/spimort/terrabrush

## Overview

TerraBrush is a Godot GDExtension terrain editor. The main workflow is to configure a TerraBrush node, create or import zone-based terrain data, edit it with terrain tools, and refresh the runtime terrain. The README documents the broad editing capabilities; source excerpts confirm key runtime construction and import behavior. Several subsystems are represented by their exact enclosing directories because their implementation files were not sampled, so those links are documented rather than inferred from unseen calls.

Main entry points: [`src/terra_brush.cpp`](https://github.com/spimort/terrabrush/blob/main/src/terra_brush.cpp) (TerraBrush node), [`src/terra_brush_plugin.cpp`](https://github.com/spimort/terrabrush/blob/main/src/terra_brush_plugin.cpp) (Editor plugin), [`src/misc/importer_engine.cpp`](https://github.com/spimort/terrabrush/blob/main/src/misc/importer_engine.cpp) (Image importer), [`src/terra_brush_editor.cpp`](https://github.com/spimort/terrabrush/blob/main/src/terra_brush_editor.cpp) (In-game editor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_editor["Godot editor"]
  node_godot_editor["Godot editor"]
  node_plugin["Editor plugin"]
  node_editor_node["In-game editor"]
end

subgraph group_editing["Terrain editing"]
  node_tools["Editing tools"]
  node_sculpt["Sculpt tools<br/>[sculpt_tool.cpp]"]
  node_angle["Angle tools<br/>[set_angle_tool.cpp]"]
  node_tool_base["Tool base<br/>[tool_base.cpp]"]
  node_menus["Tool menus<br/>[tools_pie_menu.h]"]
  node_keybinds["Key bindings"]
  node_brush["Brushes<br/>[terra_brush.cpp]"]
end

subgraph group_data["Terrain data"]
  node_zones[("Zone collection<br/>[zones_resource.cpp]")]
  node_zone_data[("Zone images<br/>[zone_resource.h]")]
  node_definitions["Terrain definitions"]
end

subgraph group_runtime["Terrain runtime"]
  node_terrain_node["TerraBrush node<br/>[terra_brush.cpp]"]
  node_terrain["Terrain mesh<br/>[terrain.cpp]"]
  node_clipmap["LOD clipmap<br/>[clipmap.cpp]"]
  node_foliage["Foliage rendering<br/>[foliage.cpp]"]
  node_objects["Object scattering<br/>[objects.cpp]"]
  node_water_snow["Water and snow"]
end

subgraph group_support["Import and export"]
  node_importer["Image importer"]
  node_exporter["Terrain exporter"]
end

node_godot_user(("Godot user"))

node_godot_user -->|"edits in"| node_godot_editor
node_godot_editor -->|"loads plugin"| node_plugin
node_plugin -->|"creates terrain"| node_terrain_node
node_godot_user -->|"edits in game"| node_editor_node
node_editor_node -->|"dispatches tools"| node_tools
node_editor_node -->|"shows menus"| node_menus
node_plugin -->|"configures keys"| node_keybinds
node_tools -->|"includes sculpting"| node_sculpt
node_tools -->|"includes angle setting"| node_angle
node_sculpt -->|"inherits behavior"| node_tool_base
node_angle -->|"inherits behavior"| node_tool_base
node_tool_base -->|"uses bindings"| node_keybinds
node_godot_user -->|"selects brush"| node_brush
node_terrain_node -.->|"loads zones"| node_zones
node_terrain_node -->|"creates terrain"| node_terrain
node_terrain -->|"uses clipmap"| node_clipmap
node_terrain_node -->|"creates foliage"| node_foliage
node_terrain_node -->|"manages objects"| node_objects
node_terrain_node -->|"creates water"| node_water_snow
node_terrain_node -->|"uses definitions"| node_definitions
node_importer -->|"imports into"| node_terrain_node
node_importer -->|"updates zones"| node_zones
node_importer -->|"writes images"| node_zone_data
node_plugin -->|"invokes import"| node_importer
node_plugin -->|"invokes export"| node_exporter
node_exporter -->|"exports terrain"| node_terrain_node

click node_plugin "https://github.com/spimort/terrabrush/blob/main/src/terra_brush_plugin.cpp"
click node_editor_node "https://github.com/spimort/terrabrush/blob/main/src/terra_brush_editor.cpp"
click node_tools "https://github.com/spimort/terrabrush/tree/main/src/editor_tools"
click node_sculpt "https://github.com/spimort/terrabrush/blob/main/src/editor_tools/sculpt_tool.cpp"
click node_angle "https://github.com/spimort/terrabrush/blob/main/src/editor_tools/set_angle_tool.cpp"
click node_tool_base "https://github.com/spimort/terrabrush/blob/main/src/editor_tools/tool_base.cpp"
click node_menus "https://github.com/spimort/terrabrush/blob/main/src/editor_nodes/tools_pie_menu.h"
click node_keybinds "https://github.com/spimort/terrabrush/blob/main/src/misc/keybind_manager.cpp"
click node_brush "https://github.com/spimort/terrabrush/blob/main/src/terra_brush.cpp"
click node_terrain_node "https://github.com/spimort/terrabrush/blob/main/src/terra_brush.cpp"
click node_terrain "https://github.com/spimort/terrabrush/blob/main/src/nodes/terrain.cpp"
click node_clipmap "https://github.com/spimort/terrabrush/blob/main/src/nodes/clipmap.cpp"
click node_foliage "https://github.com/spimort/terrabrush/blob/main/src/nodes/foliage.cpp"
click node_objects "https://github.com/spimort/terrabrush/blob/main/src/nodes/objects.cpp"
click node_water_snow "https://github.com/spimort/terrabrush/tree/main/src/nodes"
click node_zones "https://github.com/spimort/terrabrush/blob/main/src/editor_resources/zones_resource.cpp"
click node_zone_data "https://github.com/spimort/terrabrush/blob/main/src/editor_resources/zone_resource.h"
click node_definitions "https://github.com/spimort/terrabrush/tree/main/src/editor_resources"
click node_importer "https://github.com/spimort/terrabrush/blob/main/src/misc/importer_engine.cpp"
click node_exporter "https://github.com/spimort/terrabrush/blob/main/src/misc/exporter_engine.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_godot_editor,node_plugin,node_editor_node,node_godot_user toneBlue
class node_tools,node_sculpt,node_angle,node_tool_base,node_menus,node_keybinds,node_brush toneAmber
class node_zones,node_zone_data,node_definitions toneMint
class node_terrain_node,node_terrain,node_clipmap,node_foliage,node_objects,node_water_snow toneRose
class node_importer,node_exporter toneIndigo
```

## Components

### Godot editor

- **Godot editor**
- [Editor plugin](https://github.com/spimort/terrabrush/blob/main/src/terra_brush_plugin.cpp): `src/terra_brush_plugin.cpp`
- [In-game editor](https://github.com/spimort/terrabrush/blob/main/src/terra_brush_editor.cpp): `src/terra_brush_editor.cpp`

### Terrain editing

- [Editing tools](https://github.com/spimort/terrabrush/tree/main/src/editor_tools): `src/editor_tools`
- [Sculpt tools](https://github.com/spimort/terrabrush/blob/main/src/editor_tools/sculpt_tool.cpp): `src/editor_tools/sculpt_tool.cpp`
- [Angle tools](https://github.com/spimort/terrabrush/blob/main/src/editor_tools/set_angle_tool.cpp): `src/editor_tools/set_angle_tool.cpp`
- [Tool base](https://github.com/spimort/terrabrush/blob/main/src/editor_tools/tool_base.cpp): `src/editor_tools/tool_base.cpp`
- [Tool menus](https://github.com/spimort/terrabrush/blob/main/src/editor_nodes/tools_pie_menu.h): `src/editor_nodes/tools_pie_menu.h`
- [Key bindings](https://github.com/spimort/terrabrush/blob/main/src/misc/keybind_manager.cpp): `src/misc/keybind_manager.cpp`
- [Brushes](https://github.com/spimort/terrabrush/blob/main/src/terra_brush.cpp): `src/terra_brush.cpp`

### Terrain data

- [Zone collection](https://github.com/spimort/terrabrush/blob/main/src/editor_resources/zones_resource.cpp): `src/editor_resources/zones_resource.cpp`
- [Zone images](https://github.com/spimort/terrabrush/blob/main/src/editor_resources/zone_resource.h): `src/editor_resources/zone_resource.h`
- [Terrain definitions](https://github.com/spimort/terrabrush/tree/main/src/editor_resources): `src/editor_resources`

### Terrain runtime

- [TerraBrush node](https://github.com/spimort/terrabrush/blob/main/src/terra_brush.cpp): `src/terra_brush.cpp`
- [Terrain mesh](https://github.com/spimort/terrabrush/blob/main/src/nodes/terrain.cpp): `src/nodes/terrain.cpp`
- [LOD clipmap](https://github.com/spimort/terrabrush/blob/main/src/nodes/clipmap.cpp): `src/nodes/clipmap.cpp`
- [Foliage rendering](https://github.com/spimort/terrabrush/blob/main/src/nodes/foliage.cpp): `src/nodes/foliage.cpp`
- [Object scattering](https://github.com/spimort/terrabrush/blob/main/src/nodes/objects.cpp): `src/nodes/objects.cpp`
- [Water and snow](https://github.com/spimort/terrabrush/tree/main/src/nodes): `src/nodes`

### Import and export

- [Image importer](https://github.com/spimort/terrabrush/blob/main/src/misc/importer_engine.cpp): `src/misc/importer_engine.cpp`
- [Terrain exporter](https://github.com/spimort/terrabrush/blob/main/src/misc/exporter_engine.cpp): `src/misc/exporter_engine.cpp`

### Other components

- **Godot user**

## Connections

- Godot user → Godot editor: edits in
- Godot editor → Editor plugin: loads plugin
- Editor plugin → TerraBrush node: creates terrain (evidence: `src/terra_brush_plugin.cpp`)
- Godot user → In-game editor: edits in game
- In-game editor → Editing tools: dispatches tools (evidence: `src/terra_brush_editor.cpp`)
- In-game editor → Tool menus: shows menus (evidence: `src/terra_brush_editor.cpp`)
- Editor plugin → Key bindings: configures keys (evidence: `src/terra_brush_plugin.cpp`)
- Editing tools → Sculpt tools: includes sculpting (evidence: `src/editor_tools/sculpt_tool.cpp`)
- Editing tools → Angle tools: includes angle setting (evidence: `src/editor_tools/set_angle_tool.cpp`)
- Sculpt tools → Tool base: inherits behavior
- Angle tools → Tool base: inherits behavior
- Tool base → Key bindings: uses bindings (evidence: `src/editor_tools/tool_base.cpp`)
- Godot user → Brushes: selects brush
- TerraBrush node → Zone collection: loads zones
- TerraBrush node → Terrain mesh: creates terrain (evidence: `src/terra_brush.cpp`)
- Terrain mesh → LOD clipmap: uses clipmap (evidence: `src/nodes/terrain.cpp`)
- TerraBrush node → Foliage rendering: creates foliage (evidence: `src/terra_brush.cpp`)
- TerraBrush node → Object scattering: manages objects (evidence: `src/terra_brush.cpp`)
- TerraBrush node → Water and snow: creates water (evidence: `src/terra_brush.cpp`)
- TerraBrush node → Terrain definitions: uses definitions
- Image importer → TerraBrush node: imports into
- Image importer → Zone collection: updates zones (evidence: `src/misc/importer_engine.cpp`)
- Image importer → Zone images: writes images (evidence: `src/misc/importer_engine.cpp`)
- Editor plugin → Image importer: invokes import (evidence: `src/terra_brush_plugin.cpp`)
- Editor plugin → Terrain exporter: invokes export (evidence: `src/terra_brush_plugin.cpp`)
- Terrain exporter → TerraBrush node: exports terrain
