Boxshot 3D Packaging Mockup Software
Download Download Download
Download for Windows Download for Mac Download for Mac Dropdown arrow

Solid Shapes Scripting

Boxshot supports three types of solid objects: simple, complex, and script-based.

This tutorial covers the scripting API for working with solid shapes in Boxshot.

Creating script-based solid

There’s no way to directly create a script-based solid in Boxshot. You must first create a simple or complex solid, then convert it to the script-based one. Let’s create a simple solid cylinder and explore the available options:

Simple solid cylinder object in Boxshot

Besides the normal shape parameters on the right, there is a Convert to script button at the bottom. Click it and see what happens:

Converting simple solid to the script-based one

The right panel updates: all cylinder options disappear, and the new script editor button appears. Let’s click that button to open the script editor:

Solid script editor mode in Boxshot

You’ll see two panels: the left one displays the code, while the right one shows the shape preview. This is where you edit the script and view the updated shape. We’ll cover the details below; meanwhile, simply try replacing 10 with 20 in the left panel:

Adjusting the cylinder height using scripting

Boxshot automatically updates the right panel a few seconds after you finish editing the code on the left. Note that the cylinder on the right has become taller — this is because you adjusted its height in the script.

Finally, click the OK button in the bottom-right corner to confirm the changes and return to the scene:

Getting the updated solid shape back to the scene

Compare this with the initial cylinder size shown in earlier screenshots to see the difference.

That’s how you create and edit script-based solid objects in Boxshot: you create a solid shape, convert it to a script-based object, edit the script, and view the resulting changes.

You’ll likely use this feature for complex solids — especially when you already have a base shape that needs fine-tuning. However, starting with a simple solid is equally valid.

Shape-making functions

Switch back to the script editor and replace the code on the left with the following:

box(15, 10, 5);

Give Boxshot a few seconds and you’ll see the box on the right. Update the code to match the following example:

box(15, 10, 5);
box(5, 3, 10);

You will see two boxes of different colors. The box() function creates a box element as part of a solid shape. Here is the full syntax:

box(length, width, height, radius, cx, cy, cz);

The first 3 parameters are mandatory and define the box dimensions. The radius parameter specifies the edge radius, and the final three parameters define the box center. Both the radius and center parameters default to zero.

Try modifying the code to look like this:

box(15, 10, 5);
box(5, 3, 10, 1, 0, 0, 10);

You’ll see that the smaller box has rounded edges and is now placed above the larger one.

Here are all the shape-making functions in Boxshot’s solid scripting API:

box(length, width, height, radius, cx, cy, cz)
sphere(radius, cx, cy, cz)
cylinder(radius, height, edge_radius, cx, cy, cz)
prism(bottom_radius, num_edges, height, edge_radius, cx, cy, cz)
torus(radius1, radius2, cx, cy, cz)
cone(bottom_radius, height, top_radius, edge_radius, cx, cy, cz)

The parameter names are fairly self-explanatory. Edge radius and center parameters are always optional with a default value of zero.

Try using each of these functions in the script editor and see how the parameters affect the shape in the preview.

Boolean functions

Scripting simple solid shapes is thrilling — but we can take it further with boolean operations.

Here are the scripting functions for boolean operations on solids in Boxshot:

intersect(shape_a, shape_b, fillet)
add(shape_a, shape_b, fillet)
sub(shape_a, shape_b, fillet)

The first parameter — shape_a — must be another solid shape object, the second parameter — shape_b — can be either another solid shape object or an array of such objects.

The A object is particularly important only for the subtraction operation, but we maintained the consistent across all functions. This is because you may obtain different results depending on the “main” object.

The fillet parameter is optional and is zero by default. It controls the rounding of the edges added by the boolean operation — the same as when performing a boolean operation via the Tools menu.

Let’s modify the previous example with two boxes as follows:

b1 = box(15, 10, 5);
b2 = box(5, 3, 10);
b3 = sub(b1, b2, 1);

You’ll get a box with a square hole in the center. Now, try replacing the code with the following example:

b1 = box(15, 10, 5);
b2 = sphere(3);
b3 = sub(b1, b2, 1);

This time, you will see a box with a spherical hole. Now, try replacing sub with add and make the sphere a bit larger, like this:

b1 = box(15, 10, 5);
b2 = sphere(4);
b3 = add(b1, b2, 1);

You’ll end up with a box featuring a smooth spherical bump in the center, created by joining the box and the sphere.

Shapes hierarchy

Note the difference between the early script examples on this page and the later ones:

// first examples
box(15, 10, 5);
box(5, 4, 10);

// later examples
b1 = box(15, 10, 5);
b2 = box(5, 4, 10);

When we began creating scripts, we simply asked Boxshot to add a shape to the solid. Then we started using these shapes for boolean operations, which required us to track the shapes we added — so we began using variables. Each scripting functions that creates, combines or modifies shapes returns a new shape, which we can assign to a variable for later use.

Note: this is “relaxed” JavaScript — we don’t use “const” or “let” keywords to declare variables. You may use them, if you prefer, but Boxshot doesn’t require them, so we’ll omit them in this tutorial.

