Event Reference#

All omni.kit.usd.layers events are global events that can be observed using the carb::eventdispatcher::IEventDispatcher. These events are dispatched when significant changes occur to layers, layer stacks, live sessions, and other layer-related operations in the USD Layers system.

Since all events exist in a global namespace, USD Layers event descriptors are composed as the following string:

omni.kit.usd.layers::layer:<event name>

The string <event name> is listed below for each event type.

For ease of generating the event names for use with carb::eventdispatcher::IEventDispatcher, there exist functions and constants in both C++ and Python that can be used directly. The omni::kit::usd::layers::layerEventName() function will produce the event name from the omni::kit::usd::layers::LayerEventType enum. Similarly, in Python, omni.kit.usd.layers.layer_event_name will produce the event name from the omni.kit.usd.layers.LayerEventType enum.

Warning

USD Layers events have a global name, but typically listeners care about a specific layers instance. Therefore it is very important to specify a filter when observing an event, otherwise your observer will be called for all layers instances. The omni.kit.usd.layers.Layers.get_event_key() (Python) and omni::kit::usd::layers::ILayersInstance::getEventKey() (C++) helper functions exist to provide easy means to filter these events.

Layer State Events#

Layer State Events are queued when layer states change and are dispatched during the Main RunLoop’s Update event (at default priority).

Layer Info Changed#

Queued when layer metadata information is modified.

  • C++ Constant: omni::kit::usd::layers::layerEventName(LayerEventType::eInfoChanged)

  • Python Constant: omni.kit.usd.layers.layer_event_name(LayerEventType.INFO_CHANGED)

  • String event name: omni.kit.usd.layers::layer:info_changed

Arguments:

  • layer_identifier (string) - The identifier of the layer whose metadata changed.

  • val (list[string]) - List of metadata tokens that were modified.

  • context (uintptr) - The UsdContext handle representing the Layer, typically used as a filter parameter. Accessible via omni::kit::usd::layers::ILayersInstance::getEventKey() or omni::usd::UsdContext::getEventKey() (C++), or omni.kit.usd.layers.Layers.get_event_key() or omni.usd.UsdContext.get_event_key() (Python).

The following metadata tokens are currently tracked:

  • UsdGeom.Tokens.upAxis

  • UsdGeom.Tokens.metersPerUnit

  • Sdf.Layer.StartTimeCodeKey

  • Sdf.Layer.EndTimeCodeKey

  • Sdf.Layer.FramesPerSecond

  • Sdf.Layer.TimeCodesPerSecond

  • Sdf.Layer.CommentKey

  • Sdf.Layer.Documentation

  • "subLayerOffsets_offset"

  • "subLayerOffsets_scale"

Layer Muteness Scope Changed#

Sent when the muteness scope of layers changes.

  • C++ Constant: omni::kit::usd::layers::layerEventName(LayerEventType::eMutenessScopeChanged)

  • Python Constant: omni.kit.usd.layers.layer_event_name(LayerEventType.MUTENESS_SCOPE_CHANGED)

  • String event name: omni.kit.usd.layers::layer:muteness_scope_changed

Arguments:

  • val (list) - List of layer identifiers whose muteness scope changed.

  • context (uintptr) - The UsdContext handle representing the Layer, typically used as a filter parameter. Accessible via omni::kit::usd::layers::ILayersInstance::getEventKey() or omni::usd::UsdContext::getEventKey() (C++), or omni.kit.usd.layers.Layers.get_event_key() or omni.usd.UsdContext.get_event_key() (Python).

Layer Muteness State Changed#

Sent when the muted/unmuted state of one or more layers changes.

  • C++ Constant: omni::kit::usd::layers::layerEventName(LayerEventType::eMutenessStateChanged)

  • Python Constant: omni.kit.usd.layers.layer_event_name(LayerEventType.MUTENESS_STATE_CHANGED)

  • String event name: omni.kit.usd.layers::layer:muteness_state_changed

Arguments:

  • val (list[string]) - List of layer identifiers whose muteness state changed.

  • context (uintptr) - The UsdContext handle representing the Layer, typically used as a filter parameter. Accessible via omni::kit::usd::layers::ILayersInstance::getEventKey() or omni::usd::UsdContext::getEventKey() (C++), or omni.kit.usd.layers.Layers.get_event_key() or omni.usd.UsdContext.get_event_key() (Python).

Layer Dirty State Changed#

