unreal.MagicLeapARPinComponent

class unreal.MagicLeapARPinComponent(outer=None, name='None')

Bases: unreal.SceneComponent

Component to make content persist at locations in the real world.

C++ Source:

  • Plugin: MagicLeapPassableWorld

  • Module: MagicLeapARPin

  • File: MagicLeapARPinComponent.h

Editor Properties: (see get_editor_property/set_editor_property)

  • absolute_location (bool): [Read-Write] If RelativeLocation should be considered relative to the world, rather than the parent

  • absolute_rotation (bool): [Read-Write] If RelativeRotation should be considered relative to the world, rather than the parent

  • absolute_scale (bool): [Read-Write] If RelativeScale3D should be considered relative to the world, rather than the parent

  • asset_user_data (Array(AssetUserData)): [Read-Write] Array of user data stored with the component

  • auto_activate (bool): [Read-Write] Whether the component is activated at creation or must be explicitly activated.

  • auto_pin_type (MagicLeapAutoPinType): [Read-Write] Mode for automatically pinning this component or it’s owner actor to real-world.

  • can_ever_affect_navigation (bool): [Read-Write] Whether this component can potentially influence navigation

  • component_tags (Array(Name)): [Read-Write] Array of tags that can be used for grouping and categorizing. Can also be accessed from scripting.

  • detail_mode (DetailMode): [Read-Write] If detail mode is >= system detail mode, primitive won’t be rendered.

  • editable_when_inherited (bool): [Read-Write] True if this component can be modified when it was inherited from a parent actor class

  • hidden_in_game (bool): [Read-Write] Whether to hide the primitive in game, if the primitive is Visible.

  • is_editor_only (bool): [Read-Write] If true, the component will be excluded from non-editor builds

  • mobility (ComponentMobility): [Read-Write] How often this component is allowed to move, used to make various optimizations. Only safe to set in constructor.

  • object_uid (str): [Read-Write] Unique ID for this component to save the meta data for the Pin and make content persistent. This name has to be unique across all instances of the MagicLeapARPinComponent class. If empty, the name of the owner actor will be used.

  • on_component_activated (ActorComponentActivatedSignature): [Read-Write] Called when the component has been activated, with parameter indicating if it was from a reset

  • on_component_deactivated (ActorComponentDeactivateSignature): [Read-Write] Called when the component has been deactivated

  • on_persistent_entity_pin_lost (PersistentEntityPinLost): [Read-Write] Fired when an entity loses its pin.

  • on_persistent_entity_pinned (PersistentEntityPinned): [Read-Write] Fired when an entity is successfully pinned by this component.

  • on_pin_data_load_attempt_completed (MagicLeapARPinDataLoadAttemptCompleted): [Read-Write] On Pin Data Load Attempt Completed

  • physics_volume_changed_delegate (PhysicsVolumeChanged): [Read-Write] Delegate that will be called when PhysicsVolume has been changed *

  • pin_data_class (type(Class)): [Read-Write] The user defined save game class associated with this pin. Note that this MUST match the type passed into GetPinData().

  • primary_component_tick (ActorComponentTickFunction): [Read-Write] Main tick function for the Component

  • relative_location (Vector): [Read-Write] Location of the component relative to its parent

  • relative_rotation (Rotator): [Read-Write] Rotation of the component relative to its parent

  • relative_scale3d (Vector): [Read-Write] Non-uniform scaling of the component relative to its parent. Note that scaling is always applied in local space (no shearing etc)

  • replicates (bool): [Read-Write] Is this component currently replicating? Should the network code consider it for replication? Owning Actor must be replicating first!

  • search_pin_types (Set(MagicLeapARPinType)): [Read-Write] Pin types to look for when attempting to pin this component.

  • search_volume (SphereComponent): [Read-Write] Volume to search for an ARPin in. The position and scaled radius (in Unreal Units) of this sphere is used to look for an ARPin of type SearchPinTypes.

  • should_pin_actor (bool): [Read-Write] Pin this component’s owner actor instead of just the component itself. Relevant only when using ‘OnlyOnDataRestoration’ or ‘Always’ as AutoPinType.

  • should_update_physics_volume (bool): [Read-Write] Whether or not the cached PhysicsVolume this component overlaps should be updated when the component is moved. see: GetPhysicsVolume()

  • use_attach_parent_bound (bool): [Read-Write] If true, this component uses its parents bounds when attached. This can be a significant optimization with many components attached together.

  • user_index (int32): [Read-Write] Index to get the save game data for the pin

  • visible (bool): [Read-Write] Whether to completely draw the primitive; if false, the primitive is not drawn, does not cast a shadow.

