Methods

Alongside the exposed player and scene variables that are documented in the previous chapter, there are several methods you can use to control Blender and OmniStep:

System Methods

self.display_message(message, time=None)

Displays a message at the bottom of the viewport. The message style and duration can be set in the add-on preferences.

Parameters

message (string) - String to display.
time (float) - Display Time in Seconds (None defaults to Add-on Prefs).

self.local_import(import_string)

Used in the imports method to import modules. Refer to the Scripting Introduction for details.

Parameters

import_string (string) - import string, e.g.: 'import numpy as np'.

self.add_property(name, kind, value=None)

Used in the custom_ui method to expose parameters to the UI. Refer to the Scripting Introduction for details.

self.add_label(name)

Used in the custom_ui method - Adds a text label to the UserScript UI Panel

Scene Methods

The scene methods are primarily concerned with collisions and ray casting.

There are two collision BVH-trees active in OmniStep. The first is built when the operator starts, including objects according to the collision settings. For the scripting module, there is a second dynamic BVH-tree. This tree is rebuilt every time an object is added, updated, or removed. Try to minimize calls to this function. Also, be sure to exclude any collision objects you want to control with scripts from the default collision system, such as by excluding a collection holding the objects.

When you have many objects that require dynamic collisions, one trick is to put them in a collection, exclude it, and have another object with a geometry node modifier that joins all the collection objects into one. Don't forget to set a 'Realize Instances' node at the end of the node tree. You can then use this new object with set_dynamic_collider, as it is much faster to add one heavy object than a thousand small ones.

Updating the collision system every frame is only feasible for a handful of simple objects. For more complex setups, you need to carefully consider when to call set_dynamic_collider.

self.scene.set_dynamic_collider(obj, full_evaluation=False, include_children=False, recursive=False)

Adds or updates an object as collider. If the object is changing, use this when it is modified. Try to keep the use of this to a minimum, as it rebuilds all user-set dynamic colliders into one BVH-tree when called.

Parameters

obj (Object) - Object to be added to the collision system.
full_evaluation (bool) - When True, the objects modifiers, constraints, and other procedural edits are considered. When False, only the base mesh data will be used. If you are using Geometry Nodes, you sometimes need a 'Realize Instances' node at the end, in order for the geometry to be valid.
include_children (bool) - When True, the first level children of the object are included.
recursive (bool) - When True, all children are included.

self.scene.remove_dynamic_collider(obj, include_children=False, recursive=False)

Removes an object from the collision system. Try to keep the use of this to a minimum, as it rebuilds all user-set dynamic colliders into one BVH-tree when called.

Parameters

obj (Object) - Object to be removed from the collision system.
include_children (bool) - When True, the first level children of the object are included.
recursive (bool) - When True, all children are included.

self.scene.clear_dynamic_colliders()

Clears all dynamic colliders.

self.scene.ray_cast(pos, vec, distance=1.84467e+19)

Casts a ray into the scene. This is magnitudes faster than the blender scene raycast, as it uses only the internal BVH-tree. It respects only objects that are part of OmniStep's collision system, both dynamic and static. If a collection is excluded in the 'Collision' section, this method will ignore it as well.

Parameters

pos (Vector) - Ray origin.
vec (Vector) - Ray direction.
distance (float) - (Optional) maximum distance.

Return

location, normal, index, distance (Vector, Vector, int, float)
Values will all be None if no hit is found.

self.scene.find_nearest(pos, distance=1.84467e+19)

Find the nearest point to a test point.
It respects only objects that are part of OmniStep's collision system, both dynamic and static. If a collection is excluded in the 'Collision' section, this method will ignore it as well.

Parameters

pos (Vector) - Ray origin.
distance (float) - (Optional) maximum distance.

Return

location, normal, index, distance (Vector, Vector, int, float)
Values will all be None if no point is found.

Player Methods

self.player.apply_impulse(vec, clear_velocity=False)

Applies an impulse to the player, e.g. for jump pads or impact response.

Parameters

vec (Vector) - Direction and magnitude of the Impulse.
clear_velocity (bool) - When set to 'True' the player does not keep the current momentum.

self.player.set_position(pos, clear_velocity=False)

Set the player position

Parameters

pos (Vector) - Target position.
clear_velocity (bool) - When set to 'True' the player does not keep the current momentum.

self.player.spawn(obj=None, set_active=True)

Respawns the player

Parameters

obj (Object) - When an Empty is supplied, the player will spawn there. Otherwise it will fallback to the default spawn.
set_active (bool) - When the obj is a Camera, it will be set as new active camera.

self.player.ray_cast(pos, vec)

Ray-cast against the player collider.

Parameters

pos (Vector) - Ray origin.
vec (Vector) - Ray direction.

Return

location, normal, distance (Vector, Vector, float)
Values will all be None if no hit is found.

self.player.override_move_input(input_x=None, input_y=None, input_z=None)

Override the movement input. Can be used to redirect the data.input - e.g. 'Pick and Place Scripting Example'. Can also be used to control the player by code.

Parameters

input_x (float) - Local X-Axis movement (-1.0 to 1.0)
input_y (float) - Local Y-Axis movement (-1.0 to 1.0)
input_z (float) - Local Z-Axis movement (-1.0 to 1.0)

self.player.override_look_input(delta_pitch=None, delta_yaw=None, delta_roll=None)

Override the look input. Can be used to redirect the data.input - e.g. 'Pick and Place Scripting Example'. Can also be used to control the player by code.

Parameters

delta_pitch (float) - Delta pitch in radians
delta_yaw (float) - Delta yaw in radians
delta_roll (float) - Delta roll in radians (When in 'Fly' mode with 'Trackball Rotation')

self.player.align_root(normal, limit_deg=None)

