Difference between revisions of "LlAttachToAvatar"

From Second Life Wiki
Jump to: navigation, search
m (visibility in first person view added)
m
 
(29 intermediate revisions by 9 users not shown)
Line 1: Line 1:
{{LSL_Function/permission|PERMISSION_ATTACH|grant=the owner}}{{LSL_Function
+
{{LSL_Function
|func_id=113
+
|inject-2=
|func_sleep=0.0
+
{{LSL_Function/permission|PERMISSION_ATTACH|grant=the owner}}
|func_energy=10.0
+
{{Issues/VWR-12525}}{{Issues/SCR-137}}{{Issues/SVC-890}}{{Issues/SCR-277}}
 +
|func_id=113|func_sleep=0.0|func_energy=10.0
 
|func=llAttachToAvatar
 
|func=llAttachToAvatar
|sort=AttachToAvatar
+
|p1_type=integer|p1_subtype=attach_point|p1_name=attach_point|p1_desc=ATTACH_* constant or valid value (see the tables below)
|p1_type=integer|p1_name=attachment|p1_desc=ATTACH_* constant or valid value (see the tables below)
+
|func_desc=Attaches the object to the avatar who has granted permission to the script. The object is taken into the users inventory and attached to {{LSLP|attach_point}}.
|func_desc=Attaches the object to the avatar who has granted permission to the script. The object is taken into the users inventory and attached to the attach point '''attachment'''.
+
|func_footnote=If {{LSLP|attach_point}} is zero, then the object attaches to the attach point it was most recently attached to.
|func_footnote
+
 
|return_text
 
|return_text
 
|spec
 
|spec
|caveats=*The call will fail if the [[llGetPermissionsKey|avatar]] is not the [[llGetOwner|owner]] of the object being attached, even if [[PERMISSION_ATTACH]] has been properly granted.
+
|caveats=*Attach points can be occupied by multiple attachments.{{Footnote|Multiple attachments per attach point were added as result of {{Jira|SCR-277}}|Multiple attachments per attach point were added as result of SCR-277}}
*Two objects cannot be attached to the same attachment point at the same time.
+
**This was not always the case, previously if {{LSLP|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)
+
*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 disable.
 +
*If {{LSLP|attach_point}} is zero but the object was never previously attached, it defaults to the right hand ({{LSL Const|ATTACH_RHAND|integer|6|c=right hand}}).
 +
*If the object is already attached the function fails silently, regardless if the {{LSLP|attach_point}} is a different [[llGetAttached|attach point]]. -- [[Template:Issues/SCR-137|SCR-137]]
 
|examples=
 
|examples=
<lsl>//-- rez object on ground, drop in this script, it will request permissions to attach,
+
<source lang="lsl2">//-- 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,
 
//-- and then attach to the left hand if permission is granted. if permission is denied,
 
//-- then the script complains.
 
//-- then the script complains.
Line 26: Line 28:
 
     run_time_permissions( integer vBitPermissions )
 
     run_time_permissions( integer vBitPermissions )
 
     {
 
     {
         if (PERMISSION_ATTACH & vBitPermissions)
+
         if ( vBitPermissions & PERMISSION_ATTACH )    
        {
+
             llAttachToAvatar( ATTACH_LHAND );    
             llAttachToAvatar( ATTACH_LHAND );
+
         else    
        }
+
             llOwnerSay( "Permission to attach denied" );
         else
+
        {
+
             llOwnerSay( "Permission to attach denied, restarting" );
+
        }
+
 
     }
 
     }
  
 
     on_rez(integer rez)
 
     on_rez(integer rez)
 
     {
 
     {
         if(!llGetAttached())
+
         if (!llGetAttached() )       //reset the script if it's not attached.
        { //reset the script if it's not attached.
+
             llResetScript();    
             llResetScript();
+
        }
+
 
     }
 
     }
  
     attach(key AvatarKey)
+
     attach(key id)
 
     {
 
     {
         if(AvatarKey)
+
         // The attach event is called on both attach and detach, but 'id' is only valid on attach
        {//event is called on both attach and detach, but Key is only valid on attach
+
        if (id)
            integer test = llGetAttached();
+
             llOwnerSay( "The object is attached to " + llKey2Name(id) );
             if (test) {
+
        else  
                llOwnerSay( "The object is attached" );
+
            llOwnerSay( "The object is not attached");
            } else {
+
                llOwnerSay( "The object is not attached");
+
            }
+
        }
+
 
     }
 
     }
}</lsl>
+
}
 +
</source>
 
|helpers
 
|helpers
|also_functions={{LSL DefineRow||[[llDetachFromAvatar]]|Detaches the object from the avatar}}
+
|also_functions=
{{LSL DefineRow||[[llGetAttached]]|Gets the attach point number}}
+
{{LSL DefineRow||[[llAttachToAvatarTemp]]|Attach an object to any avatar but only temporarily}}
 +
{{LSL DefineRow||[[llDetachFromAvatar]]|Detaches the object from the avatar}}
 +
{{LSL DefineRow||[[llGetAttached]]|Gets the attach point number (that the object is attached to)}}
 
|also_articles
 
|also_articles
|also_events
+
|also_events=
 +
{{LSL DefineRow||[[attach]]|}}
 
|constants={{LSL_Constants_Attachment}}
 
|constants={{LSL_Constants_Attachment}}
 
|notes
 
|notes
 
|cat1=Attachment
 
|cat1=Attachment
 
|cat2=Avatar
 
|cat2=Avatar
 +
|haiku={{Haiku|Embrace me. I'm yours|Forever. Even detached|To inventory.}}
 
|cat3
 
|cat3
 
|cat4
 
|cat4
 
}}
 
}}

Latest revision as of 23:29, 21 January 2015

Summary

Function: llAttachToAvatar( integer attach_point );

Attaches the object to the avatar who has granted permission to the script. The object is taken into the users inventory and attached to attach_point.

• integer attach_point ATTACH_* constant or valid value (see the tables below)

To run this function the script must request the PERMISSION_ATTACH permission with llRequestPermissions and it must be granted by the owner. If attach_point is zero, then the object attaches to the attach point it was most recently attached to.

KBnote.png Note: Constants in italic require a viewer compatible with the Project Bento skeleton.
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

Caveats

Permissions
  • Do not depend upon the auto-grant status of permissions. Always use the run_time_permissions event.
  • If the script lacks the permission PERMISSION_ATTACH, the script will shout an error on DEBUG_CHANNEL and the operation fails (but the script continues to run).
  • If PERMISSION_ATTACH is granted by anyone other than the owner, then when the function is called an error will be shouted on DEBUG_CHANNEL.
  • Once the PERMISSION_ATTACH permission is granted there is no way to revoke it except from inside the script (for example, with a new llRequestPermissions call) or the script is reset or deleted.
  • Attach points can be occupied by multiple attachments.[1]
    • 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 disable.
  • 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 if the attach_point is a different attach point. -- SCR-137

Important Issues

~ All Issues ~ Search JIRA for related Bugs
   llAttachToAvatar can cause a stack/heap collision in certain circumstances
   Add companion command to llAttachToAvatar() to allow attaching multiple items in same attachment point

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 )     
            llAttachToAvatar( 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 id)
    {
        // The attach event is called on both attach and detach, but 'id' is only valid on attach
        if (id)
            llOwnerSay( "The object is attached to " + llKey2Name(id) );
        else 
            llOwnerSay( "The object is not attached");
    }
}

See Also

Events

•  run_time_permissions Permission receiving event
•  attach

Functions

•  llGetPermissions Get the permissions granted
•  llGetPermissionsKey Get the agent who granted permissions
•  llRequestPermissions Request permissions
•  llAttachToAvatarTemp Attach an object to any avatar but only temporarily
•  llDetachFromAvatar Detaches the object from the avatar
•  llGetAttached Gets the attach point number (that the object is attached to)

Articles

•  Script permissions

Deep Notes

All Issues

~ Search JIRA for related Issues
   llAttachToAvatar() can cause parentless attachments that can subsequently crash the client when selected
   Allow llAttachToAvatar() to switch attachment locations
   llAttachToAvatar can cause a stack/heap collision in certain circumstances
   Add companion command to llAttachToAvatar() to allow attaching multiple items in same attachment point

Footnotes

  1. ^ Multiple attachments per attach point were added as result of SCR-277

Signature

function void llAttachToAvatar( integer attach_point );

Haiku

Embrace me. I'm yours
Forever. Even detached
To inventory.