Intermediate ~15 min read

Introduction to Solids

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-Driven

Every 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.

Parametric

Define named parameters (width, height, radius) with types and constraints. Change a value in the inspector and the solid rebuilds automatically.

Composable

Combine 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

Double-click a solid (or select it 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 Controls

F Fit to view · 1 Front · 2 Right · 3 Top · 0 Toggle perspective / orthographic

Display

Toggle face visibility, edge wireframes, and adjust face opacity with the slider. Useful for inspecting internal geometry.

Save & Exit

Ctrl+S saves your code. Esc or the Done button returns to the globe view.

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.

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).

▭

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. Press Esc 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