attempt_pin_data_restoration() → bool

If BeginPlay() is called before app sets ObjectUID (can happen when component is spawned at runtime or actor that includes this component is spawned at runtime), this function can be called to attempt a fresh restoration. deprecated: Deprecated and will be removed in 0.24.2 release. Use AttemptPinDataRestorationAsync instead.

Returns

true of pin data was retored, false otherwise

Return type

bool

attempt_pin_data_restoration_async() → None

If BeginPlay() is called before app sets ObjectUID (can happen when component is spawned at runtime or actor that includes this component is spawned at runtime), this function can be called to attempt a fresh restoration. It loads the pin data from disk asynchronously. The OnPinDataLoadAttemptCompleted event is called to indicate whether the data was succesfully loaded or not.

property auto_pin_type

[Read-Write] Mode for automatically pinning this component or it’s owner actor to real-world.

Type

(MagicLeapAutoPinType)

get_pin_data(pin_data_class) → MagicLeapARPinSaveGame

Retrieves the data associated with this pin. Make sure to call this only after setting a proper ObjectID value. deprecated: Deprecated and will be removed in 0.24.2 release. Use TryGetPinData() instead.

Parameters

pin_data_class (type(Class)) – The user defined save game class used by this pin. Note that this must match the PinDataClass property.

Returns

The save game instance associated with this pin instance.

Return type

MagicLeapARPinSaveGame

get_pin_state() → MagicLeapARPinState or None

Returns the state of this Pin.

Returns

Error code representing specific success or failure cases.

state (MagicLeapARPinState): Output state of the Pin. Valid only if return value is true.

Return type

MagicLeapARPinState or None

get_pinned_pin_id() → Guid or None

Get the ID of the Pin the entity (component or actor) is currently pinned to.

Returns

True if an entity is currently pinned by this component and the output param is successfully populated.

pin_id (Guid): Output param for the ID of the Pin.

Return type

Guid or None

is_pinned() → bool

True if an entity (component or actor) is currently pinned by this component. If true, the entity’s transform will be locked. App needs to call UnPin() if it wants to move it again. If false, and you still want your content to persist, you will have to call PinSceneComponent() or PinActor() before EndPlay().

Returns

True if an entity (component or actor) is currently pinned by this component.

Return type

bool

property object_uid

[Read-Write] Unique ID for this component to save the meta data for the Pin and make content persistent. This name has to be unique across all instances of the MagicLeapARPinComponent class. If empty, the name of the owner actor will be used.

Type

(str)

property on_persistent_entity_pin_lost

[Read-Write] Fired when an entity loses its pin.

Type

(PersistentEntityPinLost)

property on_persistent_entity_pinned

[Read-Write] Fired when an entity is successfully pinned by this component.

Type

(PersistentEntityPinned)

property on_pin_data_load_attempt_completed

[Read-Write] On Pin Data Load Attempt Completed

Type

(MagicLeapARPinDataLoadAttemptCompleted)

pin_actor(actor_to_pin) → bool

Deprecated and can no longer be used to pin any actor other than the owner of this component. Set bShouldPinActor to true and call PinToBestFit(), PinToID() or PinToRestoredOrSyncedID() instead. If this component’s owner is passed to this function, PinToBestFit() is called internally. deprecated: Will be removed in MLSDK 0.25.0. Set bShouldPinActor to true and call PinToBestFit(), PinToID() or PinToRestoredOrSyncedID().

Parameters

actor_to_pin (Actor) – Only accepts the owner of this component