Sent when the dirty state of one or more layers changes.

  • C++ Constant: omni::kit::usd::layers::layerEventName(LayerEventType::eDirtyStateChanged)

  • Python Constant: omni.kit.usd.layers.layer_event_name(LayerEventType.DIRTY_STATE_CHANGED)

  • String event name: omni.kit.usd.layers::layer:dirty_state_changed

Arguments:

  • val (list[string]) - List of layer identifiers whose dirty state changed.

  • context (uintptr) - The UsdContext handle representing the Layer, typically used as a filter parameter. Accessible via omni::kit::usd::layers::ILayersInstance::getEventKey() or omni::usd::UsdContext::getEventKey() (C++), or omni.kit.usd.layers.Layers.get_event_key() or omni.usd.UsdContext.get_event_key() (Python).

Layer Out-of-date State Changed#

Sent when the out-of-date state of one or more layers changes.

  • C++ Constant: omni::kit::usd::layers::layerEventName(LayerEventType::eOutdateStateChanged)

  • Python Constant: omni.kit.usd.layers.layer_event_name(LayerEventType.OUTDATE_STATE_CHANGED)

  • String event name: omni.kit.usd.layers::layer:outdate_state_changed

Arguments:

  • val (list[string]) - List of layer identifiers whose outdate state changed.

  • context (uintptr) - The UsdContext handle representing the Layer, typically used as a filter parameter. Accessible via omni::kit::usd::layers::ILayersInstance::getEventKey() or omni::usd::UsdContext::getEventKey() (C++), or omni.kit.usd.layers.Layers.get_event_key() or omni.usd.UsdContext.get_event_key() (Python).

Layer Lock State Changed#

Sent when the lock state of one or more layers changes.

  • C++ Constant: omni::kit::usd::layers::layerEventName(LayerEventType::eLockStateChanged)

  • Python Constant: omni.kit.usd.layers.layer_event_name(LayerEventType.LOCK_STATE_CHANGED)

  • String event name: omni.kit.usd.layers::layer:lock_state_changed

Arguments:

  • val (list[string]) - List of layer identifiers whose lock state changed.

  • context (uintptr) - The UsdContext handle representing the Layer, typically used as a filter parameter. Accessible via omni::kit::usd::layers::ILayersInstance::getEventKey() or omni::usd::UsdContext::getEventKey() (C++), or omni.kit.usd.layers.Layers.get_event_key() or omni.usd.UsdContext.get_event_key() (Python).

Layer File Permission Changed#

Sent when file permissions for one or more layers change.

  • C++ Constant: omni::kit::usd::layers::layerEventName(LayerEventType::eLayerFilePermissionChanged)

  • Python Constant: omni.kit.usd.layers.layer_event_name(LayerEventType.LAYER_FILE_PERMISSION_CHANGED)

  • String event name: omni.kit.usd.layers::layer:layer_file_permission_changed

Arguments:

  • val (list[string]) - List of layer identifiers whose file permissions changed.

  • context (uintptr) - The UsdContext handle representing the Layer, typically used as a filter parameter. Accessible via omni::kit::usd::layers::ILayersInstance::getEventKey() or omni::usd::UsdContext::getEventKey() (C++), or omni.kit.usd.layers.Layers.get_event_key() or omni.usd.UsdContext.get_event_key() (Python).

Layer Structure Events#

The following events are dispatched when layer structure and composition changes:

Sublayers Changed#

Sent when sublayers are added, removed, or reordered.

  • C++ Constant: omni::kit::usd::layers::layerEventName(LayerEventType::eSublayersChanged)

  • Python Constant: omni.kit.usd.layers.layer_event_name(LayerEventType.SUBLAYERS_CHANGED)

  • String event name: omni.kit.usd.layers::layer:sublayers_changed

Arguments:

  • val (list) - List of layer identifiers whose sublayers changed.

  • context (uintptr) - The UsdContext handle representing the Layer, typically used as a filter parameter. Accessible via omni::kit::usd::layers::ILayersInstance::getEventKey() or omni::usd::UsdContext::getEventKey() (C++), or omni.kit.usd.layers.Layers.get_event_key() or omni.usd.UsdContext.get_event_key() (Python).

Used Layers Changed#

