@ubuilder-ai/core

Core library for Pascal 3D building editor.

Installation

npm install @ubuilder-ai/core

Peer Dependencies

npm install react three @react-three/fiber @react-three/drei

What's Included

• Node Schemas - Zod schemas for all building primitives (walls, slabs, items, etc.)
• Scene State - Zustand store with IndexedDB persistence and undo/redo
• Registry Contracts - Plugin and node-definition APIs shared by renderers and editor tools
• Opaque Extension Slots - Generic context and geometry metadata carriers; floor-plan presentation semantics live in @ubuilder-ai/floorplan-contract
• Scene Registry - Fast lookup from node IDs to Three.js objects
• Spatial Grid - Collision detection and placement validation
• Event Bus - Typed event emitter for inter-component communication
• Asset Storage - IndexedDB-based file storage for user-uploaded assets

Usage

import { useScene, WallNode } from '@ubuilder-ai/core'

// Create a wall
const wall = WallNode.parse({
  start: [0, 0],
  end: [5, 0],
  height: 3,
  thickness: 0.2,
})

useScene.getState().createNode(wall, parentLevelId)

// Subscribe to scene changes
function MyComponent() {
  const nodes = useScene((state) => state.nodes)
  const walls = Object.values(nodes).filter(n => n.type === 'wall')

  return <div>Total walls: {walls.length}</div>
}

Node Types

• SiteNode - Root container
• BuildingNode - Building within a site
• LevelNode - Floor level
• WallNode - Vertical wall with optional openings
• SlabNode - Floor slab
• CeilingNode - Ceiling surface
• RoofNode - Roof geometry
• ZoneNode - Spatial zone/room
• ItemNode - Furniture, fixtures, appliances
• ScanNode - 3D scan reference
• GuideNode - 2D guide image reference

Built-in Node Definitions

Core contains the schemas, scene state, and registry contracts. The built-in node definitions, renderers, geometry builders, tools, and systems ship in @ubuilder-ai/nodes:

import { loadPlugin } from '@ubuilder-ai/core'
import { builtinPlugin } from '@ubuilder-ai/nodes'

await loadPlugin(builtinPlugin)

Load the plugin before mounting @ubuilder-ai/viewer. See the @ubuilder-ai/viewer quick start for a React example.

License

MIT