Recommendation: GSI LNX (v1)
Structured key-value pair naming scheme to categorize LSL/SLua linkset data pairs
The Global Scripting Institute (GSI) is an informal organization of Second Life® users that design and test standards for efficient, flexible, and readable scripts in Second Life. "Second Life®" and "Second Life Grid™" are trademarks of Linden Research, Inc., d/b/a Linden Lab. The Global Scripting Institute and its catalog are not affiliated with or sponsored by Linden Research.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.
The Linkset_data Namespace eXtensions (LNX) is a naming scheme for llLinksetData*/linkset_data pairs in Linden Scripting Language (LSL) and SLua.
LSL-style syntax is used throughout this document, but all specifications also apply to accessing the linkset_data datastore via ll.LinksetData*.
Native linkset data is a key-value datastore that is specific to a single linkset. LNX extends this by enforcing a mandatory naming scheme that assigns linkset data pairs to a specific scope - "linkset-scope", "prim-scope", and "script-scope" - by optionally incorporating the prim UUID and script name in the linkset data pair name.
Additionally, LNX defines a standardized structure for using lists (arrays) to define pair names instead of strings.
This naming scheme is primarily designed to allow for complex cross-vendor script interoperability in the same object without accidentally modifying data managed by other scripts.
When a script that supports LNX writes to or reads from linkset data, it MAY use a linkset data pair name that does not contain any newline ("\n") characters. If so, these are "non-LNX" pairs that are outside the scope of this recommendation. However, if the script does not do this, it MUST use the LNX naming scheme. In other words, any pair that contains a newline ("\n") character MUST be an LNX pair.
Linkset data pairs that use LNX MUST be named using a list (the "pair name list") dumped to a string with newline ("\n") delineation.
LNX pairs may be one of three scopes - linkset-scope, prim-scope, and script-scope.
A linkset-scope pair operates the same as writing raw linkset data, but using the LNX naming scheme. That is, it can be accessed by any script in any prim in the entire linkset. Except when performing maintenance or cleanup, linkset-scope pairs MUST be written and read as follows:
llLinksetDataWrite(llDumpList2String(["", ""] + pair_name_list, "\n"), data)
string data = llLinksetDataRead(llDumpList2String(["", ""] + pair_name_list, "\n"))
A prim-scope pair is only accessible to scripts within the same prim. Prim-scope pairs must be maintained when the prim UUID changes due to re-rezzing (see "Prim UUID Maintenance" section below). Except when performing maintenance or cleanup, prim-scope pairs MUST be written and read as follows:
llLinksetDataWrite(llDumpList2String([llGetKey(), ""] + pair_name_list, "\n"), data)
string data = llLinksetDataRead(llDumpList2String([llGetKey(), ""] + pair_name_list, "\n"))
A script-scope pair is only accessible to the script that wrote it within the same prim. Script-scope pairs, like prim-scope pairs, must be maintained when the prim UUID changes due to re-rezzing (see "Prim UUID Maintenance" section below). Except when performing maintenance or cleanup, script-scope pairs MUST be written and read as follows:
llLinksetDataWrite(llDumpList2String([llGetKey(), llGetScriptName()] + pair_name_list, "\n"), data)
string data = llLinksetDataRead(llDumpList2String([llGetKey(), llGetScriptName()] + pair_name_list, "\n"))
In all of the above examples, pair_name_list MUST be a list of one or more values that do not contain any newline ("\n") characters.
LNX pairs MUST NOT use the llLinksetData*Protected functions. These functions make it impossible for other scripts to selectively clean the datastore of disassociated keys (see section on "Periodic Cleanup" below).
If prim-scope or script-scope pairs are used, the LNX script MUST perform prim UUID maintenance when the prim UUID changes due to re-rezzing or duplication. When this happens, the LNX script MUST iterate through all keys using llLinksetDataFindKeys and move any pairs that are associated with the prim's previous UUID.
As objects are linked and unlinked and scripts added and removed, the LNX datastore can fill up with pairs from prims and/or scripts that are no longer part of the linkset. If this happens, the linkset data datastore can run out of space.
LNX scripts SHOULD perform periodic cleanup on LNX linkset data pairs by pruning pairs that are associated with any prim UUID that is not part of the same linkset. If the LNX script is in the same prim as the pair's associated prim, it SHOULD also prune pairs that are associated with any script that is no longer in the same prim's inventory.
LNX scripts MAY perform this action either automatically or at the user's request, depending on the data's tolerance for accidental loss.
Can I modify other prims' or other scripts' LNX pairs?
No. LNX-aware scripts MUST NOT access pairs outside their designated scopes to be considered compliant with the LNX recommendation, except to perform maintenance.
Can I use the same pair name list in multiple scopes?
Yes. The same pair name list MAY be used in multiple scopes, and this will create multiple linkset data pairs.
LNX does not enforce priority of one scope over the other. For example, a pair with the name list ["abc"] MAY be written to multiple scopes with potentially conflicting data. It is up to the script reading the values on whether or how to resolve these conflicts.
What is the benefit of linkset-scope LNX pairs over using plain "non-LNX" linkset data names?
LNX only provides the hierarchical naming scheme in this instance; if you don't need that, it may not be worth using. Note that "non-LNX" and LNX pairs can coexist in the same datastore as long as the "non-LNX" pairs do not use any newline ("\n") characters in their names.
Why doesn't LNX use JSON?
JSON complicates regex-based linkset data operations due to lack of ordering and higher byte overhead. JSON data SHOULD be stored in the value, not the name.
LNX was authored by Nelson Jenkins on behalf of GSI.