Introduction to Puzzle Modeling

Author: Aaron Siegel

Printing puzzles from pre-existing STL files is fun, but sooner or later (and probably sooner!), you'll want to create and print your own models. Perhaps you want to model a design you've found on Puzzle Will Be Played or a similar site; or you have designs of your own that you'd like to prototype; or you simply want to modify an existing design to customize its appearance. This tutorial will walk you through using the puzzlecad software library to model, modify, and render puzzle designs.

What is puzzlecad?

puzzlecad is a software library for modeling 3D printable interlocking puzzles. It translates simple expressions describing the geometry of puzzle pieces, such as this:

burr_piece("xxx|.x.");

into fully rendered models for 3D printing.

puzzlecad is built on the popular OpenSCAD modeling framework. OpenSCAD itself is a powerful tool with many advanced features, but if you haven't used it before or have limited experience with CAD in general, don't worry: you only need to know a few basic things about OpenSCAD in order to use puzzlecad.

Both OpenSCAD and puzzlecad are free and open source.

Installation

To use puzzlecad, you'll first need to download and install OpenSCAD, version 2019.05 or later. You can obtain a copy at the OpenSCAD homepage:

• https://www.openscad.org/

Next, download a copy of puzzlecad, version 2.0 or later. You can find it on Thingiverse:

• https://www.thingiverse.com/thing:3198014

Unzip the puzzlecad archive into your OpenSCAD documents folder. Its location varies by operating system (replace <user_dir> with your home directory; for example, mine is /Users/asiegel on MacOS):

• Windows: <user_dir>\My Documents\OpenSCAD
• MacOS: <user_dir>/Documents/OpenSCAD
• Linux: <user_dir>/.local/share/OpenSCAD

That's all you need to get started!

Trying out a .scad File

Now you can try loading a .scad file into OpenSCAD. puzzlecad comes bundled with a simple example, half-hour-example.scad (it's a simplified model of Stewart Coffin's Half Hour puzzle, which was also discussed in the Getting Started tutorial). Start OpenSCAD, load half-hour-example.scad, and you'll see something like what's pictured in the image on the left, above. In the panel on the left side of the OpenSCAD window, you'll see the code for Half Hour.

Now try rendering! Just press F6 (or select "Render" from the Design menu in OpenSCAD). If everything is set up correctly, then after a brief calculation you'll see the puzzle rendered as in the image on the right, above.

To generate an STL file from a .scad file, first render the design with F6, then select "Export / Export as STL" from the "File" menu. The generated STL file can then be loaded into your slicer software for printing.

In the section "Understanding a .scad File", below, we'll walk through the various sections of code in half-hour-example.scad to understand how it all works.

Converting a BurrTools File to .scad

Andreas Röver's BurrTools is a popular program for visualizing and analyzing interlocking puzzles. puzzlecad ships with a tool, bt2scad, that converts BurrTools .xmpuzzle files to .scad format for use with puzzlecad. This can be useful for puzzle enthusiasts who have built up large libraries of BurrTools models, or for anyone who wants to use BurrTools as an interactive graphical "frontend" for puzzlecad. If you're not a BurrTools user, you can safely skip this section.

bt2scad will already be included in whatever directory you installed puzzlecad (your OpenSCAD documents folder, if you followed the instructions above). To use it, open a command prompt, change to that directory, and run the following command:

java -jar bt2scad.jar MyPuzzle.xmpuzzle

This will create a file called MyPuzzle.scad that can be loaded into OpenSCAD for rendering. It's that simple! You can render and print immediately, or if you prefer, use the .scad file as a starting point and edit it to apply further customizations.

bt2scad requires Java, which is installed on many systems by default. But if you do get an error message such as java: command not found, that means you need to install Java. You can obtain a copy (it's free) at java.com.

Understanding a .scad File

The code for Half Hour is organized as follows:

include <puzzlecad.scad>

This first line tells OpenSCAD to use the puzzlecad library.

$burr_scale = 17;

$burr_inset = 0.07;

$burr_bevel = 1.3;

$unit_beveled = true;

These lines set the parameters of the design:

• $burr_scale = 17; sets the voxel size to 17 mm (that's the edge length of a single cube in the puzzle pieces). Since Half Hour assembles into a 3x3x3 cube, the fully assembled puzzle will be a cube 51 mm on a side.
• $burr_inset = 0.07; adds an inset of 0.07 mm to each piece. This is related to the tolerance of the puzzle (see the Getting Started tutorial for discussion). Because each piece is inset by 0.07 mm, the actual space added between two adjacent pieces will be 0.14 mm. Increasing this value will make the puzzle fit more loosely, and decreasing it will make the puzzle tighter.
• $burr_bevel = 1.3; adds beveling to the puzzle pieces with a width of 1.3 mm. (Here the width refers to the width of the diagonal cross-section of the bevel.)
• $unit_beveled = true; tells puzzlecad to bevel each voxel in the finished output independently.

burr_plate([

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

    [".xx|xx.", "...|.x."],

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

    [".x.|xxx"],

    ["x..|xxx"],

    ["x.|xx", "..|.x"]

]);

Finally, this section is where the action happens: it defines the geometry of each of the six Half Hour pieces. We won't go into the details of the syntax here, but it's described in detail in the puzzlecad documentation (see below).

You can try playing with the various parameters if you're curious how they affect the output. For example, try changing the line

$unit_beveled = true;

to

$unit_beveled = false;

and press F6 again to re-render. The shape of the puzzle is unaffected, but its appearance changes dramatically.

The puzzlecad Documentation

puzzlecad is a rich library with numerous modules for rendering puzzles with different geometries and customizations. We won't go into all its features in this introduction; the best way to learn it is to work through the puzzlecad-examples.scad file, which is bundled with puzzlecad. Just load it into OpenSCAD and follow along with the inline comments in the .scad file itself. It's structured as an interactive tutorial, so you can render various examples as you're reading through it.