Pascal Editor 项目概览：从 Node Schema 到 Scene Registry 的架构全景图

Pascal Editor 项目概览从 Node Schema 到 Scene Registry 的架构全景图【免费下载链接】editorCreate and share 3D architectural projects.项目地址: https://gitcode.com/GitHub_Trending/editor93/editorPascal Editor 是一款基于 React Three Fiber 与 WebGPU 构建的3D 建筑编辑器让你可以在浏览器里创建、编辑并分享建筑项目。本文带你快速看懂它的核心架构从数据层的Node Schema节点模式到状态层的 Scene Store再到渲染层的Scene Registry场景注册表一张图理清这个开源项目的分层设计 ️。一图看懂项目分层结构Pascal Editor 采用 Turborepo 单仓monorepo组织每个包职责单一、边界清晰包职责一句话说明pascal-app/core节点 Schema、场景状态、注册表契约数据的大脑所有包共享pascal-app/viewer3D 渲染运行时只负责把场景画出来pascal-app/editor编辑工具与 UI 组件在 viewer 之上叠加交互能力pascal-app/nodes内置节点定义与渲染器墙、门、家具等内置内容pascal-app/cli本地安装与进程管理一条命令启动编辑器pascal-app/mcpMCP 服务与场景存储让 AI 助手操作你的建筑场景上面这张沙发模型就是编辑器里一个典型的Item 节点——它由 GLB 模型 位置数据构成正是后文要讲的节点体系的具象体现。什么是 Node Schema用一份 Zod 模式定义所有 3D 对象Node节点是描述整个 3D 场景的数据原语。墙、门、地板、家具、灯具……在 Pascal Editor 里全部是节点。所有节点都继承自同一个BaseNode基础结构id带类型前缀的自动 ID例如wall_abc123type类型标识用于类型安全分发parentId父节点引用构成层级关系visible、metadata可见性与任意元数据每种节点类型都用Zod 模式定义在packages/core/src/schema/nodes/目录下共 60 多种节点类型。以墙为例其模式定义在 wall.ts包含start、end、thickness、height等字段以及踢脚线、护墙板等建筑参数。这种设计带来两个新手友好的好处创建节点必须走.parse()——模式自动校验数据、填充默认值、生成规范 ID杜绝手搓对象的低级错误旧工程永远能加载——新增字段必须带.default()重命名字段则要走集中的迁移逻辑见 node-schemas.md 的Schema Evolution章节几个月前保存的场景今天打开依然正常渲染。节点层级遵循真实的建筑语义Site场地 └── Building建筑 └── Level楼层 ├── Wall墙→ Door / Window门窗 ├── Slab楼板、Ceiling天花、Roof屋顶 └── Zone区域、Item家具值得注意节点并非嵌套树存储而是扁平字典Recordid, Node父子关系靠parentId表达——这为后文的 O(1) 快速查找打下了基础。Scene Store用 Zustand 管理整个场景状态场景数据由useScene这个 Zustand Store 统一管理核心源码见 use-scene.tsnodes全部节点rootNodeIds顶层节点即场地dirtyNodes待系统更新的脏节点集合createNode / updateNode / deleteNodeCRUD 操作配合两个中间件Persist自动保存到 IndexedDB瞬时节点除外Zundo提供 50 步的撤销/重做历史脏节点机制是性能关键当你修改一面墙的厚度只有这面墙被标记为 dirty渲染循环每帧只重算脏节点的几何而不是整个场景。改一个抽屉不会拖累整栋楼。Scene Registry让任意节点 ID 一步直达 3D 对象这是整个架构中最巧妙的部分。渲染时每个节点的渲染器都会通过useRegistry钩子把自己的 Three.js 对象注册到全局注册表中sceneRegistry ├── nodes: Map节点ID, Object3D ← ID 直达 3D 对象 └── byType: { wall: Setid, item: Setid, … } ← 按类型批量遍历实现见 scene-registry.ts一个RevisionedMap追踪修改版本号byType用 Proxy 惰性创建——任何节点类型包括插件贡献的新类型首次访问即自动注册无需硬编码清单。它的价值在于O(1) 查找选择管理器选中某节点时直接sceneRegistry.nodes.get(id)拿到 3D 对象做高亮描边不必遍历场景树系统想处理所有墙时直接遍历byType.wall集合即可注册/清理全部由useRegistry自动完成挂载即注册、卸载即移除。规则很严格每个节点 ID 只注册一次、系统永远实时读取不缓存结果、只有useRegistry能写入注册表。完整规范见 scene-registry.md。Pascal Editor 中的矩形灯盘 3D 节点渲染从用户点击到 3D 更新完整数据流把前三层串起来一次交互的完整链路如下用户操作点击/拖拽如用 WallTool 画墙工具处理工具组件调用useScene.createNode()写入数据Store 响应节点入库节点被标记为 dirtyReact 重渲染NodeRenderer 按类型分发渲染器创建占位对象并useRegistry注册系统更新System 在渲染循环中发现脏节点通过 Scene Registry 拿到 3D 对象重新生成几何如带门窗开洞的墙体清理标记dirty 标记清除等待下一帧工具层与数据层之间还有一条清晰的边界工具只做输入翻译和状态写入几何生成全部委托给 core 的 SystemsWallSystem、SlabSystem、RoofSystem 等。详见 systems.md 与 tools.md。三个 Zustand Store 各司其职Store所在包管理内容useScenecore节点数据、CRUD、脏节点、持久化与撤销useViewerviewer当前选中项、楼层显示模式堆叠/爆炸/单独、相机模式useEditorapps/editor活动工具、面板状态、编辑器偏好这种数据 / 展示 / 编辑三分的状态设计正是 viewer 能与 editor 解耦、插件可以独立扩展的根基。如何本地跑起来无需克隆仓库Node.js 22.13 下一条命令即可启动编辑器与配套的 MCP 服务npx pascal-app/cli editor项目数据保存在~/.pascal/data/pascal.db。如果要从源码开发克隆仓库git clone https://gitcode.com/GitHub_Trending/editor93/editor后在根目录执行bun installbun dev打开http://localhost:3002即可务必从根目录启动以启用所有包的热重载。写在最后Pascal Editor 的架构可以浓缩成一句话Zod 模式定义数据Schema→ Zustand 管理状态Store 脏节点→ 注册表直连渲染Registry→ 系统增量更新几何Systems。每一层都只做一件事、可独立测试这也是它既能作为完整产品使用、又能把 core/viewer 作为 npm 包供第三方集成的原因。想深入阅读推荐按顺序浏览 wiki/architecture/README.md 中的架构文档layers→systems→renderers→tools→scene-registry配合本文的全景图你会对这个 3D 建筑编辑器的骨架有清晰的把握 。【免费下载链接】editorCreate and share 3D architectural projects.项目地址: https://gitcode.com/GitHub_Trending/editor93/editor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考