claude-workflow/skills/openscad/references/language-reference.md

OpenSCAD Language Reference (v2021.01)

Syntax & Declaration

var = value;                              // variable assignment
var = cond ? value_if_true : value_if_false;  // ternary
var = function (x) x + x;                // function literal
module name(params) { ... }              // module definition
function name(params) = expr;            // function definition
include <file.scad>                       // include (executes top-level code)
use <file.scad>                           // import (only modules/functions)

Constants

• undef — undefined value
• PI — 3.14159...

Special Variables

Variable	Purpose
$fn	Fixed number of segments for circles/spheres
$fa	Minimum angle per segment
$fs	Minimum segment size
$t	Animation step (0–1)
$vpr	Viewport rotation
$vpt	Viewport translation
$vpd	Viewport distance
$vpf	Viewport field of view
$children	Number of child modules
$preview	true in preview (F5), false in render (F6)

Modifier Characters

• * — disable (don't render)
• ! — show only this
• # — highlight/debug (transparent red)
• % — transparent/background

3D Primitives

cube(size, center=false)                   // cube([w,d,h]) or cube(s)
sphere(r=radius)                           // sphere(d=diameter)
cylinder(h, r=radius, center=false)        // cylinder(h, d=diameter)
cylinder(h, r1, r2, center=false)          // cone/tapered cylinder
polyhedron(points, faces, convexity)        // custom solid

2D Primitives

circle(r=radius)                           // circle(d=diameter)
square(size, center=false)                 // square([w,h])
polygon(points, paths)                      // 2D polygon
text(t, size=10, font, halign, valign, spacing)  // text string

2D → 3D Extrusion

linear_extrude(height, center, twist, slices, scale)
    circle(10);                            // extrude 2D to 3D

rotate_extrude(angle=360, convexity)
    translate([20,0]) circle(5);           // lathe/revolve

surface(file="heightmap.dat", center)       // heightmap to 3D

Transformations

translate([x, y, z])                       // move
rotate([x, y, z])                          // rotate (degrees)
rotate(angle, [x, y, z])                   // rotate around axis
scale([x, y, z])                           // scale
resize([x, y, z], auto)                    // resize to exact dimensions
mirror([x, y, z])                          // mirror across plane
multmatrix(m)                              // 4x4 matrix transform
color("name", alpha)                       // color("red"), color("#ff0000")
color([r, g, b, a])                        // color by RGBA (0-1)
offset(r=radius)                           // 2D offset (round)
offset(delta=dist, chamfer=false)          // 2D offset (sharp)

Boolean Operations

union() { a(); b(); }                      // combine (A + B)
difference() { a(); b(); }                // subtract (A - B)
intersection() { a(); b(); }              // overlap only (A ∩ B)

Advanced Operations

hull() { a(); b(); }                       // convex hull
minkowski() { a(); b(); }                 // Minkowski sum (slow!)
render(convexity) { ... }                  // force CGAL render (cache)
projection(cut=false) { ... }             // 3D → 2D projection

Import / Export

import("file.stl")                         // import STL, OFF, AMF, 3MF
import("file.dxf")                         // import 2D DXF
import("file.svg")                         // import 2D SVG

Flow Control

if (condition) { ... } else { ... }
for (i = [0:10]) { ... }                  // range [start:end]
for (i = [0:2:10]) { ... }                // range [start:step:end]
for (i = [1, 5, 7]) { ... }               // list iteration
for (i = [...], j = [...]) { ... }         // nested loops
intersection_for(i = [...]) { ... }        // intersection across iterations
let (a = expr) { ... }                     // local variable scope

List Comprehensions

list = [ for (i = [0:10]) i * 2 ];                    // generate
list = [ for (i = [0:10]) if (i % 2 == 0) i ];        // filter
list = [ for (i = [0:10]) let (x = i*i) x ];           // with let
list = [ each sublist ];                                // flatten

Math Functions

Function	Description
abs(x)	Absolute value
sign(x)	Sign (-1, 0, 1)
sin(x), cos(x), tan(x)	Trig (degrees)
asin(x), acos(x), atan(x)	Inverse trig
atan2(y, x)	Two-argument arctangent
floor(x), ceil(x), round(x)	Rounding
ln(x), log(x)	Natural / base-10 log
pow(base, exp)	Power
sqrt(x)	Square root
exp(x)	e^x
min(a,b,...), max(a,b,...)	Min/max
norm(v)	Vector magnitude
cross(v1, v2)	Cross product
rands(min, max, count)	Random numbers
len(x)	Length of list/string

String Functions

Function	Description
str(...)	Concatenate to string
chr(code)	ASCII code → character
ord(char)	Character → ASCII code
search(needle, haystack)	Search in list/string

Type Testing

is_undef(x)   is_bool(x)    is_num(x)
is_string(x)  is_list(x)    is_function(x)

Other Functions

echo("msg", var)                           // debug output
assert(condition, "message")               // assertion
concat(list1, list2)                       // concatenate lists
lookup(key, [[k,v], ...])                  // table lookup
children(idx)                              // access child N of module
parent_module(idx)                         // access parent module name
version()                                  // OpenSCAD version string

Operators

Type	Operators
Arithmetic	+ - * / % ^
Relational	< <= == != >= >
Logical	&& || !
Indexing	list[i] list.x list.y list.z

Tips for AI-Generated Code

• Always set $fn for predictable circle resolution
• Use center=true when building symmetric objects with difference()
• Add 0.01mm epsilon to boolean cuts to avoid coplanar Z-fighting:

  difference() {
      cube([10, 10, 10]);
      translate([-0.01, 2, 2])
          cube([10.02, 6, 6]);  // slightly larger to ensure clean cut
  }
  

• Modules for reuse: parameterize everything, compose with modules
• Comments: explain the "why", dimensions in mm
• Print orientation: think about which face goes on the build plate
• Manifold check: all boolean operands must overlap; no coincident faces