Sent when used layers change in the stage. Used layers include all sublayers, references, payloads, and any external layers loaded into the stage. If eSublayersChanged is sent, this event will also be sent.

  • C++ Constant: omni::kit::usd::layers::layerEventName(LayerEventType::eUsedLayersChanged)

  • Python Constant: omni.kit.usd.layers.layer_event_name(LayerEventType.USED_LAYERS_CHANGED)

  • String event name: omni.kit.usd.layers::layer:used_layers_changed

Arguments:

  • val (list) - List of layer identifiers whose used layers changed.

  • context (uintptr) - The UsdContext handle representing the Layer, typically used as a filter parameter. Accessible via omni::kit::usd::layers::ILayersInstance::getEventKey() or omni::usd::UsdContext::getEventKey() (C++), or omni.kit.usd.layers.Layers.get_event_key() or omni.usd.UsdContext.get_event_key() (Python).

Prim Specs Changed#

Sent when prim specifications in a layer are modified.

  • C++ Constant: omni::kit::usd::layers::layerEventName(LayerEventType::ePrimSpecsChanged)

  • Python Constant: omni.kit.usd.layers.layer_event_name(LayerEventType.PRIM_SPECS_CHANGED)

  • String event name: omni.kit.usd.layers::layer:prim_specs_changed

Arguments:

  • layer_identifier (string) - The identifier of the layer containing the changed prim specs.

  • val (list[string]) - List of prim spec paths that changed.

  • context (uintptr) - The UsdContext handle representing the Layer, typically used as a filter parameter. Accessible via omni::kit::usd::layers::ILayersInstance::getEventKey() or omni::usd::UsdContext::getEventKey() (C++), or omni.kit.usd.layers.Layers.get_event_key() or omni.usd.UsdContext.get_event_key() (Python).

Authoring and Editing Events#

The following events are dispatched when layer authoring and editing modes change:

Edit Mode Changed#

Sent when the layer edit mode changes (Normal, Auto Authoring, Specs Linking).

  • C++ Constant: omni::kit::usd::layers::layerEventName(LayerEventType::eEditModeChanged)

  • Python Constant: omni.kit.usd.layers.layer_event_name(LayerEventType.EDIT_MODE_CHANGED)

  • String event name: omni.kit.usd.layers::layer:edit_mode_changed

Arguments:

  • context (uintptr) - The UsdContext handle representing the Layer, typically used as a filter parameter. Accessible via omni::kit::usd::layers::ILayersInstance::getEventKey() or omni::usd::UsdContext::getEventKey() (C++), or omni.kit.usd.layers.Layers.get_event_key() or omni.usd.UsdContext.get_event_key() (Python).

Edit Target Changed#

Sent when the edit target layer changes.

  • C++ Constant: omni::kit::usd::layers::layerEventName(LayerEventType::eEditTargetChanged)

  • Python Constant: omni.kit.usd.layers.layer_event_name(LayerEventType.EDIT_TARGET_CHANGED)

  • String event name: omni.kit.usd.layers::layer:edit_target_changed

Arguments:

  • context (uintptr) - The UsdContext handle representing the Layer, typically used as a filter parameter. Accessible via omni::kit::usd::layers::ILayersInstance::getEventKey() or omni::usd::UsdContext::getEventKey() (C++), or omni.kit.usd.layers.Layers.get_event_key() or omni.usd.UsdContext.get_event_key() (Python).

Default Layer Changed#

Sent when the default authoring layer changes.

  • C++ Constant: omni::kit::usd::layers::layerEventName(LayerEventType::eDefaultLayerChanged)

  • Python Constant: omni.kit.usd.layers.layer_event_name(LayerEventType.DEFAULT_LAYER_CHANGED)

  • String event name: omni.kit.usd.layers::layer:default_layer_changed

Arguments:

  • context (uintptr) - The UsdContext handle representing the Layer, typically used as a filter parameter. Accessible via omni::kit::usd::layers::ILayersInstance::getEventKey() or omni::usd::UsdContext::getEventKey() (C++), or omni.kit.usd.layers.Layers.get_event_key() or omni.usd.UsdContext.get_event_key() (Python).

Specs Workflow Events#

The following events are dispatched for advanced layer workflow operations:

Specs Locking Changed#

Sent when spec locking state changes for prim specifications.

  • C++ Constant: omni::kit::usd::layers::layerEventName(LayerEventType::eSpecsLockingChanged)

  • Python Constant: omni.kit.usd.layers.layer_event_name(LayerEventType.SPECS_LOCKING_CHANGED)

  • String event name: omni.kit.usd.layers::layer:specs_locking_changed

