Pascal Editor：基于 WebGPU 的开源 3D 建筑编辑器技术解析

Pascal Editor：基于 WebGPU 的开源 3D 建筑编辑器技术解析

一个采用现代 Web 技术栈构建的高性能建筑可视化与编辑平台

项目概述

Pascal Editor 是由 pascalorg 组织开发的开源 3D 建筑编辑器，旨在提供一个无需本地安装、完全基于浏览器的建筑设计与可视化解决方案。该项目采用 WebGPU 渲染技术结合 React Three Fiber 构建三维场景，实现了接近原生应用的渲染性能与交互体验。

技术架构

Monorepo 项目结构

项目采用 Turborepo 管理的 Monorepo 架构，实现模块化设计与职责分离：

editor/
├── apps/
│ └── editor/ # Next.js 16 应用层
├── packages/
│ ├── core/ # @pascal-app/core
│ └── viewer/ # @pascal-app/viewer
└── tooling/ # 构建工具链配置

模块职责划分：

这种架构设计支持核心包的独立发布与复用，开发者可通过 npm 引入渲染引擎或核心逻辑构建定制化应用。

技术栈概览

核心技术概念

1. 节点模型（Node Schema）

节点是场景数据的基本单元，所有节点类型均继承 BaseNode：

interface BaseNode {
id: string // 自动生成，类型前缀（如 "wall_abc123"）
type: string // 类型鉴别器
parentId: string | null // 父节点引用
visible: boolean // 可见性控制
camera?: Camera // 可选相机位置
metadata?: JSON // 扩展元数据
}

节点层级结构：

Site（场地）
└── Building（建筑）
└── Level（楼层）
├── Wall → Item（门、窗附属）
├── Slab（地板）
├── Ceiling → Item（灯具附属）
├── Roof（屋顶）
├── Zone（功能区域）
├── Scan（3D 扫描参考）
└── Guide（2D 参考图）

节点存储采用 扁平字典结构（Record<id, Node>），而非嵌套树形结构。父子关系通过 parentId 与 children 数组定义，简化了遍历与查询操作。

2. 场景状态管理

场景由 Zustand Store 管理，集成持久化与时间旅行（undo/redo）中间件：

interface SceneState {
nodes: Record<string, AnyNode> // 全部节点
rootNodeIds: string[] // 顶层节点（Site）
dirtyNodes: Set<string> // 待更新节点集合

createNode(node, parentId): void
updateNode(id, updates): void
deleteNode(id): void
}

中间件配置：

• Persist Middleware：自动持久化至 IndexedDB，排除瞬态节点
• Temporal Middleware（Zundo）：50 步历史记录，支持撤销/重做

3. 场景注册表（Scene Registry）

注册表维护节点 ID 与 Three.js Object3D 的映射，实现高效的空间对象查询：

interface SceneRegistry {
nodes: Map<string, Object3D> // ID → 3D Object
byType: {
wall: Set<string>
item: Set<string>
zone: Set<string>
// … 按类型分组
}
}

渲染器通过 useRegistry Hook 注册引用：

const ref = useRef<Mesh>(null!)
useRegistry(node.id, 'wall', ref)

此机制允许系统直接访问 3D 对象，无需遍历场景图。

4. 系统（Systems）

系统是运行于渲染循环（useFrame）中的 React 组件，负责几何生成与变换更新。系统仅处理被标记为"脏"的节点。

核心系统列表：

处理流程：

useFrame(() => {
for (const id of dirtyNodes) {
const obj = sceneRegistry.nodes.get(id)
const node = useScene.getState().nodes[id]

updateGeometry(obj, node) // 更新几何与变换
dirtyNodes.delete(id) // 清除脏标记
}
})

5. 脏节点机制（Dirty Nodes）

节点变更时自动加入 dirtyNodes 集合，系统在每帧检查并仅对脏节点执行几何重建：

// 自动标记：createNode/updateNode/deleteNode 触发脏标记
useScene.getState().updateNode(wallId, { thickness: 0.2 })
// → wallId 加入 dirtyNodes
// → WallSystem 下一帧重建几何
// → wallId 从 dirtyNodes 移除

此增量更新策略避免了全量重建的计算开销，显著提升性能。

6. 事件总线（Event Bus）

组件间通信采用基于 mitt 的类型化事件发射器：

// 节点事件
emitter.on('wall:click', (event: NodeEvent) => { … })
emitter.on('item:enter', (event: NodeEvent) => { … })
emitter.on('zone:context-menu', (event: NodeEvent) => { … })

// 网格事件
emitter.on('grid:click', (event) => { … })

// 事件载荷结构
interface NodeEvent {
node: AnyNode
position: [number, number, number] // 世界坐标
localPosition: [number, number, number] // 局部坐标
normal?: [number, number, number] // 法向量
stopPropagation: () => void
}

7. 空间网格管理器（Spatial Grid Manager）

提供碰撞检测与放置验证接口：

spatialGridManager.canPlaceOnFloor(levelId, position, dimensions, rotation)
spatialGridManager.canPlaceOnWall(wallId, t, height, dimensions)
spatialGridManager.getSlabElevationAt(levelId, x, z)

工具层调用此接口验证物品放置位置合法性，并计算地板高程。

数据流架构

用户交互（click, drag）
↓
Tool Handler 处理
↓
useScene.createNode() / updateNode()
↓
节点更新 → React 重渲染 NodeRenderer → useRegistry 注册 3D Object
↓
脏节点标记 → System 检测（useFrame） → 几何重建 → 清除脏标记

编辑器扩展架构

编辑器层在 Viewer 基础上扩展以下能力：

工具系统

选择管理器

支持层级化导航的选择策略：

Site → Building → Level → Zone → Items

每层级定义独立的 hover/click 行为策略。

Store 分层

功能清单

已实现

• 墙壁绘制：点击拖拽绘制，自动斜接处理
• 门窗放置：CSG Boolean 切割生成真实开口
• 区域划分：功能区域标记
• 家具/灯具定位：3D 物品库，支持墙/天花板/地板附着
• 多楼层管理：堆叠/爆炸/单层三种显示模式
• 撤销/重做：Zundo 实现 50 步历史记录
• 数据持久化：IndexedDB 自动保存

项目状态

当前版本 v0.5.1（2026年4月），处于活跃开发阶段：

• 27 个开放 Issue
• 持续的 Commit 活动
• npm 包定期发布
• Discord 社区运营

快速开始

开发环境搭建

# 克隆仓库
git clone https://github.com/pascalorg/editor.git

# 安装依赖
bun install

# 启动开发服务器（含包监视模式）
bun dev

# 访问 http://localhost:3000

注意：运行 bun dev 需在根目录执行，确保包监视器启动，实现 packages/core 与 packages/viewer 的热重载。

生产构建

# 全量构建
turbo build

# 单包构建
turbo build –filter=@pascal-app/core

npm 包使用

npm install @pascal-app/core # 核心逻辑
npm install @pascal-app/viewer # 3D 渲染引擎

关键文件路径

适用场景分析

推荐应用场景

当前局限

技术亮点总结

参考资源