LlAttachToAvatarTemp

Wiki description

Follows the same convention as llAttachToAvatar, with the exception that the object will not create new inventory for the user, and will disappear on detach or disconnect. Also, this function can be used on avatars other than the owner (if granted permission) in which case the ownership is changed to the new wearer.

Function notes

It should be noted that when an object is attached temporarily, a user cannot 'take' or 'drop' the object that is attached to them.

The user does not have to be the owner of the object in advance; this function transfers ownership automatically (the usual permissions required to transfer objects apply).

If attach_point is zero, then the object attaches to the attach point it was most recently attached to.

Specification

**Body**
Constant	#	Name	Comment
ATTACH_HEAD	2	Skull	head
ATTACH_NOSE	17	Nose	nose
ATTACH_MOUTH	11	Mouth	mouth
''ATTACH_FACE_TONGUE''	52	Tongue	tongue
ATTACH_CHIN	12	Chin	chin
''ATTACH_FACE_JAW''	47	Jaw	jaw
ATTACH_LEAR	13	Left Ear	left ear
ATTACH_REAR	14	Right Ear	right ear
''ATTACH_FACE_LEAR''	48	Alt Left Ear	left ear (extended)
''ATTACH_FACE_REAR''	49	Alt Right Ear	right ear (extended)
ATTACH_LEYE	15	Left Eye	left eye
ATTACH_REYE	16	Right Eye	right eye
''ATTACH_FACE_LEYE''	50	Alt Left Eye	left eye (extended)
''ATTACH_FACE_REYE''	51	Alt Right Eye	right eye (extended)
ATTACH_NECK	39	Neck	neck
ATTACH_LSHOULDER	3	Left Shoulder	left shoulder
ATTACH_RSHOULDER	4	Right Shoulder	right shoulder
ATTACH_LUARM	20	L Upper Arm	left upper arm
ATTACH_RUARM	18	R Upper Arm	right upper arm
ATTACH_LLARM	21	L Lower Arm	left lower arm
ATTACH_RLARM	19	R Lower Arm	right lower arm
ATTACH_LHAND	5	Left Hand	left hand
ATTACH_RHAND	6	Right Hand	right hand
''ATTACH_LHAND_RING1''	41	Left Ring Finger	left ring finger
''ATTACH_RHAND_RING1''	42	Right Ring Finger	right ring finger
''ATTACH_LWING''	45	Left Wing	left wing
''ATTACH_RWING''	46	Right Wing	right wing
ATTACH_CHEST	1	Chest	chest/sternum
ATTACH_LEFT_PEC	29	Left Pec	left pectoral
ATTACH_RIGHT_PEC	30	Right Pec	right pectoral
ATTACH_BELLY	28	Stomach	belly/stomach/tummy
ATTACH_BACK	9	Spine	back
''ATTACH_TAIL_BASE''	43	Tail Base	tail base
''ATTACH_TAIL_TIP''	44	Tail Tip	tail tip
ATTACH_AVATAR_CENTER	40	Avatar Center	avatar center/root
ATTACH_PELVIS	10	Pelvis	pelvis
''ATTACH_GROIN''	53	Groin	groin
ATTACH_LHIP	25	Left Hip	left hip
ATTACH_RHIP	22	Right Hip	right hip
ATTACH_LULEG	26	L Upper Leg	left upper leg
ATTACH_RULEG	23	R Upper Leg	right upper leg
ATTACH_RLLEG	24	R Lower Leg	right lower leg
ATTACH_LLLEG	27	L Lower Leg	left lower leg
ATTACH_LFOOT	7	Left Foot	left foot
ATTACH_RFOOT	8	Right Foot	right foot
''ATTACH_HIND_LFOOT''	54	Left Hind Foot	left hind foot
''ATTACH_HIND_RFOOT''	55	Right Hind Foot	right hind foot

**HUD**
Constant		Comment
ATTACH_HUD_CENTER_2	31	HUD Center 2
ATTACH_HUD_TOP_RIGHT	32	HUD Top Right
ATTACH_HUD_TOP_CENTER	33	HUD Top
ATTACH_HUD_TOP_LEFT	34	HUD Top Left
ATTACH_HUD_CENTER_1	35	HUD Center
ATTACH_HUD_BOTTOM_LEFT	36	HUD Bottom Left
ATTACH_HUD_BOTTOM	37	HUD Bottom
ATTACH_HUD_BOTTOM_RIGHT	38	HUD Bottom Right

**Special**
Constant		Comment
ATTACH_ANY_HUD	-1	A special constant representing all HUD attachment points when filtering.

Caveats

When object ownership changes, any granted permissions are reset. After a successful attach, you will need a fresh call to llRequestPermissions to allow llDetachFromAvatar and other permission-required functions to work.
- Until successful attachment via this method, previously granted permissions are retained as normal.
The attach step is not guaranteed to succeed, and this function should not be relied on as a security measure. Use the same permission and script precautions you would use with conventional inventory transfers.
If you use llAttachToAvatarTemp in an object that you do not have permission to transfer, the function will fail with a script error No permission to transfer, even if you are trying to attach it to yourself.
Temporary attachments cannot request the permission PERMISSION_TELEPORT, the following error will be returned: "Temporary attachments cannot request runtime permissions to teleport"
Attach points can be occupied by multiple attachments.^{Multiple attachments per attach point were added as result of SCR-277}
- This was not always the case, previously if attach_point was occupied, the existing object was detached and the new attachment took it's place.
Objects attached to the head (and any attachment position within the head) will not be visible in First Person view (aka Mouselook) if "show attachments in mouselook" is disabled.
If attach_point is zero but the object was never previously attached, it defaults to the right hand (ATTACH_RHAND).
If the object is already attached the function fails silently, regardless of the attach_point being a different attach point.
If attached via a Land Scope Experience script, the object will be force-detached by the server if the owner enters a parcel that does not have the Experience allowed.
If the target agent is already wearing the maximum number of attachments, the object will remain on the ground with the target agent as owner. Scripters may wish to do one or more workarounds:
- check for successful attachment and llDie() after a timeout or if the object is manipulated while unattached
- check llGetObjectDetails(avatarKey, [OBJECT_ATTACHED_SLOTS_AVAILABLE]) beforehand, and avoid attaching if zero slots available

