7.7 KiB
7.7 KiB
CSG_Blockout
专为 Godot 4.7 打造的高性能、现代化的 3D 关卡白盒（Blockout）与快速原型设计插件。
安装指南
途径 1：Godot AssetLib 官方资产库（推荐）
- 在 Godot 4.7 编辑器顶部点击 AssetLib (资产库) 选项卡。
- 搜索
CSG Blockout，点击下载并安装到项目中。 - 也可通过网页版资产库直达：Godot AssetLib - CSG_Blockout。
途径 2：GitHub Releases 发布包
- 前往项目的 Releases 页面 下载最新的
.zip归档文件。 - 解压后将
addons/csg_blockout文件夹复制到你的 Godot 项目根目录下的addons/目录中。
途径 3：Git 源码克隆
在你的 Godot 项目根目录下执行以下命令：
git clone https://github.com/qwqzhanqwq/Godot-CSG-Blockout.git addons/csg_blockout
启用插件
打开 Godot 编辑器，依次点击 项目 (Project) -> 项目设置 (Project Settings) -> 插件 (Plugins)，找到 CSG_Blockout 并勾选 启用 (Enable)。
快速上手
- 呼出 3D 轮盘：在 3D 视口中按下快捷键
Shift + A，在光标所在位置唤出矢量轮盘菜单（Pie Menu），顺着手势快速创建基础 CSG 形状或切换布尔操作（并集 / 交集 / 差集）。 - 使用视口侧边栏：视口左侧边栏提供立方体、球体、圆柱体等一键创建按钮；选中
CSGCombiner3D时自动挂载为子节点，选中独立形状时自动作为同级兄弟节点插入。 - 程序化世界对齐网格：侧边栏内置灰白网格、深灰网格、橙色高亮网格等材质通道，支持多选节点后一键批量赋予，物体随意缩放旋转均不拉伸纹理。
- 一键烘焙与导出：选中
CSGRepeater3D或CSGSpreader3D时，顶部工具栏会出现专属按钮，点击 烘焙 (Bake) 即可将其固化为常规场景节点。
完整图文搭建教程与性能优化最佳实践，请查阅 快速上手与高级工作流教程 (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。原版插件验证了在 Godot 视口内集成快速 CSG 工具栏的卓越体验。
为了满足现代化高精度关卡设计与 Godot 4.7 架构标准，本项目由 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)：插件核心特性、安装指南、快速上手与演进历史。
- 快速上手与高级工作流教程 (TUTORIAL_CN.md)：手把手教学、动图演示与关键的白盒烘焙性能优化方案。
- 架构设计与技术内幕 (ARCHITECTURE_CN.md)：3D 空间哈希数学推导、策略模式架构解析与全量 API 字典。
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.
致谢与开源协议
- 原始概念与界面原型灵感：LuckyTepot (CSG Toolkit, Copyright (c) 2023).
- 架构重构、3D 轮盘、空间哈希优化、阵列/散布系统与 GDScript 2.0 重写：qwqzhanqwq (Copyright (c) 2026).
本项目基于 MIT License 开源发布。