Arguments:

  • val (list[string]) - List of spec paths whose locking state changed.

  • context (uintptr) - The UsdContext handle representing the Layer, typically used as a filter parameter. Accessible via omni::kit::usd::layers::ILayersInstance::getEventKey() or omni::usd::UsdContext::getEventKey() (C++), or omni.kit.usd.layers.Layers.get_event_key() or omni.usd.UsdContext.get_event_key() (Python).

Specs Linking Changed#

Sent when spec linking relationships change between layers.

  • C++ Constant: omni::kit::usd::layers::layerEventName(LayerEventType::eSpecsLinkingChanged)

  • Python Constant: omni.kit.usd.layers.layer_event_name(LayerEventType.SPECS_LINKING_CHANGED)

  • String event name: omni.kit.usd.layers::layer:specs_linking_changed

Arguments:

  • val (dict) - Dictionary mapping layer identifiers to lists of linked spec paths. The key of the dict is an ordering parameter (<0>, <1>, etc.) since the map is an unordered map. The value is a dict with key (layer identifier as a string) and value (list[string] of spec paths) entries. The omni.kit.usd.layers.LayerEventPayload helper Python class parses this into a flat dict of layer identifiers to list of spec paths.

  • context (uintptr) - The UsdContext handle representing the Layer, typically used as a filter parameter. Accessible via omni::kit::usd::layers::ILayersInstance::getEventKey() or omni::usd::UsdContext::getEventKey() (C++), or omni.kit.usd.layers.Layers.get_event_key() or omni.usd.UsdContext.get_event_key() (Python).

Live Session Events#

The following events are dispatched for collaborative live session operations:

Live Session State Changed#

Sent when the state of a live session changes (joining, joined, leaving, etc.).

  • C++ Constant: omni::kit::usd::layers::layerEventName(LayerEventType::eLiveSessionStateChanged)

  • Python Constant: omni.kit.usd.layers.layer_event_name(LayerEventType.LIVE_SESSION_STATE_CHANGED)

  • String event name: omni.kit.usd.layers::layer:live_session_state_changed

Arguments:

  • val (list) - List of layer identifiers affected by the state change.

  • context (uintptr) - The UsdContext handle representing the Layer, typically used as a filter parameter. Accessible via omni::kit::usd::layers::ILayersInstance::getEventKey() or omni::usd::UsdContext::getEventKey() (C++), or omni.kit.usd.layers.Layers.get_event_key() or omni.usd.UsdContext.get_event_key() (Python).

Live Session Joining#

Sent when a live session join operation is in progress.

  • C++ Constant: omni::kit::usd::layers::layerEventName(LayerEventType::eLiveSessionJoining)

  • Python Constant: omni.kit.usd.layers.layer_event_name(LayerEventType.LIVE_SESSION_JOINING)

  • String event name: omni.kit.usd.layers::layer:live_session_joining

Arguments:

  • val (list) - List of layer identifiers being joined to the session.

  • context (uintptr) - The UsdContext handle representing the Layer, typically used as a filter parameter. Accessible via omni::kit::usd::layers::ILayersInstance::getEventKey() or omni::usd::UsdContext::getEventKey() (C++), or omni.kit.usd.layers.Layers.get_event_key() or omni.usd.UsdContext.get_event_key() (Python).

Live Session User Joined#

Sent when a user joins a live session.

  • C++ Constant: omni::kit::usd::layers::layerEventName(LayerEventType::eLiveSessionUserJoined)

  • Python Constant: omni.kit.usd.layers.layer_event_name(LayerEventType.LIVE_SESSION_USER_JOINED)

  • String event name: omni.kit.usd.layers::layer:live_session_user_joined

Arguments:

  • user_name (string) - The name of the user who joined.

  • user_id (string) - The unique identifier of the user who joined.

  • layer_identifier (string) - The identifier of the layer associated with the session.

  • context (uintptr) - The UsdContext handle representing the Layer, typically used as a filter parameter. Accessible via omni::kit::usd::layers::ILayersInstance::getEventKey() or omni::usd::UsdContext::getEventKey() (C++), or omni.kit.usd.layers.Layers.get_event_key() or omni.usd.UsdContext.get_event_key() (Python).

Live Session User Left#

