一个基于 Three.js 的实时程序化地牢生成器，支持确定性种子、Delaunay/MST 图布局、房间语义、五种主题以及自定义泛光/移轴渲染管线。

项目概览

majidmanzarpour/threejs-procedural-dungeon 是一个开源的 JavaScript 项目，利用 Three.js 在浏览器中实时生成程序化地牢。它不仅仅是一个迷宫生成器，更是一套完整的地牢创作系统：从图论布局到房间语义分配，从五种视觉主题到定制化的后期特效管线。项目目前拥有 295 颗星，代码质量高，文档清晰，适合游戏开发者、图形学爱好者以及 Three.js 学习者深入研究。

痛点与解决方案

痛点

• 传统地牢设计依赖手工铺设，耗时耗力，且难以生成大量多样化的关卡。
• 现有的程序化生成算法（如随机 BSP、随机行走）往往缺乏结构控制，生成的房间布局散乱、连通性差。
• 多数地牢生成器输出的是 2D 网格或简单 3D 模型，缺乏完整的渲染管线与视觉风格支持。
• 游戏开发者需要快速原型，但缺乏开箱即用、可扩展的 Web 端地牢生成方案。

解决方案

本项目提供了一整套端到端的解决方案：

• 确定性种子：相同的种子始终生成相同的地牢，方便调试与复现。
• Delaunay 三角剖分 + 最小生成树 (MST)：将随机放置的房间通过 Delaunay 三角网连接，再用 MST 提取主干路径，保证所有房间连通且没有冗余循环。
• 房间语义：为每个房间分配标签（如“出生点”、“Boss房”、“宝箱房”），支持基于规则的游戏逻辑扩展。
• 五种主题：包括“古墓”、“地下洞穴”、“冰窟”、“熔岩”和“神殿”，通过材质、颜色和光照快速切换视觉风格。
• 定制渲染管线：内置泛光（Bloom）和移轴（Tilt-shift）效果，无需额外后期库，直接输出电影级画面。

安装与使用

环境要求

• Node.js >= 16.x
• 现代浏览器（支持 WebGL2）

安装步骤

bash

克隆仓库

git clone https://github.com/majidmanzarpour/threejs-procedural-dungeon.git
cd threejs-procedural-dungeon

安装依赖

npm install

启动开发服务器

npm run dev

浏览器打开 http://localhost:5173 即可看到实时生成的地牢，并可通过界面参数调整种子、主题、房间数量等。

核心代码示例

javascript
import { DungeonGenerator } from './src/DungeonGenerator.js';
import { ThemeManager } from './src/ThemeManager.js';

// 初始化生成器，指定种子
const generator = new DungeonGenerator({ seed: 42 });

// 设置参数：房间数量、最小房间尺寸、最大房间尺寸
generator.setParameters({ roomCount: 30, minRoomSize: 5, maxRoomSize: 15 });

// 执行生成
const dungeonData = generator.generate();

// 获取房间语义列表
console.log(dungeonData.rooms);
// 输出示例：
// [
// { id: 0, position: {x:0, z:0}, size: {w:10, d:8}, semantic: 'spawn' },
// { id: 1, position: {x:15, z:20}, size: {w:12, d:10}, semantic: 'boss' },
// ...
// ]

// 切换主题
const themeManager = new ThemeManager();
themeManager.setTheme('lava'); // 可选：'tomb', 'cave', 'ice', 'lava', 'temple'

// 渲染场景（内部使用 Three.js）
const scene = generator.buildScene(themeManager);

核心亮点深度解析

1. 图论驱动的布局算法

传统程序化地牢常使用 BSP（二叉空间分割）或随机放置后暴力连接。本项目采用更优雅的图论方法：

1. 房间放置：在二维平面上随机放置矩形房间，使用简单碰撞检测避免重叠。
2. Delaunay 三角剖分：以房间中心为顶点，构建 Delaunay 三角网，确保每个房间与最近的邻居连接。
3. 最小生成树 (MST)：从三角网中提取 MST，保留最少的边以保证所有房间连通。这一步消除了冗余通道，使地牢结构紧凑。
4. 走廊生成：对 MST 中的每条边，使用 A* 或简单 L 形走廊连接房间门。

这种方法的优势在于：

• 确定性：相同种子产生相同三角网和 MST。
• 可控性：通过调整房间数量、尺寸和 MST 权重，可以生成从紧凑迷宫到开放大厅的不同风格。
• 可扩展性：可以在 MST 基础上随机添加额外边，制造循环路径，增加探索自由度。

