Aedifex

Open-source 3D architectural editor with AI design assistant

Design buildings with natural language — AI creates walls, places doors & windows, arranges furniture, and previews changes in real-time. Powered by WebGPU.

English | 中文

https://github.com/user-attachments/assets/6c819726-65f4-45c6-903e-fa5c364a6340

Features

Structure & Layout

• Detailed stairs — Winder steps, construction details and coordinated railings.

• Wall System — Draw walls with automatic mitering, adjustable thickness and height. Walls snap to a 0.5m grid for precision.

• Doors & Windows — Place doors and windows on walls with configurable dimensions, swing direction, and hinge side.

• Zones — Rooms are auto-detected from wall boundaries. Zones display area, shape analysis, and spatial metadata.

• Multi-Level — Stack, explode, or solo levels. Each level maintains independent floor plans.

• Slabs, Ceilings & Roofs — Draw floor plates, ceilings, and roof segments with polygon-based geometry.

• Lean-to Extensions & Drainage — Attach lean-to roof extensions and generate coordinated gutters and downspouts.

• Custom Blocks — Edit mesh faces, edges, loops, transforms, and per-face materials with Blender-style controls.

Furniture & Items

• Catalog — Built-in furniture catalog with sofas, tables, chairs, beds, bookshelves, lamps, trees, and more.
• Smart Placement — Collision detection, wall-snap alignment, and zone-boundary clamping ensure items stay within rooms.
• Interactive Items — Toggle lights, adjust lamp brightness, and control interactive elements.

Materials

• 10 Presets — White, brick, concrete, wood, glass, metal, plaster, tile, marble, and custom.
• Custom Properties — Color, roughness, metalness, opacity, transparency per node.
• All Node Types — Apply materials to walls, slabs, doors, windows, ceilings, and roofs.

Viewing & Navigation

• Views — Keep 3D, 2D and plugin views in one or two panes, with persistent layouts and sidebar preferences.

• Street View — First-person walkthrough mode. WASD to move, mouse to look, Q/E to float. Explore your designs from inside.

• Dark / Light Theme — Toggle between dark and light viewport themes.

• Compass HUD — Always-visible cardinal direction indicator.

• Camera Controls — Orbit, pan, zoom with mouse or trackpad. Optimized for Mac touchpad (two-finger pan + pinch zoom + right-click rotate).

• Capture Layers — Display transport-neutral static or live room models, point clouds, surface meshes, and device motion.

Export

• GLB — Standard glTF binary format for web and game engines.
• STL / 3MF — Print-ready whole-model or per-level packages with optional shell compilation and plinths.
• OBJ — Universal exchange format.

AI Design Assistant

• Natural Language — Describe what you want: "Create a 5m x 4m room and furnish it as a bedroom."
• 16 Tools — Add/remove/move furniture, create walls, place doors & windows, update wall height/door width/window size, batch operations, propose multiple placement options, and ask clarifying questions.
• Ghost Preview — See AI suggestions as transparent previews before confirming.
• Agentic Loop — AI iterates on results, auto-corrects positions for collision and zone boundaries, and asks clarifying questions when the request is ambiguous.
• Catalog Matching — Fuzzy name matching with shape-variant warnings (e.g., warns if you ask for a round table but only rectangular is available).

---

Quick Start

Requirements

• Node.js 22.23.4+ (22.x), 24.22.1+ (24.x), or 26.12.1+
• pnpm 9+ (npm install -g pnpm)
• A WebGPU-capable browser: Chrome 113+, Edge 113+, or Firefox Nightly

Setup

# Clone
git clone https://github.com/TangSY/aedifex.git
cd aedifex

# Install dependencies
pnpm install

# Start dev server (all packages + editor)
pnpm dev

# Open http://localhost:3002

AI Assistant Configuration (Optional)

The AI design assistant requires an OpenAI-compatible API key. Without it, the editor works normally but the AI panel will be disabled.

1. Copy the example config:

cp .env.example apps/editor/.env.local

2. Edit apps/editor/.env.local and fill in your API key:

# Required — your OpenAI API key (or any OpenAI-compatible provider)
AI_API_KEY=sk-your-api-key-here

# Optional — change the base URL for compatible providers (e.g., Azure, local LLM)
AI_BASE_URL=https://api.openai.com/v1