Examples

//-- rez object on ground, drop in this script, it will request permissions to attach,
//-- and then attach to the left hand if permission is granted. if permission is denied,
//-- then the script complains.
default
{
    state_entry()
    {
        llRequestPermissions( llGetOwner(), PERMISSION_ATTACH );
    }

    run_time_permissions( integer vBitPermissions )
    {
        if( vBitPermissions & PERMISSION_ATTACH )
        {
            llAttachToAvatarTemp( ATTACH_LHAND );
        }
        else
        {
            llOwnerSay( "Permission to attach denied" );
        }
    }

    on_rez(integer rez)
    {
        if(!llGetAttached())
        { //reset the script if it's not attached.
            llResetScript();
        }
    }

    attach(key AvatarKey)
    {
        if(AvatarKey)
        {//event is called on both attach and detach, but Key is only valid on attach
            integer test = llGetAttached();
            if (test) {
                llOwnerSay( "The object is attached" );
            } else {
                llOwnerSay( "The object is not attached");
            }
        }
    }
}

//-- This example can demonstrate ownership transfer of an object on a temporary basis using llAttachToAvatarTemp()
//-- Whoever touches will be asked for permission to attach, and upon granting permission will have the item attach,
//-- But not appear in Inventory.
default
{
    touch_start(integer num_touches)
    {
        llRequestPermissions( llDetectedKey(0), PERMISSION_ATTACH );
    }

    run_time_permissions( integer vBitPermissions )
    {
        if( vBitPermissions & PERMISSION_ATTACH )
        {
            llAttachToAvatarTemp( ATTACH_LHAND );
        }
        else
        {
            llOwnerSay( "Permission to attach denied" );
        }
    }

    on_rez(integer rez)
    {
        if(!llGetAttached())
        { //reset the script if it's not attached.
            llResetScript();
        }
    }
}

// This example illustrates how to handle permissions before and after llAttachToAvatarTemp has been called. Because ownership
// changes when the object is attached, the initial PERMISSION_ATTACH is revoked, and new permissions need to be requested.

integer gAttach = TRUE;

default
{

    touch_start(integer num)
    {
        if (gAttach)  // Object has not been attached yet
        {
            llRequestPermissions(llDetectedKey(0),PERMISSION_ATTACH);
            gAttach = FALSE;
        }
        else   // Object has been attached, but you still need PERMISSION_ATTACH in order to detach the object
        {
            if (llGetPermissions() & PERMISSION_TRIGGER_ANIMATION | PERMISSION_ATTACH)
            {
                llDetachFromAvatar();  // Note that the object vanishes when detached, so there is no need to set gAttach = TRUE again
            }
        }
    }

    attach(key id)
    {
        if (id)  // Object has been attached, so request permissions again
        {
            llRequestPermissions(id,PERMISSION_ATTACH | PERMISSION_TRIGGER_ANIMATION);
        }
    }

    run_time_permissions (integer perm)
    {
        if (!gAttach)  //First time
        {
            if (perm & PERMISSION_ATTACH)
            {
                gAttach = TRUE;
                llAttachToAvatarTemp(ATTACH_HEAD);  // Initial PERMISSION_ATTACH is revoked at this point
            }
        }
        else  // Second time
        {
            if (perm & PERMISSION_ATTACH | PERMISSION_TRIGGER_ANIMATION)
            {
                llStartAnimation(llGetInventoryName(INVENTORY_ANIMATION,0));
            }
        }
    }
}

An alternative solution:

// Because ownership changes when the object is attached, the initial PERMISSION_ATTACH is revoked, and new permissions need to be requested.

default
{
    touch_start(integer num)
    {
        if (!llGetAttached()) llRequestPermissions( llDetectedKey(0), PERMISSION_ATTACH);
        else if ( llGetPermissions() & PERMISSION_ATTACH) llDetachFromAvatar();
    }
    attach(key id)
    {
        if (id) llRequestPermissions( id, PERMISSION_ATTACH | PERMISSION_TRIGGER_ANIMATION);
    }
    run_time_permissions (integer perm)
    {
        if (!llGetAttached() && (perm & PERMISSION_ATTACH)) llAttachToAvatarTemp( ATTACH_NOSE);
        if (perm & PERMISSION_TRIGGER_ANIMATION) llStartAnimation( llGetInventoryName( INVENTORY_ANIMATION, 0));
    }
}

History

Date of Release 24/07/2012

Shared wiki helpers

The original page also injects shared parameter notes, caveats or issue information through these helpers. Their conditional MediaWiki logic is not reproduced here; inspect the preserved helper source for additional material.

Template:Issues/SCR-395

Original shared helper source (conditional wiki logic is not evaluated)

{{Issues|SCR-395|[[llAttachToAvatarTemp]] worn objects do not keep group name.|type=bug}}

Template:LSL Function/permission