Quickstart Tutorial¶

This tutorial is designed to be followed in sequence from start to finish. Each section builds on the previous one, so complete each step before moving on. A companion video is available for each section and shows all steps in real time; step numbers are displayed on screen so you can follow along in this guide.

By the end of this tutorial you will know how to:

Install the extension and set up the presets folder.
Record a macro set using the right‑click (Direct) recording method.
Set minimum, maximum, and default value ranges on recorded properties.
Toggle between absolute and relative data paths.
Save, play back, edit, and duplicate macro sets.
Use the Last Touched method to capture property defaults for a 3‑in‑1 preset.
Append external datablocks from a .blend file into a macro set.
Save a companion .blend so a macro set is self‑contained and portable.

Installing the Extension¶

Video: Installing the extension.

Download sms_macros‑2.0.0.zip and save it anywhere on your computer.
Open Blender.
Go to Edit > Preferences in the top menu bar.
In the Preferences window, navigate to Get Extensions.
Click the small expand icon in the top‑right corner of the Get Extensions page and choose Install from Disk…
Browse to the folder containing sms_macros‑2.0.0.zip, select it, and click Install from Disk.
Optionally, click Save Preferences so the extension remains enabled the next time you open Blender.

Installing the Macro Presets¶

Video: Installing presets.

Before you can record or play back any macro set, the extension needs to know where to store its JSON files. This is a one‑time setup.

Open the N‑Panel in the 3D Viewport by pressing N.
Click the SMS Macros tab to reveal the three panels.
Expand the Options panel.
You will see two buttons, choose one:

Install Presets
Copies the built‑in example macro sets into a new folder next to the extension. This is the fastest way to get started and gives you working examples to explore.

Change Folder
Opens a file browser so you can point the extension at an existing folder of your choice. Use this if you already have macro sets from a previous install, or if you want to store presets in a specific location (e.g. a synced cloud folder).

Once a valid folder is in place, the Options panel shows the full set of management buttons and both the Recorder and Player panels become fully functional.

Note

You only need to do this once. The folder path is stored in assets/presets_location.json inside the extension directory and is remembered across Blender sessions.

Record a Simple Macro Set¶

In this section you will record a small macro set that transforms the default Cube. Along the way you will use the right‑click recording method, set a random range on a property, and toggle the path type so the set works on any object.

Note

Start from Blender’s default scene so that the Cube object is present and selected. If you have already modified the scene, use File > New > General to reset it. If you do not have the default Cube in the scene, add it via Add > Mesh > Cube in the 3D Viewport.

Video: Recording a simple macro set.

Start a New Recording¶

Press N to open the N‑Panel, then click the SMS Macros tab.
Expand the Recorder panel.
Click Start Recording. The button turns on and reads Recording Active. The Last Touched Actions and Object Data sub‑panels appear below it.

Record Using Right‑Click¶

The right‑click method captures a property or button the moment you interact with it. It is ideal for sliders, number fields, and any setting in the Properties panel.

Select the Cube to make sure it is the active object.
In the Properties panel, click the Object Properties tab (the orange square icon).
Expand the Transform section if it is not already open. You should see the Location, Rotation, and Scale fields.
Right‑click on the Location field and choose Add Macro Entry from the context menu.

A macro cache entry named location now appears in the Recorded Macros list.

Repeat step 4 for Rotation and Scale.

The Recorded Macros list should now contain three entries: location, rotation, and scale.

Setting a Random Range¶

Now that the Cube’s transform properties are recorded, you can assign a minimum and maximum value to each so the Player can choose a random value when the set is replayed.

Select the 0: location entry from the Recorded Macros dropdown.
The Property Details sub‑panel expands below the list, showing a live widget with the current location value of the Cube.
In the live widget, set X to 5 and Y to 5.
Click Set Max to store 5, 5, 0 as the maximum value.
In the live widget, set X to -5 and Y to -5.
Click Set Min to store -5, -5, 0 as the minimum value.
Select the second entry (1: rotation) and set the Min and Max ranges as desired.
Select the third entry (2: scale) and set the Min and Max ranges as desired.

The Min, Max, and Default labels alongside the buttons update to reflect your stored values. When you play the set with Recall Type → Random, each property will be set to a random value between its Min and Max.

Toggle Paths¶

