The ShuffleScript Manual

ShuffleScript (.shuf) is a plain-text, line-by-line recipe for building 3D models in ShapeShuffle. Every button click, drag, and resize is logged as a readable text command.

1. Core Concepts

ShuffleScript is simple by design: no variables, loops, or complex functions. You can read a script top-to-bottom and understand exactly what it builds.

• Permanent Object IDs: Every shape gets a permanent number (e.g. #1, #2) upon creation. Numbers count up continuously and are never reused, even if an object is deleted.
• Active Selection: Most commands act on selected objects. Use select N (or select 1 2 3) to pick targets, or select all for everything. Creating a new shape automatically selects only that shape.
• Units & Axes: All dimensions are in millimeters. X and Y form the floor plane; Z is always height. New shapes start resting on the floor grid (Z=0).
• Named vs Positional Arguments: Commands accept positional values (move 10 0 5) or explicit axis names (move x:10 z:5).
• Syntax Rules: One command per line. Line spacing and indentation do not matter. Anything after # or // is ignored as a comment.

2. Adding Shapes

Use add <shape> to place a new primitive at the origin. Creating a shape automatically makes that shape the new selection.

3. Moving & Rotating

Transformations act on all currently selected objects around their collective center point.

• move X Y Z — Nudge position relative to current location (e.g. move z:10).
• moveto X Y Z — Move to absolute floor coordinates. Use * to keep an axis unchanged (e.g. moveto 0 * 15).
• rotate AXIS DEG [FRAME] — Pivot around selection center. Set FRAME to world (default) or object for local axes.
• mirror AXIS [FRAME] — Reflect selection across an axis (X, Y, or Z).
• drop — Rest the lowest point of the selection onto the floor bed (Z=0).

4. Object Properties

These commands modify single selected objects:

• size X Y Z — Sets exact width (X), depth (Y), and height (Z) in mm.
• radius R — Rounds corners by R mm. (Supported on boxes, cylinders, cones, pyramids, wedges, and N-gons).
• makehole / makesolid — Toggles whether the selected object acts as a solid or a cutting tool.
• content TEXT — Updates text string on 3D text objects (e.g. content Hello World).
• params ... — Customizes parametric shapes:
  • Screw: params DIAMETER PITCH LENGTH [CLEARANCE] (clearance: exact, tight, normal, loose)
  • Gear: params TEETH MODULE WIDTH BORE KEYWAY(0/1)
  • Torus: params THICKNESS FIXED(0/1) ADVANCED(0/1)

5. Combining & Modifying

• combine [N1 N2...] — Fuses solids together and subtracts any holes in the group. If numbers are omitted, acts on current selection. The result receives a new permanent ID.
• overlap [N1 N2...] — Intersects shapes, keeping only shared volume (requires at least 2 solids). Cannot be split.
• split — Restores original pre-combine shapes from history for the selected object.
• copy — Duplicates selected objects in place (zero offset).
• delete — Permanently removes selected objects from the scene.

6. Pins & Mesh Imports

• pin X Y / unpin X Y — Adds or removes visual floor alignment markers (does not affect model geometry).
• import LABEL ... end import — Embeds external STL/OBJ mesh data as raw vertex coordinates (generated automatically by the Import tool).

7. Worked Example

# Create a plate
add box                # id:1
size 100 60 30

# Create a cutting cylinder
add cylinder           # id:2
size 20 20 40
rotate x 90
move z:15
makehole

# Combine into a plate with a hole
select 1 2
combine                # id:3
drop

# Duplicate the plate
select 3
copy                   # id:4
move x:150             # Shift copy to the side

# Split original back into parts
select 3
split                  # id:5,6 (original box and hole cylinder restored)