Macros & Reuse

Macros are an advanced feature for packaging a sequence of cuts so you can replay it with a single command. While you can use them for simple repetition like a pavilion break, they are most powerful when defining complex gem outlines using the Centerpoint-Angle Method (CAM).

Anatomy of a macro

define Name(parameter = default, ...) {
  # Optional docstring lines that explain the intent.
  STATEMENTS...
}

Name – any identifier. The studio treats names case-insensitively.
Parameters – always named (key = value when you call the macro). Defaults are optional.
Body – regular FSL statements. Use ${parameter} to inject values.

Inside the macro you can run set, let, assert, facet commands—anything you would normally write by hand. Once the macro ends, any temporary variables disappear.

Calling a macro

Invoke a macro with $Name(key = value, ...). Every argument is explicit, which keeps macros readable and avoids guessing which number corresponds to what.

$CrownRing(tier = "C1", angle = 32.5)

If you skip a parameter, the default from the definition (or inline placeholder) is used instead. Macros are also the best place to guard your design with assert statements—for example, to stop the interpreter if a caller passes an angle outside the safe range.

Full example

The snippet below defines a macro that cuts two crown rings and checks the parameters before it runs. Paste it into the studio and tweak the angles to see how the macro behaves.

set name "Macro Tour"
set gear 96
set girdle 3.5

P1 0 @ 41.8 : 0.18 x8
P2 6 @ 39.4 : mp(P1) x8

G1 0 @ 90 : size x16

let crown_target = mp(G1)

define CrownRing(tier, angle = 32.0, target = crown_target) {
  # Validate the inputs before cutting
  assert ${angle} > 0 "Crown angle must be positive"
  assert ${angle} < 35 "Keep crown angles below 35 degrees"
  ${tier} up 0 @ ${angle} : ${target} + girdle x16
}

$CrownRing(tier = "C1", angle = 32.4)
$CrownRing(tier = "C2", angle = 28.6)

Use macros sparingly—just enough to remove repetition without hiding what the stone is doing. For everyday tips on statements and expressions, revisit the earlier chapters; for advanced point tricks, head to Facets and Tiers.

CAM system macros

Looking for the built-in CAM helpers such as $Rect, $SquareTr, $Shield, or $TriCushTr? They now live in the System Macros appendix, complete with parameter tables and usage examples. Browse that chapter whenever you need a refresher on the available macros or want to drop one into a new design.

User Macros

In addition to defining macros within a single design file, you can also create User Macros that persist across all your projects. This is perfect for defining your own utility functions, constants, or setup code that you find yourself writing repeatedly.

To access this feature:

Open the workspace menu (hamburger icon).
Select User Macros.
Enter your FSL code in the dialog and click Save.

This code will be automatically prepended to every script you run in the studio. For example, if you define let magic_angle = 42 in your user macros, you can use magic_angle in any design without redefining it.

Note: If an error occurs within your user macro code during execution, the error message will indicate that it happened inside the macro. Line numbers for errors in your main script are automatically adjusted to account for the prepended macro lines.