RoofSystem - Pascal Editor

Overview

The RoofSystem is a React component that processes dirty roof nodes and generates 3D gable roof geometry. It supports:

Parametric gable roofs with independent left/right widths
Automatic pitch calculation from rise, run, and material thicknesses
Multi-layer construction (cover layer + structure layer)
Eave and rake overhangs with configurable dimensions
Gable walls at front and back ends

The system runs in a useFrame hook (default priority), ensuring roofs update after core systems.

Location

~/workspace/source/packages/core/src/systems/roof/roof-system.tsx

How It Works

Processing Pipeline

Monitor dirty nodes

The system watches the dirtyNodes set for nodes with type === 'roof'.

Generate roof geometry

For each dirty roof:

Solve pitch angle from height, width, and layer thicknesses
Generate profiles for left and right sides
Extrude profiles along ridge length
Create gable walls at front and back
Merge all geometries into single mesh

Update mesh

Dispose old geometry and replace it with new geometry, updating position and rotation.

Clear dirty flag

Once the mesh is updated, the node is removed from dirtyNodes.

Geometry Generation

The generateRoofGeometry() function builds roof geometry in these steps:

Solve pitch angle using solvePitch() to account for material thicknesses
Generate side profiles for left and right slopes (cover, structure, walls)
Create THREE.Shape from each profile
Extrude shapes along ridge length with appropriate offsets
Add gable walls at front and back ends
Merge geometries into single buffer geometry
Center at X=0 by translating -ridgeLength/2

Props

The RoofSystem component has no props. It reads state from the Zustand store:

dirtyNodes

Set<AnyNodeId>

Set of node IDs that need geometry updates

nodes

Record<AnyNodeId, AnyNode>

All nodes in the scene graph

Dependencies

RoofNode Schema

The system processes RoofNode objects with these properties:

string

required

Unique roof identifier

position

[number, number, number]

default:"[0, 0, 0]"

Center position of the roof (Y typically 0) [x, y, z]

rotation

number

default:"0"

Rotation around Y axis in radians

length

number

default:"4"

Length of the roof along the ridge direction in meters

height

number

default:"1.5"

Height of the roof peak from the base in meters

leftWidth

number

default:"1.5"

Horizontal width of the left slope (from ridge to eave) in meters

rightWidth

number

default:"1.5"

Horizontal width of the right slope (from ridge to eave) in meters

External Systems

Scene Registry (sceneRegistry.nodes): Maps node IDs to THREE.js meshes

Roof Geometry Constants (roof-system.tsx:10-17)

The system uses these architectural constants:

const THICKNESS_A = 0.05        // Roof cover thickness (5cm)
const THICKNESS_B = 0.1         // Structure thickness (10cm)
const ROOF_COVER_OVERHANG = 0.05 // Extension of cover past structure (5cm)
const EAVE_OVERHANG = 0.4       // Horizontal eave overhang (40cm)
const RAKE_OVERHANG = 0.3       // Overhang at gable ends (30cm)
const WALL_THICKNESS = 0.2      // Gable wall thickness (20cm)
const BASE_HEIGHT = 0.5         // Base height / knee wall / truss heel (50cm)

Pitch Calculation Algorithm

solvePitch() Function (roof-system.tsx:65-79)

The pitch angle is solved analytically to account for material thicknesses:

function solvePitch(rise: number, run: number, thickA: number, thickB: number): number {
  // Solves: run * tan(a) + (ThickA + ThickB)/cos(a) = rise
  const T = thickA + thickB
  const R = Math.sqrt(run * run + rise * rise)
  if (R <= T) return Math.atan2(rise, run) * 0.5  // Fallback
  
  const phi = Math.atan2(rise, run)
  const shift = Math.asin(T / R)
  
  return phi - shift
}

This ensures the roof peak reaches exactly height despite material thicknesses adding vertical dimension.

Roof Layers

The roof consists of multiple layers per side:

Layer A: Roof Cover (roof-system.tsx:150-156)

Outer weatherproofing layer:

Thickness: THICKNESS_A (5cm)
Extends beyond structure by ROOF_COVER_OVERHANG (5cm)
Includes eave overhang extension

Layer B: Structure (roof-system.tsx:158-164)

Structural layer (sheathing/decking):

