Tutorial

Introduction to Solids

Level
Intermediate
Time
~15 min read

Create parametric 3D objects with code. This tutorial covers primitive shapes, transformations, boolean operations, materials, and the solid editor — everything you need to start building structures on your site.

1

What Are Solids?

Solids are parametric 3D objects defined by JavaScript code. Unlike static meshes, solids regenerate every time their parameters change — adjust a width value and the geometry updates instantly. Under the hood, SiteCAD uses replicad (built on OpenCascade) for precise boundary-representation modeling — the same kind of solid modeling used in professional CAD tools.

Code-DrivenEvery solid is defined by a script that returns geometry. This means you can use variables, loops, and logic to create shapes that adapt to any situation.
ParametricDefine named parameters (width, height, radius) with types and constraints. Change a value in the inspector and the solid rebuilds automatically.
ComposableCombine shapes with boolean operations — union, subtract, intersect — to build complex structures from simple primitives. Split logic into reusable blueprints.

No coding experience needed

If you've never written code before, don't worry. Solid scripts are short and focused — most are under 20 lines. The AI assistant can also generate solid code for you. Just describe what you want: create a water tank 2m tall with a 1m radius.

2

Creating a Solid

There are several ways to add a solid to your site.

1

From the Create menu: Click the + button in the toolbar and select Solid. A new solid entity appears in your scene graph with a default box shape.

2

From the AI assistant: Describe what you want — e.g. create a cylinder 3m tall with radius 0.5m — and the assistant creates and positions it for you.

3

From the scene graph: Right-click a component and choose New → Solid to add a solid as a child of that component.

Every new solid starts with a simple box and three default parameters: width, height, and depth — all set to 1 meter. You'll customize this code in the solid editor.

3

The Solid Editor

Select a solid and click Edit in the inspector to enter the solid editor. The viewport switches from the globe view to a local 3D view powered by Three.js, with a dedicated toolbar for solid editing.

View ControlsF Fit to view · 1 Front · 2 Right · 3 Top · 0 Toggle perspective / orthographic
DisplayToggle face visibility, edge wireframes, and adjust face opacity with the slider. Useful for inspecting internal geometry.
Scripts PanelLists the solid's blueprints and parts. A ● and an italic name mark a script with unsaved changes. Select a blueprint to preview it over the solid's parts, drawn faded — handy for checking a sketch and where it lands — and select a part to see the whole solid again.
Save & ExitIn the code editor, Ctrl+S saves the script you are editing and Ctrl+Shift+S saves every unsaved script. Anywhere else in the solid editor, such as the 3D view, Ctrl+S saves them all. The Done button, or the code editor's ✕, returns you to the view you opened the solid from.

Live preview

The 3D view updates as you edit code. If there's a syntax error, the previous shape stays visible until you fix it. Check the error panel below the code editor for diagnostics.

Unsaved changes

Leaving the editor with unsaved changes asks first. Save saves every script and leaves, Don't Save puts every script back the way it was last saved and leaves, and Cancel keeps you in the editor with nothing changed. If the save fails, the dialog stays open and says why.

4

Primitive Shapes

SiteCAD provides three convenience functions for common shapes. Each returns a solid centered at the origin with its base on the ground plane (Z = 0).

FunctionDescriptionExample
box(width, depth, height)Rectangular prism. Origin at center of base.return box(2, 3, 1.5);
cylinder(radius, height)Circular cylinder. Origin at center of base.return cylinder(0.5, 2);
sphere(radius)Sphere centered at the origin.return sphere(1);

Full replicad API

Beyond these helpers, you have access to the full replicad library: sketchRectangle(), sketchCircle(), draw() for custom 2D sketches, .extrude(), .revolve(), loft(), and more. See the Solids & Components docs for the complete reference.

5

Transformations

Move, rotate, mirror, and scale shapes to position them precisely.

Translate

shape.translate(x, y, z)
shape.translateX(2)
shape.translateZ(-0.5)

Rotate

// Rotate 45° around Z axis
shape.rotate(45, [0,0,0], [0,0,1])

Mirror

// Mirror across YZ plane
shape.mirror("YZ")