# Optional — model selection (defaults shown)
AI_CHAT_MODEL=gpt-4o
AI_SUMMARIZE_MODEL=gpt-4o-mini

Note: The AI assistant calls OpenAI-compatible APIs directly from the server. Your API key is never exposed to the browser. Any provider that implements the OpenAI chat completions API is supported (OpenAI, Azure OpenAI, Anthropic via proxy, local Ollama, etc.).

---

Controls

Mouse

Action	Input
Select	Left click
Pan	Middle click drag, or Space + left click
Rotate	Right click drag
Zoom	Scroll wheel

Trackpad (Mac)

Action	Gesture
Pan	Two-finger drag
Zoom	Pinch
Rotate	Right-click drag (two-finger tap + drag)

Street View Mode

Action	Input
Move	WASD
Look	Mouse
Float up/down	Q / E
Exit	Escape

---

Architecture

Turborepo monorepo with reusable packages plus the editor app:

aedifex/
├── apps/editor/         # Next.js 16 application (entry point)
├── packages/core/       # Schema, state (Zustand), systems, spatial queries
├── packages/viewer/     # 3D rendering (React Three Fiber + WebGPU)
├── packages/editor/     # Editor UI: tools, panels, selection, AI assistant
├── packages/nodes/      # Built-in registry node definitions and renderers
├── packages/cli/        # Local editor runtime and MCP process manager
├── packages/mcp/        # MCP server for natural-language scene control
├── packages/ifc-converter/ # IFC conversion logic
├── packages/plugin-trees/  # In-repository Nature plugin
└── packages/ui/         # Shared shadcn/ui primitives

Package	Responsibility
core	Node schemas (Zod), scene store with undo/redo (Zundo), geometry systems, spatial grid, event bus
viewer	Renderers, camera, lighting, post-processing, level/scan/guide systems
core/capture	Versioned capture manifests, normalized streams, and transport-neutral sources
viewer/capture	Capture runtime with room-model, motion, point-cloud, and surface-mesh layers
editor	Tools, panels, selection manager, AI assistant, custom camera controls
nodes	Built-in node schemas, tools, renderers, geometry, and systems
cli	Installs and manages the local editor runtime and MCP service
mcp	Model Context Protocol server exposing scene operations to Claude Desktop / Cursor
ifc-converter	Converts IFC data into the Aedifex scene graph
plugin-trees	First-party Nature plugin and host panel
ui	Shared shadcn/ui primitives consumed by the editor

Scene Data Model

Nodes are stored in a flat dictionary with parentId references:

Site → Building → Level → Wall → Door / Window
                        → Zone
                        → Slab / Ceiling / Roof
                        → Item (furniture)

Key Files

Path	Description
packages/core/src/schema/	Node type definitions (Zod schemas)
packages/core/src/schema/material.ts	Material system (10 presets + custom properties)
packages/core/src/store/use-scene.ts	Scene state store
packages/core/src/systems/	Geometry generation systems
packages/viewer/src/components/renderers/	Node renderers
packages/viewer/src/components/viewer/	Main Viewer component
packages/editor/src/components/tools/	Editor tools (wall, zone, item, slab)
packages/editor/src/components/ai/	AI assistant (prompt, agent loop, validators)
packages/editor/src/components/editor/first-person-controls.tsx	Street view mode
packages/editor/src/components/editor/export-manager.tsx	Scene export (GLB, STL, OBJ)

Tech Stack

Layer	Technology
Rendering	Three.js (WebGPU), React Three Fiber, Drei
Framework	React 19, Next.js 16
State	Zustand + Zundo (undo/redo)
Schema	Zod
Geometry	three-bvh-csg (Boolean operations)
Tooling	TypeScript 5, Turborepo, pnpm

---

Contributing

See CONTRIBUTING.md for development guidelines.

# Build all packages
turbo build

# Build specific package
turbo build --filter=@aedifex/core

---

Acknowledgments

Aedifex is built upon Pascal Editor by Pascal Group Inc., licensed under MIT. We extend our gratitude to the original authors for their excellent work on the 3D architectural editor core.

---

License

MIT

Self-hosting and authored geometry

See SETUP.md for password-protected self-hosting and runtime URL configuration. Container builds belong in CI or a dedicated build environment.

Authored geometry supports Three.js and Blender bpy source formats. Python compilation is not enabled by default: a host must explicitly provide a Blender builder. Stored artifacts can render without executing their source.