Nodes

Understanding the node hierarchy, BaseNode structure, and type-safe node schemas

Overview

Nodes are the data primitives that describe the 3D scene in Pascal Editor. All nodes extend BaseNode and are stored in a flat dictionary structure with parent-child relationships defined via parentId.

BaseNode Structure

All nodes in the scene extend the BaseNode schema defined with Zod:

export const BaseNode = z.object({
  object: z.literal('node').default('node'),
  id: z.string(),              // Auto-generated with type prefix (e.g., "wall_abc123")
  type: nodeType('node'),      // Discriminator for type-safe handling
  name: z.string().optional(),
  parentId: z.string().nullable().default(null),
  visible: z.boolean().optional().default(true),
  camera: CameraSchema.optional(),
  metadata: z.json().optional().default({}),
})

Location: packages/core/src/schema/base.ts:21-30

Core Properties

id · string · required

Auto-generated unique identifier with type prefix (e.g., wall_abc123, item_xyz789)

type · string · required

Node type discriminator used for type-safe handling ('site', 'building', 'level', 'wall', etc.)

parentId · string | null · default: "null"

Reference to parent node ID. Null for root nodes (typically Site nodes).

visible · boolean · default: "true"

Controls whether the node is rendered in the 3D scene.

camera · Camera

Optional saved camera position for this node (used for viewpoint navigation).

metadata · JSON · default: "{}"

Arbitrary metadata object. Use { isTransient: true } to prevent persistence to IndexedDB.

Node Hierarchy

Nodes form a tree structure representing the building hierarchy:

Site
└── Building
    └── Level
        ├── Wall → Item (doors, windows)
        ├── Slab
        ├── Ceiling → Item (lights)
        ├── Roof
        ├── Zone
        ├── Scan (3D reference)
        └── Guide (2D reference)

While nodes form a logical tree, they are stored in a flat dictionary (Record<id, Node>), not a nested structure. Parent-child relationships are defined via parentId and children arrays.

Node Types

The SDK provides type-safe node schemas using Zod’s discriminated union:

export const AnyNode = z.discriminatedUnion('type', [
  SiteNode,
  BuildingNode,
  LevelNode,
  WallNode,
  ItemNode,
  ZoneNode,
  SlabNode,
  CeilingNode,
  RoofNode,
  ScanNode,
  GuideNode,
  WindowNode,
  DoorNode,
])

export type AnyNode = z.infer<typeof AnyNode>
export type AnyNodeType = AnyNode['type']
export type AnyNodeId = AnyNode['id']

Location: packages/core/src/schema/types.ts:16-35

Structural Nodes

SiteNode

Represents a site/property. Root node of the scene hierarchy.

export const SiteNode = BaseNode.extend({
  id: objectId('site'),
  type: nodeType('site'),
  polygon: PropertyLineData.optional().default({
    type: 'polygon',
    points: [
      [-15, -15],
      [15, -15],
      [15, 15],
      [-15, 15],
    ],
  }),
  children: z
    .array(z.discriminatedUnion('type', [BuildingNode, ItemNode]))
    .default([BuildingNode.parse({})]),
})

Location: packages/core/src/schema/nodes/site.ts:21-39

BuildingNode

Represents a building within a site.

export const BuildingNode = BaseNode.extend({
  id: objectId('building'),
  type: nodeType('building'),
  children: z.array(LevelNode.shape.id).default([]),
  position: z.tuple([z.number(), z.number(), z.number()]).default([0, 0, 0]),
  rotation: z.tuple([z.number(), z.number(), z.number()]).default([0, 0, 0]),
})

Location: packages/core/src/schema/nodes/building.ts:6-12

LevelNode

Represents a floor level in a building.

export const LevelNode = BaseNode.extend({
  id: objectId('level'),
  type: nodeType('level'),
  children: z.array(
    z.union([
      WallNode.shape.id,
      ZoneNode.shape.id,
      SlabNode.shape.id,
      CeilingNode.shape.id,
      RoofNode.shape.id,
      ScanNode.shape.id,
      GuideNode.shape.id,
    ])
  ).default([]),
  level: z.number().default(0),
})

Location: packages/core/src/schema/nodes/level.ts:12-18

