Puzzlecad is an OpenSCAD library for modeling mechanical puzzles. It's used in most of the models on this site. This page will be used for updates and related puzzlecad documentation; for an overview of how to get started using puzzlecad, see the Puzzle Modeling tutorial.

What's New in Version 2.3?

Puzzlecad version 2.3 (released 14 April 2022) is the first new release in over a year! Here's what's new:

packing_box improvements

The packing_box module, previously introduced in puzzlecad 2.2, has several minor improvements.

  • Diagonal cuts: packing boxes can now be specified with "diagonal cutouts," as illustrated in the example below.

  • Interior voxels: interior voxels (i.e., voxels not on the outer box surface) will now be rendered by packing_box. This may not work correctly with $auto_layout in all cases. (If you encounter issues, please submit a bug report on github.)

  • Fixed a bug involving incorrect placement of guide pins when $auto_layout splits a packing_box into three or more components.

As always, the new features are documented in the puzzlecad-examples.scad file bundled with puzzlecad.






], $burr_scale = 17, $box_wall_thickness = 6, $auto_layout = true);

Detached male joints

Male connectors can now be printed "detached". If the option $detached_joints = true; is specified, then instead of rendering male connectors, puzzlecad will render female connectors on both ends, with a separately printed strut that can join them together. In this way, the struts can be printed horizontally on the print bed, making them considerably stronger. This can be useful when modeling joints in sensitive locations where the puzzle is likely to experience significant stress.

$detached_joints can be used with or without $auto_layout, and individual detached struts can be generated with the detached_male_connector(); module.


["x..|xxx|...", "...|..x|..x"],

$auto_layout = true,

$detached_joints = true


--header option in bt2scad

The bt2scad tool now has a --header option. Specifying one tells bt2scad to copy the contents of a header file into the generated .scad file, instead of auto-generating parameters (such as $burr_scale and require_puzzlecad_version). Example:

java -jar bt2scad.jar --header my-header.scad my-puzzle.xmpuzzle

What's New in Version 2.2?

Puzzlecad version 2.2 (released 11 March 2021) brings several improvements:

A new packing_box module

The major new feature is a packing_box module for easy modeling of packing puzzle boxes. A thatched pattern is used to create semi-transparency. The packing_box module is described in detail in the puzzlecad-examples.scad file bundled with puzzlecad. Here's one example:







], $burr_scale = 17, $box_wall_thickness = 6, $auto_layout = true);

A few new convenience options

  • The components annotation for diagonal geometry has a new "slice" component for conveniently specifying half-cubes sliced along a diagonal axis.

  • Labels can now specify a custom font with the label_font annotation. Thanks to Tom Burns for contributing this feature.

See puzzlecad-examples.scad for details on the new features.

Removed spurious warnings with OpenSCAD 2021.01

Puzzlecad is now fully compatible with OpenSCAD 2021.01.