Parameters & Units

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 (double-click it, or select it and click Edit).
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.

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

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