Parameters & Units
- Level
- Intermediate
- Time
- ~10 min read
Make your solids adjustable without editing code. This tutorial covers defining parameters with types and constraints, the dimension and unit system, and how parameter values flow from the inspector into your solid scripts.
Why Parameters?
In the Introduction to Solids tutorial, you hard-coded dimensions directly in your script. That works, but it means every change requires editing code. Parameters separate shape logic from shape dimensions.
| Adjust Without Code | Change a parameter value in the properties panel and the solid rebuilds instantly — no need to open the code editor. |
|---|---|
| Type-Safe & Constrained | Each parameter has a type, optional min/max limits, and step size. Invalid values are rejected before the solid ever rebuilds. |
| Unit-Aware | Attach a dimension (length, area, angle, etc.) and SiteCAD handles unit conversion automatically — enter feet, the script receives meters. |
Defining Parameters
Parameters are defined in the solid editor's Parameters panel, which sits alongside the code editor. Each parameter has a name, a type, and optional settings depending on the type.
Open a solid in the editor (select it and click Edit in the inspector).
Locate the Parameters section in the editor panel. Existing parameters (if any) are listed here.
Click Add Parameter. A new parameter appears with a default name and type.
Give it a descriptive name — e.g. radius, wallThickness, height. Names must be alphanumeric (no spaces).
Choose a type from the dropdown and configure any additional settings (unit, default, constraints).
Press Ctrl+S to save. The parameter immediately appears in the properties panel when the solid is selected.
Labels
Each parameter has an optional label field for a human-friendly
display name. If you name a parameter wallThickness, set its label
to Wall Thickness so the inspector shows something readable.
Parameter Types
The type determines what kind of input the inspector shows and what value
your code receives via the params object.
| Type | What it is | In code |
|---|---|---|
| number | Numeric value with optional unit, min/max, and step. The most common type for dimensions and quantities. | params.height // → 2.5 |
| boolean | True/false toggle. Renders as a checkbox in the inspector. Use for on/off options like "include lid" or "hollow". | params.hollow // → true |
| string | Free-form text input. Useful for labels, material names, or any text value your script needs. | params.label // → "Tank A" |
| select | Dropdown with predefined options. Define a list of value/label pairs and the user picks one. | params.style // → "round" |
| entity | Reference to another entity in the scene. The inspector shows a dropdown plus a pick-from-scene button. Filter by entity types (solid, trace, etc.). | params.path // → entity ID |
| point | A 3D coordinate [x, y, z]. The inspector shows three
number inputs for each axis. | params.origin // → [1, 2, 0] |
Choosing the right type
Use number for anything with a dimension or quantity. Use select when there's a fixed set of choices (e.g. shape style, material preset). Use boolean for feature toggles. Use entity when your solid needs to reference another scene object (e.g. a path to follow).
Dimensions & Units
Number parameters can be assigned a dimension — a physical quantity like length or angle. Once a dimension is set, the parameter gains full unit support: the inspector shows a unit button, users can enter values in any compatible unit, and conversion happens automatically.
length | mm, cm, m, km, in, ft, yd, mi |
|---|---|
area | m², ha, km², ft², ac, mi² |
volume | mL, L, m³, fl oz, gal, ft³ |
angle | deg, rad |
temperature | °C, °F |
mass | g, kg, t, oz, lb, ton |
speed | m/s, km/h, mph, ft/s |
How Unit Conversion Works
When you define a parameter with dimension: length and unit: ft, the inspector displays values in feet. But
internally, SiteCAD stores and delivers values to your script in base units — meters for length, degrees for angles,
kilograms for mass, and so on.
// Parameter defined with dimension "length", display unit "ft"
// User enters 6 in the inspector (meaning 6 feet)
// Script receives the value in meters:
params.height // → 1.8288 (6 ft × 0.3048 = 1.8288 m)This means your solid code always works in consistent base units — you never need to worry about what unit system the user prefers. The conversion is completely transparent.
User's unit preference
SiteCAD respects the user's global unit system preference (metric or imperial).
When the inspector shows a unit-aware input, hovering the unit button
reveals alternative units. Users can type values like 6 ft directly into a meter-configured field and the conversion is applied
automatically.
Constraints
Number parameters support constraints that keep values within safe bounds. These prevent users from entering values that would break the geometry or produce physically impossible results.
| Setting | What it does | Example |
|---|---|---|
| default | The initial value when no override is set. Always define a sensible default so the solid renders correctly out of the box. | default: 1, defaultUnit: 'm' |
| min | The lowest allowed value. The inspector enforces this — users can't go below it. | min: 0.1, minUnit: 'm' |
| max | The highest allowed value. Useful for capping dimensions at realistic limits. | max: 10, maxUnit: 'm' |
| step | The increment when using arrow keys or the slider. A step of 0.1 gives one-decimal precision. | step: 0.5, stepUnit: 'ft' |
Constraint units
Each constraint value (default, min, max, step) can have its own unit.
You might define a default of 6 ft, a min of 1 ft,
and a max of 20 ft. SiteCAD converts them all to base units
internally. This lets you author constraints in whichever unit is most natural.
Accessing Parameters in Code
Inside your solid script, all defined parameters are available on the params object. Access them by name — values are already
converted to base units.
// Parameters defined:
// radius — number, dimension: length, default: 1 m
// height — number, dimension: length, default: 2 m
// hollow — boolean, default: true
const body = cylinder(params.radius, params.height);
if (params.hollow) {
const wall = 0.05; // 5cm wall thickness
const cavity = cylinder(
params.radius - wall,
params.height - wall
).translateZ(wall);
return body.cut(cavity);
}
return body;Base units in code
Remember: params.radius is always in meters, regardless of
what unit the user chose in the inspector. If you need a value in specific
units within your code (rare), do the conversion yourself — e.g. params.radius * 3.28084 for feet. But in most cases, just
use the base-unit value directly with replicad, which also works in meters.
You can use parameters in any JavaScript expression — calculations, conditionals, loops, or as arguments to any replicad function.
// Conditional geometry based on a select parameter
const base = box(params.width, params.depth, params.height);
if (params.roofStyle === 'peaked') {
// ... add a peaked roof
} else if (params.roofStyle === 'flat') {
// ... add a flat roof slab
}Setting Values from the Inspector
Once you've defined parameters and saved the solid, they appear in the properties panel whenever the solid entity is selected. Each parameter type renders its own control.
Number (with unit)
A numeric input with a small unit button. Click the unit button to see and switch between available units for that dimension.
Number (without unit)
A plain numeric input. Used for dimensionless quantities like counts or ratios.
Boolean
A checkbox toggle. Changes take effect immediately.
Select
A dropdown menu showing the defined options. Pick one and the solid rebuilds.
Entity
A dropdown listing compatible entities plus a pick button to select directly from the scene.
Point
Three coordinate inputs (X, Y, Z) for entering a 3D position.
Instance overrides
When a solid is used as a component in multiple places, each instance can override parameter values independently. The parameter definition sets the default; each instance can customize it. This is how you reuse one solid design at different sizes across your site.
Practice Exercise
Take the water tank from the Introduction to Solids tutorial and make it fully parametric.
Parameterize a Water Tank
Open your water tank solid in the editor (or create a new solid if needed).
Add a radius parameter:
- Type:
number - Dimension:
length - Default:
1 m - Min:
0.25 m· Max:5 m - Label:
Radius
Add a height parameter:
- Type:
number - Dimension:
length - Default:
2 m - Min:
0.5 m· Max:10 m - Label:
Height
Add a wallThickness parameter:
- Type:
number - Dimension:
length - Default:
5 cm(defaultUnit:cm) - Min:
1 cm· Max:20 cm - Step:
1 cm - Label:
Wall Thickness
Add a hollow parameter:
- Type:
boolean - Default:
true - Label:
Hollow
Update the solid code to use these parameters:
const body = cylinder(params.radius, params.height);
if (params.hollow) {
const inner = cylinder(
params.radius - params.wallThickness,
params.height - params.wallThickness
).translateZ(params.wallThickness);
const tank = body.cut(inner).fillet(params.wallThickness * 0.5);
return { shape: tank, color: '#4682B4', metalness: 0.6, roughness: 0.3 };
}
return { shape: body, color: '#4682B4', metalness: 0.6, roughness: 0.3 };Save with Ctrl+S, then click Done to return to the globe view.
Select the tank and try adjusting Radius, Height, and Wall Thickness from the properties panel. Toggle Hollow on and off. The tank rebuilds each time.
Next challenge
Try adding a select parameter called material with options like "steel", "concrete", and "plastic" — then use params.material in a conditional to set different color
and metalness values for each choice.
Next Steps
| Introduction to Solids | Primitives, booleans, and materials |
|---|---|
| Solids & Components | Full reference for the solid modeling system |
| Chatting with AI | Let AI generate parametric solids for you |