2. 房间语义系统

每个房间在生成时被赋予一个语义标签，目前支持：

• spawn：玩家起始点
• boss：Boss 房间（通常最大、最远）
• treasure：宝箱房（含奖励）
• normal：普通战斗/探索房间
• secret：隐藏房间（需要特定条件进入）

语义分配基于规则：例如，boss 房间总是离 spawn 最远（通过 MST 路径距离计算）。开发者可以轻松扩展语义类型，并在游戏逻辑中根据标签触发事件。

3. 五种主题的视觉实现

主题不仅仅是换色，而是完整的材质、光照和雾效组合：

主题	主色调	光照特点	雾效	特殊元素
古墓 (tomb)	土黄、暗金	暖色点光源	浅黄色薄雾	石柱、火把
地下洞穴 (cave)	深灰、暗绿	冷色环境光	深灰色浓雾	钟乳石、苔藓
冰窟 (ice)	冰蓝、白色	高光、反射	淡蓝色雾	冰柱、霜面
熔岩 (lava)	红、橙、黑	动态火焰光	深红色雾	岩浆池、焦痕
神殿 (temple)	白、金、蓝	明亮全局光	无雾	雕像、符文

主题通过 ThemeManager 统一管理，材质使用 Three.js 的 MeshStandardMaterial，支持 PBR 属性（粗糙度、金属度）。

4. 定制后期渲染管线

项目内建了一个轻量级后期管线，无需引入 PostProcessing 库：

• 泛光 (Bloom)：基于亮度的模糊叠加，使发光物体（如熔岩、魔法符文）产生辉光效果。
• 移轴 (Tilt-shift)：模拟微距摄影的景深效果，通过垂直渐变模糊实现，让地牢看起来像微缩模型。

管线使用 Three.js 的 EffectComposer 和自定义着色器，性能优化良好，在中等配置 GPU 上可保持 60fps。

5. 交互式控制面板

开发服务器包含一个基于 dat.GUI 的实时控制面板，支持：

• 调整种子（数字输入或随机按钮）
• 切换主题
• 调节房间数量、尺寸范围
• 开关 Bloom / Tilt-shift 效果
• 导出当前地牢的 JSON 数据

适用场景

1. 游戏关卡原型设计：独立游戏开发者可快速生成多种地牢布局，测试玩法机制。
2. 图形学教学：演示 Delaunay 三角剖分、MST、程序化生成等算法在 3D 场景中的实际应用。
3. Three.js 学习：项目代码结构清晰，包含 Three.js 核心概念（场景、材质、光照、后期）的实践范例。
4. 艺术创作：利用移轴效果和多种主题，生成风格化的 3D 场景截图或动画。
5. AI 训练数据生成：导出地牢 JSON 数据，用于强化学习中的迷宫导航任务。

同类项目对比

特性	本项目	dungeon-generator (npm)	procgen-dungeon (Python)
渲染引擎	Three.js (WebGL)	无（仅输出 JSON）	无（仅输出 ASCII/JSON）
布局算法	Delaunay + MST	BSP	随机行走 + 手动规则
房间语义	✅ 内置分类	❌	❌
主题系统	5种完整主题	❌	❌
后期特效	Bloom + Tilt-shift	❌	❌
实时交互	✅ 控制面板	❌	❌
确定性种子	✅	✅	✅
语言	JavaScript	JavaScript	Python

本项目在可视化丰富度、实时交互和即用性上明显优于同类工具，特别适合 Web 端游戏和演示场景。

总结与展望

threejs-procedural-dungeon 是一个小而精的项目，它巧妙地将图论算法、语义化设计和电影级渲染融为一体。对于游戏开发者，它提供了一个可立即运行的 Web 地牢原型；对于学习者，它是理解程序化生成与 Three.js 管线的绝佳案例。

未来可能的扩展方向：

• 支持更多主题（如“水下宫殿”、“机械要塞”）
• 集成物理引擎（如 Cannon.js）实现可交互的门、陷阱
• 导出为 glTF 格式，用于 Unity/Unreal 导入
• 添加多人同步功能

无论你是想快速生成游戏关卡，还是深入钻研程序化生成算法，这个项目都值得一试。

---

项目链接：https://github.com/majidmanzarpour/threejs-procedural-dungeon