Difference between revisions of "LlGetAgentList"

From Second Life Wiki
Jump to: navigation, search
(Added link to BUG-227045)
 
(35 intermediate revisions by 14 users not shown)
Line 1: Line 1:
 
{{LSL_Function
 
{{LSL_Function
|inject-2={{Issues/Svc-5488}}{{Issues/MISC-243}}{{LSL_Function/avatar|avatar|sim=*}}
+
|inject-2={{Issues/SCR-311}}{{Issues/SVC-5488}}{{Issues/MISC-243}}{{Issues/BUG-40680}}{{Issues/BUG-40681}}{{Issues/BUG-227045}}
 
|func=llGetAgentList
 
|func=llGetAgentList
 
|sort=GetAgentList
 
|sort=GetAgentList
|func_id=0
+
|func_id
|func_sleep=0.0
+
|func_sleep=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.
* 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.
+
 
|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 specified by flags
+
|return_text=<code><nowiki>[</nowiki>[[key]]&nbsp;{{HoverText|id0|First agent key}}, [[key]]&nbsp;{{HoverText|id1|Second agent key}}, ..., [[key]]&nbsp;{{HoverText|idn|nᵗʰ agent key}}]</code> or <code><nowiki>[</nowiki>[[string]]&nbsp;{{HoverText|error_msg|An error message}}]</code> -  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_hover=AGENT_LIST_* flag specifies the selection scope|p1_desc=<span></span>
|p2_type=integer|p2_name=flags|p2_desc=selection flags|p2_hover=selection flags
+
{{Collapsible_Table/Simple|title=AGENT_LIST_* flag specifies the selection scope
 +
|content={{!}}
 +
* [[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.
 +
}}
 +
|p2_type=list|p2_subtype=instructions|p2_name=options|p2_desc=Unused.
 
|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.
+
* Ghosts, agents that leave behind a corrupted presence and agents in God Mode depending on the level will have NULL_KEY returned instead of their real key with llGetAgentList(). There is also an issue with a certain type of ghosted agent still returning a key too. Perhaps check each key against llGetAgentSize() to verify if they're really in the sim or not; none of the above anomalies affect llGetAgentSize().
** 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'''.
+
|examples=
* 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.
+
{{LSL Tip|To check if an avatar is in the same sim, please check whether [[llGetAgentSize]] does NOT return [[ZERO_VECTOR]]. It's much faster and easier than calling [[llGetAgentList]] and running through the list to compare a given key with each list item.}}
* 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.
+
{{LSL Tip|As of now, this function does not have a delimiter for its option list. This means, the function MIGHT return up to a hundred avatar keys. You'll need a lot of free memory to be able to store those keys, be warned of possible STACK_HEAP_COLLISION_ERRORs.}}
|examples=<lsl>//Displays up to 100 avatar key: name pairs detected in the entire region
+
<source lang="lsl2">
list gaAgents;
+
//Displays up to 100 avatar key: name pairs detected in the entire region
integer giMaxAgentsToReturn = 100;
+
  
 
default
 
default
Line 33: Line 35:
 
     touch_start(integer total_number)
 
     touch_start(integer total_number)
 
     {
 
     {
         integer i;
+
        list avatarsInRegion = llGetAgentList(AGENT_LIST_REGION, []);
         integer liCount;
+
         integer numOfAvatars = llGetListLength(avatarsInRegion);
+
 
         gaAgents = llGetAgentList(giMaxAgentsToReturn,AGENT_LIST_REGION);
+
        // if no avatars, abort avatar listing process and give a short notice
         liCount = llGetListLength(gaAgents);
+
        if (!numOfAvatars)
         if (liCount > 0)
+
        {
             if (llGetListEntryType(gaAgents,0) == TYPE_STRING)
+
            llOwnerSay("No avatars found within the region!");
                llOwnerSay("Error: "+llList2String(gaAgents,0));
+
            return;
            else
+
        }
                for (i=0; i < liCount; ++i)
+
 
                    llOwnerSay(llList2String(gaAgents,i)+": "+llKey2Name(llList2String(gaAgents,i)));
+
         integer index;
  }
+
        while (index < numOfAvatars)
}</lsl>
+
         {
 +
            key id = llList2Key(avatarsInRegion, index);
 +
            string name = llKey2Name(id);
 +
 
 +
            llOwnerSay(name + " [ " + (string)id + " ]");
 +
            ++index;
 +
        }
 +
    }
 +
}
 +
</source>
 +
<source lang="lsl2">
 +
//  Orders new list based on distance
 +
//  and returns names and distances on touch
 +
 
 +
default
 +
{
 +
    touch_start(integer num_detected)
 +
    {
 +
        list keys = llGetAgentList(AGENT_LIST_REGION, []);
 +
         integer numberOfKeys = llGetListLength(keys);
 +
 
 +
         vector currentPos = llGetPos();
 +
        list newkeys;
 +
        key thisAvKey;
 +
 
 +
        integer i;
 +
        for (i = 0; i < numberOfKeys; ++i) {
 +
             thisAvKey = llList2Key(keys,i);
 +
            newkeys += [llRound(llVecDist(currentPos,
 +
                            llList2Vector(llGetObjectDetails(thisAvKey, [OBJECT_POS]), 0))),
 +
                        thisAvKey];
 +
        }
 +
 
 +
        newkeys = llListSort(newkeys, 2, FALSE);    //  sort strided list by descending distance
 +
 
 +
        for (i = 0; i < (numberOfKeys * 2); i += 2) {
 +
            llOwnerSay(llGetDisplayName(llList2Key(newkeys, i+1))
 +
                +" ["+ (string) llList2Integer(newkeys, i) + "m]");
 +
        }
 +
    }
 +
}
 +
</source>
 
|helpers
 
|helpers
 
|also_header
 
|also_header
|also_functions=
+
|also_functions=*[[llGetRegionAgentCount]]
 
|also_tests
 
|also_tests
 
|also_events
 
|also_events
 
|also_articles
 
|also_articles
 
|also_footer
 
|also_footer
|notes=
+
|notes
|mode=request
+
 
|deprecated
 
|deprecated
 
|location
 
|location
 +
|history=
 +
* New function proposed by LL, reconciling the feature suggestions {{Jira|SVC-805}}, {{Jira|SVC-6427}}, {{Jira|MISC-243}} and {{Jira|SVC-5488}}.
 +
* Pre-Released [[Release_Notes/Second_Life_RC_Magnum/12]] - Original JIRA requested "llGetRegionAgents()", the name changed since the released function does more.
 +
* Date of Release  [[ Release_Notes/Second_Life_Server/12#12.04.30.255166 | 30/04/2012 ]]
 
|cat1=Functions
 
|cat1=Functions
|cat2
+
|cat2=Avatar
|cat3
+
|cat3=Owner
|cat4
+
|cat4=Parcel
|cat5
+
|cat5=Region
 
|cat6
 
|cat6
 
}}
 
}}

Latest revision as of 06:14, 29 May 2019

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
AGENT_LIST_* flag specifies the 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.
  • Ghosts, agents that leave behind a corrupted presence and agents in God Mode depending on the level will have NULL_KEY returned instead of their real key with llGetAgentList(). There is also an issue with a certain type of ghosted agent still returning a key too. Perhaps check each key against llGetAgentSize() to verify if they're really in the sim or not; none of the above anomalies affect llGetAgentSize().
All Issues ~ Search JIRA for related Bugs

Examples

KBcaution.png Important: To check if an avatar is in the same sim, please check whether llGetAgentSize does NOT return ZERO_VECTOR. It's much faster and easier than calling llGetAgentList and running through the list to compare a given key with each list item.
KBcaution.png Important: As of now, this function does not have a delimiter for its option list. This means, the function MIGHT return up to a hundred avatar keys. You'll need a lot of free memory to be able to store those keys, be warned of possible STACK_HEAP_COLLISION_ERRORs.
//Displays up to 100 avatar key: name pairs detected in the entire region
 
default
{
    touch_start(integer total_number)
    {
        list avatarsInRegion = llGetAgentList(AGENT_LIST_REGION, []);
        integer numOfAvatars = llGetListLength(avatarsInRegion);
 
        // if no avatars, abort avatar listing process and give a short notice
        if (!numOfAvatars)
        {
            llOwnerSay("No avatars found within the region!");
            return;
        }
 
        integer index;
        while (index < numOfAvatars)
        {
            key id = llList2Key(avatarsInRegion, index);
            string name = llKey2Name(id);
 
            llOwnerSay(name + " [ " + (string)id + " ]");
            ++index;
        }
    }
}
//  Orders new list based on distance
//  and returns names and distances on touch
 
default
{
    touch_start(integer num_detected)
    {
        list keys = llGetAgentList(AGENT_LIST_REGION, []);
        integer numberOfKeys = llGetListLength(keys);
 
        vector currentPos = llGetPos();
        list newkeys;
        key thisAvKey;
 
        integer i;
        for (i = 0; i < numberOfKeys; ++i) {
            thisAvKey = llList2Key(keys,i);
            newkeys += [llRound(llVecDist(currentPos,
                            llList2Vector(llGetObjectDetails(thisAvKey, [OBJECT_POS]), 0))),
                        thisAvKey];
        }
 
        newkeys = llListSort(newkeys, 2, FALSE);     //  sort strided list by descending distance
 
        for (i = 0; i < (numberOfKeys * 2); i += 2) {
            llOwnerSay(llGetDisplayName(llList2Key(newkeys, i+1))
                +" ["+ (string) llList2Integer(newkeys, i) + "m]");
        }
    }
}

See Also

Deep Notes

History

All Issues

~ Search JIRA for related Issues
   llGetAgentList() with scope AGENT_LIST_PARCEL or AGENT_LIST_PARCEL_OWNER returns empty list when attached to avatar
   AGENT_LIST_LIMIT option for llGetAgentList()
   llGetNumberOfAgents() - companion to llGetAgentList() for retrieving count only.

Signature

function list llGetAgentList( integer scope, list options );