CSG Blockout: Rapid Prototyping & Advanced Workflow Tutorial

Read this in other languages: 简体中文 | Back to Main Docs | Architecture & Internals

1. Basics: Understanding CSG
2. Workflow: Rapid Blockout using Sidebar and Pie Menu
3. Advanced: The Array and Scatter Systems
4. Ultimate Technique: Performance Optimization Workflow (Must Read)

1. Basics: Understanding CSG

CSG (Constructive Solid Geometry) is a modeling technique that allows you to construct complex 3D models using boolean operations on simple geometric shapes (e.g., cubes, spheres, cylinders).

In Godot, CSG is a powerful tool for level designers to block out levels or create rapid prototypes. Its core functionality is based on three boolean operations:

Union: Merges two geometries into a single solid shape.
Intersection: Retains only the overlapping portion of two geometries.
Subtraction: Carves out the volume of one geometry from another.

Using these simple operations, you can quickly cut out doors, dig tunnels, or assemble complex architectural structures directly in the engine, completely bypassing external software like Blender.

The CSG_Blockout plugin is designed to eliminate tedious hierarchy management, providing an ultra-fast, WYSIWYG (What You See Is What You Get) experience. Whether you prefer mouse clicks or keyboard shortcuts, the plugin adapts to your workflow.

Recommended Blockout Process

Create the Root Node: Add a CSGCombiner3D node to your scene. This will act as the root container for your geometry block. All subsequently added basic shapes will merge under this node.
Select the Target: Make sure this CSGCombiner3D node (or any CSG shape inside it) is selected in the Scene Tree.
Summon the Menu:
- Method A (Pie Menu): Move your mouse over the 3D viewport and press Shift + A. A radial Pie Menu will appear at your cursor. Simply flick your mouse in the direction of your desired boolean operation and primitive shape.
- Method B (Sidebar): Use the newly added plugin sidebar on the left side of the 3D viewport. First, click the bottom icons to select a boolean operation (Union, Intersection, or Subtraction), and then click the top primitive shape icons (e.g., cube, sphere) to instantly add a CSG node with that operation.
Procedural Grid Materials & Scale Metrics:
- World-Aligned Triplanar Grid: The sidebar includes three procedural grid material presets (Light Grid, Dark Grid, Orange Accent Grid), along with Unshaded (None) and Custom Material slots. Powered by triplanar projection, the grid pattern stays perfectly aligned in world coordinates without texture stretching, making character scale and spatial distance estimation effortless.
- Apply Material to Selection: Select one or more CSGShape3D nodes in the viewport or scene tree, then click the "Apply Material to Selected" button at the bottom of the material group to batch-assign the active preset. Fully integrated with Ctrl + Z Undo/Redo.
Smart Contextual Hierarchy Placement:
- Selecting a CSGCombiner3D (or CSGRepeater3D / CSGSpreader3D) automatically places new nodes as children.
- Selecting a standard CSGShape3D (e.g., CSGBox3D) automatically places new nodes as siblings directly following the selected node, eliminating tedious scene-tree dragging.
Tweak and Adjust: Drag the handles directly in the viewport to resize and position. The plugin fully supports Ctrl+Z, so feel free to experiment without fear of breaking things.

3. Advanced: The Array and Scatter Systems

1. The Array System (CSGRepeater3D)

CSGRepeater3D allows you to rapidly generate duplicated geometries using specific mathematical patterns. It is perfect for creating stairs, fences, pillars, or circular structures.

Workflow:

Create Node: Add a CSGRepeater3D node to your scene.
Set Template: You can either add a basic CSG primitive (e.g., CSGBox3D) as a direct child of the Repeater, or assign a target node to the Template Node property in the Inspector.
Select a Pattern: In the Inspector, locate the Pattern property, create a new resource, and choose your desired pattern strategy:
- CSGGridPattern: Grid Array, easily adjust count and spacing along the X/Y/Z axes.
- CSGCircularPattern: Circular Array, distribute items in a ring by configuring radius and count.
- CSGSpiralPattern: Spiral Array, adds a height offset to circular arrays, perfect for spiral staircases.
- CSGNoisePattern: Noise Array, organic distribution driven by 3D noise functions.

2. The Scatter System (CSGSpreader3D)

CSGSpreader3D integrates a proprietary Spatial Hash Grid algorithm. It randomly scatters geometry within any 3D collision shape efficiently and without overlaps. Even with hundreds of scattered instances, the O(1) collision avoidance ensures the editor remains completely lag-free.

Workflow:

Create Node: Add a CSGSpreader3D node and assign it a child node to use as the scatter template.
Define Scatter Volume: Assign a Shape3D (such as BoxShape3D or SphereShape3D) in the properties. Objects will only be spawned strictly within this shape's boundaries.
Adjust Density & Randomness:
- Min Distance: This is the most crucial property. It dictates the scatter density. A larger value yields sparse distribution, while a smaller value makes it dense.
- Combine this with Random Rotation and Random Scale settings to instantly generate chaotic yet organic scene blockouts, like rocky terrains or rubble.

4. Ultimate Technique: Performance Optimization Workflow (Must Read)

While CSG nodes are incredibly convenient during the editing phase, retaining a large number of them during the final game runtime will cause severe performance degradation (FPS drops) due to real-time boolean calculations. When a specific room or architectural block is "finalized and won't be changed," you must convert it into a static mesh and collision body.

Standard 1-Click Conversion Process:

Finalize Blockout: Select the top-level CSGCombiner3D node that contains all your operations.
Bake to Mesh: In the editor's top menu bar, click the contextual options for CSGCombiner3D and select "Bake to MeshInstance3D".
Generate Collision: Select the newly generated MeshInstance3D, click "Mesh" in the top menu bar, and select "Create Trimesh Static Body". This will automatically generate a highly accurate collision shape that perfectly wraps your geometry.
Clean up Structure: Move the generated MeshInstance3D (along with its internal CollisionShape3D) under a clean StaticBody3D hierarchy.
Delete Original CSG: Delete the original CSGCombiner3D node and all its children. At this point, the heavy boolean calculations are completely unloaded, leaving you with an ultra-performant static game asset with perfect collisions!

Warning

Note: Before deleting the CSG nodes, it is highly recommended to save the original CSG structure as a separate scene file (e.g., CSG_Source.tscn) or keep a backup, so you can easily modify the level structure later.

7.7 KiB Raw Blame History