Pascal Editor 整合 是做什麼的?
概述
Pascal Editor (pascalorg/editor) 是一個基於 React Three Fiber 和 WebGPU 建構的開源 3D 建築編輯器。它提供了基於節點的場景圖、Zustand 狀態管理,以及適合 AI 驅動建築生成的系統架構。此技能涵蓋了用於建立、操作和匯出建築幾何形狀的核心 API。
指示
快速開始
npx create-next-app@latest my-building-app
cd my-building-app
npm install @pascal-app/core @pascal-app/ui @react-three/fiber @react-three/drei three zustand
節點階層
Pascal 使用型別化節點的樹狀結構:
Site -> Building -> Level -> Wall -> Opening (door/window)
-> Slab (floor/ceiling)
-> Zone (room boundary)
-> Item (furniture, fixture)
每個節點都包含:id(UUID)、type、parentId、children(子節點 ID)、props(型別特定屬性)以及 dirty(標記需要重建)。
Zustand 狀態儲存庫
import { useScene, useViewer, useEditor } from '@pascal-app/core'
// useScene -- 場景圖(節點、關係)
const { nodes, createNode, updateNode, deleteNode } = useScene()
// useViewer -- 視窗狀態(相機、選取)
const { selectedIds, camera, setSelection } = useViewer()
// useEditor -- 工具模式和 UI 狀態
const { activeTool, setTool, history } = useEditor()
建立帶有開口的牆壁
const scene = useScene.getState()
// 外牆:長 4.5 公尺,厚 200 公釐,天花板高 2.7 公尺
const wall = await scene.createNode({
type: 'wall',
props: {
start: { x: 0, y: 0 }, end: { x: 4.5, y: 0 },
thickness: 0.20, height: 2.7,
isExterior: true, material: 'masonry',
}
}, levelId)
// 新增窗戶:寬 1.2 公尺,窗臺高度 900 公釐
await scene.createNode({
type: 'item',
props: {
itemType: 'window', wallId: wall.id,
offsetFromStart: 1.5, width: 1.2, height: 1.2, sillHeight: 0.9,
}
}, wall.id)
// 新增門:寬 900 公釐
await scene.createNode({
type: 'item',
props: {
itemType: 'door', wallId: wall.id,
offsetFromStart: 3.0, width: 0.9, height: 2.1, sillHeight: 0,
}
}, wall.id)
建立樓層與房間
const level = await scene.createNode({
type: 'level',
props: { name: 'Ground Floor', elevation: 0, height: 2.7, index: 0 }
}, buildingId)
// 樓板
await scene.createNode({
type: 'slab',
props: {
polygon: [{ x: 0, y: 0 }, { x: 10, y: 0 }, { x: 10, y: 8 }, { x: 0, y: 8 }],
thickness: 0.25, isRoof: false,
}
}, level.id)
// 用於標籤和面積計算的房間區域
await scene.createNode({
type: 'zone',
props: {
name: 'Living Room', roomType: 'living',
polygon: [{ x: 0.1, y: 0.1 }, { x: 5.4, y: 0.1 }, { x: 5.4, y: 7.9 }, { x: 0.1, y: 7.9 }],
}
}, level.id)
將場景匯出為 JSON
function exportScene(): BuildingExport {
const { nodes } = useScene.getState()
const allNodes = Object.values(nodes)
const site = allNodes.find(n => n.type === 'site')
const building = allNodes.find(n => n.type === 'building')
const levels = allNodes
.filter(n => n.type === 'level' && n.parentId === building.id)
.sort((a, b) => a.props.elevation - b.props.elevation)
return {
units: 'meters',
site: { width: site.props.width, depth: site.props.depth },
building: {
levels: levels.map(level => ({
name: level.props.name,
elevation: level.props.elevation,
height: level.props.height,
walls: getChildrenByType(level.id, 'wall', allNodes),
rooms: getChildrenByType(level.id, 'zone', allNodes),
}))
}
}
}
使用 React Three Fiber 進行渲染
import { Canvas } from '@react-three/fiber'
import { PascalScene, PascalCamera, PascalControls } from '@pascal-app/ui'
export function BuildingViewer() {
return (
<Canvas camera={{ position: [0, 20, 20], fov: 45 }}>
<PascalScene />
<PascalCamera />
<PascalControls />
<ambientLight intensity={0.5} />
<directionalLight position={[10, 20, 10]} castShadow />
</Canvas>
)
}
網格對齊
Pascal 預設使用 100 公釐(0.1 公尺)網格:
const snapToGrid = (value: number, gridSize = 0.1) =>
Math.round(value / gridSize) * gridSize
範例
範例 1:建立 10 公尺 x 8 公尺的地面樓層
建立一個完整的地面樓層,包含外牆、將客廳與臥室分開的內部分隔牆,以及適當的開口:
- 建立 elevation 為 0、高度 2.7 公尺的樓層節點
- 建立樓板:10 公尺 x 8 公尺多邊形,厚度 0.25 公尺
- 建立 4 面外牆(厚 0.20 公尺,磚石):北(10 公尺)、東(8 公尺)、南(10 公尺)、西(8 公尺)
- 在 x=5.5 處新增內部分隔牆(厚 0.10 公尺,木材),貫穿整個深度
- 在北牆新增入口門:1.0 公尺 x 2.1 公尺,偏移 3.5 公尺
- 在東牆新增窗戶:兩個 1.2 公尺 x 1.2 公尺,窗臺高度 0.9 公尺,偏移 1.2 公尺和 4.5 公尺
- 建立區域:客廳(5.3 公尺 x 7.8 公尺 = 41.3 平方公尺)、臥室區域(4.3 公尺 x 7.8 公尺 = 33.5 平方公尺)
- 匯出為 JSON,根據
architectural-dimensions規則進行驗證
範例 2:註冊自訂驗證系統
建立一個每當牆壁節點變更時檢查牆壁厚度的系統:
import { registerSystem, useScene } from '@pascal-app/core'
registerSystem({
name: 'wall-validator',
nodeTypes: ['wall'],
priority: 100,
process(dirtyNodes) {
for (const node of dirtyNodes) {
const { thickness, isExterior, height } = node.props
if (isExterior && thickness < 0.14)
console.warn(`Wall ${node.id}: exterior ${thickness}m < 0.14m minimum`)
if (height < 2.1)
console.warn(`Wall ${node.id}: height ${height}m < 2.1m minimum`)
}
}
})
這會在牆壁節點被標記為髒(dirty)時自動執行,並在幾何系統重建網格之前執行。
指南
- 所有尺寸單位均為公尺——Pascal 內部使用公制
- 所有節點的 CRUD 操作使用
useScene,選取/相機使用useViewer,工具使用useEditor - 將座標對齊到 0.1 公尺網格,以獲得乾淨的幾何形狀
- 牆壁厚度:外牆 0.20 公尺,內部分隔牆 0.10 公尺
- 門的窗臺高度始終為 0(地面樓層);窗戶窗臺高度預設為 0.9 公尺
- 註冊 priority > 50 的自訂系統,以便在幾何重建(0-50)之前執行
- 結合
architectural-dimensions技能以進行真實世界的尺寸驗證 - 關鍵套件:
@pascal-app/core、@pascal-app/ui、@react-three/fiber、three、zustand - GitHub: github.com/pascalorg/editor