Guide

Solids & Components

Create parametric 3D objects with code, organize them into reusable components, and place instances throughout your site. This guide covers solid fundamentals, the scripting model, parameters and units, and the component/instance system.

Solid Fundamentals

A solid is a parametric 3D shape defined by JavaScript code using the replicad CAD engine (built on OpenCascade). Solids support adjustable parameters, materials, construction geometry, and export to STEP for CAD interop.

What Makes Solids Parametric

Unlike static 3D models, solids are generated from code every time their parameters change. Define a foundation with width, depth, and height parameters, then adjust those values to resize the foundation instantly. The same solid definition can be instanced multiple times with different parameter values.

Blueprints and Parts

Each solid's code is organized into blueprints and parts:

Blueprints

Reusable helper functions that produce geometry fragments. Each blueprint has a JavaScript identifier name (e.g. tankProfile) and a kind: solid, sketch, or plane. Blueprints are callable by other blueprints and by parts.

Parts

Root outputs that produce the final geometry you see in the scene. Each part has a display label, optional material style, and a visibility toggle. Parts call blueprint functions to compose complex shapes.

Why this split?

Blueprints let you factor out repeated geometry (a profile sketch, a bolt pattern) so parts stay clean and readable. A septic tank solid might have a tankProfile blueprint used by both a "body" part and a "lid" part.

Rendering

Solids render in two modes depending on context:

  • Scene mode (Cesium) — Solids appear on the globe using GPU-instanced mesh rendering, shaded by the scene's sun (or fixed light) with highlights and reflections set by each part's roughness and metalness. Efficient even with many identical objects.
  • Local space mode (Three.js) — When you edit a solid, the viewport switches to a detailed Three.js view with construction geometry, live preview, and camera controls for inspecting your shape up close.

Writing Solid Code

Solid scripts run in a sandboxed environment with access to the full replicad API and your declared parameters. You write function bodies — no imports or exports needed.

Basic Example

A simple foundation slab with three parameters:

// Part: "Foundation"
const { width, depth, height } = params;
return box(width, depth, height);

The params object contains all declared parameter values. Replicad functions like box(), cylinder(), sphere(), and sketchRectangle() are available globally in the sandbox.

What a Part Can Return

A part does not have to return a solid. A face renders as a surface with no thickness. A wire, an edge, or a 2D drawing or sketch renders as lines, and the inner outline of any hole in a drawing is drawn as well.

// A flat surface: one face of a box
return box(2, 1, 1).faces[0];

// A line: a single edge between two points
return makeLine([0, 0, 0], [2, 0, 0]);

// A 2D outline with a hole: drawn as lines, nothing filled
return drawRectangle(4, 4).cut(drawCircle(1));

Lines appear in the solid editor, where clicking one selects the part that made it. The site scene draws only surfaces, so a part that returns only lines or a sketch draws nothing on the globe, and a drawing sheet shows a marker for it; a part that returns a solid and a sketch together shows just the solid there. To see an outline in the scene, turn it into a solid first, for example drawRectangle(4, 4).cut(drawCircle(1)).sketchOnPlane('XY').extrude(0.1).

Materials

Return an object or array to apply materials to your shapes:

// Color material
return { shape: cylinder(1, 2), color: '#8B4513', roughness: 0.8 };

// Texture with tint
return { shape: base, texture: 'concrete', textureScale: 2, color: '#ddccbb' };

// Multiple shapes with different materials
return [
  { shape: trunk, color: '#8B4513' },
  { shape: foliage, color: '#228B22CC' },  // alpha = transparency
];
PropertyRangeDescription
colorCSS colorSupports #RGB, #RRGGBB, or #RRGGBBAA. Acts as tint when texture is set.
roughness0 – 10 = shiny/glossy, 1 = matte. Glossier parts show a tighter sun highlight and a stronger sky reflection.
metalness0 – 1Metallic appearance: reflections take on the part color and the flat color fades.
opacity0 – 1Explicit opacity (overrides alpha from color)
texturestringBuilt-in texture key (e.g. concrete, brick, wood-oak, metal, grass, stone)
textureScalenumberMeters per texture repeat

Construction Geometry

Add reference lines and planes that appear during editing but don't render in the final scene:

// Show a reference axis
showLine([[0, 0, 0], [0, 0, params.height]], '#ff0');

// Show a reference plane
showPlane([[0, 0, 0], [w, 0, 0], [w, d, 0], [0, d, 0]], [0, 0, 1], '#0af');

Named Features

Export semantic geometry that operations and other systems can query:

featurePoint('ground', [5, 4, 0]);       // A named point
featureLine('ridge', [[0,0,3], [10,0,3]]); // A named polyline
featureLoop('perimeter', [...corners]);    // A closed loop
featurePlane('base', [0,0,0], [0,0,1]);   // Origin + normal

Multiple features can share the same name — for example, several 'ground' points marking ground level around a foundation perimeter.

