Class UserPlacementManager

This component allows the user to choose where the origin of the scene appears in their environment. This is particularly useful for AR experiences where the content is contained within a small area, such product visualization, as it gives the user the flexibility to choose where to view the content in their room.

By default the component uses the pointing direction of a hardware controller (if present), or the user's gaze, to determine potential locations for the scene during placement mode. The user can confirm a location by pressing their device's select button - either the trigger button on the controller, or the screen itself.

Some devices and hardware can detect surfaces in the user's environment, and this component will utilise these when determining suitable locations for placement. Alternaively the forceGroundPlane property can be used to ensure that placement occurs on the floor.

The restartPlacement() function can be used to enter placement mode again after the user has chosen a location.

Zicon

my_location

Zparents

three/Object3D/Group/**

Hierarchy

  • Component
    • UserPlacementManager

Accessors

disposed elementsResolved lockedResolved

Constructors

constructor

Methods

addBehavior appendChild constructChildren dispose getBehavior getBehaviors getZComponentInstance register remove removeBehavior removeChild restartPlacement unregister

Other

tags

Properties - Animation

notPlacingLayerClip placingLayerClip

Properties - Behavior

enabled

Properties - Other

behaviors children contextManager element? enabledResolved locked? onDispose onPlacementEnd onPlacementStart onVisible parent?

Properties - UserPlacementManager

controllerPreference forceGroundPlane restartOnTrackingLoss suppressControllerEventsDuringPlacement useControllerIfPresent

Accessors

disposed

  • get disposed(): boolean

  • Gets the disposed status of the entity.

    Returns boolean

    The disposed status.

elementsResolved

  • get elementsResolved(): any[]

  • An array of the elements that this component instance exposes. In the case that this component does not expose any elements of its own, this will be an array of the elements exposed by this component's children.

    Returns any[]

lockedResolved

  • get lockedResolved(): boolean

  • Returns true if this component, or any of its parents, are marked as locked.

    Returns boolean

Constructors

constructor

Methods

addBehavior

  • addBehavior(b): void

  • Adds a behavior to the component.

    Parameters

    • b: Behavior<Component<any, ConstructorProps>>

      The behavior to add.

    Returns void

appendChild

  • appendChild(c): void

  • Adds the supplied component instance as a child of this component, removing it from any existing parent.

    Parameters

    • c: Component<any, ConstructorProps>

      The component instance to add

    Returns void

constructChildren

  • constructChildren(children, contextManager?): void

  • Constructs the children of this component.

    Parameters

    • children: ComponentChildren
    • OptionalcontextManager: ContextManager

    Returns void

dispose

getBehavior

  • getBehavior<T>(type): undefined | InstanceType<T>

  • Gets a behavior of a specific type from the component.

    Type Parameters

    • T extends (new (contextManager: ContextManager, instance: Component<any, ConstructorProps>, ...args: any[]) => Behavior<Component<any, ConstructorProps>>)

      The behavior type.

    Parameters

    • type: T

      The type of behavior to get.

    Returns undefined | InstanceType<T>

    The behavior of the specified type, or undefined if no such behavior exists.

getBehaviors

  • getBehaviors<T>(type): InstanceType<T>[]

  • Gets all behaviors of a specific type from the component.

    Type Parameters

    • T extends (new (contextManager: ContextManager, instance: Component<any, ConstructorProps>, ...args: any[]) => Behavior<Component<any, ConstructorProps>>)

      The behavior type.

    Parameters

    • type: T

      The type of behaviors to get.

    Returns InstanceType<T>[]

    An array of behaviors of the specified type.

getZComponentInstance

  • getZComponentInstance<T>(type?): T

  • Get the instance of the ZComponent that constructed this entity.

    If you pass the class of a ZComponent as the type parameter, this function will ensure that it returns an instance of that ZComponent. If this component or behavior was constructed by a different ZComponent class, or by a different entity altogether, the function with throw an error.

    Type Parameters

    • T extends ZComponent<any, T> = ZComponent<any>

    Parameters

    • Optionaltype: ConstructorForComponent<T>

      The ZComponent class that you are expecting to receive

    Returns T

    The instance of the ZComponent that constructed this component or behavior

register

  • register<Args>(evt, fn, priority?): any

  • Register a function to be called when an Event is fired, or an Observable's value changes. The function will only be bound to the underlying Event or Observable while this entity is enabled.

    Using this function, rather than attaching your handler directly to the Event or Observable, ensures your handler is automatically released when this entity is disposed.

    Type Parameters

    • Args extends any[]

    Parameters

    • evt: Event<Args>

      The Event or Observable to listen to

    • fn: ((...args: Args) => void)

      A function that will be called when the event fires, or the Observable value changes

        • (...args): void

        • Parameters

          Returns void

    • Optionalpriority: number

    Returns any

  • register<Args>(evt, fn, options?): any

  • Type Parameters

    • Args extends any[]

    Parameters

    Returns any

  • register<Type>(observable, fn, priority?): any

  • Type Parameters

    • Type

    Parameters

    • observable: Observable<Type, never>
    • fn: ((v: Type) => void)
        • (v): void

        • Parameters

          Returns void

    • Optionalpriority: number

    Returns any

  • register<Type>(observable, fn, options?): any

  • Type Parameters

    • Type

    Parameters

    Returns any

remove

  • remove(): void

  • Removes this component from its parent component.

    Returns void

removeBehavior

  • removeBehavior(b): void

  • Removes a behavior from the component.

    Parameters

    • b: Behavior<Component<any, ConstructorProps>>

      The behavior to remove.

    Returns void

removeChild

  • removeChild(c): void

  • Removes the supplied component instance from the list of children.

    Parameters

    • c: Component<any, ConstructorProps>

      The component to remove

    Returns void

restartPlacement

unregister

  • unregister<Args>(evt, fn): any

  • Unregisters a function that was previously registered to an Event or Observable.

    Type Parameters

    • Args extends any[]

    Parameters

    • evt: Event<Args>

      The Event or Observable

    • fn: ((...args: Args) => void)

      The function that was passed in the call to register

        • (...args): void

        • Parameters

          Returns void

    Returns any

  • unregister<Type>(observable, fn): any

  • Type Parameters

    • Type

    Parameters

    • observable: Observable<Type, never>
    • fn: ((v: Type) => void)
        • (v): void

        • Parameters

          Returns void

    Returns any

Other

Readonlytags

tags: Observable<string[], never>

An array of string 'tags' assocated with this component.

The getComponentsByTag(mgr, tag) function can be used to get an array of components with the supplied tag.

By default, tags are scoped to the ZComponent instance that a component is constructed by. Tags that begin with global: are scoped to the experience as a whole.

Zprop

Zgrouppriority

0

Properties - Animation

notPlacingLayerClip

notPlacingLayerClip: Observable<undefined | string, never> = ...

A layer clip to play when the component is not in placement mode.

Zui

Zgrouppriority

10

Zdefault

false

Zvalues

layerclipids

placingLayerClip

placingLayerClip: Observable<undefined | string, never> = ...

A layer clip to play when the component enters placement mode.

Zui

Zgrouppriority

10

Zdefault

false

Zvalues

layerclipids

Properties - Behavior

Readonlyenabled

enabled: Observable<boolean, never>

If false, this entity and its children will no longer participate in the experience.

Note - to read this value, you may wish to use enabledResolved which will be false if this entity, or any of its parents, have enabled set to false.

The precise implications of enabled being false will vary between entities, but in general disabled entities:

  • should not emit any events,
  • should not take any action, e.g. navigate the user to a different page,
  • should not perform any network communication,
  • should not make changes to other behaviors or components in the experience,
  • should minimise any runtime performance cost (e.g. detach from any frame handlers).

Zprop

Zdefault

true

Zgrouppriority

10

Properties - Other

Readonlybehaviors

behaviors: Behavior<Component<any, ConstructorProps>>[]

The behaviors attached to this component.

Readonlychildren

children: Component<any, ConstructorProps>[]

The children of this component.

ReadonlycontextManager

contextManager: ContextManager

Optionalelement

element?: any

The raw element(s) that this component exposes

ReadonlyenabledResolved

enabledResolved: Observable<boolean, never>

This will have value false if this entity, or any of its parents, have enabled set to false.

To change the enabled status of this entity, use the enabled property instead.

The precise implications of enabled being false will vary between entities, but in general disabled entities:

  • should not emit any events,
  • should not take any action, e.g. navigate the user to a different page,
  • should not perform any network communication,
  • should not make changes to other behaviors or components in the experience,
  • should minimise any runtime performance cost.

Disabled entities will typically remain visible (if they have a visible appearance).

Optionallocked

locked?: boolean

If true, this component can't be selected at design time in the 3D preview.

ReadonlyonDispose

onDispose: Event<[]>

An event that is fired as the last act of this entity being destroyed.

onPlacementEnd

onPlacementEnd: Event<[]> = ...

Zui

onPlacementStart

onPlacementStart: Event<[]> = ...

Zui

onVisible

onVisible: Event<[]> = ...

Zui

Optionalparent

parent?: Component<any, ConstructorProps>

The parent of this component.

Properties - UserPlacementManager

controllerPreference

controllerPreference: Observable<XRHandedness, never> = ...

For devices with multiple controllers, this property determines which controller will be used by the user to choose a location - either the left-hand or right-hand controller. If no matching controller is found, the component will use the first input source reported by the device, or the user's gaze if none are reported.

Zui

Zgrouppriority

20

Zdefault

"right"

forceGroundPlane

forceGroundPlane: Observable<boolean, never> = ...

If this property is set true, the component will disregard any surfaces that are not the floor as possible locations for the user to choose.

Zui

Zgrouppriority

20

Zdefault

false

restartOnTrackingLoss

restartOnTrackingLoss: Observable<boolean, never> = ...

If true (the default), the component will enter placement mode again if device has lost its ability to track the user's environment.

Zui

Zgrouppriority

20

Zdefault

true

suppressControllerEventsDuringPlacement

suppressControllerEventsDuringPlacement: Observable<boolean, never> = ...

If true (the default), other controller events, such as pointer events and button presses, will be suppressed during placement mode. This is to prevent any conflicts with scene interaction while the user is choosing the location of the content.

Zui

Zgrouppriority

20

Zdefault

true

useControllerIfPresent

useControllerIfPresent: Observable<boolean, never> = ...

Allow the use of a controller to choose a location. Otherwise the user's viewing direction will be used.

Zui

Zgrouppriority

20

Zdefault

true

Settings

Member Visibility

On This Page

disposedelementsResolvedlockedResolvedconstructoraddBehaviorappendChildconstructChildrendisposegetBehaviorgetBehaviorsgetZComponentInstanceregisterremoveremoveBehaviorremoveChildrestartPlacementunregistertagsnotPlacingLayerClipplacingLayerClipenabledbehaviorschildrencontextManagerelementenabledResolvedlockedonDisposeonPlacementEndonPlacementStartonVisibleparentcontrollerPreferenceforceGroundPlanerestartOnTrackingLosssuppressControllerEventsDuringPlacementuseControllerIfPresent