How many avatars can sit on the head of a prim?

[Kayaker Magic]

I could not resist that title! What I should have said was:

How to sit many avatars on one prim with one script.

I wrote a set of scripts once to sit multiple avatars on a single prim. It was very complex, requiring a separate script for each potential sitter and a list to keep track of which scripts were in use already. Recently I learned, in How to use llAvatarOnSitTarget, how to sit many avatars on many prims with only one script. So I have taken what I learned and made one script that can sit many avatars on only one prim.

When multiple avatars sit on a single prim, llAvatarOnSitTarget() fails to do anything useful. It always reports the UUID of the first avatar to sit instead of the most recent one. If the first avatar jumps off, llAvatarOnSitTargeg() returns NULL_KEY even if there are still other avatars seated on the prim. Fortunately you can get the UUID of the most reacent avatar from llGetLinkKey(llGetNumberOfPrims()) because the last avatar to sit is always the last 'prim' in the linkset.

Next you have to know where you want to put each avatar. In the script below I used a formula based on the number of avatars sitting. In furniture you could read the positions out of a notecard. After the first avatar sits down, llSitTarget stops working and the following avatars sit where they touched. But since I know where I want each one to go, I force them to move and rotate into place with llSetLinkPrimitiveParamsFast. As I learned, it is not necessary to hold onto permissions after sitting an avatar. So I just ask for new permissions for each new avatar as they arrive, animate them and forget! If you also need other permissions from the avatars, or need to hold onto the permissions, this trick will not work.

Note that this script will only work right if the avatars don't jump on and off after sitting. To fix this you need to keep a list of avatars already seated and what positions they are in. The resulting code would be thrice as big as this and you would not be able to see the essential details here.

 //This demonstrates multiple avatars sitting on one prim
//To keep the example simple, it only works if the avatars don't jump off and back on again
 
integer lastnum;        //last number of prims in the build

default
{
    state_entry()
    {
        llSetClickAction(CLICK_ACTION_SIT);   //force to sit mode
        llSitTarget(<0,0,1.44>,ZERO_ROTATION);        //and set the first sit position
        lastnum=llGetNumberOfPrims();
    } //state_entry
    changed(integer flags)
    {        
        if (flags&CHANGED_LINK)
        {
            integer num=llGetNumberOfPrims();   //goes up every time a new avatar sits
            if (num>lastnum)        //if the number of prims increased, it must be a new sitter
            {               //don't trust llSitTarget, force the avatar to the position you want
                            //note: the most recent avatar to jump on is always the last 'prim' in the link list
                llSetLinkPrimitiveParamsFast(num,[PRIM_POS_LOCAL,<2-num,0,1.44>,PRIM_ROT_LOCAL,ZERO_ROTATION]);
                llRequestPermissions(llGetLinkKey(num),PERMISSION_TRIGGER_ANIMATION); //ask to animate
            }
            lastnum=num;
        }
    } //changed
    run_time_permissions( integer perm )
    {
        if (perm&PERMISSION_TRIGGER_ANIMATION)
        {       
            llStartAnimation("surf");   //put the new guy into the surfing pose
            llStopAnimation("sit");     //stop the default sit animation
        }
    }
} //default