location

Description

Supported Script Types: Interface Scripts • Client Entity Scripts • Avatar Scripts • Assignment Client Scripts

The location API provides facilities related to your current location in the metaverse.

Getter/Setter

You can get and set your current metaverse address by directly reading a string value from and writing a string value to the location object. This is an alternative to using the location.href property or other object functions.

Properties

Name	Type	Summary
domainID	Uuid	A UUID uniquely identifying the domain you're visiting. Is Uuid.NULL if you're not connected to the domain or are in a serverless domain. Read-only.
hostname	string	The name of the domain for your current metaverse address (e.g., `"DomainName"`, `localhost`, or an IP address). Is blank if you're in a serverless domain. Read-only.
href	string	Your current metaverse address (e.g., `"hifi://domainname/15,-10,26/0,0,0,1"`) regardless of whether or not you're connected to the domain. Starts with `"file:///"` if you're in a serverless domain. Read-only.
isConnected	boolean	`true` if you're connected to the domain in your current `href` metaverse address, otherwise `false`.
pathname	string	The location and orientation in your current `href` metaverse address (e.g., `"/15,-10,26/0,0,0,1"`). Read-only.
placename	string	The place name in your current `href` metaverse address (e.g., `"DomainName"`). Is blank if your `hostname` is an IP address. Read-only.
protocol	string	The protocol of your current `href` metaverse address (e.g., `"hifi"`). Read-only.

Methods

