Basics
Verbose function names have been a bane of LSL programmers for more than two decades, and they greatly contribute to the difficulty of reading, writing, and debugging code.
The standard NS headers, utils.lsl. and objects.lsl, address this problem by replacing most of the frequently-used functions with straightforward and intuitive macros, influenced by common and user-friendly languages like BASIC, Python, and PHP.
Here are some examples of how much more legible and efficient these macros are:
- llListFindList(haystack, [needle]) → index(haystack, needle)
- llParseString2List(text, [separator], []) → split(text, separator)
- llDumpList2String(terms, separator) → concat(terms, separator)
In a few cases, like index() and split() above, new names are only provided for simplified, frequently-used cases—there's no direct macro for the full expressivity of llParseString2List(), as these features are only rarely useful. However the headers do not prevent access to the original names, so you are free to resort to using them when necessary. The standard NS headers are mainly about convenience, and include a few common utility functions that are missing from the basic LSL function library.
Here are all the macros and functions in each header:
utils.lsl
The utils file mainly focuses on data manipulation functions, though it includes a few macros for communication as well.
| integer contains(list haystack, any needle) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns a non-zero value if needle is in haystack; otherwise 0. This macro cannot directly handle list literals, so wrap them in (parentheses) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| integer index(list haystack, any needle) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns the index of needle's first occurrence if it is in haystack; otherwise -1. This macro cannot handle list literals, so wrap them in (parens) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| integer strlen(string s) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns the length of the specified string in characters; see also strlen_byte() | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| substr(string s, integer x, integer y) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns a contiguous substring of the specified string, starting from position x and ending at position y, inclusive of both end-points; negative indices count from the end of the string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| integer strpos(string haystack, string needle) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns the index of needle's first occurrence if it is in haystack; otherwise -1 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| string strdelete(string s, integer x, integer y) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns a copy of a string with the subrange [x, y] removed, inclusive of both endpoints; negative indices count from the end of the string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| string delstring(string s, integer x, integer y) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns a copy of a string with the subrange [x, y] removed, inclusive of both endpoints; negative indices count from the end of the string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| integer ucount(list x) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns TRUE if x is non-empty | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| integer count(list x) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns the number of elements in x | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| integer geti(list x, integer n) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns the value of an integer element at position n in list x, or 0 if element n is not an integer; negative indices count from the end of the list | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| string gets(list x, integer n) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns the value of a string (or key) element at position n in list x, or "" if element n is not a string (or key); negative indices count from the end of the list | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| key getk(list x, integer n) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns the value of a key (or string) element at position n in list x, or "" if element n is not a key (or string); negative indices count from the end of the list | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| vector getv(list x, integer n) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns the value of a vector element at position n in list x, or ZERO_VECTOR if element n is not a vector; negative indices count from the end of the list | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| rotation getr(list x, integer n) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns the value of a rotation element at position n in list x, or ZERO_ROTATION if element n is not a rotation; negative indices count from the end of the list | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| float getf(list x, integer n) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns the value of a float element at position n in list x, or 0.0 if element n is not a float; negative indices count from the end of the list | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| list sublist(list b, integer x, integer y) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns a new list containing the elements of list b, from the subrange [x, y], inclusive of both endpoints | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| list alter(list haystack, list needle, integer x, integer y) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns a new list containing the elements of list haystack prior to position x, followed by the elements of list needle, and then the elements of list haystack after list y, thereby replacing the range [x, y] in list haystack (inclusive) with the contents of list needle; negative indices count from the end of list haystack | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| string getjs(string json, list subscripts) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| extracts a fragment of JSON from a larger JSON string by following the specified subscripts. Atomic strings are returned unquoted. An empty subscript list returns the entire string json, unaltered. If the subscripts do not address an extant element, JSON_INVALID is returned. JSON objects must be indexed by string and JSON arrays must be indexed by integers. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| string setjs(string json, list subscripts, string value) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns a copy of string json with an element substituted. The element to substitute must be specified by the provided subscripts. Subscripts can be used to force the creation of new elements, either by appending string subscripts (to create nested objects) or through the use of the special JSON_APPEND subscript value to add to the end of an array. Values are interpreted as JSON first, numbers second, and strings third, so "1.0" will become a number, but "[1.0]" will become an array containing a number. The special value JSON_DELETE can be used to remove an element, and the values JSON_TRUE and JSON_FALSE are used to store booleans. You should sanitize your input to prevent storing the characters [, ], {, or } in string values, as the JSON parser is incomplete and will interpret these as evidence of corruption even when other implementations accept them. Always check the return value for JSON_INVALID, as this is evidence of an unsuccessful operation and will occur even when trying to JSON_DELETE an element that does not exist--otherwise you will lose data. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| integer etype(list x, integer n) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns a numeric constant describing the type of the element at position n in list x. Possible return values are TYPE_INVALID, TYPE_INTEGER, TYPE_FLOAT, TYPE_STRING, TYPE_KEY, TYPE_VECTOR, and TYPE_ROTATION (0-6). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| jstype(string json, list subscripts) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| as getjs(), but returns the type of an element instead of its actual value. Possible return values are JSON_INVALID, JSON_OBJECT, JSON_ARRAY, JSON_NUMBER, JSON_STRING, JSON_NULL, JSON_TRUE, and JSON_FALSE (U+FDD0 through UFDD7). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| echo(string message) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| sends a string directly to the owning agent's viewer; equivalent to llOwnerSay(). Maximum limit is 1024 bytes. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| tell(key id, integer c, string message) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| sends a string to the specified object id on channel c. If id is an avatar, all attachments will receive it. If id is the root of a linkset, all links will receive it. Maximum limit for message is 256 bytes if c is negative, otherwise 1024 bytes. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| string list2js(string type, list x) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns a string that is a representation of the values in list x as encoded into the specified type (which must be one of JSON_OBJECT or JSON_ARRAY). All types other than integers and floats will be converted into quoted strings, but strings that resemble JSON (due to starting and ending with [] or {}) will be interpreted as JSON. If converting into JSON_OBJECT, the source list will be interpreted as having a stride of 2, with even-numbered elements becoming the keys of the new object, and odd-numbered elements becoming values. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| list js2list(string json) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns a list that contains every element of the original JSON object or array atomized. Nested values are left as strings. Vectors, rotations, and keys previously converted into strings by list2js() are left as strings. Objects are converted into lists with a stride of 2, where even-numbered elements are the original JSON's keys and odd-numbered elements are their corresponding values. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| string jsarray(list x) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns a JSON string containing the elements of list x. All types other than integers and floats will be converted into quoted strings, but strings that resemble JSON (due to starting and ending with [] or {}) will be interpreted as JSON. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| string jsobject(list x) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns a string that is a representation of the values in list x encoded into a JSON object. The source list will be interpreted as having a stride of 2, with even-numbered elements becoming the keys of the new object, and odd-numbered elements becoming values. For values, all types other than integers and floats will be converted into quoted strings, but strings that resemble JSON (due to starting and ending with [] or {}) will be interpreted as JSON. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| list jskeys(string json) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns a list containing only the key names of the provided JSON object. Will misbehave if fed a JSON array by accident. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| linked(integer t, integer n, string m, key id) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| sends a link_message() event to linked prim t, with the parameters n, m, and id. Be careful when using link_message() for complex applications, as it can not only run out of event queue space (~64 events can be queued before silent dropping occurs), but also trigger an immense amount of pointless LSL executions (64 messages received by 64 scripts = 4096 events) that severely impact sim performance. For a tight, script-to-script communication method, use llListen() with the UUID set, as this filtering is done outside LSL. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| list split(string haystack, string sep) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns the fragments of a string haystack split at instances of a single separator string, sep. Consecutive separators will be merged. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| list splitnulls(string haystack, string sep) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns the fragments of a string haystack split at instances of a single separator string, sep. Consecutive separators will result in empty elements. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| string concat(list x, string sep) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns a concatenated form of the elements of list x, inserting string sep between each pair of elements. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| list delrange(list b, integer x, integer y) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns a copy of a list with the subrange [x, y] removed, inclusive of both endpoints; negative indices count from the end of the list | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| delitem(list b, integer n) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns a copy of a list with the element at position n removed; negative indices count from the end of the list. This macro cannot handle list literals, so wrap them in (parens) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| list insert(list a, list b, integer n) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns a copy of list a with the contents of list b inserted before element n; to append to the end of a list, use: a + b | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| list shuffle(list x) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns the list with its elements in random order | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| string replace(string haystack, string needle, string replacement) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| returns a copy of haystack with all instances of needle replaced by replacement | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| string vec2str(vector v) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
returns a string "x y z" from a vector | string vec2str2(vector v)
| returns a string "x y z" from a vector | vector str2vec(string v)
| returns a vector | string format_percentage(float f)
| converts a float to a percentage, e.g. 0.5 to 50%, or -2.31 to -231%. Always returns an integer.
| string format_float(float f, integer places)
| truncates a float to the specified precision after the decimal point, e.g. format_float(0.010999, 3) == "0.010"; always rounds toward 0
| list list_union(list x, list y)
| returns a list containing the elements of list x, followed by any elements of list y that did not appear in list x
| list list_exclude(list x, list y)
| returns a list containing the elements of list x that did not appear in list y
| list list_intersect(list x, list y)
| returns a list containing the elements from list x that are also in list y; if x contains duplicates, these will be preserved
| list list_unique(list x)
| returns a list containing only the unique elements of list x; if x contains duplicates, these will appear only at their first position
| float sum(list x)
| returns the total sum of all numeric elements in the list
| float sum_sq(list x)
| returns the total sum of all numeric elements in the list, squaring each one first
| float mean(list x)
| returns the average of all numeric elements in the list
| float min(list x)
| returns the lowest of all numeric elements in the list
| float max(list x)
| returns the highest of all numeric elements in the list
| float median(list x)
| returns the median (middle value) of all numeric elements in the list; if the number of numeric elements is even, returns the average of those two
| float range(list x)
| returns the difference between the lowest and highest of the numeric elements in the list
| float std_dev(list x)
| calculates the average of all numeric elements in the list, then the squared differences between each numeric element and that average, then returns the square root of the average of these squared differences
| float geom_mean(list x)
| returns the product of all the numeric elements in the list, raised to the power 1/n, where n is the number of numeric elements in the list
| float countn(list x)
| returns the number of numeric elements in the list
| integer validate_key(key k)
| returns TRUE if k is a valid UUID, otherwise FALSE
| list remap(list old, list new, list input)
| iterates over input, translating its elements from the old list to the new list, assuming the elements of old and new correspond in indices; e.g. remap(["red", "green", "blue"], ["cyan", "magenta", "yellow"], ["blue", "blue", "green"]) → ["yellow", "yellow", "magenta"]
| string strleft_byte(string s, integer b)
| returns a string containing characters from the start of s, so long as they take up no more than b bytes. Fragmented characters are discarded.
| integer strlen_byte(string s)
| returns the length of the provided Unicode string in bytes rather than characters (as strlen() would)
| integer strlen_byte_inline(string s)
| returns the length of the provided Unicode string in bytes rather than characters (as strlen() would) - inline macro version of the strlen_byte() function
| string format_time(float number)
| returns "x days, hh:NN:SS" format for a number of provided seconds, leaving off days or hours for smaller values; negative values are presented wrapped in -()
| string hex(integer n)
| converts an integer to lower-case hexadecimal using as few characters as possible; no prefix or suffix is appended
| NOWHERE
| use this to represent -1 when it indicates an element is not present, e.g. strpos("x", "y") == NOWHERE
| LAST
| use this to represent -1 when it indicates the last position in a string or list, e.g. substr(s, 0, LAST) == s
| SAFE_EOF
| a string encoding of U+0004 (the ASCII EOF control code), used as an in-band record separator in some protocols, especially Refactor Robotics Aurora. Some preprocessors do not like seeing literal ASCII control codes. ARES redefines this as U+007F (ASCII DEL), which has much better support and will not cause deserialization failures if it is stored on the heap during a sim transfer.
| SOUND_DEFAULT
| a placeholder sound, meant to complement SL's TEXTURE_DEFAULT
| |
objects.lsl
The objects header specifically provides support for commonly-used prim and linkset functions.
| rotation ZR |
| A convenience macro for ZERO_ROTATION, i.e. <0, 0, 0, 0> (no rotation). |
| vector ZV |
| Shorthand for ZERO_VECTOR, i.e. <0, 0, 0> (black). |
| vector ONES |
| The vector <1, 1, 1> (white). |
| setp(integer prim, list props) |
| A convenience macro for llSetLinkPrimitiveParamsFast(). For non-linked objects, set prim to 0. |
| list getp(integer prim, list props) |
| A convenience macro for llGetLinkPrimitiveParams(). For non-linked objects, set prim to 0. |
| list geto(key object, list props) |
| A convenience macro for llGetObjectDetails(). |
| vector object_pos(key object) |
| Returns the position (in region coordinates) of the center of the root prim of the specified object. |
| integer OVER_1024 |
| A precalculated value for 1.0 / 1024.0, useful when manipulating sprite sheets. |
| integer OVER_512 |
| A precalculated value for 1.0 / 512.0, useful when manipulating sprite sheets. |
| integer OVER_256 |
| A precalculated value for 1.0 / 256.0, useful when manipulating sprite sheets. |
Other bundled headers
The ARES SDK includes a few other pieces of source code that are not considered to exclusively part of ARES. These are:
- glob.lsl — A complete implementation of the Unix glob() function used to match wildcards in text strings such as * and ?. Translated from Linux C source code; dual MIT/GPLv2 license.
- lslisp.h.lsl — Dependency for the LSLisp interpreter.
- lslisp.lsl — An interpreter for a small Lisp-like programming language, LSLisp.
- qkeys.lsl — Various implementations of UUID compression routines.
- unix2slt.lsl — Converts a Unix timestamp into the current date and time in SLT, taking Daylight Savings Time into consideration if appropriate. Written by Omei Qunhua.
- variatype.h.lsl — A text-on-prim display engine similar to XyzzyText. It supports characters of different widths, so long as their widths are a multiple of 4 px and each cell is 8 px wide. Several fonts are included. © 2023 Nanite Systems. BSD-compatible license.