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)
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.
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.
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)
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.
self.scene.remove_dynamic_collider(obj)
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.
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.
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.
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.respawn(obj=None)
Respawns the player
Parameters
obj (Object) - When an Empty is supplied, the player will spawn there. Otherwise it will fallback to the default spawn.
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.
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)
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.
Return
new_object (Object)
self.util.delete_obj(obj)
Deletes an object.
Parameters
obj (Object) - Object to delete.
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.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(target_collection, filter=None)
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'.
Return
objects (list)