Name	Return Value	Summary
`canGoBack`	boolean	Checks if going back to the previous location is possible.
`copyAddress`	None	Copies your current metaverse address (i.e., `location.href` property value) to the OS clipboard.
`copyPath`	None	Copies your current metaverse location and orientation (i.e., `location.pathname` property value) to the OS clipboard.
`goBack`	None	Takes you back to the previous location in your navigation history, if there is one.
`goForward`	None	Takes you forward to the next location in your navigation history, if there is one.
`goToEntry`	None	Takes you to the default "welcome" metaverse address.
`goToLastAddress`	None	Takes you to the last address tried. This will be the last URL tried from `location.handleLookupString`.
`goToLocalSandbox`	None	Takes you to the local Sandbox server that's running on the same PC as Interface.
`goToUser`	None	Takes you to the specified user's location.
`goToViewpointForPath`	None	Takes you to a position and orientation resulting from a lookup for a named path in the domain (set in the domain server's settings). Deprecated: This function is deprecated and will be removed.
`handleLookupString`	None	Takes you to a specified metaverse address.
`lookupShareableNameForDomainID`	None	Retrieves and remembers the place name for the given domain ID if the place name is not already known. Deprecated: This function is deprecated and will be removed.
`refreshPreviousLookup`	None	Refreshes the current address, e.g., after connecting to a domain in order to position the user to the desired location. Deprecated: This function is deprecated and will be removed.
`storeCurrentAddress`	None	Updates your current metaverse location in Interface's Settings file as your last-known address. This can be used to ensure that you start up at that address if you exit Interface without a later address automatically being saved.

Signals

Name	Summary
`goBackPossible`	Triggered when there's a change in whether or not there's a previous location that can be navigated to using goBack. (Reflects changes in the state of the "Goto" dialog's back arrow.)
`goForwardPossible`	Triggered when there's a change in whether or not there's a forward location that can be navigated to using goForward. (Reflects changes in the state of the "Goto" dialog's forward arrow.)
`hostChanged`	Triggered when you navigate to a new domain.
`locationChangeRequired`	Triggered when an attempt is made to send your avatar to a specified position on the current domain. For example, when you change domains or enter a position to go to in the "Goto" dialog.
`lookupResultIsNotFound`	Triggered when looking up the details of a metaverse user or location to go to has completed and the domain or user could not be found.
`lookupResultIsOffline`	Triggered when looking up the details of a metaverse user or location to go to has completed and the domain or user is offline.
`lookupResultsFinished`	Triggered when looking up the details of a metaverse user or location to go to has completed (successfully or unsuccessfully).
`pathChangeRequired`	Triggered when an attempt is made to send your avatar to a new named path on the domain (set in the domain server's settings). For example, when you enter a "/" followed by the path's name in the "GOTO" dialog.
`possibleDomainChangeRequired`	Triggered when a request is made to go to an IP address.
`possibleDomainChangeRequiredViaICEForID`	Triggered when a request is made to go to a named domain or user.

Type Definitions

LookupTrigger
Type: number

The reasons for an address lookup via the metaverse API are defined by numeric values:

Name	Value	Description
UserInput	`0`	User-typed input.
Back	`1`	Address from a goBack call.
Forward	`2`	Address from a goForward call.
StartupFromSettings	`3`	Initial location at Interface start-up from settings.
DomainPathResponse	`4`	A named path in the domain.
Internal	`5`	An internal attempt to resolve an alternative path.
AttemptedRefresh	`6`	A refresh after connecting to a domain.
Suggestions	`7`	Address from the Goto dialog.
VisitUserFromPAL	`8`	User from the People dialog.

Method Details

(static) canGoBack( ) → {boolean} Returns: `true` if going back is possible, `false` if it isn't.
Checks if going back to the previous location is possible.

(static) copyAddress( )
Copies your current metaverse address (i.e., `location.href` property value) to the OS clipboard.

(static) copyPath( )
Copies your current metaverse location and orientation (i.e., `location.pathname` property value) to the OS clipboard.

(static) goBack( )
Takes you back to the previous location in your navigation history, if there is one.

(static) goForward( )
Takes you forward to the next location in your navigation history, if there is one.

(static) goToEntry( trigger )

Takes you to the default "welcome" metaverse address.

Parameters

Name	Type	Default Value	Description
`trigger`	location.LookupTrigger	StartupFromSettings	The reason for the function call. Helps ensure that user's location history is correctly maintained.

(static) goToLastAddress( )
Takes you to the last address tried. This will be the last URL tried from `location.handleLookupString`.

(static) goToLocalSandbox( pathopt, triggeropt )

Takes you to the local Sandbox server that's running on the same PC as Interface.

Parameters

Name	Type	Attributes	Default Value	Description
`path`	string	<optional>	""	The position and orientation to go to (e.g., `"/0,0,0"`).
`trigger`	location.LookupTrigger	<optional>	StartupFromSettings	The reason for the function call. Helps ensure that user's location history is correctly maintained.

(static) goToUser( username, matchOrientationopt )

Takes you to the specified user's location.

Parameters

Name	Type	Attributes	Default Value	Description
`username`	string			The user's username.
`matchOrientation`	boolean	<optional>	true	If `true` then go to a location just in front of the user and turn to face them, otherwise go to the user's exact location and orientation.

(static) goToViewpointForPath( path, namedPath )

Takes you to a position and orientation resulting from a lookup for a named path in the domain (set in the domain server's settings).

Deprecated: This function is deprecated and will be removed.

Parameters

Name	Type	Description
`path`	string	The position and orientation corresponding to the named path.
`namedPath`	string	The named path that was looked up on the server.

(static) handleLookupString( address, fromSuggestionsopt )

Takes you to a specified metaverse address.

Parameters

Name	Type	Attributes	Default Value	Description
`address`	string			The address to go to: a `"hifi://"` address, an IP address (e.g., `"127.0.0.1"` or `"localhost"`), a domain name, a named path on a domain (starts with `"/"`), a position or position and orientation, or a user (starts with `"@"`).
`fromSuggestions`	boolean	<optional>	false	Set to `true` if the address is obtained from the "Goto" dialog. Helps ensure that user's location history is correctly maintained.

(static) lookupShareableNameForDomainID( domainID )

Retrieves and remembers the place name for the given domain ID if the place name is not already known.

Deprecated: This function is deprecated and will be removed.

Parameters

Name	Type	Description
`domainID`	Uuid	The UUID of the domain.

(static) refreshPreviousLookup( )
Refreshes the current address, e.g., after connecting to a domain in order to position the user to the desired location. Deprecated: This function is deprecated and will be removed.

(static) refreshPreviousLookup( )

Refreshes the current address, e.g., after connecting to a domain in order to position the user to the desired location.

Deprecated: This function is deprecated and will be removed.

(static) storeCurrentAddress( )
Updates your current metaverse location in Interface's Settings file as your last-known address. This can be used to ensure that you start up at that address if you exit Interface without a later address automatically being saved.

Signal Details

goBackPossible( isPossible )
Returns: Signal

Triggered when there's a change in whether or not there's a previous location that can be navigated to using goBack. (Reflects changes in the state of the "Goto" dialog's back arrow.)

Parameters

Name	Type	Description
`isPossible`	boolean	`true` if there's a previous location to navigate to, otherwise `false`.

Example

Report when ability to navigate back changes.

function onGoBackPossible(isPossible) {
    print("Go back possible: " + isPossible);
}

location.goBackPossible.connect(onGoBackPossible);

goForwardPossible( isPossible )
Returns: Signal

Triggered when there's a change in whether or not there's a forward location that can be navigated to using goForward. (Reflects changes in the state of the "Goto" dialog's forward arrow.)

Parameters

Name	Type	Description
`isPossible`	boolean	`true` if there's a forward location to navigate to, otherwise `false`.

Example

Report when ability to navigate forward changes.

function onGoForwardPossible(isPossible) {
    print("Go forward possible: " + isPossible);
}

location.goForwardPossible.connect(onGoForwardPossible);

hostChanged( hostname )
Returns: Signal

Triggered when you navigate to a new domain.

Parameters

Name	Type	Description
`hostname`	string	The new domain's host name.

Example

Report when you navigate to a new domain.

function onHostChanged(host) {
    print("Host changed to: " + host);
}

location.hostChanged.connect(onHostChanged);

locationChangeRequired( position, hasOrientationChange, orientation, shouldFaceLocation )
Returns: Signal

Triggered when an attempt is made to send your avatar to a specified position on the current domain. For example, when you change domains or enter a position to go to in the "Goto" dialog.

Parameters

Name	Type	Description
`position`	Vec3	The position to go to.
`hasOrientationChange`	boolean	If `true` then a new `orientation` has been requested.
`orientation`	Quat	The orientation to change to. Is Quat.IDENTITY if `hasOrientationChange` is `false`.
`shouldFaceLocation`	boolean	If `true` then the request is to go to a position near that specified and orient your avatar to face it. For example when you visit someone from the "People" dialog.

Example

Report location change requests.

function onLocationChangeRequired(newPosition, hasOrientationChange, newOrientation, shouldFaceLocation) {
    print("Location change required:");
    print("- New position = " + JSON.stringify(newPosition));
    print("- Has orientation change = " + hasOrientationChange);
    print("- New orientation = " + JSON.stringify(newOrientation));
    print("- Should face location = " + shouldFaceLocation);
}

location.locationChangeRequired.connect(onLocationChangeRequired);

lookupResultIsNotFound( ) Returns: Signal
Triggered when looking up the details of a metaverse user or location to go to has completed and the domain or user could not be found.

lookupResultIsOffline( ) Returns: Signal
Triggered when looking up the details of a metaverse user or location to go to has completed and the domain or user is offline.

lookupResultsFinished( ) Returns: Signal
Triggered when looking up the details of a metaverse user or location to go to has completed (successfully or unsuccessfully).

pathChangeRequired( path )
Returns: Signal

Triggered when an attempt is made to send your avatar to a new named path on the domain (set in the domain server's settings). For example, when you enter a "/" followed by the path's name in the "GOTO" dialog.

Parameters

Name	Type	Description
`path`	string	The name of the path to go to.

Example

Report path change requests.

function onPathChangeRequired(newPath) {
    print("onPathChangeRequired: newPath = " + newPath);
}

location.pathChangeRequired.connect(onPathChangeRequired);

possibleDomainChangeRequired( domainURL, domainID )
Returns: Signal

Triggered when a request is made to go to an IP address.

Parameters

Name	Type	Description
`domainURL`	Url	URL for domain
`domainID`	Uuid	The UUID of the domain to go to.

possibleDomainChangeRequiredViaICEForID( iceServerHostName, domainID )
Returns: Signal

Triggered when a request is made to go to a named domain or user.

Parameters

Name	Type	Description
`iceServerHostName`	string	IP address of the ICE server.
`domainID`	Uuid	The UUID of the domain to go to.

High Fidelity API Reference

location

Description

Getter/Setter

Properties

Methods

Signals

Type Definitions

Method Details

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Signal Details

Parameters

Example

Parameters

Example

Parameters

Example

Parameters

Example

Parameters

Example

Parameters

Parameters