Difference between revisions of "LlSetObjectName"

From Second Life Wiki
Jump to navigation Jump to search
m (Also added a note about linksets)
(clarified the replacement chars for invalid object names, added an example for testing if an object name is valid)
 
(28 intermediate revisions by 11 users not shown)
Line 1: Line 1:
{{LSL Function
{{LSL Function
|inject-2={{LSL_Function/limits}}
|func_id=203
|func_id=203
|func_sleep=0.0
|func_sleep=0.0
|func_energy=10.0
|func_energy=10.0
|func=llSetObjectName
|func=llSetObjectName|sort=SetObjectName
|p1_type=string
|p1_type=string
|p1_name=name
|p1_name=name
|func_desc=Sets the prim's name according to the '''name''' parameter.
|func_desc=Sets the prim's name according to the {{LSLP|name}} parameter.
|func_footnote=Limited to 63 bytes by the client
|func_footnote=If this function is called from a child prim in a linked set, it will change the name of the child prim and not the root prim.
|return_text
|return_text
|spec
|spec
|caveats=*The prim name is limited to 255 bytes, any string longer then that will be truncated. This truncation does not always happen when the attribute is set or read.
|caveats=
* The name is limited to 63 characters. Longer prim names are cut short.
* Names can only consist of the 95 printable characters found in the [http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters ASCII-7] (non-extended) character set, with the exception of the vertical bar/pipe ("<nowiki>|</nowiki>") character.
** Invalid characters in the range 1 to 31, as well as the pipe character (124) are replaced with a question mark ("?").
** Other invalid characters in the range 128 and above are replaced with two or more question marks, depending on how many bytes their UTF-8 representation requires.
** Objects with all-whitespace names (e.g., a space or a series of spaces) will appear as "(Unnamed)" if they emit chat via [[llSay]], [[llOwnerSay]], [[llInstantMessage]], etc., although this behaviour may vary in third-party viewers.
* While an object is attached, the script cannot change the name of the object as it appears in the user's inventory.{{Footnote|2=Whether or not this is a bug is still debated, regardless LL has said they will not fix it. This behavior was first recognized as a pain point in 2006 and only confirmed to be lava-flowed more recently (2011).|1=Whether or not this is a bug is still debated, regardless LL has said they will not fix it. This behavior was first recognized as a pain point in [http://forums-archive.secondlife.com/255/ab/84853/1.html 2006] and only confirmed to be lava-flowed [https://jira.secondlife.com/browse/SVC-3429?focusedCommentId=267372&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-267372 more recently (2011)].}}
** Changes to the name of the root prim (with [[llSetObjectName]] for example) will not be saved to inventory; when the attachment is detached (to inventory, not dropped) this name change is discarded and the name in inventory is used instead.
** When attachment is dropped (to the ground) and taking it into inventory, the inventory item will have the new name (not the old).
* Changes to the names of child prims will be saved back to inventory when the object is detached to inventory. They survive detachment.
|constants
|constants
|examples=<pre>
|examples=
{{{!}} width="100%" {{Prettytable}}
{{!}}- {{Hl2}}
! '''Set this prim's name'''
! '''Set the root prim's name'''
{{!}}-
{{!!}}<source lang="lsl2">
default
default
{
{
     state_entry()
     state_entry()
     {
     {
         llSetObjectName("Object X");
         llSetObjectName("NEW PRIM NAME");
     }
     }
}
}
</pre>
</source>
{{!!}}
<source lang="lsl2">
default
{
    state_entry()
    {
        llSetLinkPrimitiveParamsFast(LINK_ROOT,
            [PRIM_NAME, "NEW ROOT PRIM NAME"]);
    }
}
</source>
{{!}}- {{Hl2}}
! colspan="2" {{!}} '''Test if a string is valid as an object name'''
{{!}}-
{{!}} colspan="2" {{!}}
<source lang="lsl2">
// Returns TRUE if 'name' is a valid object name, FALSE otherwise
integer isValidObjectName(string name)
{
    string original_name = llGetObjectName();
    llSetObjectName(name);
    integer valid_name = llGetObjectName() == name;
    llSetObjectName(original_name);
    return valid_name;
}
</source>
{{!}}}
|helpers
|helpers
|also_functions=
|also_functions=
Line 27: Line 70:
{{LSL DefineRow||[[llGetObjectDesc]]|Get the prims description}}
{{LSL DefineRow||[[llGetObjectDesc]]|Get the prims description}}
{{LSL DefineRow||[[llSetObjectDesc]]|Set the prims description}}
{{LSL DefineRow||[[llSetObjectDesc]]|Set the prims description}}
{{LSL DefineRow||[[llGetObjectDetails]]|Get a list of object details}}
|also_tests
|also_tests
|also_events
|also_events
|also_articles
|also_articles
|notes=*This function will change the name of the object that the script resides in regardless if the object is a root or a child prim inside of a linkset.
|notes
|cat1=Prim
|cat1=Prim
|cat2
|cat2

Latest revision as of 14:17, 9 October 2023

Summary

Function: llSetObjectName( string name );
0.0 Forced Delay
10.0 Energy

Sets the prim's name according to the name parameter.

• string name

If this function is called from a child prim in a linked set, it will change the name of the child prim and not the root prim.

Caveats

  • The name is limited to 63 characters. Longer prim names are cut short.
  • Names can only consist of the 95 printable characters found in the ASCII-7 (non-extended) character set, with the exception of the vertical bar/pipe ("|") character.
    • Invalid characters in the range 1 to 31, as well as the pipe character (124) are replaced with a question mark ("?").
    • Other invalid characters in the range 128 and above are replaced with two or more question marks, depending on how many bytes their UTF-8 representation requires.
    • Objects with all-whitespace names (e.g., a space or a series of spaces) will appear as "(Unnamed)" if they emit chat via llSay, llOwnerSay, llInstantMessage, etc., although this behaviour may vary in third-party viewers.
  • While an object is attached, the script cannot change the name of the object as it appears in the user's inventory.[1]
    • Changes to the name of the root prim (with llSetObjectName for example) will not be saved to inventory; when the attachment is detached (to inventory, not dropped) this name change is discarded and the name in inventory is used instead.
    • When attachment is dropped (to the ground) and taking it into inventory, the inventory item will have the new name (not the old).
  • Changes to the names of child prims will be saved back to inventory when the object is detached to inventory. They survive detachment.

Examples

Set this prim's name Set the root prim's name 
default
{
    state_entry()
    {
        llSetObjectName("NEW PRIM NAME");
    }
}

default
{
    state_entry()
    {
        llSetLinkPrimitiveParamsFast(LINK_ROOT,
            [PRIM_NAME, "NEW ROOT PRIM NAME"]);
    }
}
Test if a string is valid as an object name 
// Returns TRUE if 'name' is a valid object name, FALSE otherwise
integer isValidObjectName(string name)
{
    string original_name = llGetObjectName();
    llSetObjectName(name);
    integer valid_name = llGetObjectName() == name;
    llSetObjectName(original_name);
    return valid_name;
}

See Also

Functions

•  llGetObjectName – Get the prims name
•  llGetLinkName – Get a linked prims name
•  llGetObjectDesc – Get the prims description
•  llSetObjectDesc – Set the prims description
•  llGetObjectDetails – Get a list of object details

Articles

•  Limits – SL limits and constrictions

Deep Notes

Footnotes

  1. ^ Whether or not this is a bug is still debated, regardless LL has said they will not fix it. This behavior was first recognized as a pain point in 2006 and only confirmed to be lava-flowed more recently (2011).

Signature

function void llSetObjectName( string name );
Retrieved from "https://wiki.secondlife.com/w/index.php?title=LlSetObjectName&oldid=1214977"