LSL Wiki : LSL101Chapter3

Variables

Nothing can have value without being an object of utility.

- Karl Marxx

The "objects of utility" here are variables.

But First ...

A word about architecture. If you've messed about with computers before, you probably think that data is stored in files and databases, far away from programs. But Second Life is an object-based system. In LSL, the data is inside the script -- in variables.

"But, where does the data go when the script ends?" It never does! LSL scripts are persistent.
Some complex multi-script objects include a script whose sole purpose is to store and retrieve data for other scripts.

What Is A Variable?

A variable is a named memory slot for data (one or more values).

A script can only hold a maximum of 16 KB (kilobytes) of data. That is 16,384 bytes (an alphabetic character occupies one byte). This limit includes data that exists when you reset the script and stuff typed in and stored during its lifetime. So, it's to your advantage to use variables efficiently.

Declaring a Variable

To use a variable, you must first declare it. To do this, specify the variable's data-type and name.

// If you don't declare a value, the variable will be assigned a default value.

string name; 
// "string" is the type. "name" is the name. 
// "" is the value, because you didn't specify a value.

integer num = 1; // You can also declare a value. This is not required in LSL.

Data-types

There are lots of ways to process, display and store values. For example, you handle a monetary value and a date differently. (Try calculating a percentage of a date sometime!) So, the set of methods you need for dealing with a given value is as important a piece of information as the value itself. This "set of methods" is called the value's data-type.

Literal values like "Hello, avatar!" and 3.14159 use formatting and special symbols to show LSL their data-types
You specify the data-type of an LSL variable when you define it. Whenever LSL needs the data-type of a variable, it will "remember" your definition.

There are many data-types in the computer realm. These are the ones LSL currently uses:

Integer

An integer is a 32-bit value with a range from -2147483648 to 2147483647. Interestingly, integers can only hold whole numbers, as their name implies.

Integer math is of note, because values are truncated, NOT rounded. As such, integer math looks something like this:

// Returns "3," NOT "3.5"
integer test = 7 / 2;

Float

A float is a 32-bit floating point value. Unlike integers, floats can store decimals as well as whole numbers, at the expense of precision.

Float math is performed as anyone that lived through gradeschool may expect.

Q: If this is the case, why use integers? Shouldn't I just use floats for everything?

A: That totally depends on your coding style and the requirements for specific functions and events.

Q: What about doubles?

A: LSL doesn't have them.

Vector

A vector is a series of three floats, named X, Y, and Z (in that order).

Vector math can be very tricky. Here's a resource that might help.

You can also treat parts of a vector as if they were floats. Here's an example:

vector this = <0.0,1.0,2.0>;

this.x = 0.0; // The X component.
this.y = 1.0; // The Y component.
this.z = 2.0; // The Z component.

Rotation

A rotation is a series of four floats, this time named X, Y, Z, and S (in that order).

Rotations are defined in quaternions, which for many coders is synonymous with "pain in the ass."

For now, here's all you need to know:

- <0,0,0,1> is equal to no rotation.
- If you are uncomfortable with quaternions, try eulers.
- llGetRot and llSetRot are your friends.

Here's a good resource if you want to learn quaternions.

String

A string is a series of characters, like "The sky is blue." No frills here.

Strings can be added and subtracted from quite easily. See string.

Key

A key is a special type of string, used to store unique identifiers for the objects in Second Life. Also known as UUIDs, key variables function exactly like strings. Some functions even take strings and keys interchangably, like llStartAnimation, llLoopSound, and llSetTexture.

For all intents and purposes, keys are strings in denial.

List

A list is a series of several variables in one data type. It may include any of the above types and be as short or long as you like.

However, bear in mind that a list, as with all variables, is limited by the amount of free memory.

Lists on their own are worthy of long discussion. For now, here are the basics:

- To add to a list, simply use "+" or "+=" like so:

list this = [];

this += 1; // Adds the integer "1" to this list.
this += "2"; // Adds the string "2" to this list.

this = [1,"2","x","The sky is blue."]; // You can also define it thusly
// Each value in a list is separated by a comma

- To manipulate lists or see their contents, several functions exist. See lists.

Q: What about arrays?

A: No soup in LSL.

Q: I'm getting a syntax error. What's going on?

A: Make sure you defined your list properly and used commas between each entry.
Also note that you can only type out lists to a certain number of entries (72 or so).
While lists can store many times this number on their own, a user can manually enter only so many at a time.

For more information, see lists and appendix 2 of this guide.

Translating a value to a different data-type

Data-types matter. For example, a function needs its parameter value to have a particular data-type.

But the value that you want to send to a function may be trapped in a variable that's the wrong type. It's no good forcing it; LSL is not smart enough to realize that it needs to typecast a value before using it. It's only smart enough to tell you that the data-type is wrong.

I'm sure you're probably wondering: "But can't I make this wrong-type value digestible somehow?"

Yes, you can! To do this, typecast a value in one of two ways:

- Implicit typecasting: Stuff that is just understood by the compiler when you type it. For example, 2.0 is understood to be a float, whereas 2 is understood to be an integer. (But implicit typecasting only works with literal values, not variables.)

- Explicit Typecasting: Actually telling the program what type you want this object to be. Here's how you do it.

integer number = 1; 

// Typecasting an integer variable as a string, 
// and copying its value to a string variable
string not_a_number = (string)number; 
    
// You can also do this with literal values

// Typecasting a string as an integer, 
// and copying it to an integer variable
number = (integer)"12";            

// Typecasting a string as a vector, 
// and copying it to a vector variable
vector vect = (vector)"<1,1,1>";

Watch your variable types! Second Life can be very anal about them.

The next example uses explicit typecasting and concatenation (okay, we haven't talked about concatenation yet but it's not hard) to assemble a string parameter value "on the fly:"

default
{
    state_entry()
    {
        llWhisper (0, "Greetings, prisoner number " + (string)6 + "." );
    }
}

When compiled, the object containing this script confides:

Greetings, prisoner number 6.

Global Variables versus Local Variables

LSL has two classes of variables - local and global. Global variables are available to code throughout the entire script. Local variables, on the other hand, are available only to code inside their scope.

To show how local and global variables act, let's look at yet another script:

integer global = 1; // A global variable. This is available to the entire script

default
{
    state_entry()
    {
         integer local = 2; // A local variable.
    }
    // Our variable "local" is not available at this point.
    // Local variable access ends where the closer brace ends their scope.

    // Think you understand? Let's try again
    touch_start(integer total_number)
    {
         integer test = 3; // Watch this
         
         if(test == 3)
         {
              llOwnerSay((string)test);
         }
         // Can you still get to test here?
         // Yep!
     }
     // But not here!
}
// Our global variable is still available, even after this point!
// Naturally, you should choose your variable placement to best fit your needs.

Sometimes you will find a local variable with the same name as a global one. While this is allowed, it's considered bad coding. You and LSL may get different ideas about which of the identically-named variables the code is using.
Prefix a variable's name with its type only once, when you declare it. If you specify the type again when you set it "Just to make sure," then you're declaring it again. That means you're defining a new variable with an identical name -- sure to be a source of trouble!
Variables that are declared in function or event declarations are also local variables. E.g., In touch_start(integer total_number){}, total_number is a local variable and in myFunction(string myVariable){}, myVariable is a local variable.

Homepage | LSL101 | Tutorial | CrashCourse | Glossary