Building Elements

WallNode

Represents a wall defined by start and end points.

export const WallNode = BaseNode.extend({
  id: objectId('wall'),
  type: nodeType('wall'),
  children: z.array(ItemNode.shape.id).default([]),
  thickness: z.number().optional(),
  height: z.number().optional(),
  start: z.tuple([z.number(), z.number()]),
  end: z.tuple([z.number(), z.number()]),
  frontSide: z.enum(['interior', 'exterior', 'unknown']).default('unknown'),
  backSide: z.enum(['interior', 'exterior', 'unknown']).default('unknown'),
})

start · [number, number] · required

Start point in level coordinate system (2D: x, z)

end · [number, number] · required

End point in level coordinate system (2D: x, z)

thickness · number · default: "0.1"

Wall thickness in meters

height · number · default: "2.5"

Wall height in meters

Location: packages/core/src/schema/nodes/wall.ts:9-22

SlabNode

Represents a floor slab defined by a polygon.

export const SlabNode = BaseNode.extend({
  id: objectId('slab'),
  type: nodeType('slab'),
  polygon: z.array(z.tuple([z.number(), z.number()])),
  holes: z.array(z.array(z.tuple([z.number(), z.number()]))).default([]),
  elevation: z.number().default(0.05),
})

polygon · Array<[number, number]> · required

Array of [x, z] points defining the slab boundary

holes · Array<Array<[number, number]>> · default: "[]"

Array of hole polygons (for openings in the slab)

elevation · number · default: "0.05"

Elevation in meters (thickness of the slab)

Location: packages/core/src/schema/nodes/slab.ts:5-13

ItemNode

Represents furniture, fixtures, or other 3D assets.

export const ItemNode = BaseNode.extend({
  id: objectId('item'),
  type: nodeType('item'),
  position: z.tuple([z.number(), z.number(), z.number()]).default([0, 0, 0]),
  rotation: z.tuple([z.number(), z.number(), z.number()]).default([0, 0, 0]),
  scale: z.tuple([z.number(), z.number(), z.number()]).default([1, 1, 1]),
  side: z.enum(['front', 'back']).optional(),
  children: z.array(objectId('item')).default([]),

  // Wall attachment properties
  wallId: z.string().optional(),
  wallT: z.number().optional(), // 0-1 parametric position along wall

  asset: assetSchema,
})

asset · Asset · required

Asset data including model source, dimensions, attachment behavior, and corrective transforms

wallId · string

Wall ID when asset is attached to a wall

wallT · number

Parametric position (0-1) along the wall when attached

scale · [number, number, number] · default: "[1, 1, 1]"

Scale factor for the asset (applied to asset.dimensions)

Location: packages/core/src/schema/nodes/item.ts:28-42

Flat Dictionary Storage

Nodes are stored in a flat dictionary rather than a nested tree:

type SceneState = {
  // Flat dictionary of all nodes
  nodes: Record<AnyNodeId, AnyNode>
  
  // Top-level nodes (typically Site nodes)
  rootNodeIds: AnyNodeId[]
  
  // Nodes pending system updates
  dirtyNodes: Set<AnyNodeId>
}

Location: packages/core/src/store/use-scene.ts:14-23

Benefits of Flat Storage

Fast Lookups

Direct access to any node by ID without tree traversal: nodes[id]

Easy Updates

Update nodes without cloning entire tree structure

Simple Serialization

Easy to persist to IndexedDB or serialize to JSON

Flexible Relationships

Supports multiple parent-child patterns (walls, surfaces, attachments)

ID Generation

Node IDs are auto-generated with type prefixes using nanoid:

const customId = customAlphabet('0123456789abcdefghijklmnopqrstuvwxyz', 16)

export const generateId = <T extends string>(prefix: T): `${T}_${string}` =>
  `${prefix}_${customId()}` as `${T}_${string}`

Examples:

• site_a1b2c3d4e5f6g7h8
• wall_x9y8z7w6v5u4t3s2
• item_p0o9i8u7y6t5r4e3

Location: packages/core/src/schema/base.ts:5-13

The type prefix makes it easy to identify node types in logs and debugging without looking up the full node object.