An operation script reads a solid's features back by name with getSolidFeatures(id, name), where id is the solid or a placed instance of it; for an instance, that instance's own parameter values apply. It returns a list of { name, type, points }, which is empty when nothing has that name. A part whose script stops with an error adds none of its features, so a solid whose scripts all fail gives an empty list. The operation needs the Read scene data capability.

// In an operation whose entity parameter "foundation" is the
// foundation solid or a placed instance of it:
// where are its ground points on the site?
const ground = await getSolidFeatures(params.foundation, 'ground');
const onSite = [];
for (const f of ground) {
  const [x, y, z] = f.points[0];   // a point feature holds one point
  onSite.push(await localToWorld(params.foundation, { x, y, z }));
}
return onSite;

Feature points are in the solid's own coordinates; localToWorld with the solid's or the instance's id places them on the site. A plane's points are its origin and its normal.

STEP Export

Solids can be exported to STEP format (.step / .stp) for interop with CAD software like AutoCAD, SolidWorks, Fusion 360, and FreeCAD. Use the export dialog in the editor to download a solid as a STEP file.

Parameters and Units

Parameters make solids adjustable. Each parameter has a name, type, default value, and optional constraints. When a parameter has a dimension (like length or angle), SiteCAD automatically handles unit conversion.

Parameter Types

numberNumeric value with optional min, max, step, and unit. Most common for dimensions.
booleanTrue/false toggle. Use for optional features like chamfers, holes, or symmetry.
stringFree-text input. Use for labels, names, or custom identifiers.
selectDropdown with predefined choices. Use when the user picks from a fixed set of options.
entityReference to another entity in the scene. Use when your solid needs to read data from a trace, boundary, or other object.
pointA 3D position, typed in or picked from the scene. Use for an anchor, an insertion point, or a target.
transformPosition, rotation, and scale together. Use when the solid places or orients a sub-part.
listA variable-length list of items of one kind (numbers, points, entities, …). Arrives in the script as an ordinary array.

Dimensions and Units

When you assign a dimension to a number parameter, SiteCAD displays the value in the user's preferred unit and converts to the base unit internally.

DimensionBaseUnits
lengthmetersmeters, feet, yards, miles, inches, centimeters
areasquare meterssquare meters, square feet, acres, hectares
volumecubic meterscubic meters, liters, gallons, cubic feet, cubic yards
angledegreesdegrees, radians, gradians

Tip:

You can also set min, max, and step constraints on number parameters. The inspector will enforce these limits and display a slider when appropriate.

Full Parameter Example

// Parameter definitions for a water tank solid
[
  { name: "diameter", type: "number", label: "Diameter",
    dimension: "length", defaultValue: 2, unit: "m",
    min: 0.5, max: 10, step: 0.1 },
  { name: "height", type: "number", label: "Height",
    dimension: "length", defaultValue: 3, unit: "m",
    min: 0.5, max: 20 },
  { name: "hasLid", type: "boolean", label: "Include Lid",
    defaultValue: true },
  { name: "material", type: "select", label: "Material",
    options: ["steel", "concrete", "plastic"],
    defaultValue: "steel" }
]

Components and Instances

Components group entities into reusable design elements. Instances reference a component and inherit its structure, letting you place the same design multiple times with different configurations.

Components

A component is a container that groups other entities — solids, traces, boundaries, or even nested components. The site root (Entity 0) is itself a component.

  • Grouping — Moving a component moves all its children together.
  • Parameters — Components can declare their own parameters that child entities bind to, creating a configurable assembly.
  • Nesting — Components can contain other components, building up complex hierarchies (e.g., a "Farm" component containing "Barn" and "Silo" components).

Instances

An instance is a reference to a template — any entity in the Templates group, most often a component or a solid — that inherits its structure. Instances share the prototype's entities but can override declared parameters.

  • Prototype link — Change the prototype once and all instances update automatically.
  • Parameter overrides — Each instance can customize parameter values without affecting the prototype or other instances.
  • Efficient — Instances don't duplicate geometry data. The renderer uses GPU instancing for identical shapes.

Example workflow:

Define a "Fence Post" solid with height and diameter parameters. Create a "Fence Section" component containing the post solid and a trace for the rail. Instance the fence section along your property line — each instance inherits the design but can have different heights for sloped terrain.

Component / Instance Hierarchy

Garden Beds (Component)
├── Raised Bed (Solid) ← prototype
├── Irrigation Line (Trace)
└── Drip Emitter (Solid)

Scene Graph:
├── Garden Beds         (Component definition)
├── North Garden        (Instance → Garden Beds, height: 0.6m)
├── South Garden        (Instance → Garden Beds, height: 0.45m)
└── Patio Garden        (Instance → Garden Beds, height: 0.3m)

Continue Learning

Core ConceptsSites, scenarios, entities, and coordinates
TerrainElevation data, contours, and grading
Parametric Solids FeatureFeature overview and use cases
Getting StartedCreate your first site in 10 minutes