CSG_Blockout Logo

CSG_Blockout

Docs English 文档 简体中文 教程 简体中文 架构 技术内幕

Godot 引擎 Godot AssetLib 开源协议: MIT

专为 Godot 4.7 打造的高性能、现代化的 3D 关卡白盒（Blockout）与快速原型设计插件。

--- ## 安装指南 ### 途径 1：Godot AssetLib 官方资产库（推荐） 1. 在 Godot 4.7 编辑器顶部点击 **AssetLib (资产库)** 选项卡。 2. 搜索 `CSG Blockout`，点击下载并安装到项目中。 3. 也可通过网页版资产库直达：[Godot AssetLib - CSG_Blockout](https://store.godotengine.org/asset/qwqzhanqwq/csg-blockout/)。 ### 途径 2：GitHub Releases 发布包 1. 前往项目的 [Releases 页面](https://github.com/qwqzhanqwq/Godot-CSG-Blockout/releases) 下载最新的 `.zip` 归档文件。 2. 解压后将 `addons/csg_blockout` 文件夹复制到你的 Godot 项目根目录下的 `addons/` 目录中。 ### 途径 3：Git 源码克隆 在你的 Godot 项目根目录下执行以下命令： ```bash git clone https://github.com/qwqzhanqwq/Godot-CSG-Blockout.git addons/csg_blockout ``` ### 启用插件 打开 Godot 编辑器，依次点击 **项目 (Project) -> 项目设置 (Project Settings) -> 插件 (Plugins)**，找到 **CSG_Blockout** 并勾选 **启用 (Enable)**。 --- ## 快速上手 1. **呼出 3D 轮盘**：在 3D 视口中按下快捷键 `Shift + A`，在光标所在位置唤出矢量轮盘菜单（Pie Menu），顺着手势快速创建基础 CSG 形状或切换布尔操作（并集 / 交集 / 差集）。 2. **使用视口侧边栏**：视口左侧边栏提供立方体、球体、圆柱体等一键创建按钮；选中 `CSGCombiner3D` 时自动挂载为子节点，选中独立形状时自动作为同级兄弟节点插入。 3. **程序化世界对齐网格**：侧边栏内置灰白网格、深灰网格、橙色高亮网格等材质通道，支持多选节点后一键批量赋予，物体随意缩放旋转均不拉伸纹理。 4. **一键烘焙与导出**：选中 `CSGRepeater3D` 或 `CSGSpreader3D` 时，顶部工具栏会出现专属按钮，点击 **烘焙 (Bake)** 即可将其固化为常规场景节点。 > 完整图文搭建教程与性能优化最佳实践，请查阅 [快速上手与高级工作流教程 (TUTORIAL_CN.md)](TUTORIAL_CN.md)。 --- ## 核心功能特性 - **矢量 3D 轮盘菜单 (3D Pie Menu)**：在 3D 视口通过 `Shift + A` 顺发呼出，多层级布尔运算与几何形状无缝联动，支持中心死区回退与全流程 Undo/Redo。 - **智能工作流侧边栏**：集成 6 种标准 CSG 几何体快捷创建、3 种布尔操作即时切换，无 CSG 节点选中时自动隐藏，保持视口清爽。 - **程序化三平面世界网格 Shader**：摒弃传统 UV 依赖，基于世界空间坐标投影，严格保持真实世界比例尺寸（1m x 1m），内置抗锯齿算法。 - **开箱即用材质预设与批量赋予**：预置浅色、深色、重点强调等度量材质，支持视口中框选多个 CSG 节点一键应用。 - **参数化阵列生成器 (CSGRepeater3D)**：采用策略模式设计，支持网格阵列、环形阵列、螺旋阵列与 3D 噪声体域采样，支持旋转与缩放随机化。 - **物理体积防重叠散布系统 (CSGSpreader3D)**：支持以任意 Godot `Shape3D` 为空间边界进行无重叠填充，采用 $O(1)$ 空间哈希网格算法，彻底避免编辑态卡死。 - **工程级强类型与多语言支持**：全线基于 GDScript 2.0 静态强类型开发，无缝对接 `EditorUndoRedoManager`，内置支持中、英、日、韩、西、葡、俄 7 种语言 (i18n) 界面即时热切换。 --- ## 与 CSG Toolkit 的关系与全面演进 本项目灵感源自 **LuckyTepot** 开发的优秀开源插件 [CSG Toolkit](https://godotengine.org/asset-library/asset/3057)。原版插件验证了在 Godot 视口内集成快速 CSG 工具栏的卓越体验。 为了满足现代化高精度关卡设计与 Godot 4.7 架构标准，本项目由 [qwqzhanqwq](https://github.com/qwqzhanqwq) 对其进行了**彻底推倒式的架构重写与全方位扩展**： | 维度 | 原版 CSG Toolkit | CSG_Blockout (本项目) | | :--- | :--- | :--- | | **引擎架构** | 面向早期 Godot 4.x，弱类型脚本 | **深度适配 Godot 4.7+**，全线 GDScript 2.0 强类型标注与 ClassDB 校验 | | **核心交互** | 仅依赖视口固定侧边栏 | **3D 视口矢量轮盘 (Shift+A Pie Menu) + 智能侧边栏** 双工作流 | | **程序化生成** | 仅支持基础静态图元放置 | **参数化阵列 (Repeater) + 碰撞体体积散布 (Spreader)** | | **散布避障算法** | 无避障或朴素 $O(N^2)$ 遍历循环 | **自研 3D 空间哈希网格算法 ($O(1)$ 复杂度)**，数百实例实时生成不卡顿 | | **材质系统** | 依赖基础内置着色器 | **程序化世界对齐三平面网格 Shader** + 5 组预设 + 一键批量赋予 | | **工程健壮性** | 基础编辑态支持 | **全流程原子级 EditorUndoRedoManager 接入**，严格的编辑器/运行时环境隔离 | | **国际化** | 仅支持单语言 | **原生多语言支持**（中、英、日、韩、西、葡、俄 7 语），自动跟随编辑器语言偏好并支持独立覆盖 | --- ## 文档导航 ### 简体中文 - [主说明文档 (README_CN.md)](README_CN.md)：插件核心特性、安装指南、快速上手与演进历史。 - [快速上手与高级工作流教程 (TUTORIAL_CN.md)](TUTORIAL_CN.md)：手把手教学、动图演示与关键的白盒烘焙性能优化方案。 - [架构设计与技术内幕 (ARCHITECTURE_CN.md)](ARCHITECTURE_CN.md)：3D 空间哈希数学推导、策略模式架构解析与全量 API 字典。 ### English - [Main Documentation (README.md)](README.md): Plugin overview, installation, feature highlights, and credits. - [Quick Start & Advanced Workflow Tutorial (TUTORIAL_EN.md)](TUTORIAL_EN.md): Step-by-step guide, visual demonstrations, and the critical CSG-to-Mesh baking workflow. - [Architecture Design & Technical Internals (ARCHITECTURE.md)](ARCHITECTURE.md): Spatial Hash Grid algorithm derivation, design patterns, and complete API specifications. --- ## 致谢与开源协议 - **原始概念与界面原型灵感**：[LuckyTepot](https://github.com/LuckyTepot) (CSG Toolkit, Copyright (c) 2023). - **架构重构、3D 轮盘、空间哈希优化、阵列/散布系统与 GDScript 2.0 重写**：[qwqzhanqwq](https://github.com/qwqzhanqwq) (Copyright (c) 2026). 本项目基于 [MIT License](LICENSE) 开源发布。