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.
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.
Creating a Solid
There are several ways to add a solid to your site.
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.
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.
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.
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 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. |
| Scripts Panel | Lists 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 & Exit | In 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.
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).
| Function | Description | Example |
|---|---|---|
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.
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();
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)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.
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.
Practice Exercise
Put it all together by building a simple water tank from scratch.
Build a Water Tank
Create a new solid from the + menu.
In the solid editor, replace the default code with a cylinder for the tank body: const body = cylinder(1, 2);
Cut a slightly smaller cylinder to make it hollow: const hollow = body.cut(cylinder(0.9, 1.8).translateZ(0.1));
Add a fillet to round the top rim: const tank = hollow.fillet(0.05);
Return the tank with a material: return { shape: tank, color: '#4682B4', metalness: 0.6, roughness: 0.3 };
Press Ctrl+S to save. Rotate the view to inspect the hollow interior.
Try changing the cylinder dimensions and watch the shape update live.
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 & Units | Define adjustable parameters with proper units |
|---|---|
| Solids & Components | Full reference for the solid modeling system |
| Placing Entities | Position and manipulate objects on your site |