Thickness: THICKNESS_B (10cm)
Extends to eave overhang but not beyond
Sits below cover layer

Side Walls (roof-system.tsx:166-175)

Vertical gable walls:

Thickness: WALL_THICKNESS (20cm)
Height: From base (0) to sloped top
Positioned at left/right edges

Gable Fill (roof-system.tsx:177-191)

Triangular gable end fill:

C1: Upper triangle (from base height to ridge)
C2: Lower rectangle (from 0 to base height)
Created at front and back ends

Profile Generation

getSideProfile() Function (roof-system.tsx:103-194)

Generates 2D profiles for one side (left or right):

Calculate geometry

const rise = Math.max(0, roofHeight - BASE_HEIGHT)
const run = width - WALL_THICKNESS / 2
const angle = solvePitch(rise, run, THICKNESS_A, THICKNESS_B)

Compute ridge heights

const ridgeUnderY = BASE_HEIGHT + run * tan(angle)
const ridgeInterfaceY = ridgeUnderY + THICKNESS_B / cos(angle)
const ridgeTopY = ridgeInterfaceY + THICKNESS_A / cos(angle)

Calculate eave points

const overhangDx = EAVE_OVERHANG * cos(angle)
const eaveTopZ = width + WALL_THICKNESS/2 + overhangDx
const eaveTopY = ridgeTopY - eaveTopZ * tan(angle)

Build point arrays

Return profiles for cover (A), structure (B), side walls, and gable fill (C1, C2).

Extrusion and Assembly (roof-system.tsx:196-272)

Extrusion Lengths

const lengths = {
  A: ridgeLength + 2 * RAKE_OVERHANG + 2 * ROOF_COVER_OVERHANG + WALL_THICKNESS,
  B: ridgeLength + 2 * RAKE_OVERHANG + WALL_THICKNESS,
  Side: ridgeLength + WALL_THICKNESS,
  Gable: WALL_THICKNESS,
}

Extrusion Offsets

const offsets = {
  A: -RAKE_OVERHANG - ROOF_COVER_OVERHANG - WALL_THICKNESS / 2,
  B: -RAKE_OVERHANG - WALL_THICKNESS / 2,
  Side: -WALL_THICKNESS / 2,
  GableFront: -WALL_THICKNESS / 2,
  GableBack: ridgeLength - WALL_THICKNESS / 2,
}

createPart() Helper (roof-system.tsx:239-245)

const createPart = (shape: THREE.Shape, depth: number, xOffset: number) => {
  const geo = new THREE.ExtrudeGeometry(shape, { depth, bevelEnabled: false })
  geo.rotateY(Math.PI / 2)  // Extrusion goes along X axis
  geo.translate(xOffset, 0, 0)
  return geo
}

Geometry Merging (roof-system.tsx:274-302)

All parts are merged into a single BufferGeometry:

Extract position, normal, and UV attributes from each part
Concatenate into flat arrays
Create new BufferGeometry with merged attributes
Compute vertex normals
Dispose individual geometries

Roof Centering (roof-system.tsx:313-314)

The final geometry is centered at X=0:

mergedGeometry.translate(-ridgeLength / 2, 0, 0)

This matches the old geometry centering behavior and makes rotation around the Y-axis intuitive.

Usage in Viewer

import { RoofSystem } from '@pascal/core/systems/roof/roof-system'
import { useScene } from '@pascal/core/store/use-scene'

function createRoof() {
  const { addNode, markDirty } = useScene.getState()
  
  const roof = {
    id: 'roof_1',
    type: 'roof',
    parentId: 'level_2',
    position: [0, 3.0, 0],  // Y = top of walls
    rotation: 0,            // Aligned with level
    length: 10,             // 10m ridge
    height: 2.5,            // 2.5m peak height
    leftWidth: 4,           // 4m left slope
    rightWidth: 4,          // 4m right slope (symmetric)
  }
  
  addNode(roof)
  markDirty(roof.id)
}

function Viewer() {
  return (
    <Canvas>
      {/* Other scene content */}
      <RoofSystem />
    </Canvas>
  )
}

The system automatically:

Monitors the dirtyNodes store
Updates roofs when they’re marked dirty
Generates complete roof geometry with all layers

