nearbyavatars_scan

Scans the current region for other avatars.

This API call might not be suitable for LSL because of the large amount of data received.

// See "LSL Helper Functions" page for this function
smartbotsAPI("nearbyavatars_scan", []);

Variables

The following table shows input values (you send them with the API call) and returned output values.

Input basic parameters

Variable	Required	Description
action	yes	= nearbyavatars_scan
apikey	yes	Your personal developer's API key
botname	yes	Your bot's SL login
secret	yes	Bot access code of your bot
dataType	optional	Set to "json" to get JSON reply instead of URL-encoded string
custom	optional	The custom data (string) to be passed back to caller script. This value will be returned back to the caller in HTTP response

Input

This command has no additional input parameters.

Output

(To be received in *http_response* LSL event, see docs for details)

Variable	Description
result	OK - command completed successfully FAIL - command failed
resulttext	Detailed reason for the failure
custom	The value from input "custom" parameter. See above
avatars	Nearby avatars list. See Return value for details

Return value

The avatars field in the response is an array containing a list of avatars the bot can see:

{
  "name": "GrrrillaBongo Resident",
  "UUID": "d8e20552-ca84-4c42-b8d3-e8fa5fbdcc6b",
  "parcelID": 177,
  "sitting": false,
  "position": {
    "X": 110,
    "Y": 75,
    "Z": 32
  },
  "localPosition": {
    "X": 110,
    "Y": 75,
    "Z": 32
  },
  "heading": 0,
  "localHeading": 0,
  "distance": 129.97195,
  "seenSince": "2022-10-18T12:36:58.2626463Z",
  "seenSeconds": 123
}

Details

The seenSince value indicates when the bot first detected a specific avatar during nearbyavatars_scan.
For example:

The bot logs in.
Time passes (say, 1 hour).
nearbyavatars_scan is called.
Bot sees avatar Guest1, seenSince = "2022-10-18 13:00".
Five minutes later, nearbyavatars_scan is called again.
Bot now sees Guest2, seenSince = "2022-10-18 13:05".

Subsequent calls to nearbyavatars_scan return:

Guest1: seenSince = "2022-10-18 13:00"
Guest2: seenSince = "2022-10-18 13:05"

The seenSeconds value shows how many seconds the avatar has been visible (difference between now and seenSince).

Throttling

The maximum call rate for nearbyavatars_scan is 2 calls per 10 seconds.
Excessive calls will return a "Frequent API requests throttled" error.

Data size

The data returned by this command can be large (up to 10 KB or more), depending on the number of avatars nearby.