Can be used to change the root alignment of the player - e.g. tilt the player to walk on walls. (Example coming soon to the UserScripts Section)

Parameters

normal (Vector) - new player 'Up' vector. Default is (0,0,1)
limit_deg (float) - tilt limit in degrees

self.player.set_fov(fov=None, seconds=None)

Change the player field-of-view.

Parameters

fov (float) - new target fov in mm. When None it reverts to the starting value
seconds (float) - Smooth transition time in seconds. When None the change is instant.

Utility Methods

The utility methods are built on blenders pyhton api. They simplify common tasks that can be useful with OmniStep.

self.util.duplicate_obj(obj, target_collection=None, deep_copy=False, include_children=False, recursive=False, clear_animation=False)

Duplicates an object.

Parameters

obj (Object) - Object to duplicate.
target_collection (Collection) - Optional target collection.
deep_copy (bool) - Defaults to False - it behaves like 'Duplicate Linked' in blender. When True it makes a 'normal' duplicate where the object data is also duplicated.
include_children (bool) - When True, the first level children of the object are included.
recursive (bool) - When True, all children are included.
clear_animation (bool) - Clear any keyframed animation from the object.

Return

new_object (Object)

self.util.delete_obj(obj, include_children=False, recursive=False)

Deletes an object.

Parameters

obj (Object) - Object to delete.
include_children (bool) - When True, the first level children of the object are included.
recursive (bool) - When True, all children are included.

self.util.align_to_obj(source, target, mode='lrs')

Aligns an object position / rotation / scale to another object.

Parameters

source (Object) - The object to be transformed.
target (Object) - The target object.
mode (string) - (Optional) Can be lrs, rs, s.. or any combination of the letters. They stand for 'location' 'rotation' and 'scale'.

self.util.align_to_ray(obj, pos, direction, forward='Y', up='Z')

Aligns an object position and rotation to a ray.

Parameters

obj (Object) - The object that will be transformed.
pos (Vector) - Ray origin.
direction (Vector) - Ray direction.
forward (string) - (Optional) Forward vector for the transform.
up (string) - (Optional) Up vector for the transform. (Can't be the same as forward!)

self.util.translate_obj(obj, vec, space='local')

Translates an object by a vector.

Parameters

obj (Object) - The object that will be translated.
vec (Vector) - Translation vector.
space (string) - (Optional) Can be either local or global.

self.util.rotate_obj(obj, angle, axis, origin, space='global')

Rotates an object around an axis.

Parameters

obj (Object) - The object that will be rotated.
angle (float) - Angle in radians
axis (Vector) - Rotation vector
origin (Vector) - Rotation axis
space (string) - (Optional) Can be either local or global.

self.util.ray_cast_obj(obj, pos, vec)

Ray cast an object. This does NOT using OmniSteps internal BVH-tree, therefore It is not faster than a native Blender call. But in contrast to the native blender api call, it takes care of transforming the ray into object space.

Parameters

obj (Object) - The object to cast against.
pos (Vector) - Ray origin.
vec (Vector) - Ray direction.

Return

location, normal, distance (Vector, Vector, float)
Values will all be None if no hit is found.

self.util.insert_transform_keys(obj, scene_frame=None, interpolation='LINEAR')

Inserts a keyframe for location, rotation and scale.

Parameters

obj (Object) - The object to keyframe.
scene_frame (int) - (Optional) The scene frame where to insert the keyframes.
interpolation (string) - (Optional) The interpolation type. See Beztriple Interpolation Mode Items for a full list.

self.util.insert_vis_keys(obj, state, scene_frame=None)

Inserts two visibility keyframes; 'hide_viewport' and 'hide_render' effectively hiding or showing the object. Usually has to be used in pairs - e.g. False for data.scene.current_frame and True for data.scene.current_frame + 1

Parameters

obj (Object) - Target object.
state (bool) - Show or Hide.
scene_frame (int) - (Optional) Frame to insert to.

self.util.clear_collection(target_collection)

Deletes all objects inside this collection.

Parameters

target_collection (string) - Collection name.

self.util.get_collection_objs(collection, type_filter=None, include_children=False, recursive=False)

Returns a list with references to all objects inside the collection.

Parameters

target_collection (string) - Collection name.
filter (string) - (Optional) Filter objects based on their content. Supported types are: 'MESH', 'CURVE', 'SURFACE', 'META', 'FONT', 'ARMATURE', 'LATTICE', 'EMPTY', 'GPENCIL', 'CAMERA', 'LIGHT', 'SPEAKER', 'LIGHT_PROBE'.
include_children (bool) - When True, the first level children of the object are included.
recursive (bool) - When True, all children are included.

Return

objects (list)

self.util.get_children(obj, recursive=False)

Returns a list with references to all children of the object.

Parameters

obj (Object) - Object.
recursive (bool) - When True, all children are included.

Return

objects (list)

self.util.insert_camera_keys(frame=None, mute_tracks=True)

Manually insert transform keys for the active camera.

Parameters

frame (int) - Frame to insert the key. When None the current frame is used. mute_tracks (bool) - muting the tracks is recommended when the camera is active.

self.util.insert_camera_fov_key(mute_tracks=True)

Manually insert a field-of-view key for the active camera on the current frame.

Parameters

mute_tracks (bool) - Muting the tracks is recommended when the camera is active.

self.util.clear_obj_animation(obj)

Clears any keyframes for location, rotation_euler, rotation_quaternion and scale

Parameters

obj (Object) - Object to clear.

self.util.get_shader_node(obj, node_name, material_name=None)

Gets a reference to a shader node.

Parameters

obj (Object) - Object with an assigned material.
node_name (string) - Name of the node to get. material_name (string) - Material name. When None the active material is used.

Return

node (bpy.types.ShaderNode)