Scripting Introduction

Get started with scripting 3D-printable models of LEGO® compatible bricks using OpenSCAD and MachineBlocks.

Prerequisites: Before you start scripting, make sure that OpenSCAD and the MachineBlocks library are installed on your computer.

Organizing Your Scripts

Create a new folder named my-scripts as a sibling of the machineblocks folder you downloaded earlier. This lets you keep your own OpenSCAD files separate from the MachineBlocks library so you can update or replace the library without touching your scripts.

Start OpenSCAD

Start OpenSCAD and select new file.

Import Statements

To use the MachineBlocks library in your OpenSCAD scripts, you need to include two import statements at the beginning of your file. These statements ensure that all required modules, functions, and configuration settings are available.

use <../machineblocks/lib/block.scad>;
include <../machineblocks/config/config.scad>;

The use statement loads the main library file (block.scad), which contains the definitions of the building blocks and functions provided by the MachineBlocks framework.
The include statement imports the configuration file (config.scad), which defines default parameters, dimensions, and other global settings used by the library.

Tip: Always place these imports at the very top of your script to make sure all dependent modules are loaded before they are referenced. If your folder structure differs, adjust the relative paths accordingly.

Creating Your First MachineBlock

After importing the MachineBlocks library, you can create your first block by calling the machineblock() module in your script. Place this call below the import statements, leaving an empty line in between for clarity.

use <../machineblocks/lib/block.scad>;
include <../machineblocks/config/config.scad>;

machineblock();

Save the file as my-scripts/my-brick.scad, and a 1×1 plate will be rendered. This is the default output when the module is called without parameters.

Adding Parameters

You can customize the appearance and structure of a MachineBlock by adding one or more parameters to the machineblock() call. Parameters allow you to control various aspects of the rendered model, such as its size, proportions, and detailed features.

For example, the following code defines a brick with a width of 4 studs, a depth of 2 studs, and a height of 3 plates, which corresponds to the proportions of a classic LEGO®-style brick:

use <../machineblocks/lib/block.scad>;
include <../machineblocks/config/config.scad>;

machineblock(
    size = [4, 2, 3]
);

Multiple Parameters

You can add multiple parameters, separated by commas, to further customize the behavior and appearance of your MachineBlock. Each parameter controls a specific feature, such as the brick’s geometry, stud type, or the presence of Technic pin holes.

For example, the following script creates a 6×1 Technic brick with hollow studs and pin holes along the X-axis:

use <../machineblocks/lib/block.scad>;
include <../machineblocks/config/config.scad>;

machineblock(
    size = [6, 1, 3],
    studType = "hollow",
    holeX = true
);

Using Variables

Instead of entering parameter values directly into the machineblock() call, you can define variables and reference them in the module call. This approach makes your script dynamic and customizable — each variable will automatically appear in OpenSCAD’s Customizer panel, along with its description and allowed values.

This way, you can easily change values through the graphical interface without editing the source code. To show the customizer panel in OpenSCAD, select Window -> Customizer in the main menu.

use <../machineblocks/lib/block.scad>;
include <../machineblocks/config/config.scad>;

// Size of the brick in the X direction, expressed as a multiple of a 1×1 brick
sizeX = 7; // [1:32]
// Size of the brick in the Y direction, expressed as a multiple of a 1×1 brick
sizeY = 2; // [1:32]
// Height of the brick, given as the number of plates
height = 3; // [1:32]
// Type of the studs
studType = "hollow"; // [solid, hollow]
// Whether the brick should have pin holes in X-direction
holeX = true;

machineblock(
    size = [sizeX, sizeY, height],
    studType = studType,
    holeX = holeX
);

Scripting in the Web Editor

You can use the same code in the web editor. However, it’s recommended to adjust the import statements by removing the ../ between < and machineblocks.

Congratulations! You just have created your first brick from scratch using OpenSCAD and MachineBlocks!