Sent when a user leaves a live session.

  • C++ Constant: omni::kit::usd::layers::layerEventName(LayerEventType::eLiveSessionUserLeft)

  • Python Constant: omni.kit.usd.layers.layer_event_name(LayerEventType.LIVE_SESSION_USER_LEFT)

  • String event name: omni.kit.usd.layers::layer:live_session_user_left

Arguments:

  • user_name (string) - The name of the user who left.

  • user_id (string) - The unique identifier of the user who left.

  • layer_identifier (string) - The identifier of the layer associated with the session.

  • context (uintptr) - The UsdContext handle representing the Layer, typically used as a filter parameter. Accessible via omni::kit::usd::layers::ILayersInstance::getEventKey() or omni::usd::UsdContext::getEventKey() (C++), or omni.kit.usd.layers.Layers.get_event_key() or omni.usd.UsdContext.get_event_key() (Python).

Live Session List Changed#

Sent when the list of available live sessions changes.

  • C++ Constant: omni::kit::usd::layers::layerEventName(LayerEventType::eLiveSessionListChanged)

  • Python Constant: omni.kit.usd.layers.layer_event_name(LayerEventType.LIVE_SESSION_LIST_CHANGED)

  • String event name: omni.kit.usd.layers::layer:live_session_list_changed

Arguments:

  • val (string) - The layer identifier associated with the session list change.

  • context (uintptr) - The UsdContext handle representing the Layer, typically used as a filter parameter. Accessible via omni::kit::usd::layers::ILayersInstance::getEventKey() or omni::usd::UsdContext::getEventKey() (C++), or omni.kit.usd.layers.Layers.get_event_key() or omni.usd.UsdContext.get_event_key() (Python).

Live Session Merge Started#

Sent when a live session merge operation begins.

  • C++ Constant: omni::kit::usd::layers::layerEventName(LayerEventType::eLiveSessionMergeStarted)

  • Python Constant: omni.kit.usd.layers.layer_event_name(LayerEventType.LIVE_SESSION_MERGE_STARTED)

  • String event name: omni.kit.usd.layers::layer:live_session_merge_started

Arguments:

  • layer_identifier (string) - The identifier of the layer being merged.

  • success (bool) - Whether the merge start was successful.

  • context (uintptr) - The UsdContext handle representing the Layer, typically used as a filter parameter. Accessible via omni::kit::usd::layers::ILayersInstance::getEventKey() or omni::usd::UsdContext::getEventKey() (C++), or omni.kit.usd.layers.Layers.get_event_key() or omni.usd.UsdContext.get_event_key() (Python).

Live Session Merge Ended#

Sent when a live session merge operation completes.

  • C++ Constant: omni::kit::usd::layers::layerEventName(LayerEventType::eLiveSessionMergeEnded)

  • Python Constant: omni.kit.usd.layers.layer_event_name(LayerEventType.LIVE_SESSION_MERGE_ENDED)

  • String event name: omni.kit.usd.layers::layer:live_session_merge_ended

Arguments:

  • layer_identifier (string) - The identifier of the layer that was merged.

  • success (bool) - Whether the merge completed successfully.

  • context (uintptr) - The UsdContext handle representing the Layer, typically used as a filter parameter. Accessible via omni::kit::usd::layers::ILayersInstance::getEventKey() or omni::usd::UsdContext::getEventKey() (C++), or omni.kit.usd.layers.Layers.get_event_key() or omni.usd.UsdContext.get_event_key() (Python).

System Events#

The following events are dispatched for system-level layer operations:

Auto Reload Layers Changed#

Sent when the auto-reload configuration for layers changes.

  • C++ Constant: omni::kit::usd::layers::kGlobalEventAutoReloadLayersChanged

  • Python Constant: omni.kit.usd.layers.layer_event_name(LayerEventType.AUTO_RELOAD_LAYERS_CHANGED)

  • String event name: omni.kit.usd.layers::layer:auto_reload_layers_changed

Arguments:

  • layer_identifier (string) - The identifier of the layer whose auto-reload setting changed.

  • context (uintptr) - The UsdContext handle representing the Layer, typically used as a filter parameter. Accessible via omni::kit::usd::layers::ILayersInstance::getEventKey() or omni::usd::UsdContext::getEventKey() (C++), or omni.kit.usd.layers.Layers.get_event_key() or omni.usd.UsdContext.get_event_key() (Python).

Usage Examples#

Python Example - Basic Event Observation#

import carb.eventdispatcher
import omni.kit.usd.layers as layers

