Modular Tree (MTree)

A procedural tree generator addon for Blender using a node-based workflow.

Note: Maintained fork of Mtree by MaximeHerpin.

Features

• Quick Generate - One-click tree generation with presets (Oak, Pine, Willow)
• Node-based workflow - Build trees visually by connecting nodes for full control
• Procedural generation - Control trunk, branches, and leaves with parameters
• Multi-level branching - Chain branch nodes for complex tree structures
• Crown shapes - 8 botanical envelope shapes (conical, spherical, flame, etc.) based on Weber & Penn
• L-system growth - Biologically-inspired growth simulation with apical dominance
• Realistic physics - Gravity, stiffness, and natural spiral patterns (phyllotaxis)
• Leaf distribution - Automatic leaf placement on thin branches via geometry nodes
• Pivot Painter 2.0 export - Export wind animation data for Unreal Engine 5
• Non-destructive - Adjust parameters and regenerate anytime

Requirements

• Blender 4.3 or later

Installation

Blender Extensions

Find the extension on the Blender extension platform

https://extensions.blender.org/add-ons/modular-tree/

Local Installation

1. Download the latest release for your OS from Releases
2. In Blender: Edit -> Preferences -> Add-ons -> Install
3. Select the downloaded .zip file
4. Enable "Modular Tree" in the addon list

Quick Start

Quick Generate (Easiest)

1. Open the 3D View sidebar (press N)
2. Select the MTree tab
3. Click Generate Tree and choose a preset (Oak, Pine, Willow, or Random)

Node Editor (Full Control)

1. Open a Node Editor and select Mtree from the tree type dropdown
2. Add a Tree Mesher node (Shift+A)
3. Add a Trunk node and connect Tree Mesher's output to Trunk's input
4. Add a Branches node and connect Trunk's output to Branches' input
5. Click Generate Tree in the Tree Mesher node
6. (Optional) Click Add Leaves to distribute leaves on the tree

Tip: Select a Branch node and press N to see organized parameter sections with descriptions, plus preset buttons (Oak, Pine, Willow, Random) to quickly configure branch characteristics.

Node Types

Customization

Branch Parameters

Use the Presets section in the inspector panel (N key) to apply Oak, Pine, Willow, or Random configurations, or manually adjust:

• Seed - Controls randomization (same seed = same tree)
• Length/Radius - Size and thickness
• Up Attraction/Gravity - How branches grow relative to gravity
• Split - Probability and angle of branch splitting
• Phyllotaxis - Spiral angle between branches (137.5 is the golden angle)
• Crown Shape - Control tree silhouette (Cylindrical, Conical, Spherical, Flame, etc.)

Crown Shape

Crown Shape controls branch lengths based on height, creating realistic tree silhouettes. Available in the Branch node inspector panel under "Crown Shape":

Enable Preview in Viewport to visualize the envelope. See Crown Shape Guide for details.

Growth Parameters (L-system)

• Iterations - Number of growth cycles
• Apical Dominance - How much the main stem suppresses side branches
• Grow/Split/Cut Thresholds - Control branching behavior
• Gravitropism - Response to gravity direction

Leaf Generation

Mtree generates fully procedural 3D leaves from math — no hand-modeling or textures needed. Each leaf is built through a pipeline:

1. Shape — The outline is created using the Superformula, a single equation that can produce round, pointed, heart-shaped, or star-like forms by adjusting a few parameters.
2. Edge detail — Teeth, scallops, or lobes are added to the outline to match real leaf margin types (serrate, dentate, crenate, lobed).
3. Vein network — Veins grow using space colonization, which scatters "growth hormone" points across the leaf and lets veins grow toward them — producing realistic branching patterns that fill the available space.
4. Surface curvature — The flat mesh is bent with midrib curvature, cross-cupping, edge curl, and raised ridges along vein paths.

Species presets (Oak, Maple, Birch, Willow, Pine) combine these parameters to match real leaves. See the Leaf Generation Guide for a full walkthrough.

Leaf Distribution

After generating a tree, click "Add Leaves" in Tree Mesher to configure:

• Density - Leaves per area
• Max Radius - Only place leaves on thin branches
• Scale/Rotation Variation - Natural randomness
• Leaf Object - Use a custom leaf mesh

Pivot Painter 2.0 Export (UE5)

Export hierarchical wind animation data for Unreal Engine 5:

1. Generate a tree using the Tree Mesher node
2. In the Node Editor, add an Export > Pivot Painter node
3. Connect your Tree Mesher output to the Pivot Painter node
4. Set the export path and click Export

This creates two EXR textures and a UV2 layer compatible with Epic's PivotPainter2FoliageShader material function.

See UE5 Material Setup Guide for detailed import and material configuration instructions.

Note: Currently only Unreal Engine 5 export is fully tested. I am working towards testing properly in Unity

Development

This project uses modern Python tooling:

• uv - Fast Python package manager (used in CI)
• Ruff - Fast Python linter and formatter
• pre-commit - Git hooks for code quality
• clang-format - C++ code formatting

To set up the development environment:

# Install pre-commit hooks (requires uv)
uvx pre-commit install

See CONTRIBUTING.md for full development setup and build instructions.

Contributing

For detailed build instructions, architecture overview, and C++ library usage, see CONTRIBUTING.md.

License

• Blender addon: GPLv3
• Core library: MIT

Credits

Maintainer: GoodPie