location

• Properties • Methods • Signals • Type Definitions • Method Details • Signal Details •

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 a URL or 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 file:/// address, 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 "Explore" app. Helps ensure that the 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) 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 a URL or IP address.

Parameters

Name Type Description
domainURL string

The URL of the domain.
domainID Uuid

The UUID of the domain to go to. May be Uuid.NULL if not yet known.
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.