Now, here’s an important concept in Boxshot solid objects scripting: if you create a shape and don’t use it in any other operation, it will be displayed as is. However, if you use it in another operation, it won’t appear in the scene.

See the earlier examples where we added or subtracted box and sphere objects. You only see the resulting object in preview, not the source ones — because the source objects were consumed by the boolean operation. This behavior is straightforward, but sometimes you might want to keep the source object visible as well. Here’s how:

b1 = box(15, 10, 5);
b2 = box(5, 3, 10);
b3 = sub(b1, b2, 1);
b2.keep = true;

Note the very last line, which sets the “keep” property of the smaller box “b2” to true. This is how you keep the solid element visible even if it is used by another function. This is helpful when debugging a shape to ensure its parts are properly configured.

Moving elements around

There are a few more functions in the solid scripting API for offsetting and rotating the shapes:

move(shape, dx, dy, dz)
rotate_x(shape, angle, cx, cy, cz)
rotate_y(shape, angle, cx, cy, cz)
rotate_z(shape, angle, cx, cy, cz)
transform(shape, mat)

Each function takes a shape object as its first parameter and transforms it according to the function name. The move() function offsets the shape using the 3 offsets you specify. The rotate_x(), rotate_y(), and rotate_z() functions rotate the shape to the angle specified by the angle parameter (in degrees) around an optional center point, defined by the three optional parameters (zero by default).

Finally, the transform() function transforms the shape using a 16-element matrix that defines the transformation. You will rarely use this function directly, but Boxshot uses it when converting a complex shape to a scripted one.

Like the boolean functions described earlier, the transformation functions return the new transformed shape and hide the source shape — so only the new shape is visible in the scene.

Note that even if the source shape is hidden, it still exists and can be used in other operations. For instance, here’s how you make two holes in the box:

b1 = box(15, 10, 5); // the big box
b2 = box(3, 5, 10); // the small one
b3 = move(b2, 4, 0, 0); // make another shape by moving the small box a bit
b4 = sub(b1, [b2, b3], 0.2); // subtract both small boxes from the bigger one

// uncomment the lines below to see both small boxes
// b2.keep = true;
// b3.keep = true;

Here we create a larger box “b1”, then create a smaller box “b2” and move it along the X-axis, forming a small box “b3”. The “b2” box becomes hidden because it is used by the move() function, but we can still use it in the sub() operation. You can uncomment the two lines at the bottom of the script to see the original boxes.

Shapes parameters

Boxshot assigns random colors to the solid shape elements you create, but you can override this if needed. Here’s how:

b1 = box(15, 10, 5);
b2 = box(3, 5, 10);

b1.previewColor = "red";
b2.previewColor = "#008000";

This will make the larger box red and the smaller one dark green. You can use normal color names here or the hex codes used in HTML — both are acceptable.

Besides assigning colors, there are a few more parameters you can configure. Here’s the full list:

b1 = box(15, 10, 5);

b1.keep = true;
b1.previewColor = "red"; // preview color
b1.material = "Surface 1"; // Boxshot material name
b1.name = "Element 1"; // Boxshot mesh name
b1.smooth = 0.5; // 50% quality
b1.mapping = UV.SphericalX; // apply spherical mapping along the X axis

The material and name properties configure the name and material of the mesh created in Boxshot. This is important if you want to assign different materials to individual elements of a solid object to configure them separately.

The smooth and mapping parameters are similar to those found in the user interface when configuring a solid object. Below is the full list of possible mapping values:

These are exactly the same as in the user interface for solid objects and are similar to the UV mapping modes in the embedded model editor.

Note that scripted values override the parameters you configured in the user interface.

This is JavaScript

One more thing before we wrap up this tutorial: this is JavaScript, so you can go beyond simple line-by-line shape creation. Here’s an example of creating a box with a grid of round holes:

// first make a big flat box
b1 = box(20, 20, 2);

grid = []; // prepare the array of cylinders

// now run two loops to make a grid
for (x = -9; x <= 9; x += 3) {
    for (y = -9; y <= 9; y += 3) {
        // make a cylinder
        c = cylinder(0.8, 5, 0, x, y, 0);

        // uncomment to see the cylinders
        // c.keep = true;

        // add it to the array
        grid.push(c);
    }
}

// make the holes by subtracting the array
// of cylinders from the big flat box
b2 = sub(b1, grid, 0);

Put this script into the script editor and see the box with 49 holes.

Hint: you don’t actually need to learn JavaScript to get the most out of solid shapes scripting in Boxshot, as there are lots of AI helpers around. Feed this tutorial and this script example to your favorite AI and ask it to modify the script for your tasks. It might not work right away, but it usually does. At least give it a try :)

That’s it!

That’s pretty much it. You’ve learned to create simple solid elements, move them around, and combine them using boolean operations — or leave them as they are, depending on your needs. You can also setup various parameters, like texture mapping or material names, so you’re now ready to make something special!

More Tutorials

Rendering

Materials

Features

Shapes