Click Toggle Paths.

Notice that the Command for each entry in the Recorded Macros list changes from an explicit path such as:

bpy.data.objects['Cube'].location = (0.0, 0.0, 0.0)

to a relative path:

bpy.context.object.location = (0.0, 0.0, 0.0)

This means the set will now apply to whichever object is active at playback time, not just the Cube.

Tip

Toggle Paths converts all compatible entries at once. To toggle a single entry, use the Toggle Path Type button (the chain‑link icon) inside the Property Details sub‑panel. Use the per‑entry toggle when only some entries in your set should be relative.

Note

Some deeply nested properties, particularly those inside modifier panels or node sockets, cannot be represented as a bpy.context.* path. If the toggle fails for an entry, keep that entry on its absolute path and ensure the referenced datablock exists in the scene before running the set.

Save the Macro Set¶

In the Save Macro Set box, tick the + (New Category) toggle next to the Category field.
Type Tutorial in the Category field.
Type Transforms in the Subcategory field.
In the Name field, type Transform Active.
Optionally, add a short Description such as Transform the active object.
Click Save Set.

The JSON file is written to <your presets folder>/Tutorial/Transforms/Transform Active.json. The Recorder cache clears automatically and the Player panel updates to show the new set.

Play Back the Macro Set¶

Video: Recalling a macro set.

Expand the Player panel.
In the Category dropdown, choose Tutorial/Transforms.
Select Transform Active from the Macro Set dropdown.
In the Playback Controls section, set Recall Type to Random.
Click Run Set.

The Cube (or whichever object is active) will be translated, rotated, and scaled within the random ranges you set earlier.

Run the set several more times, you will see different transforms applied each time.

Try selecting another object, or multiple objects such as the light and camera, then run the set again. The random transforms will now be applied to each of those objects.

Tip

Use the Step button (the right‑arrow icon next to the Entries dropdown) to execute the set one entry at a time. This is useful for debugging or when you only need part of the set to run.

Edit a Macro Set¶

In this section you will edit an existing macro set.

Note

If a macro set depends on any datablocks (such as materials, modifiers, or objects) that are not yet in the scene, first run the set with default settings to ensure all referenced objects are present before editing.

Video: Editing a macro set.

Expand the Player panel.
In the Category dropdown, choose Tutorial/Transforms.
Select Transform Active from the Macro Set dropdown.
Click Edit. The macro set is loaded into the Recorder panel.
Expand the Recorder panel and review the entries loaded into the Recorded Macros cache.
Select the entry marked 2: scale.
Use the live widget to enter a new minimum value.
Click Set Min.
Click Save Set.
Click OK to overwrite the existing macro set.
In the Player panel, re‑select the macro set (steps 1–3).
Select the entry marked 2: scale and expand the Entry Details header.
Confirm that the Min value has been updated.
Set an active object and run the set to verify the change.

Duplicate a Macro Set¶

In this section you will duplicate a macro set to create a variation based on an existing set.

Video: Duplicating a macro set.

Expand the Player panel.
In the Category dropdown, choose Tutorial/Transforms.
Select Transform Active from the Macro Set dropdown.
Click Copy. A new macro set named Transform Active_copy1 is created. Select it in the Macro Set dropdown.
Click Edit. The macro set is loaded into the Recorder panel.
Expand the Recorder panel and review the entries loaded into the Recorded Macros cache.
In the Recorded Macros list, select the entry 1: rotation and click the Delete Entry (trash icon) button. Repeat for the 2: scale entry so that only the 0: location entry remains.
In the Save Macro Set box, update the Name to Scatter XY, optionally add a new Description, and click Save Set.
In the Player panel, set the Category to Tutorial/Transforms and select Scatter XY from the Macro Set dropdown.
Make sure there is an active object and run the set to test it.
Duplicate the active object several times and select all copies. Make sure All Selected is enabled.
Click Run Set again and note that all selected objects now scatter randomly within the range set earlier.

Define Multiple Ranges¶

Value ranges are not limited to randomisation. You can also use them to create 3‑in‑1 presets that store Low, Medium, and High variants of the same settings. In this section you will create a macro set that stores render preview presets using the Min (Low), Default (Medium), and Max (High) slots. You will also use the Last Touched recording method to quickly capture the default values.