Asymmetric Roofs

The system supports asymmetric gable roofs with different left/right widths:

const asymmetricRoof = {
  length: 8,
  height: 2.0,
  leftWidth: 3,   // Shorter left slope
  rightWidth: 5,  // Longer right slope (shed-style)
}

The ridge is always at X=0 (centered), and slopes extend different distances left and right.

Coordinate System

Roofs use level coordinates:

X-axis: Along ridge direction (length)
Y-axis: Vertical (height)
Z-axis: Perpendicular to ridge (width)

The roof’s position is at the base center, with rotation around the Y-axis.

Overhang Details

Eave Overhang

Horizontal extension beyond walls at the eaves (low sides):

Default: 0.4m (40cm)
Measured horizontally (not along slope)
Provides weather protection for walls

Rake Overhang

Extension beyond gable walls at the ends:

Default: 0.3m (30cm)
Extends ridge length
Creates shadow lines on gable ends

Roof Cover Overhang

Cover layer extends beyond structure:

Default: 0.05m (5cm)
Provides drip edge
Prevents water infiltration at edges

Integration with Other Systems

Wall System

Roofs typically sit on top of walls:

Roof position.y = top of walls
Gable walls align with building walls below
Base height (BASE_HEIGHT) creates attic knee wall

Level System

Roofs are parented to the top level of a building:

Upper floor level contains roof nodes
Roof elevation matches ceiling height of top floor

Performance Notes

Only updates dirty roofs (not all roofs every frame)
Merges all roof parts into single geometry for efficient rendering
Disposes intermediate geometries to prevent memory leaks
Pre-computes all profiles before extrusion
Reuses shape objects for left/right gable walls

WallSystem - Manages wall geometry that roofs sit on
CeilingSystem - Manages ceiling geometry below roofs
SlabSystem - Similar polygon-based geometry system

Core Package

Node Schemas

Systems

Viewer Package

​Overview

​Location

​How It Works

​Processing Pipeline

​Geometry Generation

​Props

​Dependencies

​RoofNode Schema

​External Systems

​Roof Geometry Constants (roof-system.tsx:10-17)

​Pitch Calculation Algorithm

​solvePitch() Function (roof-system.tsx:65-79)

​Roof Layers

​Layer A: Roof Cover (roof-system.tsx:150-156)

​Layer B: Structure (roof-system.tsx:158-164)

​Side Walls (roof-system.tsx:166-175)

​Gable Fill (roof-system.tsx:177-191)

​Profile Generation

​getSideProfile() Function (roof-system.tsx:103-194)

​Extrusion and Assembly (roof-system.tsx:196-272)

​Extrusion Lengths

​Extrusion Offsets

​createPart() Helper (roof-system.tsx:239-245)

​Geometry Merging (roof-system.tsx:274-302)

​Roof Centering (roof-system.tsx:313-314)

​Usage in Viewer

​Asymmetric Roofs

​Coordinate System

​Overhang Details

​Eave Overhang

​Rake Overhang

​Roof Cover Overhang

​Integration with Other Systems

​Wall System

​Level System

​Performance Notes

​Related

Build docs developers (and LLMs) love

Overview

Location

How It Works

Processing Pipeline

Geometry Generation

Props

Dependencies

RoofNode Schema

External Systems

Roof Geometry Constants (roof-system.tsx:10-17)

Pitch Calculation Algorithm

solvePitch() Function (roof-system.tsx:65-79)

Roof Layers

Layer A: Roof Cover (roof-system.tsx:150-156)

Layer B: Structure (roof-system.tsx:158-164)

Side Walls (roof-system.tsx:166-175)

Gable Fill (roof-system.tsx:177-191)

Profile Generation

getSideProfile() Function (roof-system.tsx:103-194)

Extrusion and Assembly (roof-system.tsx:196-272)

Extrusion Lengths

Extrusion Offsets

createPart() Helper (roof-system.tsx:239-245)

Geometry Merging (roof-system.tsx:274-302)

Roof Centering (roof-system.tsx:313-314)

Usage in Viewer

Asymmetric Roofs

Coordinate System

Overhang Details

Eave Overhang

Rake Overhang

Roof Cover Overhang

Integration with Other Systems

Wall System

Level System

Performance Notes

Related