7.7 KiB
7.7 KiB
CSG_Blockout
A high-performance, modernized 3D level blockout and rapid prototyping plugin designed specifically for Godot 4.7.
Installation
Option 1: Godot AssetLib (Recommended)
- Open Godot 4.7 and navigate to the AssetLib tab at the top of the editor.
- Search for
CSG Blockout, download, and install it into your project. - Or view it directly on the web: Godot AssetLib - CSG_Blockout.
Option 2: GitHub Releases (.zip)
- Download the latest release
.zipfrom the Releases page. - Extract the archive and copy the
addons/csg_blockoutdirectory into your Godot project'saddons/folder.
Option 3: Git Clone
Clone the repository directly into your project's addons/ directory:
git clone https://github.com/qwqzhanqwq/Godot-CSG-Blockout.git addons/csg_blockout
Enable the Plugin
In Godot, go to Project -> Project Settings -> Plugins, find CSG_Blockout, and check the Enable checkbox.
Quick Start
- Invoke 3D Pie Menu: Press
Shift + Ain the 3D viewport to open the vector radial menu directly at your cursor. Quickly create primitives or switch CSG operations (Union / Intersection / Subtraction) using mouse gestures. - Use the Viewport Sidebar: The left sidebar provides one-click creation for 6 standard shapes. It automatically adds nodes as children when selecting a
CSGCombiner3D, or as adjacent siblings when selecting standard shapes. - Procedural World-Aligned Grid: Switch between Light Grid, Dark Grid, or Orange Accent presets. Select multiple CSG nodes in the tree or viewport and click "Apply Material to Selected" to batch-assign without texture distortion.
- Bake to Permanent Nodes: When a
CSGRepeater3DorCSGSpreader3Dis selected, click Bake in the 3D header toolbar to detach generated instances into permanent scene nodes.
For a complete visual walkthrough and performance optimization workflow, check the Quick Start & Advanced Workflow Tutorial (TUTORIAL_EN.md).
Key Features
- Vector 3D Pie Menu: Triggered with
Shift + Ain the 3D viewport. Hierarchical radial navigation for instant CSG operations and primitive placement with central deadzone controls and full Undo/Redo integration. - Smart Viewport Sidebar: Quick-access toolbar for 6 primitive shapes and boolean modes. Auto-hides when no CSG nodes are selected to keep the viewport clean.
- Procedural World-Aligned Triplanar Shader: World-space UV projection guarantees consistent 1m x 1m grid scaling without stretching during node transformations or CSG boolean cuts. Built-in screen-derivative anti-aliasing.
- Ready-to-Use Material Presets & Batch Assignment: Pre-configured measurement materials (Light, Dark, Accent, Unshaded) with one-click batch application to all selected CSG nodes.
- Parametric Array Generator (CSGRepeater3D): Strategy-pattern array distributions (Grid, Circular, Spiral, and 3D Noise volume sampling) with randomized rotation and scale.
- Volume Collision Scatterer (CSGSpreader3D): Scatter instances within any Godot
Shape3Dvolume without overlaps. Powered by a custom\mathcal{O}(1)3D Spatial Hash Grid algorithm. - GDScript 2.0 Static Typing & Multi-Language Support: Fully typed codebase, atomic
EditorUndoRedoManagersupport (Ctrl + Z/Ctrl + Y), and built-in 7-language (i18n) localization (English, Simplified Chinese, Japanese, Korean, Spanish, Portuguese, Russian).
Relationship to CSG Toolkit & Architectural Evolution
This plugin originated from the excellent open-source CSG Toolkit created by LuckyTepot. While the original toolkit demonstrated the value of in-viewport CSG authoring, modern Godot 4.7 workflows demanded higher performance, procedural tooling, and cleaner architecture.
CSG_Blockout was re-engineered by qwqzhanqwq as a ground-up architectural overhaul:
| Dimension | Original CSG Toolkit | CSG_Blockout (This Project) |
|---|---|---|
| Engine Core | Early Godot 4.x, dynamically typed | Tailored for Godot 4.7+, full GDScript 2.0 static typing & ClassDB validation |
| Interaction | Viewport sidebar only | 3D Viewport Radial Pie Menu (Shift + A) + Smart Sidebar dual workflow |
| Procedural Tools | Static manual primitive placement | Parametric Repeaters (CSGRepeater3D) + Volume Spreaders (CSGSpreader3D) |
| Scatter Algorithm | No collision avoidance or naive \mathcal{O}(N^2) |
Custom 3D Spatial Hash Grid (\mathcal{O}(1) lookup), real-time calculation |
| Materials | Basic default materials | World-aligned triplanar anti-aliased shader + 5 presets + 1-click batch assign |
| Robustness | Basic editor state | Atomic EditorUndoRedoManager integration with strict editor/runtime decoupling |
| Localization | English only | Native multi-language support (English, Simplified Chinese, Japanese, Korean, Spanish, Portuguese, Russian) |
Documentation
English
- Main Documentation (README.md): Plugin overview, installation, feature highlights, and credits.
- Quick Start & Advanced Workflow Tutorial (TUTORIAL_EN.md): Step-by-step guide, visual demonstrations, and the critical CSG-to-Mesh baking workflow.
- Architecture Design & Technical Internals (ARCHITECTURE.md): Spatial Hash Grid algorithm derivation, design patterns, and complete API specifications.
简体中文 (Simplified Chinese)
- 中文主说明文档 (README_CN.md): 插件核心特性、安装指南、快速上手与演进历史。
- 快速上手与高级工作流教程 (TUTORIAL_CN.md): 完整图文与动图教学、白盒烘焙与性能优化方案。
- 架构设计与技术内幕 (ARCHITECTURE_CN.md): 3D 空间哈希数学推导、策略模式架构解析与全量 API 字典。
Credits & License
- Original Concept & Layout Design: LuckyTepot (CSG Toolkit, Copyright (c) 2023).
- Architecture Overhaul, 3D Pie Menu, Spatial Hash Grid, Array/Scatter Systems & GDScript 2.0 Rewrite: qwqzhanqwq (Copyright (c) 2026).
Licensed under the MIT License.