Difference between revisions of "LlGetAgentList"

From Second Life Wiki
Jump to navigation Jump to search
Line 6: Line 6:
|func_sleep=0.0
|func_sleep=0.0
|func_energy=0
|func_energy=0
|func_desc=Requests a list of agents currently in the region, limited by the flags parameter.
|func_desc=Requests a list of agents currently in the region, limited by the scope parameter.
|func_footnote=
|func_footnote=
|return_type=list
|return_type=list
|return_text=[key id0, key id1, ..., key idn] or [string error_msg] -  returns avatar keys for all agents in the region limited to the area(s) specified by flags
|return_text=[key id0, key id1, ..., key idn] or [string error_msg] -  returns avatar keys for all agents in the region limited to the area(s) specified by scope
|spec=
|spec=
|p1_type=integer|p1_name=max_agents|p1_desc=Maximum number of agents to return in the list. Must be greater than 0 and less than 200. |p1_hover=max agents to return
|p1_type=integer|p1_name=scope|p1_desc=selection scope
|p2_type=integer|p2_name=flags|p2_desc=selection flags
* AGENT_LIST_PARCEL - returns only agents on the same parcel where the script is running.
* AGENT_LIST_PARCEL - returns only agents on the same parcel where the script is running.
* AGENT_LIST_PARCEL_OWNER - returns only agents on any parcel in the region where the parcel owner is the same as the owner of the parcel under the scripted object.
* AGENT_LIST_PARCEL_OWNER - returns only agents on any parcel in the region where the parcel owner is the same as the owner of the parcel under the scripted object.
* AGENT_LIST_REGION - returns any/all agents in the region.
* AGENT_LIST_REGION - returns any/all agents in the region.
|p2_type=list|p2_name=options|p2_desc=Unused.
|p2_hover=selection flags
|p2_hover=selection flags
|constants=
|constants=
|caveats=
|caveats=
* There is no guaranteed understandable order or randomness to the list returned.
* There is no guaranteed understandable order or randomness to the list returned.
* If there are more agents than max_agents, the agents returned will not be random nor meaningfully ordered.
* Will only return up to 100 agents.
* If no agents enter or leave the list returned will probably not change.
** Example: in a region with 20 agents, llGetAgentList(5,AGENT_LIST_REGION) will return 5 arbitrary agents. It will probably return the same 5 as long as no one enters or leaves the region, but that is not guaranteed. It will not cycle through the agents in any way and the 5 agents returned are not random.
** Example: llGetAgentList(1,AGENT_LIST_PARCEL) is '''NOT''' a good way to get 1 random resident on a parcel because the result is '''not random'''.
* It is recommended to set max_agents as high as needed for the possible number of agents to process and low enough that a list with that many UUIDs would not cause a Stack-Heap Collision error.
* Examples and shared code should use 100 for max_agents unless specifically required to be something else: this will ensure that the script will work in all current regions in Second Life.
|examples=<lsl>//Displays up to 100 avatar key: name pairs detected in the entire region
|examples=<lsl>//Displays up to 100 avatar key: name pairs detected in the entire region
list gaAgents;
list gaAgents;
integer giMaxAgentsToReturn = 100;


default
default
Line 37: Line 31:
         integer  liCount;
         integer  liCount;
         gaAgents = llGetAgentList(giMaxAgentsToReturn,AGENT_LIST_REGION);
         gaAgents = llGetAgentList(AGENT_LIST_REGION, []);
         liCount = llGetListLength(gaAgents);
         liCount = llGetListLength(gaAgents);
         if (liCount > 0)
         if (liCount > 0)

Revision as of 14:13, 21 March 2012

Emblem-important-red.png Pre-release Documentation Warning!

This function is not available yet. This documentation was written prior to its final release so it may not match the final implementation.

Summary

Function: list llGetAgentList( integer scope, list options );

Requests a list of agents currently in the region, limited by the scope parameter.
Returns a list [key id0, key id1, ..., key idn] or [string error_msg] - returns avatar keys for all agents in the region limited to the area(s) specified by scope

• integer scope – selection scope
  • AGENT_LIST_PARCEL - returns only agents on the same parcel where the script is running.
  • AGENT_LIST_PARCEL_OWNER - returns only agents on any parcel in the region where the parcel owner is the same as the owner of the parcel under the scripted object.
  • AGENT_LIST_REGION - returns any/all agents in the region.
• list options – Unused.

Caveats

  • There is no guaranteed understandable order or randomness to the list returned.
  • Will only return up to 100 agents.
All Issues ~ Search JIRA for related Bugs

Examples

<lsl>//Displays up to 100 avatar key: name pairs detected in the entire region list gaAgents;

default { 

   touch_start(integer total_number)
   {
       integer  i;
       integer  liCount;

       gaAgents = llGetAgentList(AGENT_LIST_REGION, []);
       liCount = llGetListLength(gaAgents);
       if (liCount > 0)
           if (llGetListEntryType(gaAgents,0) == TYPE_STRING)
               llOwnerSay("Error: "+llList2String(gaAgents,0));
           else
               for (i=0; i < liCount; ++i)
                   llOwnerSay(llList2String(gaAgents,i)+": "+llKey2Name(llList2String(gaAgents,i)));
  }
}</lsl>

See Also

Deep Notes

Search JIRA for related Issues

Signature

function list llGetAgentList( integer scope, list options );
Retrieved from "https://wiki.secondlife.com/w/index.php?title=LlGetAgentList&oldid=1164464"