location

Description

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 this object's functions.

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

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., "AvatarIsland", 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://avatarisland/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., "AvatarIsland"). 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 None Returns if going back is possible.
copyAddress None Copy your current metaverse address (i.e., location.href property value) to the OS clipboard.
copyPath None Copy your current metaverse location and orientation (i.e., location.pathname property value) to the OS clipboard.
goBack None Go back to the previous location in your navigation history, if there is one.
goForward None Go forward to the next location in your navigation history, if there is one.
goToEntry None Go to the default "welcome" metaverse address.
goToLastAddress None Go to the last address tried. This will be the last URL tried from location.handleLookupString
goToLocalSandbox None Go to the local Sandbox server that's running on the same PC as Interface.
goToUser None Go to the specified user's location.
goToViewpointForPath None Go 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 Go to a specified metaverse address.
lookupShareableNameForDomainID None Retrieve and remember 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 Refresh 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 Update 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( )

Returns if going back is possible.

(static) copyAddress( )

Copy your current metaverse address (i.e., location.href property value) to the OS clipboard.

(static) copyPath( )

Copy your current metaverse location and orientation (i.e., location.pathname property value) to the OS clipboard.

(static) goBack( )

Go back to the previous location in your navigation history, if there is one.

(static) goForward( )

Go forward to the next location in your navigation history, if there is one.

(static) goToEntry( trigger )

Go 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( )

Go to the last address tried. This will be the last URL tried from location.handleLookupString

(static) goToLocalSandbox( path, trigger )

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

Parameters

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

Go to the specified user's location.

Parameters

Name Type Default Value Description
username string The user's username.
matchOrientation boolean 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 )

Go 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, fromSuggestions )

Go to a specified metaverse address.

Parameters

Name Type 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 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 )

Retrieve and remember 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( )

Refresh 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( )

Update 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.