Video: Taking advantage of min/max/default playback.

Expand the Recorder panel and click Start Recording.
In the Last Touched Actions header, click the X next to the dropdown to clear any previous entries.
Each property you interact with will be added to the sequence using its current value as the default. Start by setting the Viewport Shading to Rendered and configuring your default Viewport shading values.
In Scene Properties, select your default Render Device, Sampling settings, and Denoise settings.
Once you have set all the properties you want to include, click Get Last Touched in the Recorder panel.
The dropdown populates with temporary entries. Expand it to verify that all expected properties were captured.
Click Add Sequence. All compatible entries are copied to the Recorded Macros cache.
For each entry where you want a Low and High variant, select it, adjust the live widget to the desired value, and click Set Min or Set Max to store it.
In the Save Macro Set box, tick the + (New Category) toggle next to the Category field.
Type Tutorial in the Category field.
Type Render Preview in the Subcategory field.
In the Name field, type Cycles 3 in 1.
Optionally, add a short Description.
Click Save Set.
In the Player panel, select the set you just created.
Set Recall Type to Default and click Run Set. The default render settings are restored.
Set Recall Type to Min and click Run Set. The low render settings are restored.
Set Recall Type to Max and click Run Set. The high render settings are restored.

Append Datablocks¶

In this section you will:

Create a material and Geometry Nodes setup, then save the file.
From a new scene, append the Geometry Nodes setup and material, set some values, and create a macro set.
Edit the created set and toggle paths so the macro set works on any mesh object, not just objects named Cube.

Append Datablocks: A. Create an Asset File¶

Note

Video: Create the file that includes datablocks to append from.

On the Cube, rename the material to tutorial_mat.
In the Shader Editor, recreate the on‑screen node setup.
Add a new Geometry Nodes modifier, create a new node group, and name it tutorial_nodes.
In the Geometry Nodes Editor, recreate the on‑screen node setup.
Save the file and name it append_file.blend.

You now have an external file to use as a source for append macro entries.

Start a new scene: File > New > General.

Append Datablocks: B. Create a Macro Set¶

You will now create a macro set that appends the material and Geometry Nodes setup, then attaches them to an object named Cube using the Data Path method.

Video: Create a new macro set that appends datablocks from an external file.

In the Recorder panel, click Start Recording.
Click Append Asset. A file browser opens.
Navigate to append_file.blend, select it, and click Append Asset.
In the Pick Asset to Append dialogue, select None in the filter to deselect all assets.
Select only the material tutorial_mat and the node tree tutorial_nodes, then click OK. The assets are appended to the current file and two entries are added to the Recorded Macros list.
Next, link the material and Geometry Nodes to the active object:
1. Select the Cube to make it the active object.
2. Go to Properties > Material Properties and assign tutorial_mat in slot 1.
3. In the Object Data header of the Recorder panel, click Set Material. A new entry is added.
4. In Properties > Modifier Properties, click Add Modifier > Geometry Nodes, then select tutorial_nodes from the node tree dropdown.
5. In the Object Data header of the Recorder panel, click Set Geonode. A new entry is added.

Note

You should now have four entries in the Recorded Macros list: the first two append the datablocks, and the last two link them to the active object.

Record values on tutorial_nodes and tutorial_mat and set their ranges to match the on‑screen setup.
In the Save Macro Set box, tick the + (New Category) toggle next to the Category field.
Type Tutorial in the Category field.
Type Append in the Subcategory field.
In the Name field, type Append Assets.
Optionally, add a short Description.
Click Save Set.
The macro set contains explicit references to named datablocks, so the extension offers to save a companion file. For this section you are appending from an external file, so a companion is not needed. Deselect Save companion .blend and click OK.
Start a new scene: File > New > General.
Make sure the default Cube is active and set the viewport shading to Material Preview or Rendered.
In the Player panel, set the Category to Tutorial/Append and select Append Assets from the Macro Set dropdown.
Click Run Set. The Cube now has the appended material and Geometry Nodes setup linked.
Click Run Set several more times and note that the property values randomise each time.

Note

No duplicate datablocks are created when running the set multiple times because the No Duplicates property is enabled by default. To create a fresh copy of the appended datablocks on each run, disable No Duplicates. It is recommended to leave No Duplicates on for most macro sets.

