Difference between revisions of "HTTP API/Bot Commands/nearbyavatars scan"

From SmartBots Developers Docs
Jump to: navigation, search
(Created page with "{{DISPLAYTITLE: nearbyavatars_scan}} <onlyinclude>Scans current region for other avatars.</onlyinclude> {{API Variables Table}} {{API HTTP Required Vars| nearbyavatars_scan}...")
 
 
Line 1: Line 1:
 
{{DISPLAYTITLE: nearbyavatars_scan}}
 
{{DISPLAYTITLE: nearbyavatars_scan}}
 
<onlyinclude>Scans current region for other avatars.</onlyinclude>
 
<onlyinclude>Scans current region for other avatars.</onlyinclude>
 +
 +
This API call might not be suitable for LSL because of large amount of data received.
  
 
{{API Variables Table}}
 
{{API Variables Table}}

Latest revision as of 15:48, 18 October 2022

Scans current region for other avatars.

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

Variables

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

Variable Required Description
Input basic parameters:
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:
Output:
(to be received in http_response LSL event, see docs for details)
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 more info.

Return value

'avatars' field of the response is an array and contains the list of avatars our bot sees: 

{
  // Avatar name
  "name": "GrrrillaBongo Resident",
  // Avatar UUID
  "UUID": "d8e20552-ca84-4c42-b8d3-e8fa5fbdcc6b",

  // The parcel this avatar currently in
  "parcelID": 177,

  // If avatar is sitting on something
  "sitting": false,

  // Position of avatar in-world
  "position": {
    "X": 110,
    "Y": 75,
    "Z": 32
  },
  // Local position. If avatar is sitting this position is relative to sit parent
  "localPosition": {
    "X": 110,
    "Z": 32,
    "Y": 75
  },
  // Avatar heading (the view direction)
  "heading": 0,
  // Local heading (for sitting avatars)
  "localHeading": 0,

  // The distance to this avatar
  "distance": 129.97195,

  // When we seen this avatar for first time (see Details)
  "seenSince": "2022-10-18T12:36:58.2626463Z",
  // How much seconds do we see this avatar
  "seenSeconds": 123,
}

Details

'seenSince' value shows when we saw the specific avatar for the first time when running nearbyavatars_scan. For example:

  1. Bot logs on. Time passes (say, 1 hour).
  2. 'nearbyavatars_scan' command sent
  3. Bot sees one avatar, Guest1 and sets seenSince to current time (say, "2022-10-18 13:00")
  4. 5 minutes passes
  5. 'nearbyavatars_scan' sent again
  6. Now bot sees that another avatar arrived - Guest2. Its seenSince will be "2022-10-18 13:05"

Thus, all further calls to 'nearbyavatars_scan' will return:

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

SeenSeconds shows the number of seconds we see avatar (the difference between now and seenSince).

Throttling

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

Data size

The amount of data returned by this command can be pretty large (up to 10kb and more).


<< return back to Bot commands

(Miss an API call or parameter? Submit your request in forum)


Retrieved from "https://www.mysmartbots.com/dev/docs/index.php?title=HTTP_API/Bot_Commands/nearbyavatars_scan&oldid=2184"