Returns

true if the Actor was accepted to be pinned, false otherwise.

Return type

bool

property pin_data_class

[Read-Write] The user defined save game class associated with this pin. Note that this MUST match the type passed into GetPinData().

Type

(type(Class))

pin_restored_or_synced() → bool

True if the AR Pin for the unique ID ObjectUID was restored from the app’s local storage or was repliated over network. Implies if content was already pinned earlier. Does not imply if that restored Pin is available in the current environment.

Returns

True if the Pin data was restored from local storage or network.

Return type

bool

pin_scene_component(component_to_pin) → bool

Deprecated and can no longer be used to pin any scene component other than itself. Use PinToBestFit(), PinToID() or PinToRestoredOrSyncedID() instead. If a reference to itself passed to this function, PinToBestFit() is called internally. deprecated: Will be removed in MLSDK 0.25.0. Can pin only itself (will pin its children with it). Use PinToBestFit(), PinToID() or PinToRestoredOrSyncedID().

Parameters

component_to_pin (SceneComponent) – Only accepts ‘this’ / ‘self’

Returns

true if the component was accepted to be pinned, false otherwise.

Return type

bool

pin_to_best_fit() → None

Pin this component (or owner actor if bShouldPinActor is true) to the ARPin that is the best fit based on its location and desired type. If UMagicLeapARPinFunctionLibrary::QueryARPins() is implemented on this platform, pins of type SearchPinTypes will be searched within the SearchVolume (250cm radius by default) and the closest one will be selected. Otherwise, a simple search of the closest pin will be used to get the desired ARPin. OnPersistentEntityPinned event will be fired when a suitable ARPin is found for this component. The component’s transform will then be locked. App needs to call UnPin() if it wants to move the component again.

pin_to_id(pin_id) → bool

Pin this component (or owner actor if bShouldPinActor is true) to the specified PinID. If this pin exists in the environment, OnPersistentEntityPinned event will be fired in the next Tick. The component’s transform will then be locked. App needs to call UnPin() if it wants to move the component again.

Parameters

pin_id (Guid) – ID of the ARPin to attach this component (or owner actor) to.

Returns

true if the provided pin exists in the environment, false otherwise.

Return type

bool

pin_to_restored_or_synced_id() → bool

Pin this component (or owner actor if bShouldPinActor is true) to the PinID that was restored from a previous session or was synced voer the network. OnPersistentEntityPinned event will be fired when the restored pin will be found in the environment. The component’s transform will then be locked. App needs to call UnPin() if it wants to move the component again.

Returns

true if some ARPin data has been restored or synced, false otherwise.

Return type

bool

property search_pin_types

[Read-Write] Pin types to look for when attempting to pin this component.

Type

(Set(MagicLeapARPinType))

property search_volume

[Read-Write] Volume to search for an ARPin in. The position and scaled radius (in Unreal Units) of this sphere is used to look for an ARPin of type SearchPinTypes.

Type

(SphereComponent)

property should_pin_actor

[Read-Write] Pin this component’s owner actor instead of just the component itself. Relevant only when using ‘OnlyOnDataRestoration’ or ‘Always’ as AutoPinType.

Type

(bool)

try_get_pin_data(pin_data_class) -> (MagicLeapARPinSaveGame, out_pin_data_valid=bool)

Tries to retreive the data associated with this pin. Returns false if the data hasnt been loaded from the disk yet. In that case, wait until the OnPinDataLoadAttemptCompleted event is called.

Parameters

pin_data_class (type(Class)) – The user defined save game class used by this pin. Note that this must match the PinDataClass property. Used for auto casting the return value.

Returns

True if pin data was successfully loaded, false otherwise.

out_pin_data_valid (bool):

Return type

bool

un_pin() → None

Detach or un-pin the currently pinned entity (component) from the real-world. Call this if you want to change the transform of a pinned entity. Note that if you still want your content to persist, you will have to call PinToBestFit() or PinToID() before EndPlay().

property user_index

[Read-Write] Index to get the save game data for the pin

Type

(int32)