Append Datablocks: C. Toggle Paths¶

You will now edit the macro set to use relative paths so that it works on any active mesh object rather than only objects named Cube.

Video: Edit a macro set to change the path type from data to context.

Start a new scene: File > New > General.
In the Player panel, set the Category to Tutorial/Append and select Append Assets from the Macro Set dropdown.
Expand the Requirements header.
Delete the default Cube. Make sure nothing else is selected so the active object is empty.

Note

The Requirements panel now shows:

Active object required.
Object Cube must exist in the scene.

This is because one or more entries in the set explicitly reference the Cube object by name. In the next steps you will change the set so that it works on any object.

Undo (Edit > Undo) to restore the Cube, select it to make it active, then click Run Set. You are running the set first to ensure all referenced datablocks are present before editing.
In the Player panel, click Edit, then expand the Recorder panel.
In the Recorded Macros list, select entry 4: scale.

Note

The command path begins with bpy.data.objects['Cube'].... This is an explicit (absolute) reference. It can be changed to a relative reference so the set works on any active object.

In this particular set there is only one explicit reference, but other sets may have several. Currently the only way to identify explicit paths is to check each entry manually when recording or editing a set.

Click the Toggle Path Type button (chain‑link icon) to the right of the path to switch from explicit to relative.

Note

The command path now begins with bpy.context.active_object.... This is a relative reference that will work on any active object.

Click Save Set.
Click OK to overwrite the existing macro set.
The macro set contains explicit references to named datablocks, so the extension again offers to save a companion file. Deselect Save companion .blend and click OK.
Start a new scene: File > New > General.
In the Player panel, set the Category to Tutorial/Append and select Append Assets from the Macro Set dropdown.
Expand the Requirements header.
Delete the default Cube. Make sure nothing else is selected so the active object is empty.

Note

The Requirements panel now shows only:

Active object required.

Add a Monkey object: Add > Mesh > Monkey. Make sure it is active.

Note

The Requirements panel now shows:

All dependencies can be satisfied by this set.

The set is now ready to run on any mesh object.

Click Run Set several times to confirm that the set works on any active mesh object.

Save a Companion Blend¶

In this section you will create a self‑contained macro set by saving a companion .blend file alongside the JSON preset. This is a variation of the previous Append Datablocks section. Instead of appending from an external file at playback time, the required assets are bundled into a companion .blend that travels with the JSON file. This makes the macro set portable and independent of any specific external file location.

Video: Create a companion blend file that restores assets on recall from the presets folder.

Open append_file.blend saved in Append Datablocks: A. Create an Asset File, or recreate it.
Verify that tutorial_nodes and tutorial_mat are linked to the Cube object.
In the Recorder panel, click Start Recording.
Link the material and Geometry Nodes to the active object:
1. Select the Cube to make it the active object.
2. In the Object Data header of the Recorder panel, click Set Material. A new entry is added.
3. In the Object Data header of the Recorder panel, click Set Geonode. A new entry is added.

Note

You should now have two entries in the Recorded Macros list. One that links the material and one that links the Geometry Nodes tree to the active object.

Record values on tutorial_nodes and tutorial_mat and set their ranges to match the on‑screen setup.

Note

When recording entry 4: scale, the path records as an explicit reference to the Cube object. For this example you need it to be a relative path. Click the Toggle Path Type button (chain‑link icon) to the right of the path to switch from explicit to relative.

In the Save Macro Set box, tick the + (New Category) toggle next to the Category field.
Type Tutorial in the Category field.
Type Companion in the Subcategory field.
In the Name field, type Companion Assets.
Optionally, add a short Description.
Click Save Set.
The extension offers to save a companion file. Make sure Save companion .blend is enabled and click OK.
In the Player panel, select the set you just saved and expand the Entry Details header. Note that the first entry shows it is appending from a companion file.
Start a new scene: File > New > General.
Delete the default Cube and add a Monkey object: Add > Mesh > Monkey. Make sure it is active.
In the Player panel, set the Category to Tutorial/Companion and select Companion Assets from the Macro Set dropdown.
Click Run Set several times to verify that the set works.

Note

If the requirements are not satisfied, it is likely that one or more entries still use an explicit path. Refer to Append Datablocks: C. Toggle Paths for instructions on how to resolve this.