Scripting Introduction

OmniStep supports custom scripts that run in parallel with the operator, enabling users to implement new functionality. Those familiar with Unity will quickly grasp the concepts, and even if you are not, it’s straightforward.

This section documents the specifics of accessing OmniStep's data and methods, but it is not limited to this. You can use scripts to access and modify all aspects of Blender, just as in normal Python scripts.

If you want to jump right in, visit the UserScript Samples and Demo Scenes to study and modify various code examples.

Creating a New Script

First, you need to create the script text data block. Enable the 'Scripting' section and press Create Template to start:

Open a new area, set it to 'Text Editor' and select the newly created script to see and edit it:

Every script that works with OmniStep must be based on this template. You can remove or add methods, but the class CustomUserScript(UserScriptBase) is mandatory.

Custom UI Parameters

You can create custom UI parameters that are automatically exposed in the Sidebar. The template already includes an empty string variable. To give it a value, write Hello World in the UI field, and press Write Parameters:

Once the parameters are written, you'll see line 5 change from this:

def custom_ui(self):
    self.add_property('my_string', 'STRING')

to this:

def custom_ui(self):
    self.add_property('my_string', 'STRING', 'Hello World')

The value is now written to the script, but you can override it in the UI, which takes precedence over the script's value:

Overrides make it easy to test and iterate faster, only writing the values when needed.

Supported UI Parameters

OmniStep supports the following types: STRING, BOOLEAN, FLOAT, VECTOR, COLOR, OBJECT and COLLECTION. When you added new variables to the script, press Read Parameters to update the UI.

After changing the parameters in the UI, use Write Parameters to write the values back to the script:

Here is a full list of supported parameters:

def custom_ui(self):
    self.add_property('my_string_var', 'STRING')
    self.add_property('my_bool_var', 'BOOLEAN')
    self.add_property('my_float_var', 'FLOAT')
    self.add_property('my_vector_var', 'VECTOR')
    self.add_property('my_color_var', 'COLOR')
    self.add_property('my_obj_var', 'OBJECT')
    self.add_property('my_collection_var', 'COLLECTION')

Importing Modules

Imports are handled slightly differently in OmniStep. There is a dedicated imports method:

def imports(self):
    self.local_import('import bpy')
    self.local_import('from mathutils import Vector, Quaternion, Matrix')
    # add more entries as needed:
    self.local_import('import numpy as np')

Any imports you want for your script need to be placed in the imports method like this. Don't place them at the top of the file!