def on_layer_dirty_state_changed(event):
    payload = layers.get_layer_event_payload(event)
    affected_layers = payload.identifiers_or_spec_paths
    print(f"Layer dirty state changed for: {affected_layers}")

def on_live_session_user_joined(event):
    payload = layers.get_layer_event_payload(event)
    user_name = payload.user_name
    layer_id = payload.layer_identifier
    print(f"User {user_name} joined live session for layer {layer_id}")

# Get the layers interface for the current USD context
layers_interface = layers.get_layers()

# Subscribe to layer dirty state changes
dirty_subscription = carb.eventdispatcher.get_eventdispatcher().observe_event(
    observer_name="My Layer Dirty Observer",
    event_name=layers.layer_event_name(layers.LayerEventType.DIRTY_STATE_CHANGED),
    filter=layers_interface.get_event_key(),  # Very important for filtering
    on_event=on_layer_dirty_state_changed
)

# Subscribe to live session user events
user_subscription = carb.eventdispatcher.get_eventdispatcher().observe_event(
    observer_name="My Live Session Observer",
    event_name=layers.layer_event_name(layers.LayerEventType.LIVE_SESSION_USER_JOINED),
    filter=layers_interface.get_event_key(),  # Very important for filtering
    on_event=on_live_session_user_joined
)

Python Example - Multiple Event Observation#

import carb.eventdispatcher
import omni.kit.usd.layers as layers

class LayerEventObserver:
    def __init__(self):
        self.layers_interface = layers.get_layers()
        self.subscriptions = []
        self._setup_event_subscriptions()
    
    def _setup_event_subscriptions(self):
        """Setup subscriptions for multiple layer events."""
        event_handlers = (
            (layers.LayerEventType.INFO_CHANGED, self._on_info_changed),
            (layers.LayerEventType.DIRTY_STATE_CHANGED, self._on_dirty_state_changed),
            (layers.LayerEventType.LOCK_STATE_CHANGED, self._on_lock_state_changed),
            (layers.LayerEventType.LIVE_SESSION_STATE_CHANGED, self._on_live_session_state_changed),
            (layers.LayerEventType.PRIM_SPECS_CHANGED, self._on_prim_specs_changed),
        )
        
        for event_type, handler in event_handlers:
            subscription = carb.eventdispatcher.get_eventdispatcher().observe_event(
                observer_name=f"LayerEventObserver:{event_type.name}",
                event_name=layers.layer_event_name(event_type),
                filter=self.layers_interface.get_event_key(),
                on_event=handler
            )
            self.subscriptions.append(subscription)
    
    def _on_info_changed(self, event):
        payload = layers.get_layer_event_payload(event)
        layer_id = payload.layer_identifier
        info_data = payload.layer_info_data
        print(f"Layer info changed for {layer_id}: {info_data}")
    
    def _on_dirty_state_changed(self, event):
        payload = layers.get_layer_event_payload(event)
        affected_layers = payload.identifiers_or_spec_paths
        print(f"Dirty state changed for layers: {affected_layers}")
    
    def _on_lock_state_changed(self, event):
        payload = layers.get_layer_event_payload(event)
        affected_layers = payload.identifiers_or_spec_paths
        print(f"Lock state changed for layers: {affected_layers}")
    
    def _on_live_session_state_changed(self, event):
        payload = layers.get_layer_event_payload(event)
        affected_layers = payload.identifiers_or_spec_paths
        print(f"Live session state changed for layers: {affected_layers}")
    
    def _on_prim_specs_changed(self, event):
        payload = layers.get_layer_event_payload(event)
        layer_id = payload.layer_identifier
        spec_paths = payload.layer_spec_paths
        print(f"Prim specs changed in layer {layer_id}: {spec_paths}")
    
    def cleanup(self):
        """Clean up event subscriptions."""
        for subscription in self.subscriptions:
            subscription = None
        self.subscriptions.clear()

# Usage
observer = LayerEventObserver()
# ... do work ...
observer.cleanup()  # Important to clean up when done

Python Example - Live Session Monitoring#

import carb.eventdispatcher
import omni.kit.usd.layers as layers

