location

Available in: Interface Scripts Client Entity 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 this object's functions.

Methods

Signals

Type Definitions

Properties:
Name Type Description
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

canGoBack()
Returns if going back is possible.
copyAddress()
Copy your current metaverse address (i.e., location.href property value) to the OS clipboard.
copyPath()
Copy your current metaverse location and orientation (i.e., location.pathname property value) to the OS clipboard.
goBack()
Go back to the previous location in your navigation history, if there is one.
goForward()
Go forward to the next location in your navigation history, if there is one.
goToEntry(trigger)
Go to the default "welcome" metaverse address.
Parameters:
Name Type Default Description
trigger location.LookupTrigger StartupFromSettings The reason for the function call. Helps ensure that user's location history is correctly maintained.
goToLastAddress()
Go to the last address tried. This will be the last URL tried from location.handleLookupString
goToLocalSandbox(path, trigger)
Go to the local Sandbox server that's running on the same PC as Interface.
Parameters:
Name Type Default 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.
goToUser(username, matchOrientation)
Go to the specified user's location.
Parameters:
Name Type Default 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.
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).
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.
Deprecated:
This function is deprecated and will be removed.
handleLookupString(address, fromSuggestions)
Go to a specified metaverse address.
Parameters:
Name Type Default 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.
lookupShareableNameForDomainID(domainID)
Retrieve and remember the place name for the given domain ID if the place name is not already known.
Parameters:
Name Type Description
domainID Uuid The UUID of the domain.
Deprecated:
This function is deprecated and will be removed.
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.
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.

Signals

goBackPossible(isPossible) → {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.
Returns:
Type: Signal
Example

Report when ability to navigate back changes.

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

location.goBackPossible.connect(onGoBackPossible);
goForwardPossible(isPossible) → {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.
Returns:
Type: Signal
Example

Report when ability to navigate forward changes.

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

location.goForwardPossible.connect(onGoForwardPossible);
   
hostChanged(hostname) → {Signal}
Triggered when you navigate to a new domain.
Parameters:
Name Type Description
hostname string The new domain's host name.
Returns:
Type: Signal
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) → {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.
Returns:
Type: Signal
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() → {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.
Returns:
Type: Signal
lookupResultIsOffline() → {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.
Returns:
Type: Signal
lookupResultsFinished() → {Signal}
Triggered when looking up the details of a metaverse user or location to go to has completed (successfully or unsuccessfully).
Returns:
Type: Signal
pathChangeRequired(path) → {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.
Returns:
Type: Signal
Example

Report path change requests.

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

location.pathChangeRequired.connect(onPathChangeRequired);
possibleDomainChangeRequired(domainURL, domainID) → {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.
Returns:
Type: Signal
possibleDomainChangeRequiredViaICEForID(iceServerHostName, domainID) → {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.
Returns:
Type: Signal

Type Definitions

LookupTrigger

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.
Type: number