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: str)
__init__(obj_name: str)
Parameters

obj_name (str) –

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.

draw(layout)

Draw the component panel in Blender’s UI

This can be overridden per-component to create a custom panel

Parameters

layout (bpy.types.UILayout) – Parent layout to draw into

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

classmethod name() → str

str: Get common component name

property object_name: str

Name of the associated bpy.types.Object

Type

str

on_after_depsgraph_updates(depsgraph)

Executed after all depsgraph updates have been processed

Parameters

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

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(depsgraph, update)

Handle a depsgraph update for the linked bpy.types.Object

Parameters
property property_group

Returns: PropertyGroup|None

property property_names: list

PropertyGroup property names that can be synced

Type

list[str]

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

update_all_properties()

Push all associated PropertyGroup properties to Coherence

update_property(name: str, value)

Update a property shared between synced components.

This is typically called as an event handler on Blender prop changes but can be called directly with the caveat that the value may be overridden by the Blender UI.

Parameters

  • name (str) – Unique property name

  • value (mixed) – Native property value (bool, int, list, etc)

Raises

TypeError – If the value cannot be converted to a supported property type