class LiveSessionMonitor:
    def __init__(self):
        self.layers_interface = layers.get_layers()
        self.live_session_subscriptions = []
        self._setup_live_session_events()
    
    def _setup_live_session_events(self):
        """Setup subscriptions for live session events."""
        live_session_events = [
            (layers.LayerEventType.LIVE_SESSION_STATE_CHANGED, self._on_session_state_changed),
            (layers.LayerEventType.LIVE_SESSION_USER_JOINED, self._on_user_joined),
            (layers.LayerEventType.LIVE_SESSION_USER_LEFT, self._on_user_left),
            (layers.LayerEventType.LIVE_SESSION_MERGE_STARTED, self._on_merge_started),
            (layers.LayerEventType.LIVE_SESSION_MERGE_ENDED, self._on_merge_ended),
        ]
        
        for event_type, handler in live_session_events:
            subscription = carb.eventdispatcher.get_eventdispatcher().observe_event(
                observer_name=f"LiveSessionMonitor:{event_type.name}",
                event_name=layers.layer_event_name(event_type),
                filter=self.layers_interface.get_event_key(),
                on_event=handler
            )
            self.live_session_subscriptions.append(subscription)
    
    def _on_session_state_changed(self, event):
        payload = layers.get_layer_event_payload(event)
        print(f"Live session state changed for layers: {payload.identifiers_or_spec_paths}")
    
    def _on_user_joined(self, event):
        payload = layers.get_layer_event_payload(event)
        print(f"User {payload.user_name} ({payload.user_id}) joined session for layer {payload.layer_identifier}")
    
    def _on_user_left(self, event):
        payload = layers.get_layer_event_payload(event)
        print(f"User {payload.user_name} ({payload.user_id}) left session for layer {payload.layer_identifier}")
    
    def _on_merge_started(self, event):
        payload = layers.get_layer_event_payload(event)
        status = "successfully" if payload.success else "unsuccessfully"
        print(f"Live session merge started {status} for layer {payload.layer_identifier}")
    
    def _on_merge_ended(self, event):
        payload = layers.get_layer_event_payload(event)
        status = "successfully" if payload.success else "unsuccessfully"
        print(f"Live session merge ended {status} for layer {payload.layer_identifier}")

Event Filtering#

All global events include an event key that can be used for filtering. The event key is specific to each Layers instance and can be obtained using Layers.get_event_key() in Python.

Warning

If a filter key is not specified, your observer will receive events about all Layers instances.

# Filter events for a specific Layers instance
subscription = carb.eventdispatcher.get_eventdispatcher().observe_event(
    observer_name="My layer observer",
    event_name=layers.layer_event_name(layers.LayerEventType.INFO_CHANGED),
    on_event=on_event,
    filter=layers_interface.get_event_key()  # Filter by specific Layers instance
)

Event Payload Helper#

The LayerEventPayload class provides convenient access to event data:

def on_layer_event(event):
    payload = layers.get_layer_event_payload(event)
    
    # Check event type
    if payload.event_type == layers.LayerEventType.INFO_CHANGED:
        # Access layer info data
        layer_id = payload.layer_identifier
        changed_info = payload.layer_info_data
        
    elif payload.event_type == layers.LayerEventType.LIVE_SESSION_USER_JOINED:
        # Access user information
        user_name = payload.user_name
        user_id = payload.user_id
        layer_id = payload.layer_identifier
        
    # Check if a specific layer is affected
    if payload.is_layer_influenced("path/to/my/layer.usd"):
        print("My layer was affected by this event")

Legacy Events#

Previously, events could be retrieved through Event Streams via Layers.get_event_stream(). While still currently supported, this is now deprecated in favor of the global events described above.

Converting from Legacy Events#

Old Python:

import omni.kit.usd.layers as layers

def on_layer_event(event):
    # Handle event...
    pass

layers_interface = layers.get_layers()
event_stream = layers_interface.get_event_stream()
subscription = event_stream.create_subscription_to_pop_by_type(
    layers.LayerEventType.DIRTY_STATE_CHANGED,
    on_layer_event,
    carb.events.DEFAULT_ORDER,
    "My subscription name for debugging and profiling"
)

New Python:

import omni.kit.usd.layers as layers
import carb.eventdispatcher

def on_layer_event(event):
    # Handle event...
    pass

layers_interface = layers.get_layers()
subscription = carb.eventdispatcher.get_eventdispatcher().observe_event(
    observer_name="My observer name for debugging and profiling",
    event_name=layers.layer_event_name(layers.LayerEventType.DIRTY_STATE_CHANGED),
    filter=layers_interface.get_event_key(),  # Very important for filtering
    on_event=on_layer_event
)