Scale

shape.scale(2)

Clone before reusing

Replicad shapes are consumed by operations like .fuse() and .translate(). If you need the same shape in two places, call .clone() first: const copy = shape.clone();

6

Boolean Operations

Booleans let you combine simple shapes into complex geometry. These are the building blocks of parametric modeling.

Fuse (Union)

Combine two shapes into one merged solid.

const base = box(2, 2, 1);
const top = cylinder(0.8, 2)
  .translateZ(1);
return base.fuse(top);

Cut (Subtract)

Remove one shape from another — perfect for holes and cavities.

const block = box(2, 2, 2);
const hole = cylinder(0.3, 3)
  .translateZ(-0.5);
return block.cut(hole);

Intersect

Keep only the volume where two shapes overlap.

const a = box(2, 2, 2);
const b = sphere(1.4);
return a.intersect(b);

You can also round or bevel edges after combining shapes:

Fillet

Round edges with a radius.

box(2, 2, 1).fillet(0.1)

Chamfer

Bevel edges at 45°.

box(2, 2, 1).chamfer(0.1)
7

Materials

By default, solids render with a neutral material. To customize appearance, return an object with a shape and material properties instead of a bare shape.

return {
  shape: cylinder(0.5, 2),
  color: '#8B4513',     // CSS color (acts as tint with texture)
  roughness: 0.8,       // 0 = shiny, 1 = matte
  metalness: 0.1,       // 0 = plastic, 1 = metal
  opacity: 0.9,         // 0 = invisible, 1 = solid
  texture: 'concrete',  // built-in texture key
  textureScale: 2       // meters per repeat
};

color

Any CSS color string: #RGB, #RRGGBB, or #RRGGBBAA. Acts as tint when a texture is set.

roughness

0–1. Low values produce a glossy surface; high values look matte. Default: 0.35.

metalness

0–1. Controls metallic reflectance. Use 0 for wood, concrete, plastic; higher values for steel or aluminum. Default: 0.1.

opacity

0–1. Set below 1 to make shapes translucent — useful for glass or water effects. Default: 1.0.

texture

Built-in texture key: concrete, brick, wood-oak, metal, grass, stone.

textureScale

Meters per texture repeat. Controls how large or small the pattern appears on the surface. Default: 1.0.

8

Multi-Part Solids

A solid can return multiple shapes, each with its own material. Return an array to render several parts together.

const trunk = cylinder(0.15, 2);
const canopy = sphere(0.8).translateZ(2.2);

return [
  { shape: trunk,  color: '#8B4513', roughness: 0.9 },
  { shape: canopy, color: '#228B22', roughness: 0.7 }
];

For more complex solids, you can organize code using blueprints (reusable helper functions) and parts (root outputs). The solid editor lets you add multiple blueprints and parts from the composition panel.

When to use parts vs. arrays

Returning an array from a single part is fine for simple cases. Use separate parts when you want independent visibility toggles, per-part material styles in the inspector, or when your logic is complex enough to benefit from named blueprints.

9

Practice Exercise

Put it all together by building a simple water tank from scratch.

Build a Water Tank

1

Create a new solid from the + menu.

2

In the solid editor, replace the default code with a cylinder for the tank body: const body = cylinder(1, 2);

3

Cut a slightly smaller cylinder to make it hollow: const hollow = body.cut(cylinder(0.9, 1.8).translateZ(0.1));

4

Add a fillet to round the top rim: const tank = hollow.fillet(0.05);

5

Return the tank with a material: return { shape: tank, color: '#4682B4', metalness: 0.6, roughness: 0.3 };

6

Press Ctrl+S to save. Rotate the view to inspect the hollow interior.

7

Try changing the cylinder dimensions and watch the shape update live.

8

Click Done to return to the globe view and see your tank on the terrain.

Next challenge

Add parameters for tank radius and height so you can adjust them from the inspector without editing code. The Parameters & Units tutorial covers this in detail.

Next Steps

Parameters & UnitsDefine adjustable parameters with proper units
Solids & ComponentsFull reference for the solid modeling system
Placing EntitiesPosition and manipulate objects on your site