Blender API Reference

register_component(component)

Register a third party component with the Coherence API.

Component.on_registered() will be executed once successfully registered.

Parameters

component (Type[Component]) –

unregister_component(component)

Unregister a third party component from the Coherence API.

The following event chain is called on the component when unregistered:

  1. Component.on_disable() - for all instances, if currently enabled

  2. Component.on_destroy() - for all instances

  3. Component.on_unregistered()

Parameters

component (Type[Component]) –

add_component(obj, component)

Add a component to an existing object

Parameters
destroy_component(obj, component)

Remove a component from an existing object

The following event chain is called on the component when destroyed:

  1. Component.on_disable() - if currently enabled

  2. Component.on_destroy()

If there is a linked Unity component that will also be destroyed through Unity’s API.

Parameters
class Component(obj_name)
__init__(obj_name)
Parameters

obj_name (str) –

add_handler(id: str, callback)

Add an event handler for when Unity sends a custom message for this object (e.g. through a associated Unity plugin)

Parameters

  • id (str) – Unique message ID

  • callback – Callback to execute when receiving the message

add_vertex_data_stream(id: str, size: int, callback)

Add a callback to be executed every time vertex data needs to be synced.

Note

Not yet implemented

The callback has the following definition:

def callback(mesh: bpy.types.Mesh) -> Tuple[ctypes.void_p, int]:
    """
    Args:
        mesh (bpy.types.Mesh):      The evaluated mesh instance in the
                                    current Depsgraph.

    Returns:
        Tuple[ctypes.void_p, int]:  Tuple containing a pointer to the start of the
                                    vertex data array and the number of bytes per
                                    element in that array.
    """
    # ... logic here ...

Data returned by the callback must be aligned to loops for the given mesh. That is, your element count must equal len(mesh.loops)

Warning

Instancing is disabled for meshes with custom vertex data streams. Each instance will be evaluated and sent to Unity as a separate meshes.

Warning

The callback is given a temporary mesh that was created after evaluating all Blender modifiers through the active Depsgraph. The number of elements in your array must match the number of loops after the evaluation.

Parameters

  • id (str) –

  • size (int) – Number of bytes in the data stream per loop index

  • callback (callable) – Callable that returns a pointer to the data stream

property bpy_obj

Get the Blender object this component is attached onto

Avoid holding onto a reference to this value long term, as it will invalidate out from under you like other StructRNA references.

Type

bpy.types.Object

destroy()

Remove this component from the bpy_obj.

classmethod get_property_group_name() → str
Str

Name of the PropertyGroup registered to this component type

classmethod is_autobind() → bool
Bool

true if a poll method is defined on this component.

Autobind components cannot be added and removed via the Blender UI

property material_id: str

Unique identifier for the material attached to the object

If there is no bpy_obj or no active material, this returns None.

Type

Union[str, None]

property mesh_id: str

Unique identifier for the mesh attached to the object

If the object has modifiers applied - this will be unique for that object. Otherwise - this may be a common mesh name that is instanced between multiple objects in the scene.

Type

Union[str, None]

property mesh_uid

Unique identifier for the mesh associated with this object.

If a mesh is instanced between different objects and should only be evaluated once, then return the same UID between objects.

If this returns a non-None value, then on_update_mesh() must be implemented to handle the request for handling mesh data updates when the depsgraph is modified.

Returns

Union[str, None]

classmethod name() → str

str: Get common component name

property object_name: str

Name of the associated bpy.types.Object

Type

str

on_coherence_connected()

Perform any additional work after Coherence establishes a connection

on_coherence_disconnected()

Perform any cleanup after Coherence disconnects from the host.

on_coherence_start()

Called when Coherence has been started

This will be followed by on_coherence_connected() once a connection can be made.

on_coherence_stop()

Called when Coherence is stopped or the plugin is unregistered.

This will be preceded by an on_coherence_disconnected() if previously connected.

on_create()

Executes after the component has been created and synced with Coherence.

on_destroy()

Executes when the bpy.types.Object has been removed from the scene or this component has been removed from the object.

on_disable()

Perform any cleanup that needs to be done when disabling this instance

on_enable()

Perform any cleanup that needs to be done when enabling this instance

classmethod on_registered()

Perform any setup that needs to be done after loading this plugin

classmethod on_unregistered()

Perform any cleanup that needs to be done before unloading this plugin

on_update_mesh(depsgraph)

Handle mesh update events from the underlying bpy.types.Object

If the mesh is instanced across multiple objects, only one one of objects will receive this event.

Parameters

depsgraph (bpy.types.Depsgraph) – Evaluated dependency graph

property property_group

Returns: PropertyGroup|None

property property_names: list

PropertyGroup property names that can be synced

Type

list[str]

remove_all_handlers()

Remove all callbacks for inbound messages

remove_handler(id: str, callback)

Remove a callback previously added with add_handler()

Parameters

  • id (str) – Unique message ID

  • callback – Callback to execute when receiving the message

Raises

KeyError – If the handler was not registered

remove_vertex_data_stream(id: str)

Remove a previously registered vertex data stream

Note

Not implemented

Parameters

id (str) –

property scene_obj

Get the SceneObject associated with this instance.

Type

SceneObject

send_event(id: str, size: int, data)

Send an arbitrary block of data to Unity.

Data sent will be associated with this object on the Unity side.

Parameters

  • id (str) – Unique message ID

  • size (int) – Size of the payload to send

  • data (c_void_p) – Payload to send

Returns

non-zero on failure

Return type

int